ux-brief

name	ux-brief
description	Create junior-dev-ready design systems through guided discovery before implementation
allowed-tools	Read Write Edit Grep Glob WebSearch WebFetch AskUserQuestion Task Skill
argument-hint	[component, page, or feature to design]

Design System Generator

Create comprehensive, junior-dev-ready design system documents through guided discovery.

Design Target

<design_target> $ARGUMENTS </design_target>

If empty, ask: "What would you like to design? Describe the component, page, or feature."

Phase 0: Interview Option (Optional)

For complex features where requirements are unclear, offer a deep interview first:

AskUserQuestion: "This design could benefit from a requirements interview to clarify goals and constraints. Would you like to explore it in depth first?"
Options:
- "Yes, interview me first" → Skill(skill: "majestic-tools:workflows:interview", args: "[design target]"), then use refined output
- "No, proceed to design discovery" → Continue to Phase 1

When to suggest interview:

• Design target is vague (e.g., "dashboard", "admin panel")
• Multiple user types or stakeholders involved
• Business goals not clearly stated
• User seems uncertain about what they want

Skip interview suggestion for:

• Specific components with clear scope (e.g., "login form", "settings page")
• When user has existing specs/mockups
• Iteration on existing designs

Phase 1: Context Gathering

Before asking questions, understand the project:

1. Check for existing design tokens (tailwind.config.js, CSS variables)
2. Look at existing UI components for patterns
3. Identify tech stack (React, Vue, Rails/Hotwire, vanilla)
4. Check for style guides or brand documentation

Phase 2: Discovery Questions

Ask questions ONE AT A TIME. Prefer multiple choice when options are bounded.

Question Areas

1. Purpose & Goals - What is this UI trying to achieve?
2. Target Audience - Who will use this interface?
3. Aesthetic Direction - Pick one: Brutalist, Minimalist, Maximalist, Luxury, Playful, Retro-futuristic
4. Typography - Display and body font preferences
5. Color Palette - Primary brand color, light/dark theme, accent strategy
6. Motion & Interaction - Animation intensity (none, subtle, dramatic)
7. Inspiration & References - Sites they admire (Stripe, Linear, Vercel, etc.)
8. Technical Constraints - Browser support, performance, accessibility (WCAG level)
9. Framework (REQUIRED) - Based on tech_stack, suggest:
   • rails → DaisyUI + Tailwind
   • react → Tailwind or styled-components
   • Default → Plain Tailwind

Visual Language Questions (if comprehensive design system needed)

10. Photography style - "What mood should photos convey?"

    • Options: Authentic/candid, Editorial/staged, Abstract/artistic, Product-focused, People-focused

11. Illustration style - "Do you need illustrations? If so, what style?"

    • Options: None needed, Geometric/clean, Organic/hand-drawn, Isometric/3D, Flat/minimal

12. Iconography - "What icon style fits your brand?"

    • Options: Outlined (Heroicons), Filled (solid), Duotone (Phosphor), Custom/branded

Question Guidelines

• ONE question per turn
• Multiple choice preferred
• Skip obvious questions from context
• Summarize every 2-3 questions
• Research references - if user mentions a site, fetch it

Phase 3: Reference Research

When user mentions reference sites:

1. Fetch the site using WebFetch
2. Identify: typography, color palette, layout patterns, animation, unique details
3. Present findings to confirm what resonates

Common References

• Stripe: Clean gradients, depth, premium, documentation excellence
• Linear: Dark themes, minimal, focused, developer-oriented
• Vercel: Typography-forward, confident whitespace
• Notion: Friendly, approachable, illustration-forward
• Raycast: Dark, utility-focused, keyboard-first

Phase 4: Design System Generation

Load the design system template directly:

Read(file_path="references/design-system-template.md")

Then customize it with the user's specific choices:

• Replace all [placeholder] values with actual design decisions
• Fill in color hex values based on palette
• Configure typography choices
• Customize component specifications
• Add project-specific do's and don'ts

Write the completed design system to docs/design/design-system.md.

Design principles applied during generation:

• Junior-dev ready: Document should be so complete that no follow-up questions are needed
• Copy-paste ready: All classes, values, and configs should be directly usable
• Commit to a direction: Avoid wishy-washy "a bit of everything" designs
• Avoid AI slop: No Inter font, no purple gradients, no predictable layouts

Phase 5: Save & Configure

Step 1: Determine Output Path

Check .agents.yml for design_system_path, default to docs/design/design-system.md.

Step 2: Auto-Preview Check

AUTO_PREVIEW = config_read("auto_preview", "false")

If AUTO_PREVIEW is "true": Execute open <design-system-path>

Step 3: Present Options

Use AskUserQuestion:

If NOT auto-previewed:

• Preview in editor
• Start building (Recommended) - Invoke skill frontend-design
• Refine sections
• Research more

If auto-previewed:

• Start building (Recommended)
• Refine sections
• Research more

Integration with Workflow

After completing the design system:

1. Skill("blueprint") - Automatically detects UI features and references design system
2. Skill("build-task") - Loads design system as context
3. visual-validator - Verifies implementation against specifications

Key Principles

• Commit to a direction - Avoid wishy-washy designs
• Avoid AI slop - No Inter font, no purple gradients
• Research references - Actually look at sites users mention
• Be opinionated - Push back on generic choices
• Junior-dev ready - Document so complete no follow-up needed
• Copy-paste ready - All classes and configs directly usable