Design system definition

A Bedrock Flows design system is a folder of plain CSS + Nunjucks + JSON, frozen under a single version name. A version is a snapshot of tokens + components; prototypes reference one by name. Each version is self-contained — it never reaches across to another version.

Folder layout

design-system/
  <version>/                       one folder per DS version
    global.css                     tokens + base + uncomponentized rules
    style.css                      GENERATED bundle — do not edit
    ds.json                        version metadata (incl. intendedViewport)
    assets/                        fonts, logos, avatars, marker shapes, etc.
    foundations/                   non-interactive references (showcase-only)
      colors/  icons/  surfaces/  typography/
    components/                    interactive UI
      <component-name>/
        component.css              source of truth for this component's CSS
        macro.njk                  Nunjucks macro — emits canonical markup
        variants.json              prop sets the variant generator renders
        <variant>.html             GENERATED standalone variant — do not edit
    utilities/                     layout primitives (app-shell, stack, …)
      <utility-name>/
        component.css
        macro.njk                  optional
        variants.json              optional
        <variant>.html             generated

What each top-level piece is:

• global.css — design tokens (CSS custom properties), base element styles, and any rules that aren't tied to a single component. This is where you change the brand.
• style.css — GENERATED. Don't edit it. It's the concatenation of global.css plus every component's component.css, produced by the build.
• ds.json — version metadata. Notably intendedViewport, the resolution range this design system is designed for (see Viewport ranges).
• foundations/ — showcase-only references (colors, typography, surfaces, icons). These may have handwritten *.html without a macro.njk / variants.json; the generator skips folders that don't have both.
• components/ and utilities/ — the per-component contract (see Making your first component).

How a prototype picks a version

A flow declares which version it consumes in its meta.json:

{ "id": "F-001", "name": "...", "dsVersion": "ziptility-v1" }

URLs follow the folder name — /ds/ziptility-v1/storybook/, /ds/ziptility-v1/style.css, and so on.

Naming a version

The folder name is an arbitrary string; convention is <theme>-<version>, e.g. ziptility-v1, jungle-v1, ziptility-v2. A version is a frozen snapshot — once flows reference it, treat its contents as stable.

Adding a new version

Copy an existing version's folder and re-theme it by editing tokens in global.css. The components carry over unchanged:

cp -r design-system/ziptility-v1 design-system/<new-name>
# edit <new-name>/global.css to swap tokens (brand color, fonts, etc.)
# component.css / macro.njk / variants.json carry over unchanged
npm run build

The dashboard, storybook builder, and bundle compiler auto-detect the new folder.

Versions are self-contained

Components in one version must never reference paths inside another version. Each version is its own complete snapshot — so an old flow keeps rendering exactly as it did when it was frozen, no matter what changes in a newer version.