refactor(ui-design): enhance usage recommendations and extraction processes in design workflows

.claude/commands/workflow/ui-design/explore-auto.md

@@ -25,8 +25,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
    - **ELSE**: Skip (use code import) → Auto-continues to Phase 9
 5. Phase 9 (layout-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 10
 6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 11
-7. Phase 11 (design-update) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 12 (if --batch-plan)
-8. Phase 12 (batch-plan, optional) → Reports completion
+7. **Phase 11 (preview-generation)** → **Execute script → Generate preview files** → Reports completion
 
 **Phase Transition Mechanism**:
 - **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 7

.claude/commands/workflow/ui-design/import-from-code.md

@@ -181,6 +181,7 @@ Task(subagent_type="ui-design-agent",
      - Add \"_metadata.completeness\": {status, missing_categories, recommendations}
      - Add \"_metadata.conflicts\": Array of conflicting definitions (MANDATORY if conflicts exist)
      - Add \"_metadata.code_snippets\": Map of code snippets (see below)
+     - Add \"_metadata.usage_recommendations\": Usage patterns from code (see below)
      - Include \"source\" field for each token (e.g., \"file.css:23\")
 
   **Code Snippet Recording**:
@@ -209,6 +210,17 @@ Task(subagent_type="ui-design-agent",
     2. Definitions that align with overall color scheme described in comments
     3. When in doubt, report ALL variants and flag for manual review in completeness.recommendations
 
+  **Usage Recommendations Generation**:
+  - Analyze code usage patterns to extract `_metadata.usage_recommendations` (see ui-design-agent.md schema)
+  - **Typography recommendations**:
+    * `common_sizes`: Identify most frequent font size usage (e.g., \"body_text\": \"base (1rem)\")
+    * `common_combinations`: Extract heading+body pairings from actual usage (e.g., h1 with p tags)
+  - **Spacing recommendations**:
+    * `size_guide`: Categorize spacing values into tight/normal/loose based on frequency
+    * `common_patterns`: Extract frequent padding/margin combinations from components
+  - Analysis method: Scan code for class/style usage frequency, extract patterns from component implementations
+  - Optional: If insufficient usage data, mark fields as empty arrays/objects with note in completeness.recommendations
+
   ## Code Import Specific Requirements
   - ✅ Read discovered-files.json FIRST to get file paths
   - ✅ Track extraction source for each token (file:line)
@@ -341,6 +353,11 @@ Task(subagent_type="ui-design-agent",
        * dom_structure with semantic HTML5
        * css_layout_rules using var() placeholders
        * Add \"description\" field explaining component purpose and classification rationale
+       * **Add \"usage_guide\" field for universal components** (see ui-design-agent.md schema):
+         - common_sizes: Extract size variants (small/medium/large) from code
+         - variant_recommendations: Document when to use each variant (primary/secondary/etc)
+         - usage_context: List typical usage scenarios from actual implementation
+         - accessibility_tips: Extract ARIA patterns and a11y notes from code
 
   **Code Snippet Recording**:
   - Record actual layout/component code in `extraction_metadata.code_snippets`
@@ -359,6 +376,12 @@ Task(subagent_type="ui-design-agent",
     * Specialized: Feature-specific or domain-specific (checkout form, dashboard widget)
   - ✅ Record complete code snippets in extraction_metadata.code_snippets (complete components/structures)
   - ✅ **Document classification rationale** in component description
+  - ✅ **Generate usage_guide for universal components** (REQUIRED):
+    * Analyze code to extract size variants (scan for size-related classes/props)
+    * Document variant usage from code comments and implementation patterns
+    * List usage contexts from component instances in codebase
+    * Extract accessibility patterns from ARIA attributes and a11y comments
+    * If insufficient data, populate with minimal valid structure and note in completeness
   - ❌ NO external research or web searches (code-only extraction)
 ")
 ```

.claude/commands/workflow/ui-design/reference-page-generator.md

@@ -200,10 +200,18 @@ Task(ui-design-agent): `
   - Display typography scale (font sizes, weights)
   - Show typography combinations if available
   - Include font family examples
+  - **Display usage recommendations** (from design-tokens.json _metadata.usage_recommendations.typography):
+    * Common sizes table (small_text, body_text, heading)
+    * Common combinations with use cases
 
   ### Section 3: Components
   - Render all components from layout-templates.json (use layout_templates field)
   - **Universal Components**: Display reusable multi-component showcases (buttons, inputs, cards, etc.)
+    * **Display usage_guide** (from layout-templates.json):
+      - Common sizes table with dimensions and use cases
+      - Variant recommendations (when to use primary/secondary/etc)
+      - Usage context list (typical scenarios)
+      - Accessibility tips checklist
   - **Specialized Components**: Display module-specific components from code (feature-specific layouts, custom widgets)
   - Display all variants side-by-side
   - Show DOM structure with proper styling
@@ -214,6 +222,9 @@ Task(ui-design-agent): `
   - Visual spacing scale
   - Border radius examples
   - Shadow depth examples
+  - **Display spacing recommendations** (from design-tokens.json _metadata.usage_recommendations.spacing):
+    * Size guide table (tight/normal/loose categories)
+    * Common patterns with use cases and pixel values
 
   ### Section 5: Animations (if available)
   - Animation duration examples
@@ -249,6 +260,11 @@ Task(ui-design-agent): `
   - ✅ Display component DOM structures with proper styling
   - ✅ Include usage code snippets
   - ✅ Label each component type clearly (Universal / Specialized)
+  - ✅ **Display usage recommendations** when available:
+    - Typography: common_sizes, common_combinations (from _metadata.usage_recommendations)
+    - Components: usage_guide for universal components (from layout-templates)
+    - Spacing: size_guide, common_patterns (from _metadata.usage_recommendations)
+  - ✅ Gracefully handle missing usage data (display sections only if data exists)
   - ✅ Use Write() to save both files:
     - ${package_dir}/preview.html
     - ${package_dir}/preview.css