@hegemonart/get-design-done 1.14.7 → 1.15.0

package/reference/start-interview.md

@@ -0,0 +1,84 @@
+# /gdd:start — Locked 5-Question Interview
+
+**Purpose:** collect the minimum signal needed to steer the findings engine without slowing first-run completion past 30 seconds of interview wall-clock. Autodetectable dimensions collapse to a one-key confirmation; genuinely non-derivable dimensions are asked explicitly.
+
+**Hard constraint:** v1.14.7 ships this fixed question set. Do not branch, re-order, or insert new questions without an explicit `/gsd-discuss-phase` override captured in a future DISCUSSION.md.
+
+---
+
+## Q1 — Pain point *(required, free text)*
+
+**Prompt:**
+
+> What's the one design issue you'd most like to see fixed first? One line, ≤120 chars. Examples: "buttons feel jittery on hover", "colors are inconsistent across forms", "mobile nav breaks on the hero", "a11y on our modal".
+
+**Default when `--skip-interview`:** empty string (pain hint disabled; scorer runs without boost).
+
+**Validation:** max 120 chars; trim leading/trailing whitespace. No charset restrictions — the hint is free text.
+
+**Failure posture:** if the user aborts at Q1, abort the whole skill with a one-line pointer to `/gdd:scan`.
+
+---
+
+## Q2 — Target area confirmation *(autodetected, single select)*
+
+**Prompt:**
+
+> I detected your UI code at `<detected.path>` (`<detected.kind>`, confidence=`<detected.confidence>`). Use this surface? [Yes / choose another path / skip demo]
+
+**Default when `--skip-interview`:** accept detected path as-is.
+
+**Validation:** if the user picks "choose another path", ask for a repo-relative path and validate that at least one UI-extension file (.tsx/.jsx/.ts/.js/.svelte/.vue) exists inside. Re-prompt on failure. Two rejections → fall back to detected path with a warning.
+
+**Failure posture:** if the user picks "skip demo", exit clean with `## START COMPLETE` and no `.design/` footprint.
+
+---
+
+## Q3 — Budget / latency preference *(enum, default=balanced)*
+
+**Prompt:**
+
+> Report speed vs thoroughness? [fast (≤90s, tokens-only) / balanced (≤3min, default) / thorough (≤5min, includes a11y + motion checks)]
+
+**Default when `--skip-interview`:** `balanced`.
+
+**Validation:** must be one of `fast | balanced | thorough`. Any other input → re-prompt once, then default to `balanced`.
+
+**Failure posture:** n/a — this is non-blocking; defaulting is safe.
+
+---
+
+## Q4 — Framework + design-system confirmation *(autodetected, combined)*
+
+**Prompt:**
+
+> Detected framework=`<framework>`, design-system=`<design_system>`. Correct? [Yes / override framework / override design-system / skip (use detected)]
+
+**Default when `--skip-interview`:** accept both detected values.
+
+**Validation:** "override framework" → ask for a free-text label (`next | remix | vite | cra | svelte | vue | astro | solid | unknown`). "override design-system" → same, values (`tailwind | css-modules | vanilla-extract | styled | linaria | emotion | panda | unknown`). Invalid → default to `unknown`.
+
+**Failure posture:** n/a — detection output is always available even if the user skips.
+
+---
+
+## Q5 — Figma / canvas workflow *(enum, non-blocking)*
+
+**Prompt:**
+
+> Do you work with visual references? [Figma / .canvas file / neither / skip]
+
+**Default when `--skip-interview`:** `skip`.
+
+**Validation:** enum; any other → `skip`.
+
+**Effect:** result steers the `Visual Proof Readiness` section only — never gates the happy path or the findings engine. The writer uses this to decide whether to surface `/gdd:connections figma` or `.canvas` guidance.
+
+---
+
+## Do Not
+
+- Do not ask for email, org name, team size, or any identity data.
+- Do not ask more than five questions.
+- Do not branch based on Q1 content (adaptive branching is explicitly deferred per the ROADMAP).
+- Do not write STATE.md, config.json, or any source file as a side effect of the interview.

package/reference/style-vocabulary.md

@@ -0,0 +1,62 @@
+---
+name: style-vocabulary
+type: style-vocabulary
+version: 1.0.0
+source: "nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/styles.csv, data/design.csv, data/draft.csv"
+tags: [style, aesthetic, ui, vocabulary, brief]
+---
+
+# Style Vocabulary — UI Aesthetic Catalog
+
+This catalog gives two categories of agent a shared, unambiguous vocabulary for UI aesthetics.
+
+**Brief-stage (design-context-builder):** When the user names a visual direction — or when the agent infers one from brand-direction words — look up the style name here to validate that the direction is coherent with the product type (Best For / Avoid For columns) and to understand what implementation cost to surface in the constraints section (Performance column). Pre-populate the `D-02` decision line in the context file with the style name verbatim so downstream agents can pattern-match it exactly.
+
+**Audit-stage (design-auditor):** When scoring Pillar 3 (Color) and Pillar 2 (Visual Hierarchy), reference this catalog to determine whether the implemented aesthetic is internally consistent. A product that claims Glassmorphism but uses hard box-shadows scores lower on style coherence. The style name from `D-02` is the benchmark — audit against it, not against a generic checklist.
+
+Style names in this file are preserved verbatim from the UUPM source to maintain ecosystem legibility. Do not rename or abbreviate styles when writing context files or audit reports.
+
+---
+
+## Style Table
+
+| Style | Keywords | Signature Effects | Best For | Avoid For | Light/Dark | Performance | Era |
+|---|---|---|---|---|---|---|---|
+| Glassmorphism | frosted glass, translucency, blur, layered depth | backdrop-filter: blur(20px), semi-transparent cards (rgba bg at 60–80% opacity), 1px border at rgba(255,255,255,0.2), subtle inner glow | Dashboards, media apps, modern SaaS landing pages, AI/ML product surfaces | Data-dense tables, accessibility-critical flows, low-end devices, text-heavy content | Both (dark base preferred for maximum contrast) | High — backdrop-filter triggers compositor layer; avoid stacking more than 3 blur layers | 2019–present |
+| Brutalism | raw layout, stark contrast, intentional roughness, exposed grid, unconventional typography | Hard pixel borders (2–4px solid black), no border-radius or extreme (0px), flat color fills, oversized type, intentional misalignment as aesthetic choice | Creative portfolios, challenger brands, indie products, arts organizations, music artists | Healthcare, regulated finance, government, e-commerce conversion pages | Light mode primary | Lowest — no visual effects; pure CSS | 2016–present |
+| Neumorphism | extruded shadows, raised/inset UI, monochromatic, soft bilateral shadows | box-shadow: 8px 8px 16px rgba(0,0,0,0.15), -8px -8px 16px rgba(255,255,255,0.9); near-identical foreground/background hue; no hard borders | Personal finance concept dashboards, design system prototypes, high-end calculator UI | Accessibility-critical products (fails WCAG contrast in almost all implementations), mobile (touch targets unclear), production apps at scale | Light only | Low — CSS shadows only, but WCAG caution overrides implementation | 2019–2021 |
+| Flat Design 2.0 | minimal decoration, subtle shadows permitted, vibrant palette, sharp iconography | Single drop-shadow at 0 2px 4px rgba (not 0 blur), bold sans-serif, geometric icons, 8pt spacing grid, no gradients on primary surfaces | Productivity apps, documentation sites, enterprise SaaS, developer tools | Luxury/fashion (too utilitarian), entertainment (too corporate) | Both | Lowest | 2014–present |
+| Material Design 3 | dynamic color, tonal surfaces, elevation via color not shadow, M3 components | Tonal surface colors derived from wallpaper/brand seed via Material You algorithm; container/on-container token pairs; state layers at 8%/12%/16% opacity | Android-first apps, cross-platform Google-adjacent products, Material ecosystem teams | Apple HIG contexts, luxury brands, editorial-first experiences | Both | Low — relies on CSS custom properties and system fonts | 2021–present |
+| Bento Grid | card-grid layout, variable card sizes, grid gaps as design element, information hierarchy via cell size | CSS Grid with named areas; card size ranges from 1×1 to 3×2; visible grid gap (8–16px); rounded cards (radius 12–24px); subtle card shadow | Marketing landing pages, dashboard home screens, portfolio showcases, feature announcement pages | Linear narrative content, long-form reading, checkout flows | Both | Low | 2022–present |
+| AI-Native | gradient meshes, dark base, glowing accents, particle effects, flowing color | Gradient mesh backgrounds (3–5 blended color stops), subtle particle canvas overlay, glowing border via box-shadow with spread, monospace or geometric sans-serif | AI/ML products, futuristic SaaS, developer platform landing pages, inference product demos | Traditional enterprise, regulated industries, consumer packaged goods, healthcare | Dark primary | High — particle effects require canvas/WebGL; mesh gradients moderate cost | 2022–present |
+| Swiss Modernism 2.0 / International Style | strict grid, functional typography, red-black-white, structure as beauty | Baseline 12-column grid with explicit column rules; Helvetica/Neue Haas/Inter; red (#E02424) as the only accent; no imagery unless functional; type as layout element | Editorial platforms, design agencies, premium brand identities, cultural institutions | Consumer apps, gaming, children's products, anything requiring warmth | Both | Lowest | 1950–present (revival 2018–) |
+| Claymorphism | 3D inflated shapes, soft clay surfaces, pastel palette, inner shadows | border-radius: 30–50px; layered box-shadow (inner highlight + outer soft shadow); pastel fills; thick playful borders (3–4px) at lighter shade of fill | Consumer apps, children's products, lifestyle brands, wellness apps, gifting platforms | Enterprise software, data-dense apps, financial tools, anything requiring precision | Both | Medium — inner shadows and multiple box-shadow layers | 2021–present |
+| Dark Mode First | deep backgrounds, careful elevation via surface color, low-saturation palette | Background: #0A0A0A–#121212; surfaces via gray ladder (#1C1C1E, #2C2C2E, #3A3A3C); text at #F5F5F5–#EBEBF5; color desaturated 20% vs light equivalent | Developer tools, code editors, media players, gaming interfaces, creative tools | Healthcare (eye strain concern in clinical settings), high-ambient-light kiosks, point-of-sale | Dark primary | Low | 2018–present |
+| Vaporwave/Retrowave | neon gradients, dark base, grid lines, retro typography, CRT aesthetic | Hot pink to cyan gradient (#FF00FF → #00FFFF); background grid lines at low opacity; scanline overlay; pixel or VCR-style display fonts; glow effects via text-shadow | Gaming, entertainment, nostalgia brands, Gen-Z consumer products, music products | Any trust-critical vertical, healthcare, finance, government, enterprise | Dark | High — multiple glow filters, gradient overlays | 1980s aesthetic; UI revival 2016–present |
+| Editorial Grid | overlapping text and image, asymmetric layout, strong typographic hierarchy, print-inspired | Text floated over image with mix-blend-mode; column-spanning type; headline at 80–120px; print-grid column rules as decoration; serif display fonts | Media platforms, publishing, editorial brands, portfolios, cultural organizations | Functional SaaS apps, data-dense dashboards, e-commerce PDP pages | Both | Low | Print tradition; digital revival 2018–present |
+| HUD/Sci-Fi FUI | monochrome on dark, thin lines, technical readout vocabulary, blinking cursors | Background #000000–#0A0A0A; primary green or cyan (#00FF41 or #22D3EE) on black; 1px rule lines; monospace type; data table with scan-animation; corner bracket UI elements | Technology/aerospace dashboards, game UI overlays, cybersecurity monitoring, concept demos | Consumer products, any app requiring instant clarity for non-technical users | Dark | High — continuous animations, WebGL elements common | Science fiction tradition; real-world FUI since 2010 |
+| Minimal/Zen | maximum whitespace, single accent, natural textures, typography-first | 70%+ whitespace ratio; single color accent (one hue only); thin-weight serif or geometric sans; optional paper/linen texture overlay at 5% opacity; no drop shadows | Wellness apps, meditation products, luxury minimal brands, independent publications, author portfolios | Feature-dense apps, complex navigation structures, high-information-density dashboards | Both | Lowest | 2010–present |
+| Skeuomorphism 2.0 | realistic textures, modern execution, material-specific rendering | Leather, wood grain, metal surface textures rendered via CSS or SVG; specular highlight simulation; physical affordances (buttons with press state depth); material-appropriate border-radius | Premium music instruments, luxury hardware companion apps, high-end lifestyle products | Modern SaaS, productivity tools, anything with frequent UI updates (texture maintenance cost) | Both | Medium — texture assets and layered pseudo-elements | Original 2007–2013; revival/refinement 2021–present |
+| Neubrutalism | visible borders, flat colors, stark contrast, browser-default-inspired, raw energy | 2–3px solid dark border on all interactive elements; flat fill (no gradient); background colors at full saturation; hover state as color-flip (swap bg/fg); no border-radius or large radius | Indie SaaS products, creative tools, challenger brands, hackathon projects | Enterprise software, regulated industries, anything requiring perceived polish or trust | Both | Lowest | 2021–present |
+| Memphis Design Revival | geometric shapes, primary colors, patterns, 80s-inspired, maximalist decoration | Bold geometric pattern fills (triangles, squiggles, dots); primary + secondary color blocking; pattern borders; mixed type weights; controlled chaos grid | Consumer brands targeting Gen Z, playful e-commerce, lifestyle/fashion campaigns, pop culture events | Professional services, enterprise, financial products, anything requiring authority | Both | Low | 1980s origin; digital revival 2022–present |
+| Glassmorphism Dark | frosted glass on dark base, darker frost panels, subtle neon borders | backdrop-filter: blur(24px) on near-black base (#0A0A0A); card at rgba(255,255,255,0.05); neon border rgba(value from accent, 0.3); text at #F8FAFC | Gaming UI, media players, nightclub/event apps, AI product dark surfaces | Any product requiring readable body text at scale (contrast is difficult to achieve) | Dark | High — same as Glassmorphism | 2020–present |
+| Aurora/Gradient Mesh | flowing color gradients, no hard borders, dreamlike quality, organic forms | CSS mesh gradient with 4–6 color stops at 40–70% opacity; no hard-edge borders; sections dissolve into each other; type floated on gradient without hard card containers | AI/ML landing pages, creative platform hero sections, generative art tools | Data-dense apps, form-heavy flows, any context requiring clear section boundaries | Both | Medium-High — large gradient areas can trigger repaint | 2021–present |
+| Monochromatic Minimal | single hue across full lightness range, typography-first, restraint as luxury | All UI elements share one hue; lightness varies from 5% (near-black) to 97% (near-white); saturation constant; type weight provides the only contrast variation; no accent color | Portfolios, luxury brand identity systems, photography showcases, editorial | Multi-action apps, e-commerce (accent colors drive CTA attention), gaming | Both | Lowest | 2015–present |
+| Conversion-First | CTA-dominant layout, social proof integration, urgency mechanics, trust signals | Primary CTA button above fold with 100%+ width on mobile; social proof blocks within 2 scroll steps; urgency timer or scarcity counter; benefit bullets over features; sticky CTA bar on mobile | Lead-gen landing pages, SaaS trial pages, product launch pages, app store alternatives | Brand storytelling pages, editorial content, informational docs | Both | Low — minimal JS, mostly static | 2010–present |
+| Story-Scroll | parallax narrative, scroll-triggered animations, cinematic pacing | IntersectionObserver-triggered fade-in sequences; horizontal scroll segments; full-bleed imagery at each act; progress indicator; chapter-style section breaks | Brand launches, product storytelling, annual reports, agency showreels | High-conversion pages (scroll depth reduces conversion), dashboard apps, utility tools | Both | Medium-High — JavaScript animation triggers and asset loading | 2014–present |
+| Product Demo | embedded interactive preview, annotated feature callouts, tooltip overlays | Inline iframe or video demo above fold; numbered callout dots on screenshot; feature spotlight with progressive disclosure; before/after toggle; interactive hotspot map | SaaS product landing pages, browser extension pages, design tool showcases | Services businesses (no product to demo), content sites, physical product e-commerce | Both | Medium — video autoplay and interactive elements | 2016–present |
+| Trust-Builder | certification display, testimonial photography, risk-reduction copy, authority signals | Client logo strip at top of page; testimonial cards with real photos (not stock); certification badges (SOC 2, ISO, G2); security copy near forms; money-back guarantee callout | B2B SaaS sales pages, fintech onboarding, legal/compliance products, high-ticket e-commerce | Consumer social apps, entertainment (trust signals read as corporate), developer tools (badges feel marketing-y) | Both | Low | 2012–present |
+| Playful Consumer | rounded UI, emoji integration, micro-animations, confetti moments | border-radius: 24–32px everywhere; emoji in headings; lottie animation for success states; confetti particle burst on conversion; pastel color fills; bouncy spring animations (spring: 200ms) | Consumer apps, gifting platforms, children's products, food delivery, social features | Enterprise, financial products, healthcare, government | Both | Medium — Lottie/animation assets | 2018–present |
+| Dark Premium | full dark canvas, gold or silver accents, whitespace-heavy, editorial hierarchy | Background #0A0A0A; accent: gold (#B8860B or #D4AF37) or silver (#C0C0C0); large display serif or geometric sans at 80–120px; section-level spacing (120–200px vertical rhythm) | Luxury SaaS, high-end service brands, premium membership products, whiskey/watch brands | Mass-market consumer apps, anything needing color variety for information hierarchy | Dark | Low | 2018–present |
+| Typography-Led | large type as hero element, minimal imagery, type as design | Display type at 100–200px viewport width; type positioned absolutely over background color; tight leading (line-height 0.9–1.1) at display scale; type color is the background color inverted | Editorial brands, design agencies, type foundries, artist/creative portfolios | Functional apps (type-only layouts hide UI conventions), e-commerce (products need imagery) | Both | Lowest | Print tradition; digital 2015–present |
+| Data-Driven | charts and statistics as hero visual, number-forward design | Large KPI numbers at 80–120px in hero; inline sparkline or bar chart in above-fold section; data annotation typography; monospace or tabular numerals; confidence interval UI | Analytics tools, investor relations pages, research organizations, fintech reporting features | Lifestyle brands, emotional products, services without clear metrics | Both | Low — static SVG charts | 2019–present |
+| Data Dense | information-maximized layout, minimal chrome, small type | 12–13px body in tables; 4–8px row padding; no card containers (table row is the container); tooltips over labels to save space; condensed font weight; color coded only for status | Bloomberg-style terminals, trading desks, operations centers, medical records systems | Consumer apps (cognitive overload), mobile-primary experiences, accessibility-critical | Both (dark preferred for terminal contexts) | Low | 1990s terminal origin; modern SaaS 2012–present |
+| Executive Dashboard | large KPIs, traffic-light status indicators, minimal labels, decision-oriented | KPI cards at 48–64px number size; 3-color status system (green/amber/red for good/warning/critical); sparkline trend line per KPI; maximum 6 KPIs above fold; no data tables in primary view | C-suite reporting dashboards, board packs, PE portfolio monitoring, business reviews | Operational monitoring (needs more granularity), self-serve analytics (needs exploration) | Both | Low | 2010–present |
+| Operational Monitor | real-time status indicators, alert color system, live data feel, dense timeline | WebSocket or SSE refresh indicator; color-coded service status dots; rolling log window (monospace, dark); alert banner docking at top; incident timeline view | DevOps dashboards, NOC (network operations center), cloud infrastructure monitoring, on-call tools | Executive reporting, consumer apps, any latency-sensitive rendering environment | Dark primary | Medium — live data updates | 2012–present |
+| Data Storytelling | prose plus inline charts, guided narrative, progressive disclosure of complexity | Section header states the finding; chart below supports it; annotation layer on chart pointing to key data moment; reading-width body column (640–720px); chapter progress indicator | Insight reports, analytics product "stories" feature, investor updates, public data journalism | Self-serve exploration dashboards (storytelling is prescriptive, not exploratory), real-time ops | Both | Low | 2017–present |
+| Grid/Matrix | dense tabular layout, frozen headers, column sorting, data comparison | CSS sticky column headers; alternating row background (zebra stripe); column resize handles; monospace numbers; sort indicator arrows; cell-level color coding for heatmaps | Financial data apps, CRM list views, ERP interfaces, spreadsheet-replacement tools | Dashboards with narrative focus, mobile primary (tables on mobile are difficult) | Both | Low — but DOM size can be high; virtualize rows beyond 500 | 2000–present |
+| Graph/Network | node-edge visualization, force-directed layout, interactive topology | SVG or Canvas force-directed graph; node size encodes metric; edge color encodes relationship type; zoom and pan; node inspection panel on click; cluster isolation on hover | Dependency maps, org charts, knowledge graphs, security blast-radius visualization | Reports (static charts better for non-interactive), mobile primary | Both | High — force simulation is CPU-intensive; use WebGL for >1000 nodes | 2012–present |
+| Geospatial | map-first layout, choropleth overlays, geographic filter | Full-bleed map as primary content area (Mapbox/Leaflet); choropleth color scale in legend; point cluster markers; polygon selection for region drill-down; sidebar for data detail | Logistics route analytics, retail location analytics, real estate market maps, public health dashboards | Products with no inherently geographic data, mobile with small screen | Both | High — map tile loading and vector layer rendering | 2010–present |
+| Timeline-First | chronological layout, Gantt-inspired, temporal density | Horizontal scroll timeline; date-stamped lane per entity; milestone markers; dependency lines between tasks; zoom from year → week → day; color coding per project/team | Project management tools, roadmap views, history visualization, editorial production tracking | Real-time monitoring (timeline is retrospective), KPI dashboards | Both | Medium — virtualized timeline required for long date ranges | 2015–present |
+| Comparison View | side-by-side panels, diff highlighting, symmetrical layout | Two-column layout at 50%/50%; synchronized scroll; highlighted diff lines (green/red) or changed values; overlay mode toggle; summary diff count in header | A/B test result dashboards, design diff tools, version comparison, benchmark analysis | Single-subject dashboards, mobile primary (two columns collapse badly) | Both | Low | 2015–present |
+| Mobile Analytics | touch-optimized charts, swipe navigation, bottom-sheet detail | Horizontal bar charts (not vertical — finger-friendly tap targets); swipe between metric cards; bottom-sheet expansion for drill-down; large tap targets (48px minimum); chart gestures (pinch-zoom) | Field sales apps, retail staff dashboards, on-the-go executive views, mobile-first ops tools | Desktop-primary tools (mobile patterns feel cramped on large screens), data-dense tables | Both | Low — but chart libraries must support touch events | 2018–present |

package/reference/surfaces.md

@@ -0,0 +1,114 @@
+# Surfaces
+Source: jakubkrehel/make-interfaces-feel-better (MIT) — surfaces.md
+
+Rules for nested surfaces, optical alignment, shadow systems, image outlines, and hit areas.
+
+## Concentric Radius Formula
+
+When nesting interactive elements inside a container (e.g., a card with a button, or a modal with an input), the inner radius must be SMALLER than the outer radius — by exactly the padding between them:
+
+```
+outerRadius = innerRadius + padding
+```
+
+Or equivalently:
+```
+innerRadius = outerRadius − padding
+```
+
+Example: card with `border-radius: 16px` and `padding: 16px` → inner elements should use `border-radius: 0px` (16 − 16 = 0). If padding is 8px → `border-radius: 8px` for inner elements.
+
+**Exception:** when `padding > 24px`, treat the inner element as a visually separate surface and apply its own standard radius (4/8/12px depending on its type).
+
+Why this matters: same radius on nested surfaces creates a visual disconnect — the inner element appears to "float" without belonging to the outer surface. The concentric formula creates perceptual depth and containment.
+
+## Optical Alignment
+
+Mathematical centering ≠ optical centering for asymmetric elements:
+
+- **Icon with text:** `padding-inline-start` for the icon side should be 2px less than `padding-inline-end` for the text side. This corrects for the visual weight imbalance.
+- **Play/chevron triangles:** shift right by 2px from mathematical center — triangles have more visual mass on their left side (the flat edge).
+- **SVG icons with irregular bounding box:** inspect the actual glyph bounds, not the viewBox. Add `padding` to compensate for asymmetric whitespace within the SVG.
+
+## 3-Layer Shadow System
+
+Build shadows from three stacked layers, not a single `box-shadow`:
+
+```css
+/* Light mode */
+.card {
+  box-shadow:
+    0 1px 2px rgba(0,0,0,0.06),   /* sharp close shadow — elevation definition */
+    0 4px 8px rgba(0,0,0,0.06),   /* soft ambient — depth blending */
+    0 8px 16px rgba(0,0,0,0.04);  /* wide diffuse — air gap */
+}
+
+/* Dark mode */
+.card {
+  box-shadow:
+    0 1px 2px rgba(0,0,0,0.3),
+    0 4px 8px rgba(0,0,0,0.3),
+    0 8px 16px rgba(0,0,0,0.2),
+    inset 0 1px 0 rgba(255,255,255,0.08); /* subtle top rim on dark */
+}
+```
+
+The inset rim on dark mode (`rgba(255,255,255,0.08)`) simulates a light source from above, which is the visual cue that makes dark cards feel like physical surfaces rather than holes in the UI.
+
+Scale the multipliers for elevation levels:
+- Level 0 (flat): no shadow
+- Level 1 (card): values above
+- Level 2 (dropdown): multiply blur radii by ~2
+- Level 3 (modal): add a full-screen scrim behind
+
+## Image Outlines
+
+Images always look better with a subtle outline that separates them from the background:
+
+```css
+img {
+  outline: 1px solid rgba(0,0,0,0.08);   /* light mode */
+  outline-offset: -1px;                   /* inside the image boundary */
+}
+
+/* Dark mode */
+img { outline: 1px solid rgba(255,255,255,0.08); }
+```
+
+**Hard rule:** Never tint the outline with a color. Use pure black at low opacity (light) or pure white at low opacity (dark). A tinted outline competes with the image colors and creates visual noise.
+
+This applies to:
+- Avatar photos
+- Product images
+- Screenshots
+- User-uploaded content
+
+Not needed for: SVG illustrations (they have their own defined boundary), icons, decorative graphics.
+
+## Hit Area Extension
+
+Interactive elements smaller than 40×40px must have their tap target extended without changing visual size:
+
+```css
+.icon-button {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.icon-button::after {
+  content: '';
+  position: absolute;
+  inset: -10px; /* extends each side by 10px → 40×40 total */
+}
+```
+
+For primary actions, extend to 48×48px (`inset: -14px` for a 20px icon).
+
+**Collision rule:** when two interactive elements are adjacent (e.g., toolbar icons), calculate whether the extended hit areas overlap. If overlap exceeds 4px, reduce the extension on the shared side. Never let invisible hit areas steal taps from adjacent elements.
+
+Target sizes:
+- Secondary/icon-only actions: 40×40px minimum
+- Primary CTAs: 48×48px minimum
+- Navigation items (mobile): 48×48px minimum
+- Touch-critical actions (checkout, send): 48×48px minimum

package/reference/typography.md

@@ -227,3 +227,83 @@ Always include a non-variable fallback of the same family in the font stack:
 ```css
 font-family: 'InterVariable', 'Inter', -apple-system, system-ui, sans-serif;
 ```
+
+---
+
+## Micro-Typography
+Source: jakubkrehel/make-interfaces-feel-better (MIT) — typography.md
+
+### text-wrap
+
+Use `text-wrap: balance` for headings to prevent orphaned single words:
+```css
+h1, h2, h3 { text-wrap: balance; }
+```
+Chromium supports up to 6 lines, Firefox up to 10. Do not apply to body text (performance cost scales with line count). For body copy and captions, use `text-wrap: pretty` instead — it prevents widows (dangling last words) without the line-count restriction.
+
+### Font smoothing
+
+Apply antialiasing at root level only:
+```css
+:root {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+Never apply per-element — this creates inconsistency within a single text block and is one of the most common micro-typography mistakes. The antialiased value makes text appear slightly thinner/lighter, which is generally preferred for UI type at modern screen densities.
+
+### Tabular numerals
+
+Use tabular-nums on any surface where numbers change dynamically or need to align in columns:
+```css
+.counter, .price, .timer, .table-cell { font-variant-numeric: tabular-nums; }
+```
+Proportional numerals (the default) cause text to shift width when numbers change, creating a distracting jitter in timers and prices. Exception: Inter's `1` character widens slightly with tabular-nums — test at your numeric composition before committing.
+
+## Font Pairings Catalog
+Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/typography.csv
+
+57 professionally curated pairings grouped by use-case vertical. For font loading, see `reference/data/google-fonts.csv` for the full 1923-font reference.
+
+### SaaS / Productivity
+- **Inter + Inter** (mono weight hierarchy) — The "safe default" for app UIs. Use regular (400) for body, medium (500) for labels, semibold (600) for headings. Consistent x-height, excellent at small sizes.
+- **Inter + JetBrains Mono** — For dev tools and dashboards with code display. JetBrains Mono has excellent legibility at 12-14px.
+- **Geist Sans + Geist Mono** — Vercel's pair; clean, modern, designed together.
+- **Outfit + DM Mono** — Friendly SaaS feel with clear code fallback.
+
+### Consumer / Marketing
+- **Satoshi + Cabinet Grotesk** — High-energy, modern consumer feel.
+- **Plus Jakarta Sans + Syne** — Playful but legible; works for creative consumer apps.
+- **DM Sans + DM Serif Display** — Classic pairing; editorial headers, clean body.
+- **Nunito + Source Code Pro** — Approachable and friendly.
+
+### Finance / Enterprise
+- **IBM Plex Sans + IBM Plex Mono** — Authoritative, systematic, designed for data-heavy interfaces.
+- **Source Sans 3 + Source Code Pro** — Adobe's workhorse pair; widely trusted.
+- **Lato + Roboto Mono** — Clean, neutral enterprise pair.
+
+### Editorial / Publishing
+- **Playfair Display + Source Serif 4** — High contrast serif headers with readable body serif.
+- **Cormorant Garamond + Proza Libre** — Elegant luxury/editorial tone.
+- **Libre Baskerville + Libre Franklin** — Free-license editorial pair.
+- **EB Garamond + Lato** — Classic print feel with modern body.
+
+### Wellness / Health
+- **Nunito + Nunito Sans** — Soft, approachable, consistent x-height.
+- **Quicksand + Work Sans** — Rounded, friendly, healthcare-appropriate.
+- **Raleway + Open Sans** — Clean and welcoming.
+
+### Dev Tools
+- **JetBrains Mono + Inter** — Code-first, UI-second; natural for developer tools.
+- **Fira Code + Fira Sans** — Cohesive family; ligatures available.
+- **Cascadia Code + Segoe UI** — Microsoft's modern dev pair.
+
+### Luxury / Fashion
+- **Cormorant + Montserrat** — High contrast serif + geometric sans; classic luxury.
+- **Bodoni Moda + Jost** — Fashion editorial feel.
+- **Playfair Display + Raleway** — Elegant header + clean body.
+
+### Gaming / Entertainment
+- **Syne + DM Sans** — Bold, energetic headers; clean readable body.
+- **Bebas Neue + Open Sans** — Impact headlines; neutral body.
+- **Exo 2 + Roboto** — Futuristic but readable.