medesign 0.0.0-stage → 1.2.0

package/references/eng-layout.md

@@ -0,0 +1,28 @@
+### 4.7 Layout Discipline (Hard Rules. Failing any of these is shipping broken work)
+
+* **Hero MUST fit in the initial viewport.** Headline max 2 lines on desktop, subtext max **20 words** AND max 3-4 lines, CTAs visible without scroll. If the copy is too long: reduce font scale OR cut copy. If you cannot describe the value-prop in 20 words of subtext, the value-prop is unclear, not the rule too tight. Never let the hero overflow and force scroll to find the CTA.
+* **Hero font-scale discipline.** Plan font size and image size *together*. If the hero asset is large and the headline is more than 6 words, do not start at `text-7xl/text-8xl`. Default sensible range: `text-4xl md:text-5xl lg:text-6xl` for most heroes; `text-6xl md:text-7xl` only when the headline is 3-5 words. A 4-line hero headline is always a font-size error, never a copy-length error.
+* **HERO TOP PADDING CAP (mandatory):** Hero top padding max `pt-24` (≈6rem) at desktop. More than that means the hero content floats halfway down the viewport and reads as a layout bug, not as intentional space. If your hero needs more breathing room, increase font scale or asset size, not top padding.
+* **HERO STACK DISCIPLINE (max 4 text elements).** The hero is a single moment, not a feature list. Allowed text elements, max 4 in total:
+  1. Eyebrow (small uppercase label) OR brand strip OR neither - pick zero or one
+  2. Headline (max 2 lines, see above)
+  3. Subtext (max 20 words, max 4 lines)
+  4. CTAs (1 primary + max 1 secondary)
+  - **BANNED in the hero:** tiny tagline below CTAs ("Works with GitHub, GitLab, and self-hosted Git"), trust micro-strip ("Used by engineering teams at..."), pricing teaser ("Free for solo, $10/user for teams"), feature bullet list, social-proof avatar row. All of those move to dedicated sections directly below the hero.
+  - If you have an eyebrow AND a tagline below CTAs in the same hero, drop the tagline. If you have a brand strip AND a tagline, drop the tagline. One small text element per hero, max.
+* **"Used by" / "Trusted by" logo wall belongs UNDER the hero, never inside it.** The hero is for the value prop and primary CTA. The logo wall is a separate section directly below. Do not stuff trust logos into the same flex row as the hero copy.
+* **Navigation MUST render on a single line on desktop.** If items don't fit at `lg` (1024px), condense labels, drop secondary items, or move to a hamburger. A two-line nav at desktop is broken design.
+* **Navigation height cap: 80px max desktop, default 64-72px.** No huge "agency" nav bars that eat 15% of the viewport.
+* **Bento grids MUST have rhythm, not one-sided repetition.** Do not stack 6 left-image / right-text rows. Vary the composition: alternate full-width feature rows, asymmetric tile sizes, vertical breaks.
+* **BENTO CELL COUNT RULE (mandatory):** A bento grid has EXACTLY as many cells as you have content for. 3 items → 3 cells (1+2 split, or 2+1, or asymmetric trio). 5 items → 5 cells (2+3, 3+2, hero+4, etc.). If your grid has an empty cell in the middle or at the end, you planned wrong. Re-shape the grid; do not paste a blank tile.
+* **Section-Layout-Repetition Ban.** Once you use a layout family for a section (e.g., 3-column-image-cards, full-width-quote, split-text-image), that family can appear at most ONCE on the page. "Selected commissions" must not look like "What we do." A landing page with 8 sections must use at least 4 different layout families.
+* **ZIGZAG ALTERNATION CAP (mandatory).** Alternating "left-image + right-text" then "left-text + right-image" zigzag layout = banal. Max 2 sections in a row with this image+text-split pattern. The 3rd consecutive image+text split is a Pre-Flight Fail. Break the pattern with a full-width section, a vertical-stack section, a bento grid, a marquee, or a different layout family.
+* **EYEBROW RESTRAINT (mandatory, the #1 violated rule in production tests).** An "eyebrow" is the small uppercase wide-tracking label sitting above a section headline (e.g. `FOUR COLORWAYS`, `SELECTED WORK`, `THE HARDWARE`, `Git-native task management`). Typical CSS signature: `text-[11px] uppercase tracking-[0.18em]`, `font-mono text-[10.5px] uppercase tracking-[0.22em]`. Every AI-built site puts an eyebrow above EVERY section header, producing the same templated rhythm. Hard rule:
+  - **Maximum 1 eyebrow per 3 sections.** Hero counts as 1. So a page with 9 sections may use at most 3 eyebrows total.
+  - If section A has an eyebrow, the next 2 sections cannot have one.
+  - **Pre-Flight Check is mechanical:** count instances of `uppercase tracking` (or similar small-caps mono labels above headlines) across all section components. If count > ceil(sectionCount / 3), the output fails.
+  - **What to do instead of an eyebrow:** drop it entirely. The headline alone is enough. If you need to categorize a section, the section's location on the page already categorizes it; no label needed.
+* **SPLIT-HEADER BAN (mandatory).** The pattern "left big headline + right small explainer paragraph" as a section header (left col-span-7/8, right col-span-4/5 with a small body paragraph floating in the right column) is **banned as default**. Sections should have ONE focused message. If you genuinely need both a headline and an explainer paragraph, stack them vertically (headline on top, body below, max-width 65ch). Reach for the split-header pattern only when there is a real compositional reason (e.g., the right column carries a visual or interactive element, not just filler text).
+* **Bento Background Diversity (mandatory).** Bento and feature-grid sections cannot be 6 white-on-white cards with text inside. At least 2-3 cells in any multi-cell grid need real visual variation: a real image, a brand-appropriate gradient (not AI-purple), a pattern, a tinted background. A cream-on-cream bento with only typography inside reads as boring AI default, even when the rest of the page is good.
+* **Mobile collapse must be explicit per section.** For every multi-column layout, declare the `< 768px` fallback in the same component. No "it'll work, Tailwind handles it" assumptions.
+

package/references/eng-other.md

@@ -0,0 +1,26 @@
+## 4. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
+
+LLMs default to clichés. Override these defaults proactively. Each rule has a context-aware override path.
+
+### 4.3 Layout Diversification
+* **ANTI-CENTER BIAS:** Centered Hero / H1 sections are avoided when `DESIGN_VARIANCE > 4`. Force "Split Screen" (50/50), "Left-aligned content / right-aligned asset", "Asymmetric white-space", or scroll-pinned structures.
+* **Override:** centered hero is OK for editorial / manifesto / launch-announcement briefs where the message itself is the design.
+
+### 4.4 Materiality, Shadows, Cards
+* Use cards ONLY when elevation communicates real hierarchy. Otherwise group with `border-t`, `divide-y`, or negative space.
+* When a shadow is used, tint it to the background hue. No pure-black drop shadows on light backgrounds.
+* For `VISUAL_DENSITY > 7`: generic card containers are banned. Data metrics breathe in plain layout.
+* **SHAPE CONSISTENCY LOCK (mandatory):** Pick ONE corner-radius scale for the page and stick to it. Options: all-sharp (radius 0), all-soft (radius 12-16px), all-pill (full radius for interactive). Mixed systems are allowed only when there is a documented rule (e.g. "buttons are full-pill, cards are 16px, inputs are 8px") and that rule is followed everywhere. Round buttons in a square layout, or square cards on a pill-button page, is broken design.
+
+### 4.6 Data & Form Patterns
+* Label ABOVE input. Helper text optional but present in markup. Error text BELOW input. Standard `gap-2` for input blocks.
+* No placeholder-as-label. Ever.
+
+### 4.10 Quotes & Testimonials
+
+* **Max 3 lines** of quote body. Never 6. If the original quote is longer → cut it. A landing-page quote is a snippet, not the full review.
+* For very small font sizes (e.g. footer-style testimonials), the line cap can stretch slightly. Spirit: "fits in a glance."
+* **No em-dashes inside the quote text** as design flourish (long pauses, kinetic em-dashes, em-dash-bullets). See Section 9.G - em-dash is completely banned.
+* Attribution: name + role + (optionally) company. Never name only ("- Sarah").
+* Quote marks: use real typographic quotes ( " " ) or none at all. Not straight ASCII ( " ).
+

package/references/eng-states-theme.md

@@ -0,0 +1,22 @@
+### 4.5 Interactive UI States
+LLMs default to "static successful state only." Always implement full cycles:
+* **Loading:** Skeletal loaders matching the final layout's shape. Avoid generic circular spinners.
+* **Empty States:** Beautifully composed; indicate how to populate.
+* **Error States:** Clear, inline (forms), or contextual (toasts only for transient).
+* **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]` to simulate a physical push.
+* **BUTTON CONTRAST CHECK (mandatory, a11y):** Before shipping any button, verify the button text is readable against the button background. White button + white text, `bg-white` CTA with `text-white` label, transparent button against the page background with no border → all banned. Audit every CTA: contrast ratio WCAG AA min (4.5:1 for body, 3:1 for large text 18px+). Same rule applies to ghost buttons over photographic backgrounds (use a backdrop, scrim, or stroke).
+* **CTA BUTTON WRAP BAN (mandatory):** Button text MUST fit on one line at desktop. If a label like "VIEW SELECTED WORK" wraps to 2 or 3 lines, the button is broken. Fix by EITHER shortening the label (3 words max for primary CTAs, ideally 1-2) OR widening the button (do not artificially constrain `max-width` on CTAs). Wrapped CTAs at desktop are a Pre-Flight Fail.
+* **NO DUPLICATE CTA INTENT (mandatory):** Two CTAs with the same intent on one page is a Pre-Flight Fail. Examples of same intent: "Get in touch" + "Contact us" + "Let's talk" + "Start a project" + "Start something" + "Reach out" = all "contact" intent → pick ONE label and use it everywhere on the page (nav, hero, footer). Same for "Try free" + "Get started" + "Sign up free" (all "signup" intent) and "View work" + "See selected work" + "Browse projects" (all "portfolio" intent). One label per intent.
+* **FORM CONTRAST CHECK (mandatory, a11y):** Form inputs, placeholder text, focus rings, helper text, and error text all pass WCAG AA contrast against the section background. Light placeholders on a near-white form, white form on white page section, form labels grayer than 4.5:1 contrast → all banned. Audit every form before shipping.
+
+### 4.11 Page Theme Lock (Light / Dark Mode Consistency)
+
+The page has ONE theme. Sections do not invert.
+
+* If the page is dark mode, ALL sections are dark mode. No light-mode-warm-paper section sandwiched between dark sections (or vice versa). The user must not feel they walked into a different website mid-scroll.
+* The exception: if the brief explicitly calls for a "Color Block Story" or "Theme Switch on Scroll" device AND that is a deliberate composition (one full theme switch with a strong transition, not random alternation), it is allowed once per page.
+* Default behaviour: pick light, dark, or auto (`prefers-color-scheme`) at the page level and lock it. Section-level background tints within the same theme family are fine (`bg-zinc-950` next to `bg-zinc-900`); flipping to `bg-amber-50` in the middle of a `bg-zinc-950` page is broken.
+* When using a design system with built-in theming (Radix Themes, shadcn/ui with `<Theme>`), set the theme ONCE in `layout.tsx` or the page root. Do not let individual sections override.
+
+---
+

package/references/eng-type-color.md

@@ -0,0 +1,44 @@
+### 4.1 Typography
+* **Display / Headlines:** Default `text-4xl md:text-6xl tracking-tighter leading-none`.
+* **Body / Paragraphs:** Default `text-base text-gray-600 leading-relaxed max-w-[65ch]`.
+* **Sans font choice:**
+  * **Discouraged as default:** `Inter`. Pick `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`, or a brand-appropriate serif first.
+  * **Override:** Inter is acceptable when the user explicitly asks for a neutral / standard / Linear-style feel, or when the brief is a public-sector / accessibility-first site.
+* **Pairings to know:** `Geist` + `Geist Mono`, `Satoshi` + `JetBrains Mono`, `Cabinet Grotesk` + `Inter Tight`, `GT America` + `IBM Plex Mono`.
+
+* **SERIF DISCIPLINE (VERY DISCOURAGED AS DEFAULT):**
+  * Serif is **very discouraged as the default font for any project.** "It feels creative / premium / editorial" is NOT a reason to reach for serif. The agent's default mental model that "creative brief = serif" is the single most-tested AI tell in production rounds.
+  * **Serif is only acceptable when ONE of these is explicitly true:**
+    - The brand brief literally names a serif font, OR
+    - The aesthetic family is genuinely editorial / luxury / publication / manuscript / heritage / vintage AND you can articulate why this specific serif fits this specific brand
+  * For everything else (creative agency, design studio, modern brand, premium consumer, portfolio, lifestyle), **default sans-serif display** (Geist Display, ABC Diatype, Söhne Breit, Cabinet Grotesk Display, Migra Sans, GT Walsheim, Inter Display, PP Neue Montreal). Sans display fonts are not "boring" — they are the default for the same reason black is the default in fashion.
+  * **EMPHASIS RULE (related):** When you want to emphasize a word within a headline (the kinetic "and `spatial` design" type move), use **italic or bold of the SAME font**. Do NOT inject a random serif word into a sans headline (or vice versa) just to add visual interest. Mixed-family emphasis is amateur. Italic/bold emphasis in the same family is the right move.
+  * **Specifically BANNED as defaults:** `Fraunces` and `Instrument_Serif` (the two LLM-favorite display serifs).
+  * **If a serif is justified** (rare, per the above), rotate from this pool, do NOT reuse the same serif across consecutive projects: PP Editorial New, GT Sectra Display, Cardinal Grotesque, Reckless Neue, Tiempos Headline, Recoleta, Cormorant Garamond, Playfair Display, EB Garamond, IvyPresto, Migra, Editorial Old, Saol Display, Söhne Breit Kursiv, Domaine Display, Canela, Schnyder, Tobias, NB Architekt, ITC Galliard.
+
+* **ITALIC DESCENDER CLEARANCE (mandatory):** When italic is used in display type and the word contains a descender letter (`y g j p q`), `leading-[1]` or `leading-none` will clip the descender. Use `leading-[1.1]` minimum and add `pb-1` or `mb-1` reserve on the wrapping element. Audit every italic word in display headlines before shipping.
+
+### 4.2 Color Calibration
+* Max 1 accent color. Saturation < 80% by default.
+* **THE LILA RULE:** The "AI Purple / Blue glow" aesthetic is discouraged as a default. No automatic purple button glows, no random neon gradients. Use neutral bases (Zinc / Slate / Stone) with high-contrast singular accents (Emerald, Electric Blue, Deep Rose, Burnt Orange, etc.).
+* **Override:** if the brand or brief explicitly asks for purple / violet / lila, embrace it. But execute with intent: consistent palette, harmonised neutrals, restrained gradients. Not generic AI gradient slop.
+* **One palette per project.** Do not fluctuate between warm and cool grays within the same project.
+* **COLOR CONSISTENCY LOCK (mandatory):** Once an accent color is chosen for a page, it is used on the WHOLE page. A warm-grey site does not suddenly get a blue CTA in section 7. A rose-accented site does not get a teal status badge in the footer. Pick one accent, lock it, audit every component before shipping.
+
+* **PREMIUM-CONSUMER PALETTE BAN (mandatory, second-most-recurring AI-tell):**
+  * For premium-consumer briefs (cookware, wellness, artisan, luxury, heritage craft, DTC home goods, etc.) the LLM default is **warm beige/cream + brass/clay/oxblood/ochre + espresso/ink dark text**. Concretely banned hex families as default backgrounds and accents:
+    - Backgrounds: `#f5f1ea`, `#f7f5f1`, `#fbf8f1`, `#efeae0`, `#ece6db`, `#faf7f1`, `#e8dfcb` (all "warm paper / cream / chalk / bone")
+    - Accents: `#b08947`, `#b6553a`, `#9a2436`, `#9c6e2a`, `#bc7c3a`, `#7d5621` (all "brass / clay / oxblood / ochre")
+    - Text: `#1a1714`, `#1a1814`, `#1b1814` (all "espresso / warm near-black")
+  * This palette is BANNED as the default reach for premium-consumer briefs. Every premium-consumer site you have ever shipped uses this exact palette. The brand becomes invisible.
+  * **Default alternatives (rotate, do not reuse):**
+    - **Cold Luxury:** silver-grey + chrome + smoke (think Tesla, Apple Watch Hermes-without-the-leather)
+    - **Forest:** deep green + bone + amber accent (think Filson, Patagonia premium)
+    - **Black and Tan:** true off-black + warm tan, sharp contrast, no beige
+    - **Cobalt + Cream:** saturated blue against a single neutral, no brass
+    - **Terracotta + Slate:** warm rust against cool grey, no brass
+    - **Olive + Brick + Paper:** muted olive plus brick-red accent
+    - **Pure monochrome + single saturated pop:** off-white + off-black + one bright accent (electric blue, emerald, hot pink, etc.)
+  * **Palette-rotation rule:** if the previous premium-consumer project you generated used the beige+brass family, this one MUST use a different family. Do not ship the same warm-craft palette twice in a row.
+  * **Override:** the beige+brass+espresso palette is acceptable ONLY when the brand brief explicitly names those colors, or when the brand identity is genuinely vintage / artisan / warm-craft AND you can articulate why this specific palette fits this specific brand. Default-reaching for it because "this is a cookware brief" is banned.
+

package/references/icon-design.md

@@ -0,0 +1,122 @@
+# Icon Design Reference
+
+AI-powered SVG icon generation using Gemini 3.1 Pro Preview. 15 styles, 12 categories, multi-size export.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/icon/generate.py` | Generate SVG icons with Gemini 3.1 Pro Preview |
+
+## Commands
+
+### Generate Single Icon
+
+```bash
+python3 scripts/icon/generate.py --prompt "settings gear" --style outlined
+python3 scripts/icon/generate.py --prompt "shopping cart" --style filled --color "#6366F1"
+python3 scripts/icon/generate.py --name "dashboard" --category navigation --style duotone
+```
+
+### Generate Batch Variations
+
+```bash
+python3 scripts/icon/generate.py --prompt "cloud upload" --batch 4 --output-dir ./icons
+python3 scripts/icon/generate.py --prompt "notification bell" --batch 6 --style outlined --output-dir ./icons
+```
+
+### Generate Multiple Sizes
+
+```bash
+python3 scripts/icon/generate.py --prompt "user profile" --sizes "16,24,32,48" --output-dir ./icons
+```
+
+### List Styles/Categories
+
+```bash
+python3 scripts/icon/generate.py --list-styles
+python3 scripts/icon/generate.py --list-categories
+```
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--prompt, -p` | Icon description | required |
+| `--name, -n` | Icon name (for filename) | - |
+| `--style, -s` | Icon style (15 options) | - |
+| `--category, -c` | Icon category for context | - |
+| `--color` | Primary hex color | currentColor |
+| `--size` | Display size in px | 24 |
+| `--viewbox` | SVG viewBox size | 24 |
+| `--output, -o` | Output file path | auto |
+| `--output-dir` | Output directory (batch) | ./icons |
+| `--batch` | Number of variations | - |
+| `--sizes` | Comma-separated sizes | - |
+
+## Available Styles
+
+| Style | Stroke | Fill | Best For |
+|-------|--------|------|----------|
+| outlined | 2px | none | UI interfaces, web apps |
+| filled | 0 | solid | Mobile apps, nav bars |
+| duotone | 0 | dual | Marketing, landing pages |
+| thin | 1-1.5px | none | Luxury brands, editorial |
+| bold | 3px | none | Headers, hero sections |
+| rounded | 2px | none | Friendly apps, health |
+| sharp | 2px | none | Tech, fintech, enterprise |
+| flat | 0 | solid | Material design, Google-style |
+| gradient | 0 | gradient | Modern brands, SaaS |
+| glassmorphism | 1px | semi | Modern UI, overlays |
+| pixel | 0 | solid | Gaming, retro |
+| hand-drawn | varies | none | Artisan, creative |
+| isometric | 1-2px | partial | Tech docs, infographics |
+| glyph | 0 | solid | System UI, compact |
+| animated-ready | 2px | varies | Interactive UI, onboarding |
+
+## Icon Categories
+
+| Category | Icons |
+|----------|-------|
+| navigation | arrows, menus, home, chevrons |
+| action | edit, delete, save, download, upload |
+| communication | email, chat, phone, notification |
+| media | play, pause, volume, camera |
+| file | document, folder, archive, cloud |
+| user | person, group, profile, settings |
+| commerce | cart, bag, wallet, credit card |
+| data | chart, graph, analytics, dashboard |
+| development | code, terminal, bug, git, API |
+| social | heart, star, bookmark, trophy |
+| weather | sun, moon, cloud, rain |
+| map | pin, location, compass, globe |
+
+## SVG Best Practices
+
+- **ViewBox**: Use `0 0 24 24` (standard) or `0 0 16 16` (compact)
+- **Colors**: Use `currentColor` for CSS inheritance, avoid hardcoded colors
+- **Accessibility**: Always include `<title>` element
+- **Optimization**: Minimal path nodes, no embedded fonts or raster images
+- **Sizing**: Design at 24px, test at 16px and 48px for clarity
+- **Stroke**: Use `stroke-linecap="round"` and `stroke-linejoin="round"` for outlined styles
+
+## Model
+
+- **gemini-3.1-pro-preview**: Best thinking, token efficiency, factual consistency
+- Text-only output (SVG is XML text) — no image generation API needed
+- Supports structured output for consistent SVG formatting
+
+## Workflow
+
+1. Describe icon → `--prompt "settings gear"`
+2. Choose style → `--style outlined`
+3. Generate → script outputs .svg file
+4. Optionally batch → `--batch 4` for variations
+5. Multi-size export → `--sizes "16,24,32,48"`
+
+## Setup
+
+```bash
+export GEMINI_API_KEY="your-key"
+pip install google-genai
+```

package/references/image-mockup-direction.md

@@ -0,0 +1,53 @@
+# Premium Web & Mobile UI Image Art Direction
+
+มาตรฐานการออกแบบคำสั่งสร้างภาพต้นแบบ (UI Mockup Direction) สำหรับหน้าเว็บและแอปมือถือ เพื่อสร้างภาพอ้างอิงระดับเวิลด์คลาสก่อนลงมือเขียนโค้ดจริง
+
+---
+
+## 1. กฎเหล็กการสร้างภาพ (Hard Output Rules)
+
+1. **One Separate Image Per Section (หน้าเว็บ):**
+   - สร้างภาพแนวนอน (Aspect Ratio `16:9` หรือ `3:2`) แยก 1 ภาพต่อ 1 Section เสมอ
+   - ห้ามรวบทั้งหน้าเว็บ Landing Page ลงในภาพแนวยาวเพียงภาพเดียวเด็ดขาด เพราะจะทำให้ฟอนต์เล็ก ละเอียด และไม่สามารถแกะโค้ดต่อได้
+2. **One Focused Screen / Flow Per Generation (แอปมือถือ):**
+   - สร้างภาพแนวตั้ง (Aspect Ratio `9:16` หรือ `3:4`) เน้นหน้าจอเดี่ยวที่คมชัด หรือ Side-by-side Flow ไม่เกิน 2-3 จอ
+   - จำลอง Safe Area ของ iOS/Android (Status Bar, Home Indicator, Dynamic Island) ให้สมจริง
+
+---
+
+## 2. ทลายความจำเจของ Hero Section (Break Hero Clichés)
+
+หลีกเลี่ยงการใช้เลย์เอาต์ซ้ำซาก **"ข้อความซ้าย / ภาพขวา"** เป็นค่าเริ่มต้น ให้เลือกใช้ทางเลือกต่อไปนี้:
+- **Centered over Ambient Depth:** ข้อความกึ่งกลางบนพื้นหลังกราฟิก 3D หรือภาพ Abstract Depth
+- **Bottom-Left Over Canvas:** ข้อความวางชิดซ้ายล่าง พาดทับฉากหลังขนาดใหญ่แบบภาพยนตร์
+- **Editorial Asymmetry:** ข้อความตัวใหญ่แบบนิตยสาร พร้อมคอลัมน์รูปภาพขนาดเล็กตัดกัน
+- **Stacked Split Canvas:** สื่อ/เดโมอยู่กึ่งกลางเต็มจอ พร้อม Floating Badge แสดงฟังก์ชันหลัก
+
+---
+
+## 3. มาตรฐานการกำหนดคำสั่ง (Prompt Blueprint)
+
+### ก. โครงสร้างพรอมต์หน้าเว็บ (Web Section Prompt):
+```text
+UI concept comp for a [industry/purpose] website, [specific section name] section.
+Layout: [e.g. Asymmetric bento grid / Full-width hero with bottom typography].
+Style & Aesthetics: Premium dark-mode void background (#09090b), crisp 1px borders with subtle glow, refined typography with Serif display headline and sans-serif body, restrained indigo accent (#6366f1).
+Visual Content: High-fidelity dashboard widgets, clean interactive toggles, real data visualizations, generous whitespace, sharp contrast, zero blur on text elements.
+Presentation: Direct screen capture, clean 16:9 desktop viewport, professional Dribbble/Awwwards award-winning aesthetic, flat straight-on view, no device mockup frame.
+```
+
+### ข. โครงสร้างพรอมต์แอปมือถือ (Mobile App Screen Prompt):
+```text
+Mobile app UI design for iOS [purpose/domain, e.g. Fintech wealth tracker], single screen [e.g. Home Dashboard].
+Aesthetics: Warm dark surface (#111115), frosted glass navigation bar, refined tabular figures with Geist Mono font, subtle accent voltage (#f59e0b).
+Components: Top status bar with Dynamic Island, total balance hero card, segmented asset allocation chart, quick action pill buttons, recent transactions feed.
+Presentation: Ultra-clean 9:16 mobile screen view, pixel-perfect native iOS guidelines, crisp typography hierarchy, believable metric values, no external phone frame.
+```
+
+---
+
+## 4. สิ่งที่ต้องกำจัดในภาพต้นแบบ (Anti-Generic Tells)
+- ห้ามใช้คำศัพท์ Interface ปลอมหรือข้อความ Lorem Ipsum ที่มั่วซั่ว
+- ห้ามใส่แสงนีออนฟุ้งกระจายจนอ่านข้อความไม่ออก
+- ห้ามสร้างการ์ดซ้อนการ์ดเกิน 3 ชั้น
+- รักษาคู่สีให้คุมโทน สอดคล้องกับ [user-profile.json](file:///D:/WSL/.gemini/config/skills/medesign/user-profile.json) ของผู้ใช้

package/references/image-to-code.md

@@ -0,0 +1,46 @@
+# Image-to-Code Implementation Pipeline
+
+กระบวนการแปลงภาพต้นแบบหรือ Mockup ให้กลายเป็นโค้ดส่วนติดต่อผู้ใช้ (Frontend Code) คุณภาพสูง มีความเที่ยงตรง (High Fidelity) และสอดคล้องกับมาตรฐานทางวิศวกรรม
+
+---
+
+## 1. วงจรการแปลง 4 ขั้นตอน (4-Stage Conversion Flow)
+
+```mermaid
+flowchart LR
+    A["1. Visual Analysis (ผ่าสรีระภาพ)"] --> B["2. Token Extraction (สกัดสี/ฟอนต์)"]
+    B --> C["3. Component Tree (แบ่งกล่อง)"]
+    C --> D["4. Production Code (เขียนโค้ด)"]
+```
+
+---
+
+## 2. รายละเอียดขั้นตอนการปฏิบัติงาน
+
+### ขั้นที่ 1: การวิเคราะห์ภาพเชิงลึก (Deep Visual Decomposition)
+- **Spatial Grid:** ระบุจำนวนคอลัมน์, Max Width, และระยะห่าง (Gap, Margin, Padding)
+- **Visual Hierarchy:** แยกแยะลำดับสายตา (Display Title $\rightarrow$ Subtitle $\rightarrow$ Primary CTA $\rightarrow$ Secondary Metadata)
+- **Surface & Elevation:** ตรวจสอบความทึบของพื้นผิว (Solid, Frosted Glass `backdrop-blur`, Border Radius, Drop Shadows)
+
+### ขั้นที่ 2: การสกัด Token และประสานกับ User DNA
+- แมปคู่สีที่พบในภาพเข้ากับ Palette ใน `user-profile.json` หรือ [design-core.md](file:///D:/WSL/.gemini/config/skills/medesign/references/design-core.md)
+- แปลงค่าสีให้เป็นตัวแปร Tailwind หรือ CSS Variables (เช่น `bg-background`, `border-border`, `text-foreground`)
+- เลือกใช้คู่ฟอนต์ตามระบบ: Heading (Serif หรือ Display มีสไตล์) + Body (Clean Sans) + Monospace สำหรับตัวเลข
+
+### ขั้นที่ 3: การแตกชิ้นส่วน Component (Modular Tree)
+- แบ่งโค้ดออกเป็นชิ้นส่วนย่อย (เช่น `Navbar`, `HeroSection`, `BentoGrid`, `MetricCard`, `Footer`)
+- กำหนด Property และ State ที่จำเป็น (เช่น Hover effects, Active states, Responsive breakpoints)
+
+### ขั้นที่ 4: การลงมือเขียนโค้ดจริง (High-Fidelity Implementation)
+- **HTML Semantics:** ใช้แท็กที่มีความหมาย (`<header>`, `<main>`, `<section>`, `<article>`, `<nav>`)
+- **Responsive Layout:** พัฒนาแบบ Mobile-First พร้อมขยายเป็น Grid/Flex บน `md:` และ `lg:`
+- **Micro-Interactions:** เติมลูกเล่นเบาๆ เช่น `transition-all duration-150`, `hover:border-white/20`, `active:scale-[0.98]`
+- **Data Hardening:** ใช้ข้อมูลจำลองที่สมจริง (Realistic Mock Data) ห้ามใช้ข้อความขยะ
+
+---
+
+## 3. เกณฑ์การตรวจรับงานแปลงโค้ด (Fidelity Verification)
+- [ ] สัดส่วนระยะห่าง (Whitespace) ตรงตามภาพต้นแบบ ไม่เบียดหรือแน่นเกินไป
+- [ ] ค่าสีและ Contrast ผ่านเกณฑ์ WCAG AA สำหรับการอ่าน
+- [ ] ปุ่ม Action ทุกปุ่มมี Hover / Active feedback
+- [ ] โค้ดคอมไพล์ผ่าน 0 errors และไม่มี Dependency นอกเหนือจากที่โปรเจกต์รองรับ

package/references/impeccable-polish.md

@@ -0,0 +1,85 @@
+# Impeccable UI/UX Polish Heuristics & Craft Floor
+
+This reference provides actionable design heuristics and craftsmanship standards for elevating UI/UX from acceptable to exceptional. Use this guide during the refinement pass of any frontend interface.
+
+---
+
+## 1. Core Principles
+
+- **Commitment Over Hedging:** No timid designs or half-measures. Deliver complete, production-grade interfaces with intentional aesthetic direction.
+- **Bounded Verification Passes:** Do not get trapped in open-ended polish loops. Inspect desktop and mobile layouts in a batched round, triage defects systematically, fix in one focused pass, confirm, and ship.
+- **Refinement vs. Redesign:**
+  - *Refinement (Polish):* Preserves incumbent identity, data structures, and scope while tightening spacing, optical alignment, typography, and micro-interactions.
+  - *Redesign:* Replaces visual language and layout when the foundation itself fails user or business goals.
+
+---
+
+## 2. Surface Modes & Intent
+
+Design for the visitor's primary mode of engagement:
+
+- **Persuade (Landing pages, marketing, product showcases):**
+  - Goal: Visitor decides and takes decisive action.
+  - Direction: Bold typography, clear hierarchy, high-contrast CTAs, authentic imagery, immersive narrative flow.
+- **Operate (Web apps, dashboards, tools, settings, data grids):**
+  - Goal: Visitor completes tasks with speed, precision, and zero friction.
+  - Direction: High scanability, compact predictable spacing, dense tabular layouts, obvious system feedback, keyboard navigation.
+- **Read (Documentation, articles, guides, knowledge bases):**
+  - Goal: Visitor absorbs complex information without eye fatigue.
+  - Direction: Measure bounded to 65–75 characters per line, generous line-height (1.6–1.75), clean typographic scales, clear content outlines.
+- **Experience (Portfolios, creative experiments, interactive showcases):**
+  - Goal: Visitor is immersed in the aesthetic world.
+  - Direction: Interface recedes; artifacts and content lead from the initial viewport.
+
+---
+
+## 3. The Craft Floor (Non-Negotiable Verification Checklist)
+
+Every production interface must satisfy these verification checks:
+
+### Visual Mechanics & Accessibility
+- **Contrast Ratios:** Body and placeholder text $\ge$ 4.5:1; large text $\ge$ 3:1. Secondary text must tint from the background hue or foreground—never raw uncalibrated gray.
+- **Depth & Shadows:** Soft, multi-layered ambient shadows with intentional vertical offsets (`box-shadow: 0 4px 20px -2px rgba(0,0,0,0.08)`). Avoid zero-offset colored halos or arbitrary harsh outlines unless Neobrutalism is explicitly chosen.
+- **Spacing & Vertical Rhythm:** Follow an explicit 4px/8px scale. Group related items tightly; separate distinct sections generously. Ensure space above headings is visibly greater than space below them.
+- **Typography:**
+  - Body measure: 65–75 characters per line.
+  - Tracking floor: `-0.02em` to `-0.04em` on large display headings; neutral or slightly tracked on micro-labels.
+  - Hierarchy: Obvious font-weight and scale jumps (e.g., 14px -> 16px -> 24px -> 36px).
+- **Interactive & Edge States:**
+  - Every interactive component must handle: Default, Hover, Active, Focus-Visible, Disabled, Loading, Empty, and Error states.
+- **Browser Surfaces (The Details Most Engines Miss):**
+  - Style text selection (`::selection`).
+  - Style input carets (`caret-color`).
+  - Style custom slim scrollbars matching theme background.
+  - Provide distinct accessible focus rings (`focus-visible: outline-offset-2`).
+  - Use tabular numbers (`font-variant-numeric: tabular-nums`) for currency, timestamps, and metric tables.
+- **Meaningful Motion:**
+  - Max 150–250ms for micro-interactions; 300–400ms for large layout shifts.
+  - Use ease-out curves (`cubic-bezier(0.16, 1, 0.3, 1)`) for entrances.
+  - Never animate every element independently; orchestrate choreographies or keep transitions subtle.
+
+---
+
+## 4. Anti-Patterns to Refuse
+
+Avoid generic, lazy design habits:
+
+1. **Card Overload:** Do not build pages out of identical cards (icon + heading + paragraph). Use semantic containers, split layouts, and varied content density. Never nest cards inside cards.
+2. **The Hero-Metric Cliché:** Avoid the formulaic "giant number + tiny label + badge" unless it is an actual financial or analytics metric dashboard.
+3. **Gratuitous Gradients:** Avoid gradient fills on body text or illegible gradient borders. Let typography and layout provide emphasis.
+4. **Faux Glassmorphism:** Avoid blurry frosted overlays that compromise contrast and legibility.
+5. **Unicode Icons:** Never use emoji or raw unicode glyphs as user-interface icons. Always use coherent SVG icon systems (e.g., Lucide, Heroicons, Radix Icons).
+6. **Ambiguous Actions:** Buttons and controls must name their exact action ("Export GeoJSON" instead of "Submit" or "Click Here").
+
+---
+
+## 5. Polish Execution Workflow
+
+When tasked with polishing an existing surface:
+
+1. **Audit Incident Code:** Read the existing markup, design tokens, and components without rewriting architecture unnecessarily.
+2. **Prioritize Fixes:**
+   1. *Blockers:* Broken inputs, missing interactive states, overlapping text on mobile.
+   2. *Hierarchy:* Confusing visual order, low contrast, irregular padding.
+   3. *Micro-Polish:* Optical alignments, consistent icon strokes, hover transitions, focus outlines.
+3. **Verify Responsive Adaptability:** Test breakpoints (375px mobile, 768px tablet, 1280px+ desktop).

package/references/intake.md

@@ -0,0 +1,90 @@
+## 0. BRIEF INFERENCE (Read the Room Before Anything Else)
+
+Before touching code or tweaking dials, **infer what the user actually wants**. Most LLM design output is bad because the model jumps to a default aesthetic instead of reading the room.
+
+### 0.A Read these signals first
+1. **Page kind** - landing (SaaS / consumer / agency / event), portfolio (dev / designer / creative studio), redesign (preserve vs overhaul), editorial / blog.
+2. **Vibe words** the user used - "minimalist", "calm", "Linear-style", "Awwwards", "brutalist", "premium consumer", "Apple-y", "playful", "serious B2B", "editorial", "agency-y", "glassy", "dark tech".
+3. **Reference signals** - URLs they linked, screenshots they pasted, products they named, brands they're competing with.
+4. **Audience** - B2B procurement panel vs. design-conscious consumer vs. recruiter scanning a portfolio. The audience picks the aesthetic, not your taste.
+5. **Brand assets that already exist** - logo, color, type, photography. For redesigns, these are starting material, not optional input (see Section 11).
+6. **Quiet constraints** - accessibility-first audiences, public-sector, regulated industries, trust-first commerce, kids' products. These constraints OVERRIDE aesthetic preference.
+
+### 0.B Output a one-line "Design Read" before generating
+Before any code, state in one line: **"Reading this as: \<page kind> for \<audience>, with a \<vibe> language, leaning toward \<design system or aesthetic family>."**
+
+Example reads:
+- *"Reading this as: B2B SaaS landing for technical buyers, with a Linear-style minimalist language, leaning toward Tailwind utilities + Geist + restrained motion."*
+- *"Reading this as: solo designer portfolio for hiring managers, with an editorial / kinetic-type language, leaning toward native CSS + scroll-driven animation + custom typography."*
+- *"Reading this as: redesign of a public-sector service site, with a trust-first language, leaning toward GOV.UK Frontend or USWDS."*
+
+### 0.C If the brief is ambiguous, ask one question, do not guess
+Ask exactly **one** clarifying question - never a multi-question dump - and only when the design read genuinely diverges. Example: *"Should this feel closer to Linear-clean or Awwwards-experimental?"*
+
+If you can confidently infer from context, **do not ask**. Just declare the design read and proceed.
+
+### 0.D Anti-Default Discipline
+Do not default to: AI-purple gradients, centered hero over dark mesh, three equal feature cards, generic glassmorphism on everything, infinite-loop micro-animations everywhere, Inter + slate-900. These are the LLM defaults. Reach past them deliberately based on the design read.
+
+---
+
+## 2. BRIEF → DESIGN SYSTEM MAP
+
+Once you have the design read (Section 0) and dials (Section 1), pick the right foundation. Do not invent CSS for things that have an official package. Do not pretend an aesthetic trend is an official system.
+
+### 2.A When to reach for a real design system (use official packages)
+| Brief reads as… | Reach for | Why |
+|---|---|---|
+| Microsoft / enterprise SaaS / dashboards | `@fluentui/react-components` or `@fluentui/web-components` | Official Fluent UI, Microsoft tokens, accessibility done |
+| Google-ish UI, Material-flavored product | `@material/web` + Material 3 tokens | Official, theme-able via Material Theming |
+| IBM-style B2B / enterprise analytics | `@carbon/react` + `@carbon/styles` | Official Carbon, mature data-density patterns |
+| Shopify app surfaces | `polaris.js` web components / Polaris React | Required for Shopify admin UI |
+| Atlassian / Jira-style product | `@atlaskit/*` + `@atlaskit/tokens` | Official Atlassian DS |
+| GitHub-style devtool / community page | `@primer/css` or `@primer/react-brand` | Official Primer; Brand variant for marketing |
+| Public-sector UK service | `govuk-frontend` | Legally / regulatorily expected |
+| US public-sector / trust-first | `uswds` | Same |
+| Fast local-business / agency MVP | Bootstrap 5.3 | Boring, fast, works |
+| Modern accessible React foundation | `@radix-ui/themes` | Primitives + polished theme |
+| Modern SaaS where you own the components | shadcn/ui (`npx shadcn@latest add ...`) | You own the code, easy to customise; never ship default state |
+| Tailwind-based modern SaaS / AI marketing | Tailwind v4 utilities + `dark:` variant | Default for indie + small team builds |
+
+**Honesty rule:** if the brief reads as one of the systems above, install and use the **official** package. Do not recreate its CSS by hand. Do not import a system's tokens but then override 90% of them.
+
+**One system per project.** Do not mix Fluent React with Carbon in the same tree. Do not import shadcn/ui components into a Material 3 app.
+
+### 2.B When the brief is an aesthetic, not a system
+For these directions, there is **no single official package**. Build with native CSS + Tailwind + a maintained component library. Be honest in code comments about what is borrowed inspiration vs. official material.
+
+| Aesthetic | Honest implementation |
+|---|---|
+| Glassmorphism / "frosted glass" | `backdrop-filter`, layered borders, highlight overlays. Provide solid-fill fallback for `prefers-reduced-transparency`. |
+| Bento (Apple-style tile grids) | CSS Grid with mixed cell sizes. No single library owns this. |
+| Brutalism | Native CSS, monospace, raw borders. No library. |
+| Editorial / magazine | Serif type, asymmetric grid, generous whitespace. No library. |
+| Dark tech / hacker | Mono + accent neon, terminal motifs. No library. |
+| Aurora / mesh gradients | SVG or layered radial gradients. No library. |
+| Kinetic typography | Native CSS animations, scroll-driven animations, GSAP for hijacks. No library. |
+| **Apple Liquid Glass** | Apple documents this for Apple platforms only. **There is no official `liquid-glass.css`.** Web implementations are approximations using `backdrop-filter` + layered borders + highlights. Label clearly as approximation. |
+
+---
+
+## 7. DIAL DEFINITIONS (Technical Reference)
+
+### DESIGN_VARIANCE (Level 1-10)
+* **1-3 (Predictable):** Symmetrical CSS Grid (12-col, equal fr-units), equal paddings, centered alignment.
+* **4-7 (Offset):** `margin-top: -2rem` overlaps, varied image aspect ratios (4:3 next to 16:9), left-aligned headers over center-aligned data.
+* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (`grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`).
+* **MOBILE OVERRIDE:** For levels 4-10, asymmetric layouts above `md:` MUST collapse to strict single-column (`w-full`, `px-4`, `py-8`) on viewports `< 768px`.
+
+### MOTION_INTENSITY (Level 1-10)
+* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only. `prefers-reduced-motion` is the default mode anyway.
+* **4-7 (Fluid CSS):** `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. `animation-delay` cascades for load-ins. Focus on `transform` and `opacity`.
+* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals, parallax, scroll-driven animation (CSS `animation-timeline` or GSAP ScrollTrigger). Use Motion hooks. **NEVER use `window.addEventListener('scroll')`** - it is a hard ban, not a "prefer-not." See Section 5.D for the allowed alternatives.
+
+### VISUAL_DENSITY (Level 1-10)
+* **1-3 (Art Gallery):** Lots of white space. Huge section gaps (`py-32` to `py-48`). Expensive, clean.
+* **4-7 (Daily App):** Standard web app spacing (`py-16` to `py-24`).
+* **8-10 (Cockpit):** Tight paddings. No card boxes; 1px lines separate data. Mandatory: `font-mono` for all numbers.
+
+---
+

package/references/logo-color-psychology.md

@@ -0,0 +1,101 @@
+# Logo Color Psychology
+
+## Primary Color Meanings
+
+### Blue
+- **Psychology:** Trust, stability, professionalism, calm
+- **Industries:** Finance, healthcare, tech, corporate
+- **Hex Examples:** Navy #003366, Royal #0055A4, Sky #0EA5E9
+- **Pairings:** White, gold, light gray
+
+### Red
+- **Psychology:** Energy, passion, urgency, excitement
+- **Industries:** Food, sports, entertainment, sales
+- **Hex Examples:** Crimson #DC2626, Scarlet #EF4444, Burgundy #9F1239
+- **Pairings:** White, black, gold
+- **Caution:** Avoid for healthcare (blood connotation)
+
+### Green
+- **Psychology:** Growth, nature, health, sustainability
+- **Industries:** Eco, wellness, organic, finance (growth)
+- **Hex Examples:** Forest #228B22, Sage #2E8B57, Mint #10B981
+- **Pairings:** White, brown, blue
+
+### Yellow/Gold
+- **Psychology:** Optimism, warmth, luxury, attention
+- **Industries:** Food, children, luxury (gold), energy
+- **Hex Examples:** Gold #D4AF37, Amber #F59E0B, Lemon #FACC15
+- **Pairings:** Black, navy, dark brown
+
+### Purple
+- **Psychology:** Creativity, wisdom, luxury, mystery
+- **Industries:** Beauty, creative, spiritual, premium
+- **Hex Examples:** Royal #7C3AED, Lavender #A78BFA, Deep #581C87
+- **Pairings:** Gold, white, pink
+
+### Orange
+- **Psychology:** Friendly, energetic, confident, youthful
+- **Industries:** Food, sports, entertainment, retail
+- **Hex Examples:** Tangerine #F97316, Coral #FB923C, Burnt #EA580C
+- **Pairings:** White, navy, dark gray
+
+### Black
+- **Psychology:** Sophistication, power, elegance, authority
+- **Industries:** Luxury, fashion, tech, premium
+- **Pairings:** White, gold, silver
+- **Note:** Use for high-end positioning
+
+### White
+- **Psychology:** Purity, simplicity, cleanliness, modern
+- **Use:** Backgrounds, negative space, contrast
+- **Pairings:** Any color (universal neutral)
+
+## Color Combinations by Industry
+
+| Industry | Primary | Secondary | Accent | Avoid |
+|----------|---------|-----------|--------|-------|
+| Tech | Blue, Purple | Gray, White | Teal, Green | Brown, Beige |
+| Healthcare | Blue, Green | Teal, White | Light Purple | Red, Black |
+| Finance | Navy, Blue | Gold, Gray | Green | Bright colors |
+| Food | Red, Orange | Yellow, Brown | Green | Blue (appetite suppressant) |
+| Fashion | Black, White | Gold, Blush | Navy | Neon (unless intentional) |
+| Eco | Green, Brown | Beige, Blue | Yellow | Neon, Black |
+| Children | Multi-color | Pastels | Bright accents | Dark, muted |
+
+## Color Harmony Types
+
+### Monochromatic
+Single color with tints/shades. Safe, cohesive.
+
+### Complementary
+Opposite colors (blue-orange). High contrast, vibrant.
+
+### Analogous
+Adjacent colors (blue-teal-green). Harmonious, natural.
+
+### Triadic
+Three evenly spaced colors. Balanced, dynamic.
+
+## Accessibility Considerations
+
+- Minimum contrast ratio: 4.5:1 (WCAG AA)
+- Avoid red-green only indicators
+- Test in grayscale for clarity
+- Consider colorblind users (~8% of males)
+
+## Quick Reference Palettes
+
+**Tech Professional:**
+Primary: #6366F1 | Secondary: #8B5CF6 | Accent: #06B6D4
+
+**Eco Sustainable:**
+Primary: #228B22 | Secondary: #2E8B57 | Accent: #DEB887
+
+**Luxury Premium:**
+Primary: #1C1917 | Secondary: #D4AF37 | Accent: #FFFFFF
+
+**Healthcare Trust:**
+Primary: #0077B6 | Secondary: #00A896 | Accent: #FFFFFF
+
+**Food Warm:**
+Primary: #DC2626 | Secondary: #F97316 | Accent: #CA8A04