sdd-jc-methodology 0.2.0

package/.claude/skills/stitch-design/README.md

@@ -0,0 +1,50 @@
+# Stitch Design Skill
+
+Teaches agents to generate high-fidelity, consistent UI designs and maintain project-level design systems using Stitch.
+
+## Install
+
+```bash
+npx skills add google-labs-code/stitch-skills --skill stitch-design --global
+```
+
+## What It Does
+
+Enables professional-grade UI/UX design workflows through Stitch MCP:
+
+1. **Prompt Enhancement**: Transforms rough intent into structured, high-fidelity prompts with professional terminology and design system context.
+2. **Design System Synthesis**: Analyzes existing Stitch projects to create and maintain a `.stitch/DESIGN.md` "source of truth".
+3. **Iterative Generation**: Selects the best generation or editing workflow (`edit_screens`, `generate_variants`) based on user intent.
+4. **Asset Management**: Synchronizes remote designs by downloading HTML and screenshots to the project's `.stitch/designs` directory.
+
+## Prerequisites
+
+- Stitch MCP Server access
+- A project `projectId` (can be discovered via `list_projects`)
+
+## Example Prompt
+
+```text
+Design a premium landing page for a mountain resort with a focus on serene luxury and glassmorphism.
+```
+
+## Skill Structure
+
+```
+stitch-design/
+├── SKILL.md           — Core instructions & Prompt Pipeline
+├── README.md          — This file
+├── workflows/         — Specialized pipelines (Text-to-UI, Edit, MD)
+├── references/        — UI/UX keywords & Technical Mappings
+└── examples/          — Gold-standard references (Solace Mindfulness)
+```
+
+## Works With
+
+- **`react:components` skill**: Hand-off generated designs for frontend implementation.
+- **`stitch-loop` skill**: Provides the `DESIGN.md` context for autonomous building loops.
+- **Multi-agent workflows**: Refines prompts before passing design tasks to specialized agents.
+
+## Learn More
+
+See [SKILL.md](./SKILL.md) for complete instructions.

package/.claude/skills/stitch-design/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: stitch-design
+description: Unified entry point for Stitch design work. Handles prompt enhancement (UI/UX keywords, atmosphere), design system synthesis (.stitch/DESIGN.md), and high-fidelity screen generation/editing via Stitch MCP.
+allowed-tools:
+  - "StitchMCP"
+  - "Read"
+  - "Write"
+---
+
+# Stitch Design Expert
+
+You are an expert Design Systems Lead and Prompt Engineer specializing in the **Stitch MCP server**. Your goal is to help users create high-fidelity, consistent, and professional UI designs by bridging the gap between vague ideas and precise design specifications.
+
+## Core Responsibilities
+
+1.  **Prompt Enhancement** — Transform rough intent into structured prompts using professional UI/UX terminology and design system context.
+2.  **Design System Synthesis** — Analyze existing Stitch projects to create `.stitch/DESIGN.md` "source of truth" documents.
+3.  **Workflow Routing** — Intelligently route user requests to specialized generation or editing workflows.
+4.  **Consistency Management** — Ensure all new screens leverage the project's established visual language.
+5.  **Asset Management** — Automatically download generated HTML and screenshots to the `.stitch/designs` directory.
+
+---
+
+## 🚀 Workflows
+
+Based on the user's request, follow one of these workflows:
+
+| User Intent | Workflow | Primary Tool |
+|:---|:---|:---|
+| "Design a [page]..." | [text-to-design](workflows/text-to-design.md) | `generate_screen_from_text` + `Download` |
+| "Edit this [screen]..." | [edit-design](workflows/edit-design.md) | `edit_screens` + `Download` |
+| "Create/Update .stitch/DESIGN.md" | [generate-design-md](workflows/generate-design-md.md) | `get_screen` + `Write` |
+
+---
+
+## 🎨 Prompt Enhancement Pipeline
+
+Before calling any Stitch generation or editing tool, you MUST enhance the user's prompt.
+
+### 1. Analyze Context
+- **Project Scope**: Maintain the current `projectId`. Use `list_projects` if unknown.
+- **Design System**: Check for `.stitch/DESIGN.md`. If it exists, incorporate its tokens (colors, typography). If not, suggest the `generate-design-md` workflow.
+
+### 2. Refine UI/UX Terminology
+Consult [Design Mappings](references/design-mappings.md) to replace vague terms.
+- Vague: "Make a nice header"
+- Professional: "Sticky navigation bar with glassmorphism effect and centered logo"
+
+### 3. Structure the Final Prompt
+Format the enhanced prompt for Stitch like this:
+
+```markdown
+[Overall vibe, mood, and purpose of the page]
+
+**DESIGN SYSTEM (REQUIRED):**
+- Platform: [Web/Mobile], [Desktop/Mobile]-first
+- Palette: [Primary Name] (#hex for role), [Secondary Name] (#hex for role)
+- Styles: [Roundness description], [Shadow/Elevation style]
+
+**PAGE STRUCTURE:**
+1. **Header:** [Description of navigation and branding]
+2. **Hero Section:** [Headline, subtext, and primary CTA]
+3. **Primary Content Area:** [Detailed component breakdown]
+4. **Footer:** [Links and copyright information]
+```
+
+### 4. Present AI Insights
+After any tool call, always surface the `outputComponents` (Text Description and Suggestions) to the user.
+
+---
+
+## 📚 References
+
+- [Tool Schemas](references/tool-schemas.md) — How to call Stitch MCP tools.
+- [Design Mappings](references/design-mappings.md) — UI/UX keywords and atmosphere descriptors.
+- [Prompting Keywords](references/prompt-keywords.md) — Technical terms Stitch understands best.
+
+---
+
+## 💡 Best Practices
+
+- **Iterative Polish**: Prefere `edit_screens` for targeted adjustments over full re-generation.
+- **Semantic First**: Name colors by their role (e.g., "Primary Action") as well as their appearance.
+- **Atmosphere Matters**: Explicitly set the "vibe" (Minimalist, Vibrant, Brutalist) to guide the generator.

package/.claude/skills/stitch-design/examples/DESIGN.md

@@ -0,0 +1,22 @@
+---
+# The "Solace" Design System
+This is a comprehensive design language for a mindfulness and wellness application.
+
+## 🎨 Color Palette
+- **Primary**: Deep Ocean Blue (#1a365d) - for critical navigation and CTAs.
+- **Secondary**: Calm Slate (#718096) - for subtexts and secondary buttons.
+- **Background**: Soft Mist (#f7fafc) - for main page content.
+- **Accent**: Serene Emerald (#38a169) - for positive feedback and completion states.
+
+## 🔡 Typography
+- **Heading**: Montserrat, Bold - for titles and hero section headlines.
+- **Body**: Inter, Regular - for descriptions and general content.
+- **Size**: 16px as base, 48px for H1.
+
+## 📐 Components
+- **Buttons**: Rounded (12px), subtle hover shadow (4px blur).
+- **Cards**: Minimal border (1px, #e2e8f0), soft shadow (8px elevation).
+- **Navigation**: Clean, top-aligned, centered menu items.
+
+---
+💡 **Tip**: When calling `generate_screen_from_text`, include the tokens above to ensure the new screen matches this design system.

package/.claude/skills/stitch-design/examples/enhanced-prompt.md

@@ -0,0 +1,28 @@
+# Example: Prompt Enhancement
+
+## User Input (Vague)
+> "Make a landing page for my fitness app called 'Pulse'. Use red and black. It should have a place for features and a hero section."
+
+---
+
+## Enhanced Prompt (Stitch-Optimized)
+**Overall Purpose**: A high-energy, modern landing page for 'Pulse', a fitness tracking application. The vibe is powerful, motivating, and high-performance.
+
+**DESIGN SYSTEM (REQUIRED):**
+- **Primary Color**: Racing Red (#e11d48) for CTA buttons and active states.
+- **Secondary Color**: Deep Obsidian (#0f172a) for background and text containers.
+- **Typography**: Bold, condensed sans-serif headings (e.g., Impact or Inter Tight) to convey speed and strength.
+- **Style**: Hard edges with sharp, minimal borders; high contrast; dark mode by default.
+
+**PAGE STRUCTURE:**
+1. **Header**: Minimalist navigation with Pulse logo (left) and "Start Training" primary button (right).
+2. **Hero Section**: Large, emotive fitness photography background. Headline: "Elevate Every Beat." Sub-headline: "Track, analyze, and crush your fitness goals with Pulse." Primary red CTA: "Get Started".
+3. **Feature Grid**: Three-column layout highlighting:
+    - **Real-time Tracking**: Live stats from your wearable.
+    - **AI Coaching**: Personalized workouts based on your performance.
+    - **Community Challenges**: Compete with friends and stay motivated.
+4. **Social Proof Section**: Subtle slider showing "Trusted by 500,000+ athletes".
+5. **Footer**: Quick links (Training, Pricing, Support), social icons, and legal.
+
+---
+💡 **Tip**: Notice how the enhanced prompt adds specific hex codes, defines the typography "vibe", and breaks the page into a logical numbered structure. This gives Stitch much clearer instructions.

package/.claude/skills/stitch-design/references/design-mappings.md

@@ -0,0 +1,45 @@
+# Design Mappings & Descriptors
+
+Use these mappings to transform vague user requests into precise, high-fidelity design instructions.
+
+## UI/UX Keyword Refinement
+
+| Vague Term | Enhanced Professional Terminology |
+|:---|:---|
+| "menu at the top" | "sticky navigation bar with logo and list items" |
+| "big photo" | "high-impact hero section with full-width imagery" |
+| "list of things" | "responsive card grid with hover states and subtle elevations" |
+| "button" | "primary call-to-action button with micro-interactions" |
+| "form" | "clean form with labeled input fields, validation states, and submit button" |
+| "picture area" | "hero section with focal-point image or video background" |
+| "sidebar" | "collapsible side navigation with icon-label pairings" |
+| "popup" | "modal dialog with overlay and smooth entry animation" |
+
+## Atmosphere & "Vibe" Descriptors
+
+Add these adjectives to set the mood and aesthetic philosophy:
+
+| Basic Vibe | Enhanced Design Description |
+|:---|:---|
+| "Modern" | "Clean, minimal, with generous whitespace and high-contrast typography." |
+| "Professional" | "Sophisticated, trustworthy, utilizing subtle shadows and a restricted, premium palette." |
+| "Fun / Playful" | "Vibrant, organic, with rounded corners, bold accent colors, and bouncy micro-animations." |
+| "Dark Mode" | "Electric, high-contrast accents on deep slate or near-black backgrounds." |
+| "Luxury" | "Elegant, spacious, with fine lines, serif headers, and a focus on high-fidelity photography." |
+| "Tech / Cyber" | "Futuristic, neon accents, glassmorphism effects, and technological monospaced typography." |
+
+## Geometry & Shape Translation
+
+Convert technical values into physical descriptions for Stitch:
+
+- **Pill-shaped**: Used for `rounded-full` elements (buttons, tags).
+- **Softly rounded**: Used for `rounded-xl` (12px) or `rounded-2xl` (16px) containers.
+- **Sharp/Precise**: Used for `rounded-none` or `rounded-sm` elements.
+- **Glassmorphism**: Semi-transparent surfaces with background blur and thin borders.
+
+## Depth & Elevation
+
+- **Flat**: No shadows, focus on color blocking and borders.
+- **Whisper-soft**: Diffused, light shadows for subtle lift.
+- **Floating**: High-offset, soft shadows for elements that appear high above the surface.
+- **Inset**: Inner shadows for pressable or nested elements.

package/.claude/skills/stitch-design/references/prompt-keywords.md

@@ -0,0 +1,114 @@
+# UI/UX Keywords Reference
+
+Progressive disclosure reference for common UI terminology and adjective palettes.
+
+## Component Keywords
+
+### Navigation
+- navigation bar, nav menu, header
+- breadcrumbs, tabs, sidebar
+- hamburger menu, dropdown menu
+- back button, close button
+
+### Content Containers
+- hero section, hero banner
+- card, card grid, tile
+- modal, dialog, popup
+- accordion, collapsible section
+- carousel, slider
+
+### Forms
+- input field, text input
+- dropdown, select menu
+- checkbox, radio button
+- toggle switch
+- date picker, time picker
+- search bar, search input
+- submit button, form actions
+
+### Calls to Action
+- primary button, secondary button
+- ghost button, text link
+- floating action button (FAB)
+- icon button
+
+### Feedback
+- toast notification, snackbar
+- alert banner, warning message
+- loading spinner, skeleton loader
+- progress bar, step indicator
+
+### Layout
+- grid layout, flexbox
+- sidebar layout, split view
+- sticky header, fixed footer
+- full-width, contained width
+- centered content, max-width container
+
+## Adjective Palettes
+
+### Minimal / Clean
+- minimal, clean, uncluttered
+- generous whitespace, breathing room
+- subtle, understated, refined
+- simple, focused, distraction-free
+
+### Professional / Corporate
+- sophisticated, polished, trustworthy
+- corporate, business-like, formal
+- subtle shadows, clean lines
+- structured, organized, hierarchical
+
+### Playful / Fun
+- vibrant, colorful, energetic
+- rounded corners, soft edges
+- bold, expressive, dynamic
+- friendly, approachable, warm
+
+### Premium / Luxury
+- elegant, luxurious, high-end
+- dramatic, bold contrasts
+- sleek, modern, cutting-edge
+- exclusive, boutique, curated
+
+### Dark Mode
+- dark theme, night mode
+- high-contrast accents
+- soft glows, subtle highlights
+- deep backgrounds, muted surfaces
+
+### Organic / Natural
+- earthy tones, natural colors
+- warm, inviting, cozy
+- textured, tactile, handcrafted
+- flowing, organic shapes
+
+## Color Role Terminology
+
+### Backgrounds
+- page background, canvas
+- surface color, card background
+- overlay, scrim
+
+### Text
+- primary text, heading color
+- secondary text, body copy
+- muted text, placeholder
+- inverse text (on dark backgrounds)
+
+### Accents
+- primary accent, brand color
+- secondary accent, highlight
+- success, error, warning colors
+- hover state, active state
+
+## Shape Descriptions
+
+| Technical | Natural Language |
+|-----------|------------------|
+| `rounded-none` | sharp, squared-off edges |
+| `rounded-sm` | slightly softened corners |
+| `rounded-md` | gently rounded corners |
+| `rounded-lg` | generously rounded corners |
+| `rounded-xl` | very rounded, pillow-like |
+| `rounded-full` | pill-shaped, circular |

package/.claude/skills/stitch-design/references/tool-schemas.md

@@ -0,0 +1,76 @@
+# Stitch MCP Tool Schemas
+
+Use these examples to format your tool calls to the Stitch MCP server correctly.
+
+---
+
+## 🏗️ Project Management
+
+### `list_projects`
+Lists all Stitch projects accessible to you.
+```json
+// No parameters needed
+{}
+```
+
+### `get_project`
+Retrieves details of a specific project.
+```json
+{
+  "name": "projects/4044680601076201931"
+}
+```
+
+### `create_project`
+Creates a new Stitch project.
+```json
+{
+  "title": "My New App"
+}
+```
+
+---
+
+## 🎨 Design Generation
+
+### `generate_screen_from_text`
+Generates a new screen from a text description.
+```json
+{
+  "projectId": "4044680601076201931",
+  "prompt": "A modern landing page for a coffee shop with a hero section, menu, and contact form. Use warm brown tones (#4b2c20) and a clean sans-serif font.",
+  "deviceType": "DESKTOP" // Options: MOBILE, DESKTOP, TABLET
+}
+```
+
+### `edit_screens`
+Edits existing screens with a text prompt.
+```json
+{
+  "projectId": "4044680601076201931",
+  "selectedScreenIds": ["98b50e2ddc9943efb387052637738f61"],
+  "prompt": "Change the background color to white (#ffffff) and make the call-to-action button larger."
+}
+```
+
+---
+
+## 🖼️ Screen Management
+
+### `list_screens`
+Lists all screens within a project.
+```json
+{
+  "projectId": "4044680601076201931"
+}
+```
+
+### `get_screen`
+Retrieves details of a specific screen.
+```json
+{
+  "projectId": "4044680601076201931",
+  "screenId": "98b50e2ddc9943efb387052637738f61",
+  "name": "projects/4044680601076201931/screens/98b50e2ddc9943efb387052637738f61"
+}
+```

package/.claude/skills/stitch-design/workflows/edit-design.md

@@ -0,0 +1,44 @@
+---
+description: Edit an existing design screen using Stitch MCP.
+---
+
+# Workflow: Edit-Design
+
+Make targeted changes to an already generated design.
+
+## Steps
+
+### 1. Identify the Screen
+Use `list_screens` or `get_screen` to find the correct `projectId` and `screenId`.
+
+### 2. Formulate the Edit Prompt
+Be specific about the changes you want to make. Do not just say "fix it". 
+- **Location**: "Change the color of the [primary button] in the [hero section]..."
+- **Visuals**: "...to a darker blue (#004080) and add a subtle shadow."
+- **Structure**: "Add a secondary button next to the primary one with the text 'Learn More'."
+
+### 3. Apply the Edit
+Call the `mcp_StitchMCP_edit_screens` tool.
+
+```json
+{
+  "projectId": "...",
+  "selectedScreenIds": ["..."],
+  "prompt": "[Your target edit prompt]"
+}
+```
+
+### 4. Present AI Feedback
+Always show the text description and suggestions from `outputComponents` to the user.
+
+### 5. Download Design Assets
+After editing, download the updated HTML and screenshot urls from `outputComponents` to the `.stitch/designs` directory, overwriting previous versions to ensure the local files reflect the latest edits.
+
+### 6. Verify and Repeat
+- Check the output screen to see if the changes were applied correctly.
+- If more polish is needed, repeat the process with a new specific prompt.
+
+## Tips
+- **Keep it focused**: One edit at a time is often better than a long list of changes.
+- **Reference components**: Use professional terms like "navigation bar", "hero section", "footer", "card grid".
+- **Mention colors**: Use hex codes for precise color matching.

package/.claude/skills/stitch-design/workflows/generate-design-md.md

@@ -0,0 +1,63 @@
+---
+description: Analyze a Stitch project and synthesize its design system into a .stitch/DESIGN.md file.
+---
+
+# Workflow: Generate .stitch/DESIGN.md
+
+Create a "source of truth" for your project's design language to ensure consistency across all future screens.
+
+## 📥 Retrieval
+
+To analyze a Stitch project, you must retrieve metadata and assets using the Stitch MCP tools:
+
+1.  **Project lookup**: Use `list_projects` to find the target `projectId`.
+2.  **Screen lookup**: Use `list_screens` for that `projectId` to find representative screens (e.g., "Home", "Main Dashboard").
+3.  **Metadata fetch**: Call `get_screen` for the target screen to get `screenshot.downloadUrl` and `htmlCode.downloadUrl`.
+4.  **Asset download**: Use `read_url_content` to fetch the HTML code.
+
+## 🧠 Analysis & Synthesis
+
+### 1. Identify Identity
+- Capture Project Title and Project ID.
+
+### 2. Define Atmosphere
+- Analyze the HTML and screenshot to capture the "vibe" (e.g., "Airy," "Professional," "Vibrant").
+
+### 3. Map Color Palette
+- Extract exact hex codes and assign functional roles (e.g., "Primary Action: #2563eb").
+
+### 4. Translate Geometry
+- Convert Tailwind/CSS values into descriptive language (e.g., `rounded-full` → "Pill-shaped").
+
+### 5. Document Depth
+- Describe shadow styles and layering (e.g., "Soft, diffused elevation").
+
+## 📝 Output Structure
+
+Create a `.stitch/DESIGN.md` file in the project directory with this structure:
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [Insert Project ID Here]
+
+## 1. Visual Theme & Atmosphere
+(Description of mood and aesthetic philosophy)
+
+## 2. Color Palette & Roles
+(Descriptive Name + Hex Code + Role)
+
+## 3. Typography Rules
+(Font families, weights, and usage)
+
+## 4. Component Stylings
+* **Buttons:** Shape, color, behavior
+* **Containers:** Roundness, elevation
+
+## 5. Layout Principles
+(Whitespace strategy and grid alignment)
+```
+
+## 💡 Best Practices
+- **Be Precise**: Always include hex codes in parentheses.
+- **Be Descriptive**: Use natural language like "Deep Ocean Blue" instead of just "Blue".
+- **Be Functional**: Explain *why* an element is used.

package/.claude/skills/stitch-design/workflows/text-to-design.md

@@ -0,0 +1,47 @@
+---
+description: Generate new screens from a text prompt using Stitch MCP.
+---
+
+# Workflow: Text-to-Design
+
+Transform a text description into a high-fidelity design screen.
+
+## Steps
+
+### 1. Enhance the User Prompt
+Before calling the Stitch MCP tool, apply the [Prompt Enhancement Pipeline](../SKILL.md#prompt-enhancement-pipeline). 
+- Identify the platform (Web/Mobile) and page type.
+- Incorporate any existing project design system from `.stitch/DESIGN.md`.
+- Use specific [Design Mappings](../references/design-mappings.md) and [Prompting Keywords](../references/prompt-keywords.md).
+
+### 2. Identify the Project
+Use `list_projects` to find the correct `projectId` if it is not already known.
+
+### 3. Generate the Screen
+Call the `mcp_StitchMCP_generate_screen_from_text` tool with the enhanced prompt.
+
+```json
+{
+  "projectId": "...",
+  "prompt": "[Your Enhanced Prompt]",
+  "deviceType": "DESKTOP" // or MOBILE
+}
+```
+
+### 4. Present AI Feedback
+Always show the text description and suggestions from `outputComponents` to the user.
+
+### 5. Download Design Assets
+After generation, download the HTML and screenshot urls from `outputComponents` to the `.stitch/designs` directory.
+- **Naming**: Use the screen ID or a descriptive slug for the filename.
+- **Tools**: Use `curl -o` via `run_command` or similar.
+- **Directory**: Ensure `.stitch/designs` exists.
+
+### 6. Review and Refine
+- If the result is not exactly as expected, use the [edit-design](edit-design.md) workflow to make targeted adjustments.
+- Do NOT re-generate from scratch unless the fundamental layout is wrong.
+
+## Tips
+- **Be structural**: Break the page down into header, hero, features, and footer in your prompt.
+- **Specify colors**: Use hex codes for precision.
+- **Set the tone**: Explicitly mention if the design should be minimal, professional, or vibrant.