saglitzdesign-mcp 0.3.1

package/knowledge/components/cards-lists-modals.md

@@ -0,0 +1,63 @@
+---
+id: cards-lists-modals
+title: "Cards, Lists, Modals & Sheets — Design Guide"
+category: component
+platform: both
+tags: [cards, lists, modals, bottom-sheets, tables, empty-states]
+sources: ["https://m3.material.io/components/cards", "https://developer.apple.com/design/human-interface-guidelines/sheets", "https://www.nngroup.com/articles/cards-component/"]
+updated: 2026-07-08
+---
+
+# Cards, Lists, Modals & Sheets
+
+## Cards
+
+- A card = one self-contained object with one primary destination. If the whole card is tappable, make the whole card the link (stretched link) and don't nest competing tap targets except explicit secondary actions (⋯ menu, like).
+- Internal padding 16–24px; consistent radius (12–16px modern default); either a subtle border **or** a soft shadow — pick one system-wide (borders read better in dark mode; shadows on light).
+- Card grids: equal heights per row; clamp titles/descriptions (2–3 lines) instead of letting content dictate ragged heights.
+- Don't card everything: cards separate heterogeneous objects. Homogeneous, scannable data belongs in lists or tables — card-grids of identical rows waste 40%+ of space.
+
+## Lists (mobile)
+
+- Row anatomy: leading visual (icon/avatar) → title + optional 1-line subtitle → trailing meta/chevron/control.
+- Row height: 44–56px single-line, 64–72px two-line; full-bleed divider or 16px-inset divider — consistent.
+- Chevron (›) only when the row navigates; a control (switch) and navigation never share a row.
+- Swipe actions: max 2 per side, destructive full-swipe requires confirm or undo; always provide a non-gesture alternative (edit mode, ⋯ menu).
+- Infinite lists: skeleton rows on first load, spinner row on pagination, pull-to-refresh where content updates; preserve scroll position on back-navigation.
+
+## Tables (web)
+
+- Left-align text, right-align numbers, align headers with their column data.
+- Row hover highlight + entire-row click when rows navigate; sticky header past one viewport; sortable columns show direction arrow.
+- Responsive: priority columns + horizontal scroll inside the table container, or collapse to cards below ~640px. Never let the page itself scroll horizontally.
+
+## Modals (dialogs)
+
+- Use a modal only for: confirmations of destructive/irreversible actions, short focused tasks (≤1 screen of content), required decisions. Everything else: inline, page, or drawer.
+- Anatomy: title (states the decision), body (consequence), actions right-aligned — primary right, cancel as text/ghost left of it.
+- Width 400–560px for confirmations; never nest modals; dim backdrop (~40–60% black); clicking backdrop closes non-destructive modals, Escape always closes.
+- Focus management: trap focus inside, focus first meaningful element on open, return focus to the trigger on close. `role="dialog"` + `aria-modal="true"` + labelled title.
+- Destructive confirms: name the object and consequence ("Delete 'Q3 Report'? This can't be undone."), destructive button in red, never make destructive the default-focused action.
+
+## Bottom sheets (mobile)
+
+- Default mobile container for filters, pickers, share, secondary tasks — thumb-reachable, keeps context visible.
+- Grabber handle at top; detents (medium/large) for progressive content; drag-down and scrim-tap to dismiss; content scrolls only when expanded to full detent.
+- Non-modal sheets (e.g., music mini-player, maps) may persist; modal sheets must block and dim.
+
+## Empty states
+
+Every list/collection needs a designed empty state with three parts:
+1. **What this is** (one line, human tone, optional lightweight illustration/icon)
+2. **Why it's empty / what value it will hold**
+3. **A CTA to fill it** ("Create your first project")
+
+Distinguish: first-use empty (educate + CTA), cleared/zero state (positive confirmation — "All caught up"), no-search-results (show the query, offer to clear/adjust filters), error state (apologize, explain, retry).
+
+## Anti-patterns
+
+- Modal-on-load (newsletter popups before content is read), modals for content that should be pages (no URL).
+- Cards inside cards; shadows on shadows.
+- Lists where every row opens a modal instead of a detail view.
+- Empty screens that are literally blank or show a spinner forever.
+- Bottom sheets that open at full-screen height for two options.

package/knowledge/components/forms-inputs.md

@@ -0,0 +1,61 @@
+---
+id: forms-inputs
+title: "Forms & Inputs — Design Guide"
+category: component
+platform: both
+tags: [forms, inputs, validation, labels, mobile-keyboard]
+sources: ["https://www.nngroup.com/articles/form-design-white-space/", "https://m3.material.io/components/text-fields", "https://developer.apple.com/design/human-interface-guidelines/text-fields"]
+updated: 2026-07-08
+---
+
+# Forms & Inputs — Design Guide
+
+Forms are where products lose users. Every field must earn its place.
+
+## Structure
+
+- **Single column always** (multi-column forms cause skipped fields and eye-path zigzag). Exception: tightly-related pairs (First/Last name, City/ZIP, MM/YY + CVC).
+- Order fields easiest → hardest; ask for sensitive data (phone, payment) last.
+- Group related fields with headings and 24–32px group spacing; 16–24px between fields.
+- Cut every field you can derive, default, or postpone. Each removed field measurably raises completion.
+- Long forms: split into steps (wizard) with a progress indicator; 3–6 fields per step beats one 20-field page.
+
+## Labels & placeholders
+
+- **Always visible labels above the field** (not placeholder-as-label — it vanishes on focus, kills recall, fails accessibility).
+- Floating labels (Material filled/outlined fields) are acceptable; top-aligned static labels test fastest.
+- Placeholders only for format examples ("name@company.com"), in muted color, never required info.
+- Mark **optional** fields ("Optional" suffix) rather than starring required ones when most fields are required.
+- Label ↔ input programmatic association is mandatory (`<label for>`, `aria-labelledby`).
+
+## Input ergonomics
+
+- Input height: 44–56px mobile, 40–48px desktop; text ≥16px on mobile (prevents iOS zoom-on-focus).
+- Use correct types/attributes: `type="email|tel|url|number"`, `inputmode`, `autocomplete` (huge mobile win: `autocomplete="email"`, `"one-time-code"`, `"cc-number"`…).
+- Show the right mobile keyboard per field; never force numeric entry on a text keyboard.
+- Support paste everywhere, especially OTP and password fields.
+- Password fields: show/hide toggle; show requirements up front as a live checklist, not after failure.
+
+## Validation
+
+- **Validate on blur (or on submit), never on every keystroke while the user is still typing** — except live-positive confirmation (username availability, password checklist).
+- "Reward early, punish late": once a field was marked invalid, re-validate on each keystroke so the error clears immediately when fixed.
+- Error messages: below the field, red text + icon (not color alone), specific and actionable — "Enter a valid email like name@domain.com", never "Invalid input".
+- On submit with errors: scroll/focus to the first error; summarize count for screen readers (`aria-live`).
+- Never clear the form on error. Never.
+
+## Selection controls
+
+- ≤5 mutually-exclusive options: radio group / segmented control. 6+: select/dropdown or searchable combobox.
+- Multi-select ≤7: checkboxes; more: multi-select combobox with chips.
+- Toggles/switches: only for instant-effect settings (no Save button); checkboxes for form consent/choices requiring submit.
+- Date input: use platform date pickers on mobile; on web allow typed entry alongside the picker.
+
+## Anti-patterns
+
+- Placeholder-only labels; ALL-CAPS labels; centered-text inputs.
+- Resetting scroll or clearing fields after a validation error.
+- Disabling paste in password/OTP fields.
+- Dropdowns for 2–4 options, or for well-known sets better typed (country of residence when most users are one country — default it).
+- Inline "success" checkmarks on every trivially-valid field (noise).
+- CAPTCHAs before any user investment; put friction after intent is shown.

package/knowledge/components/navigation.md

@@ -0,0 +1,54 @@
+---
+id: navigation
+title: "Navigation Patterns — Mobile & Web"
+category: component
+platform: both
+tags: [navigation, tab-bar, sidebar, navbar, information-architecture]
+sources: ["https://m3.material.io/components/navigation-bar", "https://developer.apple.com/design/human-interface-guidelines/tab-bars", "https://www.nngroup.com/articles/mobile-navigation-patterns/"]
+updated: 2026-07-08
+---
+
+# Navigation Patterns — Mobile & Web
+
+Navigation is the user's mental model of your product. If they can't predict where things live, nothing else matters.
+
+## Mobile app navigation
+
+- **Bottom tab bar = default for 3–5 top-level destinations.** More than 5 → rethink IA, don't add a "More" dump unless unavoidable.
+- Tabs: icon + label always (icon-only tabs test poorly); active state with filled icon + accent color; never hide the tab bar on core screens (hiding on scroll is acceptable for immersive content).
+- Center tab as primary-action FAB (create/post) works when creation is the core loop (Instagram, X).
+- Hamburger menus on mobile apps: last resort — hides features, drops engagement. Acceptable for secondary/settings content behind a profile tab instead.
+- Hierarchical push navigation (iOS): back button top-left + swipe-back gesture must always work; label the back button with the previous screen when space allows.
+- Modality: sheets/modals for tasks that complete or cancel (compose, filters); push for drill-down browsing. Don't stack modals.
+- Tab state: each tab keeps its own navigation stack; switching tabs preserves position; re-tapping active tab scrolls to top / pops to root.
+
+## Web navigation (marketing sites)
+
+- Top navbar: logo left (links home), 4–7 items, primary CTA button right, distinct from nav links.
+- Dropdown/mega menus: open on click (hover-open menus are error-prone and unusable on touch); one level deep.
+- Sticky header: shrink on scroll (≤64px); never consume >10% of viewport height.
+- Mobile web: hamburger acceptable; full-screen overlay menu with large targets, CTA repeated inside.
+- Footer = secondary sitemap: group links under clear headings; legal + social at bottom.
+
+## Web app navigation (dashboards/SaaS)
+
+- Left sidebar = default for 6+ destinations; collapsible to icon rail; group with section labels after ~7 items.
+- Persistent global elements: search (⌘K command palette is now expected in pro tools), account menu, notifications.
+- Breadcrumbs for hierarchies ≥3 levels deep; current page is plain text, not a link.
+- Active state must be unmistakable: accent bar/fill + bolded label, not color alone.
+
+## Cross-cutting rules
+
+- Current location must always be visible (active tab, highlighted item, breadcrumb, page title).
+- Navigation labels: nouns, 1–2 words, front-loaded keywords, no jargon or cleverness ("Pricing", not "Investment").
+- URLs (web): navigation state should be linkable/back-button-safe — filters, tabs, and pagination belong in the URL.
+- Keyboard: full tab-order coverage, skip-to-content link, arrow-key support within menus, Escape closes overlays.
+- Touch: nav targets ≥44px; hit areas larger than the visible icon.
+
+## Anti-patterns
+
+- Icon-only navigation without labels (except universally-known: search, settings — and even then, tooltip/aria-label).
+- Mixing patterns: tab bar + hamburger + FAB all competing.
+- Scroll-jacking, auto-playing carousels as navigation, hover-only disclosure on touch devices.
+- Hiding primary navigation behind gestures with no visible affordance.
+- Deep nesting (>3 levels) in mobile IA — flatten with hubs or search.

package/knowledge/craft/design-critique-scoring.md

@@ -0,0 +1,237 @@
+---
+id: design-critique-scoring
+title: "Design Critique & Scoring — How Experts Judge Quality"
+category: craft
+platform: both
+tags: [critique, heuristics, scoring, delight, brand, motion]
+sources: ["impeccable design skill (local)"]
+updated: 2026-07-08
+---
+
+# Design Critique & Scoring — How Experts Judge Quality
+
+A rigorous critique is scored, prioritized, specific, and honest. Vague feedback wastes everyone's time; "consider exploring…" is banned language. This file gives the rubric, the report structure, and the judgment calls (delight vs restraint, brand expression) that separate a design director's review from a checklist run.
+
+## The scoring rubric: Nielsen's 10, scored 0–4
+
+Score each heuristic 0–4. **Be honest: a 4 means genuinely excellent, not "good enough." Most real interfaces score 20–32 total.**
+
+### 1. Visibility of system status
+
+Check for: loading indicators on async operations, confirmation of actions (save/submit/delete), progress on multi-step processes, current-location cues (breadcrumbs, active states), inline validation feedback.
+
+| Score | Criteria |
+|---|---|
+| 0 | No feedback; user is guessing what happened |
+| 1 | Rare feedback; most actions produce no visible response |
+| 2 | Partial; some states communicated, major gaps remain |
+| 3 | Good; most operations give clear feedback, minor gaps |
+| 4 | Every action confirms; progress is always visible |
+
+### 2. Match between system and real world
+
+Check for: familiar terminology (no unexplained jargon), information in the order users expect, recognizable icons/metaphors, audience-appropriate domain language, natural reading flow.
+
+| Score | Criteria |
+|---|---|
+| 0 | Pure tech jargon, alien to users |
+| 1 | Mostly confusing; requires domain expertise to navigate |
+| 2 | Mixed; some plain language, jargon leaks through |
+| 3 | Mostly natural; occasional term needs context |
+| 4 | Speaks the user's language fluently throughout |
+
+### 3. User control and freedom
+
+Check for: undo/redo, cancel on forms and modals, clear paths back to safety, easy clearing of filters/search/selections, escape from multi-step processes.
+
+| Score | Criteria |
+|---|---|
+| 0 | Users get trapped; no way out without refreshing |
+| 1 | Difficult exits; obscure paths to escape |
+| 2 | Main flows have escape, edge cases don't |
+| 3 | Users can exit and undo most actions |
+| 4 | Undo, cancel, back, and escape everywhere |
+
+### 4. Consistency and standards
+
+Check for: one term per concept, same action = same result everywhere, platform conventions followed, visual consistency (color/type/spacing/components), same gesture = same behavior.
+
+| Score | Criteria |
+|---|---|
+| 0 | Feels like different products stitched together |
+| 1 | Many inconsistencies; similar things look/behave differently |
+| 2 | Main flows match, details diverge |
+| 3 | Mostly consistent; occasional harmless deviation |
+| 4 | Cohesive system, fully predictable behavior |
+
+### 5. Error prevention
+
+Check for: confirmation before destructive actions, constraints preventing invalid input (pickers, dropdowns), smart defaults, labels that prevent misunderstanding, autosave and draft recovery.
+
+| Score | Criteria |
+|---|---|
+| 0 | Errors easy to make; no guardrails anywhere |
+| 1 | Few safeguards; some inputs validated, most aren't |
+| 2 | Common errors caught, edge cases slip |
+| 3 | Most error paths blocked proactively |
+| 4 | Errors nearly impossible through smart constraints |
+
+### 6. Recognition rather than recall
+
+Check for: visible options (not buried menus), contextual help (tooltips, inline hints), recents and history, autocomplete/suggestions, labels on icons (no icon-only navigation).
+
+| Score | Criteria |
+|---|---|
+| 0 | Heavy memorization; users must remember paths and commands |
+| 1 | Mostly recall; many hidden features, few visible cues |
+| 2 | Main actions visible, secondary features hidden |
+| 3 | Most things discoverable, few memory demands |
+| 4 | Everything discoverable; users never memorize |
+
+### 7. Flexibility and efficiency of use
+
+Check for: keyboard shortcuts for common actions, customization, recents and favorites, bulk/batch actions, power features that don't complicate the basics.
+
+| Score | Criteria |
+|---|---|
+| 0 | One rigid path; no shortcuts or alternatives |
+| 1 | Limited flexibility; few alternatives to the main path |
+| 2 | Basic keyboard support, limited bulk actions |
+| 3 | Keyboard nav, some customization |
+| 4 | Multiple paths, power features, customizable |
+
+### 8. Aesthetic and minimalist design
+
+Check for: only necessary information per step, hierarchy that directs attention, purposeful color and emphasis, no decorative clutter competing for attention.
+
+| Score | Criteria |
+|---|---|
+| 0 | Overwhelming; everything competes equally |
+| 1 | Cluttered; hard to find what matters |
+| 2 | Main content clear, periphery noisy |
+| 3 | Focused design, minor visual noise |
+| 4 | Every element earns its pixel |
+
+### 9. Error recognition, diagnosis, and recovery
+
+Check for: plain-language errors (no codes), specific problem named ("Email is missing @" not "Invalid input"), actionable recovery, errors near their source, form contents preserved.
+
+| Score | Criteria |
+|---|---|
+| 0 | Cryptic errors: codes, jargon, or silence |
+| 1 | Vague "Something went wrong" with no guidance |
+| 2 | Names the problem but not the fix |
+| 3 | Identifies problem and offers next steps |
+| 4 | Pinpoints issue, suggests fix, preserves user work |
+
+### 10. Help and documentation
+
+Check for: searchable help, contextual help (tooltips, inline hints, tours), task-focused organization (not feature-organized), concise scannable content, access without leaving context.
+
+| Score | Criteria |
+|---|---|
+| 0 | No help available anywhere |
+| 1 | Help exists but hard to find or irrelevant |
+| 2 | FAQ/docs exist, not contextual |
+| 3 | Searchable, mostly task-focused |
+| 4 | Right info at the right moment, in context |
+
+### Total score bands (out of 40)
+
+| Range | Rating | Meaning |
+|---|---|---|
+| 36–40 | Excellent | Minor polish only; ship it |
+| 28–35 | Good | Solid foundation; address weak areas |
+| 20–27 | Acceptable | Significant improvement needed before users are happy |
+| 12–19 | Poor | Major UX overhaul; core experience broken |
+| 0–11 | Critical | Redesign; unusable as-is |
+
+## Issue severity: P0–P3
+
+Tag every individual finding:
+
+| Priority | Name | Definition | Action |
+|---|---|---|---|
+| P0 | Blocking | Prevents task completion entirely | Fix immediately |
+| P1 | Major | Significant difficulty or confusion | Fix before release |
+| P2 | Minor | Annoyance with a workaround | Fix next pass |
+| P3 | Polish | Nice-to-fix, no real user impact | If time permits |
+
+**Tie-breaker:** "Would a user contact support about this?" If yes, it's at least P1.
+
+## Critique method
+
+- **Run two independent assessments** and keep them isolated until synthesis: (A) a design review with fresh eyes, (B) mechanical/automated checks (linters, detectors, browser evidence). Automated output must not anchor the design judgment — finish A before reading B. Then weave, don't concatenate: note where they agree, what the machine caught that the eye missed, and which machine findings are false positives.
+- **Evaluate on screen, not just in source.** Viewable targets require actual visual inspection at multiple viewports.
+- Automated results are **defect evidence only** — a clean scan is never proof the design is good.
+
+### Report structure (in this order)
+
+1. **Design health score** — the 10-heuristic table with per-row key issue, total /40, and rating band.
+2. **Anti-patterns verdict first** — the opening question: *would someone say "AI made this" without hesitation?* Cover layout sameness, generic composition, template tells, missed personality.
+3. **Overall impression** — brief gut reaction and the single biggest opportunity.
+4. **What's working** — 2–3 genuine strengths and *why* they work (credibility requires acknowledging strengths specifically).
+5. **Priority issues** — 3–5 max, ordered by impact, each with: **[P?] What** (named clearly) · **Why it matters** (harm to users/goals) · **Fix** (concrete, actionable).
+6. **Persona red flags** — walk 2–3 relevant user archetypes (e.g. power user, first-timer) through the primary action and name exactly what breaks for each: "No keyboard shortcuts; primary action takes 8 clicks" — never generic persona prose.
+7. **Minor observations** — quick smaller notes.
+8. **Questions to consider** — provocations that unlock better solutions: "What if the primary action were more prominent?" "Does this need to feel this complex?" "What would a confident version look like?"
+
+### Critique voice rules
+
+- Be direct; don't soften criticism — honest feedback ships great design.
+- Be specific: "the submit button," never "some elements."
+- Always pair what's wrong with why it matters to users.
+- Give concrete fixes; cut hedging language entirely.
+- Prioritize ruthlessly — if everything is important, nothing is.
+- Track score across re-critiques to show trend; don't invent defects to demonstrate iteration. "First pass clean" is a valid verdict.
+
+## Cognitive load scoring (fold into the review)
+
+Use the 8-item checklist (single focus; ≤4-item chunks; visual grouping; clear hierarchy; one decision at a time; ≤4 visible options per decision; no cross-screen memory demands; progressive disclosure). **0–1 failures = low load · 2–3 = moderate · 4+ = critical.** Flag every decision point with >4 simultaneous options. Also assess the emotional journey: peak-end rule, emotional valleys, reassurance at high-stakes moments.
+
+## Judging interaction quality
+
+- **Eight-state completeness** for every interactive element: default, hover, focus, active, disabled, loading, error, success. The common miss: hover designed without focus (keyboard users never see hover).
+- Focus: `:focus-visible` ring 2–3px, offset, ≥3:1 contrast — `outline: none` without replacement is an automatic finding.
+- Forms: visible labels (placeholders are not labels), validate on blur, errors below fields with `aria-describedby`.
+- Destructive actions: **undo beats confirmation** — users click through confirms mindlessly. Confirmation only for irreversible/high-cost/batch operations.
+- Overlays: `position: absolute` inside `overflow: hidden` clipping is the most common generated-code dropdown bug; arbitrary z-index (9999) instead of a semantic scale is a finding.
+- Touch targets ≥44×44px; no hover-only functionality; gestures always have visible fallbacks.
+
+## Judging motion
+
+- **Durations — the 100/300/500 rule:** 100–150ms instant feedback (press, toggle) · 200–300ms state changes (menu, tooltip) · 300–500ms layout changes (modal, accordion) · 500–800ms entrances only. Anything >500ms for UI feedback is a defect. **Exits run ~75% of enter duration.**
+- **Easing:** never plain `ease`; ease-out for entrances, ease-in for exits, ease-in-out for toggles. Expressive default: ease-out-quart `cubic-bezier(0.25, 1, 0.5, 1)`. **Bounce/elastic = automatic finding** — dated and amateurish; real objects decelerate, they don't boing.
+- Stagger: ~50ms per item via `calc(var(--i) * 50ms)`, total capped (~500ms) — reduce per-item delay for long lists.
+- Materials: transform/opacity are the reliable defaults; blur/filter/mask/clip-path are legitimate premium materials **if bounded to small areas and verified smooth in-browser**. Casually animating layout properties (width/height/top/left/margins) is a finding.
+- `prefers-reduced-motion` support is **not optional** (vestibular disorders affect ~35% of adults over 40): crossfade instead of movement; keep functional indicators (progress, focus).
+- Perceived performance: <80ms feels instant; skeletons beat spinners; optimistic UI for low-stakes actions only (never payments/destructive). Motion used to hide slow loading is a finding.
+
+## Delight vs restraint — the judgment call
+
+Delight is register-dependent:
+- **Product register:** delight at specific *moments* (completion, first-time actions, error recovery, milestones), never spread across pages. Reliability carries the rest. Delight everywhere reads as noise.
+- **Brand register:** delight may be distributed — copy voice, section transitions, discovery rewards, seasonal touches.
+
+Rules for judging whether a delight moment is earned:
+- **Amplifies, never blocks:** <1 second, skippable, never delays core functionality.
+- **Context-appropriate:** celebrate success; empathize with errors (never playful during critical errors); banking ≠ gaming.
+- **Survives repetition:** still pleasant on the 100th use; varied responses beat one looping animation.
+- **Discovery beats announcement:** hidden details reward curiosity; don't fanfare every touch.
+- **Ban AI-slop delight:** cliché loading jokes ("Herding pixels…"), stock confetti on trivial actions, whimsy hiding poor UX.
+- Verdict test: if users notice the delight more than they notice completing their goal, it's overdone.
+
+## Brand expression — evaluation tests
+
+- **The slop test:** would anyone say "AI made that" without hesitation? The bar is a visitor asking "how was this made?" Average is no longer findable; restraint without intent reads as mediocre, not refined.
+- **The aesthetic-lane test:** can the designer name the lane in one reference? ("Stripe-minimal," "acid-maximalism," "Klim specimen page.") Unnamed ambition becomes beige. Also check lane *fit*: editorial-magazine styling on a non-editorial brief is the wrong register within the register.
+- **The competitor-sentence test:** describe the design in one sentence as a competitor would describe theirs. If that sentence fits the category's modal landing page, it fails.
+- **Palette commitment:** palette IS voice — a named color strategy (drench, committed accent, full palette, monochrome restraint) executed without hedging. Beige-and-muted-slate on a brand brief ignores the register.
+- **Imagery obligation:** briefs that imply imagery (restaurant, hotel, food, travel, fashion, photography, product) must ship imagery. Zero images is a bug, not restraint; colored blocks where a hero photo belongs are a P1.
+- **Brand ban list (findings when present):** monospace as "technical" costume; big rounded icons above every heading; all-caps body copy; timid palette + average layout; repeated tiny uppercase tracked labels as section grammar; editorial-serif-by-default.
+- **Brand permissions (don't penalize):** ambitious first-load choreography, one dominant idea per fold, enormous display type, unexpected color strategies, per-section art direction — when the voice demands them.
+- Product-register inverse: bold theatrics in a tool ARE the finding; amplification belongs in hierarchy clarity, weight contrast, one sharper accent.
+
+## After the critique
+
+End with prioritized, actionable direction — not a raw list. Ask 2–4 targeted questions tied to actual findings (priority direction, intent vs accident on tonal issues, scope appetite), each with concrete options. Never generic "who is your audience?" questions. Map every priority issue to a concrete next action, and re-score after fixes to make progress visible.

package/knowledge/craft/typography-craft.md

@@ -0,0 +1,177 @@
+---
+id: typography-craft
+title: "Typography Craft — Typesetting Beyond the Basics"
+category: craft
+platform: both
+tags: [typography, typesetting, fonts, hierarchy, opentype]
+sources: ["impeccable design skill (local)"]
+updated: 2026-07-08
+---
+
+# Typography Craft — Typesetting Beyond the Basics
+
+Typography carries most of the information on any screen. Good typography is invisible; bad typography is distracting. The goal is never "fancier" — it is clearer, more readable, more intentional.
+
+## Scale and hierarchy
+
+- **The classic mistake: too many sizes, too close together.** 14/15/16/18px is muddy hierarchy. Use fewer sizes with more contrast.
+- **Five sizes cover most products:**
+
+| Role | Typical size | Use |
+|---|---|---|
+| xs | 0.75rem | Captions, legal |
+| sm | 0.875rem | Secondary UI, metadata |
+| base | 1rem | Body |
+| lg | 1.25–1.5rem | Subheadings, lead text |
+| xl+ | 2–4rem | Headlines, hero |
+
+- **Commit to one ratio:** 1.25 (major third), 1.333 (perfect fourth), or 1.5 (perfect fifth).
+- **Register split:** app/product UI uses a **fixed rem scale with a tighter 1.125–1.2 ratio** (dense layouts need close steps and spatial predictability — no major app design system uses fluid type in product UI). Brand/marketing surfaces use **fluid `clamp()` headings with ≥1.25 ratio between steps**; a flat 1.1× scale reads as uncommitted.
+- **Weight roles are fixed and few:** 3–4 weights max (e.g. Regular body, Medium labels, Semibold/Bold headings). Same role = same weight everywhere. Load only the weights you use.
+- Hierarchy should combine size + weight + color + space — never size alone.
+
+## Vertical rhythm
+
+Line-height is the base unit for ALL vertical spacing. 16px body at 1.5 = 24px; vertical margins and gaps should be multiples of 24px. Text and space sharing one mathematical foundation creates subconscious harmony.
+
+## Measure and leading
+
+- **45–75 characters per line** for body; set `max-width: 65ch` on text containers (use `ch` units, not px).
+- **Leading scales inversely with measure:** narrow columns take tighter line-height, wide columns need more. Headings 1.1–1.2; body 1.5–1.7.
+- **Light-on-dark needs compensation on three axes, not one.** Light text on dark reads thinner and tighter. Fix all three: line-height +0.05–0.1, letter-spacing +0.01–0.02em, and optionally step body weight up one notch (400 → 450/500, or in reverse, use 350 instead of 400 for large light-on-dark body text since it reads heavier).
+- **Paragraph rhythm: space between paragraphs OR first-line indent. Never both.** Digital defaults to space; long-form editorial can justify indent-only.
+
+## Fluid type done right
+
+- `clamp(min, preferred, max)` with a viewport-relative middle term plus a rem offset (e.g. `clamp(2rem, 5vw + 1rem, 4rem)`) so it never collapses at small widths.
+- **Bound the ratio: max ≤ ~2.5 × min.** Wider ranges break browser zoom/reflow and make large viewports feel like shouting.
+- **Body text stays fixed even on marketing pages** — the cross-viewport size delta is too small to justify fluidity.
+- **Scale container width and font-size together** so effective measure stays in the 45–75ch band at every viewport.
+
+## Font selection — the anti-reflex procedure
+
+Run this for every brand-register project; never skip:
+
+1. Write **three concrete brand-voice words** — physical-object words ("warm, mechanical, opinionated"), not "modern" or "elegant."
+2. List the three fonts you'd reach for by reflex. If any are training-data defaults, reject them.
+3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Klim, ABC Dinamo, Velvetyne) hunting the brand as a *physical object*: a museum caption, a 1970s terminal manual, a fabric label, a concert poster. Reject the first thing that merely "looks designy."
+4. Cross-check: "elegant" is not necessarily serif; "technical" is not necessarily sans; "warm" is not automatically Fraunces. If the final pick matches the original reflex, start over.
+
+**Reflex-reject list (saturated defaults — look further for greenfield work):** Fraunces, Newsreader, Lora, Crimson (all cuts), Playfair Display, Cormorant (all cuts), Syne, IBM Plex (Mono/Sans/Serif), Space Mono, Space Grotesk, Inter, DM Sans, DM Serif (Display/Text), Outfit, Plus Jakarta Sans, Instrument Sans, Instrument Serif.
+
+**Reflex-reject aesthetic lane:** the editorial-typographic cliché — italic display serif + small tracked mono labels + ruled columns + monochrome restraint — is the second-order trap. Unless the brief is literally a magazine, skip it.
+
+These lists govern **new choices**. An existing brand identity that already ships one of these fonts wins — don't second-guess shipped identity.
+
+**Anti-reflexes worth defending against:**
+- A technical brief does NOT need a serif "for warmth" — tech tools should look like tech tools.
+- A premium brief does NOT need the trendy expressive serif; premium can be Swiss-modern, neo-grotesque, quiet humanist, even monospace.
+- A children's product does NOT need a rounded display font — kids' books use real type.
+- The most "modern" move is not using the font everyone else uses.
+- **System fonts are underrated:** `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` loads instantly and reads natively. Legitimate wherever performance > personality.
+
+## Pairing
+
+- **You usually don't need a second font.** One family in committed weights beats a timid display+body pair. Add a second only for genuine contrast.
+- When pairing, contrast on multiple axes: serif+sans (structure), geometric+humanist (personality), condensed display + wide body (proportion).
+- **Never pair similar-but-not-identical fonts** (two geometric sans) — tension without hierarchy.
+- Lane conventions: editorial/luxury → display serif + sans body; tech/fintech → one committed sans with tight tracking and strong internal weight contrast; consumer/food/travel → humanist sans + script or display serif; studios/agencies → rule-breaking (mono-only, display-only) is welcome.
+- Hard ceiling: 2–3 families per project.
+
+## Web font loading
+
+- `font-display: swap` for visibility; **`optional`** when zero layout shift matters more than showing the branded font on slow networks (falls back if the font misses a ~100ms budget).
+- **Metric-matched fallback** kills the reflow jump — define a fallback `@font-face` over a local font with metric overrides (tools like Fontaine compute these automatically):
+
+```css
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2') format('woff2');
+  font-display: swap;
+}
+@font-face {
+  font-family: 'CustomFont-Fallback';
+  src: local('Arial');
+  size-adjust: 105%;        /* scale to match x-height */
+  ascent-override: 90%;
+  descent-override: 20%;
+  line-gap-override: 10%;
+}
+body { font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif; }
+```
+
+- **Preload only the critical weight** — usually the regular body weight above the fold. Preloading everything costs more than it saves.
+- **Variable font when you need 3+ weights/styles**: one file is smaller than three statics, gives fractional weights, and pairs with `font-optical-sizing: auto`. For 1–2 weights, static files are fine.
+
+## OpenType features and rendering polish
+
+Most developers don't know these exist — using them is a visible craft signal:
+
+```css
+.data-table   { font-variant-numeric: tabular-nums; }   /* numbers align in columns */
+.fraction     { font-variant-numeric: diagonal-fractions; }
+abbr          { font-variant-caps: all-small-caps; }     /* real small caps for abbreviations */
+code          { font-variant-ligatures: none; }          /* ligatures off in code */
+body          { font-kerning: normal; font-optical-sizing: auto; }
+h1, h2, h3    { text-wrap: balance; }                    /* even heading line lengths */
+article p     { text-wrap: pretty; }                     /* fewer orphans in prose */
+```
+
+- **ALL-CAPS tracking is mandatory:** capitals sit too tight at default spacing. Add 5–12% letter-spacing (`0.05em`–`0.12em`) to all-caps labels, eyebrows, small headings. Real small caps take the same treatment, slightly gentler.
+- Letter-spacing direction: open for small/uppercase text, default-or-tight for large display sizes.
+- Check a font's feature support at Wakamai Fondue before relying on it.
+
+## Widows, orphans, breaks
+
+- No single word stranded on the last line of a heading (`text-wrap: balance` handles most cases).
+- Stable line breaks at every viewport — a heading that rewraps into nonsense at one width is a defect.
+- Hyphenation only where language and column width justify it.
+
+## Token architecture
+
+Name tokens semantically — `--text-body`, `--text-heading` — never by value (`--font-size-16`). A complete type token set includes: font stacks, size scale, weights, line-heights, and letter-spacing.
+
+## Accessibility floors
+
+- **Body ≥16px / 1rem.** Smaller strains eyes and fails WCAG on mobile.
+- **Use rem/em, never px, for font sizes** — px ignores user browser settings.
+- **Never disable zoom** (`user-scalable=no`). If layout breaks at 200% zoom, fix the layout.
+- Text links need padding/line-height producing 44px+ tap targets.
+- Never decorative/display fonts for body text; never all-caps body copy (caps are for short labels and headings).
+
+## Expressive vs quiet type
+
+- **Quiet (product UI):** one well-tuned family, system stacks legitimate, fixed rem scale, hierarchy via weight and space. The type should disappear into the task.
+- **Expressive (brand):** typographic risk is a permission — enormous display sizes, unexpected italic cuts, mixed cases, a single oversize word as a hero, hand-drawn headlines. Fluid scale, ≥1.25 ratio, committed contrast.
+- **Bolder without slop:** dramatic size jumps (3–5×), extreme weight pairs (900 with 200), condensed/extended widths, monospace as a deliberate accent — never as lazy "developer" costume on a non-technical brand.
+- **Quieter without mush:** step weights down (900→600, 700→500), reduce scale jumps, add typographic air — but keep anchors. Some elements must still be unmistakably dominant.
+
+## Assessing existing typography — where to look first
+
+1. **Font choices:** invisible defaults in use (Inter, Roboto, Arial, Open Sans, bare system stack on a brand surface)? Does the face match the brand voice? More than 2–3 families?
+2. **Hierarchy:** heading vs body vs caption distinguishable at a glance? Sizes too close together? Weight contrast strong enough (Medium vs Regular is barely visible)?
+3. **Scale:** one committed ratio or arbitrary sizes? Right sizing strategy for the register (fixed rem for app UI, fluid clamp for marketing headings)?
+4. **Readability:** measure 45–75ch? Leading tuned to measure and context? Contrast sufficient?
+5. **Consistency:** same role, same treatment, everywhere? Weights used by defined role? Letter-spacing intentional rather than default-everywhere?
+
+## Hard bans
+
+- More than 2–3 font families per project
+- Arbitrary sizes off the scale; body text below 16px
+- Decorative/display fonts as body text; all-caps body copy
+- `px` font sizes; `user-scalable=no`
+- Inter/Roboto/Open Sans by default where personality matters
+- Pairing similar-but-not-identical faces (two geometric sans)
+- Skipping fallback stacks; ignoring FOUT/FOIT
+- Monospace as lazy "developer" shorthand on a non-technical brand
+
+## Typography defect checklist
+
+- [ ] Sizes come from one committed scale; no near-duplicate sizes
+- [ ] Register-appropriate sizing (fixed rem in app UI; bounded clamp on brand headings)
+- [ ] Measure 45–75ch; leading tuned per context; light-on-dark compensated on all three axes
+- [ ] Same role styled identically everywhere; ≤3–4 weights loaded
+- [ ] No FOUT jump (metric-matched fallback) and no invisible-text FOIT
+- [ ] tabular-nums on data; tracking on all-caps; balance/pretty wrapping applied
+- [ ] Body ≥16px in rem; zoom works to 200%; contrast passes WCAG
+- [ ] Font choice justifiable in one sentence of brand voice — not a reflex default