refactor(ui-design): enhance layout extraction documentation and output files

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

@@ -308,25 +308,35 @@ Task(ui-design-agent): `
 
   **Target Directory**: ${base_path}/layout-extraction/
 
-  **File to Generate**:
-  **layout-templates.json**
-  - Follow [LAYOUT_TEMPLATE_GENERATION_TASK] standard structure
-  - Add "extraction_metadata" section:
-    * extraction_source: "code_import"
-    * naming_convention: detected convention
-    * layout_system: {type, confidence, source_files}
-    * responsive: {breakpoints, mobile_first, source}
-    * completeness: {status, missing_items, recommendations}
-  - For each component in "layout_templates":
-    * Include "source" field (file:line)
-    * dom_structure with semantic HTML5
-    * css_layout_rules using var() placeholders
+  **Files to Generate**:
+
+  1. **layout-templates.json**
+     - Follow [LAYOUT_TEMPLATE_GENERATION_TASK] standard structure
+     - Add "extraction_metadata" section:
+       * extraction_source: "code_import"
+       * naming_convention: detected convention
+       * layout_system: {type, confidence, source_files}
+       * responsive: {breakpoints, mobile_first, source}
+       * completeness: {status, missing_items, recommendations}
+     - For each component in "layout_templates":
+       * Include "source" field (file:line)
+       * dom_structure with semantic HTML5
+       * css_layout_rules using var() placeholders
+
+  2. **layout-guide.md**
+     - Layout System Overview: Document detected naming convention and layout system
+     - Component Patterns: List extracted components with variants and states
+     - Responsive Strategy: Explain breakpoint system and mobile-first approach
+     - Usage Guidelines: How to use the extracted patterns
+     - Code Examples: Show actual usage from source files
+     - Missing Patterns: Document gaps and recommendations
 
   ## Code Import Specific Requirements
   - ✅ Read discovered-files.json FIRST to get file paths
   - ✅ Detect and document naming conventions
   - ✅ Identify layout system with confidence level
   - ✅ Extract component variants and states from usage patterns
+  - ✅ Generate BOTH JSON + MD files for complete documentation
   - ❌ NO external research or MCP calls (code-only extraction)
 `
 ```
@@ -369,7 +379,8 @@ ${base_path}/
 │   ├── animation-tokens.json        # Animation/transition tokens
 │   └── animation-guide.md           # Animation usage guide
 ├── layout-extraction/
-│   └── layout-templates.json        # Layout patterns and component structures
+│   ├── layout-templates.json        # Layout patterns and component structures
+│   └── layout-guide.md              # Layout system usage guide
 └── .intermediates/
     └── import-analysis/
         └── discovered-files.json    # All discovered files (JSON format)
@@ -400,6 +411,12 @@ ${base_path}/
    - Extraction metadata: naming_convention, layout_system, responsive strategy
    - Component patterns with DOM structure and CSS rules
 
+6. **layout-extraction/layout-guide.md**
+   - Layout system overview and detected conventions
+   - Component patterns documentation
+   - Responsive strategy and breakpoint usage
+   - Code examples from source files
+
 **Intermediate Files**: `.intermediates/import-analysis/`
 - `discovered-files.json` - All discovered files in JSON format with counts and metadata
 

.claude/commands/workflow/ui-design/layout-extract.md

@@ -644,19 +644,32 @@ FOR each task in task_list:
          - Device-specific styles (mobile-first @media for responsive)
          - NO colors, NO fonts, NO shadows - layout structure only
 
-      ## Output Format
-      Write single-template JSON object with:
-      - target: "{task.target}"
-      - variant_id: "layout-{task.variant_id}"
-      - source_image_path (string): Reference image path
-      - device_type: "{device_type}"
-      - design_philosophy (string from selected concept)
-      - dom_structure (JSON object)
-      - component_hierarchy (array of strings)
-      - css_layout_rules (string)
+      ## Output Files
+
+      Generate 2 files:
+
+      1. **layout-templates.json** - {task.output_file}
+         Write single-template JSON object with:
+         - target: "{task.target}"
+         - variant_id: "layout-{task.variant_id}"
+         - source_image_path (string): Reference image path
+         - device_type: "{device_type}"
+         - design_philosophy (string from selected concept)
+         - dom_structure (JSON object)
+         - component_hierarchy (array of strings)
+         - css_layout_rules (string)
+
+      2. **layout-guide.md** - {task.output_file.replace('.json', '-guide.md')}
+         Write layout system guide with:
+         - Layout Philosophy: Design philosophy from selected concept
+         - Component Hierarchy: Description of layout regions and their purpose
+         - Layout Pattern: Explanation of grid/flexbox structure
+         - Responsive Strategy: Breakpoint behavior and device optimizations
+         - Usage Guidelines: How to implement and customize the layout
+         - Accessibility Notes: ARIA roles and semantic HTML structure
 
       ## Critical Requirements
-      - ✅ Use Write() tool for {task.output_file}
+      - ✅ Use Write() tool for BOTH files (JSON + MD)
       - ✅ Single template for {task.target} variant {task.variant_id}
       - ✅ Structure only, no visual styling
       - ✅ Token-based CSS (var())
@@ -724,6 +737,7 @@ Generated Templates:
 {FOR each target in targets:
   {FOR each variant_id in range(1, selections_per_target[target].selected_indices.length + 1):
     ├── layout-{target}-{variant_id}.json
+    └── layout-{target}-{variant_id}-guide.md
   }
 }
 
@@ -779,7 +793,8 @@ bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
 │       ├── analysis-options.json      # Generated layout concepts + user selections (embedded)
 │       └── dom-structure-{target}.json   # Extracted DOM structure (URL mode only)
 └── layout-extraction/                 # Final layout templates
-    └── layout-{target}-{variant}.json # Structural layout templates (one per selected concept)
+    ├── layout-{target}-{variant}.json # Structural layout template JSON
+    └── layout-{target}-{variant}-guide.md # Layout system usage guide
 ```
 
 ## Layout Template File Format

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

@@ -626,21 +626,3 @@ Next Steps:
 
 ---
 
-## Integration with Workflow
-
-This command is typically called by the `codify-style` orchestrator, but can also be run standalone:
-
-**Standalone Usage**:
-```bash
-# Step 1: Extract styles from code
-/workflow:ui-design:import-from-code --design-id design-run-123 --source ./src
-
-# Step 2: Generate reference package
-/workflow:ui-design:reference-page-generator --design-run .workflow/WFS-xxx/design-run-123 --package-name main-app-style-v1
-```
-
-**Orchestrator Usage** (via codify-style):
-```bash
-# Orchestrator handles both steps automatically
-/workflow:ui-design:codify-style --source ./src --package-name main-app-style-v1
-```