Claude-Code-Workflow/.claude/commands/memory/style-skill-memory.md

name, description, argument-hint, allowed-tools, auto-continue

name	description	argument-hint	allowed-tools	auto-continue
style-skill-memory	Generate SKILL memory package from style reference for easy loading and consistent design system usage	[package-name] [--regenerate]	Bash,Read,Write,TodoWrite	true

Memory: Style SKILL Memory Generator

Overview

Purpose: Convert style reference package into SKILL memory for easy loading and context management.

Input: Style reference package at .workflow/reference_style/{package-name}/

Output: SKILL memory index at .claude/skills/style-{package-name}/SKILL.md

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

Command Syntax

/memory:style-skill-memory [package-name] [--regenerate]

# Arguments
package-name    Style reference package name (required)
--regenerate    Force regenerate SKILL.md even if it exists (optional)

Usage Examples

# Generate SKILL memory for package
/memory:style-skill-memory main-app-style-v1

# Regenerate SKILL memory
/memory:style-skill-memory main-app-style-v1 --regenerate

# Package name from current directory or default
/memory:style-skill-memory

---

Execution Process

Phase 1: Validate Package

Purpose: Check if style reference package exists

TodoWrite (First Action):

[
  {"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"},
  {"content": "Read package data", "status": "pending", "activeForm": "Reading package data"},
  {"content": "Generate SKILL.md with design references", "status": "pending", "activeForm": "Generating SKILL.md"}
]

Step 1: Parse Package Name

# Get package name from argument or auto-detect
bash(echo "${package_name}" || basename "$(pwd)" | sed 's/^style-//')

Store result as package_name

Step 2: Validate Package Exists

bash(test -d .workflow/reference_style/${package_name} && echo "exists" || echo "missing")

Error Handling:

if (package_not_exists) {
  error("ERROR: Style reference package not found: ${package_name}")
  error("HINT: Run '/workflow:ui-design:codify-style' first to create package")
  error("Available packages:")
  bash(ls -1 .workflow/reference_style/ 2>/dev/null || echo "  (none)")
  exit(1)
}

Step 3: Check SKILL Already Exists

bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "exists" || echo "missing")

Decision Logic:

if (skill_exists && !regenerate_flag) {
  echo("SKILL memory already exists for: ${package_name}")
  echo("Use --regenerate to force regeneration")
  exit(0)
}

if (regenerate_flag && skill_exists) {
  echo("Regenerating SKILL memory for: ${package_name}")
}

Summary Variables:

• PACKAGE_NAME: Style reference package name
• PACKAGE_DIR: .workflow/reference_style/${package_name}
• SKILL_DIR: .claude/skills/style-${package_name}
• REGENERATE: true if --regenerate flag, false otherwise

TodoWrite Update:

[
  {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
  {"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"}
]

---

Phase 2: Read Package Data

Purpose: Read all package files for SKILL description generation

Step 1: Read All JSON Files

# Read layout templates
Read(file_path=".workflow/reference_style/${package_name}/layout-templates.json")

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

# Read animation tokens (if exists)
bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "exists" || echo "missing")
Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")  # if exists

Step 2: Extract Metadata & Analyze Design System

A. Extract Metadata for Description:

# Count components and classify by type
bash(jq '.layout_templates | length' layout-templates.json)
bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' layout-templates.json)
bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' layout-templates.json)
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:

# 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
• SPECIALIZED_COUNT: Specialized components count
• UNIVERSAL_COMPONENTS: Universal component names (first 5 for description)
• HAS_ANIMATIONS: Whether animation-tokens.json exists
• 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: Analysis focuses on characteristics and patterns, not counts. Results guide which principles to include and what examples to show.

TodoWrite Update:

[
  {"content": "Read package data", "status": "completed", "activeForm": "Reading package data"},
  {"content": "Generate SKILL.md with design references", "status": "in_progress", "activeForm": "Generating SKILL.md"}
]

---

Phase 3: Generate SKILL.md

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

Step 1: Create SKILL Directory

bash(mkdir -p .claude/skills/style-${package_name})

Step 2: Generate Intelligent Description

Format:

{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.

Key Elements:

• Universal Count: Emphasize available reusable layout templates
• Project Independence: Clearly state project-independent nature
• Specialized Exclusion: Mention excluded project-specific components
• Path Reference: Precise package location
• Trigger Keywords: reusable UI components, design tokens, layout patterns, visual consistency
• Action Coverage: working with, analyzing, implementing

Example:

main-app-style-v1 project-independent design system with 5 universal layout templates and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes 3 project-specific components.

Step 3: Write SKILL.md

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

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)")

---
name: style-{package_name}
description: {intelligent description from Step 2}
---

# {Package Name} Style SKILL Package

## Package Overview

**Base Location**: `.workflow/reference_style/{package_name}/`

**JSON Files**:
- **Design Tokens**: `.workflow/reference_style/{package_name}/design-tokens.json`
- **Layout Templates**: `.workflow/reference_style/{package_name}/layout-templates.json`
- **Animation Tokens**: `.workflow/reference_style/{package_name}/animation-tokens.json` {has_animations ? "(available)" : "(not available)"}

**Package Details**:
- Package: {package_name}
- Layout Templates: {component_count} total
  - **Universal Components**: {universal_count} (reusable, project-independent)
  - **Specialized Components**: {specialized_count} (project-specific, excluded)
- Universal Component Types: {comma-separated list of UNIVERSAL_COMPONENTS}
- Preview: `.workflow/reference_style/{package_name}/preview.html`

---

## ⚡ Core Rules

1. **Project-Independent Reference**: This is a style reference system. All patterns and tokens are adaptable starting points, not fixed constraints.

2. **Universal Components Only**: When using `layout-templates.json`, **ONLY** reference components where `component_type: "universal"`. **IGNORE** `component_type: "specialized"`.

3. **Token Adaptation**: Adjust design tokens (colors, spacing, typography, shadows, etc.) based on:
   - Brand requirements and identity
   - Accessibility standards (WCAG compliance, readability)
   - Platform conventions (mobile/desktop, iOS/Android/Web)
   - Context needs (light/dark mode, responsive breakpoints)

---

## 📖 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 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

Dynamically generated based on design token characteristics:

{ANALYZE design-tokens.json characteristics and generate context-specific principles:

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

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

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 }

---

Design Token Values

Colors

{FOR each color in PRIMARY_COLORS:

• {color.key}: {color.value} }

Typography

{FOR each font in TYPOGRAPHY_FONTS:

• {font.key}: {font.value} }

Spacing Scale

{FOR each spacing in SPACING_SCALE:

• {spacing.key}: {spacing.value} }

Border Radius

{FOR each radius in BORDER_RADIUS:

• {radius.key}: {radius.value} }

Shadows

{FOR each shadow in SHADOWS:

• {shadow.key}: {shadow.value} }

{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} } }

---

🔍 Quick Index

Available JSON Fields

High-level structure overview for quick understanding

design-tokens.json

.colors             # Color palette (brand, semantic, surface, text, border)
.typography         # Font families, sizes, weights, line heights
.spacing            # Spacing scale (xs, sm, md, lg, xl, etc.)
.border_radius      # Border radius tokens (sm, md, lg, etc.)
.shadows            # Shadow definitions (elevation levels)
._metadata          # Usage recommendations and guidelines
  ├─ .usage_recommendations.typography
  ├─ .usage_recommendations.spacing
  └─ ...

layout-templates.json

.layout_templates                    # Component layout patterns
  ├─ .<component_name>
  │   ├─ .component_type            # "universal" or "specialized"
  │   ├─ .variants                  # Component variants array
  │   ├─ .usage_guide               # Usage guidelines
  │   │   ├─ .common_sizes
  │   │   ├─ .variant_recommendations
  │   │   ├─ .usage_context
  │   │   └─ .accessibility_tips
  │   └─ ...

animation-tokens.json (if available)

.duration           # Animation duration tokens
.easing            # Easing function tokens

---

Progressive jq Usage Guide

🔰 Level 0: Basic Queries (~5K tokens)

# View entire file
jq '.' <file>.json

# List top-level keys
jq 'keys' <file>.json

# Extract specific field
jq '.<field_name>' <file>.json

Use when: Quick reference, first-time exploration

---

🎯 Level 1: Filter & Extract (~12K tokens)

# Count items
jq '.<field> | length' <file>.json

# Filter by condition
jq '[.<field>[] | select(.<key> == "<value>")]' <file>.json

# Extract names
jq -r '.<field> | to_entries[] | select(<condition>) | .key' <file>.json

# Formatted output
jq -r '.<field> | to_entries[] | "\(.key): \(.value)"' <file>.json

Universal components filter: select(.component_type == "universal")

Use when: Building components, filtering data

---

🚀 Level 2: Combine & Transform (~20K tokens)

# Pattern search
jq '.<field> | keys[] | select(. | contains("<pattern>"))' <file>.json

# Regex match
jq -r '.<field> | to_entries[] | select(.key | test("<regex>"; "i"))' <file>.json

# Multi-file query
jq '.' file1.json && jq '.' file2.json

# Nested extraction
jq '.<field>["<name>"].<nested_field>' <file>.json

# Preview server
cd .workflow/reference_style/{package_name} && python -m http.server 8080

Use when: Complex queries, comprehensive analysis

---

Common Query Cheatsheet

Task	Pattern
View field	jq '.<field>' <file>.json
List names	jq -r '.<field> | keys[]' <file>.json
Count items	jq '.<field> | length' <file>.json
Filter universal	jq '[.<field>[] | select(.component_type == "universal")]' <file>.json
Preview	cd .workflow/reference_style/{package_name} && python -m http.server 8080

---

Package Structure

.workflow/reference_style/{package_name}/
├── layout-templates.json   # Layout templates from codebase
├── design-tokens.json     # Design token system
├── animation-tokens.json  # Animation tokens (optional)
├── preview.html          # Interactive showcase
└── preview.css           # Showcase styling

---

Regenerate

/memory:style-skill-memory {package_name} --regenerate

**Step 4: Verify SKILL.md Created**

```bash
bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" || echo "failed")

TodoWrite Update:

[
  {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
  {"content": "Read package data", "status": "completed", "activeForm": "Reading package data"},
  {"content": "Generate SKILL.md with design references", "status": "completed", "activeForm": "Generating SKILL.md"}
]

Final Action: Report completion summary to user

---

Completion Message

Display concise completion summary to user:

✅ SKILL memory generated successfully!

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

📦 Package Summary:
- Layout Templates: {component_count} total ({universal_count} universal, {specialized_count} specialized)
- Universal Components: {show first 5 UNIVERSAL_COMPONENTS, then "+ X more"}
- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}

🎨 Primary Design References:
{IF PRIMARY_COLORS exists:
  - Colors: {show first 3 PRIMARY_COLORS keys only, then "+ X more"}
}
{IF TYPOGRAPHY_FONTS exists:
  - Typography: {show all TYPOGRAPHY_FONTS keys only}
}
{IF SPACING_SCALE exists:
  - Spacing Scale: {count SPACING_SCALE} tokens
}
{IF BORDER_RADIUS exists:
  - Border Radius: {count BORDER_RADIUS} tokens
}
{IF SHADOWS exists:
  - Shadows: {count SHADOWS} tokens
}
{IF HAS_ANIMATIONS:
  - Animation: {count ANIMATION_DURATIONS} durations, {count EASING_FUNCTIONS} easing functions
}

⚡ Quick Index:
- Level 0: Basic Queries (~5K) - View structure, extract categories
- Level 1: Filter & Extract (~12K) - Filter universal components, format output
- Level 2: Combine & Transform (~20K) - Search patterns, combine queries, preview

💡 Quick Start:
```bash
# List universal components
jq -r '.layout_templates | to_entries[] | select(.value.component_type == "universal") | .key' \
  .workflow/reference_style/{package_name}/layout-templates.json

# Extract colors
jq '.colors' .workflow/reference_style/{package_name}/design-tokens.json

# View preview
cd .workflow/reference_style/{package_name} && python -m http.server 8080

📋 Core Rules:

1. Project-Independent Reference - Tokens are adaptable starting points
2. Universal Components Only - Filter component_type: "universal"
3. Token Adaptation - Adjust for brand, accessibility, platform, context

See SKILL.md for detailed commands and usage examples.

---

## Error Handling

### Common Errors

| Error | Cause | Resolution |
|-------|-------|------------|
| Package not found | Invalid package name or package doesn't exist | Run codify-style first to create package |
| SKILL already exists | SKILL.md already generated | Use --regenerate to force regeneration |
| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style |
| Invalid JSON format | Corrupted package files | Regenerate package with codify-style |

---

## Implementation Details

### Critical Rules

1. **Check Before Generate**: Verify package exists before attempting SKILL generation
2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
3. **Extract Primary References**: Extract key design values (colors, typography, spacing, border radius, shadows, animations) with values only, no verbose guidelines
4. **Embed jq Commands**: Include bash/jq commands in SKILL.md for dynamic loading, not external scripts
5. **Progressive Loading**: Include all 3 levels (0-2) with specific jq commands for each level
6. **Intelligent Description**: Extract component count and key features from metadata
7. **Minimize Redundancy**: Single Core Rules section, no repeated warnings or usage guidelines

### SKILL Description Format

**Template**:

{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.

**Required Elements**:
- Package name
- Universal layout template count (emphasize reusability)
- Project independence statement
- Specialized component exclusion notice
- Location (full path)
- Trigger keywords (reusable UI components, design tokens, layout patterns, visual consistency)
- Action verbs (working with, analyzing, implementing)

### Design Token Display in SKILL.md

**No Pre-Extraction Required**: Design token values (colors, typography, spacing, etc.) are NOT extracted in Phase 2. Instead, they are directly accessed from the read file contents during SKILL.md generation in Phase 3.

**Display Strategy**:
- **Colors**: Iterate `DESIGN_TOKENS_DATA.colors` and display all key-value pairs
- **Typography**: Iterate `DESIGN_TOKENS_DATA.typography` and display all key-value pairs
- **Spacing**: Iterate `DESIGN_TOKENS_DATA.spacing` and display all key-value pairs
- **Border Radius**: Iterate `DESIGN_TOKENS_DATA.border_radius` and display all key-value pairs
- **Shadows**: Iterate `DESIGN_TOKENS_DATA.shadows` and display all key-value pairs
- **Animations** (if available): Iterate `ANIMATION_TOKENS_DATA.duration` and `ANIMATION_TOKENS_DATA.easing`

**Component Classification** (minimal extraction for description only):
- Universal Count: `jq '[.layout_templates[] | select(.component_type == "universal")] | length'`
- Specialized Count: `jq '[.layout_templates[] | select(.component_type == "specialized")] | length'`
- Universal Component Names: `jq -r '.layout_templates | to_entries[] | select(.value.component_type == "universal") | .key' | head -5`

**Benefit**: Eliminates 10+ separate jq extraction commands in Phase 2, simplifies data flow.

### Progressive Loading Structure with Embedded Commands

**Level 0** (~5K tokens):
- Embed jq commands to query design-tokens.json
- Commands for extracting colors, typography, spacing categories

**Level 1** (~12K tokens):
- Embed jq commands to filter universal components
- Commands for listing component names, getting specific components
- Include component_type filtering examples

**Level 2** (~20K tokens):
- Embed jq commands for animation-tokens.json
- Include preview server command
- Comprehensive query examples

### Optimized SKILL.md Structure

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 (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, concise generic patterns) └─ Common Query Cheatsheet Package Structure Regenerate command

**Removed Sections** (to eliminate redundancy):
- ❌ Usage Guidelines per token category
- ❌ Design Adaptation Strategies section
- ❌ Interactive Preview section (condensed into Level 2)
- ❌ Usage Guidelines section
- ❌ Related Commands section (condensed into Regenerate)
- ❌ All repeated Project Independence warnings

---

## Benefits

- **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
- **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 external dependencies
- **Easy Regeneration**: Simple --regenerate flag for updates

---

## Architecture

style-skill-memory (Optimized) ├─ 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 & Analyze Design System │ ├─ Read design-tokens.json (complete content) │ ├─ Read layout-templates.json (complete content) │ ├─ Read animation-tokens.json (if exists, complete content) │ ├─ 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 (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 (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 │ │ ├─ Progressive jq Usage Guide (Level 0-2) │ │ └─ Common Query Cheatsheet │ ├─ Package Structure │ └─ Regenerate command ├─ Verify SKILL.md created successfully └─ Display concise completion message

Data Flow: 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)

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)

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: ✅ 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)