9thlevelsoftware/legion/design-workflows

Design Workflows

Structured design workflow engine for Legion. Provides domain-specific decomposition for design-focused phases -- design system creation, UX research planning and synthesis, and three-lens design review (brand, accessibility, usability). All operations produce human-readable markdown artifacts at .planning/designs/.

References:

• State File Locations from workflow-common.md (state paths, degradation pattern)
• Design Workflow Conventions from workflow-common.md (lifecycle, paths, wave pattern)
• Design Sprint team assembly from agent-registry.md Section 4 (Research + Architecture + Visual Design + Brand Review + Feedback)
• Phase decomposition from phase-decomposer.md (design domain detection trigger)
• /legion:plan in plan.md (design questioning and document generation entry point)
• /legion:build in build.md (design wave execution with research-to-design handoff)

Section 1: Principles & Design Domain Detection

Core rules governing design workflows and the detection heuristic that determines when design-specific decomposition activates.

Principles

1. Research-informed design -- design decisions should be grounded in user research when available. Wave 1 (research) produces insights that inform Wave 2 (creation). When research is unavailable or out of scope, designers proceed using established heuristics and domain expertise.
2. Human-readable artifacts -- design documents follow the same structured markdown convention as all other Legion state files. No JSON, no binary, no databases. Design tokens and component specs are documented in markdown tables, not design tool files.
3. Graceful degradation -- every consumer checks for design phase signals before applying design patterns. Non-design phases see zero impact. Design documents are never required for non-design workflow completion.
4. Discipline-driven team assembly -- the project's design scope drives which agents are assigned. Not all 6 design agents are needed for every project. A brand refresh may need 2-3 agents; a full design system may need 5-6.
5. Three-lens review -- design review uses three specialized lenses (brand, accessibility, usability) running in parallel, not a single generic reviewer. Each lens has specific criteria and a dedicated agent.
6. Specifications, not mockups -- design documents specify structure, tokens, components, and guidelines. Actual visual creation happens during execution, not during planning.

When Design Workflows Apply

Design-specific decomposition activates when ANY of the canonical triggers below matches — no other triggers. Keyword matches against the phase description are NOT authoritative (they may be used as a non-blocking hint to prompt the user, never as automatic activation).

Canonical triggers (mirror of `workflow-common/SKILL.md` § Design Phase Detection):

1. At least one phase requirement ID matches the regex ^DSN-\d+ in ROADMAP.md or REQUIREMENTS.md
2. The phase's CONTEXT.md YAML frontmatter declares workflow_type: design
3. The user passed --domain=design to /legion:plan

Single source of truth for keywords: .planning/config/intent-teams.yaml under teams.design.keywords[]. Keywords are used only as prompt hints, never for silent activation. When adding a keyword, edit the YAML — do NOT inline keyword lists in this file.

Marketing/design disambiguation (precedence when both triggers fire):

1. If the phase has explicit workflow_type frontmatter: that wins over requirement-ID detection.
2. If --domain= was passed: that wins over frontmatter and requirement IDs.
3. If both ^MKT-\d+ and ^DSN-\d+ requirement IDs are present in the same phase and no frontmatter/flag overrides: run marketing decomposition — phases with both prefixes are marketing-led, with design as a supporting discipline within the marketing wave.

When detected: use design-specific wave patterns (Section 6) and offer design document generation during planning. When not detected: standard phase decomposition applies -- no impact.

Constants

DESIGN_DIR = '.planning/designs'
SYSTEM_FILE_PATTERN = '{DESIGN_DIR}/{project-slug}-system.md'
RESEARCH_FILE_PATTERN = '{DESIGN_DIR}/{research-slug}-research.md'
DESIGN_DISCIPLINES = ['design-systems', 'ux-architecture', 'brand-identity',
                      'user-research', 'visual-storytelling', 'delight-polish']
TOKEN_CATEGORIES = ['color', 'typography', 'spacing', 'elevation', 'border-radius',
                    'animation', 'breakpoint', 'z-index']

Discipline-Agent Mapping

Graceful Degradation

• If .planning/designs/ directory does not exist: create it when the first design document is generated
• If no design document exists for a phase: standard decomposition, no design enrichment
• If design-workflows skill is referenced but phase is not design: skip silently
• Never error, never block, never require design documents for non-design workflow completion

Section 2: Design System Workflow (DSN-01)

Structured design system creation with guided questioning, document generation, agent team assembly, token taxonomy, component architecture, and lifecycle management. This section drives the design system flow triggered by /legion:plan when a design phase is detected.

2.1: Design Brief Questioning

When a design phase is detected during /legion:plan, gather design parameters using AskUserQuestion. This replaces the generic decomposition questioning for design phases.

Key questions (adapt based on responses -- do not ask all if answers imply others):

Q1: "What type of design work does this phase focus on?"
  Options:
  - "Design system / Component library" -- full system with tokens, components, guidelines
  - "UX research / User testing" -- research-focused, insights and recommendations
  - "Brand refresh / Visual identity" -- brand-focused, identity system and guidelines
  - "UI implementation / Screen design" -- applying an existing system to new screens
 
Q2: "What's the scope of the design system?" (only if Q1 = design system)
  Options:
  - "Foundation only (tokens + guidelines)" -- colors, typography, spacing, principles
  - "Foundation + Core components" -- plus buttons, inputs, cards, navigation
  - "Full system (foundation + components + patterns)" -- plus layouts, flows, page templates
 
Q3: "Does this project have existing brand guidelines?"
  Options:
  - "Yes, established brand" -- design must align with existing identity
  - "New brand / No guidelines" -- brand development is part of the work
  - "Partial / Needs refresh" -- some guidelines exist but need updating
 
Q4: "What platforms need to be supported?" (multi-select)
  Options:
  - "Web (responsive)"
  - "Mobile (iOS/Android)"
  - "Desktop application"
  - "Design documentation only"
 
Q5: "What are the key accessibility requirements?"
  Options:
  - "WCAG AA (standard)" -- 4.5:1 contrast, keyboard nav, screen reader support
  - "WCAG AAA (enhanced)" -- 7:1 contrast, extended requirements
  - "Basic compliance" -- minimum viable accessibility

If the user has already provided design details in the phase description or CONTEXT.md, extract answers from existing context rather than re-asking. Only ask for missing parameters.

2.2: Design System Document Generation

After brief questioning, generate the design system document at: {DESIGN_DIR}/{project-slug}-system.md

The slug is derived from the project name: lowercase, spaces to hyphens, strip non-alphanumeric (except hyphens), max 40 characters. Example: "Dashboard Redesign" becomes dashboard-redesign

Use the format from Section 5.1. Populate all sections from the brief answers:

• Design Principles: from project context + brand guidelines
• Token Taxonomy: from Q2 scope + Q5 accessibility + Q4 platforms
• Component Architecture: from Q2 scope level (foundation only, core components, or full system)
• Platform Targets: from Q4
• Accessibility Standard: from Q5
• Agent Assignments: from discipline selection + agent-registry Section 4 Design Sprint team

2.3: Design Team Assembly

For design projects, use the agent-registry Section 4 Design Sprint team assembly pattern:

Required roles (always included):

Discipline-specific roles (based on project scope from Q1-Q3):

• Map each relevant discipline to its primary agent using the Discipline-Agent Mapping table (Section 1)
• If a discipline's primary agent is already assigned as Design Lead or Research Lead, no duplicate -- the agent covers both roles
• Each discipline specialist owns deliverables for their area

Optional roles (add based on project needs):

2.4: Token Taxonomy

Design tokens follow a three-tier hierarchy: Global --> Semantic --> Component.

### Token Structure
 
| Category | Global Token | Semantic Token | Component Token |
|----------|-------------|----------------|-----------------|
| Color | color-blue-500 | color-primary | button-color-bg |
| Typography | font-size-16 | font-size-body | input-font-size |
| Spacing | spacing-16 | spacing-md | card-padding |
| Elevation | shadow-md | shadow-card | dialog-shadow |
| Border Radius | radius-8 | radius-md | button-radius |
| Animation | duration-200 | duration-fast | tooltip-duration |
| Breakpoint | breakpoint-768 | breakpoint-tablet | -- |
| Z-index | z-50 | z-overlay | modal-z-index |
 
Naming convention: {category}-{modifier} for global, {category}-{semantic-name} for semantic, {component}-{property} for component.

2.5: Component Architecture (Atomic Design)

Components follow atomic design hierarchy: Tokens --> Atoms --> Molecules --> Organisms --> Templates.