@archetypeai/ds-lib-tokens

Tailwind v4 theme for the Archetype AI Design System. Provides semantic design tokens, color palettes, and base styles for use with the design system component flavors.

Install

npm install @archetypeai/ds-lib-tokens tailwindcss

Usage

Import the theme before Tailwind in your global CSS:

@import '@archetypeai/ds-lib-tokens/fonts.css'; /* optional → PP Neue Montreal (requires font files in static/fonts/) */
@import '@archetypeai/ds-lib-tokens/theme.css';
@import 'tailwindcss';

<div class="bg-background text-foreground p-md border-border rounded-lg">
  Hello world
</div>

What's Included

| Feature | Details | |---------|---------| | Semantic Tokens | OKLCH CSS variables (shadcn-style): background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, chart-1–5, sidebar, atai-neutral, atai-good, atai-warning, atai-critical, atai-always-black, atai-always-white | | Brand Tokens | 8 OKLCH palettes with shades 50–950: atai-tangerine, atai-sunshine-yellow (amber-leaning scale), atai-lime, atai-screen-green, atai-fire-red, atai-energy-pink, atai-cool-purple, atai-baby-blue | | Spacing scale | --spacing-xs (0.25rem) → --spacing-xl (1.5rem), used as p-md, gap-lg, … | | Radius scale | --radius-xs → --radius-xl, --radius-full, plus --atai-radius-interactive (radius for interactive elements, rounded-interactive) | | Icon stroke widths | --stroke-width-icon-{default,interactive,status,emphasis} (1 / 1.25 / 1.5 / 2) for Lucide icons | | Width scale guard | --max-width-*/--min-width-* alias Tailwind's --container-* scale, so max-w-md resolves to container sizes instead of the t-shirt spacing tokens | | Dark mode | .dark class via @custom-variant dark (&:where(.dark, .dark *)) | | Typography | Font-family stacks with system fallbacks and semantic HTML base styles |

Brand tokens are defined in colors.css and loaded automatically via theme.css.

Semantic HTML base layer

theme.css styles bare HTML elements so plain markup is on-brand without utility classes: body, h1–h6, p, small, span, strong, em, label, a, code, blockquote. All elements default to border-border and outline-ring/50.

Fonts

fonts.css is included in this package with two kinds of @font-face declarations: 15 binary faces of PP Neue Montreal Sans + Mono (font-display: swap) pointing to /fonts/, plus 15 metric-matched fallback faces (per-OS base × per weight). The font binaries themselves are not part of the npm package - the CLI (ds create / ds init / ds add --fonts <path>) copies them into your project's static/fonts/.

When the binaries are absent, the fallback faces take over: each re-shapes a local system font to PP Neue Montreal's own metrics — x-height, average character width, and line box — via size-adjust + ascent/descent/line-gap-override, so an un-provisioned project still renders at the brand font's proportions and lays out identically. When the binaries are present, the same faces make the fallback→brand-font swap shift-free (no layout shift / CLS).

The fallback bases are chosen per operating system (the stacks in theme.css order them so each platform resolves its closest native font, all confirmed local()-reachable):

| | Apple | Windows | Android | |---|---|---|---| | Sans | Helvetica Neue | Arial | Roboto | | Mono | Menlo | Consolas / Cascadia Mono | Roboto Mono |

SF Mono is intentionally not used — it is not reachable via local(). Override numbers are generated with @capsizecss from the Regular weights (regenerate if the brand font's metrics change).

Weights are declared per instance: local('Helvetica Neue') always resolves to the Regular cut regardless of the font-weight descriptor, so a single face would silently render Medium as Regular and faux-bold 700. Each weight therefore names its real cut (local('HelveticaNeue-Medium') / -Bold, etc.). Bases without a true Medium (Arial, Menlo, Cascadia) omit 500, so it matches down to Regular.