ship-create 1.4.0 → 1.5.0

package/create.mjs

@@ -444,13 +444,17 @@ async function main() {
   }
 
   // Tech-stack reference — agent reads this when making stack decisions.
-  // (Design system is NOT bundled as a static file — the /build command
-  // invokes the ui-ux-pro-max skill to generate one specific to this project.)
   const techStackSrc = path.join(TEMPLATES_DIR, "docs", "tech-stack");
   if (fs.existsSync(techStackSrc)) {
     copyRecursiveExcluding(techStackSrc, path.join(docsDir, "tech-stack"), new Set());
   }
 
+  // Design system + spec templates — filled by /build after user picks theme/font/trend.
+  for (const f of ["DESIGN_SYSTEM.md", "DESIGN_SPEC.md"]) {
+    const src = path.join(TEMPLATES_DIR, "docs", f);
+    if (fs.existsSync(src)) fs.copyFileSync(src, path.join(docsDir, f));
+  }
+
   // ── 8. npm install ─────────────────────────────────────────────────────
   console.log("\nInstalling packages (this takes ~30 seconds)...");
   const install = spawnSync("npm", ["install"], {
@@ -468,6 +472,8 @@ Done! Your project is at: ./${projectSlug}/
 
   docs/PROJECT.md                           — product spec (pre-filled)
   docs/HUMAN_FLOW.md                        — UX flow (pre-filled)
+  docs/DESIGN_SYSTEM.md                     — design tokens & decisions (filled by /build)
+  docs/DESIGN_SPEC.md                       — screen-by-screen design spec (filled by /build)
   docs/tech-stack/STACK_DECISION_MATRIX.md  — stack choices reference
 
 ── Open in your AI coding tool and type /build ─────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ship-create",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Scaffold a new project the SHIP Method way — Structure, Human Flow, Instruction, Publish. No git clone, no API key, just one command.",
   "type": "module",
   "license": "MIT",

package/templates/.claude/commands/build.md

@@ -1,89 +1,134 @@
 ---
-description: Read docs/PROJECT.md and docs/HUMAN_FLOW.md, finalize the build spec, design the UI with the ui-ux-pro-max skill, then start building the app.
+description: Read docs, create build spec, and build the MVP fast — home screen first, white theme by default.
 argument-hint: "[feature name — leave blank to build the full MVP]"
 ---
 
-You are about to build this app using The SHIP Method framework. Follow these steps exactly.
+You are building this app using The SHIP Method. Move fast — the goal is a working MVP the user can see and react to. Refine later.
 
 Argument passed (optional feature focus): "$ARGUMENTS"
 
 ## Step 1 — Read the project docs
 
-Read both of these files now before doing anything else:
+Read both files now:
 - `docs/PROJECT.md` — what we're building and for whom
 - `docs/HUMAN_FLOW.md` — how users move through the product
 
-## Step 2 — Check docs are ready
+## Step 2 — Quick sanity check
 
-Confirm that PROJECT.md has real content (not `[fill in]` placeholders) in:
-- Product Vision
-- Problem Statement (who + what problem)
-- Target Audience (primary segment)
+If PROJECT.md or HUMAN_FLOW.md is missing OR still has `[fill in]` placeholders in Vision, Problem Statement, or Core Screens — stop and say: "Run `/ship` first — I need a filled spec to build from." Otherwise proceed immediately.
 
-And HUMAN_FLOW.md has real content in:
-- User Journey table
-- At least one Core Screen defined
+## Step 2.5 — Four quick choices (one message, one reply)
 
-If critical sections are still blank, stop and say:
-"Run `/ship` first — I need a complete spec to build from."
+Ask all four in a single message. Wait for one reply, then proceed immediately — no follow-up questions.
 
-If the docs look good, proceed to Step 3.
+**1. Site type**
+- `A` Landing page — public, no login needed to browse
+- `B` Member system — login wall, users must sign in first
 
-## Step 3 — Create the build spec
+**2. Language**
+- `A` Thai (ภาษาไทย)
+- `B` English
 
-Check if `docs/AI_BUILD_SPEC.md` exists.
+**3. Font style**
+- If Thai (choice 2A): `T1` Prompt · `T2` IBM Plex Thai · `T3` Noto Sans Thai · `T4` Anuphan
+- If English (choice 2B): `E1` Modern — Inter / Geist · `E2` Luxury — Playfair Display + DM Sans
 
-If not, create it now by deriving the following from `docs/PROJECT.md` and `docs/HUMAN_FLOW.md`:
+**4. Color theme** — shadcn/ui standard palettes:
+- `1` Zinc (neutral gray — most common default)
+- `2` Slate (cool blue-gray)
+- `3` Blue (blue accent)
+- `4` Green (green accent)
+- `5` Orange (warm orange accent)
+- `6` Rose (pink/red accent)
+- `7` Violet (purple accent)
+
+Defaults if skipped: B · B · T1 (Prompt) for Thai / E1 (Modern) for English · 1 (Zinc).
+
+---
+
+## Step 3 — Create the build spec (no waiting)
+
+Check if `docs/AI_BUILD_SPEC.md` exists. If not, create it now from the docs:
 
 ```markdown
 # AI Build Spec
 
 ## Functional Requirements
-[list the features from MVP Scope in PROJECT.md — one bullet per feature]
+[features from MVP Scope in PROJECT.md — one bullet per feature]
 
 ## Data Model
-[derive the tables/collections from the feature list — fields, types, relations]
+[tables/collections derived from features — fields, types, relations]
 
 ## API Contract
-[list the routes/actions the app needs — method, path, what it does, who can call it]
+[routes/actions needed — method, path, purpose, auth required]
 
 ## Auth
-[derive from HUMAN_FLOW.md Section 5 Key UX Decisions — magic link / OAuth / password]
+[derived from HUMAN_FLOW.md Section 5 Key UX Decisions]
 
-## Out of scope for this build
-[copy from PROJECT.md Section 6 "Out of scope for MVP"]
+## Out of scope
+[from PROJECT.md "Out of scope for MVP"]
 ```
 
-Show the spec to the user and ask: "Does this look right before I start building?"
-Wait for confirmation before continuing.
+Write it and move on — do not wait for user confirmation.
+
+## Step 4 — Apply shadcn/ui theme + font (no waiting)
+
+**Stack: Tailwind CSS v4 + shadcn/ui. Do not write custom HSL tokens manually.**
+
+1. Confirm `shadcn/ui` is initialized in the project. If `components/ui/` doesn't exist, run:
+   ```
+   npx shadcn@latest init
+   ```
+   Select the color palette chosen in Step 2.5 during init (or patch `components.json` + `app/globals.css` to match the chosen palette after the fact).
+
+2. Apply the chosen color theme to `app/globals.css` using shadcn's CSS variable block for that palette. Palettes available: `zinc` · `slate` · `blue` · `green` · `orange` · `rose` · `violet`. Always use white background (`--background: 0 0% 100%`).
+
+3. Apply the chosen font in `app/layout.tsx` and `app/globals.css` via `next/font/google`:
+
+   **Thai fonts** — set `subsets: ["thai", "latin"]` on all:
+   - `T1` Prompt: `weights: ["400","500","600","700"]`
+   - `T2` IBM Plex Thai: `weights: ["400","500","600","700"]`
+   - `T3` Noto Sans Thai: `weights: ["400","500","600","700"]`
+   - `T4` Anuphan: `weights: ["400","500","600","700"]`
+   
+   Assign to `--font-sans`, apply `font-sans` on `<body>`. Thai fonts are single-font stacks — no separate serif needed.
+
+   **English fonts:**
+   - `E1` Modern: Keep Geist if present, otherwise `Inter`. `font-sans` on `<body>`.
+   - `E2` Luxury: `Playfair_Display` → `--font-serif` (headings), `DM_Sans` → `--font-sans` (body). Apply `--font-serif` to `h1`–`h3` in global CSS.
+
+4. Install any needed shadcn components now: `npx shadcn@latest add button card input label` (add more as needed per HUMAN_FLOW.md screens). Do not build custom components for things shadcn already covers.
+
+5. **Fill `docs/DESIGN_SYSTEM.md`** — replace all `[FILL: ...]` placeholders with the actual choices made above (palette name, font, language). Leave the trend section blank for now — it gets filled by the `uiux-frontend` skill in Step 5.
 
-## Step 4 — Design the UI with ui-ux-pro-max
+6. **Fill `docs/DESIGN_SPEC.md` global decisions** — fill site type, language, font, and palette rows.
 
-**Invoke the `ui-ux-pro-max` skill now.** Use it to:
+Do not ask for approval. Proceed immediately.
 
-1. Derive a color palette and font pairing from the business described in `docs/PROJECT.md` — the product type, audience, and tone should drive the style choices.
-2. Present 2-3 theme options to the user. Never pick silently.
-3. Apply the chosen theme to `app/globals.css` (`:root` and `.dark` tokens) and `app/layout.tsx`.
-4. Use the skill's component and layout guidance when building each screen in Step 5 — it knows 67 design styles, 96 palettes, and 57 font pairings, so defer to it for any UI decision.
+## Step 5 — 5-minute MVP: home screen first, data later
 
-Also read `docs/tech-stack/STACK_DECISION_MATRIX.md` for stack decisions (database, auth provider, hosting).
+**Target: user sees a real-looking screen within 5 minutes. Build UI with static placeholder data first. Wire real data after.**
 
-## Step 5 — Build
+**Before building each screen, apply the `.claude/skills/uiux-frontend/SKILL.md` guidelines** — layout pattern, component selection, typography, states, and copy rules. Do not skip this for any screen.
 
-If a specific feature was passed as an argument, build that feature only.
-If no argument was given, build the full MVP from `docs/AI_BUILD_SPEC.md`.
+Apply choices from Step 2.5 to every screen built:
+- **Landing page:** `app/page.tsx` is a public page — hero section, features, CTA. No auth.
+- **Member system:** `app/page.tsx` redirects to `/login`. Build login page + middleware. First visible screen = the main dashboard with placeholder data.
+- **Thai:** All labels, headings, buttons, nav, and placeholder copy in Thai.
+- **English:** All copy in English.
 
-Build in this order:
-1. Database schema (`lib/db/schema.*.ts`)
-2. Server actions or API routes
-3. Pages and components (one screen at a time, following `docs/HUMAN_FLOW.md` Section 3 Core Screens)
-4. Replace mock data with real data layer calls
-5. Replace the generic `app/page.tsx` ("Pick your area") with the real entry point from `docs/HUMAN_FLOW.md`
+Build in this order — **stop after step 1 and show the user, then continue:**
+1. **Home/entry screen** — replace `app/page.tsx` with static placeholder UI. Announce: "MVP home screen done — here's what it looks like. Continuing with data layer…"
+2. **Database schema** (`lib/db/schema.*.ts`)
+3. **Server actions / API routes**
+4. **Remaining pages** — one screen at a time per HUMAN_FLOW.md
+5. **Wire real data** — replace placeholders with real data layer calls
 
-After each screen: summarize what was built and what's next.
+After each screen: one line on what was built, one line on what's next. No long summaries.
 
 ## Rules
 
-- Never invent business logic not in the spec — if something is unclear, ask.
-- If a code change would conflict with `docs/AI_BUILD_SPEC.md`, flag it instead of silently overriding.
-- After finishing, run `/ship status` to confirm nothing is outstanding before declaring done.
+- Never invent business logic not in the spec — if unclear, make a reasonable assumption and note it.
+- If a code change conflicts with `docs/AI_BUILD_SPEC.md`, flag it in one sentence and proceed with the most reasonable interpretation.
+- Speed over perfection — working UI with placeholder data beats perfect code the user can't see yet.
+- **No unnecessary libraries** — before adding any `npm install`, ask: "does Next.js, Tailwind, or shadcn already cover this?" If yes, use what's already there. Allowed additions: `next/font/google` (fonts), `zod` + `react-hook-form` (forms, included with shadcn), `lucide-react` (icons, included with shadcn). Everything else requires explicit justification. Never add: `axios` (use `fetch`), `lodash` (use native JS), `moment`/`dayjs` (use `Intl`), `framer-motion` (use CSS transforms + Tailwind transitions first), `styled-components`/`emotion` (Tailwind is the CSS layer).

package/templates/.claude/skills/uiux-frontend/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: uiux-frontend
+description: UI/UX design guidance for Next.js + Tailwind v4 + shadcn/ui projects. Invoke before building any screen. Fetches current trends, auto-selects the best one for the project, then applies layout, component, and copy guidance.
+---
+
+# UI/UX Frontend Skill
+
+Design guidance for **Next.js + Tailwind CSS v4 + shadcn/ui** projects. Runs in 3 phases: (0) fetch current trends, (1) auto-select + declare, (2) implement.
+
+---
+
+## Phase 0 — Fetch current trends (every invocation, no skipping)
+
+Before designing any screen, do a web search to get the freshest UI/UX trend signal:
+
+```
+search: "UI UX design trends 2025 site:nngroup.com OR site:smashingmagazine.com OR site:awwwards.com OR site:uxdesign.cc"
+```
+
+Scan the results for any trends that have risen or fallen since the base catalog below. Note any new entrant that appears in ≥ 2 sources. This keeps designs current — do not skip this step.
+
+---
+
+## Phase 1 — Auto-select the trend (do not ask the user)
+
+Read `docs/PROJECT.md` for product type, audience, and tone. Cross-reference with the **Trend Catalog** below. Pick **one primary trend** and optionally one supporting micro-trend. Announce the choice in one sentence before writing any code:
+
+> "Using **[Trend Name]** — suits [product type] for [audience reason]."
+
+### Trend Catalog
+
+#### 🎨 Visual & Tactile Aesthetics
+
+**Tactile Maximalism (Squishy UI)**
+Soft 3D shapes, inflated elements, playful depth, bold saturated colors, spring-like hover states.
+- Best for: consumer apps, gaming, creative tools, young (18–30) audience
+- Avoid: finance, healthcare, enterprise admin
+- Tailwind implementation: `rounded-3xl shadow-2xl scale-[1.02] hover:scale-105 transition-transform duration-200`, bold `bg-[color]` fills, thick borders `border-4`
+
+**Intentional Imperfection**
+Hand-drawn strokes, organic shapes, slight rotation/misalignment, textured backgrounds, ink-style illustrations.
+- Best for: creative agencies, cultural brands, portfolios, artisan products
+- Avoid: SaaS dashboards, fintech, legal
+- Tailwind implementation: `rotate-[-1deg]`, `skew-x-1`, SVG hand-drawn border overlays, `bg-[url('/texture.png')] bg-repeat opacity-10`
+
+**Liquid Glass & Glassmorphism**
+Frosted glass panels, translucent cards, blur backdrop, subtle borders on glass surface.
+- Best for: premium apps, fintech, luxury SaaS, iOS-style products
+- Avoid: heavy data tables, accessibility-critical flows (low contrast risk — add `backdrop-blur` + solid text)
+- Tailwind implementation: `bg-white/10 backdrop-blur-md border border-white/20 shadow-lg`, ensure text contrast with `text-white drop-shadow-sm` or `text-gray-900` on light blur
+
+**Retrofuturism**
+Neon accents on dark base, grid/scanline overlays, monospace fonts mixed with modern sans, CRT glow effects.
+- Best for: AI tools, dev products, tech startups, edgy consumer apps
+- Avoid: healthcare, legal, conservative brands
+- Tailwind implementation: `bg-gray-950 text-green-400`, `font-mono`, `shadow-[0_0_20px_rgba(74,222,128,0.5)]`, CSS `::before` scanline overlay
+
+---
+
+#### ⚙️ Function & Experience
+
+**Spatial Design**
+Elements appear to exist in 3D space — parallax layers, perspective transforms, depth through scale + shadow, immersive scrolling.
+- Best for: product showcases, portfolio sites, hero sections, tech launches
+- Avoid: CRUD admin panels, form-heavy apps
+- Tailwind implementation: `perspective-1000` (custom CSS), `translate-z-[40px]` on hover via `transform-gpu`, `shadow-2xl` depth layers, scroll-driven animation with CSS `@keyframes`
+
+**Calm Design & Strategic Minimalism**
+Maximum whitespace, restrained palette (2–3 colors), no decorative elements, typography as the main visual element.
+- Best for: healthcare, productivity, focus tools, wellness, legal SaaS
+- Avoid: marketing pages that need energy, entertainment
+- Tailwind implementation: `max-w-prose mx-auto`, `text-gray-500` for supporting text, `border-b border-gray-100` dividers, avoid shadows — use whitespace for separation
+
+**Command Palettes & Unified Search**
+Global `⌘K` search overlay that routes to any action, page, or record. Reduces nav depth, enables power-user flow.
+- Best for: SaaS dashboards, dev tools, data products with many entities
+- Avoid: simple forms, landing pages, consumer apps with < 10 routes
+- Tailwind implementation: Use `cmdk` library + shadcn `Command` component, `fixed inset-0 bg-black/50 flex items-start justify-center pt-32`, trigger via `useEffect` on `⌘K`
+
+**Bento Grids**
+Asymmetric card grid where different-sized cells showcase features, metrics, or media — like a magazine layout.
+- Best for: dashboards, feature showcases, portfolios, SaaS landing pages
+- Avoid: long-form content, step-by-step flows
+- Tailwind implementation: `grid grid-cols-3 gap-4 auto-rows-[minmax(160px,auto)]`, mix `col-span-2 row-span-2` for hero cells, shadcn `Card` in each cell
+
+---
+
+#### 🤖 Typography & AI
+
+**Expressive Typography**
+Large (100px+) hero type, variable font weights, type as graphic element, kinetic text on scroll, tight tracking on display sizes.
+- Best for: landing pages, marketing sites, portfolios, brand-forward products
+- Avoid: data-dense UIs, forms, admin panels
+- Tailwind implementation: `text-7xl lg:text-9xl font-black tracking-tighter leading-none`, variable fonts via CSS `font-variation-settings`, `mix-blend-multiply` for type overlays
+
+**Seamless AI Infrastructure**
+Streaming text (typewriter), skeleton-to-real transitions, inline AI suggestions, confidence indicators, generative placeholders.
+- Best for: AI SaaS, copilot tools, any product with AI-generated content
+- Avoid: non-tech products, forms where instant response is expected
+- Tailwind implementation: `animate-pulse` for streaming state, word-by-word reveal via JS interval, `border-l-2 border-primary pl-3` for AI response thread, `opacity-50` for low-confidence content
+
+---
+
+### Auto-selection decision matrix
+
+| Project type | Primary trend | Supporting |
+|---|---|---|
+| AI / copilot SaaS | Seamless AI Infrastructure | Command Palettes |
+| B2B dashboard / admin | Calm Design & Strategic Minimalism | Bento Grids |
+| Consumer app (young) | Tactile Maximalism | Expressive Typography |
+| Premium / luxury brand | Liquid Glass | Expressive Typography |
+| Creative agency / portfolio | Intentional Imperfection | Spatial Design |
+| Dev tool / CLI product | Retrofuturism | Command Palettes |
+| Healthcare / wellness | Calm Design & Strategic Minimalism | — |
+| Feature showcase landing page | Bento Grids | Expressive Typography |
+| Tech startup landing | Spatial Design | Expressive Typography |
+| Marketplace / e-commerce | Tactile Maximalism | Bento Grids |
+
+---
+
+## Phase 2 — Implement the screen
+
+After announcing the trend:
+
+1. **Update `docs/DESIGN_SYSTEM.md`** — fill in the `UI Trend` section (trend name, reason, implementation rules, scope) if not already done.
+2. **Update `docs/DESIGN_SPEC.md`** — add a screen entry for the screen being built. Fill all fields before writing code. Mark `Status: in-progress`.
+3. Build the screen.
+4. After screen is done, update the DESIGN_SPEC entry: mark `Status: done`, tick off states (`✓`), fill in notes.
+
+Then apply all sections below.
+
+---
+
+## A. Think user-first before touching code
+
+Answer these before laying out any screen:
+- Who is the user and what state are they in when they arrive?
+- What is the ONE thing they must accomplish on this screen?
+- Where do they come from, and where do they go next?
+- What does "success" look like for them (not the business)?
+
+If you can't answer these from `docs/HUMAN_FLOW.md` → reread it, don't guess.
+
+---
+
+## B. Layout patterns by screen type
+
+### Landing page (public)
+```
+Hero → Value props (3 columns) → Social proof → CTA section → Footer
+```
+- Hero: full-width, headline + subheadline + primary button. Apply trend here most visibly.
+- Value props: shadcn `Card` or Bento grid cells
+- CTA: high-contrast button
+- Mobile: single column, buttons full width
+
+### Dashboard (member system)
+```
+Sidebar nav (md+) | Top bar | Main content area
+```
+- Sidebar: 240px, `bg-sidebar` token, active state via `aria-current="page"`
+- Top bar: breadcrumb left, avatar/action right + optional `⌘K` trigger
+- Content: `max-w-screen-xl px-6 py-8`. Bento grid for KPI cards, shadcn `Table` for lists
+
+### Login / auth screen
+```
+Centered card (max-w-sm) — logo → heading → form → submit → helper link
+```
+- shadcn `Card` + `CardContent`. Apply trend subtly (background, not form itself).
+- Form: `Label` + `Input` stacked, `Button` full-width
+
+### Form / settings screen
+```
+Page heading → section groups → save action at bottom
+```
+- Group fields with section cards. Inline errors via shadcn `FormMessage`.
+- Save button: primary, right-aligned
+
+### List / table screen
+```
+Toolbar (search + filter + action) → Table or card grid → Pagination
+```
+- shadcn `Table` for structured data, card grid for visual items
+- Empty state: centered icon + message + CTA
+- Loading: shadcn `Skeleton` rows
+
+---
+
+## C. Typography rules
+
+### Thai fonts (Prompt / IBM Plex Thai / Noto Sans Thai / Anuphan)
+Single-font stack, `font-sans` everywhere.
+
+| Element | Class |
+|---------|-------|
+| Page title h1 | `text-3xl font-bold` |
+| Section heading h2 | `text-xl font-semibold` |
+| Body | `text-base font-normal leading-relaxed` |
+| Caption | `text-sm text-muted-foreground` |
+| Button | `text-sm font-medium` |
+
+> Thai script needs `leading-relaxed` or higher. Never go below `text-base` on mobile.
+
+### English — Modern (Inter / Geist)
+| Element | Class |
+|---------|-------|
+| Page title h1 | `text-3xl font-bold tracking-tight` |
+| Section heading h2 | `text-xl font-semibold` |
+| Body | `text-base font-normal leading-relaxed` |
+| Caption | `text-sm text-muted-foreground` |
+| Button | `text-sm font-medium` |
+
+### English — Luxury (Playfair Display + DM Sans)
+| Element | Class |
+|---------|-------|
+| Page title h1 | `font-serif text-3xl font-bold tracking-wide` |
+| Section heading h2 | `font-serif text-xl font-semibold tracking-wide` |
+| Body | `text-base font-normal leading-relaxed` |
+| Caption | `text-sm text-muted-foreground` |
+| Button | `text-sm font-medium tracking-wide uppercase` |
+
+For **Expressive Typography** trend: override h1 to `text-7xl lg:text-9xl font-black tracking-tighter leading-none` on hero sections only.
+
+---
+
+## D. Spacing & sizing
+
+- Page padding: `px-4 sm:px-6 lg:px-8`
+- Section gap: `space-y-8` or `gap-8`
+- Card padding: `p-6`
+- Form fields: `space-y-4`
+- Min touch target: `h-11` (44px)
+- Min body text: `text-base` on mobile
+
+---
+
+## E. shadcn/ui component map
+
+| Need | Component |
+|------|-----------|
+| Navigation | `NavigationMenu` or `<nav>` + Link |
+| Data entry | `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup` |
+| Form | `Form` (react-hook-form + zod) |
+| Actions | `Button` (default / outline / ghost / destructive) |
+| Feedback | `Toast`, `Alert` |
+| Modals | `Dialog`, `AlertDialog` |
+| Data display | `Table`, `Card`, `Badge` |
+| Loading | `Skeleton` |
+| Sidebar (mobile) | `Sheet` |
+| Global search | `Command` (cmdk) |
+| Dropdowns | `DropdownMenu` |
+
+Do not build custom versions of anything shadcn covers.
+
+**Library rule — always check before installing:**
+
+| Need | Use this — NOT a new library |
+|------|------------------------------|
+| HTTP requests | Native `fetch` |
+| Date formatting | `Intl.DateTimeFormat` |
+| Array/object utilities | Native JS (`.map`, `.filter`, `.reduce`) |
+| Icons | `lucide-react` (already in shadcn) |
+| Animation | CSS `transition` + Tailwind classes first; CSS `@keyframes` for complex |
+| Forms + validation | `react-hook-form` + `zod` (already in shadcn `Form`) |
+| Global search / cmd palette | shadcn `Command` (uses cmdk internally — do not install cmdk separately) |
+| Fonts | `next/font/google` |
+
+Only install a new library if no existing solution covers the need. Mention it explicitly when you do.
+
+---
+
+## F. UI copy rules
+
+### Thai
+- ปุ่ม: กริยาสั้น — "บันทึก", "เข้าสู่ระบบ", "ดูเพิ่มเติม"
+- หัวข้อ: ≤ 10 คำ
+- Placeholder: ตัวอย่างจริง — "กรอกชื่อ-นามสกุล" ไม่ใช่ "กรอกข้อมูล"
+- Error: บอกปัญหาและวิธีแก้ — "กรุณากรอกอีเมลให้ถูกต้อง"
+- Empty: สั่งทำได้ทันที — "ยังไม่มีรายการ — กด 'เพิ่มรายการ' เพื่อเริ่มต้น"
+
+### English
+- Buttons: verb-first — "Save changes", "Sign in", "View all"
+- Headings: ≤ 8 words, sentence case
+- Placeholders: real example — "Enter your full name"
+- Error: what + fix — "Email already in use. Try signing in instead."
+- Empty: actionable — "No items yet — click 'Add item' to get started"
+
+---
+
+## G. States (all 4 required on every screen)
+
+| State | Implementation |
+|-------|----------------|
+| Loading | `Skeleton` matching real content shape |
+| Empty | Centered icon + message + primary CTA |
+| Error | `Alert` destructive + retry action |
+| Success | `Toast` or inline confirmation |
+
+---
+
+## H. Accessibility minimum
+
+- Keyboard-navigable (`Tab` order = visual order)
+- Icon-only buttons have `aria-label`
+- Every input has a visible `<Label>`
+- Color contrast ≥ 4.5:1 (shadcn defaults pass; glassmorphism — verify manually)
+- Images have `alt` (or `alt=""` if decorative)
+
+---
+
+## I. Revenue link check (before closing any screen)
+
+| Screen | Revenue connection |
+|--------|--------------------|
+| Landing page | Conversion — CTA → sign-up / purchase |
+| Login / sign-up | Activation — user reaches product |
+| Dashboard | Retention — user sees value, returns |
+| Settings / billing | Revenue — upgrade path, churn prevention |
+| Empty state | Activation — first action drives retention |
+
+If a screen has no revenue link, flag it before spending time on it.

package/templates/.cursorrules

@@ -51,11 +51,11 @@ All docs live under `docs/`:
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes). Draft clearly-labeled `[TBD: ...]` placeholders or ask the user.
 
-7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.**
+7. **Once the spec is complete, apply white theme and replace the home screen — do this first, before any features.**
    When `docs/PROJECT.md` and `docs/HUMAN_FLOW.md` are filled and `docs/AI_BUILD_SPEC.md` exists:
-   - **Theme:** Invoke the `ui-ux-pro-max` skill. Using the business context from `docs/PROJECT.md`, derive 2-3 theme candidates (HSL color tokens + font pairing). Present them, let the user pick one, apply it to `app/globals.css` and `app/layout.tsx`. See `.claude/skills/ship-method/theme-guide.md` for a fallback business-type → palette reference.
-   - **Home:** Read `docs/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` with it.
-   - Never pick a theme silently. Never require brand assets the user didn't provide.
+   - **Home first:** Replace the starter kit's generic `app/page.tsx` immediately with the real entry point from `docs/HUMAN_FLOW.md`. This is always the first build output so the user sees something real right away.
+   - **Theme (shadcn/ui):** Use Tailwind CSS v4 + shadcn/ui. Apply the user's chosen shadcn color palette (zinc/slate/blue/green/orange/rose/violet) via its CSS variable block in `app/globals.css`. Always white background. Font: modern (Inter/Geist) or luxury (Playfair Display + DM Sans). Do not write custom HSL tokens manually.
+   - See `.claude/skills/ship-method/theme-guide.md` for product-type → palette reference.
 
 ## Quick Orientation for a New Agent Session
 

package/templates/.windsurfrules

@@ -51,11 +51,11 @@ All docs live under `docs/`:
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes). Draft clearly-labeled `[TBD: ...]` placeholders or ask the user.
 
-7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.**
+7. **Once the spec is complete, apply white theme and replace the home screen — do this first, before any features.**
    When `docs/PROJECT.md` and `docs/HUMAN_FLOW.md` are filled and `docs/AI_BUILD_SPEC.md` exists:
-   - **Theme:** Invoke the `ui-ux-pro-max` skill. Using the business context from `docs/PROJECT.md`, derive 2-3 theme candidates (HSL color tokens + font pairing). Present them, let the user pick one, apply it to `app/globals.css` and `app/layout.tsx`. See `.claude/skills/ship-method/theme-guide.md` for a fallback business-type → palette reference.
-   - **Home:** Read `docs/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` with it.
-   - Never pick a theme silently. Never require brand assets the user didn't provide.
+   - **Home first:** Replace the starter kit's generic `app/page.tsx` immediately with the real entry point from `docs/HUMAN_FLOW.md`. This is always the first build output so the user sees something real right away.
+   - **Theme (shadcn/ui):** Use Tailwind CSS v4 + shadcn/ui. Apply the user's chosen shadcn color palette (zinc/slate/blue/green/orange/rose/violet) via its CSS variable block in `app/globals.css`. Always white background. Font: modern (Inter/Geist) or luxury (Playfair Display + DM Sans). Do not write custom HSL tokens manually.
+   - See `.claude/skills/ship-method/theme-guide.md` for product-type → palette reference.
 
 ## Quick Orientation for a New Agent Session
 

package/templates/AGENTS.md

@@ -51,11 +51,11 @@ All docs live under `docs/`:
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes). Draft clearly-labeled `[TBD: ...]` placeholders or ask the user.
 
-7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.**
+7. **Once the spec is complete, apply white theme and replace the home screen — do this first, before any features.**
    When `docs/PROJECT.md` and `docs/HUMAN_FLOW.md` are filled and `docs/AI_BUILD_SPEC.md` exists:
-   - **Theme:** Invoke the `ui-ux-pro-max` skill. Using the business context from `docs/PROJECT.md`, derive 2-3 theme candidates (HSL color tokens + font pairing). Present them, let the user pick one, apply it to `app/globals.css` and `app/layout.tsx`. See `.claude/skills/ship-method/theme-guide.md` for a fallback business-type → palette reference.
-   - **Home:** Read `docs/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` with it.
-   - Never pick a theme silently. Never require brand assets the user didn't provide.
+   - **Home first:** Replace the starter kit's generic `app/page.tsx` immediately with the real entry point from `docs/HUMAN_FLOW.md`. This is always the first build output so the user sees something real right away.
+   - **Theme (shadcn/ui):** Use Tailwind CSS v4 + shadcn/ui. Apply the user's chosen shadcn color palette (zinc/slate/blue/green/orange/rose/violet) via its CSS variable block in `app/globals.css`. Always white background. Font: modern (Inter/Geist) or luxury (Playfair Display + DM Sans). Do not write custom HSL tokens manually.
+   - See `.claude/skills/ship-method/theme-guide.md` for product-type → palette reference.
 
 ## Quick Orientation for a New Agent Session
 

package/templates/CLAUDE.md

@@ -51,11 +51,11 @@ All docs live under `docs/`:
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes). Draft clearly-labeled `[TBD: ...]` placeholders or ask the user.
 
-7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.**
+7. **Once the spec is complete, apply white theme and replace the home screen — do this first, before any features.**
    When `docs/PROJECT.md` and `docs/HUMAN_FLOW.md` are filled and `docs/AI_BUILD_SPEC.md` exists:
-   - **Theme:** Invoke the `ui-ux-pro-max` skill. Using the business context from `docs/PROJECT.md`, derive 2-3 theme candidates (HSL color tokens + font pairing). Present them, let the user pick one, apply it to `app/globals.css` and `app/layout.tsx`. See `.claude/skills/ship-method/theme-guide.md` for a fallback business-type → palette reference.
-   - **Home:** Read `docs/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` with it.
-   - Never pick a theme silently. Never require brand assets the user didn't provide.
+   - **Home first:** Replace the starter kit's generic `app/page.tsx` immediately with the real entry point from `docs/HUMAN_FLOW.md`. This is always the first build output so the user sees something real right away.
+   - **Theme (shadcn/ui):** Use Tailwind CSS v4 + shadcn/ui. Apply the user's chosen shadcn color palette (zinc/slate/blue/green/orange/rose/violet) via its CSS variable block in `app/globals.css`. Always white background. Font: modern (Inter/Geist) or luxury (Playfair Display + DM Sans). Do not write custom HSL tokens manually.
+   - See `.claude/skills/ship-method/theme-guide.md` for product-type → palette reference.
 
 ## Quick Orientation for a New Agent Session
 

package/templates/docs/DESIGN_SPEC.md

@@ -0,0 +1,50 @@
+# Design Spec
+
+> Screen-by-screen design decisions. Auto-populated by the `uiux-frontend` skill during `/build`. Each section is filled when that screen is built — do not write speculative specs for unbuilt screens.
+
+---
+
+## Global decisions
+
+| Decision | Value |
+|----------|-------|
+| Site type | `[FILL: Landing page / Member system]` |
+| Language | `[FILL: Thai / English]` |
+| Font | `[FILL]` |
+| Color palette | `[FILL: shadcn palette name]` |
+| UI trend | `[FILL]` |
+| Trend source | `[FILL: URL or publication that confirmed this trend is current]` |
+
+---
+
+## Screen specs
+
+Each screen gets one entry. Format:
+
+```
+### [Screen name] — [route e.g. /dashboard]
+Status: [planned / in-progress / done]
+Layout: [pattern used]
+Trend application: [how the trend is expressed here]
+Key components: [shadcn components used]
+States: [loading ✓/✗ | empty ✓/✗ | error ✓/✗ | success ✓/✗]
+Revenue link: [how this screen connects to money]
+Notes: [any deviations from the design system, or decisions to revisit]
+```
+
+---
+
+<!-- SCREENS BELOW — filled by uiux-frontend skill during /build -->
+
+### Home / Entry screen — /
+Status: planned
+Layout:
+Trend application:
+Key components:
+States: loading ✗ | empty ✗ | error ✗ | success ✗
+Revenue link:
+Notes:
+
+---
+
+<!-- Add a new entry below for each screen as it gets built -->

package/templates/docs/DESIGN_SYSTEM.md

@@ -0,0 +1,145 @@
+# Design System
+
+> Auto-generated by `/build`. Update here when design decisions change — this is the source of truth for all visual decisions in this project.
+
+---
+
+## Stack
+
+| Layer | Choice |
+|-------|--------|
+| CSS framework | Tailwind CSS v4 |
+| Component library | shadcn/ui |
+| Font loading | `next/font/google` |
+
+---
+
+## Color Palette
+
+**Base theme:** `[FILL: zinc / slate / blue / green / orange / rose / violet]`
+
+All color tokens are from shadcn's CSS variable system. Do not hardcode hex or rgb values anywhere — use only these tokens:
+
+| Token | Usage |
+|-------|-------|
+| `bg-background` | Page background (always white in light mode) |
+| `text-foreground` | Primary text |
+| `text-muted-foreground` | Secondary text, captions, placeholders |
+| `bg-primary` | Primary action background |
+| `text-primary-foreground` | Text on primary background |
+| `bg-secondary` | Secondary/subtle backgrounds |
+| `border` | Dividers, card borders |
+| `bg-destructive` | Error states, delete actions |
+| `bg-accent` | Hover/active backgrounds |
+| `bg-card` | Card surfaces |
+| `bg-sidebar` | Sidebar background |
+
+**Dark mode:** not scoped for MVP — defer until user requests it.
+
+---
+
+## Typography
+
+**Language:** `[FILL: Thai / English]`
+
+**Font:** `[FILL: Prompt / IBM Plex Thai / Noto Sans Thai / Anuphan / Inter / Geist / Playfair Display + DM Sans]`
+
+**Font stack type:** `[FILL: Single-stack (Thai) / Sans-only (Modern) / Serif + Sans (Luxury)]`
+
+| Role | Tailwind classes | Notes |
+|------|-----------------|-------|
+| Display / Hero h1 | `[FILL]` | Used in hero sections only |
+| Page title h1 | `text-3xl font-bold` (Thai) / `text-3xl font-bold tracking-tight` (EN) | |
+| Section heading h2 | `text-xl font-semibold` | |
+| Card heading h3 | `text-base font-semibold` | |
+| Body | `text-base font-normal leading-relaxed` | Thai: `leading-loose` for denser text |
+| Caption / helper | `text-sm text-muted-foreground` | |
+| Label | `text-sm font-medium` | Form labels |
+| Button | `text-sm font-medium` | |
+
+---
+
+## Spacing Scale
+
+Using Tailwind's default spacing scale. These are the project's agreed units — don't introduce other values:
+
+| Use | Class | px |
+|-----|-------|----|
+| Page horizontal padding | `px-4 sm:px-6 lg:px-8` | 16 / 24 / 32 |
+| Section vertical gap | `space-y-8` / `gap-8` | 32 |
+| Card padding | `p-6` | 24 |
+| Form field gap | `space-y-4` | 16 |
+| Inline item gap | `gap-2` / `gap-3` | 8 / 12 |
+| Min touch target | `h-11` | 44 |
+
+---
+
+## Border Radius
+
+| Token | Class | Usage |
+|-------|-------|-------|
+| Default | `rounded-md` | Buttons, inputs, badges |
+| Card | `rounded-lg` | Cards, modals, sheets |
+| Full | `rounded-full` | Avatars, tags, pills |
+
+---
+
+## Shadow
+
+| Class | Usage |
+|-------|-------|
+| `shadow-sm` | Cards, inputs on focus |
+| `shadow-md` | Dropdowns, popovers |
+| `shadow-lg` | Modals, dialogs |
+| `shadow-none` | Flat/minimal screens |
+
+---
+
+## UI Trend
+
+**Selected trend:** `[FILL: trend name]`
+**Reason:** `[FILL: why this trend fits this product + audience]`
+
+**Trend implementation rules for this project:**
+`[FILL: specific Tailwind classes and patterns used to express the trend — filled by /build Step 4]`
+
+**Trend scope:** Applied to `[FILL: hero section / cards / overall layout / specific screens]`. Not applied to: forms, error states, data tables (keep those neutral for usability).
+
+---
+
+## Component Decisions
+
+| Need | Component | Notes |
+|------|-----------|-------|
+| Navigation | `[FILL]` | |
+| Data entry | `[FILL]` | |
+| Data display | `[FILL]` | |
+| Modals | `[FILL]` | |
+| Feedback | `[FILL]` | |
+| Global search | `[FILL: Command / none]` | |
+
+---
+
+## Icons
+
+Use `lucide-react` (already bundled with shadcn). Do not mix icon libraries.
+
+---
+
+## Animation
+
+Keep animations subtle and intentional:
+- Micro-interactions: `transition-all duration-150`
+- Modal/sheet open: shadcn built-in (Radix transitions)
+- Trend-specific animation: `[FILL: if any — e.g. spring scale for Squishy UI]`
+- Disable if `prefers-reduced-motion`: wrap custom animations in `@media (prefers-reduced-motion: no-preference)`
+
+---
+
+## Accessibility Baseline
+
+- Contrast: ≥ 4.5:1 for body text, ≥ 3:1 for large text/UI components
+- Focus ring: Tailwind `ring-2 ring-primary ring-offset-2` (shadcn default)
+- Every form input paired with `<Label htmlFor="...">`
+- Icon-only buttons: `aria-label` required
+- Color not used as the only differentiator (always pair color with shape/text)