@hegemonart/get-design-done 1.14.8 → 1.15.0

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.

package/reference/visual-hierarchy-layout.md

@@ -0,0 +1,306 @@
+# Visual Hierarchy & Layout
+
+<!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/landing.csv -->
+
+Visual hierarchy is the system by which a design communicates importance before the user consciously processes it. Every element in a layout has a perceived rank — determined by size, contrast, position, spacing, and depth — and that rank tells the eye where to go and in what order. A layout without deliberate hierarchy forces the user to negotiate with the design rather than work through it. The principles in this file apply to screens, components, and marketing pages equally.
+
+---
+
+## Z-Order and Depth Cues
+
+Shadow is the primary depth signal in modern flat design, because it mimics the physical relationship between surfaces at different altitudes. Shadows do not decorate — they locate. A surface with more shadow sits higher in the visual stack, which means it is more foregrounded and more important.
+
+### Three-Layer Shadow System
+
+The standard three-layer system maps to real UI altitude needs:
+
+| Layer | Shadow Spec | Use |
+|-------|------------|-----|
+| Base (elevation 0) | No shadow | Default page surface, cards at rest |
+| Raised (elevation 1) | `box-shadow: 0 2px 4px rgba(0,0,0,0.08)` | Hover states, interactive cards, sticky headers |
+| Floating (elevation 2) | `box-shadow: 0 8px 16px rgba(0,0,0,0.12)` | Dropdowns, tooltips, popovers |
+| Overlay (elevation 3) | `box-shadow: 0 16px 32px rgba(0,0,0,0.18)` | Modals, drawers, sheets |
+
+Using only these four levels prevents visual noise from competed shadows and keeps the depth hierarchy readable. An element should never sit at the same shadow level as an element it is meant to overlay — that collapses the depth relationship.
+
+### Blur-as-Scrim for Modal Depth
+
+When a modal or drawer is open, applying a backdrop blur (`backdrop-filter: blur(4px)` or a semi-transparent dark overlay) on the content beneath reinforces that the modal is spatially in front of it. This is a figure-ground manipulation (see Gestalt principles). The scrim communicates "this content is currently inaccessible" without hiding it entirely, preserving orientation.
+
+### Z-Index Scale
+
+A consistent z-index scale prevents the stacking context chaos that makes UI debugging painful. Each level exists for a reason:
+
+| Level | Value | Purpose |
+|-------|-------|---------|
+| Base | 0 | Static page content — no stacking context needed |
+| Sticky | 100 | Sticky headers and footers that must stay above scrolled content |
+| Dropdown | 200 | Menus and autocomplete dropdowns that overlay adjacent content |
+| Modal | 300 | Dialogs and drawers that overlay the entire page |
+| Toast | 400 | Notifications that must appear above even open modals |
+
+Gaps of 100 between levels exist so intermediate values can be inserted without renumbering. Never assign z-index values outside this scale without a documented reason, because arbitrary z-index values signal that someone solved a specificity problem instead of understanding the stacking architecture.
+
+---
+
+## Whitespace as Design Element
+
+Whitespace is not empty space — it is the space that gives meaning to what surrounds it. Without whitespace, elements cannot be perceived as distinct objects; they collapse into visual noise. With intentional whitespace, proximity becomes a communication tool: elements that are close together are related, and elements that are far apart are not.
+
+### Micro-Spacing (Related Elements)
+
+Elements that belong together — a label and its input, an icon and its caption, a list item and its supporting text — should be separated by 4–8px. This distance signals "these are one thing" without fusing them visually. Tighter than 4px feels merged; looser than 8px starts to break the association.
+
+### Macro-Spacing (Section Separation)
+
+Distinct content sections — hero to features, features to testimonials, nav to page content — benefit from 32–64px of separation. This spacing creates visual "chapters" in the layout, giving the eye a moment to land before beginning the next section. Without this spacing, the page feels like one undifferentiated mass regardless of the visual variation within it.
+
+### Premium vs. Compact
+
+More whitespace signals premium and confidence: the brand is not anxious about showing off everything at once. Less whitespace signals density and efficiency: the product respects the user's time and assumes they have a specific goal. Neither is universally correct — a data dashboard should be compact because users came to see data, while a luxury product landing page should be expansive because users came to be immersed.
+
+The rule of thumb: **match whitespace density to the pace at which users should move through the content.** Fast task completion → compact. Consideration and exploration → generous.
+
+---
+
+## Asymmetry and Rhythm
+
+Symmetric layouts feel stable, balanced, and trustworthy — which makes them appropriate for institutional, financial, and governmental contexts where those qualities matter. They also feel static, because perfect balance has no direction and creates no tension.
+
+Asymmetric layouts create tension and visual interest by violating the expectation of balance. When used purposefully, asymmetry directs the eye along a path — a large element on the left creates pressure toward the right, a heavy top creates pressure downward. This directed attention is why most effective marketing layouts use asymmetry: the imbalance leads the user's eye toward the CTA.
+
+The key discipline is intentionality. Asymmetry that emerges from neglect — uneven margins, inconsistent column widths — reads as incompetence, not dynamism. Asymmetry that is designed — a deliberate large/small pairing, a grid that breaks at one exact point — reads as craft. Always be able to explain why a layout is asymmetric in terms of what attention it is directing.
+
+### Rhythm
+
+Rhythm in layout means that repetition creates a predictable visual beat that the eye can lock onto and traverse quickly. A card grid has rhythm. A consistent heading-body-space pattern has rhythm. Rhythm is not uniformity — it is the reliable expectation that similar content will appear in similar visual form. Break rhythm only to signal importance: a featured item in a grid that is twice the size says "this one matters."
+
+---
+
+## Compositional Grids
+
+Grids are not aesthetic choices — they are coordination mechanisms. A grid aligns elements to invisible reference lines, which means users can scan a layout without actively negotiating where each element sits.
+
+### Responsive Column Grid
+
+| Breakpoint | Columns | Gutter | Margin |
+|------------|---------|--------|--------|
+| Mobile (≤767px) | 4 | 16px | 16px |
+| Tablet (768–1023px) | 8 | 24px | 24px |
+| Desktop (1024–1439px) | 12 | 24px | 32px |
+| Ultra-wide (≥1440px) | 16 | 32px | 48px |
+
+12-column desktop is the most common grid because it divides evenly into halves (6), thirds (4), quarters (3), sixths (2), and twelfths (1), giving layouts maximum compositional flexibility. 16-column ultra-wide grids are appropriate for dashboards because they accommodate more simultaneously visible data columns without collapsing to tiny widths.
+
+### Baseline Grid
+
+A baseline grid aligns text and element heights to a consistent vertical increment — typically 4px or 8px. Every element's height, padding, and margin should be a multiple of this increment. The baseline grid is what makes a layout feel "settled" rather than arbitrarily positioned, because every vertical decision relates to a shared rhythm. In practice, use 8px as the primary increment and 4px for sub-increments only (e.g., within a component's internal padding).
+
+---
+
+## Figure-Ground Manipulation
+
+Figure-ground perception is the visual system's ability to separate a subject (figure) from its context (ground). Design relies on this to make interactive elements pop out of the background, modal overlays recede the page behind them, and navigation items separate from the content they sit above.
+
+The primary tools for establishing figure-ground relationships are:
+
+- **Color contrast:** The figure must have at least 3:1 contrast ratio against the ground (WCAG AA for large text; perceived separation requires at least this even for decorative elements).
+- **Size:** Larger elements naturally read as foreground.
+- **Shadow:** Elements with elevation shadows read as physically in front of flat elements.
+- **Blur:** Blurred elements recede perceptually, making sharp elements read as foreground.
+
+Never rely on a single cue alone — a foreground element established only by shadow may become invisible in certain display contexts. Combining contrast + shadow + position creates a robust figure-ground relationship.
+
+---
+
+## Reading-Order Scoring
+
+Users do not read UIs — they scan them. Understanding the scan pattern users will apply to a layout allows designers to place information where the eye will naturally encounter it in the intended order.
+
+### F-Pattern
+
+Users scan the top horizontally, then move down the left side, occasionally scanning horizontally partway across the middle. This pattern dominates text-heavy content: documentation, long-form reads, dense lists. In an F-pattern layout, the most important content belongs at the top and along the left edge. Midline content will receive partial attention; right-column and lower-left content will frequently be missed.
+
+**Implication:** In F-pattern contexts, do not place critical information or CTAs in the right column or below the visible horizontal sweeps.
+
+### Z-Pattern
+
+Users scan the top-left, move horizontally to the top-right, then diagonally across to the bottom-left, then horizontally to the bottom-right. This pattern dominates sparse layouts with clear visual anchors — marketing pages with a headline, an image, and a CTA. The Z traces through the key moments of the layout, which is why placing a CTA at the Z-terminal (bottom-right) is effective for conversion-optimized pages.
+
+**Implication:** In Z-pattern contexts, place the brand/logo at top-left, the most compelling claim at top-right, the value summary along the diagonal, and the CTA at bottom-right.
+
+### Inverted Triangle
+
+The layout starts wide at the top (a full-width headline), narrows through supporting content, and terminates at a focused CTA. This pattern concentrates user attention progressively, mimicking an argument structure: here is the claim (wide), here is the evidence (mid-width), here is the action (narrow and high-contrast).
+
+**Implication:** The inverted triangle is one of the strongest conversion patterns because it naturally channels the user's attention from awareness to action without requiring a deliberate scan path.
+
+---
+
+## Progressive Disclosure Hooks
+
+Progressive disclosure is the principle that interface complexity should be revealed in proportion to user readiness and need. Showing all complexity at once overwhelms; hiding complexity aggressively creates friction. The correct level of disclosure depends on what the user is trying to do right now.
+
+**Accordion:** Use for dense but not immediately required information. FAQs, advanced settings, and multi-section forms benefit from accordions because users can navigate to the section they need without reading everything. Never hide primary actions behind an accordion — only secondary and contextual content belongs there.
+
+**Tooltip:** Use for inline definitions and contextual help that would interrupt reading flow if placed in line. Tooltips are appropriate for technical terms, icon meanings, and field constraints. They should appear on hover (not click) for desktop, and on tap for mobile. Tooltip copy must be brief — if the explanation requires more than two sentences, it belongs in documentation, not a tooltip.
+
+**Drill-down:** Use for hierarchical data exploration where showing all levels simultaneously would be overwhelming. File browsers, category navigation, and data dashboards with sub-dimension exploration are appropriate drill-down contexts. Each level should clearly communicate where the user is in the hierarchy and how to return.
+
+**The invariant:** Never hide primary actions behind any disclosure pattern. If a user must open an accordion to find the main CTA, the information architecture is broken. Disclosure patterns are for secondary information only.
+
+---
+
+## Landing-Page Archetypes
+
+<!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/landing.csv -->
+
+A landing-page archetype is a proven structural pattern — a specific order of sections, CTA placement rule, and visual approach — calibrated to a specific conversion goal and audience state. Matching the archetype to the product's vertical and the visitor's awareness level dramatically improves conversion without requiring creative originality at every decision.
+
+The 24 archetypes below are ordered by section sequence. "CTA placement rule" describes where to place the primary call to action relative to page content.
+
+---
+
+### 1. Hero-Centric
+**Section order:** Full-viewport hero → brief feature highlights → footer  
+**CTA placement rule:** Above the fold, within the hero — the primary action is visible without scrolling  
+**Best for:** SaaS product launches, single-purpose apps, brand launches where one conversion goal dominates  
+**Key visual pattern:** Large image or video background, single headline, single CTA button — nothing competes with the hero
+
+### 2. Conversion-Optimized
+**Section order:** Headline → CTA → minimal social proof → secondary CTA  
+**CTA placement rule:** Within 200px of the top of the page; repeated on scroll at a consistent interval  
+**Best for:** Lead generation, email capture, high-intent landing pages where the visitor already knows what they want  
+**Key visual pattern:** Minimal distraction — no navigation, no secondary offers; everything serves the single conversion action
+
+### 3. Feature-Rich Showcase
+**Section order:** Hero → feature grid → social proof → pricing summary → CTA  
+**CTA placement rule:** Mid-page, after the feature grid has established value  
+**Best for:** Complex products with multiple differentiated capabilities that need explaining before the user will convert  
+**Key visual pattern:** Icon cards with short descriptions arranged in a grid; screenshots or product mockups for each feature
+
+### 4. Minimal and Direct
+**Section order:** Logo → tagline → single CTA → optional supporting line  
+**CTA placement rule:** Above the fold; the page is essentially nothing but the CTA  
+**Best for:** Luxury brands, exclusive invitations, invite-only launches, products where restraint signals quality  
+**Key visual pattern:** White space is the dominant visual element; typography carries the entire design load; photography is secondary
+
+### 5. Social-Proof-Focused
+**Section order:** Hero → testimonial prominences → customer logo wall → case study summary → CTA  
+**CTA placement rule:** After the social proof block — conversion happens once trust is established  
+**Best for:** Products where credibility is the primary conversion barrier: enterprise software, high-ticket services, health products  
+**Key visual pattern:** Real face photography accompanying testimonials; recognizable logos displayed at full opacity; specific measurable results quoted
+
+### 6. Interactive Product Demo
+**Section order:** Hero with embedded live demo or interactive preview → feature explanation → CTA  
+**CTA placement rule:** Inline with the demo; allow the user to try before committing  
+**Best for:** Developer tools, SaaS products, any product where the experience is the best argument for conversion  
+**Key visual pattern:** Live code editor, interactive prototype, or animated walkthrough embedded directly in the page — not behind a click
+
+### 7. Trust and Authority
+**Section order:** Credentials and certifications → case study highlights → team or methodology → CTA  
+**CTA placement rule:** Conservative — placed after all trust signals have been presented; below the fold is acceptable  
+**Best for:** B2B enterprise sales, consulting services, legal and compliance products where buying risk is high  
+**Key visual pattern:** Logo wall with named clients; specific metrics from case studies; certifications and awards displayed prominently
+
+### 8. Storytelling-Driven
+**Section order:** Narrative introduction → problem acknowledgment → solution journey → outcome → CTA  
+**CTA placement rule:** End of story — the CTA is the natural conclusion of the narrative arc  
+**Best for:** Mission-driven brands, founder-led companies, products where the origin story creates emotional investment  
+**Key visual pattern:** Full-bleed photography that advances the narrative; minimal UI chrome; scroll-triggered reveals that pace the story
+
+### 9. Comparison/Competitive
+**Section order:** Positioning headline → feature comparison matrix → pricing → CTA  
+**CTA placement rule:** After the comparison matrix — once the product has won the comparison  
+**Best for:** Competitive category entries, products explicitly positioning against a named incumbent, switching-cost contexts  
+**Key visual pattern:** Side-by-side comparison table with clear visual wins; checkmarks vs. X marks; pricing presented as a conclusion, not an opener
+
+### 10. Problem-Solution
+**Section order:** Pain point articulation → solution introduction → specific benefits → social proof → CTA  
+**CTA placement rule:** Mid-page, after the solution and benefits have been presented  
+**Best for:** Products solving a well-understood pain that users actively feel but haven't found a solution for  
+**Key visual pattern:** Before/after contrast; language that mirrors how users describe the problem to themselves; solution reveal that feels like relief
+
+### 11. Community-Led
+**Section order:** Community value proposition → user-generated content grid → join CTA → community stats  
+**CTA placement rule:** After seeing the community in action — conversion is to join, not to buy  
+**Best for:** Social apps, creator platforms, forums, any product whose value scales with network size  
+**Key visual pattern:** Real user content grid; community size metrics; faces and usernames to signal that real people are already here
+
+### 12. Free-Tool
+**Section order:** Tool embedded directly at top → output or result preview → upgrade value proposition → CTA  
+**CTA placement rule:** After tool use — show the upgrade CTA once the user has experienced the value  
+**Best for:** Freemium SaaS products where the tool itself is the best acquisition mechanism  
+**Key visual pattern:** Functional tool widget inline in the page; results visible without signup; upgrade gate triggered by usage limit or advanced feature
+
+### 13. Event/Launch
+**Section order:** Event name and date → countdown timer → value proposition → registration form  
+**CTA placement rule:** Above the fold alongside the countdown — urgency and action together  
+**Best for:** Product launches, webinars, conferences, limited-availability events  
+**Key visual pattern:** Countdown timer as the hero element; date and time prominently displayed; registration form short enough to complete immediately
+
+### 14. Portfolio/Agency
+**Section order:** Brand positioning → selected work grid → process or approach → contact CTA  
+**CTA placement rule:** Bottom of page — the portfolio is the argument; the CTA is the conclusion  
+**Best for:** Creative agencies, freelancers, design studios, any service business where the work speaks for itself  
+**Key visual pattern:** Full-bleed project images; minimal copy; case study depth available on click; contact form or email rather than a purchase CTA
+
+### 15. E-commerce Category
+**Section order:** Category headline → filter controls → product grid → individual product CTAs  
+**CTA placement rule:** Per-product — each product card has its own CTA  
+**Best for:** Retail product categories, marketplace verticals, any browsing-first commerce context  
+**Key visual pattern:** Masonry or uniform grid layout; filter/sort controls accessible without page navigation; product image as the primary communication vehicle
+
+### 16. Mobile-App Download
+**Section order:** App value proposition → device mockup → key screens → app store badges → social proof  
+**CTA placement rule:** Above the fold with app store badge buttons; repeated at bottom  
+**Best for:** Consumer mobile apps, games, utilities targeting smartphone-first audiences  
+**Key visual pattern:** Phone frame showing the app in use; platform-specific badges (App Store / Google Play) as primary CTAs; optional rating and download count as social proof
+
+### 17. Video-First
+**Section order:** Autoplay background video → overlaid headline and CTA → supporting content below  
+**CTA placement rule:** Overlaid on the video — visible immediately on page load  
+**Best for:** Experiential brands, travel companies, premium consumer products where atmosphere is the argument  
+**Key visual pattern:** Full-screen video autoplay (muted); minimal text overlay; the video carries the emotional and brand argument
+
+### 18. Pricing-Forward
+**Section order:** Brief positioning → pricing table with tier comparison → per-tier CTA → FAQ  
+**CTA placement rule:** Per-tier — each pricing column has its own conversion action  
+**Best for:** Products with transparent, self-serve pricing; SaaS with clear tier differentiation; subscription businesses  
+**Key visual pattern:** Three-tier layout with middle tier highlighted as recommended; feature comparison below price; annual/monthly toggle
+
+### 19. Newsletter/Content
+**Section order:** Value proposition → email capture form → sample content or recent issues → social proof subscriber count  
+**CTA placement rule:** Above the fold — the form is the entire purpose of the page  
+**Best for:** Media companies, content creators, thought leaders, any subscription email product  
+**Key visual pattern:** Minimal design that does not compete with the form; preview of content quality as the primary trust signal
+
+### 20. Data/Analytics Showcase
+**Section order:** Positioning headline → live or animated dashboard preview → capability explanation → CTA  
+**CTA placement rule:** After the demo — once the data quality has been demonstrated  
+**Best for:** Analytics platforms, BI tools, data products where the output is the proof  
+**Key visual pattern:** Interactive chart or live dashboard preview embedded in the page; real-seeming data rather than placeholders; metric definitions visible to signal depth
+
+### 21. Long-Form Sales Page
+**Section order:** Headline → problem → agitation → solution → proof → benefits → objection handling → CTA → guarantee → repeated CTA  
+**CTA placement rule:** Repeated multiple times throughout — after each major argument and at the end  
+**Best for:** High-ticket items, coaching programs, courses, any product requiring significant commitment  
+**Key visual pattern:** Text-heavy with strategic visual breaks; testimonials woven throughout rather than grouped; guarantee section near the final CTA to reduce last-minute drop-off
+
+### 22. Waitlist/Pre-launch
+**Section order:** Teaser headline → product promise → email capture form → optional: social sharing incentive  
+**CTA placement rule:** Above the fold — the form is the entire conversion goal  
+**Best for:** Pre-launch products, invite-only launches, limited-release products  
+**Key visual pattern:** Intentional information scarcity; anticipation over explanation; social proof through waitlist size if available
+
+### 23. Marketplace
+**Section order:** Search bar → category navigation → featured listings → browse grid  
+**CTA placement rule:** Search-first — the search bar is the primary CTA; per-listing CTAs secondary  
+**Best for:** Two-sided platforms, classified marketplaces, any product where supply browsing is the primary user behavior  
+**Key visual pattern:** Search prominence above everything else; category browsing as primary navigation; featured/promoted listings visually distinct but not intrusive
+
+### 24. Documentation Hub
+**Section order:** Search bar → quick-start links → navigation tree → content area  
+**CTA placement rule:** No primary marketing CTA — navigation is the only action  
+**Best for:** Developer documentation, product help centers, API references, any knowledge base  
+**Key visual pattern:** Navigation-heavy layout; dense information with strong typographic hierarchy; search is the dominant entry point; no marketing chrome competing with the content