@svadmin/create 0.40.2 → 0.41.0

package/guidance/AGENTS.md

@@ -4,6 +4,17 @@ Read `DESIGN.md` before creating, revising, or reviewing any UI. It is the
 authority for visual language, page hierarchy, feedback ownership, and
 acceptance checks in this project.
 
+## Product-first generation
+
+Read `PRODUCT.md` before converting a schema, API, or feature list into pages. Build the product brief, workflows, resources, actions, surfaces, and menu in that order. Resources are data contracts; they are not automatic pages or menu entries.
+
+- Keep one primary purpose and one dominant next action per surface.
+- Give every core workflow a serving surface or contextual entry.
+- Declare loading, empty, error, forbidden, and success states before writing markup.
+- Menu count is determined by actual business needs. Never apply a fixed global cap; use roles, task frequency, placement, grouping, and context to keep it legible.
+- Run `svadmin vibe review ./svadmin.product.json` before generating UI and `svadmin vibe plan ./svadmin.product.json --role <role-id>` to inspect role-specific navigation.
+- Treat review warnings as prompts for product judgment. Do not silently delete business-required workflows or menu entries to make a count pass.
+
 ## Platform entrypoints
 
 Before generating or modifying application code, read these stable files

package/guidance/DESIGN.md

@@ -9,9 +9,15 @@ colors:
   surface-subtle: "#f1f4f8"
   muted-foreground: "#425466"
   border: "#e6ebf1"
-  primary: "#635bff"
-  on-primary: "#ffffff"
-  success: "oklch(0.51 0.16 151)"
+  secondary: "#eef2f7"
+  accent: "#eef0ff"
+  accent-foreground: "#5147d9"
+  input: "#cbd5e1"
+  sidebar: "#ffffff"
+  sidebar-foreground: "#425466"
+  primary: "oklch(0.54 0.24 293)"
+  on-primary: "oklch(0.99 0 0)"
+  success: "oklch(0.55 0.16 151)"
   warning: "oklch(0.7 0.15 75)"
   danger: "oklch(0.58 0.22 27)"
 typography:
@@ -123,7 +129,7 @@ not become a mixed visual theme:
 
 | Reference | Adopted responsibility | Explicitly excluded |
 | --- | --- | --- |
-| Stripe style prompt | `#635bff` action accent, technical grid, hairline borders, layered elevation, lift/depress feedback | Stripe brand assets, marketing gradients, oversized hero treatment |
+| Stripe style prompt | theme-menu chip `#635bff`, painted `--primary: oklch(0.54 0.24 293)`, technical grid, hairline borders, layered elevation, lift/depress feedback | Stripe brand assets, marketing gradients, oversized hero treatment |
 | Corporate-clean prompt | neutral enterprise surfaces, readable hierarchy, generous spacing, focus-ring offset, motion capped at 200ms | blue-only palette, rigid utility-class recipes, decorative cards |
 | Fuse / Midone / Skote | navigation anatomy, page-family coverage, toolbar/table/form composition, density observations | vendor palette, logos, fonts, CSS, copied markup or component chrome |
 | svadmin | semantic tokens, component API, state ownership, accessibility, responsive contracts | no second visual authority |
@@ -160,7 +166,9 @@ The same contract is used at every delivery surface:
   use motion-token fallbacks so they also work without the full UI package.
 - `packages/lite` mirrors the palette with literal colors. Its legacy-browser
   contract deliberately excludes custom properties and modern selectors;
-  visual alignment must not remove that compatibility.
+  visual alignment must not remove that compatibility. Its literal accent
+  remains the preset chip `#635bff`, not the oklch `--primary` used by
+  `@svadmin/ui`.
 
 Theme refinements must preserve component density, invalid and selected states.
 Focus belongs to the active control, not every enclosing card. Search icons and
@@ -224,8 +232,41 @@ not a page background. Success, warning, and danger are reserved for semantic
 status and feedback. Consumer themes may replace the primary hue while keeping
 the neutral hierarchy and contrast relationships intact.
 
-The reference Stripe preset uses `#635bff`, `#0a2540`, `#f6f9fc`, and
-`#e6ebf1`. The grid is a low-contrast canvas texture only; buttons and data
+**The Token Source Rule.** Frontmatter neutrals are the light values of
+`.layout-clean-flat[data-theme="stripe"]` in `packages/ui/src/app.css`. The
+painted action color is `--primary: oklch(0.54 0.24 293)` from `:root` and
+`[data-theme="stripe"]`, matching `builtinPresets.stripe.light` in
+`packages/core/src/theme.svelte.ts`. The preset menu chip
+`builtinPresets.stripe.color` is `#635bff`. It identifies the preset. It is
+not a second primary, and it must not be copied onto buttons, rings, or links.
+
+Canvas neutrals in that same stripe block are `#f6f9fc`, `#0a2540`,
+`#ffffff`, `#f1f4f8`, `#425466`, and `#e6ebf1`. Success, warning, and danger
+stay on the semantic tokens and are not overridden by the stripe block:
+`--success: oklch(0.55 0.16 151)`, `--warning: oklch(0.7 0.15 75)`,
+`--destructive: oklch(0.58 0.22 27)`. `:root` oklch neutrals are the fallback
+before the stripe layout block applies. Do not mix those fallback neutrals
+with the stripe hex canvas.
+
+Dark mode for the same preset replaces the canvas, not the accent family:
+
+| Token | Dark value |
+| --- | --- |
+| background | `#0f172a` |
+| foreground | `#f1f5f9` |
+| card / popover | `#111c2e` |
+| muted | `#18263b` |
+| muted-foreground | `#9aa9bd` |
+| border | `#26364c` |
+| sidebar | `#101b2d` |
+| primary | `oklch(0.72 0.19 293)` |
+| on-primary | `oklch(0.16 0.02 270)` |
+
+Named color themes (`neutral`, `indigo`, `blue`, `green`, `rose`, `orange`,
+`violet`, `stripe`) replace primary, ring, sidebar-primary, and chart-1 only.
+They do not rebuild the neutral ramp.
+
+The grid is a low-contrast canvas texture only; buttons and data
 surfaces remain solid, and gradients are not used to communicate status. The
 runtime names for the shared depth and motion tokens are
 `--svadmin-shadow-control`, `--svadmin-shadow-surface`,
@@ -376,6 +417,24 @@ feedback use shared components and semantic tokens. Layout presets may adjust
 density and composition, but they must not replace component color, typography,
 focus, or elevation with hard-coded values.
 
+### Shell anatomy
+
+These are the published shells. Compose them. Do not redraw them as generic cards.
+
+| Shell | Contract | Chrome |
+| --- | --- | --- |
+| `Layout` | `data-svadmin-layout`, `data-svadmin-main`, `data-svadmin-sidebar`, `data-svadmin-topbar` | Sidebar and topbar are flat hairline regions. Stripe removes their shadows. Active sidebar items use a 9% primary wash and a 4px bar. |
+| `Sidebar` | `data-svadmin-sidebar`, `.sidebar-menu-item` | System sans at 13px / 500. Section labels are not uppercase. |
+| `AutoTable` | `data-svadmin-table-head`, `data-svadmin-table-row`, `data-svadmin-datatable` | The table is not wrapped in a card. Header labels are 12px / 600, sentence case, `letter-spacing: 0`. Numbers use `tabular-nums`. |
+| `PageToolbar` | `data-svadmin-table-toolbar` | A hairline row (`border-bottom`), transparent, no radius and no surface shadow. |
+| `AutoForm` | `data-svadmin-form-row`, `data-svadmin-form-actions`, `data-svadmin-field-label` | Rows are separated by a hairline. Under the stripe preset, save actions are a footer rule, not a floating card. |
+| `ConfigurationPage`, `SettingsGroup`, `SettingsFieldRow` | `data-svadmin-settings-group` | Unframed. The group header is a bottom border, title at 16px / 600, description in muted text. One page `h1`; nested groups use `h3`. |
+| `MetricBlock` | `data-svadmin-metric-card` | This is the bounded card: 8px radius, hairline border, surface shadow. Do not put it inside another card. |
+| `AuthPageShell`, `LoginPage` | `data-svadmin-auth-page`, `data-svadmin-demo-credentials` | One auth surface. The title stays at 20px / 600. Demo credentials are a divided note inside that surface, not nested tiles. |
+
+`FilterToolbar` (`data-svadmin-filter-toolbar`) owns search and advanced filters.
+Its advanced panel may use a muted fill. That panel is not a second page card.
+
 
 ## Micro-interactions & Motion
 
@@ -476,18 +535,68 @@ Before accepting an AI-generated application page, verify all of the following:
 6. Desktop and mobile screenshots show no overlap, clipping, horizontal scroll,
    or action displacement caused by feedback content.
 
+## Responsive behavior
+
+Breakpoints already in the shell, not a new layout system:
+
+- Sidebar content offset switches at `768px`. Below that, the sidebar does not
+  reserve the 252px or 70px desktop margin.
+- Filter toolbars become a horizontal row at `640px`.
+- Stripe content padding tightens at `48rem`.
+- Auth credential columns stack at `40rem`.
+- Coarse-pointer targets stay at least 44px. Fine-pointer tables may be denser.
+
 ## Do's and Don'ts
 
 - Do keep hierarchy quiet, dense, aligned, and easy to scan repeatedly.
 - Do show loading, empty, error, permission, progress, and mutation feedback.
 - Do preserve visible keyboard focus and at least 44px coarse-pointer targets.
 - Do remove, downgrade, or relocate feedback as soon as its state is resolved.
+- Do use the system sans already set on `body` and the stripe layout rule:
+  `ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`.
 - Don't copy Metronic colors, decorative treatment, or template branding.
 - Don't repeat a success fact across Toast, title, description, banner, badge,
   and table data.
 - Don't use persistent success banners for routine mutations.
+- Don't set `font-family` to Inter, or to any single downloaded face, as the
+  product font. A system stack is the contract.
+- Don't paint marketing gradients, mesh backgrounds, glass, or a purple hero.
+  The only canvas texture is the 40px technical grid at 2% primary on
+  `[data-svadmin-main]` and 4% on the auth page.
+- Don't put muted gray type on a saturated fill. Solid status fills use their
+  foreground token. The tinted `.svadmin-product-status` badge mixes the status
+  color into `--foreground` and keeps a neutral card base.
+- Don't use cards inside cards, uppercase tracked labels, bounce easing, or
+  make every section a floating card.
 - Don't use decorative gradients, glow, glassmorphism, negative letter spacing,
   or blanket `!important` overrides as the default product language. A subtle
   two-line grid is allowed on the work canvas because it is part of the current
   Stripe-inspired reference direction.
-- Don't use cards inside cards or make every section a floating card.
+
+## Agent prompt guide
+
+Read `PRODUCT.md` for who this product is, then follow this file for pixels.
+`DESIGN.md` wins visual conflicts. `PRODUCT.md` wins product boundaries.
+
+When generating a page, start from the shell table above and the page-family
+matrix. Use semantic tokens (`--background`, `--foreground`, `--card`,
+`--primary`, `--border`, `--muted-foreground`, `--success`, `--warning`,
+`--destructive`). Do not introduce a parallel palette.
+
+Quick light reference for the default stripe + clean-flat preset:
+
+- Canvas `#f6f9fc`, ink `#0a2540`, surface `#ffffff`, hairline `#e6ebf1`.
+- Action `oklch(0.54 0.24 293)` on `oklch(0.99 0 0)`. Chip only: `#635bff`.
+- Body 14px / 400 / 1.5. Page title 20px / 600 / 1.3. Labels 13px / 500.
+- Radius 8px on controls and bounded surfaces. Spacing 4 / 8 / 16 / 24 / 32.
+- Focus: 2px solid `--ring`, offset `--svadmin-focus-offset` (2px).
+
+Reject the result when the first viewport has nested cards, a gradient hero,
+Inter as the only font, gray text on a colored button, or the same fact repeated
+in a banner and the data below it.
+
+Do not add `npx impeccable detect` to CI. The UI workflow already builds
+packages and checks browser contracts. A default detector run flags intentional
+admin choices (the Stripe accent, the technical grid, compact tables) and would
+need a large ignore list. Use that detector locally only as a hint, and keep
+this file as the authority when a finding conflicts with the tokens above.

package/guidance/PRODUCT.md

@@ -0,0 +1,29 @@
+# Product-first generation rules
+
+svadmin generates an admin application from business decisions, not from a raw resource list. Read this file before turning an API, database schema, or feature request into UI.
+
+## Decision order
+
+1. Write the product brief: primary outcome, audience, constraints, non-goals, and assumptions.
+2. List the real workflows in actor language. Each core workflow needs a trigger, goal, steps, success criteria, exceptions, priority, and frequency.
+3. Register resources as data contracts. A resource can be contextual or internal; it does not automatically become a page or menu item.
+4. Define actions with an owning workflow and role visibility.
+5. Define surfaces by purpose. Keep one primary action per surface, declare empty/loading/error/forbidden/success states, and move secondary actions into context or More.
+6. Define menu nodes last. Every node should point to a workflow, resource, or surface and declare the roles that need it.
+
+## Menu policy
+
+There is no fixed menu-count limit. A small product may need one entry; a large operational product may need many. Do not delete business-required entries to satisfy an arbitrary count. Use role visibility, workflow frequency, placement, grouping, and contextual entries to keep the navigation legible. Backend authorization remains authoritative; menu visibility is only a UI hint.
+
+## CLI review loop
+
+Store the plan as JSON using schema version `product/v1`, then run:
+
+- `svadmin vibe review ./svadmin.product.json` to report orphan resources, unserved workflows, unknown references, missing states, and dense surfaces.
+- `svadmin vibe plan ./svadmin.product.json --role operator` to inspect the role-specific menu and generated page plans.
+
+Fix product review errors before generating Svelte markup. Warnings are review prompts, not automatic page deletion rules.
+
+## Visual acceptance
+
+Generated pages must have one clear purpose, one dominant next action, and an explicit state contract. Prefer the existing `@svadmin/ui` page families and semantic tokens. Inspect long labels, dense tables, empty results, denied permissions, failures, and mobile layouts before accepting the result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/create",
-  "version": "0.40.2",
+  "version": "0.41.0",
   "description": "Scaffolding tool for svadmin projects",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "@types/node": "^26.4.0",
     "@types/prompts": "^2.4.9",
     "typescript": "^7.0.2",
-    "@svadmin/core": "^0.60.0"
+    "@svadmin/core": "^0.61.0"
   },
   "keywords": [
     "svadmin",

package/scaffold-manifest.json

@@ -10,10 +10,10 @@
     "check": "svelte-check --tsconfig ./tsconfig.json"
   },
   "dependencies": {
-    "@svadmin/core": "^0.60.0",
-    "@svadmin/app": "^0.2.3",
-    "@svadmin/ai-elements": "^0.11.1",
-    "@svadmin/ui": "^0.83.1",
+    "@svadmin/core": "^0.61.0",
+    "@svadmin/app": "^0.2.4",
+    "@svadmin/ai-elements": "^0.11.2",
+    "@svadmin/ui": "^0.84.0",
     "typebox": "^1.3.34",
     "@tanstack/svelte-query": "^6.1.48",
     "@lucide/svelte": "^1.35.0"
@@ -42,76 +42,76 @@
         "graphql": "^16.8.0"
       },
       "simple-rest": {
-        "@svadmin/simple-rest": "^0.12.4",
+        "@svadmin/simple-rest": "^0.12.5",
         "@refinedev/simple-rest": "^6.0.1"
       },
       "supabase": {
-        "@svadmin/supabase": "^0.19.1",
+        "@svadmin/supabase": "^0.19.2",
         "@supabase/supabase-js": "^2.112.4",
         "@refinedev/supabase": "^6.0.2"
       },
       "graphql": {
-        "@svadmin/graphql": "^0.12.4",
+        "@svadmin/graphql": "^0.12.5",
         "@refinedev/graphql": "^8.0.1",
         "graphql-request": "^7.4.0",
         "graphql": "^16.8.0"
       },
       "rest": {
-        "@svadmin/rest": "^0.2.3",
+        "@svadmin/rest": "^0.2.4",
         "@refinedev/rest": "^2.1.1",
         "@nestjsx/crud-request": "^5.0.0-alpha.3"
       },
       "airtable": {
-        "@svadmin/airtable": "^0.12.4",
+        "@svadmin/airtable": "^0.12.5",
         "@refinedev/airtable": "^5.0.1"
       },
       "appwrite": {
-        "@svadmin/appwrite": "^0.11.4",
+        "@svadmin/appwrite": "^0.11.5",
         "appwrite": ">=26.2.0",
         "@refinedev/appwrite": "^8.0.1"
       },
       "directus": {
-        "@svadmin/directus": "^0.11.4"
+        "@svadmin/directus": "^0.11.5"
       },
       "drizzle": {
-        "@svadmin/drizzle": "^0.14.1",
+        "@svadmin/drizzle": "^0.14.2",
         "drizzle-orm": "^1.0.0-rc.1",
         "refine-sqlx": "^0.10.3"
       },
       "elysia": {
-        "@svadmin/elysia": "^0.14.4",
+        "@svadmin/elysia": "^0.14.5",
         "elysia": ">=1.4.30",
         "@elysiajs/eden": ">=1.4.9"
       },
       "firebase": {
-        "@svadmin/firebase": "^0.12.4"
+        "@svadmin/firebase": "^0.12.5"
       },
       "hasura": {
-        "@svadmin/hasura": "^0.12.4",
+        "@svadmin/hasura": "^0.12.5",
         "@refinedev/hasura": "^7.0.1",
         "graphql-request": "^7.4.0"
       },
       "medusa": {
-        "@svadmin/medusa": "^0.12.4",
+        "@svadmin/medusa": "^0.12.5",
         "@refinedev/medusa": "^5.0.0"
       },
       "nestjs-query": {
-        "@svadmin/nestjs-query": "^0.12.4",
+        "@svadmin/nestjs-query": "^0.12.5",
         "@refinedev/nestjs-query": "^5.0.0"
       },
       "nestjsx-crud": {
-        "@svadmin/nestjsx-crud": "^0.12.4",
+        "@svadmin/nestjsx-crud": "^0.12.5",
         "@refinedev/nestjsx-crud": "^6.0.1"
       },
       "pocketbase": {
-        "@svadmin/pocketbase": "^0.13.1",
+        "@svadmin/pocketbase": "^0.13.2",
         "pocketbase": ">=0.28.0"
       },
       "sanity": {
-        "@svadmin/sanity": "^0.11.4"
+        "@svadmin/sanity": "^0.11.5"
       },
       "strapi": {
-        "@svadmin/strapi": "^0.12.4",
+        "@svadmin/strapi": "^0.12.5",
         "@refinedev/strapi-v4": "^7.0.1"
       }
     },