@donotdev/cli 0.0.13 → 0.0.15

package/templates/root-consumer/guides/dndev/SETUP_VERCEL.md.example

@@ -0,0 +1,176 @@
+# Setup: Vercel
+
+**From zero to deployed: Vercel hosting + API routes with Firebase data layer.**
+
+---
+
+## Architecture
+
+Vercel is your **hosting and API platform** — it serves your frontend and runs serverless API routes.
+Firebase is your **data layer** — Firestore (CRUD), Firebase Auth (users), Firebase Storage (files).
+
+The framework generates API routes as Vercel Serverless Functions that talk to Firebase on the backend.
+
+---
+
+## Step 1: Create Firebase Project (Data Layer)
+
+Even though you deploy to Vercel, you still need Firebase for data.
+
+1. Go to [Firebase Console](https://console.firebase.google.com) → Create a project
+2. Enable **Authentication** → Email/Password (+ OAuth providers if needed)
+3. Enable **Cloud Firestore** → Create Database → select region
+4. Enable **Storage** if your app uploads files
+
+Get the Firebase web config from: **Project Settings → General → Your apps → Web app → SDK config**.
+
+---
+
+## Step 2: Run Setup
+
+```bash
+dndev firebase:setup
+```
+
+This writes Firebase SDK config to your app's `.env`. The `overlay-vercel` providers.ts initializes the Firebase client SDK.
+
+---
+
+## Step 3: Configure Vercel
+
+1. Create a [Vercel](https://vercel.com) account and link your Git repo
+2. Import the project in Vercel Dashboard
+3. Set the **Root Directory** to `apps/<your-app>` (or leave blank if monorepo auto-detected)
+4. Set **Framework Preset** to Vite (or Next.js if using Next)
+
+**Environment Variables** (in Vercel Dashboard → Settings → Environment Variables):
+
+Copy your Firebase vars from `.env`:
+- `VITE_FIREBASE_API_KEY`
+- `VITE_FIREBASE_PROJECT_ID`
+- `VITE_FIREBASE_AUTH_DOMAIN`
+- `VITE_FIREBASE_STORAGE_BUCKET`
+- `VITE_FIREBASE_MESSAGING_SENDER_ID`
+- `VITE_FIREBASE_APP_ID`
+
+For Next.js apps, use `NEXT_PUBLIC_` prefix instead of `VITE_`.
+
+**Server secrets** (for API routes):
+- `STRIPE_SECRET_KEY`
+- `STRIPE_WEBHOOK_SECRET`
+- Any OAuth client secrets
+
+---
+
+## Step 4: API Routes (Functions)
+
+Your backend functions are in `functions/` and deploy as Vercel Serverless Functions.
+
+```
+functions/
+├── src/
+│   ├── auth/        # Auth endpoints (signup, login, etc.)
+│   ├── billing/     # Stripe endpoints (checkout, webhook, etc.)
+│   ├── crud/        # CRUD endpoints (create, read, update, delete)
+│   └── oauth/       # OAuth callback handlers
+├── vercel.json      # Route configuration
+├── tsconfig.json
+└── package.json
+```
+
+Functions use the Firebase Admin SDK on the server side to access Firestore, verify auth tokens, etc.
+
+---
+
+## Step 5: Deploy
+
+**Option A — Git push (recommended)**
+
+Push to your connected branch. Vercel auto-deploys.
+
+```bash
+git push origin main
+```
+
+**Option B — Vercel CLI**
+
+```bash
+npx vercel --prod
+```
+
+---
+
+## Environment Variables
+
+| File | What Goes Here | Loaded By |
+|------|---------------|-----------|
+| `apps/<app>/.env` | Firebase config, license key, Stripe publishable key | Vite/Next.js (dev + build) |
+| `apps/<app>/.env.local` | Local overrides (gitignored) | Vite/Next.js (overrides .env) |
+| `apps/<app>/.env.production` | Production overrides | Vite/Next.js (build --mode production) |
+| `functions/.env` | Server secrets: STRIPE_SECRET_KEY, OAuth secrets | API routes runtime |
+| Vercel Dashboard | All production env vars (client + server) | Vercel runtime |
+
+**Client vars** (browser-safe): `VITE_*` or `NEXT_PUBLIC_*` prefix.
+**Server vars** (secrets): No prefix needed in Vercel Dashboard — only accessible in API routes.
+
+---
+
+## Local Development
+
+```bash
+bun dev
+```
+
+The app runs locally, talking to your Firebase project. API routes can be tested with:
+
+```bash
+vercel dev
+```
+
+Or use Firebase emulators for fully local development:
+
+```bash
+dndev emu start
+```
+
+---
+
+## Secrets
+
+Server-side secrets go in `functions/.env` locally and in Vercel Dashboard for production.
+
+**We NEVER ask for secret keys.** You place them yourself:
+
+```bash
+# functions/.env
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+Then add the same values in Vercel Dashboard → Settings → Environment Variables.
+
+See [ENV_SETUP.md → Secrets Philosophy](./ENV_SETUP.md#secrets-philosophy) for the full policy.
+
+---
+
+## Troubleshooting
+
+**"Firebase config not loading"**
+→ Check `.env` is in your **app directory** (`apps/<app>/.env`), not repo root
+→ Vite vars must start with `VITE_`, Next.js vars with `NEXT_PUBLIC_`
+
+**"401 / Permission denied on API routes"**
+→ Check Firebase service account key is configured in Vercel env vars
+→ Verify `GOOGLE_APPLICATION_CREDENTIALS` or inline credentials in API routes
+
+**"CORS error"**
+→ Vercel handles CORS for same-origin requests automatically
+→ For cross-origin: add CORS headers in your API route handler
+
+**"Build fails on Vercel"**
+→ Check Root Directory is set to your app directory
+→ Ensure `package.json` has correct `build` script
+
+---
+
+**`dndev firebase:setup` → configure Vercel project → set env vars → `git push`. Vercel deploys automatically.**

package/templates/root-consumer/guides/dndev/USE_ROUTING.md.example

@@ -226,18 +226,14 @@ navigate('/products', {
 
 ### 5. Query Parameters
 
-**✅ Use framework useSearchParams:**
+**✅ Use framework useSearchParams (read-only, returns URLSearchParams directly):**
 ```tsx
 import { useSearchParams } from '@donotdev/ui/routing';
 
 function ProductList() {
-  const [searchParams, setSearchParams] = useSearchParams();
+  const searchParams = useSearchParams();
   const page = searchParams.get('page') || '1';
-  
-  const handlePageChange = (newPage: string) => {
-    setSearchParams({ page: newPage });
-  };
-  
+
   return <div>Page: {page}</div>;
 }
 ```
@@ -478,8 +474,8 @@ navigate('/products', { replace: true });
 // Route params
 const id = useRouteParam('id');
 
-// Query params
-const [searchParams, setSearchParams] = useSearchParams();
+// Query params (read-only, returns URLSearchParams directly)
+const searchParams = useSearchParams();
 const page = searchParams.get('page');
 
 // Navigation menu

package/templates/root-consumer/guides/dndev/essences_reference.css.example

@@ -0,0 +1,174 @@
+/**
+ * Reference: Framework essences (Brutalist, Luxury).
+ * Copy the blocks you need into your app's src/themes.css.
+ * Default essence = SaaS (Inter); these do not apply until you set the class on <html>.
+ *
+ * Fonts: Space Grotesk (Brutalist), Playfair Display (Luxury), Inter, Roboto are bundled in @donotdev/ui (no external requests).
+ */
+
+/** =========================================================================
+ *  Brutalist — Industrial, monospace body, Space Grotesk headlines, orange/black.
+ *  Set <html class="brutalist"> to apply.
+ *  ========================================================================= */
+.brutalist {
+  --theme-icon: 'Construction';
+  --theme-label: 'Brutalist';
+  --theme-is-dark: 1;
+
+  /* 1. Core Colors - Black + white + industrial orange */
+  --background: #000000;
+  --foreground: #ffffff;
+  --primary: #f97316;
+  --secondary: #ffffff;
+  --accent: #f97316;
+
+  /* 2. Semantic */
+  --success: #22c55e;
+  --warning: #f97316;
+  --destructive: #dc2626;
+
+  /* 3. Surfaces - Dark, industrial */
+  --muted: #111111;
+  --muted-foreground: #888888;
+  --border: #ffffff;
+  --input: #111111;
+  --ring: #f97316;
+  --card: #000000;
+  --card-foreground: #f97316;
+  --popover: #000000;
+  --popover-foreground: #ffffff;
+  --surface-1: #0a0a0a;
+
+  /* 4. Text on Colors */
+  --primary-foreground: #ffffff;
+  --secondary-foreground: #000000;
+  --accent-foreground: #000000;
+  --success-foreground: #ffffff;
+  --warning-foreground: #000000;
+  --destructive-foreground: #ffffff;
+
+  /* 5. Radius - Hard zero */
+  --radius-interactive: 0;
+  --radius-surface: 0;
+  --radius-floating: 0;
+
+  /* 6. Typography - Monospace for body, Space Grotesk 700 for headings */
+  --font-family: var(--font-mono);
+  --font-headline: "Space Grotesk", var(--font-sans);
+  --font-weight-semibold: 700;
+  --font-weight-bold: 700;
+
+  /* 7. Borders */
+  --border-width: 2px;
+  --border-huge: 4px;
+
+  /* 8. Shadows — flat by default, hard offset on interactive */
+  --shadow-color: var(--foreground);
+  --shadow-sm: none;
+  --shadow-md: none;
+  --shadow-xl: 8px 8px 0px 0px var(--shadow-color);
+  --shadow-cta: 20px 20px 0px 0px var(--shadow-color);
+
+  /* 9. Per-variant shadows — only at xl level (elevated/clickable) */
+  --shadow-primary: none;
+  --shadow-primary-xl: 8px 8px 0px 0px var(--background);
+  --shadow-secondary: none;
+  --shadow-secondary-xl: 8px 8px 0px 0px var(--primary);
+
+  /* 10. Header padding for hard-offset shadows */
+  --header-shadow-padding: 0.75rem;
+}
+
+/* Body - grid background */
+.brutalist body {
+  background-color: var(--background);
+  background-image:
+    linear-gradient(#111 1px, transparent 1px),
+    linear-gradient(90deg, #111 1px, transparent 1px);
+  background-size: 40px 40px;
+}
+
+/* Uppercase headings (both native elements and Text component levels) */
+.brutalist {
+  :is(h1, h2, h3, h4, h5, h6),
+  [data-level^='h'] {
+    text-transform: uppercase;
+  }
+}
+
+/* Flat surface - no gradient glow */
+.brutalist .dndev-surface { background: var(--card); }
+.brutalist .dndev-surface[data-variant='outline'] { border: var(--border-width) solid var(--border); }
+
+.brutalist .dndev-card[data-variant='outline'] {
+  background: transparent;
+  box-shadow: none;
+}
+
+
+/** =========================================================================
+ *  Luxury — Playfair Display headlines, gold/cream, warm shadows.
+ *  Set <html class="luxury"> to apply.
+ *  ========================================================================= */
+.luxury {
+  --theme-icon: 'Gem';
+  --theme-label: 'Luxury';
+  --theme-is-dark: 0;
+
+  /* 1. Core Colors */
+  --background: #faf8f5;
+  --foreground: #1c1917;
+  --primary: #b45309;
+  --secondary: #fef3c7;
+  --accent: #92400e;
+
+  /* 2. Semantic */
+  --success: #15803d;
+  --warning: #b45309;
+  --destructive: #b91c1c;
+
+  /* 3. Surfaces */
+  --muted: #fef9c3;
+  --muted-foreground: #78716c;
+  --border: #e7e5e4;
+  --border-hairline: 1px;
+  --input: #ffffff;
+  --ring: #b45309;
+  --card: #ffffff;
+  --card-foreground: #1c1917;
+  --popover: #ffffff;
+  --popover-foreground: #1c1917;
+  --surface-1: #faf8f5;
+
+  /* 4. Text on Colors */
+  --primary-foreground: #ffffff;
+  --secondary-foreground: #1c1917;
+  --accent-foreground: #ffffff;
+  --success-foreground: #ffffff;
+  --warning-foreground: #1c1917;
+  --destructive-foreground: #ffffff;
+
+  /* 5. Radius */
+  --radius-interactive: 0.375rem;
+  --radius-surface: 0.5rem;
+  --radius-floating: 0.5rem;
+
+  /* 6. Typography — lighter weights, serif headlines */
+  --font-family: var(--font-sans);
+  --font-headline: 'Playfair Display', var(--font-serif);
+  --font-weight-normal: 300;
+  --font-weight-medium: 400;
+  --font-weight-semibold: 500;
+  --font-weight-bold: 600;
+
+  /* 7. Spacing — generous, one notch above expressive */
+  --gap-sm: 0.75rem;
+  --gap-md: 1.5rem;
+  --gap-lg: 3rem;
+
+  /* 8. Shadows — warm gold-tinted, soft diffused */
+  --shadow-color: color-mix(in oklab, #b45309 8%, transparent);
+  --shadow-sm: 0 1px 3px var(--shadow-color);
+  --shadow-md: 0 4px 12px var(--shadow-color);
+  --shadow-xl: 0 8px 24px var(--shadow-color);
+}

package/templates/root-consumer/guides/wai-way/agents/builder.md.example

@@ -31,6 +31,10 @@ core_principles:
   - HARDCODE strings first - validate UX before i18n
   - Use framework components only - no custom CSS
   - Trust component defaults
+  - **70/30 Hierarchy:** Use `primary` variant for the North Star action; `outline`/`ghost` for others.
+  - **Benefit-First Copy:** For Heros/Cards, translate technical features into outcomes (e.g., 'Optimize Your Fleet' vs 'Manage Cars').
+  - **Success Intent:** Trust framework defaults for CRUD (automatic toasts/loaders). Only propose custom redirects or celebratory components for the 'North Star' action or if the user asks for more polish.
+  - **Spec Drift:** If you must deviate from the spec (field types, logic), log it in `spec_changes.md`. Do NOT modify `spec_template.md` directly.
 
 crud_pattern:
   list_page: |
@@ -83,5 +87,11 @@ Rules:
 3. HARDCODE all strings (no i18n yet)
 4. Use framework components only
 
+**Apply UX Mandates:**
+- **Visual Anchor:** Every page must have ONE clear primary focus (Hero or Main Card).
+- **Mobile First:** Ensure all touch targets are > 44px.
+- **Kano Filter:** Use 'Benefit' copy for marketing/dashboard pages. Use 'Utility' copy for forms.
+- **Success Intent:** Trust framework defaults. Only propose custom redirects/celebration for the 'North Star' action.
+
 Build each page following the scaffolded patterns.
 ```

package/templates/root-consumer/guides/wai-way/agents/extractor.md.example

@@ -36,6 +36,10 @@ core_principles:
   - Define entity states and transitions
   - Capture business rules and validations explicitly
   - Never assume - always ask
+  - **UX Strategist:** Identify the "North Star" action (max 2 clicks from home).
+  - **Kano Prioritization:** Tag features as Must-Have vs Delighter.
+  - **Duty to Advise:** Challenge layouts with high friction (> 2 clicks). If the user overrides your advice, log it in **Section 11** of the spec and move on.
+  - **Spec Drift:** Any changes to the validated spec must be logged in `spec_changes.md` for human review.
 
 phase_0_brainstorm:
   goal: DEEPLY understand the app and produce COMPLETE validated spec
@@ -47,7 +51,7 @@ phase_0_brainstorm:
       questions:
         - "Describe your app in one paragraph. What problem does it solve?"
         - "Who is the primary user? Who else uses it?"
-        - "What's the ONE thing a user MUST be able to do?"
+        - "What's the ONE thing a user MUST be able to do? (The North Star)"
         - "What makes this different from similar apps?"
       done_when: "Can explain the app to someone unfamiliar in 2 minutes"
 
@@ -111,17 +115,26 @@ phase_0_brainstorm:
         - "What happens when [entity status] changes unexpectedly?"
       done_when: "Common failure scenarios have defined handling"
 
-  output: Filled spec_template.md with ALL sections complete, validated by user
+    7_ux_intent:
+      purpose: "Plan the layout hierarchy and navigation flow"
+      questions:
+        - "Where should the shortcut for the North Star action live? (Goal: < 2 clicks)"
+        - "Which features are 'Delighters' (Marketing/Heroes) vs 'Must-Haves' (CRUD)?"
+      done_when: "Navigation hierarchy planned; high-friction paths challenged"
+
+  output: Filled spec_template.md with ALL sections complete, including Section 11 for overrides.
 
 phase_1_scaffold:
-  goal: Create all pages from validated spec
+  goal: Create an Interactive Prototype from the validated spec
   prerequisite: "spec_template.md is COMPLETE with no empty sections or TBDs"
   steps:
     - Verify spec is truly complete
     - Create *Page.tsx files for each route in spec
-    - Set PageMeta (namespace, icon, auth) from spec
+    - Set PageMeta (namespace, icon). **Set auth: false** temporarily so the user can click through the prototype without login.
+    - **Interactive Stubs:** Each page must contain its 'Role' (from spec) and 'Next Step' navigation buttons to related pages.
+    - **Friction Check:** If North Star path > 2 clicks, propose a 'Global Shortcut' (Header/Sidebar).
     - Verify app runs with bun dev
-  output: All routes exist as stub pages with correct PageMeta
+  output: All routes exist as **Interactive Prototype Stubs** with navigation buttons.
 
 validation_checklist:
   before_filling_spec:
@@ -129,14 +142,21 @@ validation_checklist:
     - [ ] Can trace every page back to a user journey
     - [ ] Can answer "who can do X to Y?" for any entity/action
     - [ ] Can answer "what happens when Z fails?" for common scenarios
+    - [ ] **North Star identified:** Defined a max 2-click path for the core action.
 
   before_moving_to_scaffold:
     - [ ] Every user journey has numbered steps
     - [ ] Every entity has fields, states, permissions
     - [ ] Every business rule is explicit
+    - [ ] **Overrides logged:** Any intentional UX friction documented in Section 11.
     - [ ] No empty fields in spec_template.md
     - [ ] User has validated the spec
 
+  after_scaffold_validation:
+    - [ ] App is running and clickable.
+    - [ ] User has clicked through the "North Star" path.
+    - [ ] Sitemap and click-depth are validated in the browser.
+
 read_files:
   - "guides/wai-way/blueprints/0_brainstorm.md"
   - "guides/wai-way/spec_template.md"

package/templates/root-consumer/guides/wai-way/agents/polisher.md.example

@@ -21,7 +21,7 @@ persona:
 
 golden_rule: |
   THE SPEC IS YOUR TEST PLAN.
-  READ the spec (Phase 0 output) for entities, permissions, journeys.
+  READ the spec (Phase 0 output) and `spec_changes.md` for entities, permissions, journeys.
   READ each entity file for access rules and fields.
   GENERATE tests that verify the spec is implemented correctly.
 
@@ -31,6 +31,8 @@ core_principles:
   - Configuration: app.ts, legal.ts, .env
   - Mobile check: 375px width
   - i18n is OPTIONAL and comes LAST
+  - **Contract Check:** Consult **Section 11** of the spec for intentional UX overrides. If a layout deviation is documented there, it is a **PASS**.
+  - **Heuristic Audit:** Verify 3-click rule for North Star, system status visibility (loaders), and visual hierarchy.
 
 test_generation:
   entity_tests:
@@ -53,6 +55,14 @@ test_generation:
     - No unauthenticated writes
     output: "tests/access/access-rules.test.ts"
 
+ux_audit_checklist:
+  - [ ] **Contract Compliance:** Check Section 11 of spec for approved deviations.
+  - [ ] **Spec Drift Review:** Ensure all changes in `spec_changes.md` are documented and explained.
+  - [ ] **North Star Check:** Is the primary action reachable in < 3 clicks? (Unless overridden)
+  - [ ] **Hierarchy:** Does every page have a clear visual anchor (one primary focus)?
+  - [ ] **System Status:** Verify framework default feedback (Toasts/Loaders) is visible. Ask if 'North Star' action needs a custom 'Delighter' redirect.
+  - [ ] **Mobile:** Touch targets > 44px, no horizontal scroll.
+
 firestore_rules:
   source: "Entity access definitions"
   mapping:
@@ -116,7 +126,8 @@ Steps:
 6. Update app.ts, legal.ts, .env
 7. Run bun test — all must pass
 8. Mobile check at 375px
-9. (Optional) Add i18n
+9. **UX Audit** (3-click rule, Visual Anchor, Mobile targets, and Spec Drift review)
+10. (Optional) Add i18n
 
 Call get_guide("TESTING") for testing patterns.
 ```

package/templates/root-consumer/guides/wai-way/blueprints/0_brainstorm.md.example

@@ -37,8 +37,7 @@ User provides idea
     ↓
 Agent calls list_features() → matches needs to existing framework capabilities
     ↓
-Agent asks IDENTITY questions (who, what, why)
-    ↓
+    Agent asks IDENTITY questions (who, what, why, and **Aesthetic Essence**)    ↓
 Agent asks USER JOURNEY questions (what do users DO step by step?)
     ↓
 Agent asks DATA questions (what entities, relationships, states?)
@@ -66,6 +65,7 @@ Start broad, then narrow down:
 - "Who is the primary user? Secondary users?"
 - "What's the one thing a user MUST be able to do?"
 - "What makes this different from [similar apps]?"
+- **Aesthetic Essence:** "Which visual 'vibe' fits the brand? SaaS (Clean/Modern), Luxury (Gold/Serif), or Brutalist (Orange/High-Contrast)?"
 
 **Don't proceed until you can explain the app to someone else.**
 

package/templates/root-consumer/guides/wai-way/blueprints/1_scaffold.md.example

@@ -22,7 +22,18 @@ Preset comes from your completed spec (Phase 0).
 
 ---
 
-## Step 2: Review Spec Pages
+## Step 2: Apply Aesthetic Essence
+
+**READ:** `guides/dndev/essences_reference.css`
+
+Apply the chosen essence (SaaS, Luxury, Brutalist) to your `src/themes.css`. 
+- If **SaaS**: Keep defaults.
+- If **Luxury/Brutalist**: Copy the variables from the reference file into `src/themes.css`.
+- If **Custom**: Adjust primary/secondary colors in `:root`.
+
+---
+
+## Step 3: Review Spec Pages
 
 From your spec, you have a list of pages. Now create them.
 
@@ -43,13 +54,16 @@ touch src/pages/ProductPage.tsx
 
 ---
 
-## Step 4: Add PageMeta
+## Step 4: Create Interactive Prototype Stubs
 
 **READ:** `src/pages/HomePage.tsx` for PageMeta pattern.
 
+For **each page**, create a functional stub that allows the user to validate the flow.
+
 ```tsx
 import type { PageMeta } from '@donotdev/core';
-import { PageContainer } from '@donotdev/ui';
+import { PageContainer, Link } from '@donotdev/ui';
+import { Section, Stack, Text, Card, Button } from '@donotdev/components';
 import { Info } from 'lucide-react';
 
 export const NAMESPACE = 'about';
@@ -57,22 +71,44 @@ export const NAMESPACE = 'about';
 export const meta: PageMeta = {
   namespace: NAMESPACE,
   icon: <Info />,
-  // From spec:
-  // auth: true,                              // Protected
-  // auth: { required: true, role: 'admin' }, // Admin
-  // hideFromMenu: true,                      // Form pages
+  // From spec: Set auth: false for the prototype phase so user can click through
+  auth: false, 
 };
 
 export default function AboutPage() {
-  return <PageContainer>About Page</PageContainer>;
+  return (
+    <PageContainer>
+      <Section title="About Page (Prototype Stub)">
+        <Stack gap="large">
+          <Text><strong>Role:</strong> [Describe the purpose of this page from the spec]</Text>
+          
+          <Text level="h3">Navigate Flow:</Text>
+          <Stack direction="row" gap="medium">
+            <Link path="/dashboard">
+              <Button variant="outline">Go to Dashboard</Button>
+            </Link>
+            <Link path="/contact">
+              <Button variant="outline">Go to Contact</Button>
+            </Link>
+          </Stack>
+
+          {/* Placeholder for flow validation */}
+          <Card variant="outline" content={[`[Placeholder for ${NAMESPACE} core components]`]} />
+        </Stack>
+      </Section>
+    </PageContainer>
+  );
 }
 ```
 
+**Goal:** The user should be able to `bun dev` and click through the entire app flow (the "North Star" path) to validate the architecture before you build any logic.
+
 ---
 
 ## Output
 
 - [ ] App runs with `bun dev`
-- [ ] All route files created (from spec)
-- [ ] PageMeta set with correct auth levels (from spec)
-- [ ] Navigation auto-generated
+- [ ] All route files created as **Interactive Stubs**
+- [ ] PageMeta set (auth: false for prototype validation)
+- [ ] Navigation links included on each stub to related pages
+- [ ] User has "clicked through" the flow and validated sitemap/friction

package/templates/root-consumer/guides/wai-way/blueprints/3_compose.md.example

@@ -9,7 +9,18 @@
 
 ---
 
-## Step 1: Read Page Patterns
+## Step 1: Apply UX Intent Rules
+
+**Every page must follow the Designer Mandate:**
+1. **70/30 Hierarchy:** Only ONE `primary` variant button/card per view. Use `outline` or `muted` for everything else to direct the user's eye to the North Star.
+2. **Benefit-First Copy:** Do not use technical titles for Heros/Cards. 
+   - ❌ "User Management" → ✅ "Empower Your Team"
+   - ❌ "Car List" → ✅ "Explore the Fleet"
+3. **Success Intent:** Ensure framework default toasts are working. Only add a custom celebratory view or Redirect for the **North Star** goal completion.
+
+---
+
+## Step 2: Read Page Patterns
 
 **READ:** `guides/wai-way/page_patterns.md` for all patterns:
 - Dashboard, List Page, Form Page
@@ -18,7 +29,7 @@
 
 ---
 
-## Step 2: CRUD Pages
+## Step 3: CRUD Pages
 
 For each entity in spec:
 
@@ -60,7 +71,7 @@ export default function ProductPage() {
 
 ---
 
-## Step 3: Dashboard Page
+## Step 4: Dashboard Page
 
 Copy Dashboard pattern from `page_patterns.md`:
 - Quick actions (cards with onClick)
@@ -69,7 +80,7 @@ Copy Dashboard pattern from `page_patterns.md`:
 
 ---
 
-## Step 4: Landing Pages
+## Step 5: Landing Pages
 
 Copy Landing pattern from `page_patterns.md`:
 - HeroSection with CTAs