# Design System — Inference Routing

This file tells Claude which design guides to read based on the task at hand. It is the entry point for any AI agent working on a codebase that uses the Fractal design system.

**Do not read all guides for every task.** Use the routing table below to fetch only what your task requires.

---

## Guide Locations

| Guide                  | Path                                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| Philosophy             | [philosophy.md](./philosophy.md) — Root aesthetic: surfaces, interaction paradigm, density            |
| Color                  | [color/color-guide.md](./color/color-guide.md) — 10-stop scales, semantic tokens, WCAG rules                 |
| Color Scale Generation | [color/color-scale-generation.md](./color/color-scale-generation.md) — Rules for creating new color scales              |
| Color CSS              | [color/colors.css](./color/colors.css) — Color token definitions                                         |
| Typography             | [typography/typography-guide.md](./typography/typography-guide.md) — Font tokens, tier system, sizing                  |
| Typography CSS         | [typography/typography.css](./typography/typography.css) — Type token definitions                                 |
| Layout                 | [layout/layout-guide.md](./layout/layout-guide.md) — 8pt grid, spacing, shadows, breakpoints, radii            |
| Layout CSS             | [layout/layout.css](./layout/layout.css) — Layout token definitions                                       |
| Motion                 | [motion/motion-guide.md](./motion/motion-guide.md) — Timing, easing curves, transitions                        |
| Motion CSS             | [motion/motion.css](./motion/motion.css) — Motion token definitions                                       |
| Components             | [components/component-guide.md](./components/component-guide.md) — Button, input, card, table, nav, modal specs       |
| Data Viz               | [data-visualization/data-visualization-guide.md](./data-visualization/data-visualization-guide.md) — Chart styling and color sequences |
| Illustration           | [illustration/blog-post-thumbnail-guide.md](./illustration/blog-post-thumbnail-guide.md) — Crystal lattice thumbnail generation (shape, layout, materials, gradients) |
| Illustration Code      | [illustration/crystal-lattice.js](./illustration/crystal-lattice.js) — Generator implementation (seeded PRNG, paths, materials, gradients) |
| Thumbnail Tool         | [../docs/tools/crystal-generator.html](../docs/tools/crystal-generator.html) — Interactive browser tool for generating thumbnails |
| Presentations          | [presentations/presentations-guide.md](./presentations/presentations-guide.md) — PPTX skill entry: reading, design ideas, QA, image conversion |
| Presentations Editing  | [presentations/editing.md](./presentations/editing.md) — Template-based PPTX editing (unpack → modify → pack) |
| Presentations PptxGenJS | [presentations/pptxgenjs.md](./presentations/pptxgenjs.md) — Creating decks from scratch with pptxgenjs |
| Presentations Scripts  | [presentations/scripts/](./presentations/scripts/) — Python tooling for unpack, pack, clean, thumbnail, slide ops |

All paths are relative to this file's location (`design/`). Resolve them relative to wherever this routing file is served from — local checkout, hosted site, or elsewhere.

---

## Routing Table

Read **only** the guides marked for your task. "Required" = always fetch and read. "If needed" = fetch only when the task touches that domain.

| Task                                  | Philosophy |  Color   | Typography |  Layout   |  Motion   | Components | Data Viz  | Illustration | Presentations |
| ------------------------------------- | :--------: | :------: | :--------: | :-------: | :-------: | :--------: | :-------: | :----------: | :-----------: |
| **New component**                     |  Required  | Required |  Required  | If needed | If needed |  Required  |     —     |      —       |       —       |
| **Modify component appearance**       |     —      | Required | If needed  |     —     |     —     |  Required  |     —     |      —       |       —       |
| **Layout / positioning / spacing**    |     —      |    —     |     —      | Required  |     —     |     —      |     —     |      —       |       —       |
| **Add animation / transition**        |     —      |    —     |     —      |     —     | Required  |     —      |     —     |      —       |       —       |
| **Color / theming change**            |     —      | Required |     —      |     —     |     —     |     —      |     —     |      —       |       —       |
| **Typography adjustment**             |     —      |    —     |  Required  |     —     |     —     |     —      |     —     |      —       |       —       |
| **Build full new page**               |  Required  | Required |  Required  | Required  | If needed |  Required  |     —     |      —       |       —       |
| **Data visualization**                |     —      | Required | If needed  | If needed |     —     |     —      | Required  |      —       |       —       |
| **Responsive design**                 |     —      |    —     |     —      | Required  |     —     | If needed  |     —     |      —       |       —       |
| **Interaction states**                |     —      | Required |     —      |     —     | If needed |  Required  |     —     |      —       |       —       |
| **Accessibility fix**                 |     —      | Required |  Required  |     —     | If needed |  Required  |     —     |      —       |       —       |
| **Blog thumbnail / illustration**     |     —      | Required |     —      |     —     |     —     |     —      |     —     |   Required   |       —       |
| **Build presentation / slide deck**   |  Required  | Required |  Required  | If needed |     —     | If needed  | If needed |  If needed   |   Required    |
| **Modify existing deck**              |     —      | If needed | If needed |     —     |     —     |     —      | If needed |  If needed   |   Required    |

---

## When to Read philosophy.md

Fetch the philosophy guide **only** when:

1. Creating a **brand-new component** without a close precedent in the codebase
2. Building a **full new page or major feature area**
3. Making a **subjective design judgment** (e.g., "dense or spacious?", "border or shadow?")
4. **First time** in a session — read once to calibrate, then rely on specific guides

Do **not** fetch philosophy.md for routine color swaps, spacing tweaks, adding a standard animation, or modifying existing components within established patterns.

---

## When to Read presentations-guide.md

Fetch the presentations guide **whenever the task creates, reads, or modifies a `.pptx` file** — including text extraction, content edits, full-deck builds, and template adaptation.

The entry guide (`presentations-guide.md`) covers reading content, design direction (color, layout, typography references), and visual QA via `soffice` + `pdftoppm`. It then routes to:

- [`editing.md`](./presentations/editing.md) for template-based workflows (unpack the source deck, manipulate slides, repack).
- [`pptxgenjs.md`](./presentations/pptxgenjs.md) for creating decks from scratch in Node.

Python tooling lives under [`presentations/scripts/`](./presentations/scripts/) (`thumbnail.py`, `add_slide.py`, `clean.py`, plus `office/` for unpack/pack/validate/soffice).

Do **not** fetch presentations-guide.md for regular app UI, blog thumbnails, or any task that doesn't produce or modify a `.pptx`.

---

## Conflict Resolution

When design guides and existing code diverge, **the design guides are authoritative**. Update code to match the guides, not the other way around.