Design token contract

Canonical --rad-ui-* tokens for Rad UI's styled layers. The headless component core does not require these variables; they apply when you import theme CSS or use Clarity/baremetal styles.

Source of truth in the repository:

• styles/cssTokens/ — CSS custom property definitions
• styles/jsTokens/ — JS token maps referencing CSS variables
• src/tokenGen/ — generation pipeline

Naming convention

All public theme variables use the prefix --rad-ui- with kebab-case segments:

txt
--rad-ui-<category>-<name>
--rad-ui-color-gray-100
--rad-ui-radius-md
--rad-ui-spacing-4

Semantic accent tokens are scoped by Theme attributes such as data-rad-ui-accent-color.

Token families

Component expectations

Styled Rad UI layers should:

1. Read layout and color from token variables, not hard-coded hex in component SCSS.
2. Use semantic data-* attributes for state; tokens supply the values in CSS.
3. Respect Theme appearance (data-rad-ui-theme) for light/dark palettes.
4. Keep motion on tokenized durations/easings so prefers-reduced-motion can be applied consistently.

Consumer contract

When importing @radui/ui/themes/default.css:

• You may rely on documented --rad-ui-* names in your own CSS.
• Override tokens on Theme containers or :root for product branding.
• Do not depend on undocumented internal class selectors.

When using Rad UI headlessly:

• Tokens are optional; bring your own design tokens and map them in wrappers.

Complete token sets

Rad UI-provided styled layers assume that the theme CSS supplies a complete token set for the component styles being used.

Supported:

• import a Rad UI theme CSS file and override selected --rad-ui-* variables
• scope overrides to :root, a Theme container, or another stable application boundary
• leave all non-overridden variables inherited from the imported theme

Unsupported:

• importing only a small subset of token definitions and expecting every styled component to recover
• removing required token families used by loaded component CSS
• relying on browser-invalid CSS declarations caused by missing variables

Partial overrides are supported when they sit on top of a complete theme. Partial token definitions are not a complete theme by themselves.

Fallback values

Inline CSS fallback values such as var(--rad-ui-radius-md, 6px) are not the public customization contract for Rad UI styled layers.

Rad UI may use fallback values where they make a declaration resilient during development, migration, or progressive token rollout. Treat those fallbacks as internal implementation details unless a variable's documentation explicitly says otherwise.

Consumers should provide the documented variables they depend on instead of depending on fallback branches. Missing documented variables are unsupported configuration, not a guaranteed graceful-degradation path.

Safe override pattern

Prefer additive token overrides:

css
@import "@radui/ui/themes/default.css";

:root {
  --rad-ui-radius-md: 8px;
  --rad-ui-spacing-4: 1rem;
}

[data-rad-ui-theme][data-rad-ui-accent-color="brand"] {
  --rad-ui-color-accent-9: #3157d5;
}

Avoid replacement strategies that redefine only a handful of variables without importing or generating the rest of the theme contract.

Adding or changing tokens

1. Update styles/cssTokens/ and regenerate via npm run generate-tokens.
2. Mirror changes in styles/jsTokens/ when Tailwind/JS consumers need the name.
3. Document new public variables if components expose them as styling hooks.
4. Run visual review on Clarity components affected by the token change.

Related docs

• Usage for Theme and optional theme CSS import
• Clarity design system in the repository knowledge docs