# 0006. Design tokens are the single source of truth for visual values

- **Status:** Accepted
- **Date:** 2026-05-26
- **Deciders:** Loma Group Platform
- **Related:** [`packages/design-tokens/README.md`](../../packages/design-tokens/README.md), [`presets/themes/README.md`](../../presets/themes/README.md)

## Context

Two frontends (Angular + Next.js) consume the same brand. Theme + dark mode + future re-skinning must be a configuration change, not a rewrite.

## Decision

- All visual values (color, spacing, typography, radius, shadow, motion, z-index, breakpoint) live as **W3C Design Tokens Community Group** JSON in `packages/design-tokens/tokens/themes/<theme>/`.
- The build (`packages/design-tokens/src/build.mjs`) emits three artifacts:
  - `dist/css/<theme>.{light,dark}.css` — CSS custom properties consumed by both frontends.
  - `dist/tailwind/index.js` — Tailwind preset (so utility classes resolve to the same values).
  - `dist/ts/index.js` + `.d.ts` — typed exports for runtime use.
- **Components never hard-code colors, spacing, or typography.** ESLint + reviewers catch violations.
- **Dark mode is a token swap** (`[data-mode="dark"]`), not a component rewrite.
- **Theme presets are token overlays** under `presets/themes/<theme>/tokens/` — switching themes is a build-time selection.

## Alternatives considered

| Option                                         | Why rejected                                                                                                  |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Hard-code Tailwind config + duplicate for Next | Two configs drift; theme switch becomes a code change.                                                        |
| Style Dictionary (full)                        | Overkill for our scale; we can adopt later without changing token shape — the JSON is already DTCG-formatted. |
| Material theme system alone                    | Doesn't cover Next.js side; brand control through Material's theming is limited.                              |
| CSS-in-JS only                                 | Larger runtime + harder for designers to inspect tokens directly.                                             |

## Consequences

### Positive

- Designers and engineers share one vocabulary (the token names).
- Re-skinning (e.g. premium → fintech) is a values swap, no code changes.
- Accessibility audits target one source.

### Negative

- A small custom build script to maintain. Acceptable while we don't need Style Dictionary's full feature set.

### Neutral

- We standardized on W3C DTCG format so we keep tool optionality.

## Compliance

WCAG 2.2 AA contrast is verified per token combination. The premium-theme palette is AA-verified for light + dark.

## References

- W3C Design Tokens Community Group: https://design-tokens.github.io/community-group/format/
- Style Dictionary: https://amzn.github.io/style-dictionary/
