ctx-cc 2.2.0 → 2.3.0

package/templates/BRAND_KIT.md

@@ -0,0 +1,265 @@
+# Brand Kit - {{project_name}}
+
+**Created:** {{timestamp}}
+**Approved:** {{approval_date}}
+**Version:** 1.0
+**Token Format:** W3C Design Tokens (DTCG)
+
+---
+
+## Brand Essence
+
+### Mission
+{{mission_statement}}
+
+### Personality
+{{personality_adjectives}}
+
+### Target Audience
+{{target_audience}}
+
+### Visual Mood
+{{visual_mood_description}}
+
+---
+
+## Token Architecture
+
+### Three-Tier Structure
+```
+tokens/
+├── primitive.tokens.json   # Raw values (colors, sizes)
+├── semantic.tokens.json    # Purpose-based aliases + modes
+└── component.tokens.json   # Component-specific tokens
+```
+
+### Mode Support
+- Light mode (default)
+- Dark mode
+{{additional_modes}}
+
+---
+
+## Color System
+
+### Primitive Colors
+| Token | Light Mode | Dark Mode |
+|-------|------------|-----------|
+| gray-50 | #FAFAFA | #171717 |
+| gray-100 | #F4F4F5 | #27272A |
+| gray-200 | #E4E4E7 | #3F3F46 |
+| gray-300 | #D4D4D8 | #52525B |
+| gray-400 | #A1A1AA | #71717A |
+| gray-500 | #71717A | #A1A1AA |
+| gray-600 | #52525B | #D4D4D8 |
+| gray-700 | #3F3F46 | #E4E4E7 |
+| gray-800 | #27272A | #F4F4F5 |
+| gray-900 | #18181B | #FAFAFA |
+| {{primary_color_name}} | {{primary_light}} | {{primary_dark}} |
+
+### Semantic Colors
+| Token | References | Usage |
+|-------|------------|-------|
+| background-primary | {gray-50} | Page backgrounds |
+| background-surface | {gray-100} | Cards, modals |
+| text-primary | {gray-900} | Body text |
+| text-secondary | {gray-600} | Captions, hints |
+| interactive | {{{primary_color}}} | CTAs, links |
+| interactive-hover | {{{primary_hover}}} | Hover states |
+
+### State Colors
+| State | Color | Hex |
+|-------|-------|-----|
+| success | green-500 | #22C55E |
+| warning | amber-500 | #F59E0B |
+| error | red-500 | #EF4444 |
+| info | blue-500 | #3B82F6 |
+
+### Accessibility Compliance
+| Combination | Ratio | WCAG 2.2 |
+|-------------|-------|----------|
+| text-primary on background | {{ratio_1}} | AA Pass |
+| text-secondary on background | {{ratio_2}} | AA Pass |
+| interactive on background | {{ratio_3}} | AA Pass |
+
+---
+
+## Typography
+
+### Font Stack
+| Role | Font Family | Fallback |
+|------|-------------|----------|
+| Heading | {{heading_font}} | system-ui, sans-serif |
+| Body | {{body_font}} | system-ui, sans-serif |
+| Mono | {{mono_font}} | ui-monospace, monospace |
+
+### Type Scale (Desktop)
+| Level | Size | Line Height | Weight | Letter Spacing |
+|-------|------|-------------|--------|----------------|
+| display | 48px | 1.1 | 700 | -0.02em |
+| h1 | 36px | 1.2 | 600 | -0.01em |
+| h2 | 28px | 1.3 | 600 | 0 |
+| h3 | 22px | 1.4 | 500 | 0 |
+| body-lg | 18px | 1.6 | 400 | 0 |
+| body | 16px | 1.5 | 400 | 0 |
+| body-sm | 14px | 1.5 | 400 | 0 |
+| caption | 12px | 1.4 | 400 | 0.01em |
+
+### Responsive Scale
+| Level | Mobile | Tablet | Desktop |
+|-------|--------|--------|---------|
+| display | 32px | 40px | 48px |
+| h1 | 28px | 32px | 36px |
+| h2 | 22px | 24px | 28px |
+
+---
+
+## Spacing & Layout
+
+### Base Scale (4px grid)
+| Token | Value | Usage |
+|-------|-------|-------|
+| space-0 | 0px | Reset |
+| space-1 | 4px | Tight inline |
+| space-2 | 8px | Related elements |
+| space-3 | 12px | Form gaps |
+| space-4 | 16px | Default gap |
+| space-6 | 24px | Section padding |
+| space-8 | 32px | Card padding |
+| space-12 | 48px | Section gaps |
+| space-16 | 64px | Page sections |
+| space-24 | 96px | Hero spacing |
+
+### Border Radius
+| Token | Value | Usage |
+|-------|-------|-------|
+| radius-sm | 4px | Small elements |
+| radius-md | 8px | Default |
+| radius-lg | 12px | Cards |
+| radius-full | 9999px | Pills, avatars |
+
+### Breakpoints
+| Token | Value | Target |
+|-------|-------|--------|
+| breakpoint-sm | 640px | Mobile landscape |
+| breakpoint-md | 768px | Tablet |
+| breakpoint-lg | 1024px | Desktop |
+| breakpoint-xl | 1280px | Large desktop |
+
+---
+
+## Motion
+
+### Duration
+| Token | Value | Usage |
+|-------|-------|-------|
+| duration-instant | 0ms | No animation |
+| duration-fast | 100ms | Micro-interactions |
+| duration-normal | 200ms | Standard transitions |
+| duration-slow | 300ms | Emphasis |
+| duration-slower | 500ms | Page transitions |
+
+### Easing
+| Token | Value | Usage |
+|-------|-------|-------|
+| ease-linear | linear | Progress bars |
+| ease-in | cubic-bezier(0.4, 0, 1, 1) | Exit animations |
+| ease-out | cubic-bezier(0, 0, 0.2, 1) | Enter animations |
+| ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) | Standard |
+| ease-bounce | cubic-bezier(0.34, 1.56, 0.64, 1) | Playful |
+
+### Common Animations
+| Token | Duration | Easing | Usage |
+|-------|----------|--------|-------|
+| transition-colors | 150ms | ease-out | Hover states |
+| transition-transform | 200ms | ease-out | Scale/move |
+| transition-opacity | 200ms | ease-in-out | Fade |
+| transition-all | 200ms | ease-in-out | Complex |
+
+---
+
+## Accessibility Requirements
+
+### WCAG 2.2 Level AA (Required)
+- [x] 1.4.3 Contrast (Minimum) - 4.5:1 text
+- [x] 1.4.11 Non-text Contrast - 3:1 UI components
+- [x] 2.4.11 Focus Not Obscured (Minimum)
+- [x] 2.5.7 Dragging Movements - alternatives provided
+- [x] 2.5.8 Target Size (Minimum) - 24x24px minimum
+- [x] 3.3.8 Accessible Authentication (Minimum)
+
+### EAA 2025 Compliance (EU Markets)
+European Accessibility Act enforcement: June 28, 2025
+- All WCAG 2.2 AA criteria
+- EN 301 549 v3.2.1 alignment
+
+---
+
+## Visual Guidelines
+
+### Do's
+- Use semantic tokens, not primitives, in components
+- Maintain 4px grid alignment
+- Test all color combinations for contrast
+- Provide alternatives to dragging interactions
+- Ensure 24x24px minimum touch targets
+- Use focus-visible for keyboard focus states
+
+### Don'ts
+- Don't use color alone to convey information
+- Don't use hardcoded values (use tokens)
+- Don't skip focus states
+- Don't obscure focused elements with overlays
+- Don't require cognitive function tests for auth
+- Don't disable paste in password fields
+
+---
+
+## Asset Locations
+
+```
+project/
+├── BRAND_KIT.md              # This document
+├── tokens/
+│   ├── primitive.tokens.json # Raw values
+│   ├── semantic.tokens.json  # Semantic + modes
+│   └── component.tokens.json # Component tokens
+├── brand-assets/
+│   ├── tokens.css            # CSS custom properties
+│   ├── tokens.scss           # SCSS variables
+│   ├── tokens.js             # JS constants
+│   ├── tailwind.config.js    # Tailwind theme
+│   └── style-dictionary.config.json
+├── design-references/
+│   └── [screenshots]
+└── logo/
+    ├── logo-primary.svg
+    ├── logo-light.svg
+    └── logo-dark.svg
+```
+
+---
+
+## Export Commands
+
+```bash
+# Using Style Dictionary
+npx style-dictionary build --config style-dictionary.config.json
+
+# Or run /ctx with design token update
+```
+
+---
+
+## Approval History
+
+| Date | Approved By | Notes |
+|------|-------------|-------|
+| {{mood_board_date}} | {{user}} | Mood board approved |
+| {{direction_date}} | {{user}} | Direction selected: Option {{option}} |
+| {{final_date}} | {{user}} | Final brand kit approved |
+
+---
+
+**This document is the source of truth for all visual decisions.**
+**All design work MUST reference this kit.**

package/templates/DESIGN_BRIEF.md

@@ -0,0 +1,163 @@
+# Design Brief - {{component_name}}
+
+## Component: {{component_name}}
+**Story:** {{story_id}}
+**Created:** {{timestamp}}
+**Approved:** {{approval_date}}
+**WCAG Level:** 2.2 AA
+**EAA 2025:** {{eaa_compliant}}
+
+---
+
+## Visual Direction
+
+### Brand Reference
+- Brand Kit: BRAND_KIT.md v{{brand_version}}
+- Mood board: .ctx/phases/{{story_id}}/MOOD_BOARD.md
+- Selected: Option {{selected_option}} {{modifications}}
+
+### Design Constraints
+| Constraint | Value |
+|------------|-------|
+| Primary Colors | {{color_palette}} |
+| Typography | {{typography}} |
+| Spacing | {{spacing_tokens}} |
+| Border Radius | {{radius_tokens}} |
+
+---
+
+## Design Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Layout | {{layout_choice}} | {{layout_why}} |
+| Colors | {{color_choice}} | {{color_why}} |
+| Typography | {{type_choice}} | {{type_why}} |
+| Spacing | {{spacing_choice}} | {{spacing_why}} |
+| Motion | {{motion_choice}} | {{motion_why}} |
+
+---
+
+## Component States
+
+| State | Description | Visual Treatment |
+|-------|-------------|------------------|
+| Default | Normal state | {{default_treatment}} |
+| Hover | Mouse over | {{hover_treatment}} |
+| Focus | Keyboard focus | {{focus_treatment}} |
+| Active | Being pressed | {{active_treatment}} |
+| Disabled | Not interactive | {{disabled_treatment}} |
+| Loading | Async operation | {{loading_treatment}} |
+| Error | Invalid state | {{error_treatment}} |
+
+---
+
+## Responsive Behavior
+
+| Breakpoint | Width | Behavior |
+|------------|-------|----------|
+| Mobile | < 768px | {{mobile_behavior}} |
+| Tablet | 768-1024px | {{tablet_behavior}} |
+| Desktop | > 1024px | {{desktop_behavior}} |
+
+---
+
+## Accessibility Implementation
+
+### WCAG 2.2 Compliance
+
+| Criterion | Requirement | Implementation |
+|-----------|-------------|----------------|
+| 2.4.7 Focus Visible | Focus indicator visible | {{focus_impl}} |
+| 2.4.11 Focus Not Obscured | Focused element visible | {{obscured_impl}} |
+| 2.5.7 Dragging | Click alternative | {{drag_impl}} |
+| 2.5.8 Target Size | 24x24px minimum | {{target_impl}} |
+| 3.3.8 Authentication | No cognitive tests | {{auth_impl}} |
+
+### Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Tab | {{tab_action}} |
+| Enter | {{enter_action}} |
+| Space | {{space_action}} |
+| Escape | {{escape_action}} |
+| Arrow Keys | {{arrow_action}} |
+
+### Screen Reader
+
+| Element | ARIA | Announcement |
+|---------|------|--------------|
+| {{element_1}} | {{aria_1}} | {{announce_1}} |
+| {{element_2}} | {{aria_2}} | {{announce_2}} |
+
+---
+
+## Approval History
+
+| Stage | Date | Approved | Notes |
+|-------|------|----------|-------|
+| Mood board | {{mood_date}} | {{mood_approved}} | {{mood_notes}} |
+| Direction (A/B/C) | {{dir_date}} | Option {{dir_choice}} | {{dir_notes}} |
+| Prototype | {{proto_date}} | {{proto_approved}} | {{proto_notes}} |
+| Final | {{final_date}} | {{final_approved}} | {{final_notes}} |
+
+---
+
+## Implementation Files
+
+| Artifact | Path |
+|----------|------|
+| Component | {{component_path}} |
+| Styles | {{styles_path}} |
+| Story | {{story_path}} |
+| Tests | {{tests_path}} |
+
+---
+
+## Figma Reference
+
+{{#if figma_link}}
+- File: {{figma_link}}
+- Node: {{figma_node}}
+{{else}}
+No Figma file linked.
+{{/if}}
+
+---
+
+## Screenshots
+
+| Viewport | Screenshot |
+|----------|------------|
+| Mobile | .ctx/phases/{{story_id}}/mobile.png |
+| Tablet | .ctx/phases/{{story_id}}/tablet.png |
+| Desktop | .ctx/phases/{{story_id}}/desktop.png |
+
+---
+
+## Verification Checklist
+
+### Visual
+- [ ] Matches approved prototype
+- [ ] All states implemented
+- [ ] Responsive at all breakpoints
+- [ ] Uses brand tokens (no hardcoded values)
+
+### Accessibility
+- [ ] Focus visible (2px ring, 3:1 contrast)
+- [ ] Target size >= 24x24px
+- [ ] Keyboard navigable
+- [ ] Screen reader tested
+- [ ] No color-only information
+
+### Technical
+- [ ] No console errors
+- [ ] Tests pass
+- [ ] Storybook story created
+- [ ] No TODO comments
+
+---
+
+**This brief documents all design decisions for {{component_name}}.**
+**Any deviations require approval update.**

package/templates/PRD.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://ctx.dev/schemas/prd.json",
-  "version": "2.0",
+  "version": "2.1",
   "project": {
     "name": "{{project_name}}",
     "description": "{{project_description}}",
@@ -22,6 +22,28 @@
       "{{risk_1}}"
     ]
   },
+  "brand": {
+    "hasBrandKit": false,
+    "personality": [],
+    "visualMood": "",
+    "inspirations": [],
+    "antiInspirations": [],
+    "existingAssets": [],
+    "darkModeRequired": false,
+    "euMarket": false
+  },
+  "design": {
+    "wcagLevel": "AA",
+    "eaaCompliance": false,
+    "tokenFormat": "w3c",
+    "figmaFileKey": null,
+    "designSystem": null,
+    "breakpoints": {
+      "mobile": 375,
+      "tablet": 768,
+      "desktop": 1440
+    }
+  },
   "constitution": {
     "principles": [
       "Code quality over speed",
@@ -51,9 +73,17 @@
     "requiresAPI": false,
     "notes": "{{testing_notes}}"
   },
+  "storyTypes": {
+    "feature": "Standard implementation story",
+    "brand": "Brand kit establishment (BRAND_KIT.md + tokens)",
+    "design": "UI component/page design with approval gates",
+    "fix": "Bug fix or correction",
+    "refactor": "Code improvement without behavior change"
+  },
   "stories": [
     {
       "id": "S001",
+      "type": "feature",
       "title": "{{story_title}}",
       "description": "{{story_description}}",
       "acceptanceCriteria": [
@@ -65,7 +95,8 @@
       "phase": 1,
       "passes": false,
       "verifiedAt": null,
-      "notes": ""
+      "notes": "",
+      "design": null
     }
   ],
   "metadata": {