Design tokens

• Color ramps preserve the generated shades for primary, secondary, and neutral anchors.

• Semantic mode tokens describe intent: backgrounds, text, borders, actions, feedback, overlays, panels, headers, and sidebars.

• Static tokens describe spacing, sizing, radius, typography, motion, focus, blur, opacity, and breakpoints.

Application code should normally consume semantic or static tokens. Direct ramp shades are useful for visualization and tooling, but they couple product CSS to palette details.

Tavo.js UI components already consume the token contract. When a product-specific class is still necessary, reference the same variables so custom sections respond to theme and scale changes.

css.projectSummary {
  color: var(--tui-color-text);
  background: var(--tui-color-panel-bg);
  border: var(--tui-border-width) solid var(--tui-color-panel-border);
  border-radius: var(--tui-radius-surface);
  padding: var(--tui-space-6);
}

tokens.light and tokens.dark apply after generated semantic tokens. Use them for a small number of product aliases that genuinely need a fixed value, then run the accessibility audit again.

json{
  "tokens": {
    "light": { "color-sidebar-bg": "#ffffff" },
    "dark": { "color-sidebar-bg": "#050505" }
  }
}

Spacing uses a numeric scale, not named md or lg variables. Component gap names map onto that scale: sm uses space-2, md uses space-4, and lg uses space-6.

css.productPanel {
  color: var(--tui-color-text);
  background: var(--tui-color-panel-bg);
  border: var(--tui-border-width) solid var(--tui-color-panel-border);
  border-radius: var(--tui-radius-surface);
  padding: var(--tui-space-6);
}

• tavoUiTokenNames is the built-in variable-name inventory.

• tavoUiTokenMetadata includes each name and its token group.

• getTavoUiTokenMetadata(config) adds project-defined override names.

• Use tavo-ui validate-css to find unknown Tavo.js UI variables in application stylesheets.

tsimport {
  getTavoUiTokenMetadata,
  getTavoUiTokenGroup,
  tavoUiTokenMetadata,
  tavoUiTokenNames
} from "@tavojs/ui/theme";

tavoUiTokenNames.includes("--tui-space-4");
getTavoUiTokenGroup("--tui-color-panel-bg");

// Includes custom entries from tokens.light and tokens.dark.
const projectTokens = getTavoUiTokenMetadata(config);

Theme generation emits the canonical --tui variable contract. Use tokens.light and tokens.dark to replace generated values or add project-specific variables for each mode.

• tokens.light and tokens.dark apply after generated semantic values.

• An override name does not need to be built in; generated custom names use the canonical --tui prefix.

• Re-run contrast and CSS-token audits after overriding foreground or background colors.

css--tui-color-panel-bg: #ffffff;
--tui-product-accent: #7c3aed;

• All elements and pseudo-elements receive border-box sizing.

• Document scrollbars receive token-backed colors and dimensions.

• body margin and padding are reset to zero.

• body receives the generated application-background token.

• The root selector receives color-scheme, root font sizing, ramps, semantic variables, and static tokens.