medesign 0.0.0-stage → 1.4.0

package/references/components.md

@@ -0,0 +1,240 @@
+## 🎨 Interactive Modal Archetypes (เมื่อใช้ `/medesign` ปกติ)
+
+เรียก `ask_question` ทันทีด้วยตัวเลือกต่อไปนี้ (หรือเปิด Comparison Lab บน Localhost):
+
+- 📄 **My DNA — Warm Editorial & Glass** *(Calibrated Default)*
+  - Near-White `#f7f5f2` + Terracotta `#cc785c` + Fraunces Serif + Frosted Glass + Full Pill
+- ⚡ **Electric Dark Upgraded**
+  - Deep Ink `#090909` + Indigo/Violet Accent + Frosted Glass Sidebar
+- 🏛️ **Warm Dark Editorial**
+  - Dark Navy `#0d1520` + Terracotta `#cc785c` + Fraunces Serif + Editorial Contrast
+- 💎 **Cyber Precision (Vercel × Linear)**
+  - Pure Ink `#0a0a0a` + Hairline `1px` Borders + Stark Monochrome + Geist Sans
+- 🟢 **Spotify Pulse**
+  - Pitch Charcoal `#121212` + Neon Green `#1ed760` + Solid Surface + Pill CTA
+- 🏎️ **BMW Precision Luxury**
+  - Pure Black `#050505` + Metallic Inset Glass + Precision Blue `#0066b1` + Razor Type
+- 📓 **Notion Warm Modern**
+  - Clean White `#ffffff` + Solid Warm Gray Sidebar `#f9f9f8` + Zero Blur + Crisp Borders
+- 🧠 **Claude Intelligent**
+  - Warm Paper `#fbfaf8` + Soft Terracotta `#a15e41` + Literary Serif + Human Approachability
+- ✦ **Best Designs on X (Linear Dark Craft)** *(New 2026 Trend)*
+  - Deep Void `#09090b` + 1px Border Glow (`rgba(255,255,255,0.08)`) + Instrument Serif Italic + Geist Sans/Mono + Indigo `#6366f1` / Violet `#8b5cf6`
+
+---
+
+## 📦 Component Blueprint Library
+
+### Hero Section
+```css
+/* Headline: Serif Display Italic */
+font-family: 'Fraunces', 'Playfair Display', serif;
+font-size: clamp(2.5rem, 6vw, 5rem);
+font-weight: 600;
+letter-spacing: -0.025em;
+font-style: italic; /* on display words */
+
+/* Eyebrow tag above headline */
+font-family: 'Geist Mono', monospace;
+font-size: 0.75rem;
+letter-spacing: 0.1em;
+text-transform: uppercase;
+
+/* CTA Primary */
+border-radius: 9999px;
+background: #cc785c;
+color: #fff;
+height: 2.75rem; /* h-11 */
+padding: 0 2rem;
+transition: opacity 150ms ease;
+```
+
+### Bento Grid
+```css
+display: grid;
+grid-template-columns: repeat(3, 1fr);
+grid-template-rows: auto;
+gap: 1rem;
+/* Feature card spans 2 cols */
+.feature-card { grid-column: span 2; }
+
+/* Card Base: Frosted Glass */
+background: rgba(255, 255, 255, 0.6);
+backdrop-filter: blur(16px);
+border: 1px solid rgba(204, 120, 92, 0.15);
+border-radius: 16px;
+/* Hover: border warm glow */
+transition: border-color 150ms ease;
+&:hover { border-color: rgba(204, 120, 92, 0.4); }
+```
+
+### Navigation (Sticky Glassmorphic)
+```css
+position: sticky; top: 0; z-index: 50;
+backdrop-filter: blur(24px) saturate(160%);
+background: rgba(250, 250, 250, 0.75);
+border-bottom: 1px solid rgba(0, 0, 0, 0.05);
+```
+
+### Data Metric Card
+```css
+/* Value */
+font-family: 'Geist Mono', monospace;
+font-size: 2.25rem;
+font-weight: 600;
+/* Label */
+font-family: 'Plus Jakarta Sans', sans-serif;
+font-size: 0.7rem;
+letter-spacing: 0.08em;
+text-transform: uppercase;
+color: #9ca3af;
+/* Status Pill */
+border-radius: 9999px;
+border: 1px solid currentColor;
+font-size: 0.688rem;
+font-family: 'Geist Mono';
+```
+
+### Command Palette (`⌘K` Modal)
+```css
+/* Container */
+background: rgba(18, 18, 23, 0.9);
+backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 255, 255, 0.1);
+border-radius: 14px;
+box-shadow: 0 24px 64px -12px rgba(0, 0, 0, 0.7);
+
+/* Search Input */
+font-family: 'Geist', sans-serif;
+color: #f4f4f5;
+border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+
+/* Active Row */
+background: rgba(99, 102, 241, 0.12);
+border: 1px solid rgba(99, 102, 241, 0.25);
+border-radius: 8px;
+color: #ffffff;
+```
+
+### Apple Bento Box 2.0 (High-Density with Mini-Metrics)
+```css
+display: grid;
+grid-template-columns: repeat(3, minmax(0, 1fr));
+gap: 1rem;
+
+/* Bento Tile Base */
+background: #111115;
+border: 1px solid rgba(255, 255, 255, 0.08);
+border-radius: 16px;
+padding: 1.25rem;
+position: relative;
+overflow: hidden;
+
+/* Border Glow Mask */
+&::before {
+  content: '';
+  position: absolute;
+  inset: -1px;
+  border-radius: inherit;
+  padding: 1px;
+  background: linear-gradient(135deg, rgba(255,255,255,0.15), rgba(255,255,255,0.02) 40%, rgba(99,102,241,0.2));
+  -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+  mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+  -webkit-mask-composite: xor;
+  mask-composite: exclude;
+  pointer-events: none;
+}
+```
+
+### Specular Top Rim Light (Crafted Button / Card Highlight)
+```css
+/* ใส่บนปุ่มหรือการ์ดเพื่อสร้างมิติสะท้อนแสงขอบบน */
+position: relative;
+&::after {
+  content: '';
+  position: absolute;
+  top: 1px;
+  left: 8px;
+  right: 8px;
+  height: 1px;
+  background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.65), transparent);
+  border-radius: 9999px;
+  pointer-events: none;
+}
+```
+
+---
+
+## 🧠 5 UI Ergonomics Blueprints (Cognitive Load Reduction)
+
+เกณฑ์การจัดวางและออกแบบส่วนติดต่อผู้ใช้เพื่อลดภาระทางสมอง (Cognitive Friction) ของผู้ใช้:
+
+### 1. Primary Action Dominance (ปุ่มหลักเด่นเพียง 1 เดียว)
+ใน 1 มุมมองหรือ 1 การ์ด ต้องมี Primary CTA เพียง 1 ปุ่มเท่านั้นเพื่อชี้ทิศทางชัดเจน (Hick's Law):
+```tsx
+{/* Primary Action vs Secondary Outline */}
+<div className="flex items-center gap-3">
+  <button className="h-10 px-5 rounded-full bg-primary text-primary-foreground font-medium shadow-sm hover:opacity-90 active:scale-[0.98] transition">
+    Confirm Coordinates
+  </button>
+  <button className="h-10 px-4 rounded-full border border-border bg-transparent text-foreground/80 hover:bg-muted/50 transition">
+    Cancel
+  </button>
+</div>
+```
+
+### 2. Whitespace & Gestalt Grouping (ระยะหายใจและการจัดกลุ่ม)
+ใช้ Negative Space และระยะห่างที่ได้สัดส่วนในการแยกกลุ่มข้อมูล:
+- **Container Padding:** ขั้นต่ำ `p-4` (16px) ถึง `p-6` (24px) รอบการ์ด
+- **Intra-group Gap:** ข้อมูลหรืออินพุตที่เกี่ยวข้องกันใช้ `space-y-2` หรือ `gap-2` (8px)
+- **Inter-group Spacing:** การแบ่งกลุ่มข้อมูลต่างประเภทใช้ `space-y-6` หรือ `gap-6` (24px) พร้อมเส้นแบ่งบาง 1px (`border-t border-border/40`)
+
+### 3. Progressive Disclosure Overflow (ปุ่มเยอะซ่อนในเมนูเพิ่มเติม)
+จำกัด Action ปุ่มลอยบนหน้าจอไม่เกิน 2–3 ปุ่ม ส่วนที่เหลือ (ปุ่มที่ใช้น้อย หรือ Destructive Action) ให้รวมไว้ใน Overflow Menu (`...`):
+```tsx
+<div className="flex items-center gap-2">
+  <Button variant="default">Save Traverse</Button>
+  <Button variant="outline">Preview Map</Button>
+  
+  {/* Overflow for rare / secondary actions */}
+  <DropdownMenu>
+    <DropdownMenuTrigger asChild>
+      <Button variant="ghost" size="icon"><MoreHorizontal className="w-4 h-4" /></Button>
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="end">
+      <DropdownMenuItem>Export GeoJSON</DropdownMenuItem>
+      <DropdownMenuItem>Duplicate Layer</DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuItem className="text-destructive">Delete Survey</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</div>
+```
+
+### 4. Typographic Scanability Hierarchy (ลำดับสายตาตัวอักษร)
+ห้ามใช้ข้อความขนาดยาวเป็นก้อนสม่ำเสมอ (Wall of Text) บังคับใช้ Type Scale นำสายตาตาม F-Shape:
+```tsx
+<div className="space-y-1.5">
+  <span className="text-xs font-mono uppercase tracking-wider text-muted-foreground">Station Alpha</span>
+  <h2 className="text-xl font-bold tracking-tight text-foreground">Traverse Computation Matrix</h2>
+  <p className="text-sm text-foreground/80 leading-relaxed max-w-prose">
+    Calculated relative closure error is within the secondary urban boundary survey threshold (1:10,000).
+  </p>
+</div>
+```
+
+### 5. Form Chunking & Multi-Step Stepper (ฟอร์มยาวแบ่งเป็นก้อน)
+เมื่อฟอร์มมี Input ตั้งแต่ $\ge 6$ รายการขึ้นไป ให้จัดกลุ่มเป็นการ์ดย่อย (Semantic Fieldsets) หรือแบ่งเป็น Multi-step Stepper:
+```tsx
+{/* Multi-step progress header */}
+<div className="mb-6 space-y-2">
+  <div className="flex justify-between text-xs font-medium text-muted-foreground">
+    <span>Step 1: Instrument Setup</span>
+    <span>Step 1 of 3</span>
+  </div>
+  <div className="h-1.5 w-full bg-muted rounded-full overflow-hidden">
+    <div className="h-full bg-primary rounded-full w-1/3 transition-all duration-300" />
+  </div>
+</div>
+```
+

package/references/dark-mode.md

@@ -0,0 +1,23 @@
+## 8. DARK MODE PROTOCOL
+
+Dual-mode by default. Never assume light-only unless the brief is print-emulating editorial.
+
+### 8.A Token Strategy (pick one, stick to it)
+* **Tailwind `dark:` variant** (default for utility-first projects): every color utility paired with its dark variant (`bg-white dark:bg-zinc-950`, `text-gray-900 dark:text-gray-100`).
+* **CSS variables** (for shadcn/ui, Radix Themes, or component libraries with theming): define semantic tokens (`--surface`, `--surface-elevated`, `--text-primary`, `--accent`) and swap values under `[data-theme="dark"]` or `@media (prefers-color-scheme: dark)`.
+
+### 8.B Do Not Prescribe Specific Colors Here
+The brief and brand decide. This skill enforces only:
+* **Contrast** - WCAG AA minimum for body text, AAA target for hero copy.
+* **Hierarchy parity** - visual hierarchy that works in light must work in dark. If a CTA pops in light, it pops in dark.
+* **Brand fidelity** - primary brand color stays recognisable. Don't desaturate the brand into a dark mode.
+* **No pure `#000000` and no pure `#ffffff`** - use off-black (zinc-950, near-black warm gray) and off-white. Pure values kill depth.
+
+### 8.C Default Mode
+Respect `prefers-color-scheme` unless the brand insists. Add a manual toggle if either mode would lose key brand expression.
+
+### 8.D Test in Both Modes Before Finishing
+Open the page in both modes during development. Do not ship a page you've only seen in one mode.
+
+---
+

package/references/design-core.md

@@ -0,0 +1,42 @@
+## 🚫 Non-Bland & Anti-AI-Slop Protocol (ห้ามจืดชืดและห้ามดูเหมือนงาน AI สุกเอาเผากิน)
+
+1. **Zero AI-Slop Negative Prompts (ข้อห้ามเด็ดขาด):**
+   - **No Gaudy Gradients:** ห้ามใช้ multi-stop rainbow/neon gradient ทับปุ่มหรือการ์ดมั่วซั่ว (อนุญาตเฉพาะ subtle atmospheric radial glow ≤ 10% opacity)
+   - **No Emoji Spam in Headings:** ห้ามใส่ Emoji เรียงหน้าหัวข้อหลัก (`🚀 Features`, `✨ Overview`) ยกเว้นผู้ใช้ระบุหรือเป็น Icon Badge เฉพาะจุด
+   - **No Heavy Drop Shadows:** ห้ามใช้ `shadow-md/lg/xl` ดำทึบเดี่ยวๆ → ต้องเป็น Frosted Glass (`backdrop-blur`) หรือ Stacked Inset Hairline Ring (`1px solid`) เสมอ
+   - **No Colored Border Clutter:** ห้ามตีกรอบสีสด (`border-blue-500`, `border-purple-500`) รอบการ์ดทุกใบ ใช้ hairline border โปร่งแสง (`rgba(..., 0.08–0.15)`) เท่านั้น
+   - **No Unnecessary Hover Bounces:** ห้ามทำการ์ดเด้งลอยสูง (`-translate-y-2`, `scale-105`) หรือ Parallax กวนสายตา → จำกัด motion ไม่เกิน `150ms–200ms` (`active:scale-[0.97]` เฉพาะปุ่มกด)
+   - **Zero Cliche AI Palette:** ห้ามใช้โทนม่วง-ฟ้า AI มาตรฐาน (`bg-indigo-600` + `bg-purple-600`) หรือขาว-ส้มการตลาดทื่อๆ ที่ไม่ได้มาจาก Brand Token หรือ User DNA
+2. **Typography Discipline:**
+   - หัวข้อทุกตัวต้องบีบ `letter-spacing: -0.025em` ถึง `-0.035em`
+   - ตัวเลข พิกัด สถิติ เวลา และรหัสสถานะ ต้องใช้ `font-mono tabular-nums` (`Geist Mono` / `JetBrains Mono`) เสมอ
+3. **Min-UI Principle (สำหรับ Tool / Engineering / SaaS Workspace เช่น MESURV, Mesnooker):**
+   - **Controls Near Content:** วางปุ่มควบคุมและตัวกรองไว้ติดกับข้อมูลที่ถูกกระทำ ไม่แยกห่างเกินจำเป็น
+   - **Verbs Over Nouns:** ปุ่ม Action ใช้คำกริยาที่ชัดเจน (`Calculate Traverse`, `Export GeoJSON`, `Start Frame`) แทนคำนามลอยๆ
+   - **Zero Marketing Fluff:** ในหน้าทำงานจริง (Workspace/Calculator/Map) ตัดคำโฆษณาเวิ่นเว้อออก เน้นความคมชัดของข้อมูล (High Signal-to-Noise)
+
+---
+
+## 📐 Calibrated Surface × Spatial Architecture Matrix (Round 2 & 3)
+
+- **Token Source of Truth:** `user-profile.json` หรือ `tokens/` (`design-tokens.json`, `design-tokens.css`, `tailwind.tokens.config.js`)
+- **Axis 1 — 3 Master Surface Themes (Synthesized from 7 Blind Winners `#B, #G, #L, #C, #K, #D, #F`):**
+  1. `fieldbook` (**The Fieldbook** — Daylight Survey & Editorial: `#B + #G + #L`)
+  2. `cosmos` (**Cosmos Glass** — Deep Space Acrylic & Velvet: `#C + #K`)
+  3. `matrix` (**Data Matrix** — Pro Telemetry & Field Controller: `#D + #F`)
+- **Axis 2 — 8 Spatial Layout Archetypes (`L-01` to `L-08` on `/style/101`–`/style/108`):**
+  - `L-01`: Asymmetric Editorial Bento + Top Command Pill (`0px` Sidebar, `8:4` + `7:5` Grid)
+  - `L-02`: Full-Bleed Canvas-First Spatial HUD (`100vw × 100vh` Map + Floating Pods)
+  - `L-03`: 3-Pane Engineering IDE Split Workbench (`18%` Tree : `56%` Stage+Console : `26%` Inspector)
+  - `L-04`: 40/60 Sticky Poster Split & Exposed Architectural Grid (`0px` Gap Hairline Cells)
+  - `L-05`: Pro Telemetry Ribbon + 50/50 Synchronized Dual Split (Top Ticker + Left/Right Sync)
+  - `L-06`: Focused 760px Executable Fieldbook Stream (Single-Column + Inline Compute Cells)
+  - `L-07`: Bottom-Dock OS & 4-Column Modular Swimlanes (4 Vertical Lanes + Bottom OS Dock)
+  - `L-08`: Spacious Full-Width Master Table + 440px Slide-Over Inspector Drawer
+
+---
+
+<!-- USER_PROFILE_SIGNATURE -->
+<!-- Last calibrated: 2026-09-29T15:19:00+07:00 -->
+<!-- Status: CONFIRMED_V2 (3 Master Themes + 7 Blind Winners + 8 Spatial Layout Archetypes) -->
+

package/references/design-md-protocol.md

@@ -0,0 +1,75 @@
+# DESIGN.md Protocol (Google Stitch Standard)
+
+`DESIGN.md` คือไฟล์ข้อกำหนดดีไซน์ระดับโปรเจกต์ (Plain-Text Design System) วางไว้ที่ Root ของโปรเจกต์ควบคู่กับ `AGENTS.md`:
+- `AGENTS.md` กำหนด **"How to Build"** (สถาปัตยกรรมโค้ด, Build steps, Testing harness)
+- `DESIGN.md` กำหนด **"How it Looks & Feels"** (Tokens, Typography, Card Anatomy, Anti-AI styling)
+
+---
+
+## 1. วัตถุประสงค์ & ประโยชน์ต่อ AI Agent
+1. **Zero Hallucination:** ป้องกันไม่ให้ AI สุ่มสร้างสี, ขนาดฟอนต์ หรือ Padding ที่ไม่สอดคล้องกันข้ามไฟล์
+2. **Context-Optimized:** เขียนด้วย Markdown ล้วน กระชับ ประหยัด Token มากกว่าการส่ง JSON สเปกหรือไฟล์รูปภาพ Figma
+3. **Single Source of Truth:** เมื่อมีการปรับเปลี่ยน Brand Tokens หรือ Component Spacing ให้แก้ที่ `DESIGN.md` จุดเดียว
+
+---
+
+## 2. โครงสร้างมาตรฐานของ `DESIGN.md` (Project Root Template)
+
+```markdown
+# Design System Specification (DESIGN.md)
+
+## 1. Aesthetic Archetype & Direction
+- **Archetype:** [Minimalist Clean / Tactical Dense / Editorial Luxury / Neumorphic Soft / Retro Cyber]
+- **Mood & Tone:** Professional, fast, low-friction, high-density survey data presentation.
+- **Visual Personality:** Sharp 1px borders, subtle frosted backdrops, negative heading tracking.
+
+## 2. Color Palette & WCAG Compliance
+- **Surfaces:**
+  - Background Base: `#09090b` (Dark) / `#fafafa` (Light) — ห้ามใช้ pure #000000 หรือ #ffffff แบนราบ
+  - Surface Elevated: `#141416` (Dark) / `#ffffff` (Light)
+  - Surface Border: `rgba(255, 255, 255, 0.08)` (Dark) / `rgba(0, 0, 0, 0.08)` (Light)
+- **Accents:**
+  - Primary Action / Voltage: `#cc785c` (Terracotta) หรือ `#6366f1` (Indigo)
+  - Success: `#10b981` (Emerald)
+  - Warning: `#f59e0b` (Amber)
+  - Danger: `#ef4444` (Rose Red)
+- **Contrast Proof:** ทุกคู่ข้อความและพื้นหลังต้องผ่านเกณฑ์ WCAG AAA (Contrast ratio >= 7:1 สำหรับ Normal text)
+
+## 3. Typography Hierarchy
+- **Font Stacks:**
+  - Display / Headings: `Instrument Serif`, `Playfair Display`, หรือ Serif italic accents
+  - Body / UI: `Plus Jakarta Sans`, `Geist`, หรือ `Inter`
+  - Code / Data / Numbers: `Geist Mono`, `JetBrains Mono`
+- **Scale:**
+  - H1 Hero: `2.25rem` (36px) | weight: 700 | tracking: `-0.03em` | line-height: 1.15
+  - H2 Section: `1.5rem` (24px) | weight: 600 | tracking: `-0.025em` | line-height: 1.25
+  - H3 Subsection: `1.125rem` (18px) | weight: 600 | tracking: `-0.015em` | line-height: 1.35
+  - Body: `0.875rem` (14px) | weight: 400 | tracking: `0em` | line-height: 1.5
+  - Caption / Micro: `0.75rem` (12px) | weight: 500 | tracking: `0.02em` | line-height: 1.4
+
+## 4. Component Anatomy & Spatial Scale
+- **Grid / Spacing:** 4px base (4, 8, 12, 16, 24, 32, 48, 64px)
+- **Border Radius:**
+  - Cards & Containers: `8px` (`rounded-lg`) ถึง `12px` (`rounded-xl`)
+  - Inputs & Dropdowns: `6px` (`rounded-md`)
+  - Primary Action Buttons: `9999px` (`rounded-full` Pill)
+  - Status Badges / Tags: `4px` (`rounded`) หรือ `9999px`
+- **Shadows & Elevation:**
+  - Card Default: `0 1px 3px 0 rgba(0, 0, 0, 0.05), 0 1px 2px 0 rgba(0, 0, 0, 0.03)`
+  - Card Hover: `0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)`
+  - Modal: `0 20px 25px -5px rgba(0, 0, 0, 0.2)`
+
+## 5. Anti-AI Visual Tells Checklist
+- [ ] ไม่มี Generic Centered Hero พร้อมปุ่มสีม่วงนีออนไล่เฉด (Indigo/Purple gradient cliché)
+- [ ] ไม่มีไอคอนลอยกลางการ์ด 3 ช่องที่มีขนาดเท่ากันหมดอย่างไร้ลำดับความสำคัญ
+- [ ] มี State ชัดเจน: Hover, Active, Focus-Visible, Disabled, Loading
+- [ ] มี Empty State ที่ออกแบบมาเฉพาะจุด พร้อมปุ่ม Action ที่พาไปขั้นตอนต่อไป
+- [ ] ใช้ 1px hairline borders (`border-border/40`) แทน Drop Shadow ขนาดใหญ่เกินจริง
+```
+
+---
+
+## 3. Workflow การประยุกต์ใช้กับ AI Agent
+1. **เมื่อเริ่มโปรเจกต์ใหม่:** รัน `/medesign` เพื่อสังเคราะห์ `DESIGN.md` วางไว้ที่ Root ของโปรเจกต์
+2. **เมื่อแก้ไขหรือเพิ่ม Component:** ตรวจสอบค่าสี, Spacing, และ Font จาก `DESIGN.md` เสมอ
+3. **เมื่อรีวิวโค้ด UI (`review`):** นำ Checklists ใน `DESIGN.md` มาเป็นเกณฑ์ตรวจรับงาน

package/references/design-routing.md

@@ -0,0 +1,207 @@
+# Design Routing Guide
+
+When to use each design sub-skill.
+
+## Skill Overview
+
+| Skill | Purpose | Key Files |
+|-------|---------|-----------|
+| brand | Brand identity, voice, assets | SKILL.md + 10 references + 3 scripts |
+| design-system | Token architecture, specs | SKILL.md + 7 references + 2 scripts |
+| ui-styling | Component implementation | SKILL.md + 7 references + 2 scripts |
+| logo-design | AI logo generation (55 styles, 30 palettes) | SKILL.md + 4 references + 2 scripts |
+| cip-design | Corporate Identity Program (50 deliverables) | SKILL.md + 3 references + 3 scripts |
+| slides | HTML presentations with Chart.js | SKILL.md + 4 references |
+| banner (built-in) | Banners for social, ads, web, print (22 styles) | references/banner-sizes-and-styles.md |
+| icon-design | SVG icon generation (15 styles, Gemini 3.1 Pro) | SKILL.md + 1 reference + 1 script |
+
+## Routing by Task Type
+
+### Brand Identity Tasks
+**→ brand**
+
+- Define brand colors and typography
+- Create logo usage guidelines
+- Establish brand voice and tone
+- Organize and validate assets
+- Create messaging frameworks
+- Audit brand consistency
+
+### Token System Tasks
+**→ design-system**
+
+- Create design tokens JSON
+- Generate CSS variables
+- Define component specifications
+- Map tokens to Tailwind config
+- Validate token usage in code
+- Document state and variants
+
+### Implementation Tasks
+**→ ui-styling**
+
+- Add shadcn/ui components
+- Style with Tailwind classes
+- Implement dark mode
+- Create responsive layouts
+- Build accessible components
+
+### Logo Design Tasks
+**→ logo-design**
+
+- Create logos with AI (Gemini Nano Banana)
+- Search logo styles, color palettes, industry guidelines
+- Generate design briefs
+- Explore 55+ styles (minimalist, vintage, luxury, geometric, etc.)
+
+### Corporate Identity Program Tasks
+**→ cip-design**
+
+- Generate CIP deliverables (business cards, letterheads, signage, vehicles, apparel)
+- Create CIP briefs with industry/style analysis
+- Generate mockups with/without logo (Gemini Flash/Pro)
+- Render HTML presentations from CIP mockups
+
+### Presentation Tasks
+**→ slides**
+
+- Create strategic HTML presentations
+- Data visualization with Chart.js
+- Apply copywriting formulas to slide content
+- Use layout patterns and design tokens
+
+### Banner Design Tasks
+**→ design (built-in banner: references/banner-sizes-and-styles.md)**
+
+- Design banners for social media (Facebook, Twitter, LinkedIn, YouTube, Instagram)
+- Create ad banners (Google Ads, Meta Ads)
+- Website hero banners and headers
+- Print banners and covers
+- 22 art direction styles (minimalist, bold typography, gradient, glassmorphism, etc.)
+
+### Icon Design Tasks
+**→ icon-design**
+
+- Generate SVG icons with AI (Gemini 3.1 Pro Preview)
+- Batch icon variations in multiple styles
+- Multi-size export (16px, 24px, 32px, 48px)
+- 15 styles: outlined, filled, duotone, rounded, sharp, gradient, etc.
+- 12 categories: navigation, action, communication, media, commerce, data
+
+## Routing by Question Type
+
+| Question | Skill |
+|----------|-------|
+| "What color should this be?" | brand |
+| "How do I create a token for X?" | design-system |
+| "How do I build a button component?" | ui-styling |
+| "Is this on-brand?" | brand |
+| "Should I use a CSS variable here?" | design-system |
+| "How do I add dark mode?" | ui-styling |
+| "Create a logo for my brand" | logo-design |
+| "Generate business card mockups" | cip-design |
+| "Create a pitch deck" | slides |
+| "Design brand identity package" | cip-design |
+| "What logo style fits my industry?" | logo-design |
+| "Design a Facebook cover" | design (built-in banner) |
+| "Create ad banners for Google" | design (built-in banner) |
+| "Make a website hero banner" | design (built-in banner) |
+| "Generate a settings icon" | icon-design |
+| "Create SVG icons for my app" | icon-design |
+| "Design an icon set" | icon-design |
+
+## Multi-Skill Workflows
+
+### New Project Setup
+
+```
+1. brand → Define identity
+   - Colors, typography, voice
+
+2. design-system → Create tokens
+   - Primitive, semantic, component
+
+3. ui-styling → Implement
+   - Configure Tailwind, add components
+```
+
+### Design System Migration
+
+```
+1. brand → Audit existing
+   - Extract brand colors, fonts
+
+2. design-system → Formalize tokens
+   - Create three-layer architecture
+
+3. ui-styling → Update code
+   - Replace hardcoded values
+```
+
+### Component Creation
+
+```
+1. design-system → Reference specs
+   - Button states, sizes, variants
+
+2. ui-styling → Implement
+   - Build with shadcn/ui + Tailwind
+```
+
+## Skill Dependencies
+
+```
+brand
+    ↓ (colors, typography)
+design-system
+    ↓ (tokens, specs)
+ui-styling
+    ↓ (components)
+Application Code
+```
+
+## Quick Commands
+
+**Brand:**
+```bash
+node ../brand/scripts/inject-brand-context.cjs
+node ../brand/scripts/validate-asset.cjs <path>
+```
+
+**Tokens:**
+```bash
+node ../design-system/scripts/generate-tokens.cjs -c tokens.json
+node ../design-system/scripts/validate-tokens.cjs -d src/
+```
+
+**Components:**
+```bash
+npx shadcn@latest add button card input
+```
+
+## When to Use Multiple Skills
+
+Use **all eight** when:
+- Complete brand package from scratch (logo → CIP → presentation)
+
+Use **brand + design-system + ui-styling** when:
+- Design system setup and implementation
+
+Use **logo-design + cip-design** when:
+- Complete brand identity package with deliverable mockups
+
+Use **logo-design + cip-design + slides** when:
+- Brand pitch: generate logo, create CIP mockups, build pitch deck
+
+Use **design (banner) + brand** when:
+- Social media presence: branded banners across all platforms
+
+Use **icon-design + design-system** when:
+- Custom icon set matching design tokens and component specs
+
+Use **brand + design-system** when:
+- Defining design language without implementation
+
+Use **design-system + ui-styling** when:
+- Implementing existing brand in code
+- Building component library

package/references/eng-imagery-content.md

@@ -0,0 +1,71 @@
+### 4.8 Image & Visual Asset Strategy
+
+Landing pages and portfolios are **visual products**. Text-only pages with fake-screenshot divs are slop.
+
+**Priority order for visual assets:**
+1. **Image-generation tool first.** If ANY image-gen tool is available in the environment (`generate_image`, MCP image tool, IDE-integrated gen, OpenAI image tools, etc.) you MUST use it to create section-specific assets: hero photography, product shots, texture backgrounds, mood images. Generate at the right aspect ratio for the section. Do not skip this step because hand-rolled CSS feels faster.
+2. **Real web images second.** When no gen tool is available, use real photography sources. Acceptable defaults:
+   * `https://picsum.photos/seed/{descriptive-seed}/{w}/{h}` for placeholder photography (seed should describe the section, e.g. `marrow-cookware-kitchen`)
+   * Actual stock or brand URLs when the brief provides them
+   * Open-license sources (Unsplash via direct URL, Pexels) if explicitly allowed
+3. **Last resort: tell the user.** If neither is possible, do NOT fill the page with hand-rolled SVG illustrations or div-based "fake screenshots." Instead, leave clearly-labeled placeholder slots (`<!-- TODO: hero product photo, 1600x1200 -->`) and at the end of the response say: *"This page needs real images at: \[list of placements\]. Please generate or provide them."*
+
+**Even minimalist sites need real images.** A pure-text page is not minimalism. It is incomplete work. Even an editorial Linear-style site needs at least 2-3 real images (hero, one product/lifestyle shot, one supporting image). Generate B&W minimalist photography if the brief is restrained; do not skip images entirely because the dial is low.
+
+**Real company logos for social proof.** When the brief calls for a "Trusted by / Used by / Customers" logo wall, do NOT default to plain text wordmarks (`<span>Acme Co</span>` styled in a row). Use real SVG logos:
+* **Source: Simple Icons** (`https://cdn.simpleicons.org/{slug}/ffffff` for any color, or `simple-icons` npm package). Covers most known brands.
+* **Alternative: devicon** for tech-stack logos (`@svgr/cli` or CDN).
+* **Make-up the brand name? Then make-up an SVG mark too.** Generate a simple monogram (one letter in a circle, two-letter ligature, abstract glyph) rendered as an inline `<svg>` matching the page style. Plain text wordmarks for invented brand names look generic.
+* **Always** ensure logos render in both light and dark mode (white-on-dark, black-on-light, or single-color theme variable).
+* **LOGO-ONLY rule (mandatory):** logo wall = logos and nothing else. Do NOT print industry / category labels below each logo (no `Vercel` + `hosting` underneath, no `Stripe` + `payments`, no `Cloudflare` + `infra`). The logo is the credibility, the label adds nothing the user does not already know. Optional: brand name as alt-text for screen readers, optional link to the brand's site. That is it.
+
+**Hand-rolled illustrations:**
+* SVG icons from libraries: fine (see Section 3.C).
+* Hand-rolled decorative SVGs (custom illustrations, logos, marks): **strongly discouraged**, never as default. Acceptable only when:
+  - The brief explicitly calls for it ("draw me an SVG logo")
+  - It's a single, simple geometric mark (a square, a circle, a wordmark in display type)
+  - You're confident in the output quality
+
+**Div-based fake screenshots are banned.** A "hand-built product preview" rendered with `<div>` rectangles, fake task lists, fake dashboards, fake terminal windows is a Tell. If you need to show a product:
+* Use a real screenshot URL if one exists
+* Generate one via image tool
+* Use a real component preview (an actual mini-version of the UI inside the page)
+* Or skip the preview entirely and use editorial photography
+
+**Hero needs a real visual.** Text + gradient blob is not a hero - it's a placeholder.
+
+### 4.9 Content Density
+
+Landing pages live on the **first impression**, not the full read. Cut ruthlessly.
+
+* **Default content shape per section:** short headline (≤ 8 words) + short sub-paragraph (≤ 25 words) + one visual asset OR one CTA. Anything more must be justified by the section's job.
+* **No data-dump sections.** A 20-row publication table, a 30-row award list, a giant pricing matrix on a marketing page = wrong layout. Use:
+  - Top 3-5 highlights + "View full list" link
+  - Marquee / carousel for breadth
+  - Different page entirely if the data is the product
+* **Long lists need a different UI component, not a longer list.** Default `<ul>` with bullets / `divide-y` rows is the lazy choice. If you have > 5 items, reach for one of these instead:
+  - 2-column split with grouped items
+  - Card grid with image + label per item
+  - Tabs / accordion if items are categorisable
+  - Horizontal scroll-snap pills
+  - Carousel for breadth-heavy lists (testimonials, logos, capabilities)
+  - Marquee for "lots-of-things-that-don't-need-individual-attention"
+  A spec sheet with 10 rows + a hairline under every row is the WORST default. Either group rows into 2-3 chunks with sparse dividers, or move to a card-per-spec layout.
+* **Spec sheets specifically (the Marrow-cookware pattern).** A long product specification table with `border-b` on every row is the AI default for cookware / hardware / apparel / artisan-goods briefs. Banned. Concrete alternatives:
+  - **2-col card grid:** each spec gets its own card with the spec name, the value (large display number), and a one-line "why it matters" body. Cards arranged 2-col on desktop, 1-col mobile.
+  - **Scroll-snap horizontal pills:** each spec is a pill, user can flick through.
+  - **Grouped chunks:** group 10 specs into 3 logical clusters (e.g. "Materials", "Cooking", "Warranty"), each cluster gets ONE soft divider and a cluster heading.
+  - **Featured-vs-rest:** 3-4 hero specs visualised as large display tiles, the rest collapsed under a "View full specifications" disclosure.
+
+* **COPY SELF-AUDIT (mandatory before ship):** Before declaring any task done, re-read every visible string on the page (headlines, subheads, eyebrows, button labels, body copy, captions, alt text, footer text, error messages). Flag any string that is:
+  - **Grammatically broken** ("free on its past", "two plans but one is honest", "to put it on the table" out of context)
+  - **Has unclear referents** ("we plan to stay that way" without prior context)
+  - **Sounds like AI hallucination** (cute-but-wrong wordplay, forced metaphors that don't track, "elegant nothing" phrases)
+  - **Reads like an LLM trying to sound thoughtful** (passive-aggressive humility, fake-craftsman labels, mock-poetic micro-meta)
+  Rewrite every flagged string. If unsure whether a string makes sense, replace it with a plain functional sentence. AI-generated cute copy is worse than boring copy.
+* **Fake-precise numbers are flagged.** Numbers like `92%`, `4.1×`, `48k`, `5.8 mm`, `13.4 lb` either:
+  - Come from real data (brief, brand guidelines, public metrics) - fine
+  - Are explicitly labeled as mock (`<!-- mock -->`, "example", "sample data") - fine
+  - Are AI-invented spec aesthetics - banned. Don't fake engineering precision the brand doesn't claim.
+* **One copy register per page.** Don't mix technical mono ("47 tasks · 0.6 ctx-switches/day"), editorial prose, and marketing punch in the same composition unless the brand voice explicitly calls for it.
+