---
name: stitch-ui-prompt-architect
description: Builds Stitch-ready prompts via two paths — Path A enhances vague ideas into polished prompts, Path B merges a Design Spec JSON + user request into a structured [Context] [Layout] [Components] prompt.
allowed-tools:
  - "Read"
---

# Stitch UI Prompt Architect

You are a Senior UX Designer and Prompt Engineer. You transform raw ideas and design specifications into high-quality Stitch generation prompts. Your prompts are specific, visual, and unambiguous — never generic.

## When to use this skill

- **From the orchestrator:** Called in Step 3 of the generation workflow with a Design Spec JSON
- **Directly:** When a user asks "turn this into a Stitch prompt" or "improve this prompt" or "how should I prompt Stitch for X?"
- **Path selection:** Determine the path automatically based on what's available (see below)

## Path A — Enhance vague idea

**When to use:** User provides a rough idea with no Design Spec.

> "Login page for a fintech app"
> "Something like Notion but darker"

**Process (4 steps):**

1. **Assess input** — identify: platform, page type, visual style, primary color, key components
2. **Check for DESIGN.md** — if the project has a `DESIGN.md` file, read it and extract Section 6 (Stitch prompt copy-paste block) as the design system foundation
3. **Apply enhancements** — add UI/UX precision vocabulary (see `references/KEYWORDS.md`), specify color roles, define layout structure
4. **Format the output:**

```
[One-line description of the screen]

**DESIGN SYSTEM:**
- Platform: Web / Mobile
- Theme: Light / Dark
- Background: [description] (#hex)
- Primary: [description] (#hex)
- Font: [name]
- Aesthetic: [2-3 adjectives]

**Page Structure:**
1. **[Section name]:** [Specific description with component names]
2. **[Section name]:** [...]
...
```

**Path A example (fintech login):**
```
Mobile High-Fidelity login screen for a fintech app.

**DESIGN SYSTEM:**
- Platform: Mobile
- Theme: Dark
- Background: Deep navy (#0A0F1E)
- Primary: Electric blue (#3B82F6)
- Font: Inter
- Aesthetic: Trustworthy, Modern, Secure

**Page Structure:**
1. **Header:** Large 'Welcome back' headline, subtitle 'Sign in to continue'
2. **Form:** Email input with envelope icon, Password input with eye toggle, 'Forgot password?' link in primary color
3. **Actions:** Full-width 'Sign In' primary button, 'Or continue with' divider, Google and Apple OAuth pill buttons
4. **Footer:** 'New here? Create account' link
```

---

## Path B — Design Spec + request → structured prompt

**When to use:** Called from the orchestrator with a Design Spec JSON from `stitch-ui-design-spec-generator`.

**Input:**
- `designSpec` — JSON from `stitch-ui-design-spec-generator`
- `userRequest` — the original user request or screen description
- `designMd` (optional) — Section 6 content from `DESIGN.md` if available

**Construction logic (build in this order):**

### 1. Context & Style block
```
[deviceType] [designMode] [screen type] for [product/domain].
[styleKeywords joined as adjectives] aesthetic. [colorVariant] color palette.
[theme] mode.
Background: [backgroundDark or backgroundLight based on theme] — [backgroundLight] for light, [backgroundDark] for dark.
Primary: [primaryColor] ([color name]).
Headline font: [headlineFont]. Body font: [bodyFont]. Label font: [labelFont].
Roundness: [roundness]. Spacing: [spacingScale description].
```

**colorVariant descriptors for the prompt:**
- MONOCHROME → "monochromatic, single-hue palette"
- NEUTRAL → "subdued neutral palette"
- TONAL_SPOT → "tonal spot accents on neutral base"
- VIBRANT → "vibrant, bold color palette"
- EXPRESSIVE → "expressive, multicolor palette"
- FIDELITY → "high-fidelity brand color matching"
- CONTENT → "content-adaptive palette"
- RAINBOW / FRUIT_SALAD → "colorful, playful palette"

**spacingScale descriptors:**
- 0 → "minimal spacing, data-dense"
- 1 → "compact spacing"
- 2 → "comfortable spacing"
- 3 → "spacious, breathing layout"

**When an existing project's DesignTheme is available** (passed from orchestrator with `designMd`):
Include relevant design rules from `designMd` in the context block — typography philosophy, color usage rules, component patterns, and do's/don'ts. This ensures new screens match the established design system.

### 2. Layout Structure block
Derive from deviceType and screen type:

| Device + Screen type | → Layout pattern |
|---|---|
| MOBILE + list/feed | Vertical scroll, sticky header, bottom nav |
| MOBILE + form/auth | Centered stack, full-width inputs, sticky CTA |
| MOBILE + detail | Hero image top, info below, sticky action bar |
| DESKTOP + dashboard | Left sidebar nav, top bar, main content area |
| DESKTOP + landing | Full-width hero, sections, sticky top nav |
| DESKTOP + data table | Top filters, main grid/table, pagination footer |
| TABLET + any | Hybrid layout, 2-column grid, side panel optional |

### 3. Components block
Be specific. Replace generic descriptions with named UI patterns:

| ❌ Generic | ✅ Specific |
|---|---|
| "A form" | "Email input field with inline validation, password input with eye icon toggle" |
| "Some buttons" | "Primary 'Continue' CTA button (full-width on mobile), ghost 'Back' link" |
| "Navigation" | "Top navigation bar with logo left, links center (Features, Pricing, About), 'Sign up' button right" |
| "Cards" | "3-column grid of cards: thumbnail image, title, description, category tag, CTA link" |

### 4. Content block
Always use realistic content — **never Lorem Ipsum, never "Item 1/2/3"**:
- Names: real-sounding (Emma, Jack, Sarah)
- Prices: realistic ($24.99, $1,200/mo)
- Titles: descriptive ("Revenue Growth Q3", "Active Users — Last 30 days")
- Dates: realistic (Nov 2024, 3 days ago)

**Path B output format (strict — must use exactly this):**
```
[Context block]

[Layout block]

[Components block]
```

**Path B example (dashboard from SaaS spec):**

Input spec:
```json
{
  "theme": "LIGHT",
  "primaryColor": "#6366F1",
  "headlineFont": "DM_SANS",
  "bodyFont": "DM_SANS",
  "labelFont": "IBM_PLEX_SANS",
  "colorVariant": "TONAL_SPOT",
  "roundness": "ROUND_EIGHT",
  "spacingScale": 1,
  "backgroundLight": "#FFFFFF",
  "backgroundDark": "#18181B",
  "density": "COMPACT",
  "designMode": "HIGH_FIDELITY",
  "styleKeywords": ["Productivity", "SaaS", "Structured"],
  "deviceType": "DESKTOP"
}
```

Output prompt:
```
Desktop High-Fidelity analytics dashboard. Productivity SaaS aesthetic. Tonal spot accents on neutral base. Light mode. Background: White (#FFFFFF). Primary: Indigo (#6366F1). Headline font: DM Sans. Body font: DM Sans. Label font: IBM Plex Sans. Roundness: 8px. Compact spacing, data-dense layout.

Left sidebar navigation (200px wide): Logo top-left, nav items with icons (Overview, Projects, Team, Billing, Settings), user avatar and name at the bottom. Main content: Top bar with 'Good morning, Sarah' and date. KPI row: 4 cards (Active Projects: 12, Tasks Completed: 847, Team Members: 24, On-time Delivery: 94%). Main chart: 'Velocity' line chart (last 30 days). Bottom split: 'Recent Activity' feed left, 'Upcoming Deadlines' list right.

KPI cards: indigo number, grey label (IBM Plex Sans), subtle upward trend arrow in green. Line chart: indigo primary line, grey grid, hover tooltip. Activity feed: avatar, action text, timestamp. Deadline items: color-coded priority dot, task name, due date, assignee avatar.
```

---

## Quality rules

- **No Lorem Ipsum** — ever
- **Name the components** — "floating action button", not "button at bottom"
- **Specify color roles** — "primary indigo (#6366F1) for CTAs", not "blue buttons"
- **Specify layout dimensions when critical** — "200px sidebar", "full-width hero (100vh)"
- **Include interaction states** — "hover state on cards", "active nav item highlighted"
- **Match content to device** — large touch targets on mobile, dense info on desktop

---

## Prompt Quality Standard (Checklist)

Before sending any prompt to `generate_screen_from_text`, verify every item passes. If anything fails — re-run prompt assembly. Don't ship vague prompts.

### Required blocks

- [ ] **Project overview** — one paragraph covering: what it is, who it's for, visual style, and 2-3 key attributes. Not a sentence — a paragraph.
- [ ] **Design system block** — must include all of these:
  - Platform (Web / Mobile / Tablet)
  - Theme (Light / Dark)
  - Color scheme with `#hex` values (primary, secondary, background minimum)
  - Typography with px sizes, font family, and weight (`Inter 16px/400 body, 24px/700 heading`)
  - Component style: border radius, shadow depth, interaction style (filled, outlined, ghost)
- [ ] **Per-section detail** — each area of the screen needs:
  - Core function in one line ("user authentication with social login")
  - Area breakdown: nav, hero, function area, actions, footer — with concrete elements and specific copy
- [ ] **No vague placeholders** — every element must be concrete:
  - ❌ "a button" → ✅ "primary CTA 'Sign In' `#6366F1` filled `rounded-lg`"
  - ❌ "some navigation" → ✅ "top nav: logo left, [Features, Pricing, About] center, 'Get Started' button right"
  - ❌ "a card section" → ✅ "3-column grid: 280px cards with 16px radius, thumbnail, title (18px/600), 2-line description, category tag"
- [ ] **Layout + Components sections populated** — both must have named, specific entries. Empty sections = failed check.

### Gate rule

If any item above fails, **re-invoke the prompt architect** before calling `generate_screen_from_text`. Each generation call costs time (60-180s) and creates a new screen — getting it right the first time saves real minutes.

## References

- `references/KEYWORDS.md` — Component terms, adjective palettes, color role vocabulary