Designs
Your app’s screens (lists, forms, detail pages, the sidebar) come from @strutvane/ui. How they look comes from a separate design package. You pick one when you create the app, adjust it in one small file you own, and can swap it for another design later without touching a single screen.
What a design is
Section titled “What a design is”A Strutvane admin is split into two parts:
| Part | Package | What it holds |
|---|---|---|
| Behaviour | @strutvane/ui |
The auto CRUD screens, tables, forms, filters, the sidebar, the command palette, keyboard shortcuts and accessibility. No colours or layout chrome of its own. |
| Look | a design package, such as @strutvane/design-crisp |
Tokens (named values for colour, type, spacing, radius, shadow and density, in light and dark), fonts, the shell (sidebar, top bar and the sign-in layout), component skins, the chart palette, empty-state illustrations, and its own DESIGN.md. |
Charts are a separate package, @strutvane/charts, not part of @strutvane/ui. When it’s installed, it takes its palette from the design.
A token is a named setting, written as a CSS variable such as --radius, that every component reads instead of a hard-coded value. Change the token and every button, card and input follows.
Why the split: the screens never mention a colour, so a design can change everything you see without changing what any screen does. That is also why switching designs later is one command.
The two designs
Section titled “The two designs”Each design is named with one short word describing its feel, so you choose by look:
| Design | Package | Feel | Good for |
|---|---|---|---|
| Crisp (default) | @strutvane/design-crisp |
Clean and minimal, quiet colours, dense readable tables, business first | Back office, ERP, finance, B2B SaaS admin |
| Vivid | @strutvane/design-vivid |
Colourful, soft-shadow cards, gradient charts, roomier spacing | Analytics, customer-facing dashboards, product consoles |
Both have a light and a dark mode and an accent colour of their own.
Choosing a design when you create the app
Section titled “Choosing a design when you create the app”The smallest example: create an app and press Enter on the design question.
npm create strutvane@latest my-appWhat you’ll see (the design is one of the Recommended questions, asked for full apps only):
? Which design should your app use?❯ Crisp Clean, minimal and business-first (recommended) Vivid Colourful, modern dashboardsThe review screen lists your pick as Design crisp (@strutvane/design-crisp), and the final “Ready” box gains two lines:
Design crisp (@strutvane/design-crisp) Restyle: resources/ui/theme.css, or switch: node strut design:use vividChoosing without questions
Section titled “Choosing without questions”Every question has a flag. --design takes crisp or vivid; --yes (and CI, or no terminal) picks Crisp:
npm create strutvane@latest my-app -- --design vivid --yesRemember the -- before the installer’s options: without it, npm keeps the flags for itself. See Installation.
API-only apps have no design
Section titled “API-only apps have no design”The design question is asked only when you build a full app (API plus admin UI). An API-only project has no screens to style, so --design with --stack api is refused:
These options do not work together: - an API-only project has no UI to style: drop --design, or use --stack full
Run with --help to see every option.What the installer writes
Section titled “What the installer writes”Two files, each with one job.
config/ui.ts says which design package styles the UI, plus the other UI answers:
// The look of the React UI. The screens come from @strutvane/ui (behaviour only); the design// package @strutvane/design-crisp gives them their colours, fonts, layout shell and component styles.//// Switch to another design later with one command (it swaps the package and updates this file):// node strut design:use vivid// Designs available: crisp, vivid.//// Your own brand colour, font or corner radius? Do not edit the design package: put your overrides// in resources/ui/theme.css. That file is yours, so it stays when you switch or upgrade the design.export default { design: 'crisp', // Light, dark, or follow the system setting (each user can still switch in the app). appearance: "system", // UI languages; add more any time (translations live in resources/ui/lang). languages: ["en"], // Installable app (PWA): home-screen icon and an offline page. pwa: false, // Live updates: tables refresh when someone else changes the data. liveUpdates: false,}resources/ui/theme.css is your own override file. Every line in it starts commented out, so a new app looks exactly like the design you picked. The installer also adds the design package to dependencies in package.json.
Why two files: switching design rewrites one line in config/ui.ts, so a brand colour you set in theme.css survives every switch and every design upgrade.
Restyling with theme.css
Section titled “Restyling with theme.css”theme.css loads after the design, so whatever you set there wins. Uncomment a line and change its value.
You restyle through four public override tokens, the same in every design:
| Token | What it changes |
|---|---|
--brand-hue |
The brand colour (buttons, links, focus rings, the active menu item) |
--font-sans |
The font of the whole UI |
--radius |
How round the corners of cards, inputs and buttons are |
--density |
How much room tables, forms and menus take |
Each design maps these four onto its own internal tokens. Crisp, for example, maps them onto its --accent*, --font-ui and --shape-* tokens. Set the public token, never a design’s internal one, and your override works in every design.
Your brand colour
Section titled “Your brand colour”The brand colour drives buttons, links, focus rings and the active menu item. It is a hue: a position on the colour wheel from 0 to 360 (250 is blue, 150 green, 25 red). The design derives every shade from it and keeps text readable for any hue.
:root { --brand-hue: 150;}What you’ll see: after the page reloads, buttons, links and the active sidebar item turn green, in light and dark mode.
Font and corners
Section titled “Font and corners”A typical override sets the brand, a font and rounder corners together:
:root { --brand-hue: 25; --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif; --radius: 0.75rem;}What you’ll see: red accents, Inter everywhere, and softer corners on cards, inputs and buttons. A web font must be loaded first, in resources/ui/index.html, or be installed on the computer.
Different values in dark mode
Section titled “Different values in dark mode”The dark theme is switched on with a dark class on the page, so dark-only overrides go under .dark:
:root { --brand-hue: 250;}
.dark { --brand-hue: 270;}What you’ll see: blue accents in light mode and violet in dark mode.
Light, dark or the system setting
Section titled “Light, dark or the system setting”Installer question 31 (“Default appearance?”) sets the starting mode: follow the system (default), light or dark. It’s saved in config/ui.ts as appearance. Each user can still switch in the app, and their choice is remembered in their browser.
npm create strutvane@latest my-app -- --appearance dark --yesSwitching to another design
Section titled “Switching to another design”node strut design:use vividWhat it will do: install @strutvane/design-vivid with npm, and change design: 'crisp' to design: 'vivid' in config/ui.ts. Your screens don’t change, because they only use @strutvane/ui components, and your theme.css stays as it is.
With Docker, type the command on your computer as usual: it runs inside the app container, like every node strut command. See Docker.
Taking full control: ejecting
Section titled “Taking full control: ejecting”When overrides aren’t enough (a different sidebar layout, your own sign-in page), copy the whole design into your project:
node strut design:ejectWhat it will do: copy the design’s source into resources/ui/design/. From then on that code is yours (Strutvane calls this level L3: you own the files and edit them freely), and design upgrades no longer reach it.
The design contract
Section titled “The design contract”Every design, first-party or from the community, is built with defineDesign() from @strutvane/ui and must pass its test kit, designConformance():
- every slot (a named place a design fills, such as the sidebar or the sign-in layout) is provided;
- every public override token (
--brand-hue,--font-sans,--radius,--density) is mapped, and setting it really changes the rendering; - every token pair meets WCAG AA contrast (the accessibility standard for readable text) in both themes;
- there are no hard-coded colours;
- axe (an automatic accessibility checker) finds 0 violations on the reference screens;
- there is no sideways scrolling on a 375-pixel-wide phone screen.
What the mockups proved
Section titled “What the mockups proved”These are mockups (clickable prototypes with sample data), not the released packages:
| Crisp mockup (spike 19) | Vivid mockup (spike 17) | |
|---|---|---|
| Screens and states | 17, light and dark | 19, light and dark |
| Tests | 162 | 63 |
| Contrast | 32 text pairs ≥ 4.5:1 and 5 non-text pairs ≥ 3:1, per theme, computed from the tokens | 31 text pairs per theme, at every accent hue in 15° steps |
| axe | 0 violations on dashboard, list and form, both themes | 0 violations on dashboard, list and form, both themes |
| Phone width | no horizontal overflow at 375 px on every route | no horizontal overflow at 375 px on every route |
| Hard-coded colours | none (tested) | none (tested) |
One known gap in Crisp: input outlines are below 3:1 against the page, a deliberate quiet-UI trade-off. Inputs are identified by their label, fill and focus ring.
More designs later
Section titled “More designs later”- First-party designs are named
@strutvane/design-<name>; community designsstrutvane-design-<name>. - A design appears in the installer once it is published and passes
designConformance(). The installer reads the list from data, so a new design needs no installer change. - The shelved Glass direction (spike 18) is the first candidate.
Common mistakes
Section titled “Common mistakes”My change to the design package disappeared
Section titled “My change to the design package disappeared”Why: you edited a file under node_modules/@strutvane/design-crisp/. That folder belongs to npm: npm install, an upgrade or design:use replaces it.
Fix: put the override in your own file instead:
:root { --brand-hue: 150;}My override in theme.css does nothing
Section titled “My override in theme.css does nothing”Why: usually one of two things. The line is still commented out (/* --brand-hue: 250; */), or you set a token that isn’t one of the four public override tokens, such as Crisp’s internal --accent.
Fix: remove the /* and */ around the line, use --brand-hue, --font-sans, --radius or --density, and reload the page. See Restyling with theme.css.
The installer refuses --design
Section titled “The installer refuses --design”These options do not work together: - an API-only project has no UI to style: drop --design, or use --stack full
Run with --help to see every option.Why: you asked for an API-only project, which has no screens.
Fix: drop --design, or build a full app:
npm create strutvane@latest my-app -- --stack full --design vivid --yes--design gets “is not a choice”
Section titled “--design gets “is not a choice””The command line has problems: - --design "glass" is not a choice. Use one of: crisp, vivid
Run with --help to see every option.Why: only published designs that pass conformance are offered. Glass is shelved.
Fix: pick crisp or vivid.
My dark-mode colour also changed light mode
Section titled “My dark-mode colour also changed light mode”Why: you put the dark value under :root, which applies to both themes.
Fix: put dark-only values under .dark:
.dark { --brand-hue: 270;}Next steps
Section titled “Next steps”- Frontend: how the React UI is organised.
- Auto CRUD & UI: the screens a design styles.
- Charts: charts take their palette from the design’s tokens.
- Installation: every installer question, including the design.