From e4a29c0b2ec75a3cd601673739bec8c0b9d611e8 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Fri, 14 Nov 2025 23:53:12 +0800 Subject: [PATCH] feat(memory): enhance style-skill-memory process by adding design system analysis and dynamic principle generation --- .claude/commands/memory/style-skill-memory.md | 302 ++++++++++++++---- 1 file changed, 236 insertions(+), 66 deletions(-) diff --git a/.claude/commands/memory/style-skill-memory.md b/.claude/commands/memory/style-skill-memory.md index 2c337ab8..c3c9f5e0 100644 --- 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) ```