refactor(ui-design): enhance usage recommendations and extraction processes in design workflows

This commit is contained in:
catlog22
2025-11-11 21:52:47 +08:00
parent 8786b8c34d
commit d602ca052b
5 changed files with 466 additions and 46 deletions

View File

@@ -1,5 +1,5 @@
---
name: memory:style-skill-memory
name: style-skill-memory
description: Generate SKILL memory package from style reference for easy loading and consistent design system usage
argument-hint: "[package-name] [--regenerate]"
allowed-tools: Bash,Read,Write,TodoWrite
@@ -18,6 +18,12 @@ auto-continue: true
**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
@@ -57,7 +63,7 @@ package-name Style reference package name (required)
```json
[
{"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"},
{"content": "Read package data and count components", "status": "pending", "activeForm": "Reading package data"},
{"content": "Read package data and extract design references", "status": "pending", "activeForm": "Reading package data"},
{"content": "Generate SKILL.md with progressive loading", "status": "pending", "activeForm": "Generating SKILL.md"}
]
```
@@ -117,17 +123,15 @@ if (regenerate_flag && skill_exists) {
```json
[
{"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
{"content": "Read package data and count components", "status": "in_progress", "activeForm": "Reading package data"}
{"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"}
]
```
**Next Action**: Continue to Phase 2
---
### Phase 2: Read Package Data
### Phase 2: Read Package Data & Extract Design References
**Purpose**: Extract package information for SKILL description generation
**Purpose**: Extract package information and primary design references for SKILL description generation
**Step 1: Count Components**
@@ -137,17 +141,76 @@ bash(jq '.layout_templates | length' .workflow/reference_style/${package_name}/l
Store result as `component_count`
**Step 2: Read Design Tokens Summary**
**Step 2: Extract Component Types**
```bash
# Extract component names from layout templates
bash(jq -r '.layout_templates | keys[]' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
```
Store as `COMPONENT_TYPES`: List of available component types
**Step 3: Read Design Tokens**
```bash
Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json")
```
**Extract Information**:
- Available token categories (colors, typography, spacing, etc.)
- Token count per category
**Extract Primary Design References**:
**Step 3: Check Available Files**
**Colors** (top 3-5 most important):
```bash
bash(jq -r '.colors | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null | head -5)
```
**Typography** (heading and body fonts):
```bash
bash(jq -r '.typography | to_entries | select(.key | contains("family")) | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
```
**Spacing Scale** (base spacing values):
```bash
bash(jq -r '.spacing | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
```
**Border Radius** (base radius values):
```bash
bash(jq -r '.border_radius | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
```
**Shadows** (elevation levels):
```bash
bash(jq -r '.shadows | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
```
Store extracted references as:
- `PRIMARY_COLORS`: List of primary color tokens
- `TYPOGRAPHY_FONTS`: Font family tokens
- `SPACING_SCALE`: Base spacing values
- `BORDER_RADIUS`: Radius values
- `SHADOWS`: Shadow definitions
**Step 4: Read Animation Tokens (if available)**
```bash
# Check if animation tokens exist
bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
```
If available, extract:
```bash
Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")
# Extract primary animation values
bash(jq -r '.duration | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
bash(jq -r '.easing | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
```
Store as:
- `ANIMATION_DURATIONS`: Animation duration tokens
- `EASING_FUNCTIONS`: Easing function tokens
**Step 5: Count Files**
```bash
bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2>/dev/null | wc -l)
@@ -155,34 +218,32 @@ bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2
Store result as `file_count`
**Step 4: Check Optional Animation Tokens**
```bash
bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
```
Store result as `has_animations`
**Summary Data**:
**Summary Data Collected**:
- `COMPONENT_COUNT`: Number of components in layout templates
- `COMPONENT_TYPES`: List of component types (first 10)
- `FILE_COUNT`: Total files in package
- `HAS_ANIMATIONS`: Whether animation tokens are available
- `PRIMARY_COLORS`: Primary color tokens with values
- `TYPOGRAPHY_FONTS`: Font family tokens
- `SPACING_SCALE`: Base spacing scale
- `BORDER_RADIUS`: Border radius values
- `SHADOWS`: Shadow definitions
- `ANIMATION_DURATIONS`: Animation durations (if available)
- `EASING_FUNCTIONS`: Easing functions (if available)
**TodoWrite Update**:
```json
[
{"content": "Read package data and count components", "status": "completed", "activeForm": "Reading package data"},
{"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
{"content": "Generate SKILL.md with progressive loading", "status": "in_progress", "activeForm": "Generating SKILL.md"}
]
```
**Next Action**: Continue to Phase 3
---
### Phase 3: Generate SKILL.md
**Purpose**: Create SKILL memory index with progressive loading structure
**Purpose**: Create SKILL memory index with progressive loading structure and design references
**Step 1: Create SKILL Directory**
@@ -208,7 +269,9 @@ bash(mkdir -p .claude/skills/style-${package_name})
main-app-style-v1 design system with 8 layout templates and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with UI components, design tokens, layout patterns, analyzing component structures, or implementing visual consistency.
```
**Step 3: Write SKILL.md** (Use Write tool)
**Step 3: Write SKILL.md**
Use Write tool to generate SKILL.md with the following complete content:
```markdown
---
@@ -227,9 +290,143 @@ Style reference package extracted from codebase with layout templates, design to
**Package Details**:
- Package: {package_name}
- Layout Templates: {component_count}
- Component Types: {comma-separated list of COMPONENT_TYPES}
- Files: {file_count}
- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
---
## ⚡ Primary Design References
**IMPORTANT**: These are **reference values** extracted from the codebase. They should be **dynamically adjusted** based on your specific design needs, not treated as fixed constraints.
### 🎨 Colors
{FOR each color in PRIMARY_COLORS:
- **{color.key}**: `{color.value}`
}
**Usage Guidelines**:
- These colors establish the foundation of the design system
- Adjust saturation, lightness, or hue based on:
- Brand requirements and accessibility needs
- Context (light/dark mode, high-contrast themes)
- User feedback and A/B testing results
- Use color theory principles to maintain harmony when modifying
### 📝 Typography
{FOR each font in TYPOGRAPHY_FONTS:
- **{font.key}**: `{font.value}`
}
**Usage Guidelines**:
- Font families can be substituted based on:
- Brand identity and design language
- Performance requirements (web fonts vs. system fonts)
- Accessibility and readability considerations
- Platform-specific availability
- Maintain hierarchy and scale relationships when changing fonts
### 📏 Spacing Scale
{FOR each spacing in SPACING_SCALE:
- **{spacing.key}**: `{spacing.value}`
}
**Usage Guidelines**:
- Spacing values form a consistent rhythm system
- Adjust scale based on:
- Target device (mobile vs. desktop vs. tablet)
- Content density requirements
- Component-specific needs (compact vs. comfortable layouts)
- Maintain proportional relationships when scaling
### 🔲 Border Radius
{FOR each radius in BORDER_RADIUS:
- **{radius.key}**: `{radius.value}`
}
**Usage Guidelines**:
- Border radius affects visual softness and modernity
- Adjust based on:
- Design aesthetic (sharp vs. rounded vs. pill-shaped)
- Component type (buttons, cards, inputs have different needs)
- Platform conventions (iOS vs. Android vs. Web)
### 🌫️ Shadows
{FOR each shadow in SHADOWS:
- **{shadow.key}**: `{shadow.value}`
}
**Usage Guidelines**:
- Shadows create elevation and depth perception
- Adjust based on:
- Material design depth levels
- Light/dark mode contexts
- Performance considerations (complex shadows impact rendering)
- Visual hierarchy needs
{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}`
}
**Usage Guidelines**:
- Animation timing affects perceived responsiveness and polish
- Adjust based on:
- User expectations and platform conventions
- Accessibility preferences (reduced motion)
- Animation type (micro-interactions vs. page transitions)
- Performance constraints (mobile vs. desktop)
}
---
## 🎯 Design Adaptation Strategies
### When to Adjust Design References
**Brand Alignment**:
- Modify colors to match brand identity and guidelines
- Adjust typography to reflect brand personality
- Tune spacing and radius to align with brand aesthetic
**Accessibility Requirements**:
- Increase color contrast ratios for WCAG compliance
- Adjust font sizes and spacing for readability
- Modify animation durations for reduced-motion preferences
**Platform Optimization**:
- Adapt spacing for mobile touch targets (min 44x44px)
- Adjust shadows and radius for platform conventions
- Optimize animation performance for target devices
**Context-Specific Needs**:
- Dark mode: Adjust colors, shadows, and contrasts
- High-density displays: Fine-tune spacing and sizing
- Responsive design: Scale tokens across breakpoints
### How to Apply Adjustments
1. **Identify Need**: Determine which tokens need adjustment based on your specific requirements
2. **Maintain Relationships**: Preserve proportional relationships between related tokens
3. **Test Thoroughly**: Validate changes across components and use cases
4. **Document Changes**: Track modifications and rationale for team alignment
5. **Iterate**: Refine based on user feedback and testing results
---
## Progressive Loading
### Level 0: Design Tokens (~5K tokens)
@@ -377,7 +574,7 @@ bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" ||
```json
[
{"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
{"content": "Read package data and count components", "status": "completed", "activeForm": "Reading package data"},
{"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
{"content": "Generate SKILL.md with progressive loading", "status": "completed", "activeForm": "Generating SKILL.md"}
]
```
@@ -388,37 +585,81 @@ bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" ||
## Completion Message
Display extracted primary design references to user:
```
✅ SKILL memory generated successfully!
Package: {package_name}
SKILL Location: .claude/skills/style-{package_name}/SKILL.md
Package Details:
📦 Package Details:
- Layout Templates: {component_count}
- Component Types: {show first 5 COMPONENT_TYPES, then "+ X more"}
- Files: {file_count}
- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
Progressive Loading Levels:
🎨 Primary Design References Extracted:
{IF PRIMARY_COLORS exists:
Colors:
{show first 3 PRIMARY_COLORS with key: value}
{if more than 3: + X more colors}
}
{IF TYPOGRAPHY_FONTS exists:
Typography:
{show all TYPOGRAPHY_FONTS}
}
{IF SPACING_SCALE exists:
Spacing Scale:
{show first 3 SPACING_SCALE items}
{if more than 3: + X more spacing tokens}
}
{IF BORDER_RADIUS exists:
Border Radius:
{show all BORDER_RADIUS}
}
{IF HAS_ANIMATIONS:
Animation:
Durations: {count ANIMATION_DURATIONS} tokens
Easing: {count EASING_FUNCTIONS} functions
}
⚡ Progressive Loading Levels:
- Level 0: Design Tokens (~5K tokens)
- Level 1: Tokens + Layout Templates (~12K tokens)
- Level 2: Complete System (~20K tokens)
Usage:
💡 Usage:
Load design system context when working with:
- UI component implementation
- Layout pattern analysis
- Design token application
- Style consistency validation
Preview:
⚠️ IMPORTANT:
The extracted design references are REFERENCE VALUES, not fixed constraints.
Dynamically adjust colors, spacing, typography, and other tokens based on:
- Brand requirements and accessibility needs
- Platform-specific conventions and optimizations
- Context (light/dark mode, responsive breakpoints)
- User feedback and testing results
See SKILL.md for detailed adjustment guidelines and best practices.
🎯 Preview:
Open interactive showcase:
file://{absolute_path}/.workflow/reference_style/{package_name}/preview.html
Next Steps:
1. Load appropriate level based on your task
2. Reference layout-templates.json for component structures
3. Use design-tokens.json for consistent styling
📋 Next Steps:
1. Load appropriate level based on your task context
2. Review Primary Design References section for key design tokens
3. Apply design tokens with dynamic adjustments as needed
4. Reference layout-templates.json for component structures
5. Use Design Adaptation Strategies when modifying tokens
```
---
@@ -442,8 +683,10 @@ Next Steps:
1. **Check Before Generate**: Verify package exists before attempting SKILL generation
2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
3. **Progressive Loading**: Always include all 4 levels (0-3) with clear token estimates
4. **Intelligent Description**: Extract component count and key features from metadata
3. **Extract Primary References**: Always extract and display key design values (colors, typography, spacing, border radius, shadows, animations)
4. **Include Adjustment Guidance**: Provide clear guidelines on when and how to dynamically adjust design tokens
5. **Progressive Loading**: Always include all 3 levels (0-2) with clear token estimates
6. **Intelligent Description**: Extract component count and key features from metadata
### SKILL Description Format
@@ -459,6 +702,30 @@ Next Steps:
- Trigger keywords (UI components, design tokens, layout patterns, component structures)
- Action verbs (working with, analyzing, implementing)
### Primary Design References Extraction
**Required Data Extraction** (from design-tokens.json):
- Colors: Primary, secondary, accent colors (top 3-5)
- Typography: Font families for headings and body text
- Spacing Scale: Base spacing values (xs, sm, md, lg, xl)
- Border Radius: All radius tokens
- Shadows: Shadow definitions (top 3 elevation levels)
**Optional Data Extraction** (from animation-tokens.json if available):
- Animation Durations: All duration tokens
- Easing Functions: Top 3 easing functions
**Extraction Format**:
Use `jq` to extract tokens from JSON files. Each token should include key and value.
### Dynamic Adjustment Guidelines
**Include in SKILL.md**:
1. **Usage Guidelines per Category**: Specific guidance for each token category
2. **Adjustment Strategies**: When to adjust design references
3. **Practical Examples**: Context-specific adaptation scenarios
4. **Best Practices**: How to maintain design system coherence while adjusting
### Progressive Loading Structure
**Level 0** (~5K tokens):
@@ -479,20 +746,67 @@ Next Steps:
## Benefits
- **Fast Context Loading**: Progressive levels for efficient token usage
- **Primary Design References**: Extracted key design values (colors, typography, spacing, etc.) displayed prominently
- **Dynamic Adjustment Guidance**: Clear instructions on when and how to adjust design tokens
- **Intelligent Triggering**: Keywords optimize SKILL activation
- **Complete Reference**: All package files accessible through SKILL
- **Easy Regeneration**: Simple --regenerate flag for updates
- **Clear Structure**: Organized levels by use case
- **Practical Usage Guidelines**: Context-specific adjustment strategies for different scenarios
---
## Architecture
```
style-skill-memory
├─ Phase 1: Validate (check package exists, check SKILL exists)
├─ Phase 2: Read Package Data (count components from layout-templates.json, check animations)
└─ Phase 3: Generate SKILL.md (write SKILL with progressive loading)
├─ 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 & Extract Primary References
│ ├─ Count components from layout-templates.json
│ ├─ Extract component types list
│ ├─ Extract primary colors from design-tokens.json (top 3-5)
│ ├─ Extract typography (font families)
│ ├─ Extract spacing scale (base values)
│ ├─ Extract border radius tokens
│ ├─ Extract shadow definitions (top 3)
│ ├─ Extract animation tokens (if available)
│ └─ Count total files in package
└─ Phase 3: Generate SKILL.md
├─ Create SKILL directory
├─ Generate intelligent description with keywords
├─ Write SKILL.md with complete structure:
│ ├─ Package Overview
│ ├─ Primary Design References
│ │ ├─ Colors with usage guidelines
│ │ ├─ Typography with usage guidelines
│ │ ├─ Spacing with usage guidelines
│ │ ├─ Border Radius with usage guidelines
│ │ ├─ Shadows with usage guidelines
│ │ └─ Animation & Timing (if available)
│ ├─ Design Adaptation Strategies
│ │ ├─ When to adjust design references
│ │ └─ How to apply adjustments
│ ├─ Progressive Loading (3 levels)
│ ├─ Interactive Preview
│ ├─ Usage Guidelines
│ ├─ Package Structure
│ ├─ Regeneration
│ └─ Related Commands
├─ Verify SKILL.md created successfully
└─ Display completion message with extracted design references
No external commands called
Direct file reading and writing
Smart description generation from package data
Data Flow:
design-tokens.json → jq extraction → PRIMARY_COLORS, TYPOGRAPHY_FONTS,
SPACING_SCALE, BORDER_RADIUS, SHADOWS
animation-tokens.json → jq extraction → ANIMATION_DURATIONS, EASING_FUNCTIONS
layout-templates.json → jq extraction → COMPONENT_TYPES, COMPONENT_COUNT
Extracted data → SKILL.md generation → Primary Design References section
→ Dynamic Adjustment Guidelines
→ Completion message display
```