@kennethsolomon/shipkit 3.13.2 → 3.15.1

package/skills/sk:website/SKILL.md

@@ -0,0 +1,471 @@
+---
+name: sk:website
+description: Build a complete, client-deliverable multi-page marketing website from a brief, URL, or one sentence. NOT a prototype — a real site you hand to a client. Auto-builds from intake to handoff package. Use --revise for change iterations after initial build.
+---
+
+# /sk:website — Client Website Builder
+
+Turn a brief, URL, or one sentence into a production-ready multi-page marketing website with real copy, real SEO, and a full client handoff package. Runs autonomously from intake to delivery.
+
+## This is NOT sk:mvp
+
+| | sk:website | sk:mvp |
+|---|---|---|
+| **Purpose** | Client deliverable | Market validation |
+| **Copy** | Real, business-specific | Placeholder/generic |
+| **Data** | Real structure | Fake data |
+| **Deploy** | Production-ready | Local prototype |
+| **Handoff** | Full client package | Docs only |
+
+## Hard Rules
+
+- **Real copy always** — never Lorem ipsum, never `[Your Headline Here]`. Extract real facts and write specific copy.
+- **Multi-page by default** — Home, About, Services/Menu, Contact + niche-specific extras.
+- **Default stack: Next.js + Tailwind** — always respect existing project stack.
+- **WhatsApp is default contact for local businesses in PH/SEA** — auto-detect and inject.
+- **Lighthouse 90+ required before handoff** — loop and fix until passing.
+- **Never invent business facts** — no fake testimonials, invented certifications, or made-up outcomes.
+- **Parallel agents for speed** — strategy + copy + art direction run simultaneously.
+- **Revision mode is targeted** — never rebuild the whole site for small changes.
+
+---
+
+## Mode Detection
+
+| Invocation | Mode |
+|---|---|
+| `/sk:website` | Full build mode (Steps 1–7) |
+| `/sk:website --revise` | Revision mode (Steps R1–R6) |
+| `/sk:website --stack nuxt` | Full build mode using Nuxt 3 + Vue 3 |
+| `/sk:website --stack laravel` | Full build mode using Laravel 11 + Blade |
+| `/sk:website --deploy` | Full build mode + Step 8 (deploy to Vercel/Netlify after build) |
+| Flags combine freely | e.g., `--stack nuxt --deploy`, `--stack laravel --revise` |
+
+---
+
+## Stack Detection
+
+Determines which stack reference file to load in Step 3.
+
+| Priority | Signal | Stack |
+|---|---|---|
+| 1 | `--stack nuxt` flag | Nuxt 3 + Vue 3 + Tailwind → `references/stacks/nuxt.md` |
+| 2 | `--stack laravel` flag | Laravel 11 + Blade + Tailwind → `references/stacks/laravel.md` |
+| 3 | `package.json` contains `"nuxt"` | Nuxt 3 (existing project) |
+| 4 | `composer.json` exists | Laravel (existing project) |
+| 5 | `package.json` contains `"next"` | Next.js (existing project) |
+| 6 | No signals | Default: Next.js App Router → `references/stacks/nextjs.md` |
+
+Read the matched stack reference at the start of Step 3 before writing any code.
+
+---
+
+## Full Build Mode
+
+### Step 1 — Brief Extraction
+
+Accept any input. Never block on a missing detail — infer and proceed.
+
+**Option A: URL input**
+
+Use WebFetch to extract facts from any URL the user provides:
+- **Google Maps URL** → business name, category, address, phone, hours, rating count, description
+- **Existing website URL** → name, tagline, services list, contact details, current copy, page structure
+- **Facebook/Instagram business page** → name, description, contact, category
+
+If WebFetch fails (JS-only page, redirect, paywall): fall back to Option B immediately. Don't retry.
+
+**Option B: Plain text / one sentence**
+
+Extract: business name, type, location, services, CTA intent. Infer reasonable defaults for anything missing.
+
+**After extraction**, display a compact confirmation and auto-proceed:
+
+```
+[Business Name] — [Type], [Location]
+Services: [list]
+CTA: [primary action]
+Pages: [inferred page set]
+Style: [inferred from type + location]
+Stack: [detected stack — Next.js / Nuxt 3 / Laravel]
+
+Building...
+```
+
+Do NOT wait for approval — auto-advance unless extracted facts are clearly ambiguous or contradictory.
+
+---
+
+### Step 2 — Parallel Research
+
+Launch 3 agents simultaneously using the Agent tool (all in a single message, `subagent_type="general-purpose"`):
+
+**Agent 1 — Strategy Agent**
+- Detect niche from business type using the niche detection table at the bottom of this file.
+- Read `references/niche/[detected-niche].md`.
+- Plan: final page set, sitemap, per-page section structure, CTA flow across all pages, shared nav/footer structure.
+- Output a structured plan with all pages + section outlines.
+
+**Agent 2 — Copy Agent**
+- Read `references/content-seo.md`.
+- Read `references/niche/[detected-niche].md` for industry-specific messaging rules.
+- Write real copy using ONLY facts from Step 1. Never invent:
+  - Hero headline + subheadline (specific to this business)
+  - About section copy
+  - Services/offerings copy (use real service names from the brief)
+  - CTA copy aligned with the primary action
+  - Footer tagline
+  - Page title tag + meta description for every page
+  - H1 for every page
+- Output all copy ready to inject directly into the build.
+
+**Agent 3 — Art Direction Agent**
+- Read `references/art-direction.md`.
+- Based on business type + location + tone keywords in the brief, determine:
+  - Dominant aesthetic direction (one of 7 — see reference)
+  - 2–4 signature design moves
+  - Typography pairing (display + body, not system fonts)
+  - Custom color palette (NOT default Tailwind palette colors)
+  - Motion stance
+- Output a complete design spec for the build step.
+
+Each agent writes its output to a temp doc before returning:
+- Agent 1 → structured sitemap + per-page section outline (markdown)
+- Agent 2 → all copy, organized by page and section (markdown)
+- Agent 3 → aesthetic direction, signature moves, typography, palette hex codes, motion stance (markdown)
+
+Collect all 3 agent outputs before proceeding to Step 3.
+
+---
+
+### Step 3 — Build
+
+Implement the full site using all 3 agent outputs as inputs.
+
+**3a. Project setup**
+- Run stack detection (see Stack Detection table above). Read the matched `references/stacks/[stack].md` file before writing any code.
+- Detect existing framework. If present, work within it and preserve conventions.
+- If no framework: scaffold using the detected stack reference (Next.js by default, or Nuxt/Laravel if flagged).
+- Apply the custom color palette from the art direction spec to `tailwind.config.js` / `tailwind.config.ts`.
+- Configure typography (Google Fonts — see stack reference for the correct import method per stack).
+
+**3b. Site configuration**
+- Create a typed site config file (`content/site.ts` or equivalent) with all pages, copy, and metadata from the research agents.
+- Organize for easy future editing — named fields, not magic strings.
+
+**3c. Page generation**
+For each page in the sitemap:
+1. Implement with semantic HTML (landmarks, heading hierarchy, descriptive links).
+2. Inject real copy from the Copy Agent — no placeholders anywhere.
+3. Apply visual system from Art Direction Agent (typography, palette, design moves).
+4. Add per-page SEO: unique title tag, meta description, canonical, OG/Twitter tags.
+5. Add structured data where appropriate (LocalBusiness, Organization, BreadcrumbList).
+6. Ensure responsiveness: mobile, tablet, desktop.
+
+**3d. WhatsApp CTA injection**
+Read `references/whatsapp-cta.md`.
+
+Auto-detect SEA local business using the detection table at the bottom of this file.
+
+Conditions for injection (ANY of these):
+- Location explicitly in PH/SEA signals table AND business is local type
+- Business is local type AND location is unknown (default to inject with placeholder)
+- User explicitly mentioned WhatsApp in the brief
+
+Implementation — use the stack-appropriate pattern:
+
+| Stack | Component pattern |
+|---|---|
+| Next.js | `components/WhatsAppButton.tsx` (React TSX `'use client'` component) — see `references/stacks/nextjs.md` |
+| Nuxt 3 | `components/WhatsAppButton.vue` (Vue SFC with `defineProps`) — see `references/stacks/nuxt.md` |
+| Laravel | `resources/views/components/whatsapp-button.blade.php` (Blade partial with `@props`) — see `references/stacks/laravel.md` |
+
+- Wire to extracted phone number (E.164 without `+`: e.g., `639171234567`), or use `[PHONE]` placeholder with a clear note for the client
+- Position: fixed bottom-right floating button
+
+If Messenger is preferred (user mentioned it, or location is Philippines): implement Messenger alternative from reference.
+
+**3e. Contact handling**
+
+Choose based on business type:
+- **Local hospitality** (cafe, restaurant): WhatsApp button + simple reservation/inquiry form
+- **Service business**: inquiry form with honeypot protection + WhatsApp fallback
+- **Professional services**: consultation booking form
+- **SaaS/product**: contact form + optional demo CTA
+- **Portfolio**: minimal contact form or email link
+
+**3f. Sitemap + robots**
+Generate `sitemap.xml` and `robots.txt` where the framework supports it (Next.js: `app/sitemap.ts`, `app/robots.ts`).
+
+---
+
+### Step 4 — Lighthouse Enforcement Loop
+
+**If Playwright MCP is available:**
+1. Start the dev server.
+2. Run Lighthouse on each page.
+3. Target: Performance ≥ 90, Accessibility ≥ 90, SEO ≥ 90, Best Practices ≥ 90.
+4. For any page failing:
+   - Read the specific failing audit items.
+   - Fix: image sizing, missing meta tags, contrast, heading order, font loading, etc.
+   - Re-run Lighthouse on that page only.
+5. Repeat until all pages pass all 4 categories.
+6. Maximum 3 fix iterations per page. If still failing after 3: flag specific issues to the user and proceed.
+
+**If Playwright MCP is NOT available:**
+Run a static quality pass instead:
+- Every page has a unique title and meta description ✓
+- No duplicate H1s, no skipped heading levels ✓
+- All images have descriptive alt text ✓
+- Color contrast is not obviously broken (verify palette choices) ✓
+- Sitemap + robots.txt are generated ✓
+- `next build` (or equivalent) passes without errors ✓
+
+Report: `Quality: [N] issues fixed. Build passing.`
+
+---
+
+### Step 5 — Launch Audit
+
+Read `references/launch-checklist.md`.
+
+Run through all 5 audit categories:
+1. Search and metadata
+2. Conversion and content
+3. Accessibility and UX
+4. Performance and implementation
+5. Launch operations
+
+Fix all blockers immediately. Log medium-priority and optional polish items for the handoff document.
+
+---
+
+### Step 6 — Handoff Package
+
+Read `references/handoff-template.md`.
+
+Generate 3 files at the project root using the templates:
+
+**`HANDOFF.md`** — Client-facing project summary:
+- What was built (pages, features, integrations)
+- What needs replacing (image placeholders, phone numbers, API keys)
+- How to make simple content edits with specific file paths
+- Contact for technical help
+
+**`DEPLOY.md`** — Deployment guide:
+- Vercel one-click deploy + CLI steps
+- Netlify as alternative
+- Required environment variables with descriptions
+- Domain configuration steps
+- Estimated monthly cost (Vercel free tier, domain ~$12/yr)
+
+**`CONTENT-GUIDE.md`** — Non-technical editing guide (written FOR the client):
+- Plain language: "To change your opening hours, open `content/site.ts` and find `hours:`"
+- Covers: business name, tagline, contact details, services list, hours, social links
+- No developer jargon
+
+---
+
+### Step 7 — Final Output
+
+```
+## [Business Name] — Website Complete
+
+**Stack:** [framework] + Tailwind CSS
+**Pages:** [list all pages]
+**Style:** [aesthetic direction] — [2-4 signature moves]
+**WhatsApp CTA:** [included — wa.me/[PHONE_NUMBER] / not applicable]
+**Quality:** [Lighthouse 90+ on all pages / static checks passed]
+
+### Run locally
+[exact command]
+
+### Client deliverables
+- `HANDOFF.md` — what was built + what to replace
+- `DEPLOY.md` — how to go live on Vercel (free tier)
+- `CONTENT-GUIDE.md` — how to update content without a developer
+
+### Still needs
+- [ ] [specific placeholders — e.g., hero photo, WhatsApp number, GA4 ID]
+```
+
+---
+
+### Step 8 — Deploy (only when `--deploy` flag is provided)
+
+**Skip this step entirely if `--deploy` was NOT passed.** DEPLOY.md covers manual deploy for all cases.
+
+**8a. Detect deploy tool**
+
+Check for Vercel CLI first, then Netlify CLI as fallback:
+
+```
+vercel --version  → if found: use Vercel
+netlify --version → if found: use Netlify
+neither found     → skip deploy, instruct user (see 8c)
+```
+
+**8b. Confirm before deploying**
+
+ALWAYS ask before running any deploy command — this is a visible external action:
+
+```
+Ready to deploy to [Vercel/Netlify]? (y/n)
+
+This will push the site live. Make sure:
+- HANDOFF.md placeholders are replaced (or noted)
+- Environment variables are configured
+- The client has approved the build
+```
+
+Wait for explicit `y`. Never auto-deploy without user confirmation.
+
+**8c. If no CLI found**
+
+```
+Vercel CLI not found. To deploy manually:
+1. Run: npm install -g vercel
+2. Run: vercel --prod
+   (or follow DEPLOY.md for Netlify or other hosts)
+
+DEPLOY.md has been generated with full step-by-step instructions.
+```
+
+**8d. Deploy**
+
+For Vercel:
+```bash
+vercel --prod
+```
+
+For Netlify:
+```bash
+netlify deploy --prod
+```
+
+For Laravel (no Vercel/Netlify support): output the recommended hosts and point to DEPLOY.md.
+
+**8e. After successful deploy**
+
+1. Display the live URL.
+2. Update `HANDOFF.md`: append a "Live URL" section with the URL and deploy date.
+3. Update `DEPLOY.md`: mark step as "Deployed" with the live URL.
+
+```
+## [Business Name] — Deployed
+
+Live URL: https://[project].vercel.app
+Deployed: [date]
+
+Update HANDOFF.md with the final custom domain once DNS is configured.
+```
+
+---
+
+## Revision Mode (`--revise`)
+
+Use after the initial build when the client has feedback.
+
+### Step R1 — Read current state
+- Read existing site files.
+- Read `HANDOFF.md` if it exists for context on what was built.
+
+### Step R2 — Collect changes
+
+If not already provided in the invocation, ask:
+> **What changes does the client want?**
+> Plain language — e.g., "make the hero warmer", "add a gallery section", "update the CTA to Book a Table", "the mobile nav is broken"
+
+### Step R3 — Classify and apply
+
+For each change, identify type and act:
+
+| Type | Examples | Action |
+|---|---|---|
+| Copy change | Updated headline, new CTA text, service names | Direct edit to config/content file |
+| Style change | Warmer colors, bigger fonts, more spacing | Targeted Tailwind/CSS edit only |
+| Structure change | New section, new page, reordering sections | Implement using existing component patterns |
+| Feature change | Gallery, new contact form, WhatsApp, map | Implement + update handoff docs |
+
+**Rule: never rebuild the whole site for targeted feedback.** Edit only what changed.
+
+### Step R4 — Quality re-check
+Run the same Lighthouse/quality checks from Step 4. Fix any regressions introduced by the changes.
+
+### Step R5 — Update handoff docs
+If the structure changed (new page, new section), update `HANDOFF.md` and `CONTENT-GUIDE.md` with new file references and editing instructions.
+
+### Step R6 — Summarize
+```
+## Revision Applied
+
+**Changes made:**
+- [each change with file:line reference]
+
+**Quality:** [passed / N issues fixed]
+**Handoff docs:** [updated / unchanged]
+```
+
+---
+
+## Niche Detection
+
+Auto-detect from brief text. Read the matched reference file in Step 2.
+
+| Business type signals | Reference file |
+|---|---|
+| cafe, coffee, espresso, bakery, brunch, brew, roaster, barista | `references/niche/cafe.md` |
+| restaurant, dining, bistro, brasserie, eatery, food, cuisine | `references/niche/restaurant.md` |
+| law, attorney, legal, litigation, counsel, solicitor | `references/niche/law-firm.md` |
+| plumber, HVAC, roofing, cleaning, landscaping, handyman, pest control | `references/niche/home-services.md` |
+| dentist, dental, orthodont, oral, clinic (dental context) | `references/niche/dentist.md` |
+| gym, fitness, yoga, pilates, trainer, crossfit, workout | `references/niche/gym.md` |
+| real estate, property, agent, broker, realty, realtor | `references/niche/real-estate.md` |
+| accountant, bookkeeper, tax, CPA, CFO, advisory, audit | `references/niche/accountant.md` |
+| med spa, aesthetics, injectables, botox, filler, skin clinic | `references/niche/med-spa.md` |
+| wedding, bridal, venue, florist, event planner | `references/niche/wedding.md` |
+| agency, studio, creative, consultancy, design firm | `references/niche/agency.md` |
+| portfolio, freelance, designer, developer, photographer, illustrator | `references/niche/portfolio.md` |
+| shop, store, ecommerce, products, catalog, DTC | `references/niche/ecommerce.md` |
+| SaaS, software, app, platform, tool, B2B | `references/niche/saas.md` |
+| (default — any local service business) | `references/niche/local-business.md` |
+
+---
+
+## SEA Location Detection
+
+Used in Step 3d to determine WhatsApp CTA injection.
+
+Inject when ALL of:
+1. Business is a local business (not SaaS, not portfolio, not ecommerce-only)
+2. Location matches any signal below OR location is unknown
+
+| Location signals | Region |
+|---|---|
+| Philippines, PH, Manila, QC, Quezon City, Cebu, Davao, BGC, Makati, Taguig, Pasig, Parañaque, Mandaluyong, Alabang | Philippines |
+| Singapore, SG | Singapore |
+| Malaysia, MY, KL, Kuala Lumpur, Penang, Johor, Petaling Jaya | Malaysia |
+| Indonesia, ID, Jakarta, Bali, Surabaya, Bandung, Medan | Indonesia |
+| Thailand, TH, Bangkok, Phuket, Chiang Mai | Thailand |
+| Vietnam, VN, Ho Chi Minh, HCMC, Hanoi, Da Nang | Vietnam |
+| Hong Kong, HK | Hong Kong |
+
+When location is unknown and business is local: inject with `+[PHONE]` placeholder and note.
+
+---
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:website"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Orchestrator | Research agents (Step 2) | Build agent (Step 3) |
+|---|---|---|---|
+| `full-sail` | opus (inherit) | sonnet | opus (inherit) |
+| `quality` | opus (inherit) | sonnet | opus (inherit) |
+| `balanced` | sonnet | haiku | sonnet |
+| `budget` | sonnet | haiku | sonnet |
+
+> `opus` = inherit (uses current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/skills/sk:website/references/art-direction.md

@@ -0,0 +1,210 @@
+# Art Direction Reference
+
+Use this when building or reviewing the visual system for a website. Translate the business brief into a deliberate visual direction that can be implemented in code without drifting into generic AI-generated styling.
+
+## Workflow
+
+1. Pick one dominant aesthetic direction from the list below.
+2. Define 2–4 signature design moves.
+3. Choose a type strategy, palette behavior, spacing rhythm, and motion stance.
+4. Verify the style still supports clarity, trust, and conversion.
+
+---
+
+## Aesthetic Directions
+
+Choose exactly one dominant direction. Do not mix multiple directions without a clear hierarchy.
+
+### Restrained Editorial
+
+Good for: architecture studios, fashion-adjacent brands, premium consultants, galleries, publishing.
+
+Signals:
+- Strong typographic contrast (large serif headline, small sans body)
+- Generous whitespace — sections breathe
+- Sparse palette (warm white + dark neutral + one muted accent)
+- Image restraint — one strong image per section, not a grid
+
+Avoid:
+- Decorative layers that break the calm
+- Loud CTA styling that contradicts the quiet tone
+
+### Premium Product-Led
+
+Good for: SaaS, devices, premium consumer products, DTC hero pages.
+
+Signals:
+- Crisp hierarchy with product at the center
+- Focused product framing (screenshot, mockup, or isolated product shot)
+- Clear product storytelling — one benefit per section
+- Controlled accent color on a near-white or dark background
+
+Avoid:
+- Fake dashboards with no real product
+- Overstuffed hero sections with too many messages
+
+### Bold Brand-Forward
+
+Good for: agencies, challenger brands, culture-led products, streetwear, creative studios.
+
+Signals:
+- Strong contrast between sections
+- Daring type scale — headline that dominates the viewport
+- Sharper section transitions (hard cuts, not gentle fades)
+- High visual recall through one repeating graphic pattern or color block
+
+Avoid:
+- Sacrificing legibility for attitude
+- Using bold direction for trust-sensitive businesses (law, medical, finance)
+
+### Warm Hospitality
+
+Good for: cafes, boutique hotels, restaurants, lifestyle spaces, florists, bakeries.
+
+Signals:
+- Tactile, atmosphere-first imagery (real textures, warm light, food close-ups)
+- Warm neutrals — cream, sand, olive, terracotta, warm grey
+- Editorial pacing — section rhythm like a magazine spread
+- Practical info (hours, address, reservation CTA) stays visible and easy to find
+
+Avoid:
+- Corporate UI chrome that breaks the atmosphere
+- Hiding menu, hours, location, or booking link behind design
+- Stock cafe imagery when real photography is the point
+
+### Sharp Technical
+
+Good for: developer tools, B2B platforms, infrastructure products, data products, security tools.
+
+Signals:
+- Precise grid with tight alignment
+- Low visual noise — very few decorative elements
+- Strong information hierarchy — function drives layout
+- Restrained motion — only when it explains something
+
+Avoid:
+- Playful or warm treatments that undermine technical credibility
+- Dense copy with no visual breathing room
+
+### Playful Contemporary
+
+Good for: consumer apps, EdTech, food delivery, kids products, lifestyle brands targeting under-35.
+
+Signals:
+- Rounded forms, approachable typography
+- Brighter palette with confident accent colors
+- Motion used generously but purposefully
+- Illustration or character work where appropriate
+
+Avoid:
+- Looking cheap or juvenile for a premium audience
+- Overanimation that obscures the product
+
+### Quiet Luxury
+
+Good for: premium services, interior design, high-end hospitality, luxury retail, wellness brands.
+
+Signals:
+- Restraint above all — nothing superfluous
+- Tactile material cues (fabric textures, paper grain, stone)
+- Elegant typography contrast (fine serif + sparse uppercase tracking)
+- Limited palette — usually 2–3 colors maximum
+
+Avoid:
+- Gimmicky animation that breaks the calm
+- Shiny, trend-driven effects (glass, neon, gradients)
+- Too much copy — quiet luxury lets the brand speak with less
+
+---
+
+## Signature Design Moves
+
+Every strong site has 2–4 memorable moves. Choose moves that fit the direction and stick with them.
+
+Examples:
+- Oversized serif headline with tight sans-serif body underneath
+- Muted palette with one decisive high-contrast accent color
+- Image-first storytelling with minimal interface chrome around it
+- Rigid grid with one intentionally broken element per section
+- Soft material textures behind simple white interface frames
+- Full-bleed photography sections alternating with dense-type sections
+- Sticky navigation that changes color on scroll
+
+**Rule:** Two strong moves beat six weak ones. Restraint is a design decision.
+
+---
+
+## Typography Mood
+
+Choose typography to express the brand's confidence level and audience — not just to look fashionable.
+
+| Mood | Type strategy |
+|---|---|
+| Elegant and assured | Serif headline + restrained supporting sans (e.g., Playfair Display + Inter) |
+| Modern and precise | Neo-grotesk or geometric sans with strong scale control (e.g., DM Sans, Plus Jakarta Sans) |
+| Warm and neighborhood-focused | Soft serif or humanist sans pairings (e.g., Lora + Nunito, Fraunces + Manrope) |
+| Technical and credible | Clean sans with tight hierarchy, minimal ornament (e.g., IBM Plex Sans, Space Grotesk) |
+| Bold brand-forward | Display face with strong personality (e.g., Syne, Cabinet Grotesk, Clash Display) |
+| Quiet luxury | Fine-weight serif or high-tracking uppercase (e.g., Cormorant Garamond, Libre Baskerville) |
+
+**Rules:**
+- Use contrast in scale, weight, and rhythm to create hierarchy before adding more colors.
+- Never use system fonts (Arial, Helvetica, Times) — always pick with intention.
+- Two fonts maximum. One display + one body. A third only if very controlled.
+
+---
+
+## Color Behavior
+
+- One strong accent is often enough. Neutrals do most of the structural work.
+- Color guides attention — it should not paint every surface.
+- Strong contrast can come from spacing and scale, not just saturated color.
+- Trust-sensitive businesses (legal, medical, finance) need calm palettes even when layout is bold.
+- If photography is strong, reduce color complexity — let the images carry the warmth.
+
+**Custom palette rules:**
+- Never use raw Tailwind palette colors (blue-500, gray-200, etc.) — always define custom values.
+- Name colors semantically: `brand`, `accent`, `surface`, `text`, `muted`.
+- Define in `tailwind.config.js` under `theme.extend.colors`.
+
+---
+
+## Motion Stance
+
+| Level | When to use | What to use |
+|---|---|---|
+| None | Trust-sensitive, performance-critical | No animation |
+| Subtle | Most business sites | Fade + translate on scroll reveal, 200–300ms |
+| Moderate | Consumer brands, hospitality | Stagger reveals, gentle parallax, hover transitions |
+| Expressive | Agencies, entertainment, playful brands | Page transitions, character animation, scroll-driven |
+
+**Rules:**
+- Motion should support pacing, reveal hierarchy, or reinforce affordances — not decorate.
+- `transform` and `opacity` only — never animate layout properties (width, height, margin).
+- Respect `prefers-reduced-motion` — wrap all animations in the media query.
+- If the page relies on performance or trust, reduce animation density.
+
+---
+
+## Anti-Patterns
+
+Avoid in all cases:
+- Random mix of brutalism, glassmorphism, and luxury minimalism in the same page
+- Default AI startup gradients (purple → blue, dark mode glow) unless clearly warranted
+- Decorative visuals that weaken the CTA or bury practical information
+- Style direction that contradicts the business category (bold agency aesthetic for a law firm)
+- Fake UI, fake charts, fake product screenshots, fake reviews
+- Overanimated entrance sequences that delay time to content
+
+By direction:
+- **SaaS**: fake dashboards, purple glow overload, feature-card sprawl with no story
+- **Agency**: dramatic visuals with vague copy, no real proof of work
+- **Local business**: beautiful design but phone, hours, and service area are buried
+- **Hospitality**: atmospheric imagery but no menu, reservation link, or location
+
+**Recovery moves when it feels generic:**
+1. Remove one full visual layer
+2. Choose one dominant type contrast and commit to it
+3. Reduce palette to neutrals + one accent
+4. Simplify motion to a single reveal family
+5. Move practical business information higher on the page