The token system

Every colour, space, radius, type size and control height in Nasaq is a CSS custom property named --nq-*. Components use these and nothing else, which is what lets one component library serve eleven brands, two themes, three densities and two expressions.

Where they come fromCopy Anchor Link

The source of truth is a set of DTCG JSON files in packages/tokens/src/dtcg:

Style Dictionary turns them into tokens.css (custom properties), theme.css (the Tailwind v4 @theme mapping) and a typed JavaScript module. Nothing in dist is edited by hand.

LayersCopy Anchor Link

1. Primitives (--nq-color-ink-800). Raw values. Components never use these.
2. Semantic tokens (--nq-bg, --nq-surface, --nq-fg, --nq-line, --nq-success). Defined for light and dark, selected by data-theme. This is the layer components use.
3. Brand (--nq-brand, --nq-action, --nq-on-action). Selected by data-brand. See Theming and brands.
4. Density and expression (--nq-control, --nq-row, --nq-radius-card). Selected by data-density and data-expression.
5. shadcn bridge (--background, --primary, --border). Aliases of the semantic tokens, so shadcn components and third-party code that expect those names follow the theme.

The ones you will useCopy Anchor Link

The full list, with values per theme, brand and density, is served by the MCP server (list_tokens) and by the generated tokens.css.

Using themCopy Anchor Link

In Tailwind, through the theme.css mapping:

<div className="rounded-[var(--nq-radius-card)] border border-nq-line bg-nq-surface p-4 text-nq-fg">
  <p className="text-body-sm text-muted-foreground">Uses tokens only</p>
</div>

In CSS, or in a style prop:

.panel {
  background: var(--nq-surface);
  border: 1px solid var(--nq-line);
  padding-inline: var(--nq-page-pad);
}

In JavaScript (charts, canvas, native):

import { color, space, themes } from "@fadymondy/nasaq/tokens";

RulesCopy Anchor Link

• Roles do not stand in for each other. Brand is identity, action is the one primary button, accent is the gold marker, status is the state of a thing, tags are user categories.
• No raw hex in components. The repo lint rejects it, so a theme change reaches everything.
• Every status has a label and its own icon. Colour is never the only signal.
• Contrast is tested. A unit test computes the contrast of the token pairs in every theme and brand and fails on regressions.

The reasoning, and the surface-level and card rules, are in the repo's docs/foundations/COLOR.md and LAYOUT.md.