@polymorphism-tech/morph-spec 4.21.0 → 4.22.0

package/framework/standards/frontend/design-system/ai-image-generation.md

@@ -0,0 +1,244 @@
+# AI Image Generation
+
+> **Scope:** nextjs
+> **Layer:** 1 (load when relevant)
+> **Keywords:** image, gemini, asset, ai-generation, placeholder, mcp, next/image
+> **Load When:** feature has UI components requiring image assets
+
+## When to Use AI-Generated Images
+
+| Use Case | Approach | Examples |
+|----------|----------|---------|
+| **AI generation** | Gemini Image MCP | Hero images, brand illustrations, feature-specific visuals, empty states, background panels |
+| **Stock photos** | External sources | Generic content (people in offices, nature scenes, stock portraits) |
+| **SVG/CSS** | Code-based | Icons, patterns, gradients, geometric shapes, loading animations |
+| **Skip** | Other tools | Screenshots (Playwright), diagrams (Mermaid), logos (vector tools) |
+
+**Decision rule:** If the image is unique to the project's brand/aesthetic and doesn't exist as stock, use AI generation. If it's generic and widely available, use stock. If it's geometric or icon-based, use SVG/CSS.
+
+## Gemini Image MCP API
+
+```javascript
+// Generate a new image
+mcp__gemini_image_mcp__generate_image({
+  prompt: string,           // Text description (max 5000 chars, narrative style)
+  aspectRatio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "9:16" | "16:9",
+  outputPath?: string,      // File path to save (e.g., "public/images/feature/hero.png")
+  model?: string,           // Default: gemini-2.5-flash-image
+})
+
+// Edit an existing image
+mcp__gemini_image_mcp__edit_image({
+  imageSource: string,      // Path to image or image ID
+  prompt: string,           // Short, targeted edit instructions (1-2 sentences)
+  outputPath?: string,
+})
+
+// Continue editing last image
+mcp__gemini_image_mcp__continue_editing({
+  prompt: string,           // One adjustment at a time
+})
+
+// List generated images
+mcp__gemini_image_mcp__list_images({
+  type?: "generated" | "edited" | "all",
+  limit?: number,
+})
+
+// Get image details
+mcp__gemini_image_mcp__get_image_info({
+  imageId?: string,         // Defaults to last image
+})
+```
+
+## Prompt Engineering Patterns
+
+### Design-System-Aware Prompts
+
+Read `design-system.md` or `globals.css` to extract project tokens. Inject into prompts:
+
+- **Background color** → use as image background
+- **Primary/accent colors** → use as highlight colors
+- **Font pair** → mention for text elements
+- **Aesthetic direction** → "Modern Luxury", "Kinetic Atelier", etc.
+
+```
+"{subject description}. Dark charcoal background (#10131a) with copper (#D2802D)
+and gold (#FFB779) accent colors. {style modifiers}. Premium luxury aesthetic.
+{composition rules}."
+```
+
+### Component-Contextual Prompts
+
+Describe what the image will BE in the UI, not just the subject:
+
+- **Hero image** → "floating tablet showing app dashboard on dark background" (not just "fitness dashboard")
+- **Auth background** → "gym equipment with moody lighting" (matches brand feel)
+- **Empty state** → "artistic wireframe body silhouette" (matches feature context)
+
+### Narrative Style
+
+Gemini responds best to coherent paragraphs. Build prompts by layering:
+
+1. **Subject** — hyper-specific description
+2. **Environment** — foreground, mid-ground, background (layered for depth)
+3. **Lighting** — multiple sources with different colors/directions
+4. **Style** — photography terms ("85mm portrait lens") or art style ("cel-shaded")
+5. **Color palette** — dominant colors and contrast relationships
+6. **Composition** — camera angle, framing, negative space
+
+**Never:** keyword spam ("beautiful, stunning, 4k, masterpiece"), JSON prompts, negative prompts ("no cars").
+
+## Iterative Editing Workflows
+
+**Cardinal rule: generation demands depth; editing demands restraint.**
+
+### Adding / Removing Elements
+One sentence. Don't describe how to integrate — the model handles that.
+```
+"Add a knitted wizard hat to the cat."
+```
+
+### Background Replacement
+State the new background simply. Don't over-describe.
+```
+"Replace the background with a tropical beach at sunset."
+```
+
+### Inpainting (Targeted Changes)
+Name what changes and what stays in one line.
+```
+"Change the blue sofa to a brown leather chesterfield. Keep everything else."
+```
+
+### Style Transfer
+Name the target style.
+```
+"Transform this into Van Gogh's Starry Night style."
+```
+
+### Iterative Refinement with `continue_editing`
+One change at a time:
+- "Make the lighting warmer"
+- "More contrast in the shadows"
+- "Zoom out a bit"
+- "More serious expression"
+
+### Text Rendering
+The model frequently misspells words. After generating any image with text:
+1. View the result
+2. If text is wrong: `continue_editing` with "Fix the text — it should read '{correct text}' exactly. Keep everything else."
+3. Expect 2-3 iterations for correct text
+
+## Aspect Ratio Guide
+
+| Use Case | Ratio | Examples |
+|----------|-------|---------|
+| Hero / banner | `16:9` | Landing page hero, YouTube thumbnail, desktop wallpaper |
+| Card / blog header | `3:2` | Feature cards, blog post headers, landscape photo |
+| Avatar / icon | `1:1` | Profile pictures, social media posts, square icons |
+| Auth panel / sidebar | `3:4` | Login brand image, Pinterest-style, portrait poster |
+| Portrait | `2:3` | Book cover, tall illustration, portrait photo |
+| Story / reel | `9:16` | Mobile wallpaper, social story, vertical banner |
+| Standard display | `4:3` | Documentation, slides, standard display |
+
+## File Naming & Directory
+
+**Convention:** `public/images/{feature}/{purpose}.png`
+
+- Lowercase, kebab-case, descriptive names
+- Group by feature, not by type
+- Examples:
+  - `public/images/ui-redesign/hero-mockup.png`
+  - `public/images/ui-redesign/gym-equipment.png`
+  - `public/images/ui-redesign/body-analysis.png`
+
+## Next.js Image Integration
+
+```tsx
+import Image from 'next/image';
+
+// Above-the-fold hero image (priority for LCP)
+<Image
+  src="/images/{feature}/hero-mockup.png"
+  alt="AI fitness analysis dashboard"
+  width={1440}
+  height={810}
+  priority
+  sizes="100vw"
+/>
+
+// Card image with responsive sizing
+<Image
+  src="/images/{feature}/card-image.png"
+  alt="Feature card illustration"
+  width={600}
+  height={400}
+  sizes="(max-width: 768px) 100vw, 50vw"
+  className="rounded-lg"
+/>
+
+// Background image with fill
+<div className="relative h-full">
+  <Image
+    src="/images/{feature}/auth-background.png"
+    alt=""
+    fill
+    className="object-cover"
+    priority={false}
+  />
+</div>
+```
+
+## `assets.md` Format
+
+The `assets.md` file is created during the UI/UX phase (Step 4.5) and consumed by the implement phase.
+
+```markdown
+# Image Assets — {feature}
+
+## Design Context
+- Aesthetic: {from design-system.md}
+- Primary: {--color-primary value}
+- Background: {--color-background value}
+- Accent: {--color-accent value}
+- Font pair: {display + body fonts}
+
+## Assets
+
+### IMG-001: {Descriptive Name}
+- **Purpose:** {What this image represents in the UI}
+- **Route:** {App route where it appears}
+- **Component:** {React component name}
+- **Aspect Ratio:** {1:1 | 3:2 | 16:9 | etc.}
+- **Output Path:** `public/images/{feature}/{kebab-name}.png`
+- **Prompt:** "{Narrative prompt with design system colors and aesthetic direction injected}"
+- **Priority:** {high | medium | low}
+```
+
+**Example entry:**
+
+```markdown
+### IMG-001: Hero Mockup
+- **Purpose:** App dashboard floating on dark background for landing page hero
+- **Route:** /
+- **Component:** HeroSection
+- **Aspect Ratio:** 16:9
+- **Output Path:** `public/images/ui-redesign/hero-mockup.png`
+- **Prompt:** "A floating tablet showing a modern AI fitness analysis dashboard on a dark charcoal background (#10131a). Copper (#D2802D) and gold (#FFB779) accent lighting creates warm rim highlights around the device edges. The screen displays body metrics with glassmorphism cards. Premium luxury aesthetic, photorealistic, cinematic lighting with a key light from the left and cool blue fill from the right."
+- **Priority:** high
+```
+
+## Quality Checklist
+
+- [ ] Colors match design system tokens (no random colors in prompts)
+- [ ] No text artifacts or misspellings (if text in image)
+- [ ] Correct aspect ratio for intended use
+- [ ] Appropriate file size (< 500KB for web, < 200KB for cards)
+- [ ] Descriptive alt text written for accessibility
+- [ ] `<Image>` component with proper width/height dimensions
+- [ ] `priority` prop set for above-the-fold images
+- [ ] Build compiles after integration (`npm run build`)
+- [ ] Image visible in dev server at correct route
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/integration/mcp/mcp-tools.md

@@ -81,6 +81,53 @@ const docs = await mcp__context7__query_docs({
 // WebFetch for specific component API pages
 ```
 
+### Gemini Image MCP — AI Image Generation
+
+> Available in: **UI/UX** (preview generation), **Implement** (production assets)
+
+| Tool | Use Case | Example |
+|------|----------|---------|
+| `generate_image` | Create new image from text prompt | `mcp__gemini-image-mcp__generate_image({ prompt, aspectRatio, outputPath })` |
+| `edit_image` | Modify existing image | `mcp__gemini-image-mcp__edit_image({ imageSource, prompt })` |
+| `continue_editing` | Iterate on last generated/edited image | `mcp__gemini-image-mcp__continue_editing({ prompt })` |
+| `list_images` | Browse image generation history | `mcp__gemini-image-mcp__list_images({ type: "all" })` |
+| `get_image_info` | Get metadata about a specific image | `mcp__gemini-image-mcp__get_image_info({ imageId })` |
+
+```javascript
+// Generate a hero image using design system tokens
+// Read design-system.md first to get project colors and aesthetic direction
+const image = await mcp__gemini_image_mcp__generate_image({
+  prompt: "A floating tablet showing a modern dashboard interface on a dark charcoal background with copper and gold accent lighting. Premium luxury aesthetic, photorealistic, cinematic lighting with warm rim light.",
+  aspectRatio: "16:9",
+  outputPath: "public/images/my-feature/hero-mockup.png"
+});
+
+// Edit an existing image (keep edits short and targeted)
+await mcp__gemini_image_mcp__edit_image({
+  imageSource: "public/images/my-feature/hero-mockup.png",
+  prompt: "Make the lighting warmer and add a subtle copper glow around the tablet edges."
+});
+
+// Iterate with continue_editing (one change at a time)
+await mcp__gemini_image_mcp__continue_editing({
+  prompt: "More contrast in the shadows."
+});
+
+// Fallback: Manual image creation, stock photos, or placeholder divs
+```
+
+**Use cases by phase:**
+
+| Phase | Use Case | Tool |
+|-------|----------|------|
+| UI/UX (2) | Generate preview images for design approval | `generate_image` |
+| Implement (7) | Generate production assets from assets.md specs | `generate_image` + `edit_image` |
+| Implement (7) | Iterate on generated images for quality | `continue_editing` |
+
+> **Standard:** See `frontend/design-system/ai-image-generation.md` for prompt engineering patterns, aspect ratio guide, and `assets.md` format.
+
+---
+
 ### Phase 3 (Design) — Schema & Architecture
 
 | Tool | Use Case | Example |
@@ -246,6 +293,7 @@ await mcp__vercel__manage_env_vars({
 | Container ops | Docker CLI (`docker ps`, `docker logs`, `docker compose`) | — |
 | Cloud resources | Azure CLI (`az resource`, `az deployment`) | — |
 | Vercel deployments | Vercel MCP | Bash `vercel` CLI |
+| AI image generation | Gemini Image MCP | Manual creation or stock photos |
 
 **Rule:** MCP tools provide structured data (JSON responses). Native tools require manual parsing. **Always prefer MCP when available** — fall back to native when not. **Exceptions:** Neon, Docker, and Azure always use their respective CLIs directly — never MCP.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",

package/src/core/paths/output-schema.js

@@ -35,6 +35,7 @@ export const OUTPUT_SCHEMA = {
   uiMockups:     { filename: 'mockups.md',          phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiComponents:  { filename: 'components.md',       phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiFlows:       { filename: 'flows.md',            phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  stitchHtml:    { filename: 'stitch-screen-map.json', phaseDir: '1-ui',   phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   decisions:     { filename: 'decisions.md',        phaseDir: '2-design',    phase: 'design',    protected: false },
   recap:         { filename: 'recap.md',            phaseDir: '5-implement', phase: 'implement', protected: false },
 };

package/src/lib/agents/output-collector.js

@@ -26,6 +26,7 @@ export const SOURCE_WEIGHTS = {
   uiMockups:      1.0,
   uiComponents:   1.0,
   uiFlows:        1.0,
+  stitchHtml:     1.0,
   recap:          1.0,
 };