ADR-012-a — Custom Component Naming Convention

Status

Accepted

Context

The project builds custom presentational components on top of PrimeNG primitives (for example, a transition timeline on p-timeline, reusable stat cards, etc.). Angular proposes app-* as the default prefix for all components generated with its CLI, and PrimeNG reserves p-* for its own elements. Without an explicit convention, a developer reading a template cannot distinguish at first glance whether a selector corresponds to a project component, a PrimeNG component, or a third-party component — which increases navigation time and the risk of name collisions.

Keeping app-* for all project components was considered, but that eliminates the distinction between a page/feature (a route AppComponent) and a reusable presentational piece, which have very different lifecycles, dependencies, and responsibilities.

Decision

kdx-* for presentational components. All custom presentational components use the selector prefix kdx- (for example, kdx-transition-timeline, kdx-stat-card, kdx-audit-log-timeline). The prefix explicitly signals “presentational primitive built by the project, reusable across features”.

app-* for pages and routing. Reserved for page-level, feature, layout, and routing components — shells, pages, containers, guards. These are components instantiated by the router or by other feature components, not by the design system.

p-* is PrimeNG only. A custom component with the p- prefix is never created.

Location: kdx-* components live in frontend/src/app/shared/components/ and are showcased at the /showcase/custom route before being consumed in features.

Showcase-before-use: Every new kdx-* component must appear in the showcase (/showcase/custom) as a prerequisite to its use in any feature or page.

Consequences

Developers can instantly identify the origin of any component in a template: kdx-* is from the project (reusable presentational), p-* is PrimeNG, app-* is a page or router feature.
The /custom-components route acts as living documentation of the design system: it lists all available kdx-* components, preventing duplication and reinvention.
The showcasing-before-use requirement creates a deliberate design cycle: components are generalized before being specialized, which reduces the technical debt of ad-hoc components.
The kdx- prefix could cause a collision if a third-party library adopts the same prefix in the future; in that case a new prefix would need to be evaluated through an ADR that supersedes this one.
Existing components prior to this decision that use app-* while being presentational must be migrated to kdx-* incrementally as they are modified.