# `@mirai/tokens`

Single source of truth for the MirAI design system. Every visual constant — color, type, space, radius, shadow, motion — lives here in **`tokens.json`** and is compiled to platform-specific targets.

> **Cardinal rule.** Don't introduce new values. Don't fork the file. If a design genuinely needs something outside this set, change `tokens.json` and regenerate.

---

## Files

| File | Format | Consumer |
|---|---|---|
| `tokens.json` | [W3C Design Tokens Community Group](https://design-tokens.github.io/community-group/format/) (`$value` / `$type`) | Style Dictionary, Specify, Cobalt, Terrazzo, any DTCG-aware tool |
| `figma.tokens.json` | [Tokens Studio for Figma](https://tokens.studio) — multi-set with `mirai/core` + `mirai/semantic` | Designers in Figma |
| `shadcn.css` | CSS variables — HSL triplets in shadcn convention | [shadcn/ui](https://ui.shadcn.com) projects |
| `tailwind.preset.js` | Tailwind theme preset | Tailwind v3 / v4 projects |
| `style-dictionary.config.js` | Style Dictionary v4 config | Build pipeline for SCSS / JS / CSS / iOS / Android outputs |

---

## Quick adoption

### shadcn / Tailwind project

```bash
# 1. Copy or symlink
cp -r mirai-design-system/tokens ./src/styles/mirai-tokens

# 2. Import the CSS layer (or paste into your globals.css)
@import "./src/styles/mirai-tokens/shadcn.css";

# 3. Wire the Tailwind preset
//   tailwind.config.js
module.exports = {
  presets: [require("./src/styles/mirai-tokens/tailwind.preset")],
  content: ["./src/**/*.{ts,tsx,html,mdx}"],
};
```

Then `npx shadcn@latest add button` etc. — components inherit MirAI's tri-color palette and 8 px interactive radius automatically.

### Figma (Tokens Studio plugin)

1. Install [Tokens Studio](https://tokens.studio) in Figma.
2. **Tools → Import → Single file (JSON)** and select `figma.tokens.json`.
3. Apply the `mirai/core` and `mirai/semantic` sets. Push back to JSON on every change so the repo stays the source of truth.

### Code generation (Style Dictionary)

```bash
npm i -D style-dictionary
npx style-dictionary build --config tokens/style-dictionary.config.js
# outputs land in dist/{css,scss,js,json}
```

---

## What's in the file

### Color — tri-color restrictive

`color.white` · `color.black` · `color.blue` (`#556DD7`).

All grays are alpha derivations of pure black:
`text.secondary` (0.65) · `text.tertiary` (0.45) · `border.subtle` (0.15) · `surface.muted` (0.04) · `surface.hover` (0.06) · `surface.press` (0.10).

Plus a MirAI Blue alpha ramp (`blueAlpha.04`–`100`) for focus rings and governed-data fills.

### Type — Space Grotesk only

8-step size scale (`display` 48 → `xs` 12). Three line heights. Four trackings. Four weights. The font file lives at [`fonts/SpaceGrotesk-VariableFont_wght.ttf`](../fonts) — load it once at the application root.

### Space — 4-pt base

`1` (4 px) → `16` (64 px). No half-steps. No new values.

### Radius — duality

`none` (0) and `structural` (4) for data and structural surfaces. `interactive` (8) **only** on buttons, inputs, menus, and other human-touch points. `pill` (999) for tags.

### Shadow — brutalist

Solid, unblurred, geometric offsets only. `hardSm` / `hard` / `hardLg` use pure black; `hardBlue` uses MirAI Blue. **No** soft drop shadows, **no** blur, **no** glassmorphism — translucency suggests obfuscation.

### Motion — deterministic

Three durations (`120ms` / `180ms` / `280ms`), one easing (`cubic-bezier(0.2, 0.8, 0.2, 1)`). No bounce, no spring.

---

## Editing protocol

1. Edit `tokens.json` only.
2. Regenerate `figma.tokens.json`, `shadcn.css`, `tailwind.preset.js` (manually or via a future build script).
3. Bump `CHANGELOG.md`. Tag the release.
4. Open a PR; design-systems review is mandatory.