# Token contract

The design system is a **contract**: a fixed set of CSS custom-property names that every theme
must define, and that every component references via `var(--…)`. Keep the names stable — themes
swap values, never names. A theme provides a `:root` block (dark / default) and an
`html[data-theme="light"]` override block.

| Token | Meaning |
|---|---|
| `--bg` | Page background |
| `--bg-2` | Secondary/elevated background |
| `--surface` | Card/panel fill (subtle) |
| `--surface-2` | Stronger surface fill (inputs, chips) |
| `--border` | Hairline border |
| `--border-strong` | Emphasized border |
| `--text` | Primary text |
| `--text-dim` | Secondary text |
| `--text-faint` | Tertiary / metadata text |
| `--accent` | Primary accent (links, primary action) |
| `--accent-2` | Secondary accent (gradients pair with `--accent`) |
| `--accent-3` | Tertiary accent (highlights) |
| `--glow` | `R, G, B` triplet of `--accent`, for `rgba(var(--glow), a)` glows |
| `--radius` | Default corner radius |
| `--radius-sm` | Small corner radius |
| `--shadow` | Elevation shadow |
| `--maxw` | Max content width |
| `--font-head` | Heading font stack |
| `--font-body` | Body font stack |

## Themes

- **`catalog`** — the project-catalog / portfolio look (shipping). Source of truth for the values.
- **`personal`** — for the new personal site. PLACEHOLDER until claude-design fills it; must
  implement every token above.

## Consuming the system

Build bundles with `node build.mjs` → `dist/<theme>.css` (self-contained: fonts + reset +
typography + `ds-*` components + theme tokens).

- **Hosted (link):** `https://arslankazmi.github.io/ak-design/dist/catalog.css` — the portfolio
  links this, so theme changes propagate on the next deploy.
- **Inlined (self-contained):** the `ak:docs-page` skill fetches a bundle and inlines it into each
  generated docs page, then layers a per-project accent override. Pages stay single-file portable.

Generic components are namespaced `ds-` (`.ds-card`, `.ds-btn`, `.ds-badge`, `.ds-tag`, `.ds-link`,
`.ds-bar`) so a consumer's own classes never collide.