diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 39e681432..fe7b61e15 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -2,7 +2,7 @@
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
"name": "impeccable",
"metadata": {
- "description": "Design fluency for AI harnesses. 1 skill, 17 commands, and curated anti-patterns for impeccable frontend design."
+ "description": "Design fluency for AI harnesses. 1 skill, 20 commands, and curated anti-patterns for impeccable frontend design."
},
"owner": {
"name": "Paul Bakaus",
@@ -11,8 +11,8 @@
"plugins": [
{
"name": "impeccable",
- "description": "Design vocabulary and skills for frontend development. Includes 17 commands (/polish, /distill, /audit, /bolder, /quieter, etc.) and an enhanced frontend-design skill with curated anti-patterns.",
- "version": "1.3.0",
+ "description": "Design vocabulary and skills for frontend development. Includes 20 commands (/polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced frontend-design skill with curated anti-patterns.",
+ "version": "1.5.0",
"author": {
"name": "Paul Bakaus",
"email": "paul@paulbakaus.com"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index ff9296bf0..e52c30e23 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "impeccable",
- "description": "Design vocabulary and skills for frontend development. Includes 18 skills (17 user-invokable: /polish, /distill, /audit, /bolder, /quieter, etc.) and an enhanced frontend-design skill with curated anti-patterns.",
- "version": "1.3.0",
+ "description": "Design vocabulary and skills for frontend development. Includes 21 skills (20 user-invokable: /polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced frontend-design skill with curated anti-patterns.",
+ "version": "1.5.0",
"author": {
"name": "Paul Bakaus",
"email": "paul@paulbakaus.com"
diff --git a/.claude/skills/arrange/SKILL.md b/.claude/skills/arrange/SKILL.md
new file mode 100644
index 000000000..3c91bf7f4
--- /dev/null
+++ b/.claude/skills/arrange/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: arrange
+description: Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy to create intentional compositions.
+user-invokable: true
+args:
+ - name: target
+ description: The feature or component to improve layout for (optional)
+ required: false
+---
+
+Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+---
+
+## Assess Current Layout
+
+Analyze what's weak about the current spatial design:
+
+1. **Spacing**:
+ - Is spacing consistent or arbitrary? (Random padding/margin values)
+ - Is all spacing the same? (Equal padding everywhere = no rhythm)
+ - Are related elements grouped tightly, with generous space between groups?
+
+2. **Visual hierarchy**:
+ - Apply the squint test: blur your (metaphorical) eyes — can you still identify the most important element, second most important, and clear groupings?
+ - Is hierarchy achieved effectively? (Space and weight alone can be enough — but is the current approach working?)
+ - Does whitespace guide the eye to what matters?
+
+3. **Grid & structure**:
+ - Is there a clear underlying structure, or does the layout feel random?
+ - Are identical card grids used everywhere? (Icon + heading + text, repeated endlessly)
+ - Is everything centered? (Left-aligned with asymmetric layouts feels more designed, but not a hard and fast rule)
+
+4. **Rhythm & variety**:
+ - Does the layout have visual rhythm? (Alternating tight/generous spacing)
+ - Is every section structured the same way? (Monotonous repetition)
+ - Are there intentional moments of surprise or emphasis?
+
+5. **Density**:
+ - Is the layout too cramped? (Not enough breathing room)
+ - Is the layout too sparse? (Excessive whitespace without purpose)
+ - Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
+
+**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material — use it with intention.
+
+## Plan Layout Improvements
+
+Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries.
+
+Create a systematic plan:
+
+- **Spacing system**: Use a consistent scale — whether that's a framework's built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency.
+- **Hierarchy strategy**: How will space communicate importance?
+- **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
+- **Rhythm**: Where should spacing be tight vs generous?
+
+## Improve Layout Systematically
+
+### Establish a Spacing System
+
+- Use a consistent spacing scale — framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers.
+- Name tokens semantically if using custom properties: `--space-xs` through `--space-xl`, not `--spacing-8`
+- Use `gap` for sibling spacing instead of margins — eliminates margin collapse hacks
+- Apply `clamp()` for fluid spacing that breathes on larger screens
+
+### Create Visual Rhythm
+
+- **Tight grouping** for related elements (8-12px between siblings)
+- **Generous separation** between distinct sections (48-96px)
+- **Varied spacing** within sections — not every row needs the same gap
+- **Asymmetric compositions** — break the predictable centered-content pattern when it makes sense
+
+### Choose the Right Layout Tool
+
+- **Use Flexbox for 1D layouts**: Rows of items, nav bars, button groups, card contents, most component internals. Flex is simpler and more appropriate for the majority of layout tasks.
+- **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
+- **Don't default to Grid** when Flexbox with `flex-wrap` would be simpler and more flexible.
+- Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints.
+- Use named grid areas (`grid-template-areas`) for complex page layouts — redefine at breakpoints.
+
+### Break Card Grid Monotony
+
+- Don't default to card grids for everything — spacing and alignment create visual grouping naturally
+- Use cards only when content is truly distinct and actionable — never nest cards inside cards
+- Vary card sizes, span columns, or mix cards with non-card content to break repetition
+
+### Strengthen Visual Hierarchy
+
+- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough — generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
+- Be aware of reading flow — in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
+- Create clear content groupings through proximity and separation.
+
+### Manage Depth & Elevation
+
+- Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip)
+- Build a consistent shadow scale (sm → md → lg → xl) — shadows should be subtle
+- Use elevation to reinforce hierarchy, not as decoration
+
+### Optical Adjustments
+
+- If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively.
+
+**NEVER**:
+- Use arbitrary spacing values outside your scale
+- Make all spacing equal — variety creates hierarchy
+- Wrap everything in cards — not everything needs a container
+- Nest cards inside cards — use spacing and dividers for hierarchy within
+- Use identical card grids everywhere (icon + heading + text, repeated)
+- Center everything — left-aligned with asymmetry feels more designed
+- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work — but it should display actual data, not decorative numbers.
+- Default to CSS Grid when Flexbox would be simpler — use the simplest tool for the job
+- Use arbitrary z-index values (999, 9999) — build a semantic scale
+
+## Verify Layout Improvements
+
+- **Squint test**: Can you identify primary, secondary, and groupings with blurred vision?
+- **Rhythm**: Does the page have a satisfying beat of tight and generous spacing?
+- **Hierarchy**: Is the most important content obvious within 2 seconds?
+- **Breathing room**: Does the layout feel comfortable, not cramped or wasteful?
+- **Consistency**: Is the spacing system applied uniformly?
+- **Responsiveness**: Does the layout adapt gracefully across screen sizes?
+
+Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.
\ No newline at end of file
diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/audit/SKILL.md
index e1ae379e2..e1711a94e 100644
--- a/.claude/skills/audit/SKILL.md
+++ b/.claude/skills/audit/SKILL.md
@@ -71,7 +71,7 @@ For each issue, document:
- **Impact**: How it affects users
- **WCAG/Standard**: Which standard it violates (if applicable)
- **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /critique, /colorize — or other installed skills you're sure exist)
+- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist)
#### Critical Issues
[Issues that block core functionality or violate WCAG A]
@@ -108,7 +108,7 @@ Create actionable plan:
### Suggested Commands for Fixes
-Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /critique, /colorize. You may also suggest other installed skills you're sure exist, but never invent commands.
+Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands.
Examples:
- "Use `/normalize` to align with design system (addresses N theming issues)"
diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md
index eb0d663b9..de81a8107 100644
--- a/.claude/skills/critique/SKILL.md
+++ b/.claude/skills/critique/SKILL.md
@@ -102,7 +102,7 @@ For each issue:
- **What**: Name the problem clearly
- **Why it matters**: How this hurts users or undermines goals
- **Fix**: What to do about it (be concrete)
-- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /critique, /colorize — or other installed skills you're sure exist)
+- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist)
### Minor Observations
Quick notes on smaller issues worth addressing.
diff --git a/.claude/skills/overdrive/SKILL.md b/.claude/skills/overdrive/SKILL.md
new file mode 100644
index 000000000..c3f1bb0cd
--- /dev/null
+++ b/.claude/skills/overdrive/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: overdrive
+description: Push interfaces past conventional limits with technically ambitious implementations. Whether that's a shader, a 60fps virtual table, spring physics on a dialog, or scroll-driven reveals — make users ask "how did they do that?"
+user-invokable: true
+args:
+ - name: target
+ description: The feature or area to push into overdrive (optional)
+ required: false
+---
+
+Start your response with:
+
+```
+──────────── ⚡ OVERDRIVE ─────────────
+》》》 Entering overdrive mode...
+```
+
+Push an interface past conventional limits. This isn't just about visual effects — it's about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+**EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate.
+
+### Propose Before Building
+
+This skill has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:
+
+1. **Think through 2-3 different directions** — consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
+2. **STOP and call the AskUserQuestion tool to clarify.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
+3. Only proceed with the direction the user confirms.
+
+Skipping this step risks building something embarrassing that needs to be thrown away.
+
+### Iterate with Browser Automation
+
+Technically ambitious effects almost never work on the first try. You MUST actively use browser automation tools to preview your work, visually verify the result, and iterate. Do not assume the effect looks right — check it. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.
+
+---
+
+## Assess What "Extraordinary" Means Here
+
+The right kind of technical ambition depends entirely on what you're working with. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that's nice"?**
+
+### For visual/marketing surfaces
+Pages, hero sections, landing pages, portfolios — the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
+
+### For functional UI
+Tables, forms, dialogs, navigation — the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
+
+### For performance-critical UI
+The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface just never hesitates.
+
+### For data-heavy interfaces
+Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
+
+**The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around.
+
+## The Toolkit
+
+Organized by what you're trying to achieve, not by technology name.
+
+### Make transitions feel cinematic
+- **View Transitions API** (same-document: all browsers; cross-document: no Firefox) — shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
+- **`@starting-style`** (all browsers) — animate elements from `display: none` to visible with CSS only, including entry keyframes
+- **Spring physics** — natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.
+
+### Tie animation to scroll position
+- **Scroll-driven animations** (`animation-timeline: scroll()`) — CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only — always provide a static fallback)
+
+### Render beyond CSS
+- **WebGL** (all browsers) — shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express.
+- **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only) — next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
+- **Canvas 2D / OffscreenCanvas** — custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas.
+- **SVG filter chains** — displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.
+
+### Make data feel alive
+- **Virtual scrolling** — render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones.
+- **GPU-accelerated charts** — Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers.
+- **Animated data transitions** — morph between chart states rather than replacing. D3's `transition()` or View Transitions for DOM-based charts.
+
+### Animate complex properties
+- **`@property`** (all browsers) — register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate.
+- **Web Animations API** (all browsers) — JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.
+
+### Push performance boundaries
+- **Web Workers** — move computation off the main thread. Heavy data processing, image manipulation, search indexing — anything that would cause jank.
+- **OffscreenCanvas** — render in a Worker thread. The main thread stays free while complex visuals render in the background.
+- **WASM** — near-native performance for computation-heavy features. Image processing, physics simulations, codecs.
+
+### Interact with the device
+- **Web Audio API** — spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
+- **Device APIs** — orientation, ambient light, geolocation. Use sparingly and always with user permission.
+
+**NOTE**: This skill is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
+
+## Implement with Discipline
+
+### Progressive enhancement is non-negotiable
+
+Every technique must degrade gracefully. The experience without the enhancement must still be good.
+
+```css
+@supports (animation-timeline: scroll()) {
+ .hero { animation-timeline: scroll(); }
+}
+```
+
+```javascript
+if ('gpu' in navigator) { /* WebGPU */ }
+else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ }
+/* CSS-only fallback must still look good */
+```
+
+### Performance rules
+
+- Target 60fps. If dropping below 50, simplify.
+- Respect `prefers-reduced-motion` — always. Provide a beautiful static alternative.
+- Lazy-initialize heavy resources (WebGL contexts, WASM modules) only when near viewport.
+- Pause off-screen rendering. Kill what you can't see.
+- Test on real mid-range devices, not just your development machine.
+
+### Polish is the difference
+
+The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works — ship the version that feels inevitable.
+
+**NEVER**:
+- Ignore `prefers-reduced-motion` — this is an accessibility requirement, not a suggestion
+- Ship effects that cause jank on mid-range devices
+- Use bleeding-edge APIs without a functional fallback
+- Add sound without explicit user opt-in
+- Use technical ambition to mask weak design fundamentals — fix those first with other skills
+- Layer multiple competing extraordinary moments — focus creates impact, excess creates noise
+
+## Verify the Result
+
+- **The wow test**: Show it to someone who hasn't seen it. Do they react?
+- **The removal test**: Take it away. Does the experience feel diminished, or does nobody notice?
+- **The device test**: Run it on a phone, a tablet, a Chromebook. Still smooth?
+- **The accessibility test**: Enable reduced motion. Still beautiful?
+- **The context test**: Does this make sense for THIS brand and audience?
+
+Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.
\ No newline at end of file
diff --git a/.claude/skills/typeset/SKILL.md b/.claude/skills/typeset/SKILL.md
new file mode 100644
index 000000000..d768c3f7b
--- /dev/null
+++ b/.claude/skills/typeset/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: typeset
+description: Improve typography by fixing font choices, hierarchy, sizing, weight consistency, and readability. Makes text feel intentional and polished.
+user-invokable: true
+args:
+ - name: target
+ description: The feature or component to improve typography for (optional)
+ required: false
+---
+
+Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+---
+
+## 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 fluid sizing used, or do sizes jump at breakpoints?
+
+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](reference/typography.md) from the frontend-design skill 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
+- **Use fluid sizing**: `clamp(min, preferred, max)` for smooth scaling
+
+### 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%?
+
+Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 452537e61..a5246fa5c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,3 +19,6 @@ Thumbs.db
# Environment
.env
.env.local
+
+# Cloudflare
+.wrangler/
diff --git a/AGENTS.md b/AGENTS.md
index 03e9b0a6b..60e29e45c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Impeccable
-The vocabulary you didn't know you needed. 1 skill, 17 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI.
+The vocabulary you didn't know you needed. 1 skill, 20 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI.
## Repository Purpose
diff --git a/CLAUDE.md b/CLAUDE.md
index 55507dd63..33de089a2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -50,3 +50,18 @@ When bumping the version, update **all** of these locations to keep them in sync
- `.claude-plugin/plugin.json` → `version`
- `.claude-plugin/marketplace.json` → `plugins[0].version`
- `public/index.html` → hero version link text + new changelog entry
+
+## Adding New Skills
+
+When adding a new user-invokable skill, update the command count in **all** of these locations:
+
+- `public/index.html` → meta descriptions, hero box, section lead
+- `public/cheatsheet.html` → meta description, subtitle, `commandCategories`, `commandRelationships`
+- `public/js/data.js` → `commandProcessSteps`, `commandCategories`, `commandRelationships`
+- `public/js/components/framework-viz.js` → `commandSymbols`, `commandNumbers`
+- `public/js/demos/commands/` → new demo file + import in `index.js`
+- `README.md` → intro, command count, commands table
+- `NOTICE.md` → steering commands count
+- `AGENTS.md` → intro command count
+- `.claude-plugin/plugin.json` → description
+- `.claude-plugin/marketplace.json` → metadata description + plugin description
diff --git a/NOTICE.md b/NOTICE.md
index 1920a3307..ddf948fa0 100644
--- a/NOTICE.md
+++ b/NOTICE.md
@@ -13,5 +13,5 @@ The `frontend-design` skill in this project builds on Anthropic's original front
This project extends the original with:
- 7 domain-specific reference files (typography, color-and-contrast, spatial-design, motion-design, interaction-design, responsive-design, ux-writing)
-- 17 steering commands
+- 20 steering commands
- Expanded patterns and anti-patterns
diff --git a/README.md b/README.md
index 973da610e..37c942024 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# Impeccable
-The vocabulary you didn't know you needed. 1 skill, 17 commands, and curated anti-patterns for impeccable frontend design.
+The vocabulary you didn't know you needed. 1 skill, 20 commands, and curated anti-patterns for impeccable frontend design.
> **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles.
@@ -12,7 +12,7 @@ Every LLM learned from the same generic templates. Without guidance, you get the
Impeccable fights that bias with:
- **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/frontend-design/))
-- **17 steering commands** to audit, review, polish, distill, animate, and more
+- **20 steering commands** to audit, review, polish, distill, animate, and more
- **Curated anti-patterns** that explicitly tell the AI what NOT to do
## What's Included
@@ -31,7 +31,7 @@ A comprehensive design skill with 7 domain-specific references ([view skill](sou
| [responsive-design](source/skills/frontend-design/reference/responsive-design.md) | Mobile-first, fluid design, container queries |
| [ux-writing](source/skills/frontend-design/reference/ux-writing.md) | Button labels, error messages, empty states |
-### 17 Commands
+### 20 Commands
| Command | What it does |
|---------|--------------|
@@ -52,6 +52,9 @@ A comprehensive design skill with 7 domain-specific references ([view skill](sou
| `/extract` | Pull into reusable components |
| `/adapt` | Adapt for different devices |
| `/onboard` | Design onboarding flows |
+| `/typeset` | Fix font choices, hierarchy, sizing |
+| `/arrange` | Fix layout, spacing, visual rhythm |
+| `/overdrive` | Add technically extraordinary effects |
### Anti-Patterns
diff --git a/package.json b/package.json
index 2262c1b2f..378ecc2f2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "impeccable",
- "version": "1.3.0",
+ "version": "1.5.0",
"author": "Paul Bakaus",
"dependencies": {
"archiver": "^7.0.1",
diff --git a/public/cheatsheet.html b/public/cheatsheet.html
index 179a09307..d0df0ea92 100644
--- a/public/cheatsheet.html
+++ b/public/cheatsheet.html
@@ -4,7 +4,7 @@
Impeccable Command Cheatsheet
-
+
@@ -160,7 +160,7 @@
The team completed the redesign of the dashboard. All components have been reviewed and approved by stakeholders.
+
Updated 2 hours ago
+
+ `,
+
+ after: `
+
+
Project Update
+
Q1 Design Sprint
+
The team completed the redesign of the dashboard. All components reviewed and approved.
+
Updated 2 hours ago
+
+ `
+};
diff --git a/public/js/effects/split-compare.js b/public/js/effects/split-compare.js
index b1e81d26a..d54071651 100644
--- a/public/js/effects/split-compare.js
+++ b/public/js/effects/split-compare.js
@@ -48,10 +48,27 @@ export function initSplitCompare(container, options = {}) {
}
function retriggerAnimations() {
- // Find all elements with animations in the "after" content and re-trigger them
+ // Re-trigger CSS animations in the "after" content.
+ // If there's a canvas (e.g. overdrive shader), we can't clone-and-replace
+ // because that destroys JS-driven animations. In that case, retrigger
+ // individual elements. Otherwise, use the fast clone approach.
const afterContent = splitAfter.querySelector('.split-content');
- if (afterContent) {
- // Clone and replace to restart all CSS animations
+ if (!afterContent) return;
+
+ const hasCanvas = afterContent.querySelector('canvas, .od-burn, .od-sparks');
+ if (hasCanvas) {
+ // Safe path: retrigger CSS animations individually, skip canvas
+ afterContent.querySelectorAll('*').forEach(el => {
+ if (el.tagName === 'CANVAS') return;
+ const anim = getComputedStyle(el).animationName;
+ if (anim && anim !== 'none') {
+ el.style.animation = 'none';
+ el.offsetHeight;
+ el.style.animation = '';
+ }
+ });
+ } else {
+ // Fast path: clone and replace to restart all CSS animations
const clone = afterContent.cloneNode(true);
afterContent.parentNode.replaceChild(clone, afterContent);
}
diff --git a/public/js/utils/scroll.js b/public/js/utils/scroll.js
index 4f31c06bd..ebe48b5a3 100644
--- a/public/js/utils/scroll.js
+++ b/public/js/utils/scroll.js
@@ -22,6 +22,21 @@ export function initHashTracking() {
let ticking = false;
function updateHash() {
+ // Don't override command deep links while user is in the commands section
+ if (currentHash.startsWith('cmd-')) {
+ const cmdEl = document.getElementById(currentHash);
+ if (cmdEl) {
+ const rect = cmdEl.getBoundingClientRect();
+ // Only clear the cmd hash if user scrolled well away from commands section
+ if (rect.top > window.innerHeight * 2 || rect.bottom < -window.innerHeight) {
+ currentHash = '';
+ } else {
+ ticking = false;
+ return;
+ }
+ }
+ }
+
const scrollY = window.scrollY;
const viewportHeight = window.innerHeight;
const triggerPoint = scrollY + viewportHeight * 0.3;
@@ -38,6 +53,9 @@ export function initHashTracking() {
}
});
+ // Don't set #hero — it's the default state, no hash needed
+ if (activeSection === 'hero') activeSection = '';
+
if (activeSection !== currentHash) {
currentHash = activeSection;
if (activeSection) {
@@ -59,17 +77,23 @@ export function initHashTracking() {
// Handle initial hash on page load - instant jump
if (window.location.hash) {
- const target = document.querySelector(window.location.hash);
+ const hash = window.location.hash.slice(1);
+ const target = document.getElementById(hash);
if (target) {
+ currentHash = hash;
setTimeout(() => {
const offset = 40;
const targetPosition = target.getBoundingClientRect().top + window.scrollY - offset;
window.scrollTo({ top: targetPosition, behavior: 'auto' });
+
+ // If it's a command deep link, activate it
+ if (hash.startsWith('cmd-') && target.classList.contains('manual-entry')) {
+ target.click();
+ }
}, 100);
}
+ } else {
+ // No hash — don't set one on initial load
}
-
- // Initial check
- updateHash();
}
diff --git a/source/skills/arrange/SKILL.md b/source/skills/arrange/SKILL.md
new file mode 100644
index 000000000..98eaea2b9
--- /dev/null
+++ b/source/skills/arrange/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: arrange
+description: Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy to create intentional compositions.
+args:
+ - name: target
+ description: The feature or component to improve layout for (optional)
+ required: false
+user-invokable: true
+---
+
+Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+---
+
+## Assess Current Layout
+
+Analyze what's weak about the current spatial design:
+
+1. **Spacing**:
+ - Is spacing consistent or arbitrary? (Random padding/margin values)
+ - Is all spacing the same? (Equal padding everywhere = no rhythm)
+ - Are related elements grouped tightly, with generous space between groups?
+
+2. **Visual hierarchy**:
+ - Apply the squint test: blur your (metaphorical) eyes — can you still identify the most important element, second most important, and clear groupings?
+ - Is hierarchy achieved effectively? (Space and weight alone can be enough — but is the current approach working?)
+ - Does whitespace guide the eye to what matters?
+
+3. **Grid & structure**:
+ - Is there a clear underlying structure, or does the layout feel random?
+ - Are identical card grids used everywhere? (Icon + heading + text, repeated endlessly)
+ - Is everything centered? (Left-aligned with asymmetric layouts feels more designed, but not a hard and fast rule)
+
+4. **Rhythm & variety**:
+ - Does the layout have visual rhythm? (Alternating tight/generous spacing)
+ - Is every section structured the same way? (Monotonous repetition)
+ - Are there intentional moments of surprise or emphasis?
+
+5. **Density**:
+ - Is the layout too cramped? (Not enough breathing room)
+ - Is the layout too sparse? (Excessive whitespace without purpose)
+ - Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
+
+**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material — use it with intention.
+
+## Plan Layout Improvements
+
+Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries.
+
+Create a systematic plan:
+
+- **Spacing system**: Use a consistent scale — whether that's a framework's built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency.
+- **Hierarchy strategy**: How will space communicate importance?
+- **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
+- **Rhythm**: Where should spacing be tight vs generous?
+
+## Improve Layout Systematically
+
+### Establish a Spacing System
+
+- Use a consistent spacing scale — framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers.
+- Name tokens semantically if using custom properties: `--space-xs` through `--space-xl`, not `--spacing-8`
+- Use `gap` for sibling spacing instead of margins — eliminates margin collapse hacks
+- Apply `clamp()` for fluid spacing that breathes on larger screens
+
+### Create Visual Rhythm
+
+- **Tight grouping** for related elements (8-12px between siblings)
+- **Generous separation** between distinct sections (48-96px)
+- **Varied spacing** within sections — not every row needs the same gap
+- **Asymmetric compositions** — break the predictable centered-content pattern when it makes sense
+
+### Choose the Right Layout Tool
+
+- **Use Flexbox for 1D layouts**: Rows of items, nav bars, button groups, card contents, most component internals. Flex is simpler and more appropriate for the majority of layout tasks.
+- **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
+- **Don't default to Grid** when Flexbox with `flex-wrap` would be simpler and more flexible.
+- Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints.
+- Use named grid areas (`grid-template-areas`) for complex page layouts — redefine at breakpoints.
+
+### Break Card Grid Monotony
+
+- Don't default to card grids for everything — spacing and alignment create visual grouping naturally
+- Use cards only when content is truly distinct and actionable — never nest cards inside cards
+- Vary card sizes, span columns, or mix cards with non-card content to break repetition
+
+### Strengthen Visual Hierarchy
+
+- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough — generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
+- Be aware of reading flow — in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
+- Create clear content groupings through proximity and separation.
+
+### Manage Depth & Elevation
+
+- Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip)
+- Build a consistent shadow scale (sm → md → lg → xl) — shadows should be subtle
+- Use elevation to reinforce hierarchy, not as decoration
+
+### Optical Adjustments
+
+- If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively.
+
+**NEVER**:
+- Use arbitrary spacing values outside your scale
+- Make all spacing equal — variety creates hierarchy
+- Wrap everything in cards — not everything needs a container
+- Nest cards inside cards — use spacing and dividers for hierarchy within
+- Use identical card grids everywhere (icon + heading + text, repeated)
+- Center everything — left-aligned with asymmetry feels more designed
+- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work — but it should display actual data, not decorative numbers.
+- Default to CSS Grid when Flexbox would be simpler — use the simplest tool for the job
+- Use arbitrary z-index values (999, 9999) — build a semantic scale
+
+## Verify Layout Improvements
+
+- **Squint test**: Can you identify primary, secondary, and groupings with blurred vision?
+- **Rhythm**: Does the page have a satisfying beat of tight and generous spacing?
+- **Hierarchy**: Is the most important content obvious within 2 seconds?
+- **Breathing room**: Does the layout feel comfortable, not cramped or wasteful?
+- **Consistency**: Is the spacing system applied uniformly?
+- **Responsiveness**: Does the layout adapt gracefully across screen sizes?
+
+Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.
diff --git a/source/skills/overdrive/SKILL.md b/source/skills/overdrive/SKILL.md
new file mode 100644
index 000000000..b600d3938
--- /dev/null
+++ b/source/skills/overdrive/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: overdrive
+description: Push interfaces past conventional limits with technically ambitious implementations. Whether that's a shader, a 60fps virtual table, spring physics on a dialog, or scroll-driven reveals — make users ask "how did they do that?"
+args:
+ - name: target
+ description: The feature or area to push into overdrive (optional)
+ required: false
+user-invokable: true
+---
+
+Start your response with:
+
+```
+──────────── ⚡ OVERDRIVE ─────────────
+》》》 Entering overdrive mode...
+```
+
+Push an interface past conventional limits. This isn't just about visual effects — it's about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+**EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate.
+
+### Propose Before Building
+
+This skill has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:
+
+1. **Think through 2-3 different directions** — consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
+2. **{{ask_instruction}}** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
+3. Only proceed with the direction the user confirms.
+
+Skipping this step risks building something embarrassing that needs to be thrown away.
+
+### Iterate with Browser Automation
+
+Technically ambitious effects almost never work on the first try. You MUST actively use browser automation tools to preview your work, visually verify the result, and iterate. Do not assume the effect looks right — check it. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.
+
+---
+
+## Assess What "Extraordinary" Means Here
+
+The right kind of technical ambition depends entirely on what you're working with. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that's nice"?**
+
+### For visual/marketing surfaces
+Pages, hero sections, landing pages, portfolios — the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
+
+### For functional UI
+Tables, forms, dialogs, navigation — the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
+
+### For performance-critical UI
+The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface just never hesitates.
+
+### For data-heavy interfaces
+Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
+
+**The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around.
+
+## The Toolkit
+
+Organized by what you're trying to achieve, not by technology name.
+
+### Make transitions feel cinematic
+- **View Transitions API** (same-document: all browsers; cross-document: no Firefox) — shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
+- **`@starting-style`** (all browsers) — animate elements from `display: none` to visible with CSS only, including entry keyframes
+- **Spring physics** — natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.
+
+### Tie animation to scroll position
+- **Scroll-driven animations** (`animation-timeline: scroll()`) — CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only — always provide a static fallback)
+
+### Render beyond CSS
+- **WebGL** (all browsers) — shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express.
+- **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only) — next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
+- **Canvas 2D / OffscreenCanvas** — custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas.
+- **SVG filter chains** — displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.
+
+### Make data feel alive
+- **Virtual scrolling** — render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones.
+- **GPU-accelerated charts** — Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers.
+- **Animated data transitions** — morph between chart states rather than replacing. D3's `transition()` or View Transitions for DOM-based charts.
+
+### Animate complex properties
+- **`@property`** (all browsers) — register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate.
+- **Web Animations API** (all browsers) — JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.
+
+### Push performance boundaries
+- **Web Workers** — move computation off the main thread. Heavy data processing, image manipulation, search indexing — anything that would cause jank.
+- **OffscreenCanvas** — render in a Worker thread. The main thread stays free while complex visuals render in the background.
+- **WASM** — near-native performance for computation-heavy features. Image processing, physics simulations, codecs.
+
+### Interact with the device
+- **Web Audio API** — spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
+- **Device APIs** — orientation, ambient light, geolocation. Use sparingly and always with user permission.
+
+**NOTE**: This skill is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
+
+## Implement with Discipline
+
+### Progressive enhancement is non-negotiable
+
+Every technique must degrade gracefully. The experience without the enhancement must still be good.
+
+```css
+@supports (animation-timeline: scroll()) {
+ .hero { animation-timeline: scroll(); }
+}
+```
+
+```javascript
+if ('gpu' in navigator) { /* WebGPU */ }
+else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ }
+/* CSS-only fallback must still look good */
+```
+
+### Performance rules
+
+- Target 60fps. If dropping below 50, simplify.
+- Respect `prefers-reduced-motion` — always. Provide a beautiful static alternative.
+- Lazy-initialize heavy resources (WebGL contexts, WASM modules) only when near viewport.
+- Pause off-screen rendering. Kill what you can't see.
+- Test on real mid-range devices, not just your development machine.
+
+### Polish is the difference
+
+The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works — ship the version that feels inevitable.
+
+**NEVER**:
+- Ignore `prefers-reduced-motion` — this is an accessibility requirement, not a suggestion
+- Ship effects that cause jank on mid-range devices
+- Use bleeding-edge APIs without a functional fallback
+- Add sound without explicit user opt-in
+- Use technical ambition to mask weak design fundamentals — fix those first with other skills
+- Layer multiple competing extraordinary moments — focus creates impact, excess creates noise
+
+## Verify the Result
+
+- **The wow test**: Show it to someone who hasn't seen it. Do they react?
+- **The removal test**: Take it away. Does the experience feel diminished, or does nobody notice?
+- **The device test**: Run it on a phone, a tablet, a Chromebook. Still smooth?
+- **The accessibility test**: Enable reduced motion. Still beautiful?
+- **The context test**: Does this make sense for THIS brand and audience?
+
+Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.
diff --git a/source/skills/typeset/SKILL.md b/source/skills/typeset/SKILL.md
new file mode 100644
index 000000000..2bf23e183
--- /dev/null
+++ b/source/skills/typeset/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: typeset
+description: Improve typography by fixing font choices, hierarchy, sizing, weight consistency, and readability. Makes text feel intentional and polished.
+args:
+ - name: target
+ description: The feature or component to improve typography for (optional)
+ required: false
+user-invokable: true
+---
+
+Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+---
+
+## 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 fluid sizing used, or do sizes jump at breakpoints?
+
+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](reference/typography.md) from the frontend-design skill 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
+- **Use fluid sizing**: `clamp(min, preferred, max)` for smooth scaling
+
+### 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%?
+
+Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.