Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Designs

View as Markdownllms.txt

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.

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.

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.

The smallest example: create an app and press Enter on the design question.

Terminal window
npm create strutvane@latest my-app

What 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 dashboards

The 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 vivid

Every question has a flag. --design takes crisp or vivid; --yes (and CI, or no terminal) picks Crisp:

Terminal window
npm create strutvane@latest my-app -- --design vivid --yes

Remember the -- before the installer’s options: without it, npm keeps the flags for itself. See Installation.

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.

Two files, each with one job.

config/ui.ts says which design package styles the UI, plus the other UI answers:

config/ui.ts
// 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.

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.

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.

resources/ui/theme.css
: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.

A typical override sets the brand, a font and rounder corners together:

resources/ui/theme.css
: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.

The dark theme is switched on with a dark class on the page, so dark-only overrides go under .dark:

resources/ui/theme.css
:root {
--brand-hue: 250;
}
.dark {
--brand-hue: 270;
}

What you’ll see: blue accents in light mode and violet in dark mode.

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.

Terminal window
npm create strutvane@latest my-app -- --appearance dark --yes
Terminal window
node strut design:use vivid

What 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.

When overrides aren’t enough (a different sidebar layout, your own sign-in page), copy the whole design into your project:

Terminal window
node strut design:eject

What 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.

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.

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.

  • First-party designs are named @strutvane/design-<name>; community designs strutvane-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.

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:

resources/ui/theme.css
:root {
--brand-hue: 150;
}

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.

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:

Terminal window
npm create strutvane@latest my-app -- --stack full --design vivid --yes
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:

resources/ui/theme.css
.dark {
--brand-hue: 270;
}
  • 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.