npm - @donotdev/cli - Versions diffs - 0.0.14 → 0.0.15 - Mend

@donotdev/cli 0.0.14 → 0.0.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (151) hide show

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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

package/templates/root-consumer/guides/wai-way/spec_template.md.example CHANGED Viewed

@@ -14,6 +14,7 @@
 | **Primary User** | _(Who uses this daily?)_ |
 | **Secondary Users** | _(Who else interacts?)_ |
 | **Core Value** | _(What problem does it solve?)_ |
+| **Aesthetic Essence** | SaaS (Default) / Luxury / Brutalist / Custom |
 ---
@@ -275,13 +276,13 @@ _(Copy entity template for each entity)_
 ---
-## 11. Open Questions
+## 11. Design Decisions & Overrides
+> **CRITICAL:** These are intentional deviations from framework UX heuristics (e.g., 3-click rule, 70/30 hierarchy).
+> **FOR AGENTS:** If a layout choice is documented here, do NOT challenge or flag it during the Build or Polish phases.
-> Anything unresolved? List here. **No coding until resolved.**
-- [ ]
-- [ ]
-- [ ]
+| Target (Page/Feature) | Override Description | Rationale |
+|-----------------------|----------------------|-----------|
+| | | |
 ---

package/templates/app-payload/.env.example DELETED Viewed

@@ -1,28 +0,0 @@
-# Payload CMS Configuration
-PAYLOAD_SECRET=your-super-secret-key-here
-PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3001
-# Database Configuration (MongoDB)
-MONGODB_URI=mongodb://localhost:27017/{{projectName}}
-# For production, use MongoDB Atlas or similar
-# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/{{projectName}}?retryWrites=true&w=majority
-# Optional: Redis for caching (recommended for production)
-# REDIS_URL=redis://localhost:6379
-# CORS Origins (comma-separated)
-CORS_ORIGINS=http://localhost:3000,https://{{projectName}}.com,https://admin.{{projectName}}.com
-# File Upload Configuration
-PAYLOAD_PUBLIC_MAX_FILE_SIZE=5000000
-# Admin Configuration
-PAYLOAD_PUBLIC_ADMIN_EMAIL=admin@{{projectName}}.com
-PAYLOAD_PUBLIC_ADMIN_PASSWORD=your-admin-password
-# Optional: Email Configuration (for notifications)
-# SMTP_HOST=smtp.gmail.com
-# SMTP_PORT=587
-# SMTP_USER=your-email@gmail.com
-# SMTP_PASS=your-app-password