From faa7453db7065c8a484eaef156179d41285ba17c Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Thu, 9 Apr 2026 20:39:02 -0700 Subject: [PATCH] Consolidate skills from 21 to 18: rename, merge, and fold - Rename /arrange to /layout for clarity - Merge /normalize into /polish (design system discovery + cleanup phases) - Merge /onboard into /harden (onboarding, empty states, progressive disclosure) - Fold /extract into /impeccable extract sub-mode (reference file, sidebar link) - Update all counts, cross-references, data files, demos, and metadata - Remove System category (now empty) Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 4 +- .claude-plugin/plugin.json | 2 +- AGENTS.md | 2 +- NOTICE.md | 2 +- README.md | 17 ++- content/site/skills/audit.md | 4 +- content/site/skills/bolder.md | 2 +- content/site/skills/distill.md | 2 +- content/site/skills/harden.md | 9 +- content/site/skills/impeccable.md | 4 + content/site/skills/layout.md | 41 ++++++ content/site/skills/polish.md | 8 +- content/site/skills/typeset.md | 2 +- public/cheatsheet.html | 30 ++--- public/index.html | 18 +-- public/js/components/framework-viz.js | 21 ++- public/js/components/glass-terminal.js | 2 +- public/js/data.js | 41 +++--- public/js/demos/commands/index.js | 13 +- public/js/demos/commands/layout.js | 47 +++++++ scripts/build-sub-pages.js | 5 +- scripts/lib/sub-pages-data.js | 12 +- source/skills/harden/SKILL.md | 36 ++++- source/skills/impeccable/SKILL.md | 10 +- source/skills/impeccable/reference/extract.md | 70 ++++++++++ source/skills/layout/SKILL.md | 124 ++++++++++++++++++ source/skills/polish/SKILL.md | 21 +++ 27 files changed, 437 insertions(+), 112 deletions(-) create mode 100644 content/site/skills/layout.md create mode 100644 public/js/demos/commands/layout.js create mode 100644 source/skills/impeccable/reference/extract.md create mode 100644 source/skills/layout/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9b5762125..c75d428d0 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, 21 commands, and curated anti-patterns for impeccable frontend design." + "description": "Design fluency for AI harnesses. 1 skill, 18 commands, and curated anti-patterns for impeccable frontend design." }, "owner": { "name": "Paul Bakaus", @@ -11,7 +11,7 @@ "plugins": [ { "name": "impeccable", - "description": "Design vocabulary and skills for frontend development. Includes 21 commands (/polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced impeccable skill with curated anti-patterns.", + "description": "Design vocabulary and skills for frontend development. Includes 18 commands (/polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced impeccable skill with curated anti-patterns.", "version": "2.0.7", "author": { "name": "Paul Bakaus", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ea500e5fe..e9b1e89c0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "impeccable", - "description": "Design vocabulary and skills for frontend development. Includes 21 commands (/polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced impeccable skill with curated anti-patterns.", + "description": "Design vocabulary and skills for frontend development. Includes 18 commands (/polish, /distill, /audit, /typeset, /overdrive, etc.) and an enhanced impeccable skill with curated anti-patterns.", "version": "2.0.7", "author": { "name": "Paul Bakaus", diff --git a/AGENTS.md b/AGENTS.md index 291dea674..54a0d2c35 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Impeccable -The vocabulary you didn't know you needed. 1 skill, 21 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, 18 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI. ## Repository Purpose diff --git a/NOTICE.md b/NOTICE.md index f48a8a8bc..04be4620b 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -13,5 +13,5 @@ The `impeccable` skill in this project builds on Anthropic's original frontend-d 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) -- 21 steering commands +- 18 steering commands - Expanded patterns and anti-patterns diff --git a/README.md b/README.md index 8d4455d74..fdbe50d19 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Impeccable -The vocabulary you didn't know you needed. 1 skill, 21 commands, and curated anti-patterns for impeccable frontend design. +The vocabulary you didn't know you needed. 1 skill, 18 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/impeccable/)) -- **21 steering commands** to audit, review, polish, distill, animate, and more +- **18 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,29 +31,28 @@ A comprehensive design skill with 7 domain-specific references ([view skill](sou | [responsive-design](source/skills/impeccable/reference/responsive-design.md) | Mobile-first, fluid design, container queries | | [ux-writing](source/skills/impeccable/reference/ux-writing.md) | Button labels, error messages, empty states | -### 21 Commands +### 18 Commands | Command | What it does | |---------|--------------| | `/impeccable teach` | One-time setup: gather design context, save to config | +| `/impeccable craft` | Full shape-then-build flow with visual iteration | +| `/impeccable extract` | Pull reusable components and tokens into the design system | | `/audit` | Run technical quality checks (a11y, performance, responsive) | | `/critique` | UX design review: hierarchy, clarity, emotional resonance | -| `/normalize` | Align with design system standards | -| `/polish` | Final pass before shipping | +| `/polish` | Final pass, design system alignment, and shipping readiness | | `/distill` | Strip to essence | | `/clarify` | Improve unclear UX copy | | `/optimize` | Performance improvements | -| `/harden` | Error handling, i18n, edge cases | +| `/harden` | Error handling, onboarding, i18n, edge cases | | `/animate` | Add purposeful motion | | `/colorize` | Introduce strategic color | | `/bolder` | Amplify boring designs | | `/quieter` | Tone down overly bold designs | | `/delight` | Add moments of joy | -| `/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 | +| `/layout` | Fix layout, spacing, visual rhythm | | `/overdrive` | Add technically extraordinary effects | #### Usage Examples diff --git a/content/site/skills/audit.md b/content/site/skills/audit.md index e4a0891ab..b1e340636 100644 --- a/content/site/skills/audit.md +++ b/content/site/skills/audit.md @@ -20,7 +20,7 @@ The skill scans your code across five dimensions: Each dimension gets a 0 to 4 score. Each finding gets a severity: P0 blocks the release, P1 should fix this sprint, P2 is next cycle, P3 is polish. You get back a single document you can paste into a ticket tracker. -Audit does not fix anything. It documents. Route the findings to `/polish`, `/harden`, `/normalize`, or `/optimize` depending on the category. +Audit does not fix anything. It documents. Route the findings to `/polish`, `/harden`, or `/optimize` depending on the category. ## Try it @@ -41,7 +41,7 @@ Performance: 3/4 (good) ... ``` -Hand the P0s to `/harden`, the theming and typography P1s to `/normalize` and `/typeset`, the rest to `/polish`. +Hand the P0s to `/harden`, the theming and typography P1s to `/typeset` and `/polish`, the rest to `/polish`. ## Pitfalls diff --git a/content/site/skills/bolder.md b/content/site/skills/bolder.md index 2445c097d..f636e03d8 100644 --- a/content/site/skills/bolder.md +++ b/content/site/skills/bolder.md @@ -35,6 +35,6 @@ Expected changes: ## Pitfalls -- **Running it on the wrong page.** Product dashboards, settings, and forms should not be bold. They should be legible. Use `/arrange` or `/polish` instead. +- **Running it on the wrong page.** Product dashboards, settings, and forms should not be bold. They should be legible. Use `/layout` or `/polish` instead. - **Confusing bold with loud.** Bold means committed and confident. Loud means shouting. Bolder is the former. If the result feels aggressive, follow up with `/quieter`. - **Pairing it with `/delight` in the same pass.** Delight works best against a stable visual baseline. Bold first, stabilize, then delight. diff --git a/content/site/skills/distill.md b/content/site/skills/distill.md index 422d4fb53..d8a112f15 100644 --- a/content/site/skills/distill.md +++ b/content/site/skills/distill.md @@ -41,4 +41,4 @@ Fewer things. Each one clearer. - **Confusing distill with delete.** Distill removes obstacles. It does not remove features users need. If a user relies on something daily, find a way to keep it quietly, not a way to cut it. - **Running it too early.** If the feature is still growing, distilling it now means distilling the same thing again next week. Wait until the shape is stable. -- **Expecting it to replace hierarchy work.** Sometimes the right fix is not removing things, it is arranging them. Reach for `/arrange` when the problem is layout, not quantity. +- **Expecting it to replace hierarchy work.** Sometimes the right fix is not removing things, it is arranging them. Reach for `/layout` when the problem is layout, not quantity. diff --git a/content/site/skills/harden.md b/content/site/skills/harden.md index 88a892bce..d2c498a0d 100644 --- a/content/site/skills/harden.md +++ b/content/site/skills/harden.md @@ -1,5 +1,5 @@ --- -tagline: "Make interfaces production-ready. Edge cases, i18n, error states, overflow." +tagline: "Make interfaces production-ready. Edge cases, onboarding, i18n, error states, overflow." --- ## When to use it @@ -10,12 +10,13 @@ Reach for it before launch, before opening to a new market, or any time a bug re ## How it works -The skill works through four dimensions of real-world resilience: +The skill works through five dimensions of real-world resilience: 1. **Text and data extremes**. Long text, short text, special characters, emoji, RTL, numbers in the billions, 1000-item lists, zero-data empty states. 2. **Error scenarios**. Network failures, API 4xx/5xx, validation errors, permission errors, rate limits, concurrent operations. 3. **Internationalization**. Long translations (German is often 30% longer than English), RTL languages, date and number formats, currency symbols, character sets. -4. **Device and context**. Touch targets, offline behavior, slow connections, low-power mode. +4. **Onboarding and empty states**. First-run experiences, empty state design, progressive disclosure, feature discovery. Making the feature work for someone who has never seen it before. +5. **Device and context**. Touch targets, offline behavior, slow connections, low-power mode. For each dimension it identifies the failure mode, then applies the concrete fix: overflow handling, proper empty states, informative error UI, i18n-safe layouts, pluralization, sensible fallbacks. @@ -40,5 +41,5 @@ Run it per-page, not all at once. The first run is the biggest; subsequent runs ## Pitfalls - **Waiting for a bug report.** Harden is preventative. If you find yourself fixing the same class of bug twice, run `/harden` across the feature. -- **Treating error states as an afterthought.** Most hardening work is error UI. Budget time for it, not just a `catch` block. +- **Treating error and empty states as an afterthought.** Most hardening work is error and empty state UI. Budget time for it, not just a `catch` block. - **Skipping i18n because "we are English-only for now".** i18n-safe layouts are still better layouts. Flexible containers, proper text wrapping, generous line-height. None of that hurts English. diff --git a/content/site/skills/impeccable.md b/content/site/skills/impeccable.md index a44b79f65..c151883e2 100644 --- a/content/site/skills/impeccable.md +++ b/content/site/skills/impeccable.md @@ -16,6 +16,10 @@ The full shape-then-build flow. It starts by running `/shape` internally (a stru One-time project setup. Runs a short discovery interview about your brand, audience, and aesthetic direction, then writes a `.impeccable.md` file that every future skill call reads automatically. Run this once per project before doing any design work. +### /impeccable extract {#extract} + +Pull reusable components, design tokens, and patterns out of your code and into the design system. Finds repeated UI patterns (buttons in 12 places, three card variants, scattered hex colors), extracts them into shared primitives, and migrates all callers. Best used after a product has shipped enough features to reveal the patterns -- premature extraction creates abstractions that do not match reality. + ## How it works Most AI-generated UIs fail the same way: generic fonts, purple gradients, card grids on card grids, glassmorphism everywhere. `/impeccable` gives your AI a strong point of view. It loads an opinionated design handbook plus a long list of anti-patterns, then pushes the model to commit to a specific aesthetic direction before writing a single line of code. diff --git a/content/site/skills/layout.md b/content/site/skills/layout.md new file mode 100644 index 000000000..8af09fa28 --- /dev/null +++ b/content/site/skills/layout.md @@ -0,0 +1,41 @@ +--- +tagline: "Fix layout, spacing, and visual rhythm." +--- + +## When to use it + +`/layout` is for pages where nothing is technically wrong but nothing is breathing either. Equal padding everywhere, monotonous card grids, content that runs edge to edge, hierarchy that relies on size alone. Reach for it when a layout "feels off" and you cannot articulate why. + +Good triggers: "everything feels crowded", "it reads like a wall", "I do not know where to look first". + +## How it works + +The skill runs through five layout dimensions: + +1. **Spacing**: is the spacing scale consistent or are there random 13px gaps, are related elements grouped tightly with generous space between groups, is there any rhythm at all. +2. **Visual hierarchy**: does the eye land on the primary action within 2 seconds, is the hierarchy doing real work or is everything shouting. +3. **Grid and structure**: is there an underlying grid or is the layout random, are elements aligned to baselines. +4. **Rhythm**: does the page alternate between tight and generous spacing, or is everything uniform. +5. **Density**: is the layout cramped or is it wasteful, does density match the content type. + +Fixes usually involve rebuilding the spacing scale, introducing asymmetry, collapsing monotonous grids into a mixed layout with hero and supporting elements, and giving the primary action real space. + +## Try it + +``` +/layout the settings page +``` + +Typical changes: + +- Spacing scale unified to 8 / 16 / 24 / 48 / 96px +- Section breaks at 48px, row gaps at 16px, form field groups at 8px +- Primary actions pulled out of the form flow with 32px buffer +- Decorative borders removed, replaced with spacing-driven grouping +- Sidebar and main column proportions rebalanced (280 / flex vs 25 / 75) + +## Pitfalls + +- **Confusing arrange with distill.** If the problem is too many things, run `/distill` first. Layout is for arranging what is already the right set. +- **Expecting it to rescue a broken grid.** If the page has no grid at all, arrange will build one. Just know that the diff is going to be larger than you expect. +- **Ignoring the hierarchy verdict.** If arrange says "nothing is primary", no amount of spacing work fixes that. You need a content decision, not a layout tweak. diff --git a/content/site/skills/polish.md b/content/site/skills/polish.md index 2956f6585..048957757 100644 --- a/content/site/skills/polish.md +++ b/content/site/skills/polish.md @@ -4,13 +4,13 @@ tagline: "The meticulous final pass between good and great." ## When to use it -`/polish` is the last thing you run before shipping. It hunts down the small details that separate a shipped feature from a polished one: half-pixel misalignments, inconsistent spacing, forgotten focus states, loading transitions that flash, copy that drifts in tone. +`/polish` is the last thing you run before shipping. It hunts down the small details that separate a shipped feature from a polished one: half-pixel misalignments, inconsistent spacing, forgotten focus states, loading transitions that flash, copy that drifts in tone. It also aligns the feature with your design system -- replacing hard-coded values with tokens, swapping custom components for shared ones, and fixing any drift from established patterns. -Reach for it when the feature is functionally complete, nothing is broken, and something still feels off. +Reach for it when the feature is functionally complete, nothing is broken, and something still feels off. Also reach for it when a feature has drifted from the design system and needs to be pulled back in line. ## How it works -Polish works methodically across six dimensions: +Polish starts by discovering the design system (tokens, spacing scale, shared components), then works methodically across six dimensions: 1. **Visual alignment and spacing**: pixel-perfect grid adherence, consistent spacing scale, optical alignment on icons. 2. **Typography**: hierarchy consistency, line length, widows and orphans, kerning on headlines. @@ -42,5 +42,5 @@ Five small fixes, no rewrites. That is the shape of a good polish pass. ## Pitfalls - **Polishing work that is not done.** If there are TODOs in the code, you are not ready. Run `/polish` on finished features only. -- **Treating polish as redesign.** Polish refines what exists. If you find yourself rearchitecting a layout, you needed `/critique` or `/arrange` instead. +- **Treating polish as redesign.** Polish refines what exists. If you find yourself rearchitecting a layout, you needed `/critique` or `/layout` instead. - **Running `/polish` without `/audit` first.** Polish catches feel-based issues. Audit catches measurable ones. Use both. diff --git a/content/site/skills/typeset.md b/content/site/skills/typeset.md index 079661297..feb656821 100644 --- a/content/site/skills/typeset.md +++ b/content/site/skills/typeset.md @@ -38,5 +38,5 @@ Expected diff: ## Pitfalls - **Asking for a new font without context.** Typeset will pick based on the `.impeccable.md` brand voice. If you have not run `/impeccable teach`, the suggestion will be generic. -- **Reaching for typeset when the issue is layout.** If paragraphs are fine but the page feels cramped, you want `/arrange`. +- **Reaching for typeset when the issue is layout.** If paragraphs are fine but the page feels cramped, you want `/layout`. - **Expecting fluid clamp scales on app UIs.** Typeset uses fixed rem scales for app interfaces. Fluid typography is for marketing and content pages where line length varies dramatically. diff --git a/public/cheatsheet.html b/public/cheatsheet.html index cdd7f4add..5cb8cef64 100644 --- a/public/cheatsheet.html +++ b/public/cheatsheet.html @@ -13,7 +13,7 @@ Impeccable Command Cheatsheet - + @@ -188,7 +188,7 @@

Impeccable Commands

-

Quick reference for all 21 design commands

+

Quick reference for all 18 design commands

@@ -215,7 +215,6 @@ 'impeccable': 'system', 'audit': 'diagnostic', 'critique': 'diagnostic', - 'normalize': 'quality', 'polish': 'quality', 'optimize': 'quality', 'harden': 'quality', @@ -226,34 +225,29 @@ 'animate': 'enhancement', 'colorize': 'enhancement', 'delight': 'enhancement', - 'extract': 'system', 'adapt': 'adaptation', - 'onboard': 'enhancement', 'typeset': 'enhancement', - 'arrange': 'enhancement', + 'layout': 'enhancement', 'overdrive': 'enhancement' }; const commandRelationships = { 'impeccable': { flow: 'One-time project context gathering' }, - 'audit': { leadsTo: ['normalize', 'harden', 'optimize', 'adapt', 'clarify'], flow: 'Technical quality audit' }, - 'critique': { leadsTo: ['polish', 'distill', 'bolder', 'quieter', 'typeset', 'arrange'], flow: 'UX and design review' }, - 'normalize': { combinesWith: ['clarify', 'adapt'], flow: 'Align with design system' }, - 'polish': { flow: 'Final pass before shipping' }, + 'audit': { leadsTo: ['harden', 'optimize', 'adapt', 'clarify'], flow: 'Technical quality audit' }, + 'critique': { leadsTo: ['polish', 'distill', 'bolder', 'quieter', 'typeset', 'layout'], flow: 'UX and design review' }, + 'polish': { flow: 'Final pass and design system alignment' }, 'optimize': { flow: 'Performance improvements' }, - 'harden': { combinesWith: ['optimize'], flow: 'Error handling & edge cases' }, - 'clarify': { combinesWith: ['normalize', 'adapt'], flow: 'Improve UX copy' }, + 'harden': { combinesWith: ['optimize'], flow: 'Edge cases, onboarding, and error handling' }, + 'clarify': { combinesWith: ['polish', 'adapt'], flow: 'Improve UX copy' }, 'quieter': { pairs: 'bolder', flow: 'Tone down bold designs' }, 'bolder': { pairs: 'quieter', flow: 'Amplify timid designs' }, - 'distill': { combinesWith: ['quieter', 'normalize'], flow: 'Strip to essence' }, + 'distill': { combinesWith: ['quieter', 'polish'], flow: 'Strip to essence' }, 'animate': { combinesWith: ['delight'], flow: 'Add motion' }, 'colorize': { combinesWith: ['bolder', 'delight'], flow: 'Add strategic color' }, 'delight': { combinesWith: ['bolder', 'animate'], flow: 'Add personality' }, - 'extract': { flow: 'Create design system elements' }, - 'adapt': { combinesWith: ['normalize', 'clarify'], flow: 'Different devices/contexts' }, - 'onboard': { combinesWith: ['clarify', 'delight'], flow: 'Onboarding & empty states' }, - 'typeset': { combinesWith: ['bolder', 'normalize'], flow: 'Fix typography' }, - 'arrange': { combinesWith: ['distill', 'adapt'], flow: 'Fix layout & spacing' }, + 'adapt': { combinesWith: ['polish', 'clarify'], flow: 'Different devices/contexts' }, + 'typeset': { combinesWith: ['bolder', 'polish'], flow: 'Fix typography' }, + 'layout': { combinesWith: ['distill', 'adapt'], flow: 'Fix layout & spacing' }, 'overdrive': { combinesWith: ['animate', 'delight'], flow: 'Technically extraordinary effects' } }; diff --git a/public/index.html b/public/index.html index 8195abbd0..2360f6e48 100644 --- a/public/index.html +++ b/public/index.html @@ -13,7 +13,7 @@ Impeccable: The missing upgrade to Anthropic's impeccable skill - + @@ -21,7 +21,7 @@ - + @@ -29,7 +29,7 @@ - + @@ -88,15 +88,15 @@

Impeccable

Design fluency for AI harnesses

-

Great design prompts require design vocabulary. Most people don't have it. Impeccable teaches your AI deep design knowledge and gives you 21 commands to steer the result.

-

Impeccable teaches your AI real design and gives you 21 commands to steer the result.

+

Great design prompts require design vocabulary. Most people don't have it. Impeccable teaches your AI deep design knowledge and gives you 18 commands to steer the result.

+

Impeccable teaches your AI real design and gives you 18 commands to steer the result.

What's included
Enhanced impeccable skill + anti-patterns · - 21 design commands: /polish, /audit, /typeset, /overdrive... + 18 design commands: /polish, /audit, /typeset, /overdrive...
@@ -203,7 +203,7 @@

The Language

-

21 commands form a shared vocabulary between you and your AI. Each one encodes a specific design discipline, so you can steer with precision.

+

18 commands form a shared vocabulary between you and your AI. Each one encodes a specific design discipline, so you can steer with precision.

@@ -331,7 +331,7 @@

1Install the skills Recommended

-

21 commands that steer your AI toward better design, in real time. The full Impeccable experience.

+

18 commands that steer your AI toward better design, in real time. The full Impeccable experience.

@@ -489,7 +489,7 @@
  • Chrome DevTools extension. One-click detection on any page: yours, staging, production, or someone else's. Reads live computed styles, surfaces findings in an interactive panel, and highlights elements on the page. In Chrome Web Store review.
  • /critique got teeth. Persona sub-agents review in parallel, score against Nielsen's heuristics, run the detector automatically, and open a live browser overlay so you can walk each finding in place.
  • New ways to create with Impeccable. /shape runs a structured discovery interview about purpose, audience, and goals, then produces a design brief before any code is written. /impeccable craft chains that brief straight into the full implementation flow so you ship a designed feature instead of a reflex card grid.
    • -
  • New docs site. Top-level Docs, Anti-Patterns, and Visual Mode sections. 21 per-skill pages with before/after demos and the canonical SKILL.md inline, two tutorials, and 38 rule cards with inline visual examples.
    • +
  • New docs site. Top-level Docs, Anti-Patterns, and Visual Mode sections. 18 per-skill pages with before/after demos and the canonical SKILL.md inline, two tutorials, and 38 rule cards with inline visual examples.
  • New harness: Rovo Dev. 11 supported AI tools total.
    • diff --git a/public/js/components/framework-viz.js b/public/js/components/framework-viz.js index 28ba69f60..133eec4dd 100644 --- a/public/js/components/framework-viz.js +++ b/public/js/components/framework-viz.js @@ -28,12 +28,11 @@ const commandSymbols = { 'shape': 'Sh', 'impeccable craft': 'Ic', 'impeccable': 'Im', - 'onboard': 'On', 'overdrive': 'Od', 'critique': 'Cr', 'audit': 'Au', 'typeset': 'Ty', - 'arrange': 'Ar', + 'layout': 'La', 'colorize': 'Co', 'animate': 'An', 'delight': 'De', @@ -42,29 +41,29 @@ const commandSymbols = { 'distill': 'Di', 'clarify': 'Cl', 'adapt': 'Ad', - 'normalize': 'No', 'polish': 'Po', 'optimize': 'Op', 'harden': 'Ha', 'impeccable teach': 'It', - 'extract': 'Ex' + 'impeccable extract': 'Ie' }; const commandNumbers = { 'shape': 0, - 'impeccable craft': 1, 'impeccable': 2, 'onboard': 3, 'overdrive': 4, - 'critique': 5, 'audit': 6, - 'typeset': 7, 'arrange': 8, 'colorize': 9, 'animate': 10, - 'delight': 11, 'bolder': 12, 'quieter': 13, - 'distill': 14, 'clarify': 15, 'adapt': 16, - 'normalize': 17, 'polish': 18, 'optimize': 19, 'harden': 20, - 'impeccable teach': 21, 'extract': 22 + 'impeccable craft': 1, 'impeccable': 2, 'overdrive': 3, + 'critique': 4, 'audit': 5, + 'typeset': 6, 'layout': 7, 'colorize': 8, 'animate': 9, + 'delight': 10, 'bolder': 11, 'quieter': 12, + 'distill': 13, 'clarify': 14, 'adapt': 15, + 'polish': 16, 'optimize': 17, 'harden': 18, + 'impeccable teach': 19, 'impeccable extract': 20 }; // Map sub-commands to their display label and scroll target const commandDisplay = { 'impeccable craft': { label: '/impeccable craft', scrollTo: 'impeccable' }, 'impeccable teach': { label: '/impeccable teach', scrollTo: 'impeccable' }, + 'impeccable extract': { label: '/impeccable extract', scrollTo: 'impeccable' }, }; export class PeriodicTable { diff --git a/public/js/components/glass-terminal.js b/public/js/components/glass-terminal.js index 716846e5f..543ca1a16 100644 --- a/public/js/components/glass-terminal.js +++ b/public/js/components/glass-terminal.js @@ -72,7 +72,7 @@ function renderDesktopLayout(container, commands) { let startIndex = -1; // Filter out deprecated shims and sub-commands (no standalone demos) - const deprecated = new Set(['teach-impeccable', 'frontend-design', 'impeccable craft', 'impeccable teach']); + const deprecated = new Set(['teach-impeccable', 'frontend-design', 'arrange', 'normalize', 'onboard', 'extract', 'impeccable craft', 'impeccable teach', 'impeccable extract']); const filteredCommands = commands.filter(c => !deprecated.has(c.id)); const categoryOrder = ['create', 'evaluate', 'refine', 'simplify', 'harden', 'system']; diff --git a/public/js/data.js b/public/js/data.js index 9de7a2f1f..d3858a50b 100644 --- a/public/js/data.js +++ b/public/js/data.js @@ -9,7 +9,7 @@ export const readySkills = [ ]; export const readyCommands = [ - 'normalize' // First command to be fully completed + 'layout' // First command to be fully completed ]; // Commands marked as beta — shown with a badge in the UI @@ -56,12 +56,11 @@ export const commandProcessSteps = { 'shape': ['Interview', 'Synthesize', 'Brief', 'Confirm'], 'impeccable craft': ['Shape', 'Reference', 'Build', 'Iterate'], 'impeccable': ['Direct', 'Design', 'Build', 'Refine'], - 'onboard': ['Map', 'Design', 'Guide'], 'overdrive': ['Assess', 'Choose', 'Build', 'Polish'], 'critique': ['Evaluate', 'Critique', 'Prioritize', 'Suggest'], 'audit': ['Scan', 'Document', 'Prioritize', 'Recommend'], 'typeset': ['Assess', 'Select', 'Scale', 'Refine'], - 'arrange': ['Assess', 'Grid', 'Rhythm', 'Balance'], + 'layout': ['Assess', 'Grid', 'Rhythm', 'Balance'], 'colorize': ['Analyze', 'Strategy', 'Apply', 'Balance'], 'animate': ['Identify', 'Design', 'Implement', 'Polish'], 'delight': ['Identify', 'Design', 'Implement'], @@ -70,12 +69,11 @@ export const commandProcessSteps = { 'distill': ['Audit', 'Remove', 'Clarify'], 'clarify': ['Read', 'Simplify', 'Improve', 'Test'], 'adapt': ['Analyze', 'Adjust', 'Optimize'], - 'normalize': ['Analyze', 'Identify', 'Align', 'Verify'], - 'polish': ['Review', 'Refine', 'Verify'], + 'polish': ['Discover', 'Review', 'Refine', 'Verify'], 'optimize': ['Profile', 'Identify', 'Improve', 'Measure'], - 'harden': ['Test', 'Handle', 'Wrap', 'Validate'], + 'harden': ['Test', 'Handle', 'Onboard', 'Validate'], 'impeccable teach': ['Explore', 'Interview', 'Synthesize', 'Save'], - 'extract': ['Identify', 'Abstract', 'Document'] + 'impeccable extract': ['Identify', 'Abstract', 'Migrate', 'Document'] }; export const commandCategories = { @@ -88,26 +86,24 @@ export const commandCategories = { 'audit': 'evaluate', // REFINE - improve existing design 'typeset': 'refine', - 'arrange': 'refine', + 'layout': 'refine', 'colorize': 'refine', 'animate': 'refine', 'delight': 'refine', 'bolder': 'refine', 'quieter': 'refine', - 'onboard': 'refine', 'overdrive': 'refine', // SIMPLIFY - reduce and clarify 'distill': 'simplify', 'clarify': 'simplify', 'adapt': 'simplify', // HARDEN - production-ready - 'normalize': 'harden', 'polish': 'harden', 'optimize': 'harden', 'harden': 'harden', // SYSTEM - setup and tooling 'impeccable teach': 'system', - 'extract': 'system' + 'impeccable extract': 'system' }; // Skill relationships - now consolidated into impeccable skill @@ -123,25 +119,22 @@ export const commandRelationships = { 'shape': { flow: 'Create: Plan UX and UI through structured discovery' }, 'impeccable craft': { flow: 'Create: Full shape-then-build flow with visual iteration' }, 'impeccable': { flow: 'Create: Freeform design with full design intelligence' }, - 'onboard': { combinesWith: ['clarify', 'delight'], flow: 'Create: Onboarding flows and empty states' }, 'overdrive': { combinesWith: ['animate', 'delight'], flow: 'Refine: Technically extraordinary effects' }, - 'critique': { leadsTo: ['polish', 'distill', 'bolder', 'quieter', 'typeset', 'arrange'], flow: 'Evaluate: UX and design review with scoring' }, - 'audit': { leadsTo: ['normalize', 'harden', 'optimize', 'adapt', 'clarify'], flow: 'Evaluate: Technical quality audit' }, - 'typeset': { combinesWith: ['bolder', 'normalize'], flow: 'Refine: Fix typography and type hierarchy' }, - 'arrange': { combinesWith: ['distill', 'adapt'], flow: 'Refine: Fix layout and spacing' }, + 'critique': { leadsTo: ['polish', 'distill', 'bolder', 'quieter', 'typeset', 'layout'], flow: 'Evaluate: UX and design review with scoring' }, + 'audit': { leadsTo: ['harden', 'optimize', 'adapt', 'clarify'], flow: 'Evaluate: Technical quality audit' }, + 'typeset': { combinesWith: ['bolder', 'polish'], flow: 'Refine: Fix typography and type hierarchy' }, + 'layout': { combinesWith: ['distill', 'adapt'], flow: 'Refine: Fix layout and spacing' }, 'colorize': { combinesWith: ['bolder', 'delight'], flow: 'Refine: Add strategic color' }, 'animate': { combinesWith: ['delight'], flow: 'Refine: Add purposeful motion' }, 'delight': { combinesWith: ['bolder', 'animate'], flow: 'Refine: Add personality and joy' }, 'bolder': { pairs: 'quieter', flow: 'Refine: Amplify timid designs' }, 'quieter': { pairs: 'bolder', flow: 'Refine: Tone down aggressive designs' }, - 'distill': { combinesWith: ['quieter', 'normalize'], flow: 'Simplify: Strip to essence' }, - 'clarify': { combinesWith: ['normalize', 'adapt'], flow: 'Simplify: Improve UX copy' }, - 'adapt': { combinesWith: ['normalize', 'clarify'], flow: 'Simplify: Adapt for different contexts' }, - 'normalize': { combinesWith: ['clarify', 'adapt'], flow: 'Harden: Align with design system' }, - 'polish': { flow: 'Harden: Final pass before shipping' }, + 'distill': { combinesWith: ['quieter', 'polish'], flow: 'Simplify: Strip to essence' }, + 'clarify': { combinesWith: ['polish', 'adapt'], flow: 'Simplify: Improve UX copy' }, + 'adapt': { combinesWith: ['polish', 'clarify'], flow: 'Simplify: Adapt for different contexts' }, + 'polish': { flow: 'Harden: Final pass and design system alignment' }, 'optimize': { flow: 'Harden: Performance improvements' }, - 'harden': { combinesWith: ['optimize'], flow: 'Harden: Error handling and edge cases' }, + 'harden': { combinesWith: ['optimize'], flow: 'Harden: Edge cases, onboarding, and error handling' }, 'impeccable teach': { flow: 'System: One-time project design context setup' }, - 'extract': { flow: 'System: Create design system components and tokens' } + 'impeccable extract': { flow: 'System: Extract design system components and tokens' } }; - diff --git a/public/js/demos/commands/index.js b/public/js/demos/commands/index.js index 6be37758e..8a29d7026 100644 --- a/public/js/demos/commands/index.js +++ b/public/js/demos/commands/index.js @@ -2,7 +2,6 @@ import animate from "./animate.js"; import bolder from "./bolder.js"; -import normalize from "./normalize.js"; import audit from "./audit.js"; import critique from "./critique.js"; import polish from "./polish.js"; @@ -13,15 +12,12 @@ import quieter from "./quieter.js"; import distill from "./distill.js"; import colorize from "./colorize.js"; import delight from "./delight.js"; -import extract from "./extract.js"; import adapt from "./adapt.js"; -import onboard from "./onboard.js"; import typeset from "./typeset.js"; -import arrange from "./arrange.js"; +import layout from "./layout.js"; import overdrive from "./overdrive.js"; export const commandDemos = { - normalize, bolder, animate, audit, @@ -34,17 +30,12 @@ export const commandDemos = { distill, colorize, delight, - extract, adapt, - onboard, typeset, - arrange, + layout, overdrive, }; export function getCommandDemo(commandId) { return commandDemos[commandId] || null; } - - - diff --git a/public/js/demos/commands/layout.js b/public/js/demos/commands/layout.js new file mode 100644 index 000000000..cc27b2bc4 --- /dev/null +++ b/public/js/demos/commands/layout.js @@ -0,0 +1,47 @@ +// Layout command demo - shows monotonous equal spacing becoming rhythmic and intentional +export default { + id: 'layout', + caption: 'Equal spacing everywhere → Intentional rhythm and hierarchy', + + before: ` +
    +
    +
    Team Members
    +
    +
    +
    +
    +
    Alice Chen
    +
    Designer
    +
    +
    +
    +
    Bob Park
    +
    Engineer
    +
    +
    +
    + `, + + after: ` +
    +
    Team Members
    +
    +
    +
    AC
    +
    +
    Alice Chen
    +
    Designer
    +
    +
    +
    +
    BP
    +
    +
    Bob Park
    +
    Engineer
    +
    +
    +
    +
    + ` +}; diff --git a/scripts/build-sub-pages.js b/scripts/build-sub-pages.js index 912029a80..ce9d3d2ef 100644 --- a/scripts/build-sub-pages.js +++ b/scripts/build-sub-pages.js @@ -202,6 +202,7 @@ ${tutorials impeccable: [ { id: 'impeccable-craft', label: '/impeccable craft', href: '/skills/impeccable#craft' }, { id: 'impeccable-teach', label: '/impeccable teach', href: '/skills/impeccable#teach' }, + { id: 'impeccable-extract', label: '/impeccable extract', href: '/skills/impeccable#extract' }, ], }; @@ -280,7 +281,7 @@ ${skillChips}

    ${totalSkills} commands

    Skills

    -

    One skill, /impeccable, teaches your AI design. Twenty commands steer the result. Each command does one job with an opinion about what good looks like.

    +

    One skill, /impeccable, teaches your AI design. Eighteen commands steer the result. Each command does one job with an opinion about what good looks like.

    @@ -632,7 +633,7 @@ export async function generateSubPages(rootDir) { const html = renderPage({ title: 'Skills | Impeccable', description: - '21 commands that teach your AI harness how to design. Browse by category: create, evaluate, refine, simplify, harden, system.', + '18 commands that teach your AI harness how to design. Browse by category: create, evaluate, refine, simplify, harden.', bodyHtml: wrapInDocsLayout(sidebar, main), activeNav: 'docs', canonicalPath: '/skills', diff --git a/scripts/lib/sub-pages-data.js b/scripts/lib/sub-pages-data.js index c0c13abf4..61246f932 100644 --- a/scripts/lib/sub-pages-data.js +++ b/scripts/lib/sub-pages-data.js @@ -34,6 +34,10 @@ export { const EXCLUDED_SKILLS = new Set([ 'frontend-design', // deprecated, renamed to impeccable 'teach-impeccable', // deprecated, folded into /impeccable teach + 'arrange', // renamed to layout + 'normalize', // merged into /polish + 'onboard', // merged into /harden + 'extract', // merged into /impeccable extract ]); /** @@ -50,28 +54,24 @@ const SKILL_CATEGORIES = { audit: 'evaluate', // REFINE - improve existing design typeset: 'refine', - arrange: 'refine', + layout: 'refine', colorize: 'refine', animate: 'refine', delight: 'refine', bolder: 'refine', quieter: 'refine', - onboard: 'refine', overdrive: 'refine', // SIMPLIFY - reduce and clarify distill: 'simplify', clarify: 'simplify', adapt: 'simplify', // HARDEN - production-ready - normalize: 'harden', polish: 'harden', optimize: 'harden', harden: 'harden', - // SYSTEM - setup and tooling - extract: 'system', }; -export const CATEGORY_ORDER = ['create', 'evaluate', 'refine', 'simplify', 'harden', 'system']; +export const CATEGORY_ORDER = ['create', 'evaluate', 'refine', 'simplify', 'harden']; export const CATEGORY_LABELS = { create: 'Create', diff --git a/source/skills/harden/SKILL.md b/source/skills/harden/SKILL.md index b64f65403..5aafb5f4e 100644 --- a/source/skills/harden/SKILL.md +++ b/source/skills/harden/SKILL.md @@ -1,6 +1,6 @@ --- name: harden -description: "Improve interface resilience through better error handling, i18n support, text overflow handling, and edge case management. Makes interfaces robust and production-ready. Use when the user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues." +description: "Make interfaces production-ready: error handling, empty states, onboarding flows, i18n, text overflow, and edge case management. Use when the user asks to harden, make production-ready, handle edge cases, add error states, design empty states, improve onboarding, or fix overflow and i18n issues." argument-hint: "[target]" user-invocable: true --- @@ -224,6 +224,40 @@ t('items', { count }) // Handles complex plural rules - Feature detection (not browser detection) - Test in target browsers +### Onboarding & First-Run Experience + +Production-ready features work for first-time users, not just power users. Design the paths that get new users to value: + +**Empty states**: Every zero-data screen needs: +- What will appear here (description or illustration) +- Why it matters to the user +- Clear CTA to create the first item or start from a template +- Visual interest (not just blank space with "No items yet") + +Empty state types to handle: +- **First use**: emphasize value, provide templates +- **User cleared**: light touch, easy to recreate +- **No results**: suggest a different query, offer to clear filters +- **No permissions**: explain why, how to get access + +**First-run experience**: Get users to their "aha moment" as quickly as possible. +- Show, don't tell -- working examples over descriptions +- Progressive disclosure -- teach one thing at a time, not everything upfront +- Make onboarding optional -- let experienced users skip +- Provide smart defaults so required setup is minimal + +**Feature discovery**: Teach features when users need them, not upfront. +- Contextual tooltips at point of use (brief, dismissable, one-time) +- Badges or indicators on new or unused features +- Celebrate activation events quietly (a toast, not a modal) + +**NEVER**: +- Force long onboarding before users can touch the product +- Show the same tooltip repeatedly (track and respect dismissals) +- Block the entire UI during a guided tour +- Create separate tutorial modes disconnected from the real product +- Design empty states that just say "No items" with no next action + ### Input Validation & Sanitization **Client-side validation**: diff --git a/source/skills/impeccable/SKILL.md b/source/skills/impeccable/SKILL.md index 517905a8b..9f650c9ba 100644 --- a/source/skills/impeccable/SKILL.md +++ b/source/skills/impeccable/SKILL.md @@ -1,7 +1,7 @@ --- name: impeccable -description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup." -argument-hint: "[craft|teach]" +description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' for shape-then-build, 'teach' for design context setup, or 'extract' to pull reusable components and tokens into the design system." +argument-hint: "[craft|teach|extract]" user-invocable: true license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -340,3 +340,9 @@ Write this section to `.impeccable.md` in the project root. If the file already Then {{ask_instruction}} whether they'd also like the Design Context appended to {{config_file}}. If yes, append or update the section there as well. Confirm completion and summarize the key design principles that will now guide all future work. + +--- + +## Extract Mode + +If this skill is invoked with the argument "extract" (e.g., `{{command_prefix}}impeccable extract [target]`), follow the [extract flow](reference/extract.md). Pass any additional arguments as the extraction target. diff --git a/source/skills/impeccable/reference/extract.md b/source/skills/impeccable/reference/extract.md new file mode 100644 index 000000000..845f078a7 --- /dev/null +++ b/source/skills/impeccable/reference/extract.md @@ -0,0 +1,70 @@ +# Extract Flow + +Identify reusable patterns, components, and design tokens, then extract and consolidate them into the design system for systematic reuse. + +## Step 1: Discover the Design System + +Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. + +**CRITICAL**: If no design system exists, {{ask_instruction}} before creating one. Understand the preferred location and structure first. + +## Step 2: Identify Patterns + +Look for extraction opportunities in the target area: + +- **Repeated components**: Similar UI patterns used 3+ times (buttons, cards, inputs) +- **Hard-coded values**: Colors, spacing, typography, shadows that should be tokens +- **Inconsistent variations**: Multiple implementations of the same concept +- **Composition patterns**: Layout or interaction patterns that repeat (form rows, toolbar groups, empty states) +- **Type styles**: Repeated font-size + weight + line-height combinations +- **Animation patterns**: Repeated easing, duration, or keyframe combinations + +Assess value: only extract things used 3+ times with the same intent. Premature abstraction is worse than duplication. + +## Step 3: Plan Extraction + +Create a systematic plan: + +- **Components to extract**: Which UI elements become reusable components? +- **Tokens to create**: Which hard-coded values become design tokens? +- **Variants to support**: What variations does each component need? +- **Naming conventions**: Component names, token names, prop names that match existing patterns +- **Migration path**: How to refactor existing uses to consume the new shared versions + +**IMPORTANT**: Design systems grow incrementally. Extract what is clearly reusable now, not everything that might someday be reusable. + +## Step 4: Extract & Enrich + +Build improved, reusable versions: + +- **Components**: Clear props API with sensible defaults, proper variants for different use cases, accessibility built in (ARIA, keyboard navigation, focus management), documentation and usage examples +- **Design tokens**: Clear naming (primitive vs semantic), proper hierarchy and organization, documentation of when to use each token +- **Patterns**: When to use this pattern, code examples, variations and combinations + +## Step 5: Migrate + +Replace existing uses with the new shared versions: + +- **Find all instances**: Search for the patterns you extracted +- **Replace systematically**: Update each use to consume the shared version +- **Test thoroughly**: Ensure visual and functional parity +- **Delete dead code**: Remove the old implementations + +## Step 6: Document + +Update design system documentation: + +- Add new components to the component library +- Document token usage and values +- Add examples and guidelines +- Update any Storybook or component catalog + +**NEVER**: +- Extract one-off, context-specific implementations without generalization +- Create components so generic they are useless +- Extract without considering existing design system conventions +- Skip proper TypeScript types or prop documentation +- Create tokens for every single value (tokens should have semantic meaning) +- Extract things that differ in intent (two buttons that look similar but serve different purposes should stay separate) + +Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently. diff --git a/source/skills/layout/SKILL.md b/source/skills/layout/SKILL.md new file mode 100644 index 000000000..747fb66be --- /dev/null +++ b/source/skills/layout/SKILL.md @@ -0,0 +1,124 @@ +--- +name: layout +description: "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition." +argument-hint: "[target]" +user-invocable: true +--- + +Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions. + +## MANDATORY PREPARATION + +Invoke {{command_prefix}}impeccable — 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 {{command_prefix}}impeccable teach 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 impeccable 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/polish/SKILL.md b/source/skills/polish/SKILL.md index 410290493..0cd35a7a5 100644 --- a/source/skills/polish/SKILL.md +++ b/source/skills/polish/SKILL.md @@ -13,6 +13,16 @@ Invoke {{command_prefix}}impeccable — it contains design principles, anti-patt Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +## Design System Discovery + +Before polishing, understand the system you are polishing toward: + +1. **Find the design system**: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: color tokens, spacing scale, typography styles, component API. +2. **Note the conventions**: How are shared components imported? What spacing scale is used? Which colors come from tokens vs hard-coded values? What motion and interaction patterns are established? +3. **Identify drift**: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale. + +If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase. + ## Pre-Polish Assessment Understand the current state and goals: @@ -188,6 +198,8 @@ Go through systematically: - Introduce bugs while polishing (test thoroughly) - Ignore systematic issues (if spacing is off everywhere, fix the system) - Perfect one thing while leaving others rough (consistent quality level) +- Create new one-off components when design system equivalents exist +- Hard-code values that should use design tokens ## Final Verification @@ -199,5 +211,14 @@ Before marking as done: - **Compare to design**: Match intended design - **Check all states**: Don't just test happy path +## Clean Up + +After polishing, ensure code quality: + +- **Replace custom implementations**: If the design system provides a component you reimplemented, switch to the shared version. +- **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. +- **Consolidate tokens**: If you introduced new values, check whether they should be tokens. +- **Verify DRYness**: Look for duplication introduced during polishing and consolidate. + Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.