/extract | Impeccable

When to use it

/extract is for the moment your codebase has accidentally become a design system. Repeated button styles in 12 places. Three variants of the same card. Hex colors scattered throughout. Hand-rolled spacing that accidentally matches a scale. Reach for it when you want to consolidate this drift into reusable primitives.

Use it after a product has shipped enough features to reveal the patterns. Premature extraction creates abstractions that do not match reality.

How it works

The skill discovers the design system structure first, then identifies extraction opportunities:

Tokens: find repeated literal values (colors, spacing, radii, shadows, font sizes). Propose token names, add to the token system, replace usages.

Components: find UI patterns that repeat with minor variation (buttons, cards, inputs, modals). Extract into a single component with variants, migrate callers.

Composition patterns: find layout or interaction patterns that repeat (form rows, toolbar groups, empty states). Extract into composition primitives.

Type styles: find repeated font-size + weight + line-height combinations. Extract into text styles.

Animation patterns: find repeated easing, duration, or keyframe combinations. Extract into motion tokens.

The skill is cautious. It only extracts things used three or more times, with the same intent. It never extracts "because it might be reused later". Premature abstraction is worse than duplication.

Try it

/extract the button styles

Expected output:

Found 14 button instances across 8 files

4 distinct variants: primary (filled accent), secondary (bordered), ghost (text-only), destructive (filled red)

All 4 variants use the same size scale (small, default, large)

Extracted into <Button variant="primary" size="default"> with token-driven styles

Migrated 14 call sites, removed ~180 lines of duplicated CSS

Added 3 missing tokens: --button-radius, --button-padding-y, --button-padding-x

Pitfalls

Extracting too early. Two usages are not a pattern. Three might be. Wait until the pattern is obvious.

Over-generalizing. The extracted component should match the current use cases closely, not anticipate every possible future one. You can always add variants later.

Forgetting the migration. Extraction without migration leaves the old duplicated code around and creates a third way of doing the same thing. Always migrate in the same pass.

Extracting things that differ in intent. Two buttons that look similar but serve different purposes (primary action vs link styled as button) should probably stay separate.

Identify reusable patterns, components, and design tokens, then extract and consolidate them into the design system for systematic reuse.

Discover

Analyze the target area to identify extraction opportunities:

Find the design system: Locate your design system, component library, or shared UI directory (grep for "design system", "ui", "components", etc.). Understand its structure:
- Component organization and naming conventions
- Design token structure (if any)
- Documentation patterns
- Import/export conventions
CRITICAL: If no design system exists, ask before creating one. Understand the preferred location and structure first.
Identify patterns: Look for:
- Repeated components: Similar UI patterns used multiple times (buttons, cards, inputs, etc.)
- Hard-coded values: Colors, spacing, typography, shadows that should be tokens
- Inconsistent variations: Multiple implementations of the same concept (3 different button styles)
- Reusable patterns: Layout patterns, composition patterns, interaction patterns worth systematizing
Assess value: Not everything should be extracted. Consider:
- Is this used 3+ times, or likely to be reused?
- Would systematizing this improve consistency?
- Is this a general pattern or context-specific?
- What's the maintenance cost vs benefit?

Plan Extraction

Create a systematic extraction 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's clearly reusable now, not everything that might someday be reusable.

Extract & Enrich

Build improved, reusable versions:

Components: Create well-designed components with:
- 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: Create tokens with:
- Clear naming (primitive vs semantic)
- Proper hierarchy and organization
- Documentation of when to use each token
Patterns: Document patterns with:
- When to use this pattern
- Code examples
- Variations and combinations

NEVER:

Extract one-off, context-specific implementations without generalization
Create components so generic they're 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)

Migrate

Replace existing uses with the new shared versions:

Find all instances: Search for the patterns you've 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

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

Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently.