Tokens

Aria UI examples are styled with @ariaui/tokens. The package publishes a generated CSS file for Tailwind CSS v4 and a small TypeScript API for teams that need to inspect or regenerate the token contract.

Use tokens as semantic names in your UI. Prefer bg-background, text-foreground, border-border, bg-primary, and text-primary-foreground over hard-coded colors. Override semantic variables in your app when the product theme changes.

Install the stylesheet

Import Tailwind first, then import the generated tokens file:

@import 'tailwindcss';
@import '@ariaui/tokens/dist/tokens.css';

The stylesheet emits three layers:

• :root contains light-mode semantic variables and shared values such as radius, typography, opacity, section spacing, and shadow layer colors
• .dark contains dark-mode overrides for mode-aware semantic variables
• @theme maps semantic variables into Tailwind v4 utilities such as bg-background, text-foreground, border-border, and shadow-sm

The docs site imports the same file from the monorepo source so every example uses the package output.

Use semantic utilities

Style component parts with semantic Tailwind classes:

export function ExampleCard() {
  return (
    <section className="rounded-[var(--border-radius-lg)] border border-border bg-card p-4 text-card-foreground shadow-sm">
      <h2 className="text-lg font-semibold text-foreground">Project status</h2>
      <p className="mt-2 text-sm text-muted-foreground">
        Token-backed classes keep the component aligned with light and dark
        mode.
      </p>
      <button className="mt-4 rounded-[var(--border-radius-md)] bg-primary px-3 py-2 text-sm font-medium text-primary-foreground hover:bg-primary-hover">
        Review
      </button>
    </section>
  )
}

Color tokens are the easiest to use because generateCSS() maps each semantic color to --color-{name} in @theme. That is what enables utilities like bg-card, text-muted-foreground, border-input, and text-icon-tertiary.

Non-color values are available as CSS variables. Use arbitrary values when you need the exact token, such as rounded-[var(--border-radius-md)], max-w-[var(--max-width-3xl)], or py-[var(--section-gap-lg)].

Override existing tokens

Override semantic variables after importing the package stylesheet. Keep the variable names the same so all existing Tailwind utilities continue to work.

@import 'tailwindcss';
@import '@ariaui/tokens/dist/tokens.css';

:root {
  --primary: oklch(54.6% 0.215 263 / 1);
  --primary-hover: oklch(48.8% 0.217 264 / 1);
  --primary-foreground: oklch(100% 0 0 / 1);
  --ring: oklch(54.6% 0.215 263 / 1);
  --border-radius-md: 0.5rem;
}

.dark {
  --primary: oklch(80.9% 0.096 252 / 1);
  --primary-hover: oklch(88.2% 0.057 254 / 1);
  --primary-foreground: oklch(14.5% 0 0 / 1);
  --ring: oklch(80.9% 0.096 252 / 1);
}

Existing utilities now read your values:

<button className="rounded-[var(--border-radius-md)] bg-primary text-primary-foreground hover:bg-primary-hover">
  Save changes
</button>

Override semantic tokens such as primary, background, card, border, ring, muted, destructive, success, and warning. Do not override primitive Tailwind color variables like --color-neutral-900 or --color-red-600 as a theming strategy. The tokens package intentionally resolves primitive values into semantic variables so Tailwind's own primitive color scale remains intact.

Customizable token reference

Every token below is emitted as a CSS custom property in :root. Mode-aware values also receive .dark overrides when the token source defines them. Override these variables after importing @ariaui/tokens/dist/tokens.css.

Add a project token

For project-only tokens, define your own CSS variable and expose it to Tailwind with @theme when you want a utility class.

:root {
  --panel-accent: oklch(96.9% 0.016 294 / 1);
  --panel-accent-foreground: oklch(38% 0.178 294 / 1);
}

.dark {
  --panel-accent: oklch(28.3% 0.135 291 / 1);
  --panel-accent-foreground: oklch(94.3% 0.029 295 / 1);
}

@theme {
  --color-panel-accent: var(--panel-accent);
  --color-panel-accent-foreground: var(--panel-accent-foreground);
}

That creates utilities such as bg-panel-accent and text-panel-accent-foreground. Keep project-only tokens close to the app unless multiple packages need them.

TypeScript API

Use the TypeScript exports when you need to inspect tokens, generate CSS in tooling, or write package-level checks:

import { base, dark, generateCSS, light, primitives } from '@ariaui/tokens'

const css = generateCSS()
const lightPrimary = light.primary
const darkBackground = dark.background
const violet500 = primitives.violet[500]
const white = base.white

The public exports are:

• primitives: Tailwind v4 OKLCH color scales stored as bare channel strings
• base: white and black channels
• light: the full semantic token map, including shared non-color values
• dark: dark-mode overrides for mode-aware values
• generateCSS(): creates the same CSS shape written to dist/tokens.css

Source of truth

Token edits start in packages/tokens:

• src/primitives.ts stores primitive OKLCH channel values
• src/semantic.ts stores semantic tokens, dark-mode overrides, typography, radius, spacing, opacity, shadows, and focus-ring inputs
• src/css.ts resolves primitive references, emits :root and .dark, forwards supported non-color prefixes into @theme, and defines shadow and focus-ring composites
• scripts/write-css.ts writes dist/tokens.css during the package build

After changing token source, run the package build so the committed CSS artifact matches TypeScript:

pnpm --filter=@ariaui/tokens build