ADR-012 — Design System

ADR-012 — Design System

Status

Accepted

Context

The frontend needs a unified design system that prevents ad-hoc UI decisions and ensures visual consistency across all pages and components. The project uses PrimeNG as its component library and Tailwind CSS v4 as a utility layer. Without explicit rules, developers make inconsistent choices: raw Tailwind colors instead of design tokens, custom CSS where a PrimeNG component exists, or components built in isolation without validation.

Decision

PrimeNG is the component SSOT. Lara preset with Noir/Zinc theme. Every UI need is first mapped to an existing PrimeNG component before considering custom work.

Component precedence: PrimeNG primitive > kdx-* custom > raw HTML + Tailwind. Always exhaust the higher tier before dropping to a lower one — a p-button is always preferred over a styled <button>.

Vanilla PrimeNG first. When a PrimeNG component already looks correct with the Noir/Zinc theme, use it as-is. Do not wrap it in Tailwind utilities for margin, padding, or color that the component already handles. <p-tag severity="success"> is correct; <p-tag severity="success" class="px-3 py-1 rounded-full"> fights the component’s own styling.

Tailwind v4 is the utility layer. Used for layout, spacing, responsive breakpoints, and typography utilities. Never for color — always reference PrimeNG design tokens or @theme tokens.

Custom CSS must be justified. Writing raw CSS (.scss, styles, ::ng-deep) instead of Tailwind v4 utilities requires an explicit reason — typically a PrimeNG override that Tailwind cannot express, or an animation that has no utility equivalent. If Tailwind can do it, CSS is not allowed.

KdxPreset in theme.config.ts is the single theming entry point. All PrimeNG customization flows through this preset. PrimeNG internals are never patched directly.

Showcase-first development. All reusable kdx-* components are validated in the /showcase route before consumption in features. The showcase is the living documentation of the design system.

OnPush + standalone. All components use ChangeDetectionStrategy.OnPush and are standalone. No NgModule.

Sub-decisions

• [[adr-012-a-custom-component-naming|ADR-012-a]] — Custom component naming convention (kdx-* prefix, app-* for pages, p-* reserved for PrimeNG).
• [[adr-012-b-typography|ADR-012-b]] — Typography (3-tier font system: Brand/Title/UI, Inter as base, Outfit for brand).
• [[adr-012-c-theming-tokens|ADR-012-c]] — Theming and token conventions (Noir/Zinc palette, token usage rules, surface semantics).

Consequences

• Developers have a deterministic decision path for any UI task: check PrimeNG first, then kdx-*, then raw HTML.
• Visual consistency is enforced by the token system rather than by manual review.
• The showcase route provides a single source of truth for available components, reducing duplication.
• New developers can build pages by composing existing primitives without learning the full design system internals.
• Theming changes propagate globally through KdxPreset without touching individual components.