@monoes/monomindcli 1.8.0 → 1.9.1

package/.claude/skills/monodesign/reference/teach.md

@@ -0,0 +1,156 @@
+# Teach Flow
+
+Gathers design context for a project and writes two complementary files at the project root:
+
+- **PRODUCT.md** (strategic): root project file for register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): root project file for visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+Read PRODUCT.md and DESIGN.md directly (check project root, then docs/, then .agents/context/)
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 and offer to run `/impeccable document` for DESIGN.md.
+- **PRODUCT.md exists but has no `## Register` section (legacy)**: add it. Infer a hypothesis from the codebase (see Step 2), confirm with the user, write the field.
+- **Both exist**: Ask the user for clarification before proceeding. Ask which file to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+If teach was invoked as a setup blocker by another command, such as `/monodesign craft landing page`, pause that command here. Complete teach, re-run the loader, then resume the original command with the freshly loaded context. For craft, resume into shape next; teach creates project context, but it is not a substitute for the task-specific shape interview and confirmed design brief.
+
+## Step 2: Explore the codebase
+
+Before asking questions, thoroughly scan the project to discover what you can:
+
+- **README and docs**: Project purpose, target audience, any stated goals
+- **Package.json / config files**: Tech stack, dependencies, existing design libraries
+- **Existing components**: Current design patterns, spacing, typography in use
+- **Brand assets**: Logos, favicons, color values already defined
+- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
+- **Any style guides or brand documentation**
+
+Also form a **register hypothesis** from what you find:
+
+- Brand signals: `/`, `/about`, `/pricing`, `/blog/*`, `/docs/*`, hero sections, big typography, scroll-driven sections, landing-page-shaped content.
+- Product signals: `/app/*`, `/dashboard`, `/settings`, `/(auth)`, forms, data tables, side/top nav, app-shell components.
+
+Register is a hypothesis at this point, not a decision; Step 3 confirms it.
+
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
+
+## Step 3: Ask strategic questions (for PRODUCT.md)
+
+Ask the user for clarification before proceeding. Ask only about what you couldn't infer from the codebase.
+
+### Interview mode, not confirmation mode
+
+If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
+
+- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
+- Ask **2-3 questions per round**, then wait for answers.
+- Use inferred answers as hypotheses or options, not as finished facts.
+- Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
+- Round 1 should establish register, users/purpose, and desired outcome.
+- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
+
+### Minimum viable interview
+
+Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, users and purpose, brand personality, anti-references, and accessibility needs unless each answer is directly discoverable from repo context. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
+
+### Register (ask first; it shapes everything below)
+
+Every design task is either **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboards, tools: design SERVES the product).
+
+If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface. Does that match your intent, or should we treat it differently?"*
+
+If the signal is genuinely split (e.g. a product with a big marketing landing), Ask the user for clarification before proceeding. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
+
+### Users & Purpose
+- Who uses this? What's their context when using it?
+- What job are they trying to get done?
+- For brand: what emotions should the interface evoke? (confidence, delight, calm, urgency)
+- For product: what workflow are they in? What's the primary task on any given screen?
+
+### Brand & Personality
+- How would you describe the brand personality in 3 words?
+- Reference sites or apps that capture the right feel? What specifically about them?
+  - For brand, push for real-world references in the right lane (tech-minimal, editorial-magazine, consumer-warm, brutalist-grid, etc.), not generic "modern" adjectives.
+  - For product, push for category best-tool references (Linear, Figma, Notion, Raycast, Stripe).
+- What should this explicitly NOT look like? Any anti-references?
+
+### Accessibility & Inclusion
+- Specific accessibility requirements? (WCAG level, known user needs)
+- Considerations for reduced motion, color blindness, or other accommodations?
+
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here.** Those belong in DESIGN.md, not PRODUCT.md.
+
+## Step 4: Write PRODUCT.md
+
+Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
+
+Synthesize into a strategic document:
+
+```markdown
+# Product
+
+## Register
+
+product
+
+## Users
+[Who they are, their context, the job to be done]
+
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
+[Voice, tone, 3-word personality, emotional goals]
+
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
+
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "show, don't tell", "expert confidence". NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
+```
+
+Register is either `brand` or `product` as a bare value. No prose, no commentary.
+
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it; merge into that content rather than starting from scratch.
+
+## Step 5: Decide on DESIGN.md
+
+Offer `/impeccable document` either way. Two paths:
+
+- **Code exists** (CSS tokens, components, a running site): "I can generate a DESIGN.md that captures your visual system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+- **Pre-implementation** (empty project): "I can seed a starter DESIGN.md from five quick questions about color strategy, type direction, motion energy, and references. You can re-run once there's code, to capture the real tokens. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (it auto-detects scan vs seed). Load its reference and follow that flow.
+
+If the user prefers to skip, mention they can run `/impeccable document` any time later.
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- Register captured (brand / product)
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `Read PRODUCT.md and DESIGN.md directly (check project root, then docs/, then .agents/context/)` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version.
+
+If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context.
+
+Optionally Ask the user for clarification before proceeding. Ask whether they'd like a brief summary of PRODUCT.md appended to PRODUCT.md and DESIGN.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

package/.claude/skills/monodesign/reference/token-architecture.md

@@ -0,0 +1,222 @@
+# Token Architecture
+
+Three-layer token system for scalable, themeable design systems. Use during `extract` and `document` workflows when building or auditing a project's design token structure.
+
+## The Three Layers
+
+```
+┌─────────────────────────────────────────┐
+│  Component Tokens                       │  Per-component overrides
+│  --button-bg, --card-padding            │
+├─────────────────────────────────────────┤
+│  Semantic Tokens                        │  Purpose-based aliases
+│  --color-primary, --spacing-section     │
+├─────────────────────────────────────────┤
+│  Primitive Tokens                       │  Raw design values
+│  --color-ink, --space-4                 │
+└─────────────────────────────────────────┘
+```
+
+| Layer | Purpose | When to change |
+|-------|---------|----------------|
+| Primitive | Raw values — colors, sizes, radii | Rarely; these are foundational |
+| Semantic | Meaning assignment | When switching themes or rebrand |
+| Component | Component customization | Per-component deviations from semantic defaults |
+
+---
+
+## Layer 1: Primitive Tokens
+
+Raw values with no semantic meaning. For the Editorial Sanctuary, these are the OKLCH palette values.
+
+```css
+:root {
+  /* Colors — OKLCH only (see design-principles.md for full palette) */
+  --color-ink-raw:        oklch(10% 0 0);          /* Deep Graphite */
+  --color-charcoal-raw:   oklch(25% 0 0);          /* Soft Charcoal */
+  --color-ash-raw:        oklch(55% 0 0);          /* Mid Ash */
+  --color-mist-raw:       oklch(92% 0 0);          /* Paper Mist */
+  --color-paper-raw:      oklch(96% 0.005 350);    /* Warm Ash Cream */
+  --color-white-raw:      oklch(98% 0 0);          /* Crisp Paper White */
+  --color-accent-raw:     oklch(60% 0.25 350);     /* Editorial Magenta */
+  --color-accent-deep-raw:oklch(52% 0.25 350);     /* Editorial Magenta Deep */
+
+  /* Spacing (8-base scale) */
+  --space-1:  0.5rem;   /*  8px */
+  --space-2:  1rem;     /* 16px */
+  --space-3:  1.5rem;   /* 24px */
+  --space-4:  2rem;     /* 32px */
+  --space-6:  3rem;     /* 48px */
+  --space-10: 5rem;     /* 80px */
+  --space-15: 7.5rem;   /* 120px */
+
+  /* Typography */
+  --font-size-xs:   0.8125rem; /* 13px — captions minimum */
+  --font-size-sm:   0.875rem;  /* 14px */
+  --font-size-base: 1rem;      /* 16px — body minimum */
+  --font-size-lg:   1.125rem;
+  --font-size-xl:   1.25rem;
+  --font-size-2xl:  1.5rem;
+  --font-size-3xl:  1.875rem;
+  --font-size-4xl:  2.25rem;
+
+  /* Radius */
+  --radius-none: 0;       /* Editorial Sanctuary: sharp by default */
+  --radius-sm:   0.25rem;
+  --radius-md:   0.5rem;
+  --radius-lg:   0.75rem;
+
+  /* Shadows — max 0.15 alpha (Low-Alpha Rule) */
+  --shadow-sm:  0 1px 3px rgba(0,0,0,0.06);
+  --shadow-md:  0 4px 24px -4px rgba(0,0,0,0.12), 0 1px 3px rgba(0,0,0,0.06);
+  --shadow-lg:  0 8px 40px -8px rgba(0,0,0,0.14), 0 2px 6px rgba(0,0,0,0.08);
+
+  /* Duration */
+  --duration-fast:   150ms;
+  --duration-base:   250ms;
+  --duration-slow:   400ms;
+
+  /* Easing */
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+---
+
+## Layer 2: Semantic Tokens
+
+Purpose-based aliases. These are what components consume — never primitives directly.
+
+```css
+:root {
+  /* Surface */
+  --color-bg:        var(--color-paper-raw);     /* Page background */
+  --color-surface:   var(--color-white-raw);     /* Card surfaces */
+  --color-border:    var(--color-mist-raw);      /* Hairline borders */
+
+  /* Text */
+  --color-ink:       var(--color-ink-raw);       /* Primary text */
+  --color-secondary: var(--color-charcoal-raw);  /* Secondary text */
+  --color-tertiary:  var(--color-ash-raw);       /* Meta, captions */
+
+  /* Accent */
+  --color-accent:      var(--color-accent-raw);
+  --color-accent-hover:var(--color-accent-deep-raw);
+  --color-accent-dim:  oklch(60% 0.25 350 / 0.15); /* Magenta Whisper */
+  --color-accent-veil: oklch(60% 0.25 350 / 0.25); /* Magenta Veil */
+
+  /* Feedback */
+  --color-error:    oklch(55% 0.22 27);
+  --color-success:  oklch(55% 0.18 145);
+  --color-warning:  oklch(72% 0.17 60);
+
+  /* Spacing semantics */
+  --spacing-component: var(--space-2);  /* 16px — within components */
+  --spacing-section:   var(--space-6);  /* 48px — between sections */
+}
+```
+
+---
+
+## Layer 3: Component Tokens
+
+Component-specific overrides referencing the semantic layer. Add only when a component genuinely deviates from the semantic defaults.
+
+```css
+:root {
+  /* Primary CTA — see design-principles.md for full spec */
+  --btn-primary-bg:       var(--color-ink);
+  --btn-primary-fg:       var(--color-surface);
+  --btn-primary-hover-bg: var(--color-accent);
+  --btn-radius:           0;                    /* Sharp — editorial */
+
+  /* Input */
+  --input-border:         var(--color-border);
+  --input-border-focus:   var(--color-accent);
+  --input-focus-ring:     var(--color-accent-dim);
+  --input-bg:             var(--color-surface);
+  --input-radius:         0;
+
+  /* Card */
+  --card-border:          var(--color-border);
+  --card-bg:              var(--color-surface);
+  --card-padding:         var(--space-2);
+  --card-shadow-hover:    var(--shadow-md);
+  --card-radius:          0;                    /* Or --radius-sm for product register */
+}
+```
+
+---
+
+## Dark Mode
+
+Override semantic tokens only — primitives stay unchanged.
+
+```css
+.dark {
+  --color-bg:        var(--color-ink-raw);
+  --color-surface:   oklch(15% 0.005 350);   /* Slightly warmer than pure black */
+  --color-ink:       var(--color-white-raw);
+  --color-secondary: var(--color-mist-raw);
+  --color-tertiary:  var(--color-ash-raw);
+  --color-border:    oklch(22% 0 0);
+}
+```
+
+---
+
+## Naming Convention
+
+```
+--{category}-{item}-{variant}-{state}
+
+Examples:
+--color-accent             # category-item
+--color-accent-hover       # category-item-state
+--btn-primary-hover-bg     # component-variant-state-property
+--spacing-section          # category-semantic
+```
+
+## Antipattern: Flat Tokens
+
+Before (flat — wrong):
+```css
+--button-primary-bg: oklch(10% 0 0);   /* Hard to theme */
+```
+
+After (three-layer — correct):
+```css
+/* Primitive */    --color-ink-raw: oklch(10% 0 0);
+/* Semantic */     --color-ink:     var(--color-ink-raw);
+/* Component */    --btn-primary-bg: var(--color-ink);
+```
+
+The three-layer structure means a rebrand only touches primitives. A theme switch (dark mode) only touches semantics. A component redesign only touches component tokens.
+
+---
+
+## File Organization
+
+```
+tokens/
+├── primitives.css    # --color-X-raw, --space-N, --font-size-X
+├── semantic.css      # --color-bg, --color-ink, --spacing-section
+├── components.css    # --btn-*, --input-*, --card-*
+└── index.css         # @import all three
+
+/* Or single file with layer comments */
+/* === PRIMITIVES === */
+/* === SEMANTIC === */
+/* === COMPONENTS === */
+/* === DARK MODE === */
+```
+
+---
+
+## Token Validation Rules
+
+During `extract` and `document` workflows, flag:
+- Raw hex or rgb() in component CSS — should be a token reference
+- Repeated identical raw values — extract to primitive
+- Semantic names that embed color names (`--color-blue-button`) — semantic names should describe role, not value
+- Component tokens bypassing the semantic layer — breaks theming

package/.claude/skills/monodesign/reference/typeset.md

@@ -0,0 +1,124 @@
+Typography carries most of the information on the page. Replace generic defaults (Inter, Roboto, system fallback at flat scale) with type that reflects the brand and scales with intentional contrast.
+
+---
+
+## Register
+
+Brand: run the font selection procedure in [brand.md](brand.md). Pairing follows the brand's lane (display serif + sans body for editorial/luxury, one committed sans for tech, etc.). Fluid `clamp()` scale, ≥1.25 ratio between steps.
+
+Product: system fonts and familiar sans stacks are legitimate here. One well-tuned family typically carries the whole UI. Fixed `rem` scale, 1.125–1.2 ratio between more closely-spaced steps.
+
+---
+
+## Assess Current Typography
+
+Analyze what's weak or generic about the current type:
+
+1. **Font choices**:
+   - Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
+   - Does the font match the brand personality? (A playful brand shouldn't use a corporate typeface)
+   - Are there too many font families? (More than 2-3 is almost always a mess)
+
+2. **Hierarchy**:
+   - Can you tell headings from body from captions at a glance?
+   - Are font sizes too close together? (14px, 15px, 16px = muddy hierarchy)
+   - Are weight contrasts strong enough? (Medium vs Regular is barely visible)
+
+3. **Sizing & scale**:
+   - Is there a consistent type scale, or are sizes arbitrary?
+   - Does body text meet minimum readability? (16px+)
+   - Is the sizing strategy appropriate for the context? (Fixed `rem` scales for app UIs; fluid `clamp()` for marketing/content page headings)
+
+4. **Readability**:
+   - Are line lengths comfortable? (45-75 characters ideal)
+   - Is line-height appropriate for the font and context?
+   - Is there enough contrast between text and background?
+
+5. **Consistency**:
+   - Are the same elements styled the same way throughout?
+   - Are font weights used consistently? (Not bold in one section, semibold in another for the same role)
+   - Is letter-spacing intentional or default everywhere?
+
+**CRITICAL**: The goal isn't to make text "fancier." It's to make it clearer, more readable, and more intentional. Good typography is invisible; bad typography is distracting.
+
+## Plan Typography Improvements
+
+Consult the [typography reference](typography.md) for detailed guidance on scales, pairing, and loading strategies.
+
+Create a systematic plan:
+
+- **Font selection**: Do fonts need replacing? What fits the brand/context?
+- **Type scale**: Establish a modular scale (e.g., 1.25 ratio) with clear hierarchy
+- **Weight strategy**: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings, or whatever fits)
+- **Spacing**: Line-heights, letter-spacing, and margins between typographic elements
+
+## Improve Typography Systematically
+
+### Font Selection
+
+If fonts need replacing:
+- Choose fonts that reflect the brand personality
+- Pair with genuine contrast (serif + sans, geometric + humanist), or use a single family in multiple weights
+- Ensure web font loading doesn't cause layout shift (`font-display: swap`, metric-matched fallbacks)
+
+### Establish Hierarchy
+
+Build a clear type scale:
+- **5 sizes cover most needs**: caption, secondary, body, subheading, heading
+- **Use a consistent ratio** between levels (1.25, 1.333, or 1.5)
+- **Combine dimensions**: Size + weight + color + space for strong hierarchy. Don't rely on size alone
+- **App UIs**: Use a fixed `rem`-based type scale, optionally adjusted at 1-2 breakpoints. Fluid sizing undermines the spatial predictability that dense, container-based layouts need
+- **Marketing / content pages**: Use fluid sizing via `clamp(min, preferred, max)` for headings and display text. Keep body text fixed
+
+### Fix Readability
+
+- Set `max-width` on text containers using `ch` units (`max-width: 65ch`)
+- Adjust line-height per context: tighter for headings (1.1-1.2), looser for body (1.5-1.7)
+- Increase line-height slightly for light-on-dark text
+- Ensure body text is at least 16px / 1rem
+
+### Refine Details
+
+- Use `tabular-nums` for data tables and numbers that should align
+- Apply proper `letter-spacing`: slightly open for small caps and uppercase, default or tight for large display text
+- Use semantic token names (`--text-body`, `--text-heading`), not value names (`--font-16`)
+- Set `font-kerning: normal` and consider OpenType features where appropriate
+
+### Weight Consistency
+
+- Define clear roles for each weight and stick to them
+- Don't use more than 3-4 weights (Regular, Medium, Semibold, Bold is plenty)
+- Load only the weights you actually use (each weight adds to page load)
+
+**NEVER**:
+- Use more than 2-3 font families
+- Pick sizes arbitrarily; commit to a scale
+- Set body text below 16px
+- Use decorative/display fonts for body text
+- Disable browser zoom (`user-scalable=no`)
+- Use `px` for font sizes; use `rem` to respect user settings
+- Default to Inter/Roboto/Open Sans when personality matters
+- Pair fonts that are similar but not identical (two geometric sans-serifs)
+
+## Verify Typography Improvements
+
+- **Hierarchy**: Can you identify heading vs body vs caption instantly?
+- **Readability**: Is body text comfortable to read in long passages?
+- **Consistency**: Are same-role elements styled identically throughout?
+- **Personality**: Does the typography reflect the brand?
+- **Performance**: Are web fonts loading efficiently without layout shift?
+- **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
+
+When the type carries the hierarchy on its own, hand off to `/monodesign polish` for the final pass.
+
+## Live-mode signature params
+
+Each variant MUST declare a `scale` param controlling the hierarchy ratio. Express all font sizes in the variant's scoped CSS through `calc(var(--p-scale, 1) * <base>)` or, better, scale the type ramp via `clamp(min, calc(var(--p-scale, 1) * Npx), max)`. Users slide from subdued to commanding.
+
+```json
+{"id":"scale","kind":"range","min":0.85,"max":1.3,"step":0.05,"default":1,"label":"Scale"}
+```
+
+Where the variant riffs on a specific pairing, expose the pairing choice as a `steps` param (e.g. "serif display + sans body" vs. "mono display + sans body" vs. "all-sans"). Each branch routes through `:scope[data-p-pairing="X"]` selectors in scoped CSS.
+
+See `reference/live.md` for the full params contract.

package/.claude/skills/monodesign/reference/typography.md

@@ -0,0 +1,159 @@
+# Typography
+
+## Classic Typography Principles
+
+### Vertical Rhythm
+
+Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony; text and space share a mathematical foundation.
+
+### Modular Scale & Hierarchy
+
+The common mistake: too many font sizes that are too close together (14px, 15px, 16px, 18px...). This creates muddy hierarchy.
+
+**Use fewer sizes with more contrast.** A 5-size system covers most needs:
+
+| Role | Typical Ratio | Use Case |
+|------|---------------|----------|
+| xs | 0.75rem | Captions, legal |
+| sm | 0.875rem | Secondary UI, metadata |
+| base | 1rem | Body text |
+| lg | 1.25-1.5rem | Subheadings, lead text |
+| xl+ | 2-4rem | Headlines, hero text |
+
+Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.
+
+### Readability & Measure
+
+Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length: narrow columns need tighter leading, wide columns need more.
+
+**Non-obvious**: Light text on dark backgrounds needs compensation on three axes, not just one. Bump line-height by 0.05–0.1, add a touch of letter-spacing (0.01–0.02em), and optionally step the body weight up one notch (regular → medium). The perceived weight drops across all three; fix all three.
+
+**Paragraph rhythm**: Pick either space between paragraphs OR first-line indentation. Never both. Digital usually wants space; editorial/long-form can justify indent-only.
+
+## Font Selection & Pairing
+
+The tactical selection procedure and the reflex-reject list live in [reference/brand.md](brand.md) under **Font selection procedure** and **Reflex-reject list** (loaded for brand-register tasks). The rest of this section covers the adjacent knowledge: anti-reflex corrections, system font use, and pairing rules.
+
+### Anti-reflexes worth defending against
+
+- A technical/utilitarian brief does NOT need a serif "for warmth." Most tech tools should look like tech tools.
+- An editorial/premium brief does NOT need the same expressive serif everyone is using right now. Premium can be Swiss-modern, can be neo-grotesque, can be a literal monospace, can be a quiet humanist sans.
+- A children's product does NOT need a rounded display font. Kids' books use real type.
+- A "modern" brief does NOT need a geometric sans. The most modern thing you can do is not use the font everyone else is using.
+
+**System fonts are underrated**: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` looks native, loads instantly, and is highly readable. Consider this for apps where performance > personality.
+
+### Pairing Principles
+
+**The non-obvious truth**: You often don't need a second font. One well-chosen font family in multiple weights creates cleaner hierarchy than two competing typefaces. Only add a second font when you need genuine contrast (e.g., display headlines + body serif).
+
+When pairing, contrast on multiple axes:
+- Serif + Sans (structure contrast)
+- Geometric + Humanist (personality contrast)
+- Condensed display + Wide body (proportion contrast)
+
+**Never pair fonts that are similar but not identical** (e.g., two geometric sans-serifs). They create visual tension without clear hierarchy.
+
+### Web Font Loading
+
+The layout shift problem: fonts load late, text reflows, and users see content jump. Here's the fix:
+
+```css
+/* 1. Use font-display: swap for visibility */
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2') format('woff2');
+  font-display: swap;
+}
+
+/* 2. Match fallback metrics to minimize shift */
+@font-face {
+  font-family: 'CustomFont-Fallback';
+  src: local('Arial');
+  size-adjust: 105%;        /* Scale to match x-height */
+  ascent-override: 90%;     /* Match ascender height */
+  descent-override: 20%;    /* Match descender depth */
+  line-gap-override: 10%;   /* Match line spacing */
+}
+
+body {
+  font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
+}
+```
+
+Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these overrides automatically.
+
+**`swap` vs `optional`**: `swap` shows fallback text immediately and FOUT-swaps when the web font arrives. `optional` uses the fallback if the web font misses a small load budget (~100ms) and avoids the shift entirely. Pick `optional` when zero layout shift matters more than seeing the branded font on slow networks.
+
+**Preload the critical weight only**: typically the regular-weight body font used above the fold. Preloading every weight costs more bandwidth than it saves.
+
+**Variable fonts for 3+ weights or styles**: a single variable font file is usually smaller than three static weight files, gives fractional weight control, and pairs well with `font-optical-sizing: auto`. For 1–2 weights, static is fine.
+
+## Modern Web Typography
+
+### Fluid Type
+
+Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport. The middle value (e.g., `5vw + 1rem`) controls scaling rate (higher vw = faster scaling). Add a rem offset so it doesn't collapse to 0 on small screens.
+
+**Use fluid type for**: Headings and display text on marketing/content pages where text dominates the layout and needs to breathe across viewport sizes.
+
+**Use fixed `rem` scales for**: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI; fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.
+
+**Bound your clamp()**: keep `max-size ≤ ~2.5 × min-size`. Wider ratios break the browser's zoom and reflow behaviour and make large viewports feel like the page is shouting.
+
+**Scale container width and font-size together** so effective character measure stays in the 45–75ch band at every viewport. A heading that widens faster than its container drifts out of the comfortable measure at the top end.
+
+### OpenType Features
+
+Most developers don't know these exist. Use them for polish:
+
+```css
+/* Tabular numbers for data alignment */
+.data-table { font-variant-numeric: tabular-nums; }
+
+/* Proper fractions */
+.recipe-amount { font-variant-numeric: diagonal-fractions; }
+
+/* Small caps for abbreviations */
+abbr { font-variant-caps: all-small-caps; }
+
+/* Disable ligatures in code */
+code { font-variant-ligatures: none; }
+
+/* Enable kerning (usually on by default, but be explicit) */
+body { font-kerning: normal; }
+```
+
+Check what features your font supports at [Wakamai Fondue](https://wakamaifondue.com/).
+
+### Rendering polish
+
+```css
+/* Even out heading line lengths (browser picks better break points) */
+h1, h2, h3 { text-wrap: balance; }
+
+/* Reduce orphans and ragged endings in long prose */
+article p { text-wrap: pretty; }
+
+/* Variable fonts: pick the right optical-size master automatically */
+body { font-optical-sizing: auto; }
+```
+
+**ALL-CAPS tracking**: capitals sit too close at default spacing. Add 5–12% letter-spacing (`letter-spacing: 0.05em` to `0.12em`) to short all-caps labels, eyebrows, and small headings. Real small caps (via `font-variant-caps`) need the same treatment, slightly gentler.
+
+## Typography System Architecture
+
+Name tokens semantically (`--text-body`, `--text-heading`), not by value (`--font-size-16`). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.
+
+## Accessibility Considerations
+
+Beyond contrast ratios (which are well-documented), consider:
+
+- **Never disable zoom**: `user-scalable=no` breaks accessibility. If your layout breaks at 200% zoom, fix the layout.
+- **Use rem/em for font sizes**: This respects user browser settings. Never `px` for body text.
+- **Minimum 16px body text**: Smaller than this strains eyes and fails WCAG on mobile.
+- **Adequate touch targets**: Text links need padding or line-height that creates 44px+ tap targets.
+
+---
+
+**Avoid**: More than 2-3 font families per project. Skipping fallback font definitions. Ignoring font loading performance (FOUT/FOIT). Using decorative fonts for body text.