Folio
The White Reset
Monochrome design system — CSS tokens and accessible React primitives
Documentation · 中文 · Report Issue
Features
- 52 React primitives — Radix underneath wherever behaviour is involved,
cmdk for the command palette, react-day-picker for the calendar. No router, no state library, no CSS-in-JS.
- 15 data-visualisation primitives, from a separate entry (
@misoto22/folio/charts) so an app that renders a Badge does not pay for a rendering engine — and four of them (Heatmap, Sparkline, BarList, BigNumber) need no engine at all. Texture carries series identity and the grey ramp supports it, which is what keeps two series apart in greyscale print, under forced colours and for a colour-blind reader. Every chart is announced, has an empty state, and puts its rows in a table.
- 11 diagram components, from a third entry (
@misoto22/folio/diagrams) — five server-rendered figures for architecture, workflow, sequence, data-flow and lifecycle, plus the chrome to explore one. They read archify's JSON schemas, so a specification authored for that tool renders here in this system's own monochrome terms. The kind of a node is carried by a drawn sigil AND a word, so it survives greyscale.
- Two axes, both attributes (
data-mode, data-density) — light and dark, comfortable and compact. Set either on any container and everything below it follows.
- 178 tokens, machine-readable (
@misoto22/folio/tokens) — every token with its light value, dark value, category and comment, as JSON and as a typed module.
- RTL with no second stylesheet — every component is written in logical properties, so
dir="rtl" mirrors the system. A test fails the build on a physical one.
- Accessibility the build enforces —
coverage.test.ts fails when a component has no fixture, so "every component is checked" is a property rather than a claim.
Tech Stack
Project Structure
The canonical tokens are CSS and TypeScript in src. Everything else — the
compiled stylesheet, the JSON, the site's swatches and token tables — is built
from them, which is why dist/ is never edited by hand.
flowchart LR
A["styles/tokens.css<br/>tokens/brand.ts"] --> B["packages/design<br/>build"]
B --> C["dist/<br/>JS · CSS · tokens.json"]
C --> D["apps/docs"] & E["consuming apps"]
packages/design/
├── src/
│ ├── components/ 52 primitives, one directory each
│ ├── charts/ 20 primitives + their shared lib/
│ ├── diagrams/ 11 more + their shared lib/
│ ├── styles/ tokens.css · semantic.css · keyframes.css
│ ├── tokens/ brand.ts — hex mirrors for non-CSS surfaces
│ └── lib/ cn, control base, overlay container, svg export
└── scripts/ font vendoring, portable CSS, token emit, size budget
apps/docs/
├── src/content/ the hand-written part: grouping and summaries
├── src/generated/ parsed out of the package at build time
├── src/templates/ whole screens, not single components
└── e2e/ axe · keyboard · RTL · density, in a browser
docs/ component conventions · the site · releasing
Install
pnpm add @misoto22/folio
Prerequisites — Node.js 24+, React 19 and React DOM 19 as peers
// Once, at your app root — the compiled stylesheet carries the tokens, the
// utilities the components use, and the vendored faces.
import '@misoto22/folio/styles.css'
import { Button, Field, Input } from '@misoto22/folio'
Take the portable layers instead and skip a second copy of the utilities:
@import 'tailwindcss';
@import '@misoto22/folio/tokens.css'; /* primitives */
@import '@misoto22/folio/semantic.css'; /* roles */
@import '@misoto22/folio/keyframes.css'; /* motion */
@source '../node_modules/@misoto22/folio/dist';
@custom-variant dark (&:is([data-mode='dark'] *));
[!NOTE]
The mode is an attribute rather than a class so an inline script can write it
before the first paint and never flash the wrong theme. Density is the only
other axis: 44px targets by default (what WCAG 2.5.5 asks for), 36px compact
(which clears 2.5.8 but not 2.5.5, so it is for a dense desktop tool).
Development
git clone https://github.com/Misoto22/folio.git
cd folio
pnpm install
pnpm build:design # the docs site reads the package from dist
pnpm dev # → http://localhost:4023
Prerequisites — Node.js 24+, pnpm 11+
pnpm lint ESLint, both workspaces
pnpm typecheck tsc --noEmit, both workspaces
pnpm test vitest, both workspaces
pnpm build the package, then the site
pnpm --filter @misoto22/folio-docs test:e2e axe + keyboard, in a browser
pnpm --filter @misoto22/folio check:size size and tree-shaking budget
The site's Tailwind compiles from the package's source, so styling changes are
live; a changed component needs pnpm build:design before pnpm dev sees it.
Documentation
ui.misoto22.com is the gallery, the foundations, the
principles and the templates, in English and — under /zh —
in Chinese. The engineering notes live in docs/: component
conventions, the documentation
site, releasing.
Nothing about the library is written twice. Prop tables are parsed out of the
package's TypeScript at build time, token tables out of the CSS, and every
example is a real .tsx module that the page renders and that the code block
beneath it was read from — so a preview cannot drift from the code printed under
it. The API reference is translated too, and each Chinese entry records a
fingerprint of the English it was made from: editing a doc comment in the
package fails the build until the translation beside it is updated, rather than
quietly telling a Chinese reader something that stopped being true.
The site also serves itself to a reader that does not render CSS —
/llms.txt as an index,
/llms-full.txt inline, and one file
per component. Not a scrape of the HTML: the same generated data the pages read,
arranged for one sequential pass.
Release
The pull-request title is the release. Write it as a Conventional Commit and
merge it; release-please reads the subjects that reached main, opens a
release pull request holding the version bump and the changelog, and merging
that tags, publishes the GitHub Release and sends the package to npm.
feat(button): add a loading state → next minor
fix(sidebar): stop the rail collapsing → next patch
feat(tokens)!: drop the m22 prefix → next major
Below 1.0.0 this package is still treated as if SemVer's guarantees held: a
removed export, a changed default, or a token that no longer resolves is a
major. See docs/releasing.md.
Deployment
Two entry points, named after what triggers them, over two shared definitions:
pr-title.yml on: pull_request_target → pr-title
pr.yml on: pull_request → verify → browser
release.yml on: push to main → verify → browser → deploy · release → publish
↑ ↑ ↑ ↑
verify.yml · browser.yml Cloudflare release- npmjs
please
verify.yml is lint, typecheck, tests, both builds and the size and
tree-shaking budget; browser.yml is the axe, keyboard and RTL suite against
the built export. Both are workflow_call definitions, so a pull request and a
release are gated by the same file rather than by two that drift — and nothing
deploys or publishes that they have not both passed.
deploy uploads the exact directory verify built to the folio-design
Cloudflare Pages project and smoke-tests the deployed routes;
ui.misoto22.com is a proxied CNAME onto it. release opens and maintains the
release pull request, and publish sends the tarball to npmjs when that pull
request merges — see docs/releasing.md.
pr-title.yml calls the fleet's shared Conventional Commit check. It is its own
file because it triggers on pull_request_target, which a fork's pull request
needs and which nothing that checks out a branch may use.
What this repository does not own
The primitives serve both misoto22.com and its admin console, and neither host's
routes, data access or business logic lives here. A component that needs to know
about a route, a session or a database has been built in the wrong repository.
This package is also the source for the misoto22 Claude Design project — run
the /design-sync skill from the repository root to push verified components up,
after the local gates pass. See .design-sync/NOTES.md.
Website compositions
@misoto22/folio/website adds 17 composition families for complete editorial
websites. Presentation and accessible interactions live in the package; content,
router adapters and backend integrations remain with each consumer. Import
website.css beside styles.css or the portable layers — styles.css does not
include it — and add website-base.css when the whole page is a website, for its
body type, heading margins and site-wide focus ring. The offline CLI documents
every family and public part.
