| 1 | # Extract Flow |
| 2 | |
| 3 | Identify reusable patterns, components, and design tokens, then extract and consolidate them into the design system for systematic reuse. |
| 4 | |
| 5 | ## Step 1: Discover the Design System |
| 6 | |
| 7 | Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. |
| 8 | |
| 9 | **CRITICAL**: If no design system exists, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. |
| 10 | |
| 11 | ## Step 2: Identify Patterns |
| 12 | |
| 13 | Look for extraction opportunities in the target area: |
| 14 | |
| 15 | - **Repeated components**: Similar UI patterns used 3+ times (buttons, cards, inputs) |
| 16 | - **Hard-coded values**: Colors, spacing, typography, shadows that should be tokens |
| 17 | - **Inconsistent variations**: Multiple implementations of the same concept |
| 18 | - **Composition patterns**: Layout or interaction patterns that repeat (form rows, toolbar groups, empty states) |
| 19 | - **Type styles**: Repeated font-size + weight + line-height combinations |
| 20 | - **Animation patterns**: Repeated easing, duration, or keyframe combinations |
| 21 | |
| 22 | Assess value: only extract things used 3+ times with the same intent. Premature abstraction is worse than duplication. |
| 23 | |
| 24 | ## Step 3: Plan Extraction |
| 25 | |
| 26 | Create a systematic plan: |
| 27 | |
| 28 | - **Components to extract**: Which UI elements become reusable components? |
| 29 | - **Tokens to create**: Which hard-coded values become design tokens? |
| 30 | - **Variants to support**: What variations does each component need? |
| 31 | - **Naming conventions**: Component names, token names, prop names that match existing patterns |
| 32 | - **Migration path**: How to refactor existing uses to consume the new shared versions |
| 33 | |
| 34 | **IMPORTANT**: Design systems grow incrementally. Extract what is clearly reusable now, not everything that might someday be reusable. |
| 35 | |
| 36 | ## Step 4: Extract & Enrich |
| 37 | |
| 38 | Build improved, reusable versions: |
| 39 | |
| 40 | - **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 |
| 41 | - **Design tokens**: Clear naming (primitive vs semantic), proper hierarchy and organization, documentation of when to use each token |
| 42 | - **Patterns**: When to use this pattern, code examples, variations and combinations |
| 43 | |
| 44 | ## Step 5: Migrate |
| 45 | |
| 46 | Replace existing uses with the new shared versions: |
| 47 | |
| 48 | - **Find all instances**: Search for the patterns you extracted |
| 49 | - **Replace systematically**: Update each use to consume the shared version |
| 50 | - **Test thoroughly**: Ensure visual and functional parity |
| 51 | - **Delete dead code**: Remove the old implementations |
| 52 | |
| 53 | ## Step 6: Document |
| 54 | |
| 55 | Update design system documentation: |
| 56 | |
| 57 | - Add new components to the component library |
| 58 | - Document token usage and values |
| 59 | - Add examples and guidelines |
| 60 | - Update any Storybook or component catalog |
| 61 | |
| 62 | **NEVER**: |
| 63 | - Extract one-off, context-specific implementations without generalization |
| 64 | - Create components so generic they are useless |
| 65 | - Extract without considering existing design system conventions |
| 66 | - Skip proper TypeScript types or prop documentation |
| 67 | - Create tokens for every single value (tokens should have semantic meaning) |
| 68 | - Extract things that differ in intent (two buttons that look similar but serve different purposes should stay separate) |
| 69 | |
| 70 |