docs(frontend): fix documentation and Angular skill drift after the Angular 22 / TypeScript 6 upgrade by oidacra · Pull Request #37013 · dotCMS/core

oidacra · 2026-08-11T16:07:21Z

Summary

The Angular 21 to 22 / TypeScript 6 upgrade (#35930, shipped via #36838 and #36907) changed framework behavior and workspace tooling, but the frontend documentation was never updated. docs/frontend/ANGULAR_STANDARDS.md describes itself as "the single source of truth for Angular development in the dotCMS frontend", so every stale rule in it actively produced incorrect code for both developers and AI coding agents.

This updates the documentation, the Cursor and Copilot instruction files, and the Angular agent skill to match what origin/main actually is.

Closes #37009

What changed

docs/frontend/ANGULAR_STANDARDS.md — rewritten (304 to 434 lines)

OnPush is the v22 framework default. New components must not declare changeDetection. ChangeDetectionStrategy.Eager is documented as the opt-in eager mode renamed from Default, and existing Eager components stay Eager.
Resolved the inline-template self-contradiction: L33 said "prefer inline templates for small components" while L111 said "every component MUST have three separate files", and the doc's own "Required" example used an inline template. The three-file rule wins; the example was rewritten.
Teardown modernized to DestroyRef + takeUntilDestroyed(), with the legacy destroy$ pattern documented as not-to-be-mass-migrated.
Versions are now major-only with core-web/package.json named as the source of truth, which is what caused the original patch-level drift.
pnpm nx for every command; pnpm install replaces yarn install.
Documents the transitional "ignoreDeprecations": "6.0" TypeScript 6 flag.

Sibling docs — @ngneat/spectator renamed to @openng/spectator, explicit OnPush removed from examples, *ngFor replaced with @for. COMPONENT_ARCHITECTURE.md's "OnPush Change Detection" section taught the pre-v22 opt-in as if still required and was reworked.

Commands and package manager — yarn nx and bare nx replaced with pnpm nx across CLAUDE.md, .cursor/rules/, .cursor/agents/, .github/instructions/, docs/core/, docs/claude/ and docs/infrastructure/.

.claude/skills/dot-ui-angular-standards/ (new) — a governed first-party overlay skill carrying the dotCMS rules, declaring precedence over the vendored angular-developer skill.

.agents/skills/angular-developer/ — re-synced to upstream angular/angular@840f071 and given a PROVENANCE.md.

Decisions taken

The issue deliberately left several choices open.

Decision	Choice
Vendored skill handling	Re-sync from upstream and add a governed overlay
Inline templates vs three files	Three separate files, always
`destroy$` vs `takeUntilDestroyed()`	`takeUntilDestroyed()` for new code
Drift beyond the enumerated files	Fixed, limited to the same drift classes

On the vendored skill. The issue asked for a deliberate decision instead of a silent fork. The vendored copy had no upstream URL, no version marker and no sync mechanism, so drift was undetectable. Upstream has since removed the standalone: true and explicit changeDetection lines from its signal-forms example, which fixes the two contradictions the issue cites at their source, and adds four new references (http-client, pipes, migrations, environment-configuration). Upstream remains Angular-CLI-first by design — it still mandates ng build and ng new and documents angular.json and Karma — so the overlay is still required for the Nx- and dotCMS-specific rules. PROVENANCE.md records the source, the synced commit and the re-sync procedure so this cannot silently rot again.

Standards added beyond the issue

Requested during review and applied to both the standards doc and the overlay skill:

Reuse before creating — check dotCMS's own components (libs/ui / @dotcms/ui) first, then PrimeNG; a new component is the last resort.
Component state handling — loading, empty, error and loaded must all be handled explicitly.
Error handling — no silent failures, no unguarded .subscribe(), errors surfaced to the user.
Material Symbols for icons — <span class="material-symbols-outlined">name</span>, the name in text content. Existing PrimeIcons stay; PrimeNG's internal icons are a theming concern; the deprecated dot-icon component is not recommended.
Signal Forms first — new forms use @angular/forms/signals. Existing Reactive Forms are not mass-migrated.

Each follows the same shape as the change-detection rule: forward-looking for new code, explicitly no mass migration of what exists.

Verification

Check	Result
`@ngneat` in docs, CLAUDE.md, Cursor rules	none
`yarn` as package manager (case-insensitive)	none
Bare `nx` commands	none
`changeDetection: ChangeDetectionStrategy.OnPush` mandates	none
Stale "Angular 20/21" claims	none, apart from a past-tense incident record
Patch versions in `docs/frontend/`	none
PrimeIcons test assertions	none
`just skills-lint`	passes, 20 first-party skills, 0 warnings
`CATALOG.md` freshness	regenerated, not hand-edited
Relative links in touched files	all resolve
`core-web/**` source	unchanged

Ground truth confirmed against the workspace: pnpm@10.17.1, @angular/core 22.1.0, primeng 21.1.3, @ngrx/signals 21.1.1, tailwindcss 4.1.17, nx 23.1.1, typescript 6.0.3, jest 30.2.0, @openng/spectator 1.0.1, Node >=v22.22.3. Also verified: 219 ChangeDetectionStrategy.Eager call sites, 528 files importing @openng/spectator and zero importing @ngneat, and that the Material Symbols @font-face is self-hosted in libs/dotcms-scss/shared/ and loaded through libs/dotcms-scss/angular/styles.scss.

The issue's own analysis was accurate on every cited line number, with two exceptions found while verifying: TESTING_FRONTEND.md had 8 @ngneat references rather than the 6 listed, and the CICD_PIPELINE.md snippet is illustrative prose rather than a copy of live CI, confirmed by grepping .github/workflows/*.yml.

Out of scope

Unchanged, as the issue specifies: the 219 ChangeDetectionStrategy.Eager call sites, nx.json's @nx/angular:component generator default, and removal of the ignoreDeprecations flag. core-web/CLAUDE.md was verified clean.

Two follow-ups worth filing separately:

Justfile:116 still uses yarn nx serve dotcms-ui — same drift class, but build tooling rather than documentation.
docs/frontend/TESTING_REVIEW_RULES.md is not linked from anywhere in the repo, including the docs/frontend/README.md index.

…pt 6 The Angular 21 to 22 / TypeScript 6 upgrade changed framework behavior and workspace tooling, but this doc was never updated. It calls itself the single source of truth, so every stale rule actively produced incorrect code. - OnPush is the v22 framework default: new components must NOT declare changeDetection. Document ChangeDetectionStrategy.Eager as the opt-in eager mode renamed from Default, and that existing Eager components stay Eager. - Resolve the inline-template self-contradiction in favour of the three-file rule, and rewrite the Standalone Component example that violated it. - Modernize teardown to DestroyRef + takeUntilDestroyed(), noting the legacy destroy$ pattern is not to be mass-migrated. - Express versions as major-only with core-web/package.json as source of truth. - pnpm nx for all commands; pnpm install replaces yarn install. - Document the transitional "ignoreDeprecations": "6.0" TypeScript 6 flag. Adds newly required standards: reuse-before-creating, mandatory loading/empty/error/loaded state handling, mandatory error handling, Material Symbols icons, and Signal Forms first for new forms.

@OpenNg

- Rename @ngneat/spectator to @openng/spectator (the workspace migrated; 528 files import @OpenNg, zero import @ngneat). TESTING_FRONTEND.md had 8 references, not the 6 originally counted. - Correct the runner claims: core-web runs Jest 30 only, not "Jest or Vitest". @openng/spectator does export a /vitest entry, so the old hedge would have encouraged the wrong import. - Drop explicit OnPush from examples and rework the OnPush Change Detection section, which taught the pre-v22 opt-in as if still required. - STATE_MANAGEMENT: the three-file rule is unconditional, not "when not trivial". - STYLING_STANDARDS: replace *ngFor with @for. - Update icon assertions to Material Symbols.

core-web is pinned to pnpm@10.17.1 and pnpm-lock.yaml is the only lockfile — there is no yarn.lock anywhere in the repo. Nx is not installed globally, so every nx invocation must go through the package manager. - Replace yarn nx / bare nx with pnpm nx across docs, Cursor rules and the Copilot frontend instructions. - DOCKER_BUILD_PROCESS: npm install and bare nx build were both wrong. - CICD_PIPELINE: the illustrative workflow snippet referenced yarn.lock and cache: yarn. Verified against .github/workflows/*.yml that no real workflow uses these commands, so this is prose, not a mirror of live CI. - Angular 21+ becomes 22+; drop the "use yarn nx, not nx" parenthetical. - Carry the OnPush-is-default rule and Signal-Forms-first rule into the agent instruction files, and remove the "prefer inline templates" line that contradicted the three-file rule.

The vendored angular-developer skill is generic upstream Angular guidance: it mandates ng build and ng new, documents angular.json and Karma, and assumes a greenfield CLI app. None of that applies to core-web, which is an Nx monorepo running Jest 30 with no angular.json. Rather than hand-editing the vendored skill into an undocumented fork, this adds a governed first-party overlay that declares precedence over it and states the dotCMS rules: no standalone: true, no changeDetection on new components, pnpm nx instead of ng, Jest + @openng/spectator, three files per component, DestroyRef teardown, reuse-before-creating, mandatory state and error handling, Material Symbols icons, and Signal Forms first. It defers to docs/frontend/ANGULAR_STANDARDS.md as the canonical long-form source rather than duplicating it. CATALOG.md is regenerated, not hand-edited.

The vendored copy had no recorded upstream source, no version marker and no sync mechanism, so drift from upstream was undetectable. Syncs it to angular/angular@840f071 and adds PROVENANCE.md documenting the source URL, the synced commit, the re-sync procedure and a sync history. This fixes at the source the two contradictions flagged in the issue: upstream has since removed the standalone: true and explicit changeDetection lines from the signal-forms example that violated our own standards. Also brings in four new references: http-client, pipes, migrations and environment-configuration. Upstream remains Angular-CLI-first by design, so the dot-ui-angular-standards overlay is still required for the Nx- and dotCMS-specific rules.

claude · 2026-08-11T16:08:22Z

Claude finished @oidacra's task in 2m 53s —— View job

PR Review — Frontend docs & Angular skill drift fix

Reviewed the committed PR diff against origin/main. This is a documentation/skill PR (no core-web/** source touched), so I checked factual accuracy against the workspace, internal contradictions, and link integrity.

Read the diff vs origin/main
Check the ANGULAR_STANDARDS.md rewrite for accuracy & contradictions
Verify claims against workspace ground truth
Check relative/anchor links resolve
Verify pnpm nx command consistency
Post review

Verified against workspace ground truth (all correct)

Versions match core-web/package.json: @angular/core 22.1.0, primeng 21.1.3, @ngrx/signals 21.1.1, tailwindcss 4.1.17, nx 23.1.1, typescript 6.0.3, jest 30.2.0, @openng/spectator 1.0.1, packageManager: pnpm@10.17.1, node >=v22.22.3. Major-only + "read package.json" framing is the right call.
ChangeDetectionStrategy.Eager is real in the tree (confirmed imported from @angular/core and used as changeDetection: ChangeDetectionStrategy.Eager, ~207 call sites) — corroborates the "OnPush is the v22 default, Eager is the renamed opt-in" claim.
Material Symbols SCSS is self-hosted: libs/dotcms-scss/shared/_material-symbols-outlined.scss, _material-symbols-rounded.scss, loaded via libs/dotcms-scss/angular/styles.scss — all present.
"ignoreDeprecations": "6.0" present in core-web/tsconfig.base.json; @angular/forms/signals is in use in the tree.
No @ngneat and no yarn package-manager references remain in the PR diff hunks.
All docs/frontend/README.md targets exist; ANGULAR_STANDARDS.md anchors (#icons-material-symbols, #file-structure-requirements-critical, #forms-signal-forms-first) and ../core/PROGRESSIVE_ENHANCEMENT.md / TYPESCRIPT_STANDARDS.md resolve; overlay skill ../../../docs/frontend/* and ../../../.agents/skills/angular-developer/PROVENANCE.md links resolve.
CATALOG.md count is internally consistent (19 → 20 first-party, new dot-ui-angular-standards row).
The L33/L111 inline-template self-contradiction called out in the description is genuinely resolved — the "Required" example now uses templateUrl/styleUrls and the three-file rule is stated once.

New Issues

🟡 Medium: ONBOARDING.md:74,75,85,178 — This file is edited by the PR (index/"start here" section) and the PR's thesis + verification table claim "yarn as package manager: none," yet these untouched lines still teach yarn nx serve dotcms-ui, yarn nx test, and a nx: command not found → Use yarn nx troubleshooting row. Since the file was already opened, converting these to pnpm nx in the same pass would keep it self-consistent. Pre-existing content, non-blocking. Fix this →

Notes (non-blocking)

The two follow-ups you flagged (justfile:116 yarn nx serve, and docs/frontend/TESTING_REVIEW_RULES.md now being linked from the README index) are the right scoping calls — justfile:116 still carries yarn nx and is correctly deferred.
The component examples log failures with console.error(...) alongside surfacing to an $error signal. That's standard Angular practice and consistent with the doc's "no silent failures" rule, so no change needed — just noting the doc doesn't prescribe a frontend logging abstraction (none is mandated in the repo).

Overall: accurate, internally consistent, and links resolve. No blocking issues — the single Medium is a same-file consistency cleanup you can fold in or defer with the other yarn follow-ups.

dot-ui-vtl-migration covers VTL custom field templates and the Dojo/Dijit to DotCustomFieldApi migration — unrelated to Angular standards in the core-web Nx workspace. It was linked only because it was the other dot-ui- skill, which is prefix adjacency rather than the complementarity 'related' is meant to express. The genuinely adjacent skill is the vendored angular-developer, but that relationship is directional (this one overrides it) and 'related' is explicitly non-directional, so it is stated in the body instead.

…rlay skill The overlay skill restated rules that docs/frontend/ANGULAR_STANDARDS.md already owned, which is the same two-sources-of-truth problem this PR set out to fix. Makes the split explicit: the doc is the single source of truth and the skill carries only the trigger, the precedence declaration over the vendored angular-developer skill, and the rules where upstream actively says the wrong thing here — so the correction is present at the moment an agent would otherwise follow upstream. Adds an explicit read-the-doc-first instruction and states that if the two disagree, the doc wins and the skill is the bug. Drops the restated teardown, Signal Forms and TypeScript 6 rules plus the generic Angular API table, since upstream already agrees on those; they are now a pointer. Keeps the dotCMS-only naming rules that upstream cannot know about. Also states the dot- selector prefix rule in the doc, which every example relied on but no rule declared — it existed only in core-web/CLAUDE.md.

…DARDS frontend.instructions.md is a third statement of the Angular rules, alongside docs/frontend/ANGULAR_STANDARDS.md and the dot-ui-angular-standards skill, and it had already drifted: it carried no Material Symbols icon rule, no DestroyRef teardown rule, no reuse-before-creating rule, no state/error handling rules and no TypeScript 6 note. A Copilot user in core-web/ therefore got a strictly weaker ruleset than a human or Claude reading the doc. Adds the five missing standards. The file stays self-contained by design — Copilot injects instruction files verbatim and does not follow references — so this is a copy, and the duplication is a known drift risk tracked separately.

…nsumers The index listed 7 of 8 docs. TESTING_REVIEW_RULES.md was absent from it and referenced by nothing anywhere in the repo — a doc nobody could find. Three docs (ANGULAR_STANDARDS, BREADCRUMBS, TESTING_REVIEW_RULES) had no link back to the index, so navigation only worked in one direction. - Rewrite the index: all 8 docs, what each is for, when to load it, and the cross-cutting conventions that hold across all of them. Names ANGULAR_STANDARDS.md as the single source of truth and states that a disagreeing sibling is the one that is wrong. - Add an index backlink to every doc, so navigation works from anywhere. - Disambiguate the two testing docs: TESTING_FRONTEND for writing tests, TESTING_REVIEW_RULES for reviewing them. Consumers follow a hybrid rule rather than blanket redirection: files that enumerate several docs (CLAUDE.md, ONBOARDING.md, dotFrontendOnboarding.md, WORKFLOW_PATTERNS.md, frontend-context.mdc) now lead with the index, while single-doc consumers (test-context.mdc, typescript-unit-testing.md, doc-updates.mdc) keep their direct link — routing those through the index would mean loading two files to get one. Also fixes a pre-existing broken link: docs/core/SECURITY_PRINCIPLES.md pointed at docs/frontend/SECURITY_FRONTEND.md, which has never existed.

docs/README.md listed only 2 of the 8 docs in docs/frontend/, and listed them as plain bold text rather than links, so the top-level index could neither reach most frontend docs nor navigate to the ones it named. Lists all 8 as working links and points at docs/frontend/README.md as the entry point, matching how the other multi-doc consumers now reference the folder.

…iblings The skill named docs/frontend/ANGULAR_STANDARDS.md three times but only as inline code, never as a link, and mentioned none of its seven sibling docs or the index. An agent following it was told to read the source of truth but had no way to discover TESTING_FRONTEND.md, STATE_MANAGEMENT.md or STYLING_STANDARDS.md — even though the skill states testing and styling rules that those docs cover in depth. Makes the source-of-truth reference a working relative link and adds a task -> doc table for the siblings, pointing at docs/frontend/README.md when unsure. Keeps the direct link to ANGULAR_STANDARDS.md as the primary reference rather than routing through the index.

claude · 2026-08-11T17:19:01Z

(stray test comment removed by automation — disregard)

…ar-skill-dri

Copilot

Pull request overview

This PR updates dotCMS frontend documentation and AI instruction/skill content to reflect the post–Angular 22 / TypeScript 6 reality of the core-web Nx workspace (pnpm + pnpm nx, Angular v22 OnPush default, @openng/spectator, modern teardown patterns, etc.), and introduces a governed overlay skill to prevent future drift from the vendored upstream Angular skill.

Changes:

Rewrites/aligns docs/frontend/* to current Angular 22 defaults (change detection, template control flow, teardown, testing stack, icons, commands).
Replaces legacy tooling guidance across docs/instructions (Yarn/bare Nx → pnpm nx; removes patch-version pinning in docs).
Re-syncs the vendored angular-developer skill from upstream and adds a dotCMS-owned overlay skill (dot-ui-angular-standards) + provenance tracking.

Reviewed changes

Copilot reviewed 51 out of 51 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
ONBOARDING.md	Points onboarding readers to the frontend docs index + Angular standards.
dotFrontendOnboarding.md	Updates onboarding link targets to the frontend docs index and clarifies source of truth.
docs/README.md	Expands `/docs/frontend` section and directs readers to the frontend index.
docs/infrastructure/DOCKER_BUILD_PROCESS.md	Updates frontend-only build instructions to pnpm + `pnpm nx`.
docs/frontend/TESTING_REVIEW_RULES.md	Updates Spectator package to `@openng`, removes Vitest mention, adds “See also” links.
docs/frontend/TESTING_FRONTEND.md	Aligns test stack and examples to Jest + `@openng/spectator`, Material Symbols, and Angular 22 defaults.
docs/frontend/STYLING_STANDARDS.md	Updates template example to modern `@for` control flow.
docs/frontend/STATE_MANAGEMENT.md	Removes redundant `changeDetection` from examples; updates Spectator import; clarifies Angular 22 defaults.
docs/frontend/README.md	Adds a clearer frontend docs entry point, cross-cutting conventions, and doc selection guidance.
docs/frontend/COMPONENT_ARCHITECTURE.md	Removes explicit `OnPush` from examples; updates change detection guidance for Angular 22.
docs/frontend/ANGULAR_STANDARDS.md	Major rewrite: Angular 22 defaults, pnpm/Nx commands, teardown, Signal Forms guidance, icons, error/state handling rules.
docs/core/SECURITY_PRINCIPLES.md	Updates frontend security doc link to frontend docs index + Angular standards.
docs/core/GIT_WORKFLOWS.md	Updates frontend workflow commands to `pnpm nx`.
docs/core/CICD_PIPELINE.md	Updates illustrative CI snippets and caching notes from Yarn to pnpm.
docs/claude/WORKFLOW_PATTERNS.md	Updates frontend command indicators and doc reading priority to include the frontend index + pnpm Nx.
docs/claude/DOCUMENTATION_MAINTENANCE.md	Updates example “run tests” command to `pnpm nx`.
CLAUDE.md	Updates frontend commands and version guidance; adds frontend docs index and expands frontend doc links.
.github/instructions/frontend.instructions.md	Aligns embedded frontend instructions with Angular 22 defaults, pnpm Nx, TypeScript 6 transitional flag, and `@openng/spectator`.
.cursor/rules/test-context.mdc	Updates test guidance for Material Symbols assertions and pnpm Nx commands.
.cursor/rules/frontend-context.mdc	Updates Angular version note, pnpm Nx commands, and adds links for testing review + breadcrumbs docs.
.cursor/agents/typescript-unit-testing.md	Updates Spectator package and pnpm Nx test runner commands.
.claude/skills/dot-ui-angular-standards/SKILL.md	New governed overlay skill documenting dotCMS-specific Angular rules + precedence over vendored skill.
.claude/skills/CATALOG.md	Updates skill catalog counts and adds the new overlay skill entry.
.agents/skills/angular-developer/SKILL.md	Updates upstream skill description and reference list (adds HTTP/pipes/migrations/env config references).
.agents/skills/angular-developer/references/testing-fundamentals.md	Upstream reference update for zoneless async-first testing fundamentals.
.agents/skills/angular-developer/references/signal-forms.md	Updates signal forms guidance and examples; refines pitfalls table.
.agents/skills/angular-developer/references/router-testing.md	Updates router testing example to newer setup style.
.agents/skills/angular-developer/references/resource.md	Updates `resource` guidance and examples; removes “experimental” warning.
.agents/skills/angular-developer/references/reactive-forms.md	Updates reactive forms guidance (NonNullableFormBuilder, modern template syntax).
.agents/skills/angular-developer/references/pipes.md	New upstream reference for pipe usage patterns and non-template reuse guidance.
.agents/skills/angular-developer/references/outputs.md	Updates output examples to use `readonly` fields.
.agents/skills/angular-developer/references/migrations.md	New upstream reference for modernization/migration schematics.
.agents/skills/angular-developer/references/mcp.md	Updates Angular CLI MCP server reference content.
.agents/skills/angular-developer/references/linked-signal.md	Updates examples to prefer `protected readonly` fields.
.agents/skills/angular-developer/references/inputs.md	Updates input examples to prefer `readonly` fields and refines template snippet.
.agents/skills/angular-developer/references/injection-context.md	Updates injection-context reference and examples.
.agents/skills/angular-developer/references/http-client.md	New upstream reference covering `HttpClient` and `httpResource`.
.agents/skills/angular-developer/references/host-elements.md	Updates host bindings examples to prefer `protected readonly` fields.
.agents/skills/angular-developer/references/hierarchical-injectors.md	Updates DI hierarchy notes and examples.
.agents/skills/angular-developer/references/environment-configuration.md	New upstream reference for build-time vs runtime configuration patterns.
.agents/skills/angular-developer/references/effects.md	Updates effect examples to prefer `protected readonly` fields.
.agents/skills/angular-developer/references/e2e-testing.md	Updates E2E reference to be framework-selection guidance rather than Cypress-specific.
.agents/skills/angular-developer/references/di-fundamentals.md	Updates DI fundamentals reference and examples.
.agents/skills/angular-developer/references/data-resolvers.md	Updates resolver examples to prefer `readonly` fields.
.agents/skills/angular-developer/references/creating-services.md	Updates service-creation guidance and examples.
.agents/skills/angular-developer/references/component-harnesses.md	Updates component harnesses reference example.
.agents/skills/angular-developer/references/cli.md	Updates CLI reference table wording.
.agents/skills/angular-developer/references/angular-aria.md	Updates Angular Aria reference examples and expands coverage.
.agents/skills/angular-developer/references/angular-animations.md	Updates animation example fields to `protected readonly`.
.agents/skills/angular-developer/PROVENANCE.md	New provenance file documenting upstream source, synced commit, and re-sync procedure.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

oidacra added 5 commits August 11, 2026 11:59

github-project-automation Bot added this to dotCMS - Product Planning Aug 11, 2026

github-actions Bot mentioned this pull request Aug 11, 2026

Fix frontend documentation and Angular skill drift after the Angular 22 / TypeScript 6 upgrade #37009

Open

29 tasks

github-actions Bot added the Area : Documentation PR changes documentation files label Aug 11, 2026