Root conventions also apply: read ../AGENTS.md; where they disagree, the closest file wins for its directory and below. If your tool cannot read it, restart it from the repository root.

Angular Conventions

Angular-specific conventions for Gravitee repositories. Global engineering, security, accessibility, TypeScript, and TDD rules still apply.

Follow the repo

• Match the repository's Node version, package manager, lockfile, Angular version, formatter, lint rules, folder structure, naming style, and test stack. Do not introduce a second convention.
• Use the repo's documented scripts for build, test, lint, and serve. Do not invent new entrypoints unless explicitly required.
• Prefer the Angular patterns already established in the repo. Use standalone components, signals, and modern control flow where the repo has adopted them.

Components, state, and RxJS

• Keep components focused. Containers orchestrate data and side effects; presentational components receive inputs and emit outputs.
• Prefer typed inputs, outputs, forms, services, and API models.
• Prefer signals or template async binding for UI state. Avoid duplicate reactive state for the same value.
• For async data, prefer rxResource or the repo's equivalent where available, because it co-locates loading/error/value. Fall back to the async pipe for template-only values, and to toSignal() when the class needs a signal.
• Reserve subscribe() for side effects such as navigation, dialogs, analytics, or toasts, using the repo's existing destroy pattern.
• Do not create nested subscriptions. Use the appropriate RxJS flattening operator instead.
• On Angular code using dependency injection, prefer the repo's established style. In modern Angular code, prefer inject() where it improves clarity.

Templates, styling, and accessibility

• Use the repo's established Angular template syntax. Prefer modern control flow (@if, @for, @switch) where the repo has adopted it.
• Avoid method calls in templates for derived state. Use computed values, signals, observables, or pipes.
• Use semantic HTML and accessible interactions before adding ARIA-only custom widgets.
• Use design-system tokens, CSS variables, and existing component APIs. Do not hard-code colours, spacing, or one-off visual patterns unless already local convention.
• Do not use ::ng-deep / :ng-deep unless there is no supported component API, token, or documented styling hook.

Forms

• Use typed reactive forms where the repo supports them.
• Validate at the boundary and surface errors with accessible, user-visible messaging.

Testing

• Use the repo's existing Angular test stack and utilities.
• Test behaviour, not implementation details. Do not assert private state, framework internals, or ng-reflect-*.
• Prefer component harnesses or stable user-facing selectors such as roles, labels, and data-testid where available.
• For HTTP and service wiring, prefer the repo's existing HTTP testing utilities rather than mocking away request/response behaviour.
• Exception to Follow the repo: for components using rxResource (or other resource-based async data), use the provider-style HTTP testing setup (provideHttpClient + provideHttpClientTesting), even where the repo's other tests use the module style. Module-style setups such as HttpClientTestingModule have hung such tests on whenStable().
• Keep async tests deterministic. Await async work explicitly; avoid sleeps, wall-clock assumptions, real network calls, and order-dependent assertions.
• For bug fixes, add or update a regression test where practical.

Shared UI and design system

• Reuse existing project utilities, design-system components, and Angular Material/Gio patterns before creating new helpers or UI components.
• Extend the design system; do not fork or duplicate it inside feature code.

Compatibility-sensitive surfaces

Treat changes to any of these as compatibility-sensitive — call them out explicitly in the PR description and final response summary:

• Public routes, navigation behaviour, guards, and permissions.
• Generated API models, DTOs, and on-wire data shapes.
• Form field names, validation behaviour, and submitted payloads.
• Design-system components, tokens, shared styles, and global theme behaviour.
• Accessibility semantics, keyboard behaviour, and focus management.
• Build configuration, environment files, package manager files, and CI configuration.

TypeScript Conventions

TypeScript-specific conventions; the general engineering rules (clean code, fail-loud boundaries) still apply.

• Match the repository's module system and tsconfig.json strictness. In an existing package, do not loosen or tighten these settings unless asked. A new package inside an existing repository follows the repository; default to ESM with strict and noUncheckedIndexedAccess only where the repository has no established setting.
• No any — use unknown and narrow with type guards.
• Type the boundaries (function signatures, exported types); let inference handle the rest.

UI Test Ids

Automated tests, including end-to-end suites in other repositories, select elements by data-testid. A changed or removed id breaks them without failing any test here. This holds whether or not a suite covers the screen today.

• Every element your change adds, or whose markup it rewrites, that reads or writes data carries a data-testid: form controls, toggles, selects, displayed application data (status, names, counts), and the buttons that create, save, delete or change state. A styling, formatting or mechanical change does not require ids on elements it does not otherwise touch.
• Keep each id on the control or value it identifies; an id on a wrapper does not count. Replacing a component that keeps the same job is not a removal: its id stays. Do not strip ids from production builds.
• Write an id as a string literal. Where it must vary per item, keep a literal prefix and vary only the suffix, taken from a stable key, not the position or display text.
• While its element stays in the product, never rename or remove an existing data-testid value, built at run time or not, even when its name is poor, its case is inconsistent, or it no longer fits its context. Cleaning up the code around it does not extend to the id.
• When you move markup into a shared component, the original screen keeps rendering its original ids. A reusable component takes the id or prefix from its caller (an input or prop) and hard-codes none; when the caller passes none, the inner control renders without one. The original caller passes the old value, new callers may use new ones.
• Remove an id only when its element leaves the product. Name each removed id, or the prefix of a removed family, with the reason, in the pull request description (the commit message when there is no pull request yet) and in your final summary, as a compatibility-sensitive change.