medesign 0.0.0-stage → 1.2.0

package/references/social-photos-design.md

@@ -0,0 +1,329 @@
+# Social Photos Design Guide
+
+Design social media images via HTML/CSS rendering + screenshot export. Orchestrates the bundled `ui-ux-pro-max`, `brand`, and `design-system` skills; screenshot export runs through Chrome headless, Playwright, or Puppeteer.
+
+## Platform Sizes
+
+| Platform | Type | Size (px) | Aspect |
+|----------|------|-----------|--------|
+| Instagram | Post | 1080 x 1080 | 1:1 |
+| Instagram | Story/Reel | 1080 x 1920 | 9:16 |
+| Instagram | Carousel | 1080 x 1350 | 4:5 |
+| Facebook | Post | 1200 x 630 | ~1.9:1 |
+| Facebook | Story | 1080 x 1920 | 9:16 |
+| Twitter/X | Post | 1200 x 675 | 16:9 |
+| Twitter/X | Card | 800 x 418 | ~1.91:1 |
+| LinkedIn | Post | 1200 x 627 | ~1.91:1 |
+| LinkedIn | Article | 1200 x 644 | ~1.86:1 |
+| Pinterest | Pin | 1000 x 1500 | 2:3 |
+| YouTube | Thumbnail | 1280 x 720 | 16:9 |
+| TikTok | Cover | 1080 x 1920 | 9:16 |
+| Threads | Post | 1080 x 1080 | 1:1 |
+
+## Workflow
+
+### Step 1: Plan the Work
+
+Create TODO tasks with the runtime's native task list. Break down into:
+- Requirement analysis task
+- Idea generation task(s)
+- HTML design task(s) — can parallelize per size/variant
+- Screenshot export task(s) — can parallelize per file
+- Report generation task
+
+Spawn parallel subagents for independent tasks (e.g., multiple HTML files for different sizes).
+
+### Step 2: Analyze Requirements
+
+Parse user input for:
+- **Subject/topic** — what the social photo represents
+- **Target platforms** — which sizes needed (default: Instagram Post 1:1 + Story 9:16)
+- **Visual style** — minimalist, bold, gradient, photo-based, etc.
+- **Brand context** — read from `docs/brand-guidelines.md` if exists
+- **Content elements** — headline, subtext, CTA, images, icons
+- **Quantity** — how many variations (default: 3)
+
+### Step 3: Generate Ideas
+
+Create 3-5 concept ideas that:
+- Match the input prompt/requirements
+- Consider platform-specific best practices
+- Vary in composition, color, typography approach
+- Align with brand guidelines if available
+
+Present ideas to user via `AskUserQuestion` for approval before designing.
+
+### Step 4: Design HTML Files
+
+Use these bundled skills in sequence:
+
+1. **`brand`** — Extract brand colors, fonts, voice from user's project
+2. **`design-system`** — Get design tokens (spacing, typography scale, color palette)
+3. **`ui-ux-pro-max`** — Layout, hierarchy, visual balance; search a different style, palette, or font pairing per concept for design variety.
+
+For each approved idea + each target size, create an HTML file:
+
+```
+output/social-photos/
+├── idea-1-instagram-post-1080x1080.html
+├── idea-1-instagram-story-1080x1920.html
+├── idea-2-instagram-post-1080x1080.html
+├── idea-2-instagram-story-1080x1920.html
+└── ...
+```
+
+#### HTML Design Rules
+
+- **Viewport** — Set exact pixel dimensions matching target size
+- **Self-contained** — Inline all CSS, embed fonts via Google Fonts CDN
+- **No scrolling** — Everything fits in one viewport
+- **High contrast** — Text readable at thumbnail size
+- **Brand-aligned** — Use extracted brand colors/fonts
+- **Safe zones** — Critical content within central 80% area
+- **Typography** — Min 24px for headlines, min 16px for body at 1080px width
+- **Visual hierarchy** — One focal point, clear reading flow
+
+#### HTML Template Structure
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width={WIDTH}, initial-scale=1.0">
+  <link href="https://fonts.googleapis.com/css2?family={FONT}&display=swap" rel="stylesheet">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body {
+      width: {WIDTH}px;
+      height: {HEIGHT}px;
+      overflow: hidden;
+      font-family: '{FONT}', sans-serif;
+    }
+    .canvas {
+      width: {WIDTH}px;
+      height: {HEIGHT}px;
+      position: relative;
+      /* Background: gradient, solid, or image */
+    }
+    /* Design tokens from brand/design-system */
+  </style>
+</head>
+<body>
+  <div class="canvas">
+    <!-- Content layers -->
+  </div>
+</body>
+</html>
+```
+
+### Step 5: Screenshot Export
+
+Use Chrome headless, Playwright, or Puppeteer to capture exact-size screenshots.
+
+**IMPORTANT:** Always add a delay (3-5s) after page load for fonts/images to fully render before capture.
+
+#### Option A: Chrome Headless CLI (Recommended — zero dependencies)
+
+```bash
+CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+DELAY=5  # seconds for fonts/images to load
+
+"$CHROME" \
+  --headless \
+  --disable-gpu \
+  --no-sandbox \
+  --hide-scrollbars \
+  --window-size="${WIDTH},${HEIGHT}" \
+  --virtual-time-budget=$((DELAY * 1000)) \
+  --screenshot="output.png" \
+  "file:///path/to/file.html"
+```
+
+Key flags:
+- `--virtual-time-budget=5000` — waits 5s virtual time for assets (Google Fonts, images) to load
+- `--hide-scrollbars` — prevents scrollbar artifacts in screenshots
+- `--window-size=WxH` — sets exact pixel dimensions
+
+#### Option B: Browser automation provided by the runtime
+
+If the runtime offers a browser-automation or screenshot capability (for example a browser MCP server), use it to:
+1. Open each HTML file in browser
+2. Set viewport to exact target dimensions
+3. Wait 3-5s for fonts/images to fully load
+4. Screenshot full page to PNG
+5. Save to `output/social-photos/exports/`
+
+#### Option C: Playwright script
+
+```javascript
+const { chromium } = require('playwright');
+
+async function captureScreenshots(htmlFiles) {
+  const browser = await chromium.launch();
+
+  for (const file of htmlFiles) {
+    const [width, height] = file.match(/(\d+)x(\d+)/).slice(1).map(Number);
+
+    const page = await browser.newPage();
+    await page.setViewportSize({ width, height });
+    await page.goto(`file://${file}`, { waitUntil: 'networkidle' });
+    // Wait for fonts/images to fully render
+    await page.waitForTimeout(3000);
+
+    const outputPath = file.replace('.html', '.png').replace('social-photos/', 'social-photos/exports/');
+    await page.screenshot({ path: outputPath, type: 'png' });
+    await page.close();
+  }
+
+  await browser.close();
+}
+```
+
+#### Option D: Puppeteer script
+
+```javascript
+const puppeteer = require('puppeteer');
+
+async function captureScreenshots(htmlFiles) {
+  const browser = await puppeteer.launch();
+
+  for (const file of htmlFiles) {
+    const [width, height] = file.match(/(\d+)x(\d+)/).slice(1).map(Number);
+
+    const page = await browser.newPage();
+    await page.setViewport({ width, height, deviceScaleFactor: 2 }); // 2x for retina
+    await page.goto(`file://${file}`, { waitUntil: 'networkidle0' });
+    // Wait for fonts/images to fully render
+    await new Promise(r => setTimeout(r, 3000));
+
+    const outputPath = file.replace('.html', '.png').replace('social-photos/', 'social-photos/exports/');
+    await page.screenshot({ path: outputPath, type: 'png' });
+    await page.close();
+  }
+
+  await browser.close();
+}
+```
+
+**IMPORTANT:** Use `deviceScaleFactor: 2` for retina-quality output (Puppeteer only).
+
+### Step 6: Verify & Fix Designs
+
+Open each exported PNG in an available browser or image viewer and inspect it:
+
+1. Open exported screenshots and check for layout/styling issues
+2. Verify: fonts rendered correctly, colors match brand, text readable at thumbnail size
+3. Check: no overflow, no cut-off content, safe zones respected, visual hierarchy clear
+4. If issues found → fix HTML source → re-export screenshot → verify again
+5. Repeat until all designs pass visual QA
+
+**Common issues to check:**
+- Fonts not loaded (fallback to system fonts)
+- Text overflow or clipping
+- Elements outside safe zone (central 80%)
+- Low contrast text (below WCAG AA 4.5:1)
+- Misaligned elements or broken layouts
+
+### Step 7: Generate Summary Report
+
+Save the report as `plans/reports/{YYMMDD}-social-photos-{topic}.md`.
+
+Report structure:
+
+```markdown
+# Social Photos Design Report
+
+## Overview
+- Prompt/requirements: {original input}
+- Platforms: {target platforms}
+- Variations: {count}
+- Style: {chosen style}
+
+## Ideas Generated
+1. **{Idea name}** — {brief description, rationale}
+2. ...
+
+## Design Decisions
+- Color palette: {colors used, why}
+- Typography: {fonts, sizes, why}
+- Layout: {composition approach, why}
+- Brand alignment: {how brand guidelines influenced design}
+
+## Output Files
+| File | Size | Platform | Preview |
+|------|------|----------|---------|
+| exports/{filename}.png | {WxH} | {platform} | {description} |
+
+## Why This Works
+- {Platform-specific reasoning}
+- {Brand alignment reasoning}
+- {Visual hierarchy reasoning}
+- {Engagement potential reasoning}
+
+## Recommendations
+- {A/B test suggestions}
+- {Platform-specific tips}
+- {Iteration opportunities}
+```
+
+### Step 8: Organize Output
+
+Organize all output files and reports:
+- Move/copy exported PNGs to proper asset directories
+- Ensure reports are in `plans/reports/` under the name from Step 7
+- Clean up intermediate HTML files if requested
+- Tag outputs with metadata (platform, size, concept name)
+
+## Design Best Practices
+
+### Platform-Specific Tips
+
+- **Instagram** — Visual-first, minimal text (<20%), strong colors, lifestyle feel
+- **Facebook** — Informative, can have more text, eye-catching in feed
+- **Twitter/X** — Bold headlines, contrast for dark/light mode, clear message
+- **LinkedIn** — Professional, clean, data-driven visuals, thought leadership
+- **Pinterest** — Vertical format, text overlay on images, how-to style
+- **YouTube** — Face close-ups perform best, bright colors, readable at small size
+- **TikTok** — Trendy, energetic, bold typography, youth-oriented
+
+### Art Direction Styles (Reuse from Banner)
+
+| Style | Best For | Key Elements |
+|-------|----------|--------------|
+| Minimalist | SaaS, tech, luxury | Whitespace, single accent color, clean type |
+| Bold Typography | Announcements, quotes | Large type, high contrast, minimal imagery |
+| Gradient Mesh | Modern brands, apps | Fluid color transitions, floating elements |
+| Photo-Based | Lifestyle, e-commerce | Hero image, subtle overlay, text on image |
+| Geometric | Tech, fintech | Shapes, patterns, structured layouts |
+| Glassmorphism | SaaS, modern apps | Frosted glass, blur effects, transparency |
+| Flat Illustration | Education, health | Custom illustrations, friendly, approachable |
+| Duotone | Creative, editorial | Two-color treatment on photos |
+| Collage | Fashion, culture | Mixed media, overlapping elements |
+| 3D/Isometric | Tech, product | Depth, shadows, modern perspective |
+
+### Color & Contrast
+
+- Ensure WCAG AA contrast ratio (4.5:1 min) for all text
+- Test designs at 50% size to verify readability
+- Consider platform dark/light mode compatibility
+- Use brand primary color as dominant, secondary as accent
+
+### Typography Hierarchy
+
+| Element | Min Size (at 1080px) | Weight |
+|---------|---------------------|--------|
+| Headline | 48px | Bold/Black |
+| Subheadline | 32px | Semibold |
+| Body | 24px | Regular |
+| Caption | 18px | Regular/Light |
+| CTA | 28px | Bold |
+
+## Security & Scope
+
+This sub-skill handles social media image design only. Does NOT handle:
+- Video content creation
+- Animation/motion graphics
+- Print production files (CMYK, bleed)
+- Direct social media posting/scheduling
+- AI image generation (supply images, or generate them with a separate authorized capability)

package/references/spatial-canvas-engine.md

@@ -0,0 +1,160 @@
+# Infinite Spatial Canvas & Viewport Virtualization Engine
+
+> [!NOTE]
+> สถาปัตยกรรมระดับสูงสำหรับการพัฒนาผืนผ้าใบอินฟินิท (Infinite Spatial Canvas) รองรับการวาดเส้น แผนผัง และการแสดงผลองค์ประกอบกราฟิกนับหมื่นชิ้นที่ 60-120 FPS ถอดแบบองค์ความรู้จาก **tldraw**, **Excalidraw**, และ **Perfect Freehand**
+
+---
+
+## 1. การแปลงพิกัดมิติผืนผ้าใบ (Coordinate System & Matrix Transforms)
+
+ระบบ Infinite Canvas ประกอบด้วย 2 ระนาบพิกัดที่ต้องแปลงไปมาแบบเรียลไทม์:
+1. **Screen Space (Viewport):** พิกัดพิกเซลบนหน้าจออุปกรณ์ `(x, y)` เริ่มต้นจากมุมซ้ายบนของ Element
+2. **World Space (Canvas Space):** พิกัดสมบูรณ์ในผืนผ้าใบไร้ขีดจำกัด `(wx, wy)` ที่คงที่แม้จะมีการ Zoom/Pan
+
+```typescript
+// types/spatial.ts
+export interface Camera {
+  x: number;     // ค่า offset แนวนอน (World units)
+  y: number;     // ค่า offset แนวตั้ง (World units)
+  zoom: number;  // อัตราการซูม (เช่น 1.0 = 100%, 0.5 = 50%, 2.0 = 200%)
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Box {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+// 1. แปลง Screen Coordinate -> World Coordinate (เมื่อคลิกเมาส์/ทัช)
+export function screenToWorld(screenPt: Point, camera: Camera): Point {
+  return {
+    x: (screenPt.x - camera.x) / camera.zoom,
+    y: (screenPt.y - camera.y) / camera.zoom,
+  };
+}
+
+// 2. แปลง World Coordinate -> Screen Coordinate (เมื่อเรนเดอร์ลงจอ)
+export function worldToScreen(worldPt: Point, camera: Camera): Point {
+  return {
+    x: worldPt.x * camera.zoom + camera.x,
+    y: worldPt.y * camera.zoom + camera.y,
+  };
+}
+
+// 3. ซูมเข้าหาตำแหน่งเคอร์เซอร์ (Zoom Towards Pointer)
+export function zoomToPoint(
+  pointerScreen: Point,
+  camera: Camera,
+  deltaZoomFactor: number,
+  minZoom = 0.1,
+  maxZoom = 8.0
+): Camera {
+  const nextZoom = Math.min(Math.max(camera.zoom * deltaZoomFactor, minZoom), maxZoom);
+  const worldPt = screenToWorld(pointerScreen, camera);
+  
+  return {
+    zoom: nextZoom,
+    x: pointerScreen.x - worldPt.x * nextZoom,
+    y: pointerScreen.y - worldPt.y * nextZoom,
+  };
+}
+```
+
+---
+
+## 2. Spatial Indexing & Viewport Culling (AABB)
+
+การเรนเดอร์ทุก Shape บนหน้าจอจะทำให้ประสิทธิภาพพังทลายเมื่อวัตถุมีจำนวนมาก วิธีแก้ปัญหาคือการใช้ **Axis-Aligned Bounding Box (AABB)** เพื่อกรองและเรนเดอร์เฉพาะวัตถุที่อยู่ในขอบเขตกล้อง (Viewport Culling):
+
+```typescript
+// spatial/culling.ts
+
+// คำนวณขอบเขตสี่เหลี่ยมของ Viewport ใน World Space
+export function getViewportWorldBounds(viewportWidth: number, viewportHeight: number, camera: Camera): Box {
+  const topLeft = screenToWorld({ x: 0, y: 0 }, camera);
+  const bottomRight = screenToWorld({ x: viewportWidth, y: viewportHeight }, camera);
+  return {
+    minX: Math.min(topLeft.x, bottomRight.x),
+    minY: Math.min(topLeft.y, bottomRight.y),
+    maxX: Math.max(topLeft.x, bottomRight.x),
+    maxY: Math.max(topLeft.y, bottomRight.y),
+  };
+}
+
+// ทดสอบการตัดกันของสี่เหลี่ยม AABB (O(1) Check)
+export function intersects(a: Box, b: Box): boolean {
+  return a.minX <= b.maxX && a.maxX >= b.minX && a.minY <= b.maxY && a.maxY >= b.minY;
+}
+
+// เลือกเฉพาะ Shapes ที่อยู่ในสายตากล้อง
+export function getVisibleShapes<T extends { bounds: Box }>(shapes: T[], viewportBounds: Box): T[] {
+  return shapes.filter(shape => intersects(shape.bounds, viewportBounds));
+}
+```
+
+---
+
+## 3. Vector Freehand Smoothing Algorithm
+
+การแปลงพิกัด Pointer เกรี้ยวกราด `[{x, y, pressure}]` ให้กลายเป็นโครงร่างเวกเตอร์ (SVG Polygon Path) ที่โค้งมนลื่นไหล พร้อมแรงกดแบบ Calligraphy:
+
+```typescript
+// geometry/freehand.ts
+
+export interface StrokePoint {
+  point: Point;
+  pressure: number;
+  distance: number;
+  vector: Point;
+}
+
+// คำนวณ Outline Polygon จากชุดจุดด้วยการจำลองความเร็วและมวล
+export function getStrokeOutlinePoints(points: Point[], strokeWidth = 8, smoothing = 0.5): Point[] {
+  if (points.length < 2) return [];
+
+  const leftPoints: Point[] = [];
+  const rightPoints: Point[] = [];
+
+  for (let i = 0; i < points.length; i++) {
+    const curr = points[i];
+    const prev = points[Math.max(0, i - 1)];
+    const next = points[Math.min(points.length - 1, i + 1)];
+
+    const dx = next.x - prev.x;
+    const dy = next.y - prev.y;
+    const len = Math.hypot(dx, dy) || 1;
+    const nx = -dy / len;
+    const ny = dx / len;
+
+    const halfWidth = strokeWidth / 2;
+    leftPoints.push({ x: curr.x + nx * halfWidth, y: curr.y + ny * halfWidth });
+    rightPoints.push({ x: curr.x - nx * halfWidth, y: curr.y - ny * halfWidth });
+  }
+
+  return [...leftPoints, ...rightPoints.reverse()];
+}
+```
+
+---
+
+## 4. Multi-Layer Composition Architecture
+
+โครงสร้างเลเยอร์ DOM/Canvas แยกอิสระเพื่อป้องกัน Repaint ทั้งหน้าจอ:
+
+```
+┌────────────────────────────────────────────────────────┐
+│  1. HUD / Minimap / Toolbars (HTML DOM - Fixed UI)     │
+├────────────────────────────────────────────────────────┤
+│  2. Selection Box / Transform Handles (SVG Overlay)    │
+├────────────────────────────────────────────────────────┤
+│  3. Interactive Shapes / Connectors (Culled Virtualized)│
+├────────────────────────────────────────────────────────┤
+│  4. Infinite Coordinate Grid (CSS Shader or Canvas 2D) │
+└────────────────────────────────────────────────────────┘
+```

package/references/stitch-system.md

@@ -0,0 +1,184 @@
+---
+name: stitch-skill
+description: "ออกแบบและสร้างระบบดีไซน์ระดับ Semantic สำหรับหน้าเว็บและแอป ผ่านไฟล์ DESIGN.md — ใช้เมื่อต้องการวางแผนและกำหนดมาตรฐาน UI สเปกฟอนต์ สี และ Micro-motion ตาม Google Stitch (Semantic design system, DESIGN.md generation, Google Stitch UI standards, typography scales, token contracts)"
+---
+
+# Stitch Design Taste — Semantic Design System Skill
+
+## Overview
+This skill generates `DESIGN.md` files optimized for Google Stitch screen generation. It translates the battle-tested anti-slop frontend engineering directives into Stitch's native semantic design language — descriptive, natural-language rules paired with precise values that Stitch's AI agent can interpret to produce premium, non-generic interfaces.
+
+The generated `DESIGN.md` serves as the **single source of truth** for prompting Stitch to generate new screens that align with a curated, high-agency design language. Stitch interprets design through **"Visual Descriptions"** supported by specific color values, typography specs, and component behaviors.
+
+## Prerequisites
+- Access to Google Stitch via [labs.google/stitch](https://labs.google/stitch)
+- Optionally: Stitch MCP Server for programmatic integration with Cursor, Antigravity, or Gemini CLI
+
+## The Goal
+Generate a `DESIGN.md` file that encodes:
+1. **Visual atmosphere** — the mood, density, and design philosophy
+2. **Color calibration** — neutrals, accents, and banned patterns with hex codes
+3. **Typographic architecture** — font stacks, scale hierarchy, and anti-patterns
+4. **Component behaviors** — buttons, cards, inputs with interaction states
+5. **Layout principles** — grid systems, spacing philosophy, responsive strategy
+6. **Motion philosophy** — animation engine specs, spring physics, perpetual micro-interactions
+7. **Anti-patterns** — explicit list of banned AI design clichés
+
+## Analysis & Synthesis Instructions
+
+### 1. Define the Atmosphere
+Evaluate the target project's intent. Use evocative adjectives from the taste spectrum:
+- **Density:** "Art Gallery Airy" (1–3) → "Daily App Balanced" (4–7) → "Cockpit Dense" (8–10)
+- **Variance:** "Predictable Symmetric" (1–3) → "Offset Asymmetric" (4–7) → "Artsy Chaotic" (8–10)
+- **Motion:** "Static Restrained" (1–3) → "Fluid CSS" (4–7) → "Cinematic Choreography" (8–10)
+
+Default baseline: Variance 8, Motion 6, Density 4. Adapt dynamically based on user's vibe description.
+
+### 2. Map the Color Palette
+For each color provide: **Descriptive Name** + **Hex Code** + **Functional Role**.
+
+**Mandatory constraints:**
+- Maximum 1 accent color. Saturation below 80%
+- The "AI Purple/Blue Neon" aesthetic is strictly BANNED — no purple button glows, no neon gradients
+- Use absolute neutral bases (Zinc/Slate) with high-contrast singular accents
+- Stick to one palette for the entire output — no warm/cool gray fluctuation
+- Never use pure black (`#000000`) — use Off-Black, Zinc-950, or Charcoal
+
+### 3. Establish Typography Rules
+- **Display/Headlines:** Track-tight, controlled scale. Not screaming. Hierarchy through weight and color, not just massive size
+- **Body:** Relaxed leading, max 65 characters per line
+- **Font Selection:** `Inter` is BANNED for premium/creative contexts. Force unique character: `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`
+- **Serif Ban:** Generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`, `Palatino`) are BANNED. If serif is needed for editorial/creative contexts, use only distinctive modern serifs: `Fraunces`, `Gambarino`, `Editorial New`, or `Instrument Serif`. Serif is always BANNED in dashboards or software UIs
+- **Dashboard Constraint:** Use Sans-Serif pairings exclusively (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`)
+- **High-Density Override:** When density exceeds 7, all numbers must use Monospace
+
+### 4. Define the Hero Section
+The Hero is the first impression and must be creative, striking, and never generic:
+- **Inline Image Typography:** Embed small, contextual photos or visuals directly between words or letters in the headline. Images sit inline at type-height, rounded, acting as visual punctuation. This is the signature creative technique
+- **No Overlapping:** Text must never overlap images or other text. Every element occupies its own clean spatial zone
+- **No Filler Text:** "Scroll to explore", "Swipe down", scroll arrow icons, bouncing chevrons are BANNED. The content should pull users in naturally
+- **Asymmetric Structure:** Centered Hero layouts BANNED when variance exceeds 4
+- **CTA Restraint:** Maximum one primary CTA. No secondary "Learn more" links
+
+### 5. Describe Component Stylings
+For each component type, describe shape, color, shadow depth, and interaction behavior:
+- **Buttons:** Tactile push feedback on active state. No neon outer glows. No custom mouse cursors
+- **Cards:** Use ONLY when elevation communicates hierarchy. Tint shadows to background hue. For high-density layouts, replace cards with border-top dividers or negative space
+- **Inputs/Forms:** Label above input, helper text optional, error text below. Standard gap spacing
+- **Loading States:** Skeletal loaders matching layout dimensions — no generic circular spinners
+- **Empty States:** Composed compositions indicating how to populate data
+- **Error States:** Clear, inline error reporting
+
+### 6. Define Layout Principles
+- No overlapping elements — every element occupies its own clear spatial zone. No absolute-positioned content stacking
+- Centered Hero sections are BANNED when variance exceeds 4 — force Split Screen, Left-Aligned, or Asymmetric Whitespace
+- The generic "3 equal cards horizontally" feature row is BANNED — use 2-column Zig-Zag, asymmetric grid, or horizontal scroll
+- CSS Grid over Flexbox math — never use `calc()` percentage hacks
+- Contain layouts using max-width constraints (e.g., 1400px centered)
+- Full-height sections must use `min-h-[100dvh]` — never `h-screen` (iOS Safari catastrophic jump)
+
+### 7. Define Responsive Rules
+Every design must work across all viewports:
+- **Mobile-First Collapse (< 768px):** All multi-column layouts collapse to single column. No exceptions
+- **No Horizontal Scroll:** Horizontal overflow on mobile is a critical failure
+- **Typography Scaling:** Headlines scale via `clamp()`. Body text minimum `1rem`/`14px`
+- **Touch Targets:** All interactive elements minimum `44px` tap target
+- **Image Behavior:** Inline typography images (photos between words) stack below headline on mobile
+- **Navigation:** Desktop horizontal nav collapses to clean mobile menu
+- **Spacing:** Vertical section gaps reduce proportionally (`clamp(3rem, 8vw, 6rem)`)
+
+### 8. Encode Motion Philosophy
+- **Spring Physics default:** `stiffness: 100, damping: 20` — premium, weighty feel. No linear easing
+- **Perpetual Micro-Interactions:** Every active component should have an infinite loop state (Pulse, Typewriter, Float, Shimmer)
+- **Staggered Orchestration:** Never mount lists instantly — use cascade delays for waterfall reveals
+- **Performance:** Animate exclusively via `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`. Grain/noise filters on fixed pseudo-elements only
+
+### 9. List Anti-Patterns (AI Tells)
+Encode these as explicit "NEVER DO" rules in the DESIGN.md:
+- No emojis anywhere
+- No `Inter` font
+- No generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`) — distinctive modern serifs only if needed
+- No pure black (`#000000`)
+- No neon/outer glow shadows
+- No oversaturated accents
+- No excessive gradient text on large headers
+- No custom mouse cursors
+- No overlapping elements — clean spatial separation always
+- No 3-column equal card layouts
+- No generic names ("John Doe", "Acme", "Nexus")
+- No fake round numbers (`99.99%`, `50%`)
+- No AI copywriting clichés ("Elevate", "Seamless", "Unleash", "Next-Gen")
+- No filler UI text: "Scroll to explore", "Swipe down", scroll arrows, bouncing chevrons
+- No broken Unsplash links — use `picsum.photos` or SVG avatars
+- No centered Hero sections (for high-variance projects)
+
+## Output Format (DESIGN.md Structure)
+
+```markdown
+# Design System: [Project Title]
+
+## 1. Visual Theme & Atmosphere
+(Evocative description of the mood, density, variance, and motion intensity.
+Example: "A restrained, gallery-airy interface with confident asymmetric layouts
+and fluid spring-physics motion. The atmosphere is clinical yet warm — like a
+well-lit architecture studio.")
+
+## 2. Color Palette & Roles
+- **Canvas White** (#F9FAFB) — Primary background surface
+- **Pure Surface** (#FFFFFF) — Card and container fill
+- **Charcoal Ink** (#18181B) — Primary text, Zinc-950 depth
+- **Muted Steel** (#71717A) — Secondary text, descriptions, metadata
+- **Whisper Border** (rgba(226,232,240,0.5)) — Card borders, 1px structural lines
+- **[Accent Name]** (#XXXXXX) — Single accent for CTAs, active states, focus rings
+(Max 1 accent. Saturation < 80%. No purple/neon.)
+
+## 3. Typography Rules
+- **Display:** [Font Name] — Track-tight, controlled scale, weight-driven hierarchy
+- **Body:** [Font Name] — Relaxed leading, 65ch max-width, neutral secondary color
+- **Mono:** [Font Name] — For code, metadata, timestamps, high-density numbers
+- **Banned:** Inter, generic system fonts for premium contexts. Serif fonts banned in dashboards.
+
+## 4. Component Stylings
+* **Buttons:** Flat, no outer glow. Tactile -1px translate on active. Accent fill for primary, ghost/outline for secondary.
+* **Cards:** Generously rounded corners (2.5rem). Diffused whisper shadow. Used only when elevation serves hierarchy. High-density: replace with border-top dividers.
+* **Inputs:** Label above, error below. Focus ring in accent color. No floating labels.
+* **Loaders:** Skeletal shimmer matching exact layout dimensions. No circular spinners.
+* **Empty States:** Composed, illustrated compositions — not just "No data" text.
+
+## 5. Layout Principles
+(Grid-first responsive architecture. Asymmetric splits for Hero sections.
+Strict single-column collapse below 768px. Max-width containment.
+No flexbox percentage math. Generous internal padding.)
+
+## 6. Motion & Interaction
+(Spring physics for all interactive elements. Staggered cascade reveals.
+Perpetual micro-loops on active dashboard components. Hardware-accelerated
+transforms only. Isolated Client Components for CPU-heavy animations.)
+
+## 7. Anti-Patterns (Banned)
+(Explicit list of forbidden patterns: no emojis, no Inter, no pure black,
+no neon glows, no 3-column equal grids, no AI copywriting clichés,
+no generic placeholder names, no broken image links.)
+```
+
+## Best Practices
+- **Be Descriptive:** "Deep Charcoal Ink (#18181B)" — not just "dark text"
+- **Be Functional:** Explain what each element is used for
+- **Be Consistent:** Same terminology throughout the document
+- **Be Precise:** Include exact hex codes, rem values, pixel values in parentheses
+- **Be Opinionated:** This is not a neutral template — it enforces a specific, premium aesthetic
+
+## Tips for Success
+1. Start with the atmosphere — understand the vibe before detailing tokens
+2. Look for patterns — identify consistent spacing, sizing, and styling
+3. Think semantically — name colors by purpose, not just appearance
+4. Consider hierarchy — document how visual weight communicates importance
+5. Encode the bans — anti-patterns are as important as the rules themselves
+
+## Common Pitfalls to Avoid
+- Using technical jargon without translation ("rounded-xl" instead of "generously rounded corners")
+- Omitting hex codes or using only descriptive names
+- Forgetting functional roles of design elements
+- Being too vague in atmosphere descriptions
+- Ignoring the anti-pattern list — these are what make the output premium
+- Defaulting to generic "safe" designs instead of enforcing the curated aesthetic