# Ivy's Visual Foundation — LAW

**Status:** locked 2026-04-17 (baseline). Refines with every Visual Interview.
**Scope:** every visual output in IvyGarden — HTML, app UI, docs, charts, emails.
**Principle:** if Ivy can't read it comfortably, nothing else matters.

---

## 1. Font — dyslexia-strengthened

- **Primary:** `Lexend` (variable, weights 400 / 500 / 700) — evidence-based for
  reading proficiency, not decorative.
- **Alternates Ivy can switch to:** `Atkinson Hyperlegible`, `OpenDyslexic`,
  `system-ui`.
- **Never:** decorative serif for body text. Serif *headings* only allowed when
  Ivy picks them explicitly in a VI.

```css
font-family: "Lexend", "Atkinson Hyperlegible", "OpenDyslexic", system-ui, sans-serif;
```

## 2. Type scale

| Role       | Size (baseline) | Weight |
|------------|-----------------|--------|
| Body       | 20px (min 18px) | 500    |
| Small      | 16px            | 500    |
| H3         | 24px            | 700    |
| H2         | 32px            | 700    |
| H1         | 44px            | 700    |
| Button     | 20px            | 700    |

- `line-height: 1.7` default, adjustable 1.4 → 2.0.
- `letter-spacing: 0.02em` default, adjustable 0 → 0.08em.
- Body copy max-width ~ 62ch; never a wall of text.

## 3. Palette (baseline — refined by VI #1)

| Token             | Hex       | Use                                    |
|-------------------|-----------|----------------------------------------|
| `--bg-deep`       | `#0a0a1f` | page background (midnight indigo)      |
| `--bg-panel`      | `#121233` | cards, sheets                          |
| `--bg-raised`     | `#1a1a44` | hover / active                         |
| `--accent-1`      | `#6b21a8` | primary purple, borders                |
| `--accent-2`      | `#9333ea` | mid purple, buttons                    |
| `--accent-3`      | `#a855f7` | glow, highlight                        |
| `--text-body`     | `#d4a843` | warm gold — body text                  |
| `--text-accent`   | `#e8c564` | lighter gold — accent text             |
| `--text-soft`     | `#f5f5ef` | soft white — secondary / captions      |
| `--muted`         | `#6b6b86` | disabled / hints                       |

**Priority order:** purple > midnight indigo > gold > soft white > silver.

## 4. Dyslexia controls — required on every visual surface

Every HTML VI, every app screen, must expose (either visible or behind a
one-tap "a11y" pill):

1. Font-size slider — 16 to 26 px
2. Letter-spacing slider — 0 to 0.08 em
3. Line-height slider — 1.4 to 2.0
4. High-contrast toggle (boosts `--text-body` to `#ffe58a` on `#000000`)
5. Motion-reduce toggle (disables decorative transitions)

Controls persist via `localStorage` key `ivy-a11y`.

## 5. Layout language

- Rounded corners: **16px** standard, 24px for hero cards.
- Card style: dark panel with a **2px `--accent-1` left border** OR a soft
  `box-shadow: 0 0 20px rgba(168,85,247,0.25)` purple glow.
- Dividers: 1px `rgba(212,168,67,0.25)` (thin gold rule).
- Tap targets: min **64px × 64px** on mobile. Buttons get generous padding.
- Whitespace: airy. No dense grids. No small hover-only affordances.

## 6. Motion

- Default easing: `cubic-bezier(.2,.7,.2,1)`, 240–320ms.
- Big animations (shuffle, card flip) lean into the mystical, but honor
  `prefers-reduced-motion` and the Motion-Reduce toggle: fade-only fallback.

## 7. Visual references Ivy likes

See [`visual-references.md`](visual-references.md). Summary: dark starry
background, elegant card framing, generous negative space, single-card focus,
subtle reflection under the hero card.

## 8. How this document evolves

Each Visual Interview can amend this file. The process:

1. Run a VI (HTML in `visual-interviews/`).
2. Ivy answers; results save to `visual-interviews/results/NNN-*.json`.
3. I read the results, write a short diff summary at the bottom of this file
   under a dated "Refinements" heading, and update the tokens above.
4. The previous values stay in the history so we never lose context.

## Refinements

_(none yet — VI #001 is the baseline)_