Flow Design System
The Flow Design System is a claude.ai Design System artifact: Flow's tokens, faces, rules and one live card per shared component. Agents read it before they build a screen, and a person reviews a component there by commenting on its card. The repository is the source: the artifact's files are generated from it, never edited by hand.
server/theme/themes.js ─┐
server/ui/flow.css ─────┤
server/ui/kit.js, ──────┼─► npm run design-system ─► .artifacts/design-system/project/
view-bar.js, … │ (scripts/design-system/build.mjs) │
design-system/ ─────────┘ ▼
README.md, components/<Card>/ Flow Design System artifact
(published after a merge)
What is generated
| File in the artifact | From |
|---|---|
tokens.json |
Every --t-* colour of Harbour and Meridian, light and dark (four themes), radii, the shadow, type styles, the font files |
fonts/*.woff2 |
The fontsource packages Flow serves (latin, variable weight) |
components/bundle.js |
The real shared modules (server/ui/kit.js, view-bar.js, bulk-bar.js, tip.js, custom-fields.js, job-change.js, sidecar.js, columns.js) bundled by esbuild as window.FlowDesignSystem (scripts/design-system/entry.js) |
components/bundle.css |
server/ui/flow.css, every family's --t-* tokens as [data-theme="<family>-<mode>"], and the Lucide icons the app names, inlined |
components/<Card>/ |
design-system/components/<Card>/: preview.html (line 1 the @dsCard marker), README.md (first sentence the summary, a Code: line naming the code) and mobile.json (the phone rules) |
components/Themes/ |
Generated: every family, light and dark |
README.md, assets/ |
design-system/README.md, design-system/assets/ |
project/design-system.json (the index) is not generated: it is written at
publish, and keeps what a person changed on the page. The logo is an upload
in the artifact's asset store (Logos group).
The rule for a pull request
A pull request that adds or changes a shared component changes its card in
design-system/components/ too. test/design-system.test.js fails when an
export of a shared module (kit.js, view-bar.js, bulk-bar.js, tip.js,
job-change.js, sidecar.js, columns.js) has no card naming it, when a card has no README or marker,
when a visible card has no mobile.json, or when the build writes something the artifact cannot read.
Phone rules
Read the card's mobile.json before building. It names the picked direction,
the layout at phone, tablet and desk, the touch size, the page overflow rule,
and the screens that use the component. The build shows that card in a phone
frame with the rules in a table. The shared component reads the same file
through server/ui/mobile.js (rule, applyPhoneRule, WIDTHS): the three
widths are 639/640 and 1023/1024, and a flag such as a column's phone slot
comes from the card, not from a second copy. The phone suite asserts those
rules on each listed screen (docs/MOBILE_TESTS.md).
A card calls window.FlowDesignSystem.<name>, so it shows what the app draws.
A card for CSS only (Button, Pager, Tabs) uses the real classes; it says
"static card" in its README.
Publishing
CI cannot write to claude.ai, so an agent publishes after a merge that
changed design-system/, server/ui/flow.css, server/theme/ or a shared
module:
npm run design-system.- Read the artifact's
project/design-system.json. - Publish
.artifacts/design-system/project/to the artifact URL above with the Artifact tool (root=.artifacts/design-system, every changed file), and the index last, withlastChange{ by, at, via: "GitHub · arcforgelabs/flow@<sha>", note }.
A file a person changed on the page is kept unless the repository changed it too; tell them which.
Review
A comment on a card, sent to Claude, wakes the session that watches the artifact. That session fixes the component in the repository (and its card), opens a pull request, and republishes after the merge.
Locally
npm run design-system [out-dir] writes the files (default
.artifacts/design-system, ignored by git). Each card is a small HTML file:
open it with components/bundle.css and components/bundle.js loaded to see
it as the artifact does.