@xzibit/tokens

Canonical design tokens for the Xzibit Apps portfolio — consumed as a Tailwind preset + a CSS variables file.

Single source of truth: mirrors _portfolio/CONVENTIONS/DESIGN-STANDARD.md v2.1+. Stewarded by the Xzibit Apps Design Standards Cowork. When the standard changes, this package bumps to match.

Install

npm install @xzibit/tokens

(Tailwind 3+ is a peer dependency — apps should already have it.)

Use

1. Add the preset to tailwind.config.{ts,js}

// tailwind.config.ts
import type { Config } from 'tailwindcss';
import xzibitTokens from '@xzibit/tokens';

const config: Config = {
  presets: [xzibitTokens],
  content: [
    './src/app/**/*.{ts,tsx}',
    './src/components/**/*.{ts,tsx}',
    './src/hooks/**/*.{ts,tsx}',
  ],
  theme: {
    extend: {}, // app-specific extensions go here
  },
  plugins: [],
};

export default config;

2. Import the CSS variables once at your app's root layout

// src/app/layout.tsx
import '@xzibit/tokens/tokens.css';

That's it. Tailwind utility classes now resolve against the Xzibit token set.

What you get

Brand palette (literal values)

xz-teal, xz-teal-dark, xz-teal-light, xz-dark, xz-charcoal, xz-grey, xz-light-grey, xz-off-white, xz-white, xz-red, xz-purple, xz-indigo, xz-deep-teal, xz-deep-orange, xz-rose, xz-blue-grey.

<button className="bg-xz-teal text-xz-white">Save</button>

Semantic tokens (theme-aware via CSS vars)

background, foreground, border, muted, muted-foreground, primary, primary-foreground, secondary, secondary-foreground, destructive, destructive-foreground, success, success-foreground, warning, warning-foreground.

<main className="bg-background text-foreground">...</main>

Status chip tokens

status-in-scope-bg/ink, status-deferred-bg/ink, status-wont-build-bg/ink.

Provenance chip tokens

prov-internal-bg/ink, prov-best-bg/ink, prov-vendor-bg/ink.

Typography

tokens.css sets body to the Xzibit font stack (League Spartan → HurmeGeometricSans1 → system-ui). The preset exposes the stack as font-sans (Tailwind's default font-family utility).

Six type-scale sizes per the density preset:

| Class | Size | Weight | Use for | |---|---|---|---| | text-h1 | 32px | 500 | Page lead | | text-h2 | 24px | 500 | Section | | text-h3 | 18px | 500 | Sub-section | | text-body | 16px | 400 | Body | | text-small | 14px | 400 | Table cell, secondary text | | text-micro | 12px | 500 | Table header, chip, micro-meta |

Density preset spacing

Tight padding values matching DESIGN-STANDARD §Density Preset:

| Class | Value | Use for | |---|---|---| | py-cell-y px-cell-x | 0.6rem × 0.875rem | Data table cells | | py-card-y px-card-x | 1rem × 1.25rem | Card body | | py-input-y px-input-x | 0.55rem × 0.75rem | Form inputs | | py-btn-y px-btn-x | 0.55rem × 1.25rem | Primary buttons | | py-chip-y px-chip-x | 0.15rem × 0.5rem | Chips / pills | | py-page-y px-page-x | 3rem × 2rem | Page container |

Shadows

shadow-card (resting) and shadow-card-hover (hover / active). Two-layer subtle shadows tinted with --xz-dark alpha, not black.

Border radius

rounded-chip (4px), rounded-button / rounded-input (6px), rounded-card (8px).

Max content width

max-w-content (960px) — default for centred <main> containers.

What's NOT included

• React components — components live in each app or in a future separate package. See _portfolio/CONVENTIONS/DESIGN-STANDARD.md §Component Vocabulary for the spec.
• Dark mode — out of scope for v0.1.0. The token structure supports it (semantic tokens are CSS vars); dark variant lands in a future release.
• Icons, fonts, illustrations — fonts are referenced by name (League Spartan from Google Fonts; HurmeGeometricSans1 from licensed source). Apps load them themselves.

Versioning

Semantic versioning. Apps consume latest by default.

• Patch (0.1.x): bug fixes; no value changes
• Minor (0.x.0): new tokens added; no breaking changes
• Major (x.0.0): existing token renamed or removed (deprecation cycle documented in CHANGELOG)

Authority chain

When _portfolio/CONVENTIONS/DESIGN-STANDARD.md changes, this package bumps to match within ~1 week. The reverse is not true — never update a token here without amending the standard first.

Sister-request the Xzibit Apps Design Standards Cowork for amendments that touch DESIGN-STANDARD.

License

MIT. See LICENSE.