# src/tokens/

> **P2** | Parent: [Root AGENTS.md](../../AGENTS.md)

## Member list (CSS entrypoints)

| Area | Files | Purpose |
| ---- | ----- | ------- |
| Bundle | `index.css` | Recommended full import |
| Scale | `scale/`, `scale.css` (legacy) | Layout tokens (`data-style`) via config + computed + presets |
| Theme bridge | `theme-base.css`, `theme.css` (legacy) | Tailwind `@theme` mappings, shared motion, scrollbar helpers |
| Color packs | `themes/*.css` | Palette definitions (`--token-color-*`), including Mint, Forest, Parchment, and QoderWork theme-name aliases |
| Agent ontology | `registry/tokens/ontology.json` | Machine-readable token intent, usage, and forbidden patterns |
| Utilities | `scrollbar-utility.css` | Scrollbar styling helpers |

---

**Covenant:** whenever you add presets, themes, or rename token files, update this table and the root `AGENTS.md` if publishing behavior changes.

---

## Narrative

### Two axes

1. **`data-style`** — spacing, radii, typography presets (`scale/`).
2. **`data-theme`** — color palettes independent from layout. Define **`--token-color-*`** in `:root` / `[data-theme]`, map to **`--color-*`** inside `@theme` without self-referential loops (critical for CLI consumers).

### Authoring rules

- Never create `@theme` entries such as `--color-primary: var(--color-primary)` — use `--token-color-*` as the source of truth.
- Components consume **`var(--color-*)`** only; token files own the mapping.
- When adding a preset or theme, cover spacing, radius, and font scales consistently.

### Consumption modes

| Mode | What happens | Consumer needs Tailwind? |
| ---- | ------------- | ------------------------- |
| npm package | `@tailwindcss/cli` emits `dist/sparkdesign.css` | No |
| CLI copy | User `@import`s token CSS in their app | Tailwind v4 recommended |

### Checklist

- [ ] New `data-style` preset updates `scale/presets/`
- [ ] New configurable knobs land in `scale/config.css` + `computed.css`
- [ ] New theme file added under `themes/` and wired through `index.css`
- [ ] Contrast checked for accessibility
- [ ] This P2 file reflects the change