Token Model

How design.tokens.json becomes shared semantic CSS.

The source of truth is root design.tokens.json. Colors are structured OKLCH token values, and semantic light/dark groups reference primitive leaves. CSS strings are generated output only.

packages/tokens distributes the canonical CSS through @mun.digital/tokens/css and generated static metadata through @mun.digital/tokens/metadata. Apps should import package entries instead of copying generated values.

Authoring Model

Primitive color tokens describe raw OKLCH values.
Semantic color tokens describe product intent: background, foreground, primary, border, and related surface roles.
Layout tokens describe shared structure such as the portfolio rail width and gap.
App component authors use semantic Tailwind utilities backed by generated variables, not raw color literals.

Generated Outputs

Export	File	Purpose
`@mun.digital/tokens/css`	`packages/tokens/css/tokens.generated.css`	Runtime CSS variables for web, docs, and Storybook styles.
`@mun.digital/tokens/metadata`	`packages/tokens/metadata/tokens.generated.mjs`	Static metadata for docs and Storybook references.

The CSS includes storybook-design-token comment annotations so token categories remain compatible with Storybook token browsing. The docs token reference below is rendered from metadata, so reference content does not depend on Storybook addon compatibility.

Semantic Usage

Use semantic tokens for component intent:

<h2 className="text-foreground">Experience</h2>
<span className="text-primary">[02]</span>
<div className="border-border bg-card" />

Avoid raw color values when a semantic token exists. Add new tokens in design.tokens.json, then regenerate outputs.

Verification:

Run pnpm design:build after editing design.tokens.json.
Run pnpm design:check before committing.
Run pnpm tokens:smoke when a consumer changes.
Run pnpm pack:smoke when package exports change.

Generated Token Reference

This reference is rendered from @mun.digital/tokens/metadata, the generated metadata companion to the canonical CSS export.

Semantic color tokens
Token	Mode	Value	Source
`--background`	light	`oklch(0.985 0.004 80)`	`color.semantic.light.background`
`--card`	light	`oklch(0.97 0.004 80)`	`color.semantic.light.card`
`--foreground`	light	`oklch(0.18 0.01 240)`	`color.semantic.light.foreground`
`--muted-foreground`	light	`oklch(0.42 0.01 240)`	`color.semantic.light.muted-foreground`
`--subtle-foreground`	light	`oklch(0.54 0.008 240)`	`color.semantic.light.subtle-foreground`
`--border`	light	`oklch(0.85 0.008 240)`	`color.semantic.light.border`
`--border-strong`	light	`oklch(0.3 0.01 240)`	`color.semantic.light.border-strong`
`--primary`	light	`oklch(0.5 0.15 220)`	`color.semantic.light.primary`
`--primary-soft`	light	`oklch(0.55 0.15 220 / 0.12)`	`color.semantic.light.primary-soft`
`--grid`	light	`oklch(0.94 0.004 240)`	`color.semantic.light.grid`
`--background`	dark	`oklch(0.14 0.01 240)`	`color.semantic.dark.background`
`--card`	dark	`oklch(0.17 0.012 240)`	`color.semantic.dark.card`
`--foreground`	dark	`oklch(0.95 0.005 240)`	`color.semantic.dark.foreground`
`--muted-foreground`	dark	`oklch(0.72 0.01 240)`	`color.semantic.dark.muted-foreground`
`--subtle-foreground`	dark	`oklch(0.62 0.01 240)`	`color.semantic.dark.subtle-foreground`
`--border`	dark	`oklch(0.28 0.015 240)`	`color.semantic.dark.border`
`--border-strong`	dark	`oklch(0.85 0.01 240)`	`color.semantic.dark.border-strong`
`--primary`	dark	`oklch(0.83 0.15 220)`	`color.semantic.dark.primary`
`--primary-soft`	dark	`oklch(0.78 0.15 220 / 0.14)`	`color.semantic.dark.primary-soft`
`--grid`	dark	`oklch(0.3 0.018 240)`	`color.semantic.dark.grid`

Layout tokens
Token	Mode	Value	Source
`--rail-width`	base	`120px`	`dimension.layout.rail.width`
`--rail-gap`	base	`28px`	`dimension.layout.rail.gap`
`--rail-offset`	base	`calc(var(--rail-width) + var(--rail-gap))`	`dimension.layout.rail`