mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
refactor: consolidate workflow commands and add UI design templates
1. Remove deprecated task-generate.md - Replaced by task-generate-agent.md in previous commits - Clean up duplicate command documentation 2. Update ui-design-agent.md - Refine agent specifications and workflow integration 3. Add UI design template files - Create ~/.claude/workflows/cli-templates/ui-design/systems/ - Add animation-tokens.json for animation and transition patterns - Add design-tokens.json for color, typography, spacing tokens - Add layout-templates.json for structural layout patterns - Modular design system management 4. Update analyze_commands.py - Enhance command analysis capabilities - Improve metadata extraction Key improvements: - Remove duplicate/deprecated documentation - Modular UI design template management - Better workflow command organization
This commit is contained in:
catlog22
@@ -318,270 +318,21 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
|
||||
|
||||
### design-tokens.json
|
||||
|
||||
**Template Reference**: `~/.claude/workflows/cli-templates/ui-design/systems/design-tokens.json`
|
||||
|
||||
**Format**: W3C Design Tokens Community Group Specification
|
||||
|
||||
**Schema Structure**:
|
||||
```json
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
"name": "string - Token set name",
|
||||
"description": "string - Token set description",
|
||||
|
||||
"color": {
|
||||
"background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" }, "$description": "optional" },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"card": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"card-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"border": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"input": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"ring": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
|
||||
"interactive": {
|
||||
"primary": {
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"disabled": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
"secondary": { "/* Same structure as primary */" },
|
||||
"accent": { "/* Same structure (no disabled state) */" },
|
||||
"destructive": { "/* Same structure (no active/disabled states) */" }
|
||||
},
|
||||
|
||||
"muted": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"muted-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
|
||||
"chart": {
|
||||
"1": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"2": { "/* ... */" },
|
||||
"3": { "/* ... */" },
|
||||
"4": { "/* ... */" },
|
||||
"5": { "/* ... */" }
|
||||
},
|
||||
|
||||
"sidebar": {
|
||||
"background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "/* ... */" },
|
||||
"primary": { "/* ... */" },
|
||||
"primary-foreground": { "/* ... */" },
|
||||
"accent": { "/* ... */" },
|
||||
"accent-foreground": { "/* ... */" },
|
||||
"border": { "/* ... */" },
|
||||
"ring": { "/* ... */" }
|
||||
}
|
||||
},
|
||||
|
||||
"typography": {
|
||||
"font_families": {
|
||||
"sans": "string - 'Font Name', fallback1, fallback2",
|
||||
"serif": "string",
|
||||
"mono": "string"
|
||||
},
|
||||
"font_sizes": {
|
||||
"xs": "0.75rem",
|
||||
"sm": "0.875rem",
|
||||
"base": "1rem",
|
||||
"lg": "1.125rem",
|
||||
"xl": "1.25rem",
|
||||
"2xl": "1.5rem",
|
||||
"3xl": "1.875rem",
|
||||
"4xl": "2.25rem"
|
||||
},
|
||||
"line_heights": {
|
||||
"tight": "number",
|
||||
"normal": "number",
|
||||
"relaxed": "number"
|
||||
},
|
||||
"letter_spacing": {
|
||||
"tight": "string",
|
||||
"normal": "string",
|
||||
"wide": "string"
|
||||
},
|
||||
"combinations": [
|
||||
{
|
||||
"name": "h1|h2|h3|h4|h5|h6|body|caption",
|
||||
"font_family": "sans|serif|mono",
|
||||
"font_size": "string - reference to font_sizes",
|
||||
"font_weight": "number - 400|500|600|700",
|
||||
"line_height": "string",
|
||||
"letter_spacing": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"spacing": {
|
||||
"0": "0",
|
||||
"1": "0.25rem",
|
||||
"2": "0.5rem",
|
||||
"/* Systematic scale: 3, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64 */"
|
||||
},
|
||||
|
||||
"opacity": {
|
||||
"disabled": "0.5",
|
||||
"hover": "0.8",
|
||||
"active": "1"
|
||||
},
|
||||
|
||||
"shadows": {
|
||||
"2xs": "string - CSS shadow value",
|
||||
"xs": "string",
|
||||
"sm": "string",
|
||||
"DEFAULT": "string",
|
||||
"md": "string",
|
||||
"lg": "string",
|
||||
"xl": "string",
|
||||
"2xl": "string"
|
||||
},
|
||||
|
||||
"border_radius": {
|
||||
"sm": "string - calc() or fixed",
|
||||
"md": "string",
|
||||
"lg": "string",
|
||||
"xl": "string",
|
||||
"DEFAULT": "string"
|
||||
},
|
||||
|
||||
"breakpoints": {
|
||||
"sm": "640px",
|
||||
"md": "768px",
|
||||
"lg": "1024px",
|
||||
"xl": "1280px",
|
||||
"2xl": "1536px"
|
||||
},
|
||||
|
||||
"component": {
|
||||
"/* COMPONENT PATTERN - Apply to: button, card, input, dialog, dropdown, toast, accordion, tabs, switch, checkbox, badge, alert */": {
|
||||
"$type": "component",
|
||||
"base": {
|
||||
"/* Layout properties using camelCase */": "value or {token.path}",
|
||||
"display": "inline-flex|flex|block",
|
||||
"alignItems": "center",
|
||||
"borderRadius": "{border_radius.md}",
|
||||
"transition": "{transitions.default}"
|
||||
},
|
||||
"size": {
|
||||
"small": { "height": "32px", "padding": "{spacing.2} {spacing.3}", "fontSize": "{typography.font_sizes.xs}" },
|
||||
"default": { "height": "40px", "padding": "{spacing.2} {spacing.4}" },
|
||||
"large": { "height": "48px", "padding": "{spacing.3} {spacing.6}", "fontSize": "{typography.font_sizes.base}" }
|
||||
},
|
||||
"variant": {
|
||||
"variantName": {
|
||||
"default": { "backgroundColor": "{color.interactive.primary.default}", "color": "{color.interactive.primary.foreground}" },
|
||||
"hover": { "backgroundColor": "{color.interactive.primary.hover}" },
|
||||
"active": { "backgroundColor": "{color.interactive.primary.active}" },
|
||||
"disabled": { "backgroundColor": "{color.interactive.primary.disabled}", "opacity": "{opacity.disabled}", "cursor": "not-allowed" },
|
||||
"focus": { "outline": "2px solid {color.ring}", "outlineOffset": "2px" }
|
||||
}
|
||||
},
|
||||
"state": {
|
||||
"/* For stateful components (dialog, accordion, etc.) */": {
|
||||
"open": { "animation": "{animation.name.component-open} {animation.duration.normal} {animation.easing.ease-out}" },
|
||||
"closed": { "animation": "{animation.name.component-close} {animation.duration.normal} {animation.easing.ease-in}" }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"elevation": {
|
||||
"$type": "elevation",
|
||||
"base": { "$value": "0" },
|
||||
"overlay": { "$value": "40" },
|
||||
"dropdown": { "$value": "50" },
|
||||
"dialog": { "$value": "50" },
|
||||
"tooltip": { "$value": "60" }
|
||||
},
|
||||
|
||||
"_metadata": {
|
||||
"version": "string - W3C version or custom version",
|
||||
"created": "ISO timestamp - 2024-01-01T00:00:00Z",
|
||||
"source": "code-import|explore|text",
|
||||
"theme_colors_guide": {
|
||||
"description": "Theme colors are the core brand identity colors that define the visual hierarchy and emotional tone of the design system",
|
||||
"primary": {
|
||||
"role": "Main brand color",
|
||||
"usage": "Primary actions (CTAs, key interactive elements, navigation highlights, primary buttons)",
|
||||
"contrast_requirement": "WCAG AA - 4.5:1 for text, 3:1 for UI components"
|
||||
},
|
||||
"secondary": {
|
||||
"role": "Supporting brand color",
|
||||
"usage": "Secondary actions and complementary elements (less prominent buttons, secondary navigation, supporting features)",
|
||||
"principle": "Should complement primary without competing for attention"
|
||||
},
|
||||
"accent": {
|
||||
"role": "Highlight color for emphasis",
|
||||
"usage": "Attention-grabbing elements used sparingly (badges, notifications, special promotions, highlights)",
|
||||
"principle": "Should create strong visual contrast to draw focus"
|
||||
},
|
||||
"destructive": {
|
||||
"role": "Error and destructive action color",
|
||||
"usage": "Delete buttons, error messages, critical warnings",
|
||||
"principle": "Must signal danger or caution clearly"
|
||||
},
|
||||
"harmony_note": "All theme colors must work harmoniously together and align with brand identity. In multi-file extraction, prioritize definitions with semantic comments explaining brand intent."
|
||||
},
|
||||
"conflicts": [
|
||||
{
|
||||
"token_name": "string - which token has conflicts",
|
||||
"category": "string - colors|typography|etc",
|
||||
"definitions": [
|
||||
{
|
||||
"value": "string - token value",
|
||||
"source_file": "string - absolute path",
|
||||
"line_number": "number",
|
||||
"context": "string - surrounding comment or null",
|
||||
"semantic_intent": "string - interpretation of definition"
|
||||
}
|
||||
],
|
||||
"selected_value": "string - final chosen value",
|
||||
"selection_reason": "string - why this value was chosen"
|
||||
}
|
||||
],
|
||||
"code_snippets": [
|
||||
{
|
||||
"category": "colors|typography|spacing|shadows|border_radius|component",
|
||||
"token_name": "string - which token this snippet defines",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete code block",
|
||||
"context_type": "css-variable|css-class|js-object|scss-variable|etc"
|
||||
}
|
||||
],
|
||||
"usage_recommendations": {
|
||||
"typography": {
|
||||
"common_sizes": {
|
||||
"small_text": "sm (0.875rem)",
|
||||
"body_text": "base (1rem)",
|
||||
"heading": "2xl-4xl"
|
||||
},
|
||||
"common_combinations": [
|
||||
{
|
||||
"name": "Heading + Body",
|
||||
"heading": "2xl",
|
||||
"body": "base",
|
||||
"use_case": "Article sections"
|
||||
}
|
||||
]
|
||||
},
|
||||
"spacing": {
|
||||
"size_guide": {
|
||||
"tight": "1-2 (0.25rem-0.5rem)",
|
||||
"normal": "4-6 (1rem-1.5rem)",
|
||||
"loose": "8-12 (2rem-3rem)"
|
||||
},
|
||||
"common_patterns": [
|
||||
{
|
||||
"pattern": "padding-4 margin-bottom-6",
|
||||
"use_case": "Card content spacing",
|
||||
"pixel_value": "1rem padding, 1.5rem margin"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
**Structure Overview**:
|
||||
- **color**: Base colors, interactive states (primary, secondary, accent, destructive), muted, chart, sidebar
|
||||
- **typography**: Font families, sizes, line heights, letter spacing, combinations
|
||||
- **spacing**: Systematic scale (0-64, multiples of 0.25rem)
|
||||
- **opacity**: disabled, hover, active
|
||||
- **shadows**: 2xs to 2xl (8-tier system)
|
||||
- **border_radius**: sm to xl + DEFAULT
|
||||
- **breakpoints**: sm to 2xl
|
||||
- **component**: 12+ components with base, size, variant, state structures
|
||||
- **elevation**: z-index values for layered components
|
||||
- **_metadata**: version, created, source, theme_colors_guide, conflicts, code_snippets, usage_recommendations
|
||||
|
||||
**Required Components** (12+ components, use pattern above):
|
||||
- **button**: 5 variants (primary, secondary, destructive, outline, ghost) + 3 sizes + states (default, hover, active, disabled, focus)
|
||||
@@ -632,136 +383,26 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
|
||||
|
||||
### layout-templates.json
|
||||
|
||||
**Template Reference**: `~/.claude/workflows/cli-templates/ui-design/systems/layout-templates.json`
|
||||
|
||||
**Optimization**: Unified structure combining DOM and styling into single hierarchy
|
||||
|
||||
**Schema Structure**:
|
||||
```json
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
"templates": [
|
||||
{
|
||||
"target": "string - page/component name (e.g., hero-section, product-card)",
|
||||
"description": "string - layout description",
|
||||
"component_type": "universal|specialized",
|
||||
"device_type": "mobile|tablet|desktop|responsive",
|
||||
"layout_strategy": "string - grid-3col|flex-row|stack|sidebar|etc",
|
||||
|
||||
"structure": {
|
||||
"tag": "string - HTML5 semantic tag (header|nav|main|section|article|aside|footer|div|etc)",
|
||||
"attributes": {
|
||||
"class": "string - semantic class name",
|
||||
"role": "string - ARIA role (navigation|main|complementary|etc)",
|
||||
"aria-label": "string - ARIA label",
|
||||
"aria-describedby": "string - ARIA describedby",
|
||||
"data-state": "string - data attributes for state management (open|closed|etc)"
|
||||
},
|
||||
"layout": {
|
||||
"/* LAYOUT PROPERTIES ONLY - Use camelCase for property names */": "",
|
||||
"display": "grid|flex|block|inline-flex",
|
||||
"grid-template-columns": "{spacing.*} or CSS value (repeat(3, 1fr))",
|
||||
"grid-template-rows": "string",
|
||||
"gap": "{spacing.*}",
|
||||
"padding": "{spacing.*}",
|
||||
"margin": "{spacing.*}",
|
||||
"alignItems": "start|center|end|stretch",
|
||||
"justifyContent": "start|center|end|space-between|space-around",
|
||||
"flexDirection": "row|column",
|
||||
"flexWrap": "wrap|nowrap",
|
||||
"position": "relative|absolute|fixed|sticky",
|
||||
"top|right|bottom|left": "string",
|
||||
"width": "string",
|
||||
"height": "string",
|
||||
"maxWidth": "string",
|
||||
"minHeight": "string"
|
||||
},
|
||||
"responsive": {
|
||||
"/* ONLY properties that CHANGE at each breakpoint - NO repetition */": "",
|
||||
"sm": {
|
||||
"grid-template-columns": "1fr",
|
||||
"padding": "{spacing.4}"
|
||||
},
|
||||
"md": {
|
||||
"grid-template-columns": "repeat(2, 1fr)",
|
||||
"gap": "{spacing.6}"
|
||||
},
|
||||
"lg": {
|
||||
"grid-template-columns": "repeat(3, 1fr)"
|
||||
}
|
||||
},
|
||||
"children": [
|
||||
{
|
||||
"/* Recursive structure - same fields as parent */": "",
|
||||
"tag": "string",
|
||||
"attributes": {},
|
||||
"layout": {},
|
||||
"responsive": {},
|
||||
"children": [],
|
||||
"content": "string or {{placeholder}}"
|
||||
}
|
||||
],
|
||||
"content": "string - text content or {{placeholder}} for dynamic content"
|
||||
},
|
||||
|
||||
"accessibility": {
|
||||
"patterns": [
|
||||
"string - ARIA patterns used (e.g., WAI-ARIA Tabs pattern, Dialog pattern)"
|
||||
],
|
||||
"keyboard_navigation": [
|
||||
"string - keyboard shortcuts (e.g., Tab/Shift+Tab navigation, Escape to close)"
|
||||
],
|
||||
"focus_management": "string - focus trap strategy, initial focus target",
|
||||
"screen_reader_notes": [
|
||||
"string - screen reader announcements (e.g., Dialog opened, Tab selected)"
|
||||
]
|
||||
},
|
||||
|
||||
"usage_guide": {
|
||||
"common_sizes": {
|
||||
"small": {
|
||||
"dimensions": "string - e.g., px-3 py-1.5 (height: ~32px)",
|
||||
"use_case": "string - Compact UI, mobile views"
|
||||
},
|
||||
"medium": {
|
||||
"dimensions": "string - e.g., px-4 py-2 (height: ~40px)",
|
||||
"use_case": "string - Default size for most contexts"
|
||||
},
|
||||
"large": {
|
||||
"dimensions": "string - e.g., px-6 py-3 (height: ~48px)",
|
||||
"use_case": "string - Prominent CTAs, hero sections"
|
||||
}
|
||||
},
|
||||
"variant_recommendations": {
|
||||
"variant_name": {
|
||||
"description": "string - when to use this variant",
|
||||
"typical_actions": ["string - action examples"]
|
||||
}
|
||||
},
|
||||
"usage_context": [
|
||||
"string - typical usage scenarios (e.g., Landing page hero, Product listing grid)"
|
||||
],
|
||||
"accessibility_tips": [
|
||||
"string - accessibility best practices (e.g., Ensure heading hierarchy, Add aria-label)"
|
||||
]
|
||||
},
|
||||
|
||||
"extraction_metadata": {
|
||||
"source": "code-import|explore|text",
|
||||
"created": "ISO timestamp",
|
||||
"code_snippets": [
|
||||
{
|
||||
"component_name": "string - which layout component",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete HTML/CSS/JS code block",
|
||||
"context_type": "html-structure|css-utility|react-component|vue-component|etc"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
**Structure Overview**:
|
||||
- **templates[]**: Array of layout templates
|
||||
- **target**: page/component name (hero-section, product-card)
|
||||
- **component_type**: universal | specialized
|
||||
- **device_type**: mobile | tablet | desktop | responsive
|
||||
- **layout_strategy**: grid-3col, flex-row, stack, sidebar, etc.
|
||||
- **structure**: Unified DOM + layout hierarchy
|
||||
- **tag**: HTML5 semantic tags
|
||||
- **attributes**: class, role, aria-*, data-state
|
||||
- **layout**: Layout properties only (display, grid, flex, position, spacing) using {token.path}
|
||||
- **responsive**: Breakpoint-specific overrides (ONLY changed properties)
|
||||
- **children**: Recursive structure
|
||||
- **content**: Text or {{placeholder}}
|
||||
- **accessibility**: patterns, keyboard_navigation, focus_management, screen_reader_notes
|
||||
- **usage_guide**: common_sizes, variant_recommendations, usage_context, accessibility_tips
|
||||
- **extraction_metadata**: source, created, code_snippets
|
||||
|
||||
**Field Rules**:
|
||||
- $schema MUST reference W3C Design Tokens format specification
|
||||
@@ -783,140 +424,21 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
|
||||
|
||||
### animation-tokens.json
|
||||
|
||||
**Schema Structure**:
|
||||
```json
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
**Template Reference**: `~/.claude/workflows/cli-templates/ui-design/systems/animation-tokens.json`
|
||||
|
||||
"duration": {
|
||||
"$type": "duration",
|
||||
"instant": { "$value": "0ms" },
|
||||
"fast": { "$value": "150ms" },
|
||||
"normal": { "$value": "300ms" },
|
||||
"slow": { "$value": "500ms" },
|
||||
"slower": { "$value": "1000ms" }
|
||||
},
|
||||
|
||||
"easing": {
|
||||
"$type": "cubicBezier",
|
||||
"linear": { "$value": "linear" },
|
||||
"ease-in": { "$value": "cubic-bezier(0.4, 0, 1, 1)" },
|
||||
"ease-out": { "$value": "cubic-bezier(0, 0, 0.2, 1)" },
|
||||
"ease-in-out": { "$value": "cubic-bezier(0.4, 0, 0.2, 1)" },
|
||||
"spring": { "$value": "cubic-bezier(0.68, -0.55, 0.265, 1.55)" },
|
||||
"bounce": { "$value": "cubic-bezier(0.68, -0.6, 0.32, 1.6)" }
|
||||
},
|
||||
|
||||
"keyframes": {
|
||||
"/* PATTERN: Define pairs (in/out, open/close, enter/exit) */": {
|
||||
"0%": { "/* CSS properties */": "value" },
|
||||
"100%": { "/* CSS properties */": "value" }
|
||||
},
|
||||
"/* Required keyframes for components: */": "",
|
||||
"fade-in": { "0%": { "opacity": "0" }, "100%": { "opacity": "1" } },
|
||||
"fade-out": { "/* reverse of fade-in */" },
|
||||
"slide-up": { "0%": { "transform": "translateY(10px)", "opacity": "0" }, "100%": { "transform": "translateY(0)", "opacity": "1" } },
|
||||
"slide-down": { "/* reverse direction */" },
|
||||
"scale-in": { "0%": { "transform": "scale(0.95)", "opacity": "0" }, "100%": { "transform": "scale(1)", "opacity": "1" } },
|
||||
"scale-out": { "/* reverse of scale-in */" },
|
||||
"accordion-down": { "0%": { "height": "0", "opacity": "0" }, "100%": { "height": "var(--radix-accordion-content-height)", "opacity": "1" } },
|
||||
"accordion-up": { "/* reverse */" },
|
||||
"dialog-open": { "0%": { "transform": "translate(-50%, -48%) scale(0.96)", "opacity": "0" }, "100%": { "transform": "translate(-50%, -50%) scale(1)", "opacity": "1" } },
|
||||
"dialog-close": { "/* reverse */" },
|
||||
"dropdown-open": { "0%": { "transform": "scale(0.95) translateY(-4px)", "opacity": "0" }, "100%": { "transform": "scale(1) translateY(0)", "opacity": "1" } },
|
||||
"dropdown-close": { "/* reverse */" },
|
||||
"toast-enter": { "0%": { "transform": "translateX(100%)", "opacity": "0" }, "100%": { "transform": "translateX(0)", "opacity": "1" } },
|
||||
"toast-exit": { "/* reverse */" },
|
||||
"spin": { "0%": { "transform": "rotate(0deg)" }, "100%": { "transform": "rotate(360deg)" } },
|
||||
"pulse": { "0%, 100%": { "opacity": "1" }, "50%": { "opacity": "0.5" } }
|
||||
},
|
||||
|
||||
"interactions": {
|
||||
"/* PATTERN: Define for each interactive component state */": {
|
||||
"property": "string - CSS properties (comma-separated)",
|
||||
"duration": "{duration.*}",
|
||||
"easing": "{easing.*}"
|
||||
},
|
||||
"button-hover": { "property": "background-color, transform", "duration": "{duration.fast}", "easing": "{easing.ease-out}" },
|
||||
"button-active": { "property": "transform", "duration": "{duration.instant}", "easing": "{easing.ease-in}" },
|
||||
"card-hover": { "property": "box-shadow, transform", "duration": "{duration.normal}", "easing": "{easing.ease-in-out}" },
|
||||
"input-focus": { "property": "border-color, box-shadow", "duration": "{duration.fast}", "easing": "{easing.ease-out}" },
|
||||
"dropdown-toggle": { "property": "opacity, transform", "duration": "{duration.fast}", "easing": "{easing.ease-out}" },
|
||||
"accordion-toggle": { "property": "height, opacity", "duration": "{duration.normal}", "easing": "{easing.ease-in-out}" },
|
||||
"dialog-toggle": { "property": "opacity, transform", "duration": "{duration.normal}", "easing": "{easing.spring}" },
|
||||
"tabs-switch": { "property": "color, border-color", "duration": "{duration.fast}", "easing": "{easing.ease-in-out}" }
|
||||
},
|
||||
|
||||
"transitions": {
|
||||
"default": { "$value": "all {duration.normal} {easing.ease-in-out}" },
|
||||
"colors": { "$value": "color {duration.fast} {easing.linear}, background-color {duration.fast} {easing.linear}" },
|
||||
"transform": { "$value": "transform {duration.normal} {easing.spring}" },
|
||||
"opacity": { "$value": "opacity {duration.fast} {easing.linear}" },
|
||||
"all-smooth": { "$value": "all {duration.slow} {easing.ease-in-out}" }
|
||||
},
|
||||
|
||||
"component_animations": {
|
||||
"/* PATTERN: Map each component to its animations - MUST match design-tokens.json component list */": {
|
||||
"stateOrInteraction": {
|
||||
"animation": "keyframe-name {duration.*} {easing.*} OR none",
|
||||
"transition": "{interactions.*} OR none"
|
||||
}
|
||||
},
|
||||
"button": {
|
||||
"hover": { "animation": "none", "transition": "{interactions.button-hover}" },
|
||||
"active": { "animation": "none", "transition": "{interactions.button-active}" }
|
||||
},
|
||||
"card": {
|
||||
"hover": { "animation": "none", "transition": "{interactions.card-hover}" }
|
||||
},
|
||||
"input": {
|
||||
"focus": { "animation": "none", "transition": "{interactions.input-focus}" }
|
||||
},
|
||||
"dialog": {
|
||||
"open": { "animation": "dialog-open {duration.normal} {easing.spring}" },
|
||||
"close": { "animation": "dialog-close {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"dropdown": {
|
||||
"open": { "animation": "dropdown-open {duration.fast} {easing.ease-out}" },
|
||||
"close": { "animation": "dropdown-close {duration.fast} {easing.ease-in}" }
|
||||
},
|
||||
"toast": {
|
||||
"enter": { "animation": "toast-enter {duration.normal} {easing.ease-out}" },
|
||||
"exit": { "animation": "toast-exit {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"accordion": {
|
||||
"open": { "animation": "accordion-down {duration.normal} {easing.ease-out}" },
|
||||
"close": { "animation": "accordion-up {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"/* Add mappings for: tabs, switch, checkbox, badge, alert */" : {}
|
||||
},
|
||||
|
||||
"accessibility": {
|
||||
"prefers_reduced_motion": {
|
||||
"duration": "0ms",
|
||||
"keyframes": {},
|
||||
"note": "Disable animations when user prefers reduced motion",
|
||||
"css_rule": "@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; } }"
|
||||
}
|
||||
},
|
||||
|
||||
"_metadata": {
|
||||
"version": "string",
|
||||
"created": "ISO timestamp",
|
||||
"source": "code-import|explore|text",
|
||||
"code_snippets": [
|
||||
{
|
||||
"animation_name": "string - keyframe/transition name",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete @keyframes or transition code",
|
||||
"context_type": "css-keyframes|css-transition|js-animation|scss-animation|etc"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
**Structure Overview**:
|
||||
- **duration**: instant (0ms), fast (150ms), normal (300ms), slow (500ms), slower (1000ms)
|
||||
- **easing**: linear, ease-in, ease-out, ease-in-out, spring, bounce
|
||||
- **keyframes**: Animation definitions in pairs (in/out, open/close, enter/exit)
|
||||
- Required: fade-in/out, slide-up/down, scale-in/out, accordion-down/up, dialog-open/close, dropdown-open/close, toast-enter/exit, spin, pulse
|
||||
- **interactions**: Component interaction animations with property, duration, easing
|
||||
- button-hover/active, card-hover, input-focus, dropdown-toggle, accordion-toggle, dialog-toggle, tabs-switch
|
||||
- **transitions**: default, colors, transform, opacity, all-smooth
|
||||
- **component_animations**: Maps components to animations (MUST match design-tokens.json components)
|
||||
- State-based: dialog, dropdown, toast, accordion (use keyframes)
|
||||
- Interaction: button, card, input, tabs (use transitions)
|
||||
- **accessibility**: prefers_reduced_motion with CSS rule
|
||||
- **_metadata**: version, created, source, code_snippets
|
||||
|
||||
**Field Rules**:
|
||||
- $schema MUST reference W3C Design Tokens format specification
|
||||
|
||||
@@ -1,680 +0,0 @@
|
||||
---
|
||||
name: task-generate
|
||||
description: Generate task JSON files and IMPL_PLAN.md from analysis results using action-planning-agent with artifact integration
|
||||
argument-hint: "--session WFS-session-id [--cli-execute]"
|
||||
examples:
|
||||
- /workflow:tools:task-generate --session WFS-auth
|
||||
- /workflow:tools:task-generate --session WFS-auth --cli-execute
|
||||
---
|
||||
|
||||
# Task Generation Command
|
||||
|
||||
## 1. Overview
|
||||
This command generates task JSON files and an `IMPL_PLAN.md` from brainstorming role analyses. It automatically detects and integrates all brainstorming artifacts (role-specific `analysis.md` files and `guidance-specification.md`), creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate requirements and design specifications from role analyses into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
|
||||
|
||||
## 2. Execution Modes
|
||||
|
||||
This command offers two distinct modes for task execution, providing flexibility for different implementation complexities.
|
||||
|
||||
### Agent Mode (Default)
|
||||
In the default mode, each step in `implementation_approach` **omits the `command` field**. The agent interprets the step's `modification_points` and `logic_flow` to execute the task autonomously.
|
||||
- **Step Structure**: Contains `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, and `output` fields
|
||||
- **Execution**: Agent reads these fields and performs the implementation autonomously
|
||||
- **Context Loading**: Agent loads context via `pre_analysis` steps
|
||||
- **Validation**: Agent validates against acceptance criteria in `context.acceptance`
|
||||
- **Benefit**: Direct agent execution with full context awareness, no external tool overhead
|
||||
- **Use Case**: Standard implementation tasks where agent capability is sufficient
|
||||
|
||||
### CLI Execute Mode (`--cli-execute`)
|
||||
When the `--cli-execute` flag is used, each step in `implementation_approach` **includes a `command` field** that specifies the exact execution command. This mode is designed for complex implementations requiring specialized CLI tools.
|
||||
- **Step Structure**: Includes all default fields PLUS a `command` field
|
||||
- **Execution**: The specified command executes the step directly (e.g., `bash(codex ...)`)
|
||||
- **Context Packages**: Each command receives context via the CONTEXT field in the prompt
|
||||
- **Multi-Step Support**: Complex tasks can have multiple sequential codex steps with `resume --last`
|
||||
- **Benefit**: Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning and autonomous execution
|
||||
- **Use Case**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
|
||||
|
||||
## 3. Core Principles
|
||||
This command is built on a set of core principles to ensure efficient and reliable task generation.
|
||||
|
||||
- **Role Analysis-Driven**: All generated tasks originate from role-specific `analysis.md` files (enhanced in synthesis phase), ensuring direct link between requirements/design and implementation
|
||||
- **Artifact-Aware**: Automatically detects and integrates all brainstorming outputs (role analyses, guidance-specification.md, enhancements) to enrich task context
|
||||
- **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
|
||||
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
|
||||
- **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task
|
||||
- **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
|
||||
- **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
|
||||
- **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
|
||||
- **Quantification-Enforced**: **NEW** - All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations to prevent ambiguity (e.g., "17 commands: [list]" not "implement commands")
|
||||
- **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
|
||||
|
||||
## 3.5. Quantification Requirements (MANDATORY)
|
||||
|
||||
**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
|
||||
|
||||
**Core Rules**:
|
||||
1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
|
||||
2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
|
||||
3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
|
||||
4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
|
||||
5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
|
||||
|
||||
**Standard Formats**:
|
||||
|
||||
- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
|
||||
- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
|
||||
- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
|
||||
|
||||
**Validation Checklist**:
|
||||
- [ ] Every requirement contains explicit count or enumerated list
|
||||
- [ ] Every acceptance criterion is measurable with verification command
|
||||
- [ ] Every modification_point specifies exact targets (files/functions/lines)
|
||||
- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
|
||||
- [ ] Each implementation step has its own acceptance criteria
|
||||
|
||||
## 4. Execution Flow
|
||||
The command follows a streamlined, three-step process to convert analysis into executable tasks.
|
||||
|
||||
### Step 1: Input & Discovery
|
||||
The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory.
|
||||
1. **Session Validation**: Loads and validates the session from `.workflow/active/{session_id}/workflow-session.json`.
|
||||
2. **Context Package Loading** (primary source): Reads `.workflow/active/{session_id}/.process/context-package.json` for smart context and artifact catalog.
|
||||
3. **Brainstorm Artifacts Extraction**: Extracts role analysis paths from `context-package.json` → `brainstorm_artifacts.role_analyses[]` (supports `analysis*.md` automatically).
|
||||
4. **Document Loading**: Reads role analyses, guidance specification, synthesis output, and conflict resolution (if exists) using paths from context package.
|
||||
|
||||
### Step 2: Task Decomposition & Grouping
|
||||
Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
|
||||
|
||||
**Phase 2.1: Quantification Extraction (NEW - CRITICAL)**
|
||||
1. **Count Extraction**: Scan analysis documents for quantifiable information:
|
||||
- Search for numbers + nouns (e.g., "5 files", "17 commands", "3 features")
|
||||
- Identify enumerated lists (bullet points, numbered lists, comma-separated items)
|
||||
- Extract explicit counts from tables, diagrams, or structured data
|
||||
- Store extracted counts with their context (what is being counted)
|
||||
|
||||
2. **List Enumeration**: Build explicit lists for each deliverable:
|
||||
- If analysis says "implement session commands", enumerate ALL commands: [start, resume, list, complete, archive]
|
||||
- If analysis mentions "create categories", list ALL categories: [literature, experiment, data-analysis, visualization, context]
|
||||
- If analysis describes "modify functions", list ALL functions with line numbers
|
||||
- Maintain full enumerations (no "..." unless list exceeds 20 items)
|
||||
|
||||
3. **Verification Method Assignment**: For each deliverable, determine verification approach:
|
||||
- File count: `ls {path}/*.{ext} | wc -l = {count}`
|
||||
- Directory existence: `ls {parent}/ | grep -E '(name1|name2|...)' | wc -l = {count}`
|
||||
- Test coverage: `pytest --cov={module} --cov-report=term | grep TOTAL | awk '{print $4}' >= {percentage}`
|
||||
- Function existence: `grep -E '(func1|func2|...)' {file} | wc -l = {count}`
|
||||
|
||||
4. **Ambiguity Detection**: Flag vague language for replacement:
|
||||
- Detect words: "complete", "comprehensive", "reorganize", "refactor", "implement", "create" without counts
|
||||
- Require quantification: "implement" → "implement {N} {items}: [{list}]"
|
||||
- Reject unquantified deliverables
|
||||
|
||||
**Phase 2.2: Task Definition & Grouping**
|
||||
1. **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies from quantified analysis
|
||||
2. **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`
|
||||
3. **Task Grouping**:
|
||||
* Tasks with the **same signature** are candidates for merging, as they operate on the same context
|
||||
* Tasks with **different signatures** and no dependencies are grouped for parallel execution
|
||||
* Tasks with `depends_on` relationships are marked for sequential execution
|
||||
4. **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field
|
||||
|
||||
### Step 3: Output Generation
|
||||
Finally, the command generates all the necessary output files.
|
||||
1. **Task JSON Creation**: Creates individual `.task/IMPL-*.json` files, embedding all context, artifacts, and flow control steps. If `--cli-execute` is active, it generates the appropriate `codex exec` commands.
|
||||
2. **IMPL_PLAN.md Generation**: Creates the main implementation plan document, summarizing the strategy, tasks, and dependencies.
|
||||
3. **TODO_LIST.md Generation**: Creates a simple checklist for tracking task progress.
|
||||
4. **Session State Update**: Updates `workflow-session.json` with the final task count and artifact inventory, marking the session as ready for execution.
|
||||
|
||||
## 5. Task Decomposition Strategy
|
||||
The command employs a sophisticated strategy to group and decompose tasks, optimizing for context reuse and parallel execution.
|
||||
|
||||
### Core Principles
|
||||
- **Primary Rule: Shared Context → Merge Tasks**: Tasks that operate on the same files, use the same artifacts, and share the same tech stack are merged. This avoids redundant context loading and recognizes inherent relationships between the tasks.
|
||||
- **Secondary Rule: Different Contexts + No Dependencies → Decompose for Parallel Execution**: Tasks that are fully independent (different files, different artifacts, no shared dependencies) are decomposed into separate parallel execution groups.
|
||||
|
||||
### Context Analysis for Task Grouping
|
||||
The decision to merge or decompose is based on analyzing context indicators:
|
||||
|
||||
1. **Shared Context Indicators (→ Merge)**:
|
||||
* Identical `focus_paths` (working on the same modules/files).
|
||||
* Same tech stack and dependencies.
|
||||
* Identical `context.artifacts` references.
|
||||
* A sequential logic flow within the same feature.
|
||||
* Shared test fixtures or setup.
|
||||
|
||||
2. **Independent Context Indicators (→ Decompose)**:
|
||||
* Different `focus_paths` (separate modules).
|
||||
* Different tech stacks (e.g., frontend vs. backend).
|
||||
* Different `context.artifacts` (using different brainstorming outputs).
|
||||
* No shared dependencies.
|
||||
* Can be tested independently.
|
||||
|
||||
**Decomposition is only performed when**:
|
||||
- Tasks have different contexts and no shared dependencies (enabling parallel execution).
|
||||
- A single task represents an excessive workload (e.g., >2500 lines of code or >6 files to modify).
|
||||
- A sequential dependency creates a necessary block (e.g., IMPL-1 must complete before IMPL-2 can start).
|
||||
|
||||
### Context Signature Algorithm
|
||||
To automate grouping, a `context_signature` is computed for each task.
|
||||
|
||||
```javascript
|
||||
// Compute context signature for task grouping
|
||||
function computeContextSignature(task) {
|
||||
const focusPathsStr = task.context.focus_paths.sort().join('|');
|
||||
const artifactsStr = task.context.artifacts.map(a => a.path).sort().join('|');
|
||||
const techStack = task.context.shared_context?.tech_stack?.sort().join('|') || '';
|
||||
|
||||
return hash(`${focusPathsStr}:${artifactsStr}:${techStack}`);
|
||||
}
|
||||
```
|
||||
|
||||
### Execution Group Assignment
|
||||
Tasks are assigned to execution groups based on their signatures and dependencies.
|
||||
|
||||
```javascript
|
||||
// Group tasks by context signature
|
||||
function groupTasksByContext(tasks) {
|
||||
const groups = {};
|
||||
|
||||
tasks.forEach(task => {
|
||||
const signature = computeContextSignature(task);
|
||||
if (!groups[signature]) {
|
||||
groups[signature] = [];
|
||||
}
|
||||
groups[signature].push(task);
|
||||
});
|
||||
|
||||
return groups;
|
||||
}
|
||||
|
||||
// Assign execution groups for parallel tasks
|
||||
function assignExecutionGroups(tasks) {
|
||||
const contextGroups = groupTasksByContext(tasks);
|
||||
|
||||
Object.entries(contextGroups).forEach(([signature, groupTasks]) => {
|
||||
if (groupTasks.length === 1) {
|
||||
const task = groupTasks[0];
|
||||
// Single task with unique context
|
||||
if (!task.context.depends_on || task.context.depends_on.length === 0) {
|
||||
task.meta.execution_group = `parallel-${signature.slice(0, 8)}`;
|
||||
} else {
|
||||
task.meta.execution_group = null; // Sequential task
|
||||
}
|
||||
} else {
|
||||
// Multiple tasks with same context → Should be merged
|
||||
console.warn(`Tasks ${groupTasks.map(t => t.id).join(', ')} share context and should be merged`);
|
||||
// Merge tasks into single task
|
||||
return mergeTasks(groupTasks);
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
**Task Limits**:
|
||||
- **Maximum 10 tasks** (hard limit).
|
||||
- **Hierarchy**: Flat (≤5 tasks) or two-level (6-10 tasks). If >10, the scope should be re-evaluated.
|
||||
- **Parallel Groups**: Tasks with the same `execution_group` ID are independent and can run concurrently.
|
||||
|
||||
## 6. Generated Outputs
|
||||
The command produces three key documents and a directory of task files.
|
||||
|
||||
### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
|
||||
Each task JSON embeds all necessary context, artifacts, and execution steps using this schema:
|
||||
|
||||
**Top-Level Fields**:
|
||||
- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks)
|
||||
- `title`: Descriptive task name
|
||||
- `status`: Task state (`pending|active|completed|blocked|container`)
|
||||
- `context_package_path`: Path to context package (`.workflow/active/WFS-[session]/.process/context-package.json`)
|
||||
- `meta`: Task metadata
|
||||
- `context`: Task-specific context and requirements
|
||||
- `flow_control`: Execution steps and workflow
|
||||
|
||||
**Meta Object**:
|
||||
- `type`: Task category (`feature|bugfix|refactor|test-gen|test-fix|docs`)
|
||||
- `agent`: Assigned agent (`@code-developer|@test-fix-agent|@universal-executor`)
|
||||
- `execution_group`: Parallelization group ID or null
|
||||
- `context_signature`: Hash for context-based grouping
|
||||
|
||||
**Context Object**:
|
||||
- `requirements`: Quantified implementation requirements (with counts and explicit lists)
|
||||
- `focus_paths`: Target directories/files (absolute or relative paths)
|
||||
- `acceptance`: Measurable acceptance criteria (with verification commands)
|
||||
- `parent`: Parent task ID for subtasks
|
||||
- `depends_on`: Prerequisite task IDs
|
||||
- `inherited`: Shared patterns and dependencies from parent
|
||||
- `shared_context`: Tech stack and conventions
|
||||
- `artifacts`: Referenced brainstorm artifacts with paths, priority, and usage
|
||||
|
||||
**Flow Control Object**:
|
||||
- `pre_analysis`: Context loading and preparation steps
|
||||
- `load_context_package`: Load smart context and artifact catalog
|
||||
- `load_role_analysis_artifacts`: Load role analyses dynamically from context package
|
||||
- `load_planning_context`: Load finalized decisions with resolved conflicts
|
||||
- `codebase_exploration`: Discover existing patterns
|
||||
- `analyze_task_patterns`: Identify modification targets
|
||||
- `implementation_approach`: Execution steps
|
||||
- **Agent Mode**: Steps contain `modification_points` and `logic_flow` (agent executes autonomously)
|
||||
- **CLI Mode**: Steps include `command` field with CLI tool invocation
|
||||
- `target_files`: Specific files/functions/lines to modify
|
||||
|
||||
**Key Characteristics**:
|
||||
- **Quantification**: All requirements/acceptance use explicit counts and enumerations
|
||||
- **Mode Flexibility**: Supports both agent execution (default) and CLI tool execution (`--cli-execute`)
|
||||
- **Context Intelligence**: References context-package.json for smart context and artifact paths
|
||||
- **Artifact Integration**: Dynamically loads role analyses and brainstorm artifacts
|
||||
|
||||
**Example Task JSON**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-1",
|
||||
"title": "Implement feature X with Y components",
|
||||
"status": "pending",
|
||||
"context_package_path": ".workflow/active/WFS-session/.process/context-package.json",
|
||||
"meta": {
|
||||
"type": "feature",
|
||||
"agent": "@code-developer",
|
||||
"execution_group": "parallel-abc123",
|
||||
"context_signature": "hash-value"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]",
|
||||
"Create 3 directories: [dir1/, dir2/, dir3/]",
|
||||
"Modify 2 functions: [funcA() in file1.ts lines 10-25, funcB() in file2.ts lines 40-60]"
|
||||
],
|
||||
"focus_paths": ["D:\\project\\src\\module", "./tests/module"],
|
||||
"acceptance": [
|
||||
"5 command files created: verify by ls .claude/commands/*/*.md | wc -l = 5",
|
||||
"3 directories exist: verify by ls -d dir*/ | wc -l = 3",
|
||||
"All tests pass: pytest tests/ --cov=src/module (>=80% coverage)"
|
||||
],
|
||||
"depends_on": [],
|
||||
"artifacts": [
|
||||
{
|
||||
"path": ".workflow/active/WFS-session/.brainstorming/system-architect/analysis.md",
|
||||
"priority": "highest",
|
||||
"usage": "Architecture decisions and API specifications"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_context_package",
|
||||
"action": "Load context package for artifact paths and smart context",
|
||||
"commands": ["Read({{context_package_path}})"],
|
||||
"output_to": "context_package",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_role_analysis_artifacts",
|
||||
"action": "Load role analyses from context-package.json",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
"Read(each extracted path)"
|
||||
],
|
||||
"output_to": "role_analysis_artifacts",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement feature following role analyses",
|
||||
"description": "Implement feature X using requirements from role analyses and context package",
|
||||
"modification_points": [
|
||||
"Create 5 command files: [cmd1.md, cmd2.md, cmd3.md, cmd4.md, cmd5.md]",
|
||||
"Modify funcA() in file1.ts lines 10-25: add validation logic",
|
||||
"Modify funcB() in file2.ts lines 40-60: integrate with new API"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Load role analyses and context package",
|
||||
"Extract requirements and design decisions",
|
||||
"Implement commands following existing patterns",
|
||||
"Update functions with new logic",
|
||||
"Validate against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file1.ts:funcA:10-25", "file2.ts:funcB:40-60"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: In CLI Execute Mode (`--cli-execute`), `implementation_approach` steps include a `command` field with the CLI tool invocation (e.g., `bash(codex ...)`).
|
||||
|
||||
### 6.2. IMPL_PLAN.md Structure
|
||||
This document provides a high-level overview of the entire implementation plan.
|
||||
|
||||
```markdown
|
||||
---
|
||||
identifier: WFS-{session-id}
|
||||
source: "User requirements" | "File: path" | "Issue: ISS-001"
|
||||
role_analyses: .workflow/active//{session-id}/.brainstorming/[role]/analysis*.md
|
||||
artifacts: .workflow/active//{session-id}/.brainstorming/
|
||||
context_package: .workflow/active//{session-id}/.process/context-package.json # CCW smart context
|
||||
guidance_specification: .workflow/active//{session-id}/.brainstorming/guidance-specification.md # Finalized decisions with resolved conflicts
|
||||
workflow_type: "standard | tdd | design" # Indicates execution model
|
||||
verification_history: # CCW quality gates
|
||||
synthesis_clarify: "passed | skipped | pending" # Brainstorm phase clarification
|
||||
action_plan_verify: "pending"
|
||||
conflict_resolution: "resolved | none | low" # Status from context-package.json
|
||||
phase_progression: "brainstorm → synthesis → context → conflict_resolution (if needed) → planning" # CCW workflow phases
|
||||
---
|
||||
|
||||
# Implementation Plan: {Project Title}
|
||||
|
||||
## 1. Summary
|
||||
Core requirements, objectives, technical approach summary (2-3 paragraphs max).
|
||||
|
||||
**Core Objectives**:
|
||||
- [Key objective 1]
|
||||
- [Key objective 2]
|
||||
|
||||
**Technical Approach**:
|
||||
- [High-level approach]
|
||||
|
||||
## 2. Context Analysis
|
||||
|
||||
### CCW Workflow Context
|
||||
**Phase Progression**:
|
||||
- ✅ Phase 1: Brainstorming (role analyses generated by participating roles)
|
||||
- ✅ Phase 2: Synthesis (concept enhancement + clarification, {N} questions answered, role analyses refined)
|
||||
- ✅ Phase 3: Context Gathering (context-package.json: {N} files, {M} modules analyzed, conflict_risk: {level})
|
||||
- ✅ Phase 4: Conflict Resolution ({status}: {conflict_count} conflicts detected and resolved | skipped if no conflicts)
|
||||
- ⏳ Phase 5: Task Generation (current phase - generating IMPL_PLAN.md and task JSONs)
|
||||
|
||||
**Quality Gates**:
|
||||
- synthesis-clarify: ✅ Passed ({N} ambiguities resolved, {M} enhancements applied)
|
||||
- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
|
||||
|
||||
**Context Package Summary**:
|
||||
- **Focus Paths**: {list key directories from context-package.json}
|
||||
- **Key Files**: {list primary files for modification}
|
||||
- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
|
||||
- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
|
||||
|
||||
### Project Profile
|
||||
- **Type**: Greenfield/Enhancement/Refactor
|
||||
- **Scale**: User count, data volume, complexity
|
||||
- **Tech Stack**: Primary technologies
|
||||
- **Timeline**: Duration and milestones
|
||||
|
||||
### Module Structure
|
||||
'''
|
||||
[Directory tree showing key modules]
|
||||
'''
|
||||
|
||||
### Dependencies
|
||||
**Primary**: [Core libraries and frameworks]
|
||||
**APIs**: [External services]
|
||||
**Development**: [Testing, linting, CI/CD tools]
|
||||
|
||||
### Patterns & Conventions
|
||||
- **Architecture**: [Key patterns like DI, Event-Driven]
|
||||
- **Component Design**: [Design patterns]
|
||||
- **State Management**: [State strategy]
|
||||
- **Code Style**: [Naming, TypeScript coverage]
|
||||
|
||||
## 3. Brainstorming Artifacts Reference
|
||||
|
||||
### Artifact Usage Strategy
|
||||
**Primary Reference (Role Analyses)**:
|
||||
- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights
|
||||
- **When**: Every task references relevant role analyses for requirements and design decisions
|
||||
- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
|
||||
- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
|
||||
- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning
|
||||
|
||||
**Context Intelligence (context-package.json)**:
|
||||
- **What**: Smart context gathered by CCW's context-gather phase
|
||||
- **Content**: Focus paths, dependency graph, existing patterns, module structure, tech stack, conflict_risk status
|
||||
- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup and conflict awareness
|
||||
- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
|
||||
|
||||
**Conflict Resolution Status**:
|
||||
- **What**: Conflict resolution applied in-place to brainstorm artifacts (if conflict_risk was >= medium)
|
||||
- **Location**: guidance-specification.md and role analyses (*.md) contain resolved conflicts
|
||||
- **Status**: Check context-package.json → conflict_detection.conflict_risk ("resolved" | "none" | "low")
|
||||
- **Usage**: Read finalized decisions from guidance-specification.md (includes applied resolutions)
|
||||
- **CCW Value**: Interactive conflict resolution with user confirmation, modifications applied automatically
|
||||
|
||||
### Role Analysis Documents (Highest Priority)
|
||||
Role analyses provide specialized perspectives on the implementation:
|
||||
- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies
|
||||
- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns
|
||||
- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements
|
||||
- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics
|
||||
- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies
|
||||
- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns
|
||||
|
||||
### Supporting Artifacts (Reference)
|
||||
- **topic-framework.md**: Role-specific discussion points and analysis framework
|
||||
|
||||
**Artifact Priority in Development**:
|
||||
1. {context_package_path} (primary source: smart context AND brainstorm artifact catalog in `brainstorm_artifacts` + conflict_risk status)
|
||||
2. role/analysis*.md (paths from context-package.json: requirements, design specs, enhanced by synthesis, with resolved conflicts if any)
|
||||
3. guidance-specification.md (path from context-package.json: finalized decisions with resolved conflicts if any)
|
||||
|
||||
## 4. Implementation Strategy
|
||||
|
||||
### Execution Strategy
|
||||
**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
|
||||
|
||||
**Rationale**: [Why this execution model fits the project]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [List independent workstreams]
|
||||
|
||||
**Serialization Requirements**:
|
||||
- [List critical dependencies]
|
||||
|
||||
### Architectural Approach
|
||||
**Key Architecture Decisions**:
|
||||
- [ADR references from role analyses]
|
||||
- [Justification for architecture patterns]
|
||||
|
||||
**Integration Strategy**:
|
||||
- [How modules communicate]
|
||||
- [State management approach]
|
||||
|
||||
### Key Dependencies
|
||||
**Task Dependency Graph**:
|
||||
'''
|
||||
[High-level dependency visualization]
|
||||
'''
|
||||
|
||||
**Critical Path**: [Identify bottleneck tasks]
|
||||
|
||||
### Testing Strategy
|
||||
**Testing Approach**:
|
||||
- Unit testing: [Tools, scope]
|
||||
- Integration testing: [Key integration points]
|
||||
- E2E testing: [Critical user flows]
|
||||
|
||||
**Coverage Targets**:
|
||||
- Lines: ≥70%
|
||||
- Functions: ≥70%
|
||||
- Branches: ≥65%
|
||||
|
||||
**Quality Gates**:
|
||||
- [CI/CD gates]
|
||||
- [Performance budgets]
|
||||
|
||||
## 5. Task Breakdown Summary
|
||||
|
||||
### Task Count
|
||||
**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
|
||||
|
||||
### Task Structure
|
||||
- **IMPL-1**: [Main task title]
|
||||
- **IMPL-2**: [Main task title]
|
||||
...
|
||||
|
||||
### Complexity Assessment
|
||||
- **High**: [List with rationale]
|
||||
- **Medium**: [List]
|
||||
- **Low**: [List]
|
||||
|
||||
### Dependencies
|
||||
[Reference Section 4.3 for dependency graph]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [Specific task groups that can run in parallel]
|
||||
|
||||
## 6. Implementation Plan (Detailed Phased Breakdown)
|
||||
|
||||
### Execution Strategy
|
||||
|
||||
**Phase 1 (Weeks 1-2): [Phase Name]**
|
||||
- **Tasks**: IMPL-1, IMPL-2
|
||||
- **Deliverables**:
|
||||
- [Specific deliverable 1]
|
||||
- [Specific deliverable 2]
|
||||
- **Success Criteria**:
|
||||
- [Measurable criterion]
|
||||
|
||||
**Phase 2 (Weeks 3-N): [Phase Name]**
|
||||
...
|
||||
|
||||
### Resource Requirements
|
||||
|
||||
**Development Team**:
|
||||
- [Team composition and skills]
|
||||
|
||||
**External Dependencies**:
|
||||
- [Third-party services, APIs]
|
||||
|
||||
**Infrastructure**:
|
||||
- [Development, staging, production environments]
|
||||
|
||||
## 7. Risk Assessment & Mitigation
|
||||
|
||||
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|
||||
|------|--------|-------------|---------------------|-------|
|
||||
| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
|
||||
|
||||
**Critical Risks** (High impact + High probability):
|
||||
- [Risk 1]: [Detailed mitigation plan]
|
||||
|
||||
**Monitoring Strategy**:
|
||||
- [How risks will be monitored]
|
||||
|
||||
## 8. Success Criteria
|
||||
|
||||
**Functional Completeness**:
|
||||
- [ ] All requirements from role analysis documents implemented
|
||||
- [ ] All acceptance criteria from task.json files met
|
||||
|
||||
**Technical Quality**:
|
||||
- [ ] Test coverage ≥70%
|
||||
- [ ] Bundle size within budget
|
||||
- [ ] Performance targets met
|
||||
|
||||
**Operational Readiness**:
|
||||
- [ ] CI/CD pipeline operational
|
||||
- [ ] Monitoring and logging configured
|
||||
- [ ] Documentation complete
|
||||
|
||||
**Business Metrics**:
|
||||
- [ ] [Key business metrics from role analyses]
|
||||
```
|
||||
|
||||
### 6.3. TODO_LIST.md Structure
|
||||
A simple Markdown file for tracking the status of each task.
|
||||
|
||||
```markdown
|
||||
# Tasks: [Session Topic]
|
||||
|
||||
## Task Progress
|
||||
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
|
||||
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
|
||||
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2-summary.md)
|
||||
|
||||
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md)
|
||||
|
||||
## Status Legend
|
||||
- `▸` = Container task (has subtasks)
|
||||
- `- [ ]` = Pending leaf task
|
||||
- `- [x]` = Completed leaf task
|
||||
- Maximum 2 levels: Main tasks and subtasks only
|
||||
```
|
||||
|
||||
### 6.4. Output Files Diagram
|
||||
The command organizes outputs into a standard directory structure.
|
||||
```
|
||||
.workflow/active//{session-id}/
|
||||
├── IMPL_PLAN.md # Implementation plan
|
||||
├── TODO_LIST.md # Progress tracking
|
||||
├── .task/
|
||||
│ ├── IMPL-1.json # Container task
|
||||
│ ├── IMPL-1.1.json # Leaf task with flow_control
|
||||
│ └── IMPL-1.2.json # Leaf task with flow_control
|
||||
├── .brainstorming # Input artifacts from brainstorm + synthesis
|
||||
│ ├── guidance-specification.md # Finalized decisions (with resolved conflicts if any)
|
||||
│ └── {role}/analysis*.md # Role analyses (enhanced by synthesis, with resolved conflicts if any)
|
||||
└── .process/
|
||||
└── context-package.json # Input from context-gather (smart context + conflict_risk status)
|
||||
```
|
||||
|
||||
## 7. Artifact Integration
|
||||
The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.
|
||||
|
||||
#### Artifact Priority
|
||||
1. **context-package.json** (critical): Primary source - smart context AND all brainstorm artifact paths in `brainstorm_artifacts` section + conflict_risk status
|
||||
2. **role/analysis*.md** (highest): Paths from context-package.json → role-specific requirements, design specs, enhanced by synthesis, with resolved conflicts applied in-place
|
||||
3. **guidance-specification.md** (high): Path from context-package.json → finalized decisions with resolved conflicts (if conflict_risk was >= medium)
|
||||
|
||||
#### Artifact-Task Mapping
|
||||
Artifacts are mapped to tasks based on their relevance to the task's domain.
|
||||
- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type
|
||||
- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components
|
||||
- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns
|
||||
- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards
|
||||
- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs
|
||||
- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories
|
||||
|
||||
This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
|
||||
|
||||
## 8. Error Handling
|
||||
|
||||
### Input Validation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Session not found | Invalid session ID | Verify session exists |
|
||||
| Context missing | Incomplete planning | Run context-gather first |
|
||||
| Invalid format | Corrupted results | Regenerate analysis |
|
||||
|
||||
### Task Generation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Count exceeds limit | >10 tasks | Re-scope requirements |
|
||||
| Invalid structure | Missing fields | Fix analysis results |
|
||||
| Dependency cycle | Circular refs | Adjust dependencies |
|
||||
|
||||
### Artifact Integration Errors
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| Artifact not found | Missing output | Continue without artifacts |
|
||||
| Invalid format | Corrupted file | Skip artifact loading |
|
||||
| Path invalid | Moved/deleted | Update references |
|
||||
|
||||
## 10. Usage & Related Commands
|
||||
|
||||
**Basic Usage**:
|
||||
```bash
|
||||
/workflow:tools:task-generate --session WFS-auth [--cli-execute]
|
||||
```
|
||||
|
||||
**Workflow Integration**:
|
||||
- Called by: `/workflow:plan` (task generation phase)
|
||||
- Followed by: `/workflow:execute`, `/workflow:status`
|
||||
|
||||
**Related Commands**:
|
||||
- `/workflow:plan` - Orchestrates entire planning workflow
|
||||
- `/workflow:tools:context-gather` - Provides context package input
|
||||
- `/workflow:tools:conflict-resolution` - Provides conflict resolution (if needed)
|
||||
- `/workflow:execute` - Executes generated tasks
|
||||
@@ -148,7 +148,6 @@ def build_command_relationships() -> Dict[str, Any]:
|
||||
"workflow:session:start",
|
||||
"workflow:tools:context-gather",
|
||||
"workflow:tools:conflict-resolution",
|
||||
"workflow:tools:task-generate",
|
||||
"workflow:tools:task-generate-agent"
|
||||
],
|
||||
"next_steps": ["workflow:action-plan-verify", "workflow:status", "workflow:execute"],
|
||||
|
||||
@@ -0,0 +1,247 @@
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
|
||||
"duration": {
|
||||
"$type": "duration",
|
||||
"instant": { "$value": "0ms" },
|
||||
"fast": { "$value": "150ms" },
|
||||
"normal": { "$value": "300ms" },
|
||||
"slow": { "$value": "500ms" },
|
||||
"slower": { "$value": "1000ms" }
|
||||
},
|
||||
|
||||
"easing": {
|
||||
"$type": "cubicBezier",
|
||||
"linear": { "$value": "linear" },
|
||||
"ease-in": { "$value": "cubic-bezier(0.4, 0, 1, 1)" },
|
||||
"ease-out": { "$value": "cubic-bezier(0, 0, 0.2, 1)" },
|
||||
"ease-in-out": { "$value": "cubic-bezier(0.4, 0, 0.2, 1)" },
|
||||
"spring": { "$value": "cubic-bezier(0.68, -0.55, 0.265, 1.55)" },
|
||||
"bounce": { "$value": "cubic-bezier(0.68, -0.6, 0.32, 1.6)" }
|
||||
},
|
||||
|
||||
"keyframes": {
|
||||
"_comment_pattern": "Define pairs (in/out, open/close, enter/exit)",
|
||||
"_comment_required": "Required keyframes for components",
|
||||
|
||||
"fade-in": {
|
||||
"0%": { "opacity": "0" },
|
||||
"100%": { "opacity": "1" }
|
||||
},
|
||||
"fade-out": {
|
||||
"_comment": "reverse of fade-in",
|
||||
"0%": { "opacity": "1" },
|
||||
"100%": { "opacity": "0" }
|
||||
},
|
||||
|
||||
"slide-up": {
|
||||
"0%": { "transform": "translateY(10px)", "opacity": "0" },
|
||||
"100%": { "transform": "translateY(0)", "opacity": "1" }
|
||||
},
|
||||
"slide-down": {
|
||||
"_comment": "reverse direction",
|
||||
"0%": { "transform": "translateY(0)", "opacity": "1" },
|
||||
"100%": { "transform": "translateY(10px)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"scale-in": {
|
||||
"0%": { "transform": "scale(0.95)", "opacity": "0" },
|
||||
"100%": { "transform": "scale(1)", "opacity": "1" }
|
||||
},
|
||||
"scale-out": {
|
||||
"_comment": "reverse of scale-in",
|
||||
"0%": { "transform": "scale(1)", "opacity": "1" },
|
||||
"100%": { "transform": "scale(0.95)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"accordion-down": {
|
||||
"0%": { "height": "0", "opacity": "0" },
|
||||
"100%": { "height": "var(--radix-accordion-content-height)", "opacity": "1" }
|
||||
},
|
||||
"accordion-up": {
|
||||
"_comment": "reverse",
|
||||
"0%": { "height": "var(--radix-accordion-content-height)", "opacity": "1" },
|
||||
"100%": { "height": "0", "opacity": "0" }
|
||||
},
|
||||
|
||||
"dialog-open": {
|
||||
"0%": { "transform": "translate(-50%, -48%) scale(0.96)", "opacity": "0" },
|
||||
"100%": { "transform": "translate(-50%, -50%) scale(1)", "opacity": "1" }
|
||||
},
|
||||
"dialog-close": {
|
||||
"_comment": "reverse",
|
||||
"0%": { "transform": "translate(-50%, -50%) scale(1)", "opacity": "1" },
|
||||
"100%": { "transform": "translate(-50%, -48%) scale(0.96)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"dropdown-open": {
|
||||
"0%": { "transform": "scale(0.95) translateY(-4px)", "opacity": "0" },
|
||||
"100%": { "transform": "scale(1) translateY(0)", "opacity": "1" }
|
||||
},
|
||||
"dropdown-close": {
|
||||
"_comment": "reverse",
|
||||
"0%": { "transform": "scale(1) translateY(0)", "opacity": "1" },
|
||||
"100%": { "transform": "scale(0.95) translateY(-4px)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"toast-enter": {
|
||||
"0%": { "transform": "translateX(100%)", "opacity": "0" },
|
||||
"100%": { "transform": "translateX(0)", "opacity": "1" }
|
||||
},
|
||||
"toast-exit": {
|
||||
"_comment": "reverse",
|
||||
"0%": { "transform": "translateX(0)", "opacity": "1" },
|
||||
"100%": { "transform": "translateX(100%)", "opacity": "0" }
|
||||
},
|
||||
|
||||
"spin": {
|
||||
"0%": { "transform": "rotate(0deg)" },
|
||||
"100%": { "transform": "rotate(360deg)" }
|
||||
},
|
||||
"pulse": {
|
||||
"0%, 100%": { "opacity": "1" },
|
||||
"50%": { "opacity": "0.5" }
|
||||
}
|
||||
},
|
||||
|
||||
"interactions": {
|
||||
"_comment_pattern": "Define for each interactive component state",
|
||||
"_structure": {
|
||||
"property": "string - CSS properties (comma-separated)",
|
||||
"duration": "{duration.*}",
|
||||
"easing": "{easing.*}"
|
||||
},
|
||||
|
||||
"button-hover": {
|
||||
"property": "background-color, transform",
|
||||
"duration": "{duration.fast}",
|
||||
"easing": "{easing.ease-out}"
|
||||
},
|
||||
"button-active": {
|
||||
"property": "transform",
|
||||
"duration": "{duration.instant}",
|
||||
"easing": "{easing.ease-in}"
|
||||
},
|
||||
"card-hover": {
|
||||
"property": "box-shadow, transform",
|
||||
"duration": "{duration.normal}",
|
||||
"easing": "{easing.ease-in-out}"
|
||||
},
|
||||
"input-focus": {
|
||||
"property": "border-color, box-shadow",
|
||||
"duration": "{duration.fast}",
|
||||
"easing": "{easing.ease-out}"
|
||||
},
|
||||
"dropdown-toggle": {
|
||||
"property": "opacity, transform",
|
||||
"duration": "{duration.fast}",
|
||||
"easing": "{easing.ease-out}"
|
||||
},
|
||||
"accordion-toggle": {
|
||||
"property": "height, opacity",
|
||||
"duration": "{duration.normal}",
|
||||
"easing": "{easing.ease-in-out}"
|
||||
},
|
||||
"dialog-toggle": {
|
||||
"property": "opacity, transform",
|
||||
"duration": "{duration.normal}",
|
||||
"easing": "{easing.spring}"
|
||||
},
|
||||
"tabs-switch": {
|
||||
"property": "color, border-color",
|
||||
"duration": "{duration.fast}",
|
||||
"easing": "{easing.ease-in-out}"
|
||||
}
|
||||
},
|
||||
|
||||
"transitions": {
|
||||
"default": { "$value": "all {duration.normal} {easing.ease-in-out}" },
|
||||
"colors": { "$value": "color {duration.fast} {easing.linear}, background-color {duration.fast} {easing.linear}" },
|
||||
"transform": { "$value": "transform {duration.normal} {easing.spring}" },
|
||||
"opacity": { "$value": "opacity {duration.fast} {easing.linear}" },
|
||||
"all-smooth": { "$value": "all {duration.slow} {easing.ease-in-out}" }
|
||||
},
|
||||
|
||||
"component_animations": {
|
||||
"_comment_pattern": "Map each component to its animations - MUST match design-tokens.json component list",
|
||||
"_structure": {
|
||||
"stateOrInteraction": {
|
||||
"animation": "keyframe-name {duration.*} {easing.*} OR none",
|
||||
"transition": "{interactions.*} OR none"
|
||||
}
|
||||
},
|
||||
|
||||
"button": {
|
||||
"hover": { "animation": "none", "transition": "{interactions.button-hover}" },
|
||||
"active": { "animation": "none", "transition": "{interactions.button-active}" }
|
||||
},
|
||||
"card": {
|
||||
"hover": { "animation": "none", "transition": "{interactions.card-hover}" }
|
||||
},
|
||||
"input": {
|
||||
"focus": { "animation": "none", "transition": "{interactions.input-focus}" }
|
||||
},
|
||||
"dialog": {
|
||||
"open": { "animation": "dialog-open {duration.normal} {easing.spring}" },
|
||||
"close": { "animation": "dialog-close {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"dropdown": {
|
||||
"open": { "animation": "dropdown-open {duration.fast} {easing.ease-out}" },
|
||||
"close": { "animation": "dropdown-close {duration.fast} {easing.ease-in}" }
|
||||
},
|
||||
"toast": {
|
||||
"enter": { "animation": "toast-enter {duration.normal} {easing.ease-out}" },
|
||||
"exit": { "animation": "toast-exit {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"accordion": {
|
||||
"open": { "animation": "accordion-down {duration.normal} {easing.ease-out}" },
|
||||
"close": { "animation": "accordion-up {duration.normal} {easing.ease-in}" }
|
||||
},
|
||||
"_comment_missing": "Add mappings for: tabs, switch, checkbox, badge, alert"
|
||||
},
|
||||
|
||||
"accessibility": {
|
||||
"prefers_reduced_motion": {
|
||||
"duration": "0ms",
|
||||
"keyframes": {},
|
||||
"note": "Disable animations when user prefers reduced motion",
|
||||
"css_rule": "@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; } }"
|
||||
}
|
||||
},
|
||||
|
||||
"_metadata": {
|
||||
"version": "string",
|
||||
"created": "ISO timestamp",
|
||||
"source": "code-import|explore|text",
|
||||
"code_snippets": [
|
||||
{
|
||||
"animation_name": "string - keyframe/transition name",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete @keyframes or transition code",
|
||||
"context_type": "css-keyframes|css-transition|js-animation|scss-animation|etc"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"_field_rules": {
|
||||
"schema": "$schema MUST reference W3C Design Tokens format specification",
|
||||
"duration_wrapper": "All duration values MUST use $value wrapper with ms units",
|
||||
"easing_wrapper": "All easing values MUST use $value wrapper with standard CSS easing or cubic-bezier()",
|
||||
"keyframes": "keyframes MUST define complete component state animations (open/close, enter/exit)",
|
||||
"interactions_refs": "interactions MUST reference duration and easing using {token.path} syntax",
|
||||
"component_mapping": "component_animations MUST map component states to specific keyframes and transitions",
|
||||
"component_coverage": "component_animations MUST be defined for all interactive and stateful components",
|
||||
"transitions_wrapper": "transitions MUST use $value wrapper for complete transition definitions",
|
||||
"accessibility": "accessibility.prefers_reduced_motion MUST be included with CSS media query rule",
|
||||
"code_snippets": "_metadata.code_snippets ONLY present in Code Import mode"
|
||||
},
|
||||
|
||||
"_animation_component_integration": {
|
||||
"requirement": "Each component in design-tokens.json component section MUST have corresponding entry in component_animations",
|
||||
"state_based": "State-based animations (dialog.open, accordion.close) MUST use keyframe animations",
|
||||
"interaction": "Interaction animations (button.hover, input.focus) MUST use transitions",
|
||||
"consistency": "All animation references use {token.path} syntax for consistency"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,342 @@
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
"name": "string - Token set name",
|
||||
"description": "string - Token set description",
|
||||
|
||||
"color": {
|
||||
"background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" }, "$description": "optional" },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"card": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"card-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"border": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"input": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"ring": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
|
||||
"interactive": {
|
||||
"primary": {
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"disabled": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
"secondary": {
|
||||
"_comment": "Same structure as primary",
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"disabled": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
"accent": {
|
||||
"_comment": "Same structure (no disabled state)",
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"active": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
"destructive": {
|
||||
"_comment": "Same structure (no active/disabled states)",
|
||||
"default": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"hover": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
}
|
||||
},
|
||||
|
||||
"muted": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"muted-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
|
||||
"chart": {
|
||||
"1": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"2": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"3": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"4": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"5": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
},
|
||||
|
||||
"sidebar": {
|
||||
"background": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"primary": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"primary-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"accent": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"accent-foreground": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"border": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } },
|
||||
"ring": { "$type": "color", "$value": { "light": "oklch(...)", "dark": "oklch(...)" } }
|
||||
}
|
||||
},
|
||||
|
||||
"typography": {
|
||||
"font_families": {
|
||||
"sans": "string - 'Font Name', fallback1, fallback2",
|
||||
"serif": "string",
|
||||
"mono": "string"
|
||||
},
|
||||
"font_sizes": {
|
||||
"xs": "0.75rem",
|
||||
"sm": "0.875rem",
|
||||
"base": "1rem",
|
||||
"lg": "1.125rem",
|
||||
"xl": "1.25rem",
|
||||
"2xl": "1.5rem",
|
||||
"3xl": "1.875rem",
|
||||
"4xl": "2.25rem"
|
||||
},
|
||||
"line_heights": {
|
||||
"tight": "number",
|
||||
"normal": "number",
|
||||
"relaxed": "number"
|
||||
},
|
||||
"letter_spacing": {
|
||||
"tight": "string",
|
||||
"normal": "string",
|
||||
"wide": "string"
|
||||
},
|
||||
"combinations": [
|
||||
{
|
||||
"name": "h1|h2|h3|h4|h5|h6|body|caption",
|
||||
"font_family": "sans|serif|mono",
|
||||
"font_size": "string - reference to font_sizes",
|
||||
"font_weight": "number - 400|500|600|700",
|
||||
"line_height": "string",
|
||||
"letter_spacing": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"spacing": {
|
||||
"0": "0",
|
||||
"1": "0.25rem",
|
||||
"2": "0.5rem",
|
||||
"3": "0.75rem",
|
||||
"4": "1rem",
|
||||
"6": "1.5rem",
|
||||
"8": "2rem",
|
||||
"12": "3rem",
|
||||
"16": "4rem",
|
||||
"20": "5rem",
|
||||
"24": "6rem",
|
||||
"32": "8rem",
|
||||
"40": "10rem",
|
||||
"48": "12rem",
|
||||
"56": "14rem",
|
||||
"64": "16rem"
|
||||
},
|
||||
|
||||
"opacity": {
|
||||
"disabled": "0.5",
|
||||
"hover": "0.8",
|
||||
"active": "1"
|
||||
},
|
||||
|
||||
"shadows": {
|
||||
"2xs": "string - CSS shadow value",
|
||||
"xs": "string",
|
||||
"sm": "string",
|
||||
"DEFAULT": "string",
|
||||
"md": "string",
|
||||
"lg": "string",
|
||||
"xl": "string",
|
||||
"2xl": "string"
|
||||
},
|
||||
|
||||
"border_radius": {
|
||||
"sm": "string - calc() or fixed",
|
||||
"md": "string",
|
||||
"lg": "string",
|
||||
"xl": "string",
|
||||
"DEFAULT": "string"
|
||||
},
|
||||
|
||||
"breakpoints": {
|
||||
"sm": "640px",
|
||||
"md": "768px",
|
||||
"lg": "1024px",
|
||||
"xl": "1280px",
|
||||
"2xl": "1536px"
|
||||
},
|
||||
|
||||
"component": {
|
||||
"_comment_pattern": "COMPONENT PATTERN - Apply to: button, card, input, dialog, dropdown, toast, accordion, tabs, switch, checkbox, badge, alert",
|
||||
"_example_button": {
|
||||
"$type": "component",
|
||||
"base": {
|
||||
"_comment": "Layout properties using camelCase",
|
||||
"display": "inline-flex|flex|block",
|
||||
"alignItems": "center",
|
||||
"borderRadius": "{border_radius.md}",
|
||||
"transition": "{transitions.default}"
|
||||
},
|
||||
"size": {
|
||||
"small": { "height": "32px", "padding": "{spacing.2} {spacing.3}", "fontSize": "{typography.font_sizes.xs}" },
|
||||
"default": { "height": "40px", "padding": "{spacing.2} {spacing.4}" },
|
||||
"large": { "height": "48px", "padding": "{spacing.3} {spacing.6}", "fontSize": "{typography.font_sizes.base}" }
|
||||
},
|
||||
"variant": {
|
||||
"variantName": {
|
||||
"default": { "backgroundColor": "{color.interactive.primary.default}", "color": "{color.interactive.primary.foreground}" },
|
||||
"hover": { "backgroundColor": "{color.interactive.primary.hover}" },
|
||||
"active": { "backgroundColor": "{color.interactive.primary.active}" },
|
||||
"disabled": { "backgroundColor": "{color.interactive.primary.disabled}", "opacity": "{opacity.disabled}", "cursor": "not-allowed" },
|
||||
"focus": { "outline": "2px solid {color.ring}", "outlineOffset": "2px" }
|
||||
}
|
||||
},
|
||||
"state": {
|
||||
"_comment": "For stateful components (dialog, accordion, etc.)",
|
||||
"open": { "animation": "{animation.name.component-open} {animation.duration.normal} {animation.easing.ease-out}" },
|
||||
"closed": { "animation": "{animation.name.component-close} {animation.duration.normal} {animation.easing.ease-in}" }
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"elevation": {
|
||||
"$type": "elevation",
|
||||
"base": { "$value": "0" },
|
||||
"overlay": { "$value": "40" },
|
||||
"dropdown": { "$value": "50" },
|
||||
"dialog": { "$value": "50" },
|
||||
"tooltip": { "$value": "60" }
|
||||
},
|
||||
|
||||
"_metadata": {
|
||||
"version": "string - W3C version or custom version",
|
||||
"created": "ISO timestamp - 2024-01-01T00:00:00Z",
|
||||
"source": "code-import|explore|text",
|
||||
"theme_colors_guide": {
|
||||
"description": "Theme colors are the core brand identity colors that define the visual hierarchy and emotional tone of the design system",
|
||||
"primary": {
|
||||
"role": "Main brand color",
|
||||
"usage": "Primary actions (CTAs, key interactive elements, navigation highlights, primary buttons)",
|
||||
"contrast_requirement": "WCAG AA - 4.5:1 for text, 3:1 for UI components"
|
||||
},
|
||||
"secondary": {
|
||||
"role": "Supporting brand color",
|
||||
"usage": "Secondary actions and complementary elements (less prominent buttons, secondary navigation, supporting features)",
|
||||
"principle": "Should complement primary without competing for attention"
|
||||
},
|
||||
"accent": {
|
||||
"role": "Highlight color for emphasis",
|
||||
"usage": "Attention-grabbing elements used sparingly (badges, notifications, special promotions, highlights)",
|
||||
"principle": "Should create strong visual contrast to draw focus"
|
||||
},
|
||||
"destructive": {
|
||||
"role": "Error and destructive action color",
|
||||
"usage": "Delete buttons, error messages, critical warnings",
|
||||
"principle": "Must signal danger or caution clearly"
|
||||
},
|
||||
"harmony_note": "All theme colors must work harmoniously together and align with brand identity. In multi-file extraction, prioritize definitions with semantic comments explaining brand intent."
|
||||
},
|
||||
"conflicts": [
|
||||
{
|
||||
"token_name": "string - which token has conflicts",
|
||||
"category": "string - colors|typography|etc",
|
||||
"definitions": [
|
||||
{
|
||||
"value": "string - token value",
|
||||
"source_file": "string - absolute path",
|
||||
"line_number": "number",
|
||||
"context": "string - surrounding comment or null",
|
||||
"semantic_intent": "string - interpretation of definition"
|
||||
}
|
||||
],
|
||||
"selected_value": "string - final chosen value",
|
||||
"selection_reason": "string - why this value was chosen"
|
||||
}
|
||||
],
|
||||
"code_snippets": [
|
||||
{
|
||||
"category": "colors|typography|spacing|shadows|border_radius|component",
|
||||
"token_name": "string - which token this snippet defines",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete code block",
|
||||
"context_type": "css-variable|css-class|js-object|scss-variable|etc"
|
||||
}
|
||||
],
|
||||
"usage_recommendations": {
|
||||
"typography": {
|
||||
"common_sizes": {
|
||||
"small_text": "sm (0.875rem)",
|
||||
"body_text": "base (1rem)",
|
||||
"heading": "2xl-4xl"
|
||||
},
|
||||
"common_combinations": [
|
||||
{
|
||||
"name": "Heading + Body",
|
||||
"heading": "2xl",
|
||||
"body": "base",
|
||||
"use_case": "Article sections"
|
||||
}
|
||||
]
|
||||
},
|
||||
"spacing": {
|
||||
"size_guide": {
|
||||
"tight": "1-2 (0.25rem-0.5rem)",
|
||||
"normal": "4-6 (1rem-1.5rem)",
|
||||
"loose": "8-12 (2rem-3rem)"
|
||||
},
|
||||
"common_patterns": [
|
||||
{
|
||||
"pattern": "padding-4 margin-bottom-6",
|
||||
"use_case": "Card content spacing",
|
||||
"pixel_value": "1rem padding, 1.5rem margin"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"_field_rules": {
|
||||
"schema": "$schema MUST reference W3C Design Tokens format specification",
|
||||
"colors": "All color values MUST use OKLCH format with light/dark mode values",
|
||||
"types": "All tokens MUST include $type metadata (color, dimension, duration, component, elevation)",
|
||||
"states": "Color tokens MUST include interactive states (default, hover, active, disabled) where applicable",
|
||||
"fonts": "Typography font_families MUST include Google Fonts with fallback stacks",
|
||||
"spacing": "Spacing MUST use systematic scale (multiples of 0.25rem base unit)",
|
||||
"components": "Component definitions MUST be structured objects referencing other tokens via {token.path} syntax",
|
||||
"component_states": "Component definitions MUST include state-based styling (default, hover, active, focus, disabled)",
|
||||
"elevation": "elevation z-index values MUST be defined for layered components (overlay, dropdown, dialog, tooltip)",
|
||||
"metadata_guide": "_metadata.theme_colors_guide RECOMMENDED in all modes to help users understand theme color roles and usage",
|
||||
"metadata_conflicts": "_metadata.conflicts MANDATORY in Code Import mode when conflicting definitions detected",
|
||||
"metadata_snippets": "_metadata.code_snippets ONLY present in Code Import mode",
|
||||
"metadata_recommendations": "_metadata.usage_recommendations RECOMMENDED for universal components"
|
||||
},
|
||||
|
||||
"_required_components": {
|
||||
"_comment": "12+ components required, use pattern above",
|
||||
"button": "5 variants (primary, secondary, destructive, outline, ghost) + 3 sizes + states (default, hover, active, disabled, focus)",
|
||||
"card": "2 variants (default, interactive) + hover animations",
|
||||
"input": "states (default, focus, disabled, error) + 3 sizes",
|
||||
"dialog": "overlay + content + states (open, closed with animations)",
|
||||
"dropdown": "trigger (references button) + content + item (with states) + states (open, closed)",
|
||||
"toast": "2 variants (default, destructive) + states (enter, exit with animations)",
|
||||
"accordion": "trigger + content + states (open, closed with animations)",
|
||||
"tabs": "list + trigger (states: default, hover, active, disabled) + content",
|
||||
"switch": "root + thumb + states (checked, disabled)",
|
||||
"checkbox": "states (default, checked, disabled, focus)",
|
||||
"badge": "4 variants (default, secondary, destructive, outline)",
|
||||
"alert": "2 variants (default, destructive)"
|
||||
},
|
||||
|
||||
"_token_reference_syntax": {
|
||||
"_comment": "Use {token.path} to reference other tokens",
|
||||
"examples": [
|
||||
"{color.interactive.primary.default}",
|
||||
"{spacing.4}",
|
||||
"{typography.font_sizes.sm}"
|
||||
],
|
||||
"resolution": "References are resolved during CSS generation",
|
||||
"nested": "Supports nested references (e.g., {component.button.base})"
|
||||
},
|
||||
|
||||
"_conflict_resolution_rules": {
|
||||
"_comment": "Code Import Mode only",
|
||||
"detect": "MUST detect when same token has different values across files",
|
||||
"read": "MUST read semantic comments (/* ... */) surrounding definitions",
|
||||
"prioritize": "MUST prioritize definitions with semantic intent over bare values",
|
||||
"record": "MUST record ALL definitions in conflicts array, not just selected one",
|
||||
"explain": "MUST explain selection_reason referencing semantic context",
|
||||
"verify": "For core theme tokens (primary, secondary, accent): MUST verify selected value aligns with overall color scheme described in comments"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,145 @@
|
||||
{
|
||||
"$schema": "https://tr.designtokens.org/format/",
|
||||
"templates": [
|
||||
{
|
||||
"target": "string - page/component name (e.g., hero-section, product-card)",
|
||||
"description": "string - layout description",
|
||||
"component_type": "universal|specialized",
|
||||
"device_type": "mobile|tablet|desktop|responsive",
|
||||
"layout_strategy": "string - grid-3col|flex-row|stack|sidebar|etc",
|
||||
|
||||
"structure": {
|
||||
"tag": "string - HTML5 semantic tag (header|nav|main|section|article|aside|footer|div|etc)",
|
||||
"attributes": {
|
||||
"class": "string - semantic class name",
|
||||
"role": "string - ARIA role (navigation|main|complementary|etc)",
|
||||
"aria-label": "string - ARIA label",
|
||||
"aria-describedby": "string - ARIA describedby",
|
||||
"data-state": "string - data attributes for state management (open|closed|etc)"
|
||||
},
|
||||
"layout": {
|
||||
"_comment": "LAYOUT PROPERTIES ONLY - Use camelCase for property names",
|
||||
"display": "grid|flex|block|inline-flex",
|
||||
"grid-template-columns": "{spacing.*} or CSS value (repeat(3, 1fr))",
|
||||
"grid-template-rows": "string",
|
||||
"gap": "{spacing.*}",
|
||||
"padding": "{spacing.*}",
|
||||
"margin": "{spacing.*}",
|
||||
"alignItems": "start|center|end|stretch",
|
||||
"justifyContent": "start|center|end|space-between|space-around",
|
||||
"flexDirection": "row|column",
|
||||
"flexWrap": "wrap|nowrap",
|
||||
"position": "relative|absolute|fixed|sticky",
|
||||
"top": "string",
|
||||
"right": "string",
|
||||
"bottom": "string",
|
||||
"left": "string",
|
||||
"width": "string",
|
||||
"height": "string",
|
||||
"maxWidth": "string",
|
||||
"minHeight": "string"
|
||||
},
|
||||
"responsive": {
|
||||
"_comment": "ONLY properties that CHANGE at each breakpoint - NO repetition",
|
||||
"sm": {
|
||||
"grid-template-columns": "1fr",
|
||||
"padding": "{spacing.4}"
|
||||
},
|
||||
"md": {
|
||||
"grid-template-columns": "repeat(2, 1fr)",
|
||||
"gap": "{spacing.6}"
|
||||
},
|
||||
"lg": {
|
||||
"grid-template-columns": "repeat(3, 1fr)"
|
||||
}
|
||||
},
|
||||
"children": [
|
||||
{
|
||||
"_comment": "Recursive structure - same fields as parent",
|
||||
"tag": "string",
|
||||
"attributes": {},
|
||||
"layout": {},
|
||||
"responsive": {},
|
||||
"children": [],
|
||||
"content": "string or {{placeholder}}"
|
||||
}
|
||||
],
|
||||
"content": "string - text content or {{placeholder}} for dynamic content"
|
||||
},
|
||||
|
||||
"accessibility": {
|
||||
"patterns": [
|
||||
"string - ARIA patterns used (e.g., WAI-ARIA Tabs pattern, Dialog pattern)"
|
||||
],
|
||||
"keyboard_navigation": [
|
||||
"string - keyboard shortcuts (e.g., Tab/Shift+Tab navigation, Escape to close)"
|
||||
],
|
||||
"focus_management": "string - focus trap strategy, initial focus target",
|
||||
"screen_reader_notes": [
|
||||
"string - screen reader announcements (e.g., Dialog opened, Tab selected)"
|
||||
]
|
||||
},
|
||||
|
||||
"usage_guide": {
|
||||
"common_sizes": {
|
||||
"small": {
|
||||
"dimensions": "string - e.g., px-3 py-1.5 (height: ~32px)",
|
||||
"use_case": "string - Compact UI, mobile views"
|
||||
},
|
||||
"medium": {
|
||||
"dimensions": "string - e.g., px-4 py-2 (height: ~40px)",
|
||||
"use_case": "string - Default size for most contexts"
|
||||
},
|
||||
"large": {
|
||||
"dimensions": "string - e.g., px-6 py-3 (height: ~48px)",
|
||||
"use_case": "string - Prominent CTAs, hero sections"
|
||||
}
|
||||
},
|
||||
"variant_recommendations": {
|
||||
"variant_name": {
|
||||
"description": "string - when to use this variant",
|
||||
"typical_actions": ["string - action examples"]
|
||||
}
|
||||
},
|
||||
"usage_context": [
|
||||
"string - typical usage scenarios (e.g., Landing page hero, Product listing grid)"
|
||||
],
|
||||
"accessibility_tips": [
|
||||
"string - accessibility best practices (e.g., Ensure heading hierarchy, Add aria-label)"
|
||||
]
|
||||
},
|
||||
|
||||
"extraction_metadata": {
|
||||
"source": "code-import|explore|text",
|
||||
"created": "ISO timestamp",
|
||||
"code_snippets": [
|
||||
{
|
||||
"component_name": "string - which layout component",
|
||||
"source_file": "string - absolute path",
|
||||
"line_start": "number",
|
||||
"line_end": "number",
|
||||
"snippet": "string - complete HTML/CSS/JS code block",
|
||||
"context_type": "html-structure|css-utility|react-component|vue-component|etc"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
|
||||
"_field_rules": {
|
||||
"schema": "$schema MUST reference W3C Design Tokens format specification",
|
||||
"semantic_tags": "structure.tag MUST use semantic HTML5 tags (header, nav, main, section, article, aside, footer)",
|
||||
"aria": "structure.attributes MUST include ARIA attributes where applicable (role, aria-label, aria-describedby)",
|
||||
"token_refs": "structure.layout MUST use {token.path} syntax for all spacing values",
|
||||
"no_visual": "structure.layout MUST NOT include visual styling (colors, fonts, shadows - those belong in design-tokens)",
|
||||
"layout_only": "structure.layout contains ONLY layout properties (display, grid, flex, position, spacing)",
|
||||
"breakpoints": "structure.responsive MUST define breakpoint-specific overrides matching breakpoint tokens",
|
||||
"no_repetition": "structure.responsive uses ONLY the properties that change at each breakpoint (no repetition)",
|
||||
"recursive": "structure.children inherits same structure recursively for nested elements",
|
||||
"component_type": "component_type MUST be 'universal' or 'specialized'",
|
||||
"accessibility": "accessibility MUST include patterns, keyboard_navigation, focus_management, screen_reader_notes",
|
||||
"usage_guide_universal": "usage_guide REQUIRED for universal components (buttons, inputs, forms, cards, navigation, etc.)",
|
||||
"usage_guide_specialized": "usage_guide OPTIONAL for specialized components (can be simplified or omitted)",
|
||||
"code_snippets": "extraction_metadata.code_snippets ONLY present in Code Import mode"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user