name: design-tokens
description: The design-token strategy for this repo. Use whenever adding, naming, overriding, reading, or theming design tokens or CSS variables: role tokens, variant-state color tokens, brand themes, the cssVars in registry manifests (the single source the Storybook preview derives from), or any --lifi-* variable. Defines the naming convention, the shadcn base plus --lifi-* layer, how utilities are generated, and where values live. Always apply when touching tokens or theme values.
user-invocable: false
Design tokens
Tokens are the color, font, and radius values of the system, written as CSS variables and consumed through Tailwind utilities. They are the shadcn base (role tokens) plus a small --lifi-* layer for interactive colors the base does not cover. Structure (padding, radius step, sizing) is not a token: it lives in a component's style. Reference: Linear EMB-401.
Principles
- Reach for a role token first. Add a
--lifi-* token only for an interactive color no role token covers that a brand must set on its own.
- Register every utility in
@theme. Tailwind generates a utility only for a variable in a @theme namespace.
- Put values where they belong.
@core/tokens holds the base; a theme defines only its overrides.
- Tokenize color, font, and the
--radius value, nothing else. How much radius, padding, and size a component takes is its style, written with the Tailwind scale.
- Never hard-code a value, and never couple unrelated roles. An input background is not a card.
Critical rules
These are always enforced. Each links to a file with Incorrect/Correct pairs.
- Role tokens are unprefixed (the shadcn base, plus
--success, --warning, --info).
- Variant-state color tokens are
--lifi-<component>-<variant>-<state>, for example --lifi-button-primary-hover. Each derives from a role token by default; a brand overrides it.
- Mint a token only for an interactive color a brand must set itself; read role utilities directly otherwise.
- A new color or radius needs a
@theme mapping in @core/tokens, or no utility is generated.
- The registry manifests are the single source of token values; a theme's
cssVars carries overrides only, and the Storybook preview derives its themes from them.
- A value that differs by mode must appear in both the
light and dark blocks.
- Mode (light or dark) is the
.dark class; theme (which token set) is data-theme. They are independent.
- Style with token utilities (
bg-card, border-input, rounded-lg), never raw values.
- Pair a surface with its foreground (
bg-primary with text-primary-foreground).
- Size and space with the Tailwind scale (
h-11.5, px-3.5), not tokens or arbitrary values.
Detailed references
- rules/naming.md: naming grammar, role tokens, variant-state color tokens, namespaces.
- rules/theming.md:
@theme registration, where values live, manifests vs Storybook, mode vs theme.
- rules/usage.md: token utilities, surface and foreground pairing, sizing.
