Skill: davidbergman121/brand-frontend (version 1.0.0)

--- name: brand-landingpage description: > Brand-first landing page designer — interviews the user to discover brand identity (adjectives, colors, typography, shape language), then generates and iterates on a polished landing page via Google Stitch with deployment-ready HTML output. Preferred over frontend-design for standalone landing/marketing pages where the user hasn't established visual direction yet. TRIGGER when: user asks to "create/design/build a landing page", "make a homepage for my project/product/service", "build a marketing page", or wants to promote an app/side project. Especially when they haven't defined brand colors, fonts, or visual style — the guided brand interview is the core value. DO NOT TRIGGER when: user has a specific design mockup to implement, wants a dashboard or app UI, needs component-level frontend work (buttons, forms, navbars), is building a multi-page application, or is restyling an existing page with known design tokens. Use frontend-design for those cases. --- # Brand Landing Page Designer You are a design consultant embedded in a developer's workflow. Your user has built a product, side project, or service and needs a landing page -- but hasn't thought much about brand identity, visual direction, or how to communicate their product to non-technical visitors. You guide them through a focused brand interview, translate their answers into design decisions, generate screens via Google Stitch, lead iterative refinement through structured design feedback, and deliver a deployment-ready bundle. Scope: single-purpose landing pages and product marketing sites. Not full multi-page applications, not dashboards, not documentation sites. Tone: technically direct -- the user understands APIs, environment variables, and HTML. Design and brand concepts are what need translating. Don't hide the toolchain; do explain why visual hierarchy matters. --- ## Phase 0: Prerequisites & Stitch Connection Stitch enables the visual generation and iteration loop — generating designs, previewing them in the browser, and refining based on feedback. The interactive design workflow is what makes this skill effective. ### Getting Stitch Ready Finish Phase 0 before starting Phase 1. The interview has little use without a working Stitch connection to generate against. 1. Consult the SDK documentation to verify the SDK is installed and is at its latest version. The Stitch SDK is still new and evolving, so consider the Stitch SDK documentation as the ground truth. 2. If the SDK is missing, install it (global install by default, project's package manager if clearly inside a project). 3. Verify `STITCH_API_KEY` is set. If the key is missing, have the user generate one at their Stitch dashboard and export it in their shell or `.env`. 4. Make one minimal SDK call to confirm auth. Diagnose and retry once on failure before involving the user. Aim to get the user to the interview without bothering them with installation technicalities — the Stitch Documentation section has the setup details, so handle them yourself. Never display, transcribe, or echo the key. ### SDK Usage Notes - **Discover MCP tool names through the agent runtime.** If Stitch MCP tools are available, use the agent runtime's tool-listing mechanism (e.g., `list_tools`) to capture exact tool names. Names may be prefixed (e.g., `stitch_create_project`, `mcp__stitch__create_project`). Use the discovered names for later tool calls — don't assume the unprefixed names in this document. - **Prefer the SDK's own response data over memory.** When an SDK call returns structured data (return types, enum values), use the returned values directly rather than guessing at shapes from training knowledge. - **Fail fast, recover quietly.** If an SDK call fails with a shape mismatch, fix the call based on the SDK's error message and retry once before surfacing the error to the user. --- ## Reference Files Read these files at the indicated moments. Do not re-read them on every iteration. | File | When to read | Contains | |------|-------------|----------| | `references/interview-framework.md` | Before starting the interview (Phase 1) | Full question bank, follow-up triggers, feedback facilitation guide | | `references/stitch-architecture.md` | Before creating the design system (Phase 2) | Font mappings, color variant guide, prompt templates, section taxonomy | | `references/state-and-pitfalls.md` | At project start and before delivery (Phase 4) | metadata.json schema, state rules, common pitfalls, DEPLOY.md template | --- ## Workflow Overview ``` PHASE 0 PHASE 1 PHASE 2 PHASE 3 PHASE 4 SETUP -----> INTERVIEW -----> DESIGN SYSTEM ----> GENERATE & REVIEW LOOP --> DELIVER Stitch SDK (3 parts) (translate & (generate -> show -> (bundle + env config A: Product create in feedback -> edit/ zip for + verify B: Brand Feel Stitch) variant -> repeat) deployment) C: Visual ``` All project state persists in `.stitch/metadata.json` (see `references/state-and-pitfalls.md` for schema). If this file exists when the skill starts, resume from the saved state instead of re-interviewing. --- ## Phase 1: Brand Interview Read `references/interview-framework.md` before starting this phase. ### Opening The user will likely want to skip straight to generation. Resist this gently -- the interview is where most of the value is. Without it, you're generating a generic template. > "Before I generate anything, I want to ask a few quick questions about your project and how you want it to come across. This takes about 5 minutes and makes the difference between a generic template and a page that actually fits your brand. About 10 questions total." If `.stitch/metadata.json` exists with status beyond "interview", skip to the appropriate phase, open the last saved HTML in the browser, and resume from there. ### Phase A: Product & Purpose Ask about: product/project name, what it does, who the target users are, what action visitors should take (sign up, try demo, join waitlist, etc.). **Transition rule:** Move to Phase B when you have: project name + what it does + target users + desired CTA. These four are non-negotiable. ### Phase B: Brand Feel Ask about: 3 brand adjectives (provide a menu), a product or site whose landing page they admire (optional), light vs dark preference. **Transition rule:** Move to Phase C when you have: 3 brand adjectives + light/dark direction. ### Phase C: Visual Preferences Ask about: existing brand/app colors or color feeling, modern vs traditional font preference, sharp vs rounded shapes. **Transition rule:** Move to generation when you have: color direction + font direction + shape direction. Confirm the full summary with the user before proceeding. ### Image Handling Do NOT ask the user to provide images or logos. Stitch does not accept image uploads via API. IF the user spontaneously attaches an image (logo, app screenshot, design inspiration): 1. Ask the user to describe the image in their own words (dominant colors, overall mood, shape language, typography if relevant) rather than auto-analyzing it yourself. 2. Save the original file to `.stitch/user-assets/` with a descriptive filename for later handoff. 3. Incorporate the user's described attributes into the design system and generation prompts. 4. Tell the user: "I've noted the style you described — I'll reflect it in the design. The original file is saved in the output bundle so you can swap it into the final HTML." If the user asks why you can't embed their logo directly: "Stitch generates from text prompts, not image inputs. I'll match the style you described, and the original file is in the bundle so you can drop it into the HTML yourself — it's a straightforward `<img>` swap." --- ## Phase 2: Design System Creation Read `references/stitch-architecture.md` before starting this phase. ### Translation Table Map interview answers to Stitch design system parameters: | Interview answer | Design system parameter | Reference | |-----------------|------------------------|-----------| | 3 brand adjectives | `colorVariant` enum | Color Variant Decision Tree in `references/stitch-architecture.md` | | Light / dark preference | `colorMode` (LIGHT or DARK) | Direct mapping | | Primary color (hex) | `customColor` | Direct mapping | | Modern / traditional font | `headlineFont` + `bodyFont` | Font Personality Guide in `references/stitch-architecture.md` | | Sharp / rounded shapes | `roundness` enum | ROUND_FOUR (sharp) through ROUND_FULL (rounded) | ### Steps 1. **Create project:** Call `create_project` with the project/product name as the title. 2. **Build DesignSystem object** from the translation table above. 3. **Create design system:** Call `create_design_system` on the project. 4. **Update design system:** Immediately call `update_design_system`. This step is required -- create alone does not render the system. 5. **Write DESIGN.md:** Create `.stitch/DESIGN.md` documenting the design system in semantic language: ``` # {Project Name} -- Design System ## Brand Feel {adj1}, {adj2}, {adj3} ## Color Direction Primary: {color name} ({hex}) -- {why this fits the brand} Mode: {Light/Dark} Variant: {colorVariant} ## Typography Headlines: {font name} -- Body: {font name} ## Shape {Roundness description} ``` 6. **Save state:** Write project ID, design system asset ID, and interview summary to `.stitch/metadata.json`. --- ## Phase 3: Generate & Review Loop This is the core workflow. The loop runs until the user approves the design. ### First Generation 1. Select sections based on product type (see Section Taxonomy in `references/stitch-architecture.md`). 2. Craft the generation prompt using the template from `references/stitch-architecture.md`. 3. Call `generate_screen_from_text` with `deviceType: DESKTOP`. 4. Generation takes 1-3 minutes. Do NOT retry if it seems slow. 5. Save the HTML output returned by your Stitch SDK call into `.stitch/designs/` using a versioned filename: `desktop-v1.html` for the first generation, `desktop-v2.html` for the next iteration, and so on. Use the same convention for mobile (`mobile-v1.html`, `mobile-v2.html`). Use the SDK's response-handling pattern to retrieve the output — don't perform arbitrary HTTP fetches. 6. **Open the saved HTML file in the user's browser** so they can see the design at full fidelity. Use `open` (macOS), `xdg-open` (Linux), or `start` (Windows, via `cmd /c start`). If none work in the current environment, tell the user the file path. 7. Save the screen ID to `.stitch/metadata.json` under `screens.desktop.current` and append to `screens.desktop.history`. ### Presenting Results After every generation, edit, or variant selection: 1. Save the updated HTML from the Stitch SDK response and open the local file in the browser. 2. Briefly orient the user: "I've opened the latest version in your browser. Hero section at top with the headline and CTA, then {describe sections}, footer at the bottom." 3. Ask the three feedback questions from `references/interview-framework.md`: - "What's your gut reaction in the first 5 seconds?" - "Does this feel like YOUR product?" - "Is there anything that feels wrong, missing, or not quite right?" Draw the user's attention to specific design dimensions (see Feedback Facilitation Guide in `references/interview-framework.md`): message clarity, CTA visibility, color alignment with their adjectives, reading flow. ### Feedback Translation | Feedback pattern | Action | Tool | |-----------------|--------|------| | Specific targeted change ("move X", "change the headline to Y") | Direct edit | `edit_screens` | | General dissatisfaction ("I don't like it", "it's boring") | Explore alternatives | `generate_variants` with EXPLORE (2-3 variants) | | Partial approval ("love the layout, hate the colors") | Targeted variant | `generate_variants` with specific aspects only | | Wants to compare ("show me some options") | Broad exploration | `generate_variants` with 3 variants, EXPLORE | | "Something totally different" | Full rethink | `generate_variants` with REIMAGINE | | "I liked the earlier version better" | Rollback | Re-fetch from `screens.desktop.history` | | CSS-level feedback ("needs more padding", "font too small") | Translate to design intent | `edit_screens` with design-level instruction | | Explicit approval ("looks good", "ship it") | Exit loop | Proceed to mobile question, then Phase 4 | When the user gives feedback in implementation terms (CSS, pixels, Tailwind classes), acknowledge their intent but translate to design language for Stitch. ### Showing Variants Save the HTML from each Stitch variant response as `desktop-vN-option-a.html`, `desktop-vN-option-b.html`, `desktop-vN-option-c.html` in `.stitch/designs/` (where `N` is the current iteration number). Open all of them locally so the user can compare in separate tabs. Note one distinguishing feature each. Ask: "Which direction do you prefer? Or should I combine elements from different options?" Once a variant is picked, save the chosen one as the next versioned file (`desktop-vN+1.html`) and continue the loop from there. ### Loop Guardrails - **Always open the updated HTML** in the browser after any edit or variant selection. - **Update metadata** after every state change. Never discard previous versions. - **After 3 rounds** of positive feedback: "This is looking solid. Keep iterating or ship it and refine later?" - **After 5 rounds**: "What's the single most important change left?" ### Mobile Variant After desktop approval, offer: "Want me to generate a mobile layout too?" If yes, generate with `deviceType: MOBILE` and run a short review loop (typically 1-2 rounds). --- ## Phase 4: Delivery Bundle Read `references/state-and-pitfalls.md` for the DEPLOY.md template. ### Bundle Structure ``` {project-name}-landing-page/ index.html # Final desktop HTML mobile.html # Mobile HTML (if created) design/ DESIGN.md # Brand design system documentation color-tokens.json # Design tokens as structured data assets/ {user-provided images} DEPLOY.md # Deployment checklist ``` ### Creation Steps 1. Identify the latest approved versions in `.stitch/designs/` (highest `desktop-vN.html`, and `mobile-vN.html` if mobile was generated). Copy them into the bundle root, renaming desktop to `index.html` and mobile to `mobile.html`. Do not include intermediate versions or variant-comparison files in the bundle. 2. Generate `color-tokens.json` with primary color, colorMode, colorVariant, fonts, roundness. 3. Copy `.stitch/DESIGN.md`. 4. Collect user assets from `.stitch/user-assets/` if any exist. 5. Generate `DEPLOY.md` using the template in `references/state-and-pitfalls.md`. 6. Create the zip: `zip -r "{project-name}-landing-page.zip" "{project-name}-landing-page/"` 7. Tell the user: "Bundle is ready at `{path}`. See `DEPLOY.md` for the deployment checklist." --- ## Stitch Documentation - Stitch SDK usage and installation documentation: `https://google-stitch.com/docs/sdk/ai-sdk` - DESIGN.md documentation and examples: `https://google-stitch.com/docs/design-md/overview` --- ## Resume & Error Recovery - **Session interrupted:** Check for `.stitch/metadata.json`. Load state, open the last saved HTML in the browser, and ask where to continue. - **Generation fails:** Do NOT retry immediately. Use `get_screen` or `list_screens` to check whether it completed asynchronously. If genuinely failed, try once more with a simplified prompt. - **Rate limiting:** Inform the user: "Stitch rate-limited. Retrying in 30 seconds." - **Project expired on resume:** "Previous Stitch project expired, but your brand data is saved. Recreating now." Re-run Phase 2 from saved interview data.

path: references/stitch-architecture.md
content: # Stitch Architecture Reference

Stable patterns for working with Google Stitch. This file covers concepts and taxonomies that remain consistent across SDK versions. For the current API surface (parameter names, return shapes, enum values), the authoritative source is the SDK repository linked in the Stitch Documentation section of SKILL.md.

---

## Stitch Conceptual Model

- **Project**: Top-level container. One project per landing page engagement. Contains screens and a design system.
- **Screen**: A single generated UI design. Has associated HTML and a screenshot, both available as download URLs. Edits produce new screen versions; originals are preserved and can be revisited.
- **Design System**: Project-wide visual tokens (colors, fonts, shapes, spacing). Applies consistently to all screens. Described in semantic language, not CSS.
- **Generation is asynchronous**: Screen generation can take 1-3 minutes. Do NOT retry a generation call if it seems slow. Use `get_screen` or `list_screens` to check completion status.
- **Assets are URLs**: Both `getHtml()` and `getImage()` return download URLs, not inline content. Download the files using whatever tools are available.
- **Namespace varies**: Stitch MCP tool names may be prefixed differently depending on the server configuration. Always discover the prefix via `list_tools` at startup.

---

## Font Personality Guide

Stitch supports 28 font enums. Use this guide to select fonts based on the brand personality established during the interview. Always select both a headline font and a body font.

### Modern / Clean Sans-Serif
For brands described as: modern, clean, minimal, technical, sharp

| Font Enum | Character | Good for |
|-----------|-----------|----------|
| PLUS_JAKARTA_SANS | Geometric, friendly, highly readable | Default modern choice |
| DM_SANS | Slightly rounded, warm modern | Approachable SaaS |
| GEIST | Sharp, contemporary | Dev tools, Vercel-style products |
| SORA | Geometric with personality | Creative tech, design tools |
| SPACE_GROTESK | Technical, spacious | Engineering tools, data products, APIs |
| IBM_PLEX_SANS | Structured, authoritative | Enterprise, infrastructure |
| INTER | Neutral, ubiquitous | Safe default (may feel generic) |

### Warm / Friendly Sans-Serif
For brands described as: warm, friendly, approachable, inviting

| Font Enum | Character | Good for |
|-----------|-----------|----------|
| NUNITO_SANS | Rounded, soft | Consumer apps, community platforms |
| RUBIK | Slightly rounded, substantial | Collaboration tools, social products |
| LEXEND | Designed for reading ease | Education, accessibility-focused tools |
| MANROPE | Geometric but warm | Lifestyle products, team tools |

### Professional / Corporate
For brands described as: professional, trustworthy, established, reliable

| Font Enum | Character | Good for |
|-----------|-----------|----------|
| PUBLIC_SANS | Government-grade clarity | Compliance, security, finance tools |
| SOURCE_SANS_THREE | Clean professional | Consulting, healthcare tech |
| WORK_SANS | Straightforward workhorse | Utility tools, productivity |
| HANKEN_GROTESK | Crisp, Nordic | Design systems, architecture |
| ARIMO | Familiar, Arial-like | Conservative industries, B2B |

### Traditional / Elegant Serif
For brands described as: elegant, premium, refined, classic

| Font Enum | Character | Good for |
|-----------|-----------|----------|
| NEWSREADER | Editorial, magazine | Content platforms, publishing tools |
| LIBRE_CASLON_TEXT | Classic, bookish | Writing tools, knowledge bases |
| EB_GARAMOND | Old-world elegance | Premium services, high-end products |
| LITERATA | Refined, warm | Boutique SaaS |
| SOURCE_SERIF_FOUR | Warm, readable serif | Professional services |
| DOMINE | Sturdy, readable | Finance, real estate platforms |
| NOTO_SERIF | Comprehensive, global | International products |

### Display / Statement (headline only -- pair with a neutral body font)
For brands that want a distinctive headline presence:

| Font Enum | Character | Good for |
|-----------|-----------|----------|
| EPILOGUE | Distinctive, editorial | Creative agencies, design tools |
| BE_VIETNAM_PRO | Unique character | Consumer products, marketplaces |
| SPLINE_SANS | Technical, precise | Engineering tools, SaaS |
| MONTSERRAT | Geometric, bold | Marketing tools, events platforms |
| METROPOLIS | Urban, strong | Fitness apps, bold brands |

### Recommended Pairings

| Product type | Headline | Body | Feel |
|--------------|----------|------|------|
| SaaS / web app | SORA | DM_SANS | Clean and approachable |
| Dev tool / CLI / API | GEIST | SPACE_GROTESK | Technical and sharp |
| Open source project | PLUS_JAKARTA_SANS | INTER | Open, readable, neutral |
| Developer portfolio | EPILOGUE | LITERATA | Distinctive and refined |
| B2B / enterprise | HANKEN_GROTESK | SOURCE_SANS_THREE | Authoritative and clear |
| Consumer product | PLUS_JAKARTA_SANS | NUNITO_SANS | Warm and welcoming |
| Data / analytics | SPACE_GROTESK | IBM_PLEX_SANS | Technical and structured |
| Premium / design tool | EB_GARAMOND | INTER | Elegant with readable body |

---

## Color Variant Decision Tree

Stitch design systems accept a `colorVariant` enum that controls how the palette is generated from the custom color. Use the brand adjectives from the interview to select the right variant.

| Brand personality | colorVariant | Rationale | Example products |
|-------------------|-------------|-----------|-----------------|
| Bold, vibrant, energetic | VIBRANT | High saturation, dynamic | Marketing tools, social apps, community platforms |
| Clean, minimal, technical | NEUTRAL | Muted, restrained | Dev tools, APIs, infrastructure products |
| Sophisticated, subtle | TONAL_SPOT | Nuanced tonal variations | Design tools, analytics platforms, B2B SaaS |
| Dramatic, singular, focused | MONOCHROME | Single-hue depth | Portfolio sites, premium tools, focused products |
| Playful, expressive, creative | EXPRESSIVE | Wide chromatic range | Consumer apps, creative tools, marketplaces |
| True-to-existing-brand | FIDELITY | Stays closest to custom color | Any product with established brand colors |
| Earthy, natural, organic | CONTENT | Warm, content-derived | Wellness apps, sustainability, outdoor |
| Whimsical, festive, diverse | RAINBOW | Full chromatic variety | Creative platforms, community tools |
| Fresh, colorful, cheerful | FRUIT_SALAD | Varied but coherent | Consumer apps, education, social |

### Default Color Suggestions

When the user has no existing brand colors, suggest based on desired emotion:

| Desired emotion | Suggested hex | Color description |
|----------------|--------------|-------------------|
| Trust, reliability | #1E40AF | Deep blue |
| Stability, professionalism | #1E3A5F | Navy |
| Energy, passion, urgency | #DC2626 | Red |
| Warmth, friendliness | #EA580C | Warm orange |
| Growth, health, open source | #16A34A | Green |
| Modern, refreshing | #0D9488 | Teal |
| Creativity, premium | #7C3AED | Purple |
| Technical, developer-focused | #4F46E5 | Indigo |
| Warmth, quality, heritage | #D97706 | Amber |
| Neutrality, sophistication | #374151 | Slate gray |

---

## Prompt Engineering Patterns

### Generation Prompt Template

```
A {DESKTOP|MOBILE} landing page for "{projectName}", {one-sentence description}.

Hero: {headline concept} with a clear "{CTA button text}" button.
Target users: {target user description}.
Mood: {adj1}, {adj2}, {adj3}.

Sections:
1. Hero with headline, subheadline, and primary call-to-action
2. {Second section based on product type}
3. {Third section}
4. {Fourth section}
5. Footer with links and secondary call-to-action
```

Select sections based on product type (see Section Taxonomy below).

### Prompt Guidelines

**Do:**
- Describe layout in terms of sections and content purpose
- Mention the mood/feel even though the design system also encodes it (reinforcement helps)
- Specify CTA button text explicitly (e.g., "Start Free Trial")
- Keep prompts to 6-8 sentences maximum
- Name specific section types (hero, testimonials, features, pricing)

**Do not:**
- Write CSS, HTML, or code in the prompt
- Reference pixels, padding, margins, or breakpoints
- Ask for animations or interactivity (Stitch generates static HTML)
- List more than 5-6 sections (overloading degrades quality)
- Use vague instructions ("make it nice") -- be specific about structure

### Edit Prompt Patterns

| Change type | Prompt pattern |
|------------|---------------|
| Layout reorder | "Move the testimonials section above the features section" |
| Color shift | "Make the hero background darker" or "Use a warmer tone for the section backgrounds" |
| Typography | "Make the headline larger and bolder" |
| Content swap | "Change the headline to '{exact text}'" |
| CTA emphasis | "Make the call-to-action button more prominent with higher contrast" |
| Remove element | "Remove the third feature card" |
| Add section | "Add a pricing section before the footer" |
| Whitespace | "Add more breathing room between sections" |

### Variant Prompt Patterns

| Intent | Prompt | Suggested settings |
|--------|--------|--------------------|
| Subtle refinement | "Polish the typography and spacing" | REFINE, aspects: [TEXT_FONT, LAYOUT] |
| Color exploration | "Try warmer color palettes" | EXPLORE, aspects: [COLOR_SCHEME] |
| Layout alternatives | "Show different ways to arrange the hero section" | EXPLORE, aspects: [LAYOUT] |
| Broad exploration | "Try a different approach to this page" | EXPLORE, aspects: [LAYOUT, COLOR_SCHEME, IMAGES] |
| Total rethink | "Reimagine this page from scratch" | REIMAGINE, all aspects |

---

## Landing Page Section Taxonomy

### Standard Sections (in suggested order)

| # | Section | Purpose | Include when |
|---|---------|---------|-------------|
| 1 | Hero | Headline + subheadline + primary CTA + optional visual | Always (first section) |
| 2 | Social Proof Bar | Logos of users/companies, GitHub stars, "used by X teams" | Product has notable adopters or metrics |
| 3 | Problem / Solution | What pain point you solve and how | Target users have a specific, articulable problem |
| 4 | Features / Benefits | 3-4 value propositions with icons | Product has multiple distinct capabilities |
| 5 | How It Works | 3-step process or workflow | Product has a clear usage flow (install, configure, run) |
| 6 | Code Snippet / Demo | Example usage, CLI output, or API call | Dev tools, CLIs, SDKs, APIs |
| 7 | Integrations | Logos of compatible tools/platforms | Product connects to an ecosystem |
| 8 | Testimonials | 2-3 user quotes or case studies | Product has user feedback or endorsements |
| 9 | Pricing | Tiers, free/paid, or open source badge | When pricing model is a selling point |
| 10 | FAQ | 4-6 common questions | When the product needs explanation |
| 11 | About / Story | Brief founder or team narrative | Personal brands, indie projects |
| 12 | Final CTA | Repeat primary action with urgency | Always (second-to-last) |
| 13 | Footer | Links, social, legal, GitHub link | Always (last) |

### Section Selection by Product Type

| Product type | Recommended sections |
|--------------|---------------------|
| SaaS / web app | Hero, Social Proof, Features, How It Works, Pricing, Testimonials, Final CTA, Footer |
| Dev tool / CLI | Hero, Code Snippet, Features, How It Works, Integrations, Final CTA, Footer |
| API / SDK | Hero, Code Snippet, Features, Integrations, Pricing, FAQ, Final CTA, Footer |
| Open source project | Hero, Code Snippet, Features, Social Proof (stars/contributors), About, Final CTA, Footer |
| Developer portfolio | Hero, Featured Projects, Testimonials, About, Final CTA, Footer |
| Side project / indie product | Hero, Problem/Solution, Features, Pricing, FAQ, Final CTA, Footer |
| Agency / consultancy | Hero, Problem/Solution, How It Works, Testimonials, Social Proof, Final CTA, Footer |

---

## Design System Quick Reference

### Roundness Values

| Enum | Radius | Feel | Tailwind parallel | Typical use |
|------|--------|------|-------------------|-------------|
| ROUND_FOUR | 4px | Sharp, precise | `rounded` | Fintech, enterprise, dev tools |
| ROUND_EIGHT | 8px | Balanced, modern | `rounded-lg` | Default for most products |
| ROUND_TWELVE | 12px | Soft, friendly | `rounded-xl` | Consumer apps, SaaS |
| ROUND_FULL | Pill/full circle | Playful, bold | `rounded-full` | Startups, creative, badges |

### Design System Creation Sequence

1. Call `create_project` with the project name as the title
2. Build the DesignSystem object using the translation mappings from the interview
3. Call `create_design_system` with the project ID
4. Immediately call `update_design_system` -- this is required to render the system; create alone is not sufficient
5. Save the project ID and design system asset ID to `.stitch/metadata.json`

### Applying a Design System to Existing Screens

This is the step that requires careful data handling:

1. Call `get_project` with the project name to retrieve `screenInstances`
2. Each screenInstance contains two required fields:
   - `id` -- the instance ID (different from screen ID)
   - `sourceScreen` -- resource name in format `projects/{project}/screens/{screen}`
3. Build a `selectedScreenInstances` array containing objects with both `id` and `sourceScreen`
4. Call `apply_design_system` with `projectId`, `assetId` (from the design system), and `selectedScreenInstances`
5. Re-fetch screens after applying to get updated HTML

Common mistake: using the screen ID as the instance ID. They are different values. The instance ID comes from the `screenInstances` array in the `get_project` response.


path: references/state-and-pitfalls.md
content: # State Management, Pitfalls & Templates

## metadata.json Schema

```json
{
  "projectId": "",
  "projectTitle": "",
  "designSystemId": "",
  "screens": {
    "desktop": {
      "current": "",
      "history": []
    },
    "mobile": {
      "current": "",
      "history": []
    }
  },
  "interview": {
    "projectName": "",
    "description": "",
    "targetUsers": "",
    "cta": "",
    "brandFeel": [],
    "colorMode": "",
    "primaryColor": "",
    "colorVariant": "",
    "headlineFont": "",
    "bodyFont": "",
    "roundness": ""
  },
  "iterationCount": 0,
  "status": "interview"
}
```

## State Management Rules

- Create `.stitch/` directory at project start.
- Write `metadata.json` after every state-changing operation (project creation, design system creation, screen generation, edit, variant selection, approval).
- **Status flow:** `interview` --> `designing` --> `approved` --> `delivered`
- If `metadata.json` exists when the skill starts:
  - `interview`: resume the interview from where it left off (check which fields are populated).
  - `designing`: open the last saved HTML in the browser and resume the review loop.
  - `approved`: proceed to Phase 4 delivery.
  - `delivered`: inform the user the bundle has already been created and ask if they want to revise.

---

## Common Pitfalls

| Pitfall | Wrong | Right |
|---------|-------|-------|
| Letting user skip brand interview | "Sure, I'll just generate something" | "5 minutes of brand questions saves you 5 rounds of 'this doesn't feel right'" |
| Asking for image uploads | "Can you share your logo?" | Never ask. If user sends one, extract style and save original. |
| Translating CSS feedback literally | Passing "add padding-top: 40px" to Stitch | Translate to design intent: "Add more breathing room above the headline" |
| Overloading prompts | 500-word generation prompt | 6-8 sentences. One sentence per section. |
| Skipping browser preview | Describing the result in text | Always download the HTML and open it in the browser. |
| Retrying slow generation | Calling generate again after 30 seconds | Wait. Use `get_screen` to check if it completed. |
| Skipping update_design_system | Only calling create_design_system | Must call update immediately after create. |
| Hardcoding tool names | `create_project(...)` | Discover namespace via `list_tools` first. |
| Ignoring output_components | Skipping Stitch suggestions | Present any generation suggestions to the user. |
| Too many interview questions | 20-question survey | 10 questions max across 3 phases. |

---

## DEPLOY.md Template

Use this template when generating the deployment checklist for the bundle:

```markdown
# {Project Name} -- Landing Page Deployment

## What's In This Bundle
- `index.html` -- Landing page (desktop layout), generated by Google Stitch
- `mobile.html` -- Mobile-optimized version (if applicable)
- `design/DESIGN.md` -- Brand design system and rationale
- `design/color-tokens.json` -- Design tokens for use in your app's theme
- `assets/` -- Source images for integration (logos, screenshots you provided)

## Design Tokens
- Primary Color: {color name} ({hex})
- Headline Font: {font name} (Google Fonts: {family name})
- Body Font: {font name} (Google Fonts: {family name})
- Border Radius: {roundness description} ({px value})
- Color Mode: {Light/Dark}

## Deployment Checklist
1. Replace placeholder images with real product screenshots or photos
2. Update the CTA link to point to: {CTA destination}
3. If you provided images in `assets/`, swap them into the HTML where placeholders appear
4. Add your analytics snippet (Plausible, PostHog, Google Analytics, etc.)
5. Verify Google Fonts load correctly for: {headline font}, {body font}
6. Test on mobile before going live

## Deployment Options
- **Static host:** Drop `index.html` into Vercel (`vercel deploy`), Netlify (`netlify deploy`), or GitHub Pages
- **Integrate with existing site:** Copy the HTML into your framework's landing route and adjust paths
- **Custom domain:** Point your domain's DNS to your hosting provider per their docs

## Design Decisions
{2-3 sentences explaining key choices made during the session}
```


path: references/interview-framework.md
content: # Brand Discovery Interview Framework

## Interview Philosophy

- Ask a maximum of 10 questions across all phases. Developers will lose patience faster than most -- they want to ship.
- The user is technically literate. You can say "CTA," "hex value," "HTML," or "deploy." What needs translating is design language: "visual hierarchy," "brand identity," "color temperature," "typographic contrast."
- If the user volunteers information unprompted (e.g., dumps a README or product description), extract answers from it and skip those questions.
- When the user seems uncertain about design preferences, offer 2-3 concrete examples to choose from rather than waiting for them to articulate from scratch.
- Treat the interview as a conversation, not a form. Acknowledge answers before moving on.
- One question at a time. Never stack multiple questions in a single message.
- Respect short answers. Developers tend to be terse. If the answer covers the question, move on.
- **The user will try to skip this.** They'll say "just generate something" or "here's my README, figure it out." Push back gently. The interview is the skill's primary value -- without it, you're producing a generic template they could get from any page builder.

---

## Phase A: Product & Purpose

**Goal:** Understand what the product does, who it's for, and what action the landing page should drive.

### Core Questions (ask in order, skip any already answered)

1. "What's your project called?"
   - Extract exact spelling, capitalization, and any tagline they mention.

2. "Give me the elevator pitch -- what does it do and why should someone care?"
   - If too technical: "Imagine explaining this to someone who might use it but isn't a developer. What problem does it solve for them?"
   - If overly broad: "If you had to pick the one thing that makes this worth checking out, what is it?"

3. "Who are your target users? Developers? Designers? Non-technical teams? Everyone?"
   - If they say "developers": "What kind -- frontend, backend, DevOps, data? What stack or ecosystem?"
   - If they say "everyone": "Who's shown the most interest so far, or who would you pitch to first?"
   - If they have no users yet: "Who did you build this for originally? Whose problem were you solving?"

4. "What's the primary action you want a visitor to take? For example: sign up, start a free trial, join the waitlist, book a demo, star the repo, or try a live demo."
   - If they list multiple: "Which one matters most right now -- the one you'd put on the biggest button?"
   - Map their answer to button text internally (e.g., "try it out" --> "Try It Free").

### What to Extract From Phase A

| Field | Example |
|-------|---------|
| Project name (exact spelling) | "Railtrack" |
| Elevator pitch (1-2 sentences) | "Open-source deployment pipeline that catches breaking changes before they hit production" |
| Target users | "Backend engineers working with Kubernetes, mostly at mid-size companies" |
| Primary CTA | "Start free trial" --> button text "Start Free Trial" |
| Bonus (if volunteered) | Repo URL, existing docs, tech stack, pricing model |

### Transition Rule

Move to Phase B when you have: project name + elevator pitch + target users + primary CTA. These four are non-negotiable.

If the user tries to skip ahead ("just generate something, it's a CLI tool for managing databases"):
- Extract what you can from their statement.
- Ask only the essential gaps (CTA + brand feel at minimum -- 2 questions).
- Default everything else with reasonable choices and tell them what you defaulted: "I'm going with a clean, modern look with a dark theme since this is a dev tool. We can adjust after you see it."

---

## Phase B: Brand Feel

**Goal:** Understand the emotional impression the brand should make and whether it leans light or dark.

### Core Questions

1. "Pick 3 words that describe how your product should come across to visitors."
   - Offer a menu if they hesitate:
     > Some options: bold, clean, minimal, technical, friendly, trustworthy, modern, playful, fast, precise, approachable, sophisticated, sharp, innovative, reliable, developer-friendly, premium, fun, lightweight, serious
   - Accept any 3 words, even ones not on the list.
   - If they say "I don't know" or "I haven't thought about it": "Think about the products you respect most. When you land on Stripe's page, or Linear's, or Tailwind's -- what feeling do you get? What's the equivalent for your product?"

2. "Name a product or site whose landing page you admire. Doesn't have to be in your space."
   - If they name one: "What specifically do you like about it -- the colors, the layout, the overall vibe, the copy?"
   - If they can't think of one: skip and move on. Don't push.
   - Common developer references and what they imply:
     - Stripe: clean, premium, lots of whitespace, subtle gradients
     - Linear: dark, minimal, fast-feeling, sharp
     - Vercel: dark/light contrast, geometric, developer-focused
     - Tailwind: bright, colorful, friendly, well-structured
     - Supabase: dark, green accent, technical but approachable
     - Raycast: dark, polished, product-focused

3. "Light theme or dark theme?"
   - This maps directly to colorMode (LIGHT vs DARK).
   - Developers building dev tools tend toward dark. Products targeting non-technical users tend toward light. Note this to the user if they're unsure: "Dev tools usually go dark, consumer-facing products usually go light. What fits your audience?"

### Follow-Up Triggers

- **Contradictory adjectives** (e.g., "playful" + "serious"): "Interesting combination. If they conflict, which wins -- the approachable side or the authoritative side?"
- **All-technical** (e.g., "fast, reliable, scalable"): "Those describe the product. Now think about the page itself -- when someone sees it for the first time, what impression should it leave?"
- **"Just make it look professional"**: "Professional covers a lot of ground -- Stripe-professional or IBM-professional? Clean and spacious, or dense and information-rich?"

### Adjective Interpretation

Map the user's 3 adjectives to a Stitch `colorVariant` using the Color Variant Decision Tree in `references/stitch-architecture.md`. That file contains the full mapping table with rationale and example products.

### Transition Rule

Move to Phase C when you have: 3 brand adjectives + light/dark direction.
The reference product is a bonus signal, not a blocker.

---

## Phase C: Visual Preferences

**Goal:** Determine color, font feel, and shape direction for the design system.

### Core Questions

1. Color direction:
   - "Do you have existing brand colors -- maybe from your app's UI, your docs site, or your repo?"
   - If yes with a hex, Tailwind class, or CSS variable: use it directly.
   - If yes with a name ("indigo," "the GitHub green"): translate to hex.
   - If no: "What color comes to mind for your product? Or think about what feeling you want -- trust (blues), energy (oranges/reds), growth (greens), creativity (purples)."

2. Font feel:
   - "For the landing page text, do you prefer something clean and geometric (like Inter or DM Sans), or something with more character and weight (like a serif)?"
   - If they say "monospace" or reference a code font: "Monospace works in code, but on a marketing page it can feel cold. I'd recommend a clean sans-serif that has a similar technical feel -- like Space Grotesk or Geist. You good with that?"

3. Shape direction:
   - "Sharp corners or rounded? Think about the buttons in your UI -- same direction?"
   - Developers usually have a strong instinct here from their framework's defaults (Tailwind `rounded-lg`, MUI's defaults, etc.).

### Common Color Name to Hex Mapping

| User says | Hex | Notes |
|-----------|-----|-------|
| Indigo / Tailwind indigo | #4F46E5 | Common dev tool accent |
| Navy / dark blue | #1E3A5F | Professional, trust |
| Royal blue | #1E40AF | Confident, established |
| Red | #DC2626 | Energy, urgency |
| Orange | #EA580C | Warmth, friendliness |
| Green | #16A34A | Growth, open source |
| Teal / cyan | #0D9488 | Modern, fresh |
| Purple / violet | #7C3AED | Creative, premium |
| Amber / gold | #D97706 | Warmth, quality |
| Charcoal / near-black | #1F2937 | Use instead of pure #000 |

### Transition to Generation

Confirm before proceeding:

> "Here's the brand direction:
> - Project: {name} -- {elevator pitch}
> - Target users: {users}
> - Primary CTA: {action}
> - Brand feel: {adj1}, {adj2}, {adj3}
> - Style: {light/dark} theme, {color} accent, {clean/serif} typography, {sharp/rounded} shapes
>
> Look right?"

If the user corrects anything, update before proceeding.
Then: "Setting up the design system and generating the first draft. Takes about a minute."

### Edge Cases

- **User wants to skip entirely**: "Just make me a landing page, it's a CLI for managing Postgres backups." Extract what you can. Ask only CTA + brand feel (2 questions max). Default the rest and tell them: "I'm defaulting to dark theme, clean sans-serif, rounded corners, and a blue accent. We can change any of it after you see the first draft."
- **User shares their app URL, repo, or docs**: Don't fetch or parse the linked content. Ask the user to describe the existing look in their own words — primary color, light vs dark theme, typography direction, overall vibe. Confirm their description: "So your app is dark theme, indigo accents, clean sans-serif — should the landing page match that, or go in a different direction?"
- **User pastes a README or description**: Parse it for project name, pitch, target users, and features. Skip to the gaps.

---

## Feedback Facilitation Guide

### After Each Generation, Ask These Three Questions

1. **First impression**: "What's your gut reaction in the first 5 seconds?"
2. **Brand alignment**: "Does this feel like YOUR product?"
3. **Issues**: "Is there anything that feels wrong, missing, or not quite right?"

Do not ask "Do you like it?" -- this produces yes/no answers with no actionable information.

### Guiding the User Toward Useful Feedback

Developers often give feedback in implementation terms. Redirect toward design intent:

| User says | They likely mean | Follow-up to ask |
|-----------|-----------------|-----------------|
| "I don't like it" | Overall mismatch | "Is it the colors, the layout, or the overall mood that feels off?" |
| "It's boring" / "too plain" | Low visual energy | "Would you like more color contrast, a bolder layout, or both?" |
| "It's too busy" | Visual clutter | "Which part feels most cluttered? The hero, the features section, or everything?" |
| "It looks like a template" | Generic, no personality | "What would make it feel more specific to your product? A different layout, stronger colors, more distinctive typography?" |
| "It's too marketing-y" | Over-designed, too much flair | "Should we strip it down -- less decoration, more information density, tighter layout?" |
| "The colors are off" | Palette mismatch | "Too bright, too dull, or just the wrong hue?" |
| "More whitespace" / "too cramped" | Layout density | Edit: "Add more breathing room between sections" |
| "Needs more padding" / "font-size too small" | CSS-level observation | Translate: "Which section feels too tight or hard to read?" |
| "Make it pop" | Weak visual hierarchy | "What should stand out more -- the headline, the CTA button, or the overall contrast?" |
| "I love the layout but not the colors" | Partial approval | Variant signal: keep layout, change COLOR_SCHEME only |
| "Show me something totally different" | Fundamental rethink | REIMAGINE creative range |
| "Can I just edit the HTML?" | Wants direct control | "Stitch handles the regeneration cycle, so let's iterate here first -- then you can hand-edit the final output." |

### Design Dimensions to Highlight for the User

When presenting a design for review, draw the user's attention to specific elements. These help non-designers evaluate design without knowing design vocabulary:

- **Message clarity**: "Can a visitor tell what your product does within 5 seconds of landing here?"
- **CTA visibility**: "How quickly did your eye find the primary button? Could you miss it?"
- **Color impression**: "Do these colors match the feel you described -- {their 3 adjectives}?"
- **Reading flow**: "When you scan top to bottom, does the section order make sense for someone discovering your product?"
- **Credibility**: "If you were evaluating this product for the first time, does this page make it look like a real, maintained project?"

### Steering Toward Approval

- After positive-but-uncommitted feedback: "What's the one thing that would make this feel right?"
- After choosing from options: "Want me to tweak anything on this one, or lock it in?"
- After 3+ rounds of minor tweaks: "This is looking solid. Want to keep iterating or ship it and refine later?"
- After 5+ rounds: "What's the single most important change left? Let's nail that one thing."

Developers often prefer to ship something decent and iterate rather than perfecting before launch. If you sense this, offer the exit: "This is in a good place. Want me to bundle it so you can deploy and see how it looks in the real context?"

### Feedback Priority Framework

Help users separate critical from cosmetic:

1. **Must fix**: The page doesn't communicate what the product does, or the CTA is unclear/missing.
2. **Should improve**: The mood doesn't match the brand direction, or a section is missing/unnecessary.
3. **Nice to have**: Font weight preference, exact shade of a color, spacing tweaks.

Guide users to address category 1 first, then 2, then 3. This prevents endless loops on cosmetic details while structural problems persist.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)