feat(memory): enhance style-skill-memory process by adding design system analysis and dynamic principle generation

2026-02-05 01:50:27 +08:00 · 2025-11-14 23:53:12 +08:00
parent ca18043b14
commit e4a29c0b2e
1 changed files with 236 additions and 66 deletions
--- a/.claude/commands/memory/style-skill-memory.md
+++ b/.claude/commands/memory/style-skill-memory.md
@@ -147,9 +147,9 @@ bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json &&
 Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")  # if exists
 ```

-**Step 2: Extract Metadata for Description**
+**Step 2: Extract Metadata & Analyze Design System**

-Only extract minimal metadata needed for intelligent SKILL description:
+**A. Extract Metadata for Description:**

 ```bash
 # Count components and classify by type
@@ -159,6 +159,36 @@ bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | leng
 bash(jq -r '.layout_templates | to_entries[] | select(.value.component_type == "universal") | .key' layout-templates.json | head -5)
 ```

+**B. Analyze Design System for Dynamic Principles:**
+
+Analyze design-tokens.json to extract characteristics and patterns:
+
+```bash
+# Analyze color system characteristics
+bash(jq '.colors | keys' design-tokens.json)  # Color token names (check for semantic naming)
+bash(jq '.colors | to_entries[0:2] | map(.value)' design-tokens.json)  # Sample color values
+
+# Detect spacing scale pattern
+bash(jq '.spacing | to_entries | map(.value) | map(gsub("[^0-9.]"; "") | tonumber)' design-tokens.json)
+# Analyze pattern: linear (4-8-12-16) vs geometric (4-8-16-32) vs custom
+
+# Analyze typography characteristics
+bash(jq '.typography | keys | map(select(contains("family") or contains("weight")))' design-tokens.json)
+bash(jq '.typography | to_entries | map(select(.key | contains("size"))) | .[].value' design-tokens.json)  # Size values
+
+# Analyze border radius style
+bash(jq '.border_radius | to_entries | map(.value)' design-tokens.json)
+# Check range: small values (sharp, modern) vs large values (rounded, friendly)
+
+# Analyze shadow characteristics
+bash(jq '.shadows | keys' design-tokens.json)  # Shadow naming (elevation levels)
+bash(jq '.shadows | to_entries[0].value' design-tokens.json)  # Sample shadow definition
+
+# Analyze animations (if available)
+bash(jq '.duration | to_entries | map(.value)' animation-tokens.json)  # Duration range
+bash(jq '.easing | keys' animation-tokens.json)  # Easing function variety
+```
+
 **Summary Variables**:
 - `COMPONENT_COUNT`: Total components
 - `UNIVERSAL_COUNT`: Universal components count
@@ -168,8 +198,22 @@ bash(jq -r '.layout_templates | to_entries[] | select(.value.component_type == "
 - `DESIGN_TOKENS_DATA`: Complete design-tokens.json content (from Read)
 - `LAYOUT_TEMPLATES_DATA`: Complete layout-templates.json content (from Read)
 - `ANIMATION_TOKENS_DATA`: Complete animation-tokens.json content (from Read, if available)
+- **`DESIGN_ANALYSIS`**: Analysis results for dynamic principle generation:
+  - `has_colors`: Colors exist (generate "Color System" principle)
+  - `color_semantic`: Has semantic naming (primary/secondary/accent pattern)
+  - `spacing_pattern`: Detected pattern type ("linear", "geometric", "custom")
+  - `spacing_scale`: Actual scale values (e.g., [4, 8, 16, 32, 64])
+  - `has_typography`: Typography system exists
+  - `typography_hierarchy`: Has size scale for hierarchy
+  - `has_radius`: Border radius exists
+  - `radius_style`: Style characteristic ("sharp" <4px, "moderate" 4-8px, "rounded" >8px)
+  - `has_shadows`: Shadow system exists
+  - `shadow_pattern`: Elevation naming pattern
+  - `has_animations`: Animation tokens exist
+  - `animation_range`: Duration range (fast to slow)
+  - `easing_variety`: Types of easing functions

-**Note**: All design token extraction (colors, typography, spacing, etc.) is performed directly in Phase 3 during SKILL.md generation using the read file contents, not through separate jq commands.
+**Note**: Analysis focuses on characteristics and patterns, not counts. Results guide which principles to include and what examples to show.

 **TodoWrite Update**:
 ```json
@@ -215,7 +259,17 @@ main-app-style-v1 project-independent design system with 5 universal layout temp

 Use Write tool to generate SKILL.md with the following optimized content.

-**Data Source**: All design token values (colors, typography, spacing, etc.) are extracted directly from the read JSON file contents (`DESIGN_TOKENS_DATA`, `LAYOUT_TEMPLATES_DATA`, `ANIMATION_TOKENS_DATA`) during SKILL.md generation. Template variables like `{FOR each color in ...}` iterate over the read data structure, not pre-extracted lists.
+**Data Sources**:
+1. **Design Token Values**: Iterate directly from `DESIGN_TOKENS_DATA`, `LAYOUT_TEMPLATES_DATA`, `ANIMATION_TOKENS_DATA`
+2. **Dynamic Principles**: Use `DESIGN_ANALYSIS` characteristics to generate context-specific principles:
+   - If `has_colors`: Include "Color System" with semantic pattern and examples
+   - If `spacing_pattern` detected: Include "Spatial Rhythm" with pattern type and scale
+   - If `has_typography` with hierarchy: Include "Typographic System" with scale examples
+   - If `has_radius`: Include "Shape Language" with style characteristic (sharp/moderate/rounded)
+   - If `has_shadows`: Include "Depth & Elevation" with pattern explanation
+   - If `has_animations`: Include "Motion & Timing" with duration range and easing variety
+   - Always include: "Accessibility First" principle
+3. **Examples**: Insert actual characteristics from analysis (e.g., `{radius_style}` → "moderate (4-8px, balanced approach)", `{spacing_pattern}` → "geometric progression (4→8→16→32)")

 ```markdown
 ---
@@ -258,36 +312,99 @@ description: {intelligent description from Step 2}

 ---

+## 📖 How to Use This SKILL
+
+### Quick Access Pattern
+
+**This SKILL provides design references, NOT executable code.** To use the design system:
+
+1. **Query JSON files with jq commands** (see [Quick Index](#-quick-index) for detailed commands)
+2. **Extract relevant tokens** for your implementation
+3. **Adapt values** based on your specific design needs
+
+### Basic Usage Examples
+
+```bash
+# View all colors
+jq '.colors' .workflow/reference_style/{package_name}/design-tokens.json
+
+# List universal components
+jq -r '.layout_templates | to_entries[] | select(.value.component_type == "universal") | .key' \
+  .workflow/reference_style/{package_name}/layout-templates.json
+
+# Get specific component structure
+jq '.layout_templates["button"]' .workflow/reference_style/{package_name}/layout-templates.json
+```
+
+### Progressive Loading
+
+- **Level 0** (~5K tokens): Quick token reference with `jq '.colors'`, `jq '.typography'`
+- **Level 1** (~12K tokens): Component filtering with `select(.component_type == "universal")`
+- **Level 2** (~20K tokens): Complex queries, animations, and preview
+
+**See [Quick Index](#-quick-index) section below for comprehensive jq command guide.**
+
+---
+
 ## 🎨 Style Understanding & Design References

 **IMPORTANT**: Reference values extracted from codebase. Dynamically adjust based on specific design needs.

 ### Design Principles

-**Visual Hierarchy**
- Use scale, color, and spacing to establish clear information hierarchy
- Primary actions and content should be immediately recognizable
- Guide user attention through deliberate contrast and emphasis
+**Dynamically generated based on design token characteristics:**

-**Consistency**
- Maintain consistent token usage across components (spacing, colors, typography)
- Repeated patterns create familiarity and reduce cognitive load
- Systematic application builds trust and predictability
+{ANALYZE design-tokens.json characteristics and generate context-specific principles:

-**Contrast & Balance**
- High contrast for critical actions and accessibility (WCAG AA/AAA)
- Balance visual weight through size, color intensity, and whitespace
- Harmonious color relationships using systematic palette
+IF has_colors:
+**Color System**
+- Semantic naming: {color_semantic ? "primary/secondary/accent hierarchy" : "descriptive names"}
+- Use color intentionally to guide attention and convey meaning
+- Maintain consistent color relationships for brand identity
+- Ensure sufficient contrast ratios (WCAG AA/AAA) for accessibility

-**Rhythm & Flow**
- Progressive spacing scale creates natural visual rhythm (e.g., 4px base × 2^n)
- Typography scale establishes typographic rhythm and readability
- Animation easing creates natural, fluid motion feeling
+IF spacing_pattern detected:
+**Spatial Rhythm**
+- Scale pattern: {spacing_pattern} (e.g., "geometric: 4→8→16→32→64" or "linear: 4→8→12→16")
+- Actual scale: {spacing_scale} creates consistent visual rhythm
+- {spacing_pattern == "geometric" ? "Exponential growth provides clear hierarchy" : "Linear progression offers subtle gradations"}
+- Apply systematically: smaller values for compact elements, larger for breathing room

-**Readability & Accessibility**
- Minimum 4.5:1 contrast for text (WCAG AA)
- Clear typographic hierarchy with adequate line-height
- Touch targets ≥44px for mobile, adequate spacing for interaction
+IF has_typography with typography_hierarchy:
+**Typographic System**
+- Type scale establishes content hierarchy and readability
+- Size progression: {typography_scale_example} (e.g., "12px→14px→16px→20px→24px")
+- Use scale consistently: body text at base, headings at larger sizes
+- Maintain adequate line-height for readability (1.4-1.6 for body text)
+
+IF has_radius:
+**Shape Language**
+- Radius style: {radius_style} (e.g., "sharp <4px: modern, technical" or "rounded >8px: friendly, approachable")
+- Creates visual personality: sharp = precision, rounded = warmth
+- Apply consistently across similar elements (all cards, all buttons)
+- Match to brand tone: corporate/technical = sharper, consumer/friendly = rounder
+
+IF has_shadows:
+**Depth & Elevation**
+- Shadow pattern: {shadow_pattern} (e.g., "elevation-based: subtle→moderate→prominent")
+- Use shadows to indicate interactivity and component importance
+- Consistent application reinforces spatial relationships
+- Subtle for static cards, prominent for floating/interactive elements
+
+IF has_animations:
+**Motion & Timing**
+- Duration range: {animation_range} (e.g., "100ms (fast feedback) to 300ms (content transitions)")
+- Easing variety: {easing_variety} (e.g., "ease-in-out for natural motion, ease-out for UI responses")
+- Fast durations for immediate feedback, slower for spatial changes
+- Consistent timing creates predictable, polished experience
+
+ALWAYS include:
+**Accessibility First**
+- Minimum 4.5:1 contrast for text, 3:1 for UI components (WCAG AA)
+- Touch targets ≥44px for mobile interaction
+- Clear focus states for keyboard navigation
+- Test with screen readers and keyboard-only navigation
+}

 ---

@@ -637,14 +754,25 @@ See SKILL.md for detailed commands and usage examples.
 ### Optimized SKILL.md Structure

 ```
-Package Overview (concise)
-Core Rules (3 rules, consolidated from all previous warnings)
+Package Overview (concise with JSON file paths)
+Core Rules (3 rules, consolidated)
+How to Use This SKILL (NEW - explains jq query approach with examples)
+  ├─ Quick Access Pattern (3-step process)
+  ├─ Basic Usage Examples (3 jq commands)
+  └─ Progressive Loading overview
 Style Understanding & Design References
-  ├─ Design Principles (5 art rules: hierarchy, consistency, contrast, rhythm, accessibility)
+  ├─ Design Principles (DYNAMIC - based on characteristics, not counts)
+  │   ├─ Color System (if colors exist, show semantic pattern)
+  │   ├─ Spatial Rhythm (if spacing exists, show pattern: linear/geometric + actual scale)
+  │   ├─ Typographic System (if hierarchy exists, show size progression)
+  │   ├─ Shape Language (if radius exists, show style: sharp/moderate/rounded)
+  │   ├─ Depth & Elevation (if shadows exist, show elevation pattern)
+  │   ├─ Motion & Timing (if animations exist, show duration range + easing)
+  │   └─ Accessibility First (always included)
  └─ Design Token Values (colors, typography, spacing, radius, shadows, animations)
 Quick Index
  ├─ Available JSON Fields (high-level structure)
-  ├─ Progressive jq Usage Guide (Level 0-2)
+  ├─ Progressive jq Usage Guide (Level 0-2, concise generic patterns)
  └─ Common Query Cheatsheet
 Package Structure
 Regenerate command
@@ -662,15 +790,17 @@ Regenerate command

 ## Benefits

- **Simplified Data Flow**: Read complete JSON files once, iterate during generation (eliminates 10+ jq extraction commands)
- **Enhanced Design Understanding**: 5 art principles (hierarchy, consistency, contrast, rhythm, accessibility) provide design context
- **Cleaner Structure**: Organized into Core Rules + Style Understanding (principles + tokens) + Quick Index
- **No Content Overlap**: Single Core Rules section + focused Design Principles section
+- **Clear Usage Instructions**: New "How to Use This SKILL" section explains jq query approach with 3 concrete examples
+- **Characteristic-Based Principles**: Generated from design token characteristics (patterns, styles, ranges), not counts
+- **Smart Analysis**: jq analyzes semantic naming, spacing patterns (linear/geometric), radius style (sharp/rounded), shadow elevation, animation ranges
+- **Meaningful Insights**: Focus on design implications (e.g., "rounded radius = friendly" vs "10 radius tokens")
+- **Conditional Principles**: Only include relevant design aspects based on token existence and characteristics
+- **JSON File Paths**: Package Overview clearly lists all JSON file locations
+- **Read Once, Analyze Characteristics**: Complete files read once, then extract patterns with jq
 - **Universal jq Patterns**: Generic patterns with placeholders for flexible querying
- **Fast Context Loading**: Progressive levels (5K/12K/20K tokens) with concise jq guide
+- **Progressive Loading Guide**: 3-level approach with token estimates and use cases
 - **Component Filtering**: Clear universal/specialized distinction with filtering commands
- **Self-Contained**: All loading logic embedded, no dependencies on external scripts
- **Intelligent Triggering**: Keywords optimize SKILL activation
+- **Self-Contained**: All loading logic embedded, no external dependencies
 - **Easy Regeneration**: Simple --regenerate flag for updates

 ---
@@ -684,26 +814,41 @@ style-skill-memory (Optimized)
  │   ├─ Check package exists in .workflow/reference_style/
  │   └─ Check if SKILL already exists (skip if exists and no --regenerate)
  │
-  ├─ Phase 2: Read Package Data
+  ├─ Phase 2: Read Package Data & Analyze Design System
  │   ├─ Read design-tokens.json (complete content)
  │   ├─ Read layout-templates.json (complete content)
  │   ├─ Read animation-tokens.json (if exists, complete content)
-  │   └─ Extract minimal metadata for description:
-  │       ├─ Component count
-  │       ├─ Universal/specialized counts
-  │       └─ Universal component names (first 5)
+  │   ├─ Extract metadata for description (using jq):
+  │   │   ├─ Component count
+  │   │   ├─ Universal/specialized counts
+  │   │   └─ Universal component names (first 5)
+  │   └─ Analyze design system (using jq on read data):
+  │       ├─ Color count and examples
+  │       ├─ Spacing pattern detection (geometric progression)
+  │       ├─ Typography system (fonts/weights count)
+  │       ├─ Border radius count and examples
+  │       ├─ Shadow levels count
+  │       └─ Animation durations (if available)
  │
  └─ Phase 3: Generate Optimized SKILL.md
      ├─ Create SKILL directory
      ├─ Generate intelligent description with keywords
      ├─ Write SKILL.md with optimized structure:
-      │   ├─ Package Overview (concise)
-      │   ├─ Core Rules (3 rules, single consolidated section)
+      │   ├─ Package Overview (with JSON file paths)
+      │   ├─ Core Rules (3 rules)
+      │   ├─ How to Use This SKILL (NEW - jq query examples and loading guide)
      │   ├─ Style Understanding & Design References
-      │   │   ├─ Design Principles (5 art rules: hierarchy, consistency, contrast, rhythm, accessibility)
-      │   │   └─ Design Token Values (colors, typography, spacing, radius, shadows, animations)
+      │   │   ├─ Design Principles (DYNAMIC - based on characteristics)
+      │   │   │   ├─ Color System (if colors exist, with semantic pattern)
+      │   │   │   ├─ Spatial Rhythm (if spacing exists, with pattern: linear/geometric)
+      │   │   │   ├─ Typographic System (if typography hierarchy exists)
+      │   │   │   ├─ Shape Language (if radius exists, with style: sharp/moderate/rounded)
+      │   │   │   ├─ Depth & Elevation (if shadows exist, with elevation pattern)
+      │   │   │   ├─ Motion & Timing (if animations exist, with duration range)
+      │   │   │   └─ Accessibility First (always included)
+      │   │   └─ Design Token Values (iterate from read data)
      │   ├─ Quick Index
-      │   │   ├─ Available JSON Fields (high-level structure)
+      │   │   ├─ Available JSON Fields
      │   │   ├─ Progressive jq Usage Guide (Level 0-2)
      │   │   └─ Common Query Cheatsheet
      │   ├─ Package Structure
@@ -712,30 +857,55 @@ style-skill-memory (Optimized)
      └─ Display concise completion message

 Data Flow:
-  Read Files:
-    design-tokens.json → DESIGN_TOKENS_DATA (complete)
-    layout-templates.json → LAYOUT_TEMPLATES_DATA (complete)
-    animation-tokens.json → ANIMATION_TOKENS_DATA (if available, complete)
+  Read Files (Phase 2A):
+    design-tokens.json → Read → DESIGN_TOKENS_DATA (complete JSON)
+    layout-templates.json → Read → LAYOUT_TEMPLATES_DATA (complete JSON)
+    animation-tokens.json → Read → ANIMATION_TOKENS_DATA (if available, complete JSON)

-  Minimal Extraction (for description only):
-    layout-templates.json → jq → COMPONENT_COUNT, UNIVERSAL_COUNT,
-                                  SPECIALIZED_COUNT, UNIVERSAL_COMPONENTS (first 5)
+  Analysis with jq (Phase 2B - on read data):
+    DESIGN_TOKENS_DATA → jq commands → DESIGN_ANALYSIS (characteristics):
+      ├─ jq '.colors | keys' → color_semantic (check naming pattern)
+      ├─ jq '.spacing | ... | map(tonumber)' → spacing_pattern (linear/geometric/custom)
+      ├─ jq '.spacing | ...' → spacing_scale (actual values)
+      ├─ jq '.typography | ...' → typography_hierarchy (size scale exists)
+      ├─ jq '.border_radius | map(.value)' → radius_style (sharp/moderate/rounded)
+      ├─ jq '.shadows | keys' → shadow_pattern (naming convention)
+      └─ jq '.duration | map(.value)' → animation_range (if animations)

-  SKILL.md Generation:
-    Read file contents → Direct iteration during Write → Package Overview
-                                                       → Core Rules
-                                                       → Design Principles (static)
-                                                       → Design Token Values (iterate DESIGN_TOKENS_DATA)
-                                                       → Quick Index
-                                                       → Completion message
+    LAYOUT_TEMPLATES_DATA → jq commands → Metadata:
+      ├─ jq '.layout_templates | length' → COMPONENT_COUNT
+      ├─ jq '[... | select(.component_type == "universal")]' → UNIVERSAL_COUNT
+      └─ jq -r '... | .key' → UNIVERSAL_COMPONENTS (first 5)
+
+  SKILL.md Generation (Phase 3 - uses both read data and analysis):
+    DESIGN_ANALYSIS → Dynamic Principles (based on characteristics):
+      ├─ IF has_colors → "Color System" (with semantic pattern)
+      ├─ IF spacing_pattern detected → "Spatial Rhythm" (with pattern type & scale)
+      ├─ IF has_typography_hierarchy → "Typographic System" (with scale examples)
+      ├─ IF has_radius → "Shape Language" (with style: sharp/moderate/rounded)
+      ├─ IF has_shadows → "Depth & Elevation" (with elevation pattern)
+      ├─ IF has_animations → "Motion & Timing" (with duration range & easing)
+      └─ ALWAYS → "Accessibility First"
+
+    DESIGN_TOKENS_DATA → Direct Iteration → Design Token Values
+
+    Final SKILL.md Structure:
+      ├─ Package Overview (with JSON paths)
+      ├─ Core Rules
+      ├─ How to Use This SKILL (NEW - jq examples)
+      ├─ Design Principles (DYNAMIC from DESIGN_ANALYSIS)
+      ├─ Design Token Values (iterate from DESIGN_TOKENS_DATA)
+      └─ Quick Index (fields + jq guide + cheatsheet)

 Optimization Impact:
-  ✅ Simplified Phase 2 (Read files once instead of 10+ jq extractions)
-  ✅ Cleaner structure with art principles (~250 → ~280 lines with design rules)
-  ✅ Zero content overlap (1 Core Rules + 1 Design Principles section)
-  ✅ Enhanced understanding (5 art rules for design context)
-  ✅ Direct iteration (generate SKILL.md from read data, not pre-extracted variables)
-  ✅ Embedded commands (no external script dependencies)
-  ✅ Package-specific queries (exact paths in jq commands)
+  ✅ Read once, analyze characteristics (Phase 2A: Read, Phase 2B: Extract patterns/styles)
+  ✅ Usage rules included ("How to Use This SKILL" with jq examples)
+  ✅ Characteristic-based principles (patterns, not counts: "geometric spacing" vs "8 spacing tokens")
+  ✅ Meaningful insights (design implications: "sharp=modern" vs "radius count")
+  ✅ Context-specific principles (6-7 based on actual characteristics)
+  ✅ Direct iteration for token values (from DESIGN_TOKENS_DATA)
+  ✅ Conditional principle inclusion (based on token existence & characteristics)
+  ✅ Embedded jq for analysis (maintains clear command examples)
+  ✅ Clear JSON file paths (Package Overview lists all locations)
  ✅ Self-contained loading (all logic in SKILL.md)
 ```