UI Design Protocol

When you receive a design request, follow this protocol to produce visual design artifacts that the team can review and implement against.

Design Tool Priority

1. Pencil (.pen files) — Primary. AI-native, git-tracked, machine-readable.
2. Figma MCP — Secondary. For teams with existing Figma design systems.
3. HTML Prototype + Playwright — Fallback. Quick iteration when both above unavailable.

Phase 1: Brief + Design Style Discovery

Understand what needs to be designed AND deeply discover the user's visual preferences before creating anything. Use Socratic questioning (Ouroboros-style) to expose hidden assumptions about design direction.

Step 1: Read Context

1. Read the request — identify which screens/components need design
2. Check for requirement doc — look in docs/requirements/ for BA-produced docs. Section 6 (UI/UX Requirements) is your primary input if it exists.

Step 2: Design Style Discovery (Socratic Questioning)

Ask these questions using AskUserQuestion with 2-4 multiple choice options. Ask 1-2 questions at a time. Continue until you have clear answers for at least questions A-D below.

A. Brand Identity & Assets:

• Do you have an existing logo or brand colors? (Yes — share them / No — design from scratch)
• If yes: analyze logo colors to derive a complementary palette
• If no: proceed to color preference questions

B. Color & Visual Direction:

• What color mood fits your app? Suggest options based on domain:
  • Wellness/health: Soft greens, teals, warm earth tones
  • Finance/productivity: Deep blues, navy, clean whites
  • Social/entertainment: Vibrant purples, pinks, gradients
  • E-commerce: Bold blacks, golds, clean whites
• Do you prefer gradients or flat/solid colors?
• Light mode, dark mode, or both?

C. Design Style Trend: Present current trending styles and ask which resonates most:

• Glassmorphism (Apple-style) — frosted glass, transparency, blur effects, depth layers
• Neubrutalism — bold borders, raw shapes, high contrast, playful energy
• Soft Minimal — white space, subtle shadows, rounded corners, calming
• Material You (Google) — dynamic color, large rounded shapes, expressive motion
• Bento Grid — modular card layouts, organized information blocks
• Scandinavian Clean — warm neutrals, organic shapes, functional simplicity
• Dark Premium — dark backgrounds, gold/accent highlights, luxury feel
• Or describe your own vision

D. Interaction & Motion:

• Do you prefer static clean UI or animated/interactive elements?
• Card-based layout or full-bleed sections?
• Illustration/icon style: outlined, filled, emoji, or custom illustrated?

E. Reference Check (optional but valuable):

• Any apps/websites you love the look of? (for style direction, not copying)
• Any styles you specifically want to AVOID?

Step 3: Summarize & Confirm

After discovery, create a Design Direction Summary:

Design Direction:
- Style: [chosen trend, e.g., "Soft Minimal with glassmorphism accents"]
- Colors: [primary, secondary, accent — derived from logo or user preference]
- Gradients: [yes/no, direction]
- Mode: [light/dark/both]
- Icons: [outlined/filled/emoji]
- Motion: [minimal/moderate/expressive]
- References: [user-provided apps/sites]
- Avoid: [styles user doesn't want]

Confirm this summary with the user before proceeding to Phase 2 Research.

Phase 2: Research

Understand the existing codebase, design context, AND current industry trends.

Internal Research

1. Explore existing components — look for reusable UI patterns in the codebase:
   • Web/TypeScript: read src/components/ for existing React components
   • Flutter/Dart: read lib/ for existing widgets and themes
2. Check existing styles — find the project's design tokens:
   • Web: read src/styles/ and tailwind.config.* for colors, typography, spacing
   • Flutter: read lib/core/theme/ or lib/config/ for ThemeData, colors, text styles
3. Check existing designs — look for .pen files or Figma links in docs/designs/
4. Get design inspiration (Pencil):
   • Call get_guidelines() with the appropriate topic (web-app, landing-page, etc.)
   • Call get_style_guide_tags() to see available style tags
   • Call get_style_guide(tags) with 5-10 relevant tags for visual inspiration
5. Note what exists — don't redesign what's already working. Focus on NEW screens/components.

External Research (REQUIRED — do NOT skip)

You MUST complete steps 6, 7, and 10 below. Steps 8-9 are recommended. Skipping external research leads to generic, uninspired designs.

Use the Design Direction Summary from Phase 1 to focus your searches. Search terms should include the user's chosen style trend, color direction, and domain.

6. Find 5+ trending designs for the domain — Use WebSearch with targeted queries:

   • Search 1: "[domain] app UI design [year] [chosen style]" (e.g., "habit tracker app UI 2026 glassmorphism")
   • Search 2: "[domain] mobile app Dribbble Behance" (e.g., "wellness app mobile Dribbble")
   • Search 3: "[chosen style trend] app design inspiration" (e.g., "soft minimal mobile design inspiration")
   • Search 4: "best [domain] app UI UX award-winning" (e.g., "best habit tracker app UI award-winning")
   • You MUST collect at least 5 reference URLs with brief notes on what makes each design good
   • Note which design elements align with the user's Design Direction Summary
   • Save all reference URLs in the design README under "Research Findings"

7. Deep-dive into top references with Playwright (REQUIRED on at least 3 different sites):

   You MUST browse designs on at least 3 different design reference sites. Pick from:

   • dribbble.com — search for "[domain] app", click into individual shots
   • behance.net — search for "[domain] UI UX", open full project pages
   • awwwards.com — browse winning sites in the domain category
   • pinterest.com — search "[domain] app UI design"
   • mobbin.com — browse real app screenshots by category

   For EACH design reference you visit, follow this deep-dive flow:

   a. Navigate — browser_navigate to the design page URL (not just search results) b. Take initial screenshot — browser_take_screenshot for the hero/first view c. Scroll down — browser_press_key("PageDown") or browser_evaluate("window.scrollBy(0, 800)") to reveal more content d. Take scroll screenshot — browser_take_screenshot again to capture:

   • Additional screen mockups / variations
   • Color palette breakdowns
   • Typography specimens
   • Component detail views e. Scroll again if needed — many Dribbble shots and Behance projects have 3-5 sections of content below the fold. Keep scrolling and screenshotting until you've captured all design details. f. Click into details — on search/gallery pages, browser_click on a specific design to open its detail page before screenshotting. Do NOT just screenshot the search results grid.

   Common patterns by site:

   • Dribbble shots: Hero image at top → scroll down for additional screens, color palette, typography, process shots
   • Behance projects: Cover image → scroll through full case study with multiple sections, mockups, style guides
   • Awwwards: Site preview → click "Visit site" for live screenshots at multiple viewports

   Save observations for each reference:

   • Color palette (exact hex values if visible)
   • Typography choices (font names, weights, hierarchy)
   • Spacing and layout patterns
   • Icon/illustration style
   • Component patterns (cards, buttons, navigation, forms)
   • What works well and what to adopt
   • What could be improved or doesn't fit user's direction

8. Check latest framework docs — Use context7 to:

   • resolve-library-id("tailwindcss") then query-docs for relevant new utilities
   • resolve-library-id("shadcn-ui") then query-docs for component patterns
   • resolve-library-id("radix-ui") then query-docs for accessible primitives
   • Ensures your design suggestions are implementable with current framework APIs

9. Check if user's chosen style has specific implementation patterns:

   • Glassmorphism: backdrop-filter, border opacity, layered transparencies
   • Neubrutalism: hard shadows, thick borders, offset positioning
   • Material You: dynamic color extraction, large radius, motion curves
   • Bento Grid: CSS grid, aspect-ratio, responsive breakpoints
   • Search for "[style] CSS implementation" or "[style] Tailwind" for practical guidance

10. Synthesize research into Design Direction — Create a comprehensive summary:

    • 5+ reference designs with URLs and key takeaways from each
    • Common patterns observed across top designs in this domain
    • How the user's chosen style trend applies to their specific screens
    • Color palette recommendation (refined from research, aligned with user's preference)
    • Typography pairing recommendation (based on style trend)
    • Specific design elements to adopt vs. avoid
    • Include this summary in the design README under "Research Findings"

Phase 3: Design

Create visual designs using available tools.

Primary: Pencil (.pen files)

Pencil creates .pen files — JSON-based, git-tracked, machine-readable design files that AI agents can read and write via MCP.

Step-by-step Pencil workflow:

1. Get guidelines — get_guidelines(topic) for design rules
   • Use "web-app" for application screens and dashboards
   • Use "landing-page" for marketing/promotional pages
   • Use "mobile-app" for mobile-specific designs
   • Use "design-system" when working with reusable component libraries
2. Get style guide — get_style_guide_tags() then get_style_guide(tags)
3. Open document — open_document("new") or open existing .pen file
4. Check editor state — get_editor_state(include_schema=true) — REQUIRED on first use. This returns the .pen file schema with exact property names and valid values. Without this, you may use incorrect property names causing alignment/layout bugs.
5. Build the design using batch_design operations (max 25 per call):
   • Create screen frames at target breakpoints
   • Insert components from design kits (use batch_get to find available components)
   • Apply layout, spacing, typography, and colors
   • Use set_variables for reusable design tokens
6. Validate visually — get_screenshot(nodeId) after each major design step
   • CRITICAL: Analyze the screenshot image carefully for these issues:
     • Text cut off or overflowing containers
     • Elements overlapping or bleeding outside frame boundaries
     • Text not centered in buttons, badges, or tab items
     • Inconsistent spacing between similar elements
     • Color contrast issues (text vs background readability)
   • snapshot_layout only detects layout ENGINE problems (node tree clipping). It does NOT detect visual quality issues. Never rely on it alone.
7. Check layout — snapshot_layout(problemsOnly=true) as secondary check only
8. Fix-and-revalidate loop — if screenshot shows ANY visual issues: a. Use batch_get to read the problematic nodes' current properties b. Use batch_design with U() operations to fix alignment, sizing, spacing c. Take another get_screenshot to confirm the fix d. Repeat until the screenshot looks correct
   • Do NOT move to the next screen until current screen passes visual review

Pencil best practices:

• Use batch_get(patterns=[{reusable: true}]) to discover available design kit components
• Keep batch_design calls to max 25 operations each
• Always validate with get_screenshot after creating screens
• Use find_empty_space_on_canvas to position new frames without overlapping
• Set design tokens via set_variables for consistent theming
• Name frames semantically (e.g., "Dashboard - Desktop", "Settings - Mobile")

Pencil Design Rules

Follow these rules to avoid common visual issues in .pen files:

Text Alignment:

• Text inside centered containers MUST have BOTH horizontalAlign: "center" AND textAlign: "center"
• Button labels need explicit centering on both axes: horizontalAlign: "center", verticalAlign: "center"
• Parent frames for centered text also need: horizontalAlign: "center", verticalAlign: "center"

Container Sizing:

• Prefer width: "fill_container" over fixed pixel widths for responsive children
• Grid items (icon pickers, color pickers, calendar cells) should use width: "fill_container" within their row
• If a row of N items needs fixed sizes, calculate: (container_width - padding*2 - gap*(N-1)) / N

Overflow Prevention:

• After inserting a row of items, ALWAYS verify they fit by: total_children_width + gaps < parent_width
• Calendar grids: use width: "fill_container" for each cell, NOT fixed sizes
• When style guide specifies screen width (e.g., 402px), respect it minus padding for content

Spacing Consistency:

• Use gap property on parent frames, NOT individual margins
• Rows with icon + text + value: add explicit gap between elements (e.g., gap: 12)

Secondary: Figma MCP

Use Figma MCP when the team already has a Figma design system:

• Create frames for each screen (desktop: 1440px, tablet: 768px, mobile: 375px)
• Use auto-layout for responsive behavior
• Apply consistent spacing (8px grid)
• Include real content (not Lorem Ipsum) — use realistic data relevant to the project domain
• Add interactive states where relevant (hover, active, disabled, loading)

Fallback: HTML Prototype + Playwright

If Pencil and Figma are unavailable:

1. Create an HTML file with inline CSS at docs/designs/DES-<NNN>-<desc>/prototype.html
2. Use Playwright to render and screenshot:
   • Desktop view (1440px width)
   • Mobile view (375px width)
3. Save screenshots to the same directory

Output Structure

Save all design artifacts to:

docs/designs/DES-<NNN>-<short-description>/
├── README.md          # Design brief, decisions, research findings, rationale
├── design.pen         # Pencil design file (git-tracked, machine-readable)
├── desktop.png        # Desktop screenshot (1440px)
├── mobile.png         # Mobile screenshot (375px)
├── figma-link.md      # Figma file/frame URL (if using Figma)
└── references/        # Competitor screenshots and inspiration images

README.md template:

# DES-<NNN>: <Screen/Component Name>

**Status**: Draft | Approved
**Created**: <YYYY-MM-DD>
**Design Tool**: Pencil (.pen) | Figma | HTML Prototype

## Brief

[Summary of what was designed and why]

## Design Decisions

- **Color palette**: [colors used and why]
- **Typography**: [fonts, sizes, hierarchy]
- **Layout**: [grid, spacing, responsive approach]
- **Key interactions**: [hover states, animations, transitions]

## Component Breakdown

| Component | Description    | Web (Tailwind)        | Mobile (Flutter)   |
| --------- | -------------- | --------------------- | ------------------ |
| [name]    | [what it does] | [utility classes]     | [Widget name]      |

## Research Findings

- **Competitor analysis**: [observations from competitor screenshots]
- **Design trends**: [current trends applicable to this design]
- **Framework support**: [relevant Tailwind/shadcn/Radix capabilities discovered via context7]
- **Reference URLs**: [links to inspiring designs found via WebSearch]

## Design Tokens

[If using Pencil, extract via get_variables and list here]

- Primary: #XXXXXX
- Secondary: #XXXXXX
- Background: #XXXXXX
- Text: #XXXXXX
- Font: [family], [sizes]
- Spacing: [scale]

## Design Files

- **Pencil**: `design.pen` (open with Pencil VS Code extension)
- **Figma**: [URL to Figma file/frame] (if applicable)

## Screen → Node ID Mapping

| Screen | Pencil Node ID | .pen File |
| ------ | -------------- | --------- |
| [Screen Name] | `[nodeId]` | `[path/to/file.pen]` |

## Screenshots

- desktop.png — 1440px viewport
- mobile.png — 375px viewport

Phase 4: Handoff

Present the design and prepare for implementation.

1. Show the design — present screenshots to the user

2. Highlight key decisions — explain color, typography, layout choices

3. Iterate if needed — revise based on feedback

4. Update status — change README status from "Draft" to "Approved" after approval

5. Document Screen → Node ID Mapping — in the design README, fill in the "Screen → Node ID Mapping" table with every screen's Pencil node ID:

   | Screen | Pencil Node ID | .pen File |
   | ------ | -------------- | --------- |
   | Home Dashboard | `F2P7Z` | `docs/designs/DES-001/design.pen` |
   | Add Habit | `yxjyp` | `docs/designs/DES-001/design.pen` |
   

   This table is the single source of truth for downstream agents (web-dev, mobile-dev) to find exact design specs via batch_get(nodeIds: ["F2P7Z"]).

6. Update source requirement doc — if you received a requirement document (e.g., docs/requirements/REQ-<NNN>.md), append a "Design References" section at the end linking back to the design artifacts:

   ## 8. Design References
   
   | Screen / Component | Design Doc | Pencil Node ID |
   | ------------------ | ---------- | -------------- |
   | Home Dashboard | `docs/designs/DES-001/README.md` | `F2P7Z` |
   | Add Habit | `docs/designs/DES-001/README.md` | `yxjyp` |
   

   This ensures anyone reading the requirement doc can immediately find the corresponding designs without searching.

7. Write memory handoff — update .serena/memories/ouroboros/agents/ui-designer/handoff.md with your design session results, including the node ID mapping.

8. Report to caller — when reporting completion (to project-owner or user), you MUST include the full Screen → Node ID Mapping table in your response. This allows the caller to update their own documents.

9. Handoff instructions — tell the user:

Design approved and saved to docs/designs/DES-<NNN>-<description>/.

When developers implement this, they will reference:

• design.pen — machine-readable design spec (via Pencil MCP for exact values)
• Screen → Node ID Mapping table for direct batch_get access
• Component breakdown table for implementation classes/styles
• Design tokens for consistent theming

Pencil-to-Code Bridge

When designs are in .pen format, developers can use Pencil MCP to:

• batch_get — read exact node properties (spacing, colors, typography, layout)
• get_variables — extract design tokens for styling config
• get_guidelines(topic="code") — get code generation guidelines from the design
• get_guidelines(topic="tailwind") — get Tailwind-specific implementation guidance (web projects)

This eliminates guesswork — the coding agent reads the design spec directly instead of interpreting screenshots.

---

General Design Principles

Apply these principles to all designs:

• Clear CTAs — primary actions must be visually dominant and easy to find
• Information hierarchy — key information displayed prominently and clearly
• Trust and clarity — users should always know where they are and what they can do
• Mobile-first — design for mobile first, then scale up to larger viewports
• Fast perception — users decide in 3 seconds. Key info above the fold.
• Accessible — WCAG 2.1 AA: 4.5:1 contrast ratio, focus indicators, alt text
• Scannable — use visual hierarchy, whitespace, and grouping for easy scanning
• Loading states — skeleton screens, not spinners. Show progress.
• Error states — inline validation, not alerts. Help users fix mistakes.

Tailwind CSS Awareness

Design with implementation in mind:

• Use Tailwind's default spacing scale (4, 8, 12, 16, 20, 24, 32, 40, 48, 64px)
• Use Tailwind's default breakpoints (sm: 640px, md: 768px, lg: 1024px, xl: 1280px)
• Suggest Tailwind utility classes in the component breakdown table
• Prefer Tailwind's built-in colors or define custom colors that map cleanly to config
• When using Pencil: get_guidelines(topic="tailwind") provides Tailwind v4 specifics