ADR-012-c — Theming and Token Conventions

Status

Accepted

Context

The project uses PrimeNG with the Lara preset and Tailwind CSS v4. Both systems expose design tokens (CSS custom properties), but they serve different purposes and can conflict if used without clear rules. Without conventions, developers mix raw Tailwind colors (bg-zinc-800) with PrimeNG surface tokens (bg-surface-0), creating inconsistency and making theme changes fragile.

Decision

Noir/Zinc is the project’s color identity. The KdxPreset configures PrimeNG’s Noir color family with Zinc as the surface palette. All color decisions flow from this choice.

PrimeNG semantic tokens for all color usage. Use primary, surface, text-color, text-muted-color, and PrimeNG severity tokens (success, warn, danger, info). Never use raw Tailwind color utilities (text-zinc-500, bg-blue-600) in components or pages.

@theme tokens for Tailwind extensions. When Tailwind needs a color not covered by PrimeNG (for example, a custom accent for a specific visualization), define it in @theme inside tailwind.css with a semantic name. Never hardcode hex values in templates.

Surface hierarchy follows PrimeNG convention. surface-0 (lightest) through surface-ground (page background). Use these for layering cards, dialogs, and panels — not arbitrary zinc shades.

KdxPreset is the single override point. All PrimeNG token overrides live in theme.config.ts inside the preset. Component-level ::ng-deep or inline style overrides of PrimeNG tokens are forbidden.

Dark mode is not in scope for MVP ([[adr-013-accessibility|ADR-013]]). The system is designed for light mode only. Token names are semantic (surface, primary) to enable dark mode later without renaming.

Consequences

Theme changes propagate globally by modifying KdxPreset — no component-level hunting for hardcoded colors.
Templates are readable: bg-primary and text-surface-500 convey intent; bg-zinc-800 does not.
The Noir/Zinc identity is consistent across PrimeNG components and custom layouts.
Dark mode can be added later by providing an alternate token set in KdxPreset without touching templates.
Developers must learn PrimeNG’s token vocabulary, which has a learning curve but pays off in consistency.