@3fn/core 14.1.0 → 15.0.0

package/dist/consumer-canonical/skills/impeccable/reference/quieter.md

@@ -0,0 +1,99 @@
+Quiet design is harder than bold design. Subtlety needs precision. Reduce visual intensity in designs that are too loud, aggressive, or overstimulating without losing personality or making the result generic.
+
+---
+
+## Register
+
+Brand: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated; the POV stays intact.
+
+Product: "quieter" means reducing visual noise. Fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
+
+---
+
+## Assess Current State
+
+Analyze what makes the design feel too intense:
+
+1. **Identify intensity sources**:
+   - **Color saturation**: Overly bright or saturated colors
+   - **Contrast extremes**: Too much high-contrast juxtaposition
+   - **Visual weight**: Too many bold, heavy elements competing
+   - **Animation excess**: Too much motion or overly dramatic effects
+   - **Complexity**: Too many visual elements, patterns, or decorations
+   - **Scale**: Everything is large and loud with no hierarchy
+
+2. **Understand the context**:
+   - What's the purpose? (Marketing vs tool vs reading experience)
+   - Who's the audience? (Some contexts need energy)
+   - What's working? (Don't throw away good ideas)
+   - What's the core message? (Preserve what matters)
+
+If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+
+**CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness.
+
+## Plan Refinement
+
+Create a strategy to reduce intensity while maintaining impact:
+
+- **Color approach**: Desaturate or shift to more restrained tones?
+- **Hierarchy approach**: Which elements should stay bold (very few), which should recede?
+- **Simplification approach**: What can be removed entirely?
+- **Sophistication approach**: How can we signal quality through restraint?
+
+**IMPORTANT**: Subtlety requires precision. Quiet without intent collapses to generic.
+
+## Refine the Design
+
+Systematically reduce intensity across these dimensions:
+
+### Color Refinement
+- **Reduce saturation**: Shift from fully saturated to 70-85% saturation
+- **Soften palette**: Replace bright colors with muted tones
+- **Reduce color variety**: Use fewer colors more thoughtfully
+- **Neutral dominance**: Let neutrals do more work, use color as accent (10% rule)
+- **Gentler contrasts**: High contrast only where it matters most
+- **Tinted grays**: Use warm or cool tinted grays instead of pure gray. Adds depth without loudness
+- **Never gray on color**: If you have gray text on a colored background, use a darker shade of that color or transparency instead
+
+### Visual Weight Reduction
+- **Typography**: Reduce font weights (900 → 600, 700 → 500), decrease sizes where appropriate
+- **Hierarchy through subtlety**: Use weight, size, and space instead of color and boldness
+- **White space**: Increase breathing room, reduce density
+- **Borders & lines**: Reduce thickness, decrease opacity, or remove entirely
+
+### Simplification
+- **Remove decorative elements**: Gradients, shadows, patterns, textures that don't serve purpose
+- **Simplify shapes**: Reduce border radius extremes, simplify custom shapes
+- **Reduce layering**: Flatten visual hierarchy where possible
+- **Clean up effects**: Reduce or remove blur effects, glows, multiple shadows
+
+### Motion Reduction
+- **Reduce animation intensity**: Shorter distances (10-20px instead of 40px), gentler easing
+- **Remove decorative animations**: Keep functional motion, remove flourishes
+- **Subtle micro-interactions**: Replace dramatic effects with gentle feedback
+- **Refined easing**: Use ease-out-quart for smooth, understated motion. Never bounce or elastic
+- **Remove animations entirely** if they're not serving a clear purpose
+
+### Composition Refinement
+- **Reduce scale jumps**: Smaller contrast between sizes creates calmer feeling
+- **Align to grid**: Bring rogue elements back into systematic alignment
+- **Even out spacing**: Replace extreme spacing variations with consistent rhythm
+
+**NEVER**:
+- Make everything the same size/weight (hierarchy still matters)
+- Remove all color (quiet ≠ grayscale)
+- Eliminate all personality (maintain character through refinement)
+- Sacrifice usability for aesthetics (functional elements still need clear affordances)
+- Make everything small and light (some anchors needed)
+
+## Verify Quality
+
+Ensure refinement maintains quality:
+
+- **Still functional**: Can users still accomplish tasks easily?
+- **Still distinctive**: Does it have character, or is it generic now?
+- **Better reading**: Is text easier to read for extended periods?
+- **Restrained, not absent**: Does the POV survive the cuts?
+
+When the result feels right, hand off to `/impeccable polish` for the final pass.

package/dist/consumer-canonical/skills/impeccable/reference/responsive-design.md

@@ -0,0 +1,114 @@
+# Responsive Design
+
+## Mobile-First: Write It Right
+
+Start with base styles for mobile, use `min-width` queries to layer complexity. Desktop-first (`max-width`) means mobile loads unnecessary styles first.
+
+## Breakpoints: Content-Driven
+
+Don't chase device sizes; let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
+
+## Detect Input Method, Not Just Screen Size
+
+**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard. Use pointer and hover queries:
+
+```css
+/* Fine pointer (mouse, trackpad) */
+@media (pointer: fine) {
+  .button { padding: 8px 16px; }
+}
+
+/* Coarse pointer (touch, stylus) */
+@media (pointer: coarse) {
+  .button { padding: 12px 20px; }  /* Larger touch target */
+}
+
+/* Device supports hover */
+@media (hover: hover) {
+  .card:hover { transform: translateY(-2px); }
+}
+
+/* Device doesn't support hover (touch) */
+@media (hover: none) {
+  .card { /* No hover state - use active instead */ }
+}
+```
+
+**Critical**: Don't rely on hover for functionality. Touch users can't hover.
+
+## Safe Areas: Handle the Notch
+
+Modern phones have notches, rounded corners, and home indicators. Use `env()`:
+
+```css
+body {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+
+/* With fallback */
+.footer {
+  padding-bottom: max(1rem, env(safe-area-inset-bottom));
+}
+```
+
+**Enable viewport-fit** in your meta tag:
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+```
+
+## Responsive Images: Get It Right
+
+### srcset with Width Descriptors
+
+```html
+<img
+  src="hero-800.jpg"
+  srcset="
+    hero-400.jpg 400w,
+    hero-800.jpg 800w,
+    hero-1200.jpg 1200w
+  "
+  sizes="(max-width: 768px) 100vw, 50vw"
+  alt="Hero image"
+>
+```
+
+**How it works**:
+- `srcset` lists available images with their actual widths (`w` descriptors)
+- `sizes` tells the browser how wide the image will display
+- Browser picks the best file based on viewport width AND device pixel ratio
+
+### Picture Element for Art Direction
+
+When you need different crops/compositions (not just resolutions):
+
+```html
+<picture>
+  <source media="(min-width: 768px)" srcset="wide.jpg">
+  <source media="(max-width: 767px)" srcset="tall.jpg">
+  <img src="fallback.jpg" alt="...">
+</picture>
+```
+
+## Layout Adaptation Patterns
+
+**Navigation**: Three stages: hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
+
+## Testing: Don't Trust DevTools Alone
+
+DevTools device emulation is useful for layout but misses:
+
+- Actual touch interactions
+- Real CPU/memory constraints
+- Network latency patterns
+- Font rendering differences
+- Browser chrome/keyboard appearances
+
+**Test on at least**: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.
+
+---
+
+**Avoid**: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.

package/dist/consumer-canonical/skills/impeccable/reference/shape.md

@@ -0,0 +1,165 @@
+Shape the UX and UI for a feature before any code is written. This command produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork.
+
+**Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good.
+
+**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output.
+
+## Philosophy
+
+Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This command inverts that: understand deeply first, so implementation is precise.
+
+## Phase 1: Discovery Interview
+
+**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
+
+This is a required interaction, not optional guidance. Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
+
+### Interview cadence
+
+Discovery includes at least one user-answer round unless MCP context (product overview, brand context), or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response.
+
+- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
+- Ask **2-3 questions per round**, then wait for answers.
+- Treat MCP context as anchors; it reduces repeated questions but does **not** replace shape for craft. Shape is task-specific.
+- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough.
+- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction.
+- Round 2, when needed, fills in whatever's still genuinely missing.
+
+**Assert-then-confirm, not menu-with-escape.** When MCP context and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear.
+
+### Purpose & Context
+- What is this feature for? What problem does it solve?
+- Who specifically will use it? (Not "users"; be specific: role, context, frequency)
+- What does success look like? How will you know this feature is working?
+- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?)
+
+### Content & Data
+- What content or data does this feature display or collect?
+- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items)
+- What are the edge cases? (Empty state, error state, first-time use, power user)
+- Is any content dynamic? What changes and how often?
+- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets.
+
+### Design Direction
+
+Force a visual decision on three fronts. Skip anything MCP context (product overview, brand context, design philosophy) already answers; ask only what's missing.
+
+- **Color strategy for this surface.** Pick one: Restrained / Committed / Full palette / Drenched. Can override the project default if the surface earns it (e.g. a drenched hero inside an otherwise Restrained product).
+- **Theme via scene sentence.** Write one sentence of physical context for this surface: who uses it, where, under what ambient light, in what mood. The sentence forces dark vs light. If it doesn't, add detail until it does.
+- **Two or three named anchor references.** Specific products, brands, objects. Not adjectives like "modern" or "clean."
+
+### Scope
+
+Always ask. Sketch quality and shipped quality are different outputs; don't guess between them.
+
+- **Fidelity.** Sketch / mid-fi / high-fi / production-ready?
+- **Breadth.** One screen / a flow / a whole surface?
+- **Interactivity.** Static visual / interactive prototype / shipped-quality component?
+- **Time intent.** Quick exploration, or polish until it ships?
+
+Scope answers are task-scoped. Don't persist them beyond the design brief.
+
+### Constraints
+- Are there technical constraints? (Framework, performance budget, browser support)
+- Are there content constraints? (Localization, dynamic text length, user-generated content)
+- Mobile/responsive requirements?
+- Accessibility requirements beyond WCAG AA?
+
+### Anti-Goals
+- What should this NOT be? What would be a wrong direction?
+- What's the biggest risk of getting this wrong?
+
+## Phase 1.5: Visual Direction Probe (Capability-Gated)
+
+After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true:
+
+- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief.
+- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning.
+- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling.
+
+When those conditions are met, this step is mandatory. If image generation isn't natively available, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. The one-line announcement is required, not optional; it forces a conscious decision instead of letting the step quietly evaporate.
+
+Use probes to explore visual lanes, not to replace the brief.
+
+Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
+
+### What to generate
+
+Generate **2 to 4** distinct direction probes based on the discovery answers, especially:
+
+- Color strategy
+- Theme scene sentence
+- Named anchor references
+- Scope and fidelity
+
+The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks.
+
+### How to use the probes
+
+- Treat them as **direction tests**, not final designs.
+- Use them to pressure-test whether the brief is pointing at the right lane.
+- Ask the user which direction feels closest, what feels off, and what should carry forward.
+- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief.
+
+### Important limits
+
+- Do **not** skip discovery because image generation is available.
+- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior.
+- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice.
+
+If image generation isn't natively available, announce the skip in one line and proceed to the design brief.
+
+## Phase 2: Design Brief
+
+After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate.
+
+**Choose the brief shape based on how clear the answers are:**
+
+- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + MCP context already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt.
+- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight.
+
+Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point.
+
+Present the brief, then **stop and wait for explicit confirmation**. You are not the judge of whether the user already approved. Even when the brief feels obviously right, ask once and wait. The pause is what separates shape from premature implementation.
+
+### Brief Structure
+
+**1. Feature Summary** (2-3 sentences)
+What this is, who it's for, what it needs to accomplish.
+
+**2. Primary User Action**
+The single most important thing a user should do or understand here.
+
+**3. Design Direction**
+Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference MCP context (product overview, brand context) where it already answers, and note any per-surface overrides.
+
+If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it.
+
+**4. Scope**
+Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped; these don't persist beyond the brief.
+
+**5. Layout Strategy**
+High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS.
+
+**6. Key States**
+List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel.
+
+**7. Interaction Model**
+How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion?
+
+**8. Content Requirements**
+What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission).
+
+**9. Recommended References**
+Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., layout.md for complex layouts, animate.md for animated features, interaction-design.md for form-heavy features, typeset.md for typography-driven pages, colorize.md for color-led brands).
+
+**10. Open Questions**
+Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X.
+
+---
+
+ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing.
+
+If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction.
+
+Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.)

package/dist/consumer-canonical/skills/impeccable/reference/spatial-design.md

@@ -0,0 +1,100 @@
+# Spatial Design
+
+## Spacing Systems
+
+### Use 4pt Base, Not 8pt
+
+8pt systems are too coarse; you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
+
+### Name Tokens Semantically
+
+Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing; it eliminates margin collapse and cleanup hacks.
+
+## Grid Systems
+
+### The Self-Adjusting Grid
+
+Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints. Columns are at least 280px, as many as fit per row, leftovers stretch. For complex layouts, use named grid areas (`grid-template-areas`) and redefine them at breakpoints.
+
+## Visual Hierarchy
+
+### The Squint Test
+
+Blur your eyes (or screenshot and blur). Can you still identify:
+- The most important element?
+- The second most important?
+- Clear groupings?
+
+If everything looks the same weight blurred, you have a hierarchy problem.
+
+### Hierarchy Through Multiple Dimensions
+
+Don't rely on size alone. Combine:
+
+| Tool | Strong Hierarchy | Weak Hierarchy |
+|------|------------------|----------------|
+| **Size** | 3:1 ratio or more | <2:1 ratio |
+| **Weight** | Bold vs Regular | Medium vs Regular |
+| **Color** | High contrast | Similar tones |
+| **Position** | Top/left (primary) | Bottom/right |
+| **Space** | Surrounded by white space | Crowded |
+
+**The best hierarchy uses 2-3 dimensions at once**: A heading that's larger, bolder, AND has more space above it.
+
+### Cards Are Not Required
+
+Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. **Never nest cards inside cards.** Use spacing, typography, and subtle dividers for hierarchy within a card.
+
+## Container Queries
+
+Viewport queries are for page layouts. **Container queries are for components**:
+
+```css
+.card-container {
+  container-type: inline-size;
+}
+
+.card {
+  display: grid;
+  gap: var(--space-md);
+}
+
+/* Card layout changes based on its container, not viewport */
+@container (min-width: 400px) {
+  .card {
+    grid-template-columns: 120px 1fr;
+  }
+}
+```
+
+**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands automatically, without viewport hacks.
+
+## Optical Adjustments
+
+Text at `margin-left: 0` looks indented due to letterform whitespace; use negative margin (`-0.05em`) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.
+
+### Touch Targets vs Visual Size
+
+Buttons can look small but need large touch targets (44px minimum). Use padding or pseudo-elements:
+
+```css
+.icon-button {
+  width: 24px;  /* Visual size */
+  height: 24px;
+  position: relative;
+}
+
+.icon-button::before {
+  content: '';
+  position: absolute;
+  inset: -10px;  /* Expand tap target to 44px */
+}
+```
+
+## Depth & Elevation
+
+Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle. If you can clearly see it, it's probably too strong.
+
+---
+
+**Avoid**: Arbitrary spacing values outside your scale. Making all spacing equal (variety creates hierarchy). Creating hierarchy through size alone - combine size, weight, color, and space.

package/dist/consumer-canonical/skills/impeccable/reference/typeset.md

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