@svadmin/create 0.40.1 → 0.40.3

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`,
@@ -300,10 +341,10 @@ Use `PagePattern` for custom business compositions that do not fit those
 resource routes. It supplies layout only, not querying, permissions, form
 submission, or loading/error handling:
 
-- `list`: compact title, toolbar, table/list content, and list empty states.
+- `list`: comfortable title, toolbar, table/list content, and list empty states.
 - `form`: narrow reading width, comfortable grouped fields and a single save area.
 - `detail`: read-only summary and related content.
-- `workspace`: primary work area plus an optional secondary panel.
+- `workspace`: comfortable primary work area plus an optional secondary panel.
 - `dashboard`: wide layout with optional metrics and secondary context.
 
 Optional `secondary` content renders beside the primary content for every kind.
@@ -357,7 +398,10 @@ cards, repeated title bars, or unrestricted two-column fields.
   persistence request succeeds; preserve edits after failure.
 - Separate initial-empty content from filtered-no-results content. Offer
   creation only when permitted, and clearing filters only when filters exist.
-- Use compact density for operational work and comfortable density for forms.
+- Page patterns default to comfortable density so generated and custom pages
+  have a consistent baseline. Use compact density explicitly for operational
+  work that prioritizes scanning speed; use comfortable density for forms and
+  general-purpose pages.
 - Reference `packages/ui/stories/ConfigurationExample.svelte` in the SVAdmin
   source for a working composition; its save action is in-memory demo state,
   not a persistence implementation.
@@ -373,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
 
@@ -473,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/create",
-  "version": "0.40.1",
+  "version": "0.40.3",
   "description": "Scaffolding tool for svadmin projects",
   "type": "module",
   "bin": {

package/scaffold-manifest.json

@@ -13,7 +13,7 @@
     "@svadmin/core": "^0.60.0",
     "@svadmin/app": "^0.2.3",
     "@svadmin/ai-elements": "^0.11.1",
-    "@svadmin/ui": "^0.83.0",
+    "@svadmin/ui": "^0.83.2",
     "typebox": "^1.3.34",
     "@tanstack/svelte-query": "^6.1.48",
     "@lucide/svelte": "^1.35.0"