From f9c33bd0ba9b80f85d21ea04a1ac97bb6f1390d6 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 15 Nov 2025 10:09:45 +0800 Subject: [PATCH] Add SKILL.md template for Style Memory Package with comprehensive jq usage guide and design principles --- .claude/commands/memory/style-skill-memory.md | 901 ++++-------------- .../style-skill-memory/skill-md-template.md | 357 +++++++ 2 files changed, 556 insertions(+), 702 deletions(-) create mode 100644 .claude/workflows/cli-templates/memory/style-skill-memory/skill-md-template.md diff --git a/.claude/commands/memory/style-skill-memory.md b/.claude/commands/memory/style-skill-memory.md index c3c9f5e0..e7f13722 100644 --- a/.claude/commands/memory/style-skill-memory.md +++ b/.claude/commands/memory/style-skill-memory.md @@ -21,12 +21,14 @@ auto-continue: true **Key Features**: - Extracts primary design references (colors, typography, spacing, etc.) - Provides dynamic adjustment guidelines for design tokens +- Includes prerequisites and tooling requirements (browsers, PostCSS, dark mode) - Progressive loading structure for efficient token usage +- Complete implementation examples with React components - Interactive preview showcase --- -## Usage +## Quick Reference ### Command Syntax @@ -51,20 +53,77 @@ package-name Style reference package name (required) /memory:style-skill-memory ``` +### Key Variables + +**Input 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 + +**Data Sources** (Phase 2): +- `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 exists) + +**Metadata** (Phase 2): +- `COMPONENT_COUNT`: Total components +- `UNIVERSAL_COUNT`: Universal components count +- `SPECIALIZED_COUNT`: Specialized components count +- `UNIVERSAL_COMPONENTS`: Universal component names (first 5) +- `HAS_ANIMATIONS`: Whether animation-tokens.json exists + +**Analysis Output** (`DESIGN_ANALYSIS` - Phase 2): +- `has_colors`: Colors exist +- `color_semantic`: Has semantic naming (primary/secondary/accent) +- `uses_oklch`: Uses modern color spaces (oklch, lab, etc.) +- `has_dark_mode`: Has separate light/dark mode color tokens +- `spacing_pattern`: 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 +- `uses_calc`: Uses calc() expressions in token values +- `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 + +### Common Errors + +| Error | Cause | Resolution | +|-------|-------|------------| +| Package not found | Invalid package name or doesn't exist | Run `/workflow:ui-design:codify-style` first | +| SKILL already exists | SKILL.md already generated | Use `--regenerate` flag | +| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style | +| Invalid JSON format | Corrupted package files | Regenerate package with codify-style | + --- ## Execution Process ### Phase 1: Validate Package -**Purpose**: Check if style reference package exists - **TodoWrite** (First Action): ```json [ - {"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"} + { + "content": "Validate package exists and check SKILL status", + "activeForm": "Validating package and SKILL status", + "status": "in_progress" + }, + { + "content": "Read package data and analyze design system", + "activeForm": "Reading package data and analyzing design system", + "status": "pending" + }, + { + "content": "Generate SKILL.md with design principles and token values", + "activeForm": "Generating SKILL.md with design principles and token values", + "status": "pending" + } ] ``` @@ -75,8 +134,6 @@ package-name Style reference package name (required) bash(echo "${package_name}" || basename "$(pwd)" | sed 's/^style-//') ``` -Store result as `package_name` - **Step 2: Validate Package Exists** ```bash @@ -113,25 +170,11 @@ if (regenerate_flag && skill_exists) { } ``` -**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**: -```json -[ - {"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"} -] -``` +**TodoWrite Update**: Mark "Validate" as completed, "Read package data" as in_progress --- -### Phase 2: Read Package Data - -**Purpose**: Read all package files for SKILL description generation +### Phase 2: Read Package Data & Analyze Design System **Step 1: Read All JSON Files** @@ -147,9 +190,7 @@ 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 & Analyze Design System** - -**A. Extract Metadata for Description:** +**Step 2: Extract Metadata for Description** ```bash # Count components and classify by type @@ -159,76 +200,60 @@ 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:** +Store results in metadata variables (see [Key Variables](#key-variables)) + +**Step 3: 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 +# Color system characteristics +bash(jq '.colors | keys' design-tokens.json) +bash(jq '.colors | to_entries[0:2] | map(.value)' design-tokens.json) +# Check for modern color spaces +bash(jq '.colors | to_entries[] | .value | test("oklch|lab|lch")' design-tokens.json) +# Check for dark mode variants +bash(jq '.colors | keys | map(select(contains("dark") or contains("light")))' design-tokens.json) +# → Store: has_colors, color_semantic, uses_oklch, has_dark_mode -# Detect spacing scale pattern +# Spacing pattern detection 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 +# → Store: spacing_pattern, spacing_scale -# Analyze typography characteristics +# 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 +bash(jq '.typography | to_entries | map(select(.key | contains("size"))) | .[].value' design-tokens.json) +# Check for calc() usage +bash(jq '. | tostring | test("calc\\(")' design-tokens.json) +# → Store: has_typography, typography_hierarchy, uses_calc -# Analyze border radius style +# 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) +# Check range: small (sharp <4px) vs moderate (4-8px) vs large (rounded >8px) +# → Store: has_radius, radius_style -# 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 +# Shadow characteristics +bash(jq '.shadows | keys' design-tokens.json) +bash(jq '.shadows | to_entries[0].value' design-tokens.json) +# → Store: has_shadows, shadow_pattern -# 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 +# Animations (if available) +bash(jq '.duration | to_entries | map(.value)' animation-tokens.json) +bash(jq '.easing | keys' animation-tokens.json) +# → Store: has_animations, animation_range, easing_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 +Store analysis results in `DESIGN_ANALYSIS` (see [Key Variables](#key-variables)) -**Note**: Analysis focuses on characteristics and patterns, not counts. Results guide which principles to include and what examples to show. +**Note**: Analysis focuses on characteristics and patterns, not counts. Include technical feature detection (oklch, calc, dark mode) for Prerequisites section. -**TodoWrite Update**: -```json -[ - {"content": "Read package data", "status": "completed", "activeForm": "Reading package data"}, - {"content": "Generate SKILL.md with design references", "status": "in_progress", "activeForm": "Generating SKILL.md"} -] -``` +**TodoWrite Update**: Mark "Read package data" as completed, "Generate SKILL.md" as in_progress --- ### Phase 3: Generate SKILL.md -**Purpose**: Create SKILL memory index with progressive loading structure and design references - **Step 1: Create SKILL Directory** ```bash @@ -242,356 +267,57 @@ bash(mkdir -p .claude/skills/style-${package_name}) {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)") - -```markdown ---- -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 +**Step 3: Load and Process SKILL.md Template** +**⚠️ CRITICAL - Execute First**: ```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 +bash(cat .claude/workflows/cli-templates/memory/style-skill-memory/skill-md-template.md) ``` -### 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 - -**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_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) - -```bash -# View entire file -jq '.' .json - -# List top-level keys -jq 'keys' .json - -# Extract specific field -jq '.' .json -``` - -**Use when:** Quick reference, first-time exploration - ---- - -#### 🎯 Level 1: Filter & Extract (~12K tokens) - -```bash -# Count items -jq '. | length' .json - -# Filter by condition -jq '[.[] | select(. == "")]' .json - -# Extract names -jq -r '. | to_entries[] | select() | .key' .json - -# Formatted output -jq -r '. | to_entries[] | "\(.key): \(.value)"' .json -``` - -**Universal components filter:** `select(.component_type == "universal")` - -**Use when:** Building components, filtering data - ---- - -#### 🚀 Level 2: Combine & Transform (~20K tokens) - -```bash -# Pattern search -jq '. | keys[] | select(. | contains(""))' .json - -# Regex match -jq -r '. | to_entries[] | select(.key | test(""; "i"))' .json - -# Multi-file query -jq '.' file1.json && jq '.' file2.json - -# Nested extraction -jq '.[""].' .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 '.' .json` | -| List names | `jq -r '. \| keys[]' .json` | -| Count items | `jq '. \| length' .json` | -| Filter universal | `jq '[.[] \| select(.component_type == "universal")]' .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 - -```bash -/memory:style-skill-memory {package_name} --regenerate -``` -``` +**Template Processing**: +1. **Replace variables**: Substitute all `{variable}` placeholders with actual values from Phase 2 +2. **Generate dynamic sections**: + - **Prerequisites & Tooling**: Generate based on `DESIGN_ANALYSIS` technical features (oklch, calc, dark mode) + - **Design Principles**: Generate based on `DESIGN_ANALYSIS` characteristics + - **Complete Implementation Example**: Include React component example with token adaptation + - **Design Token Values**: Iterate `DESIGN_TOKENS_DATA`, `ANIMATION_TOKENS_DATA` and display all key-value pairs with DEFAULT annotations +3. **Write to file**: Use Write tool to save to `.claude/skills/style-{package_name}/SKILL.md` + +**Variable Replacement Map**: +- `{package_name}` → PACKAGE_NAME +- `{intelligent_description}` → Generated description from Step 2 +- `{component_count}` → COMPONENT_COUNT +- `{universal_count}` → UNIVERSAL_COUNT +- `{specialized_count}` → SPECIALIZED_COUNT +- `{universal_components_list}` → UNIVERSAL_COMPONENTS (comma-separated) +- `{has_animations}` → HAS_ANIMATIONS + +**Dynamic Content Generation**: + +See template file for complete structure. Key dynamic sections: + +1. **Prerequisites & Tooling** (based on DESIGN_ANALYSIS technical features): + - IF uses_oklch → Include PostCSS plugin requirement (`postcss-oklab-function`) + - IF uses_calc → Include preprocessor requirement for calc() expressions + - IF has_dark_mode → Include dark mode implementation mechanism (class or media query) + - ALWAYS include browser support, jq installation, and local server setup + +2. **Design Principles** (based on DESIGN_ANALYSIS): + - IF has_colors → Include "Color System" principle with semantic pattern + - IF spacing_pattern detected → Include "Spatial Rhythm" with unified scale description (actual token values) + - IF has_typography_hierarchy → Include "Typographic System" with scale examples + - IF has_radius → Include "Shape Language" with style characteristic + - IF has_shadows → Include "Depth & Elevation" with elevation pattern + - IF has_animations → Include "Motion & Timing" with duration range + - ALWAYS include "Accessibility First" principle + +3. **Design Token Values** (iterate from read data): + - Colors: Iterate `DESIGN_TOKENS_DATA.colors` + - Typography: Iterate `DESIGN_TOKENS_DATA.typography` + - Spacing: Iterate `DESIGN_TOKENS_DATA.spacing` + - Border Radius: Iterate `DESIGN_TOKENS_DATA.border_radius` with calc() explanations + - Shadows: Iterate `DESIGN_TOKENS_DATA.shadows` with DEFAULT token annotations + - Animations (if available): Iterate `ANIMATION_TOKENS_DATA.duration` and `ANIMATION_TOKENS_DATA.easing` **Step 4: Verify SKILL.md Created** @@ -599,92 +325,27 @@ cd .workflow/reference_style/{package_name} && python -m http.server 8080 bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" || echo "failed") ``` -**TodoWrite Update**: -```json -[ - {"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 +**TodoWrite Update**: Mark all todos as completed --- -## Completion Message +### Completion Message -Display concise completion summary to user: +Display a simple completion message with key information: ``` -✅ SKILL memory generated successfully! +✅ SKILL memory generated for style package: {package_name} -Package: {package_name} -SKILL Location: .claude/skills/style-{package_name}/SKILL.md +📁 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"} +📊 Package Summary: + - {component_count} components ({universal_count} universal, {specialized_count} specialized) + - Design tokens: colors, typography, spacing, shadows{animations_note} -🎨 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 +💡 Usage: /memory:load-skill-memory style-{package_name} "your task description" ``` -📋 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 | +Variables: `{package_name}`, `{component_count}`, `{universal_count}`, `{specialized_count}`, `{animations_note}` (", animations" if exists) --- @@ -694,218 +355,54 @@ See SKILL.md for detailed commands and usage examples. 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 +3. **Load Templates via cat**: Use `cat ~/.claude/workflows/cli-templates/memory/style-skill-memory/{template}` to load templates +4. **Variable Substitution**: Replace all `{variable}` placeholders with actual values +5. **Technical Feature Detection**: Analyze tokens for modern features (oklch, calc, dark mode) and generate appropriate Prerequisites section +6. **Dynamic Content Generation**: Generate sections based on DESIGN_ANALYSIS characteristics +7. **Unified Spacing Scale**: Use actual token values as primary scale reference, avoid contradictory pattern descriptions +8. **Direct Iteration**: Iterate data structures (DESIGN_TOKENS_DATA, etc.) for token values +9. **Annotate Special Tokens**: Add comments for DEFAULT tokens and calc() expressions +10. **Embed jq Commands**: Include bash/jq commands in SKILL.md for dynamic loading +11. **Progressive Loading**: Include all 3 levels (0-2) with specific jq commands +12. **Complete Examples**: Include end-to-end implementation examples (React components) +13. **Intelligent Description**: Extract component count and key features from metadata +14. **Emphasize Flexibility**: Strongly warn against rigid copying - values are references for creative adaptation -### 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 +### Template Files Location ``` -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 +.claude/workflows/cli-templates/memory/style-skill-memory/ +├── skill-md-template.md # SKILL.md structure template +├── completion-message.txt # Completion message template +└── todowrite-initial.json # Initial TodoWrite state ``` -**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 +### Data Flow + +``` +Phase 1: Validate + ├─ Parse package_name + ├─ Check PACKAGE_DIR exists + └─ Check SKILL_DIR exists (skip if exists and no --regenerate) + +Phase 2: Read & Analyze + ├─ Read design-tokens.json → DESIGN_TOKENS_DATA + ├─ Read layout-templates.json → LAYOUT_TEMPLATES_DATA + ├─ Read animation-tokens.json → ANIMATION_TOKENS_DATA (if exists) + ├─ Extract Metadata → COMPONENT_COUNT, UNIVERSAL_COUNT, etc. + └─ Analyze Design System → DESIGN_ANALYSIS (characteristics) + +Phase 3: Generate + ├─ Create SKILL directory + ├─ Generate intelligent description + ├─ Load SKILL.md template (cat command) + ├─ Replace variables and generate dynamic content + ├─ Write SKILL.md + ├─ Verify creation + ├─ Load completion message template (cat command) + └─ Display completion message +``` --- -## 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) -``` diff --git a/.claude/workflows/cli-templates/memory/style-skill-memory/skill-md-template.md b/.claude/workflows/cli-templates/memory/style-skill-memory/skill-md-template.md new file mode 100644 index 00000000..9ab905f9 --- /dev/null +++ b/.claude/workflows/cli-templates/memory/style-skill-memory/skill-md-template.md @@ -0,0 +1,357 @@ +# SKILL.md Template for Style Memory Package + +--- +name: style-{package_name} +description: {intelligent_description} +--- + +# {Package Name} Style SKILL Package + +## 🔍 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_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) + +```bash +# View entire file +jq '.' .json + +# List top-level keys +jq 'keys' .json + +# Extract specific field +jq '.' .json +``` + +**Use when:** Quick reference, first-time exploration + +--- + +#### 🎯 Level 1: Filter & Extract (~12K tokens) + +```bash +# Count items +jq '. | length' .json + +# Filter by condition +jq '[.[] | select(. == "")]' .json + +# Extract names +jq -r '. | to_entries[] | select() | .key' .json + +# Formatted output +jq -r '. | to_entries[] | "\(.key): \(.value)"' .json +``` + +**Universal components filter:** `select(.component_type == "universal")` + +**Use when:** Building components, filtering data + +--- + +#### 🚀 Level 2: Combine & Transform (~20K tokens) + +```bash +# Pattern search +jq '. | keys[] | select(. | contains(""))' .json + +# Regex match +jq -r '. | to_entries[] | select(.key | test(""; "i"))' .json + +# Multi-file query +jq '.' file1.json && jq '.' file2.json + +# Nested extraction +jq '.[""].' .json + +# Preview server +cd .workflow/reference_style/{package_name} && python -m http.server 8080 +``` + +**Use when:** Complex queries, comprehensive analysis + +--- + +### Quick Reference: Consistency vs Adaptation + +| Aspect | Prioritize Consistency | Prioritize Adaptation | +|--------|----------------------|---------------------| +| **UI Components** | Standard buttons, inputs, cards | Hero sections, landing pages | +| **Spacing** | Component internal padding | Page layout, section gaps | +| **Typography** | Body text, headings (h1-h6) | Display text, metric numbers | +| **Colors** | Brand colors, semantic states | Marketing accents, data viz | +| **Radius** | Interactive elements | Feature cards, containers | + +--- + + + +## 📖 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 + + +### 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 above for comprehensive jq command guide.** + +### Complete Implementation Example + +**Scenario**: Building a primary button component for a React application + +--- + +## ⚡ Core Rules + +1. **Reference, Not Requirements**: This is a design reference system for inspiration and guidance. **DO NOT rigidly copy values.** Analyze the patterns and principles, then adapt creatively to build the optimal design for your specific requirements. Your project's unique needs, brand identity, and user context should drive the final design decisions. + +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) + - User experience goals and interaction patterns + - Performance and technical constraints + +--- + +## ⚖️ Token Adaptation Strategy + +### Balancing Consistency and Flexibility + +**The Core Problem**: Reference tokens may not have suitable sizes or styles for your new interface needs. Blindly copying leads to poor, rigid design. But ignoring tokens breaks visual consistency. + +**The Solution**: Use tokens as a **pattern foundation**, not a value prison. + +--- + +### Decision Framework + +**When to Use Existing Tokens (Maintain Consistency)**: +- ✅ Common UI elements (buttons, cards, inputs, typography hierarchy) +- ✅ Repeated patterns across multiple pages +- ✅ Standard interactions (hover, focus, active states) +- ✅ When existing token serves the purpose adequately + +**When to Extend Tokens (Adapt for New Needs)**: +- ✅ New component type not in reference system +- ✅ Existing token creates visually awkward result +- ✅ Special context requires unique treatment (hero sections, landing pages, data visualization) +- ✅ Target device/platform has different constraints (mobile vs desktop) + +**Critical Rule**: **Extend by pattern, not by random values.** + + +### Integration Guidelines + +**1. Document Your Extensions** +When you create new token values: +- Note the pattern/method used (interpolation, extrapolation, etc.) +- Document the specific use case +- Consider if it should be added to the design system + +**2. Maintain Visual Consistency** +- Use extended values sparingly (don't create 50 spacing tokens) +- Prefer using existing tokens when "close enough" (90% fit is often acceptable) +- Group extended tokens by context (e.g., "hero-section-padding", "dashboard-metric-size") + +**3. Respect Core Patterns** +- **Color**: Preserve hue and semantic meaning, adjust lightness/saturation +- **Spacing**: Follow progression pattern (linear/geometric) +- **Typography**: Maintain scale ratio and line-height relationships +- **Radius**: Continue shape language (sharp vs rounded personality) + +**4. Know When to Break Rules** +Sometimes you need unique values for special contexts: +- Landing page hero sections +- Marketing/promotional components +- Data visualization (charts, graphs) +- Platform-specific requirements + +**For these cases**: Create standalone tokens with clear naming (`hero-title-size`, `chart-accent-color`) rather than forcing into standard scale. + +--- + + + +## 🎨 Style Understanding & Design References + +**IMPORTANT**: These are reference values and patterns extracted from codebase for inspiration. **DO NOT copy rigidly.** Use them as a starting point to understand design patterns, then creatively adapt to build the optimal solution for your specific project requirements, user needs, and brand identity. + +### Design Principles + +**Dynamically generated based on design token characteristics:** + +{GENERATE_PRINCIPLES_FROM_DESIGN_ANALYSIS} + +{IF DESIGN_ANALYSIS.has_colors: +**Color System** +- Semantic naming: {DESIGN_ANALYSIS.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 DESIGN_ANALYSIS.spacing_pattern detected: +**Spatial Rhythm** +- Primary scale pattern: {DESIGN_ANALYSIS.spacing_scale} (derived from analysis, represents actual token values) +- Pattern characteristics: {DESIGN_ANALYSIS.spacing_pattern} (e.g., "primarily geometric with practical refinements") +- {DESIGN_ANALYSIS.spacing_pattern == "geometric" ? "Geometric progression provides clear hierarchy with exponential growth" : "Linear progression offers subtle gradations for fine control"} +- Apply systematically: smaller values (4-12px) for compact elements, medium (16-32px) for standard spacing, larger (48px+) for section breathing room +- Note: Practical scales may deviate slightly from pure mathematical patterns to optimize for real-world UI needs +} + +{IF DESIGN_ANALYSIS.has_typography with typography_hierarchy: +**Typographic System** +- Type scale establishes content hierarchy and readability +- Size progression: {DESIGN_ANALYSIS.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 DESIGN_ANALYSIS.has_radius: +**Shape Language** +- Radius style: {DESIGN_ANALYSIS.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 DESIGN_ANALYSIS.has_shadows: +**Depth & Elevation** +- Shadow pattern: {DESIGN_ANALYSIS.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 DESIGN_ANALYSIS.has_animations: +**Motion & Timing** +- Duration range: {DESIGN_ANALYSIS.animation_range} (e.g., "100ms (fast feedback) to 300ms (content transitions)") +- Easing variety: {DESIGN_ANALYSIS.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 + +{ITERATE DESIGN_TOKENS_DATA.colors: + - **{color.key}**: `{color.value}` +} + +#### Typography + +{ITERATE DESIGN_TOKENS_DATA.typography: + - **{font.key}**: `{font.value}` +} + +#### Spacing Scale + +{ITERATE DESIGN_TOKENS_DATA.spacing: + - **{spacing.key}**: `{spacing.value}` +} + +#### Border Radius + +{ITERATE DESIGN_TOKENS_DATA.border_radius: + - **{radius.key}**: `{radius.value}` +} + +#### Shadows + +{ITERATE DESIGN_TOKENS_DATA.shadows: + - **{shadow.key}**: `{shadow.value}` {shadow.key == "DEFAULT" ? "# Default shadow, matches specific variant for framework compatibility" : ""} +} + +{IF HAS_ANIMATIONS: +#### Animation & Timing + +**Durations**: +{ITERATE ANIMATION_TOKENS_DATA.duration: + - {duration.key}: `{duration.value}` +} + +**Easing Functions**: +{ITERATE ANIMATION_TOKENS_DATA.easing: + - {easing.key}: `{easing.value}` +} +} + +--- + +## 📦 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)"} + + + +