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) <noreply@anthropic.com>

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**:

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.

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.

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.

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.