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

2026-02-05 01:50:27 +08:00 · 2025-11-11 21:52:47 +08:00
parent 8786b8c34d
commit d602ca052b
5 changed files with 466 additions and 46 deletions
--- a/.claude/agents/ui-design-agent.md
+++ b/.claude/agents/ui-design-agent.md
@@ -349,7 +349,38 @@ body {
        "snippet": "string - complete code block",
        "context_type": "string - css-variable|css-class|js-object|etc"
      }
-    ]
+    ],
+    "usage_recommendations": {
+      "typography": {
+        "common_sizes": {
+          "small_text": "string - e.g., sm (0.875rem)",
+          "body_text": "string - e.g., base (1rem)",
+          "heading": "string - e.g., 2xl-4xl"
+        },
+        "common_combinations": [
+          {
+            "name": "string - e.g., 标题+正文",
+            "heading": "string - size name",
+            "body": "string - size name",
+            "use_case": "string - typical usage scenario"
+          }
+        ]
+      },
+      "spacing": {
+        "size_guide": {
+          "tight": "string - e.g., 1-2 (0.25rem-0.5rem)",
+          "normal": "string - e.g., 4-6 (1rem-1.5rem)",
+          "loose": "string - e.g., 8-12 (2rem-3rem)"
+        },
+        "common_patterns": [
+          {
+            "pattern": "string - e.g., padding-4 margin-bottom-6",
+            "use_case": "string - typical usage",
+            "pixel_value": "string - converted values"
+          }
+        ]
+      }
+    }
  }
 }
 ```
@@ -360,6 +391,7 @@ body {
 - Spacing MUST use systematic scale (multiples of base unit)
 - _metadata.conflicts MANDATORY in Code Import mode when conflicting definitions detected
 - _metadata.code_snippets ONLY present in Code Import mode
+- _metadata.usage_recommendations RECOMMENDED for universal components (buttons, inputs, cards, etc.)
 - component_styles is optional but recommended

 **Conflict Resolution Rules** (Code Import Mode):
@@ -379,6 +411,7 @@ body {
    {
      "target": "string - page/component name",
      "description": "string - layout description",
+      "component_type": "string - universal|specialized",
      "device_type": "string - mobile|tablet|desktop|responsive",
      "layout_strategy": "string - grid-3col|flex-row|etc",
      "dom_structure": {
@@ -417,6 +450,34 @@ body {
        "string - ARIA patterns used",
        "string - keyboard navigation notes"
      ],
+      "usage_guide": {
+        "common_sizes": {
+          "small": {
+            "dimensions": "string - e.g., px-3 py-1.5 (height: ~32px)",
+            "use_case": "string - typical usage"
+          },
+          "medium": {
+            "dimensions": "string - e.g., px-4 py-2 (height: ~40px)",
+            "use_case": "string - typical usage"
+          },
+          "large": {
+            "dimensions": "string - e.g., px-6 py-3 (height: ~48px)",
+            "use_case": "string - typical usage"
+          }
+        },
+        "variant_recommendations": {
+          "variant_name": {
+            "description": "string - when to use this variant",
+            "typical_actions": ["string - action examples"]
+          }
+        },
+        "usage_context": [
+          "string - typical usage scenarios"
+        ],
+        "accessibility_tips": [
+          "string - accessibility best practices"
+        ]
+      },
      "extraction_metadata": {
        "source": "string - code-import|explore|text",
        "created": "ISO timestamp",
@@ -442,6 +503,13 @@ body {
 - css_layout_rules MUST use var() placeholders for token values (spacing, breakpoints)
 - css_layout_rules MUST NOT include visual styling (colors, fonts - those belong in design-tokens)
 - responsive_breakpoints MUST match breakpoint tokens
+- component_type MUST be specified as "universal" or "specialized"
+- usage_guide REQUIRED for universal components (buttons, inputs, forms, cards, navigation, etc.)
+- usage_guide OPTIONAL for specialized components (can be simplified or omitted)
+- usage_guide.common_sizes SHOULD include at least small, medium, large variants
+- usage_guide.variant_recommendations SHOULD explain when to use each variant
+- usage_guide.usage_context SHOULD list typical usage scenarios
+- usage_guide.accessibility_tips SHOULD include WCAG compliance notes
 - extraction_metadata.code_snippets ONLY present in Code Import mode

 ### animation-tokens.json
--- a/.claude/commands/memory/style-skill-memory.md
+++ b/.claude/commands/memory/style-skill-memory.md
@@ -1,5 +1,5 @@
 ---
-name: memory:style-skill-memory
+name: style-skill-memory
 description: Generate SKILL memory package from style reference for easy loading and consistent design system usage
 argument-hint: "[package-name] [--regenerate]"
 allowed-tools: Bash,Read,Write,TodoWrite
@@ -18,6 +18,12 @@ auto-continue: true

 **Use Case**: Load design system context when working with UI components, analyzing design patterns, or implementing style guidelines.

+**Key Features**:
+- Extracts primary design references (colors, typography, spacing, etc.)
+- Provides dynamic adjustment guidelines for design tokens
+- Progressive loading structure for efficient token usage
+- Interactive preview showcase
+
 ---

 ## Usage
@@ -57,7 +63,7 @@ package-name    Style reference package name (required)
 ```json
 [
  {"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"},
-  {"content": "Read package data and count components", "status": "pending", "activeForm": "Reading package data"},
+  {"content": "Read package data and extract design references", "status": "pending", "activeForm": "Reading package data"},
  {"content": "Generate SKILL.md with progressive loading", "status": "pending", "activeForm": "Generating SKILL.md"}
 ]
 ```
@@ -117,17 +123,15 @@ if (regenerate_flag && skill_exists) {
 ```json
 [
  {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
-  {"content": "Read package data and count components", "status": "in_progress", "activeForm": "Reading package data"}
+  {"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"}
 ]
 ```

-**Next Action**: Continue to Phase 2
-
 ---

-### Phase 2: Read Package Data
+### Phase 2: Read Package Data & Extract Design References

-**Purpose**: Extract package information for SKILL description generation
+**Purpose**: Extract package information and primary design references for SKILL description generation

 **Step 1: Count Components**

@@ -137,17 +141,76 @@ bash(jq '.layout_templates | length' .workflow/reference_style/${package_name}/l

 Store result as `component_count`

-**Step 2: Read Design Tokens Summary**
+**Step 2: Extract Component Types**
+
+```bash
+# Extract component names from layout templates
+bash(jq -r '.layout_templates | keys[]' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
+```
+
+Store as `COMPONENT_TYPES`: List of available component types
+
+**Step 3: Read Design Tokens**

 ```bash
 Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json")
 ```

-**Extract Information**:
- Available token categories (colors, typography, spacing, etc.)
- Token count per category
+**Extract Primary Design References**:

-**Step 3: Check Available Files**
+**Colors** (top 3-5 most important):
+```bash
+bash(jq -r '.colors | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null | head -5)
+```
+
+**Typography** (heading and body fonts):
+```bash
+bash(jq -r '.typography | to_entries | select(.key | contains("family")) | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Spacing Scale** (base spacing values):
+```bash
+bash(jq -r '.spacing | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Border Radius** (base radius values):
+```bash
+bash(jq -r '.border_radius | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Shadows** (elevation levels):
+```bash
+bash(jq -r '.shadows | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+Store extracted references as:
+- `PRIMARY_COLORS`: List of primary color tokens
+- `TYPOGRAPHY_FONTS`: Font family tokens
+- `SPACING_SCALE`: Base spacing values
+- `BORDER_RADIUS`: Radius values
+- `SHADOWS`: Shadow definitions
+
+**Step 4: Read Animation Tokens (if available)**
+
+```bash
+# Check if animation tokens exist
+bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
+```
+
+If available, extract:
+```bash
+Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")
+
+# Extract primary animation values
+bash(jq -r '.duration | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
+bash(jq -r '.easing | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
+```
+
+Store as:
+- `ANIMATION_DURATIONS`: Animation duration tokens
+- `EASING_FUNCTIONS`: Easing function tokens
+
+**Step 5: Count Files**

 ```bash
 bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2>/dev/null | wc -l)
@@ -155,34 +218,32 @@ bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2

 Store result as `file_count`

-**Step 4: Check Optional Animation Tokens**
-
-```bash
-bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
-```
-
-Store result as `has_animations`
-
-**Summary Data**:
+**Summary Data Collected**:
 - `COMPONENT_COUNT`: Number of components in layout templates
+- `COMPONENT_TYPES`: List of component types (first 10)
 - `FILE_COUNT`: Total files in package
 - `HAS_ANIMATIONS`: Whether animation tokens are available
+- `PRIMARY_COLORS`: Primary color tokens with values
+- `TYPOGRAPHY_FONTS`: Font family tokens
+- `SPACING_SCALE`: Base spacing scale
+- `BORDER_RADIUS`: Border radius values
+- `SHADOWS`: Shadow definitions
+- `ANIMATION_DURATIONS`: Animation durations (if available)
+- `EASING_FUNCTIONS`: Easing functions (if available)

 **TodoWrite Update**:
 ```json
 [
-  {"content": "Read package data and count components", "status": "completed", "activeForm": "Reading package data"},
+  {"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
  {"content": "Generate SKILL.md with progressive loading", "status": "in_progress", "activeForm": "Generating SKILL.md"}
 ]
 ```

-**Next Action**: Continue to Phase 3
-
 ---

 ### Phase 3: Generate SKILL.md

-**Purpose**: Create SKILL memory index with progressive loading structure
+**Purpose**: Create SKILL memory index with progressive loading structure and design references

 **Step 1: Create SKILL Directory**

@@ -208,7 +269,9 @@ bash(mkdir -p .claude/skills/style-${package_name})
 main-app-style-v1 design system with 8 layout templates and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with UI components, design tokens, layout patterns, analyzing component structures, or implementing visual consistency.
 ```

-**Step 3: Write SKILL.md** (Use Write tool)
+**Step 3: Write SKILL.md**
+
+Use Write tool to generate SKILL.md with the following complete content:

 ```markdown
 ---
@@ -227,9 +290,143 @@ Style reference package extracted from codebase with layout templates, design to
 **Package Details**:
 - Package: {package_name}
 - Layout Templates: {component_count}
+- Component Types: {comma-separated list of COMPONENT_TYPES}
 - Files: {file_count}
 - Animation Tokens: {has_animations ? "✓ Available" : "Not available"}

+---
+
+## ⚡ Primary Design References
+
+**IMPORTANT**: These are **reference values** extracted from the codebase. They should be **dynamically adjusted** based on your specific design needs, not treated as fixed constraints.
+
+### 🎨 Colors
+
+{FOR each color in PRIMARY_COLORS:
+  - **{color.key}**: `{color.value}`
+}
+
+**Usage Guidelines**:
+- These colors establish the foundation of the design system
+- Adjust saturation, lightness, or hue based on:
+  - Brand requirements and accessibility needs
+  - Context (light/dark mode, high-contrast themes)
+  - User feedback and A/B testing results
+- Use color theory principles to maintain harmony when modifying
+
+### 📝 Typography
+
+{FOR each font in TYPOGRAPHY_FONTS:
+  - **{font.key}**: `{font.value}`
+}
+
+**Usage Guidelines**:
+- Font families can be substituted based on:
+  - Brand identity and design language
+  - Performance requirements (web fonts vs. system fonts)
+  - Accessibility and readability considerations
+  - Platform-specific availability
+- Maintain hierarchy and scale relationships when changing fonts
+
+### 📏 Spacing Scale
+
+{FOR each spacing in SPACING_SCALE:
+  - **{spacing.key}**: `{spacing.value}`
+}
+
+**Usage Guidelines**:
+- Spacing values form a consistent rhythm system
+- Adjust scale based on:
+  - Target device (mobile vs. desktop vs. tablet)
+  - Content density requirements
+  - Component-specific needs (compact vs. comfortable layouts)
+- Maintain proportional relationships when scaling
+
+### 🔲 Border Radius
+
+{FOR each radius in BORDER_RADIUS:
+  - **{radius.key}**: `{radius.value}`
+}
+
+**Usage Guidelines**:
+- Border radius affects visual softness and modernity
+- Adjust based on:
+  - Design aesthetic (sharp vs. rounded vs. pill-shaped)
+  - Component type (buttons, cards, inputs have different needs)
+  - Platform conventions (iOS vs. Android vs. Web)
+
+### 🌫️ Shadows
+
+{FOR each shadow in SHADOWS:
+  - **{shadow.key}**: `{shadow.value}`
+}
+
+**Usage Guidelines**:
+- Shadows create elevation and depth perception
+- Adjust based on:
+  - Material design depth levels
+  - Light/dark mode contexts
+  - Performance considerations (complex shadows impact rendering)
+  - Visual hierarchy needs
+
+{IF HAS_ANIMATIONS:
+### ⏱️ Animation & Timing
+
+**Durations**:
+{FOR each duration in ANIMATION_DURATIONS:
+  - **{duration.key}**: `{duration.value}`
+}
+
+**Easing Functions**:
+{FOR each easing in EASING_FUNCTIONS:
+  - **{easing.key}**: `{easing.value}`
+}
+
+**Usage Guidelines**:
+- Animation timing affects perceived responsiveness and polish
+- Adjust based on:
+  - User expectations and platform conventions
+  - Accessibility preferences (reduced motion)
+  - Animation type (micro-interactions vs. page transitions)
+  - Performance constraints (mobile vs. desktop)
+}
+
+---
+
+## 🎯 Design Adaptation Strategies
+
+### When to Adjust Design References
+
+**Brand Alignment**:
+- Modify colors to match brand identity and guidelines
+- Adjust typography to reflect brand personality
+- Tune spacing and radius to align with brand aesthetic
+
+**Accessibility Requirements**:
+- Increase color contrast ratios for WCAG compliance
+- Adjust font sizes and spacing for readability
+- Modify animation durations for reduced-motion preferences
+
+**Platform Optimization**:
+- Adapt spacing for mobile touch targets (min 44x44px)
+- Adjust shadows and radius for platform conventions
+- Optimize animation performance for target devices
+
+**Context-Specific Needs**:
+- Dark mode: Adjust colors, shadows, and contrasts
+- High-density displays: Fine-tune spacing and sizing
+- Responsive design: Scale tokens across breakpoints
+
+### How to Apply Adjustments
+
+1. **Identify Need**: Determine which tokens need adjustment based on your specific requirements
+2. **Maintain Relationships**: Preserve proportional relationships between related tokens
+3. **Test Thoroughly**: Validate changes across components and use cases
+4. **Document Changes**: Track modifications and rationale for team alignment
+5. **Iterate**: Refine based on user feedback and testing results
+
+---
+
 ## Progressive Loading

 ### Level 0: Design Tokens (~5K tokens)
@@ -377,7 +574,7 @@ bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" ||
 ```json
 [
  {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
-  {"content": "Read package data and count components", "status": "completed", "activeForm": "Reading package data"},
+  {"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
  {"content": "Generate SKILL.md with progressive loading", "status": "completed", "activeForm": "Generating SKILL.md"}
 ]
 ```
@@ -388,37 +585,81 @@ bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" ||

 ## Completion Message

+Display extracted primary design references to user:
+
 ```
 ✅ SKILL memory generated successfully!

 Package: {package_name}
 SKILL Location: .claude/skills/style-{package_name}/SKILL.md

-Package Details:
+📦 Package Details:
 - Layout Templates: {component_count}
+- Component Types: {show first 5 COMPONENT_TYPES, then "+ X more"}
 - Files: {file_count}
 - Animation Tokens: {has_animations ? "✓ Available" : "Not available"}

-Progressive Loading Levels:
+🎨 Primary Design References Extracted:
+{IF PRIMARY_COLORS exists:
+Colors:
+  {show first 3 PRIMARY_COLORS with key: value}
+  {if more than 3: + X more colors}
+}
+
+{IF TYPOGRAPHY_FONTS exists:
+Typography:
+  {show all TYPOGRAPHY_FONTS}
+}
+
+{IF SPACING_SCALE exists:
+Spacing Scale:
+  {show first 3 SPACING_SCALE items}
+  {if more than 3: + X more spacing tokens}
+}
+
+{IF BORDER_RADIUS exists:
+Border Radius:
+  {show all BORDER_RADIUS}
+}
+
+{IF HAS_ANIMATIONS:
+Animation:
+  Durations: {count ANIMATION_DURATIONS} tokens
+  Easing: {count EASING_FUNCTIONS} functions
+}
+
+⚡ Progressive Loading Levels:
 - Level 0: Design Tokens (~5K tokens)
 - Level 1: Tokens + Layout Templates (~12K tokens)
 - Level 2: Complete System (~20K tokens)

-Usage:
+💡 Usage:
 Load design system context when working with:
 - UI component implementation
 - Layout pattern analysis
 - Design token application
 - Style consistency validation

-Preview:
+⚠️ IMPORTANT:
+The extracted design references are REFERENCE VALUES, not fixed constraints.
+Dynamically adjust colors, spacing, typography, and other tokens based on:
+- Brand requirements and accessibility needs
+- Platform-specific conventions and optimizations
+- Context (light/dark mode, responsive breakpoints)
+- User feedback and testing results
+
+See SKILL.md for detailed adjustment guidelines and best practices.
+
+🎯 Preview:
 Open interactive showcase:
  file://{absolute_path}/.workflow/reference_style/{package_name}/preview.html

-Next Steps:
-1. Load appropriate level based on your task
-2. Reference layout-templates.json for component structures
-3. Use design-tokens.json for consistent styling
+📋 Next Steps:
+1. Load appropriate level based on your task context
+2. Review Primary Design References section for key design tokens
+3. Apply design tokens with dynamic adjustments as needed
+4. Reference layout-templates.json for component structures
+5. Use Design Adaptation Strategies when modifying tokens
 ```

 ---
@@ -442,8 +683,10 @@ Next Steps:

 1. **Check Before Generate**: Verify package exists before attempting SKILL generation
 2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
-3. **Progressive Loading**: Always include all 4 levels (0-3) with clear token estimates
-4. **Intelligent Description**: Extract component count and key features from metadata
+3. **Extract Primary References**: Always extract and display key design values (colors, typography, spacing, border radius, shadows, animations)
+4. **Include Adjustment Guidance**: Provide clear guidelines on when and how to dynamically adjust design tokens
+5. **Progressive Loading**: Always include all 3 levels (0-2) with clear token estimates
+6. **Intelligent Description**: Extract component count and key features from metadata

 ### SKILL Description Format

@@ -459,6 +702,30 @@ Next Steps:
 - Trigger keywords (UI components, design tokens, layout patterns, component structures)
 - Action verbs (working with, analyzing, implementing)

+### Primary Design References Extraction
+
+**Required Data Extraction** (from design-tokens.json):
+- Colors: Primary, secondary, accent colors (top 3-5)
+- Typography: Font families for headings and body text
+- Spacing Scale: Base spacing values (xs, sm, md, lg, xl)
+- Border Radius: All radius tokens
+- Shadows: Shadow definitions (top 3 elevation levels)
+
+**Optional Data Extraction** (from animation-tokens.json if available):
+- Animation Durations: All duration tokens
+- Easing Functions: Top 3 easing functions
+
+**Extraction Format**:
+Use `jq` to extract tokens from JSON files. Each token should include key and value.
+
+### Dynamic Adjustment Guidelines
+
+**Include in SKILL.md**:
+1. **Usage Guidelines per Category**: Specific guidance for each token category
+2. **Adjustment Strategies**: When to adjust design references
+3. **Practical Examples**: Context-specific adaptation scenarios
+4. **Best Practices**: How to maintain design system coherence while adjusting
+
 ### Progressive Loading Structure

 **Level 0** (~5K tokens):
@@ -479,20 +746,67 @@ Next Steps:
 ## Benefits

 - **Fast Context Loading**: Progressive levels for efficient token usage
+- **Primary Design References**: Extracted key design values (colors, typography, spacing, etc.) displayed prominently
+- **Dynamic Adjustment Guidance**: Clear instructions on when and how to adjust design tokens
 - **Intelligent Triggering**: Keywords optimize SKILL activation
 - **Complete Reference**: All package files accessible through SKILL
 - **Easy Regeneration**: Simple --regenerate flag for updates
 - **Clear Structure**: Organized levels by use case
+- **Practical Usage Guidelines**: Context-specific adjustment strategies for different scenarios
+
+---

 ## Architecture

 ```
 style-skill-memory
-  ├─ Phase 1: Validate (check package exists, check SKILL exists)
-  ├─ Phase 2: Read Package Data (count components from layout-templates.json, check animations)
-  └─ Phase 3: Generate SKILL.md (write SKILL with progressive loading)
+  ├─ Phase 1: Validate
+  │   ├─ Parse package name from argument or auto-detect
+  │   ├─ Check package exists in .workflow/reference_style/
+  │   └─ Check if SKILL already exists (skip if exists and no --regenerate)
+  │
+  ├─ Phase 2: Read Package Data & Extract Primary References
+  │   ├─ Count components from layout-templates.json
+  │   ├─ Extract component types list
+  │   ├─ Extract primary colors from design-tokens.json (top 3-5)
+  │   ├─ Extract typography (font families)
+  │   ├─ Extract spacing scale (base values)
+  │   ├─ Extract border radius tokens
+  │   ├─ Extract shadow definitions (top 3)
+  │   ├─ Extract animation tokens (if available)
+  │   └─ Count total files in package
+  │
+  └─ Phase 3: Generate SKILL.md
+      ├─ Create SKILL directory
+      ├─ Generate intelligent description with keywords
+      ├─ Write SKILL.md with complete structure:
+      │   ├─ Package Overview
+      │   ├─ Primary Design References
+      │   │   ├─ Colors with usage guidelines
+      │   │   ├─ Typography with usage guidelines
+      │   │   ├─ Spacing with usage guidelines
+      │   │   ├─ Border Radius with usage guidelines
+      │   │   ├─ Shadows with usage guidelines
+      │   │   └─ Animation & Timing (if available)
+      │   ├─ Design Adaptation Strategies
+      │   │   ├─ When to adjust design references
+      │   │   └─ How to apply adjustments
+      │   ├─ Progressive Loading (3 levels)
+      │   ├─ Interactive Preview
+      │   ├─ Usage Guidelines
+      │   ├─ Package Structure
+      │   ├─ Regeneration
+      │   └─ Related Commands
+      ├─ Verify SKILL.md created successfully
+      └─ Display completion message with extracted design references

-No external commands called
-Direct file reading and writing
-Smart description generation from package data
+Data Flow:
+  design-tokens.json → jq extraction → PRIMARY_COLORS, TYPOGRAPHY_FONTS,
+                                       SPACING_SCALE, BORDER_RADIUS, SHADOWS
+  animation-tokens.json → jq extraction → ANIMATION_DURATIONS, EASING_FUNCTIONS
+  layout-templates.json → jq extraction → COMPONENT_TYPES, COMPONENT_COUNT
+
+  Extracted data → SKILL.md generation → Primary Design References section
+                                      → Dynamic Adjustment Guidelines
+                                      → Completion message display
 ```
--- a/.claude/commands/workflow/ui-design/explore-auto.md
+++ b/.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
--- a/.claude/commands/workflow/ui-design/import-from-code.md
+++ b/.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)
 ")
 ```
--- a/.claude/commands/workflow/ui-design/reference-page-generator.md
+++ b/.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