# misoto22 design

> A monochrome design system for software, writing and photography:
> portable CSS tokens and accessible React primitives. Paper ground,
> near-black mark, and status is the only chroma in the file.

Install: `npm install @misoto22/design`. Styles: `import '@misoto22/design/styles.css'`.
Every component is a client-safe React 19 component; the token layer is
plain CSS and works without React at all.

## The laws

1. **The ground is paper.** White, not off-white, and the same white on every surface. There is no card colour, no elevated panel tint, and no "subtle background" that quietly becomes a second ground.
   Rules out: A card that separates itself from the page by being a different shade of white.
2. **A shadow is never blurred.** The system has no light source, so it has no elevation ramp. Depth is a hairline, a change of ground, or a hard ink offset with no blur radius.
   Rules out: box-shadow: 0 2px 8px rgba(0,0,0,.08) — and the whole scale it belongs to.
3. **The rule does the work colour would.** Three weights, and each is chosen by what it separates: hairline between rows, edge between blocks, hard under a masthead. A monochrome page has nothing else to divide with.
   Rules out: Five hand-tuned greys, picked per component, that nobody can tell apart.
4. **There are two text steps and nothing lighter.** The floor clears AA on white at 6.7:1. Every step above it is darker. A third, lighter grey is not a design decision available here.
   Rules out: #999 on white, for "secondary" text that half the readers cannot see.
5. **Chroma is bound to state.** Green, amber and red mean succeeded, needs attention, and failed. They are never decorative, and the meaning is always doubled — by an icon, by the words, or by both.
   Rules out: A blue badge because the row needed some colour.
6. **One ladder, and the page owns the top of it.** Five heading steps, fluid between a phone and the full page, and nothing sits above the page title. Two headings that nest must skip a step, or the hierarchy is not readable as one.
   Rules out: A card title on one page that is larger than another page’s own h1.
7. **The accent is ink.** In a monochrome system the single editorial pointer collapses onto the mark. What used to be carried by hue is carried by weight, by an underline, by a filled pill, or by reversal.
   Rules out: A brand hue reintroduced through a link colour or a hover state.
8. **Dark mode is a value swap, not a second palette.** The same token names, different values. That is why a component reads a semantic alias and never a primitive: the alias re-resolves on its own when the mode flips. The two exceptions — type over a photograph, and a foreign brand mark — are documented where they are defined, because their ground is not the theme.
   Rules out: A .dark block in a component’s own stylesheet, freezing one side of the swap.

## Theming

Attributes that re-point tokens the package already defines. No component
reads any of them, and none of them introduces a token.

- `data-chart-palette`: chroma (unset = the neutral series ramp)
- `data-density`: compact (unset = comfortable)
- `data-mode`: dark | light (unset = follows the app)
- `data-motion`: snappy | still (unset = calm)
- `data-radius`: round | sharp (unset = the default radius ladder)
- `data-rules`: firm | quiet (unset = hairline)
- `data-surface`: cool | glass | warm (unset = paper)
- `data-table-density`: compact (unset = comfortable — whatever `data-density` is doing around it)
- `data-type`: bookish | grotesk (unset = editorial)

An unset attribute is the default; nothing is anchored to `:root`, so an
axis set on any element applies to the subtree below it. There is no
`data-accent` attribute — `--accent` is a custom property, re-pointed in CSS.

## When you get it wrong

Some misuse fails silently — a `Field` whose child is a wrapper puts the
label on the box; an icon-only `Button` with no accessible name renders
perfectly and is invisible to a screen reader. The component says so in
development, with the field that caused it and an imperative fix. Each code
is stable, so it is safe to branch on:

- `BUTTON_ICON_ONLY_UNNAMED`
- `FIELD_CONTROL_NOT_LABELLABLE`
- `FIELD_CONTROL_NOT_WIRED`
- `REQUIRED_NAME_BLANK`

## Components

- [Button](https://ui.misoto22.com/components/button/llms.txt): The system’s action, on the same corner as the field beside it.
- [FloatingIconButton](https://ui.misoto22.com/components/floating-icon-button/llms.txt): A round action pinned to a screen corner.
- [Field](https://ui.misoto22.com/components/field/llms.txt): A labelled form row: label, control, and the one message below it — and, in row layout, the settings row.
- [Input](https://ui.misoto22.com/components/input/llms.txt): A single line of text entry.
- [Textarea](https://ui.misoto22.com/components/textarea/llms.txt): Multi-line text entry, resizable vertically only.
- [Select](https://ui.misoto22.com/components/select/llms.txt): A choice from a list, styled the whole way down.
- [NativeSelect](https://ui.misoto22.com/components/native-select/llms.txt): The platform’s own picker, restyled where it can be.
- [Checkbox](https://ui.misoto22.com/components/checkbox/llms.txt): A choice that takes effect when the form is submitted.
- [RadioGroup](https://ui.misoto22.com/components/radio-group/llms.txt): A set of mutually exclusive choices.
- [Switch](https://ui.misoto22.com/components/switch/llms.txt): A setting that takes effect immediately.
- [Combobox](https://ui.misoto22.com/components/combobox/llms.txt): A select you can type into.
- [DatePicker](https://ui.misoto22.com/components/date-picker/llms.txt): A date — or a span of them — chosen from a calendar.
- [Slider](https://ui.misoto22.com/components/slider/llms.txt): A value chosen along a range.
- [ToggleGroup](https://ui.misoto22.com/components/toggle-group/llms.txt): A segmented control: several options, one strip.
- [Tabs](https://ui.misoto22.com/components/tabs/llms.txt): One strip, several panels.
- [Accordion](https://ui.misoto22.com/components/accordion/llms.txt): Disclosure rows that open in place.
- [Breadcrumb](https://ui.misoto22.com/components/breadcrumb/llms.txt): Where you are, as a path.
- [Pagination](https://ui.misoto22.com/components/pagination/llms.txt): Numbered pages, with the middle elided.
- [NavItem](https://ui.misoto22.com/components/nav-item/llms.txt): A row in a sidebar.
- [Collapsible](https://ui.misoto22.com/components/collapsible/llms.txt): One thing that opens, on its own.
- [Dialog](https://ui.misoto22.com/components/dialog/llms.txt): A modal surface: portal, scrim, centred panel.
- [DropdownMenu](https://ui.misoto22.com/components/dropdown-menu/llms.txt): A menu of actions.
- [Tooltip](https://ui.misoto22.com/components/tooltip/llms.txt): A short label on hover and on focus.
- [Popover](https://ui.misoto22.com/components/popover/llms.txt): A panel anchored to a control, holding content you can interact with.
- [Sheet](https://ui.misoto22.com/components/sheet/llms.txt): A panel docked to an edge of the viewport.
- [ContextMenu](https://ui.misoto22.com/components/context-menu/llms.txt): The menu a right-click opens.
- [SearchableMenu](https://ui.misoto22.com/components/searchable-menu/llms.txt): A menu of actions you can type into.
- [Command](https://ui.misoto22.com/components/command/llms.txt): A filterable list of actions — the ⌘K surface.
- [Spinner](https://ui.misoto22.com/components/spinner/llms.txt): The one “working” indicator — a ring, never a shimmer.
- [Skeleton](https://ui.misoto22.com/components/skeleton/llms.txt): The shape of the page, before the page.
- [Progress](https://ui.misoto22.com/components/progress/llms.txt): A bar that fills, or sweeps when the end is unknown.
- [Alert](https://ui.misoto22.com/components/alert/llms.txt): A message about the page, in place.
- [EmptyState](https://ui.misoto22.com/components/empty-state/llms.txt): A collection with nothing in it — yet.
- [ErrorState](https://ui.misoto22.com/components/error-state/llms.txt): A page that could not be shown.
- [Toast](https://ui.misoto22.com/components/toast/llms.txt): A transient confirmation, mounted once near the app root.
- [Badge](https://ui.misoto22.com/components/badge/llms.txt): A count or a state, set in mono so it reads as metadata.
- [Tag](https://ui.misoto22.com/components/tag/llms.txt): A subject label — a topic, a technology, a filter facet — that filters with onClick and is dismissed with onRemove.
- [Kbd](https://ui.misoto22.com/components/kbd/llms.txt): A key on a keyboard, set as one.
- [Avatar](https://ui.misoto22.com/components/avatar/llms.txt): A person, as a circle, with initials until the image lands.
- [StatusDot](https://ui.misoto22.com/components/status-dot/llms.txt): The dot beside a status word.
- [Steps](https://ui.misoto22.com/components/steps/llms.txt): A numbered sequence, as a rail — one thing after another, with a rule through them.
- [StatusPill](https://ui.misoto22.com/components/status-pill/llms.txt): A live state, named: a dot plus an uppercase mono label.
- [LinkArrow](https://ui.misoto22.com/components/link-arrow/llms.txt): The mark on a link that leaves the page.
- [Separator](https://ui.misoto22.com/components/separator/llms.txt): A rule, in the three weights a monochrome page needs — with words in it when the break has something to say.
- [Diagram](https://ui.misoto22.com/components/diagram/llms.txt): A flow or architecture figure, drawn out of the system’s own parts.
- [FigureBand](https://ui.misoto22.com/components/figure-band/llms.txt): A row of counted facts, divided by hairlines and nothing else.
- [Text](https://ui.misoto22.com/components/text/llms.txt): The system’s paragraph, on the second rung of the ink ladder.
- [Heading](https://ui.misoto22.com/components/heading/llms.txt): A heading whose element and whose size are two decisions.
- [Code](https://ui.misoto22.com/components/code/llms.txt): A function name or a flag, inside a sentence.
- [CodeBlock](https://ui.misoto22.com/components/code-block/llms.txt): A multi-line snippet, on a plate, with a way to take it away.
- [Markdown](https://ui.misoto22.com/components/markdown/llms.txt): A Markdown string, rendered as this system’s components.
- [Timestamp](https://ui.misoto22.com/components/timestamp/llms.txt): A date or a time, rendered the one way the system renders them.
- [Article](https://ui.misoto22.com/components/article/llms.txt): The long-form reading surface — everything a Markdown pipeline emits, in this system’s type.
- [Card](https://ui.misoto22.com/components/card/llms.txt): A bounded surface, with no shadow under it.
- [AppShell](https://ui.misoto22.com/components/app-shell/llms.txt): Two columns on a desktop, a drawer on a phone.
- [Calendar](https://ui.misoto22.com/components/calendar/llms.txt): A month, as a grid of days.
- [ScrollArea](https://ui.misoto22.com/components/scroll-area/llms.txt): A box that scrolls, with a scrollbar that looks the same everywhere.
- [DescriptionList](https://ui.misoto22.com/components/description-list/llms.txt): One record’s fields, as a real <dl> rather than a grid of divs.
- [Toolbar](https://ui.misoto22.com/components/toolbar/llms.txt): The bar of actions at the edge of a working surface.
- [AspectRatio](https://ui.misoto22.com/components/aspect-ratio/llms.txt): A box that keeps its shape whatever is inside it.
- [Table](https://ui.misoto22.com/components/table/llms.txt): A ruled data table — alignment, sorting and rules all per column.
- [Heatmap](https://ui.misoto22.com/components/heatmap/llms.txt): A grid of values read by weight.
- [Sparkline](https://ui.misoto22.com/components/sparkline/llms.txt): A run of numbers at the size of a word.
- [BarList](https://ui.misoto22.com/components/bar-list/llms.txt): A ranked list, with the bar behind the name rather than beside it.
- [BigNumber](https://ui.misoto22.com/components/big-number/llms.txt): One number, at the size of a headline.
- [BulletChart](https://ui.misoto22.com/components/bullet-chart/llms.txt): A measure, its target, and the bands that say whether it is any good.
- [AreaChart](https://ui.misoto22.com/components/area-chart/llms.txt): A filled series over a continuous axis, where the area means something.
- [BarChart](https://ui.misoto22.com/components/bar-chart/llms.txt): Discrete categories compared by length.
- [LineChart](https://ui.misoto22.com/components/line-chart/llms.txt): Several series compared over a continuous axis.
- [ComposedChart](https://ui.misoto22.com/components/composed-chart/llms.txt): Bars and lines over one axis — the volume, and the rate it moved at.
- [PieChart](https://ui.misoto22.com/components/pie-chart/llms.txt): Parts of one whole.
- [RadarChart](https://ui.misoto22.com/components/radar-chart/llms.txt): A profile across several named dimensions.
- [RadialChart](https://ui.misoto22.com/components/radial-chart/llms.txt): Values on an arc — a gauge, or a few totals against one scale.
- [SankeyChart](https://ui.misoto22.com/components/sankey-chart/llms.txt): Where a quantity goes as it moves through stages.
- [ScatterChart](https://ui.misoto22.com/components/scatter-chart/llms.txt): Two measures against each other, one mark per observation.
- [FunnelChart](https://ui.misoto22.com/components/funnel-chart/llms.txt): Stages that only ever narrow.
- [TreemapChart](https://ui.misoto22.com/components/treemap-chart/llms.txt): Part of a whole, when the whole has too many parts for a pie — and the parts nest.
- [BoxPlot](https://ui.misoto22.com/components/box-plot/llms.txt): The spread of a measurement, per category.
- [Histogram](https://ui.misoto22.com/components/histogram/llms.txt): The shape of one distribution.
- [WaterfallChart](https://ui.misoto22.com/components/waterfall-chart/llms.txt): How a total got from one figure to another.
- [Facet](https://ui.misoto22.com/components/facet/llms.txt): The same chart once per group, on one shared scale.
- [ArchitectureFigure](https://ui.misoto22.com/components/architecture-figure/llms.txt): A component map: services, datastores, trust boundaries, and what talks to what.
- [WorkflowFigure](https://ui.misoto22.com/components/workflow-figure/llms.txt): A process in lanes and phases, with the main path drawn heavier than its branches.
- [SequenceFigure](https://ui.misoto22.com/components/sequence-figure/llms.txt): A call chain over time: who asks whom, in what order, and what comes back.
- [DataflowFigure](https://ui.misoto22.com/components/dataflow-figure/llms.txt): A pipeline: where data comes from, what happens to it, and who ends up with it.
- [LifecycleFigure](https://ui.misoto22.com/components/lifecycle-figure/llms.txt): A state machine: what something can be, and what moves it between states.
- [DiagramCanvas](https://ui.misoto22.com/components/diagram-canvas/llms.txt): A frame that a picture larger than it can be panned and zoomed inside.
- [DiagramToolbar](https://ui.misoto22.com/components/diagram-toolbar/llms.txt): A bar of actions belonging to the surface underneath them.
- [DiagramExportMenu](https://ui.misoto22.com/components/diagram-export-menu/llms.txt): Taking the figure off the page: PNG, JPEG, WebP, SVG and a 1200×630 share card.
- [DiagramInspector](https://ui.misoto22.com/components/diagram-inspector/llms.txt): What the reader just picked, written out beside the picture.
- [DiagramMinimap](https://ui.misoto22.com/components/diagram-minimap/llms.txt): Where you are in something bigger than the window.
- [DiagramLegend](https://ui.misoto22.com/components/diagram-legend/llms.txt): The key: which drawn form means which kind of thing.

## Foundations

- [Getting started](https://ui.misoto22.com/foundations/getting-started/): Install it, pick a stylesheet, and render the first control.
- [Colour](https://ui.misoto22.com/foundations/colour/): A white ground, a near-black mark, three rule weights, and status.
- [Typography](https://ui.misoto22.com/foundations/typography/): Three faces, one heading ladder, and nothing above the page title.
- [Space & shape](https://ui.misoto22.com/foundations/space/): The page gutter, the measures, and the four radii.
- [Shape](https://ui.misoto22.com/foundations/shape/): Five steps from one number, and the arithmetic that keeps two of them concentric.
- [Elevation](https://ui.misoto22.com/foundations/elevation/): Nothing rises. Four shadow tokens exist to make sure of it.
- [Icons](https://ui.misoto22.com/foundations/icons/): One stroke weight, three sizes, and a library that has stopped shipping brand marks.
- [Motion](https://ui.misoto22.com/foundations/motion/): One curve, three durations, and a reduced-motion rule that is not optional.
- [Working with AI](https://ui.misoto22.com/foundations/agents/): The package documents itself twice. This is the half a browser cannot open.

## Templates

- [Dashboard](https://ui.misoto22.com/templates/dashboard/): A console: a sidebar, a figure band, tabs, a filterable table and two job cards.
- [Landing page](https://ui.misoto22.com/templates/landing/): A marketing page: a hero, a figure band, three pillars, a reversed pricing plate and an FAQ.
- [Blog index](https://ui.misoto22.com/templates/blog/): A publication index: a filter strip, a lead story, and a ruled list of records.
- [Architecture explorer](https://ui.misoto22.com/templates/architecture/): One diagram given the screen: a floating toolbar, a pannable canvas, an inspector, a minimap, a key and the conclusions under it.
- [Article](https://ui.misoto22.com/templates/post/): One post, rendered from a real Markdown file through the site’s own pipeline.
- [Settings](https://ui.misoto22.com/templates/settings/): A workspace settings screen: a section rail, four groups of real controls, and a save bar that only exists once something changed.
- [Sign in](https://ui.misoto22.com/templates/login-card/): A centred authentication card: email and password, a rejected attempt still on screen, and a divider into two SSO buttons.
- [Data table](https://ui.misoto22.com/templates/table-filter/): A table with everything a real one has: a filter strip, a sorted column, row selection with a bulk bar, and pagination.
- [Multi-step form](https://ui.misoto22.com/templates/form-wizard/): Four steps to create a deploy environment: the rail on one side, the current step’s fields beside it, and a review that reads back what was entered.
- [Record detail](https://ui.misoto22.com/templates/detail-page/): One incident: a title block carrying its status, the write-up, a metadata rail, and the activity that happened to it.
- [Loading, empty, error](https://ui.misoto22.com/templates/states/): The three states every real screen has, drawn side by side: a skeleton, an empty collection, and a page that failed.
- [Documentation](https://ui.misoto22.com/templates/docs-shell/): A reference page: a sidebar of sections, an article column with a props table and a keyboard note, and a contents rail beside it.
- [Pricing](https://ui.misoto22.com/templates/pricing/): Three plans behind a monthly/annual switch, a feature comparison table, and the questions people ask before paying.

## Optional

- [Everything, inline](https://ui.misoto22.com/llms-full.txt) — every component in one file.
- [Themes](https://ui.misoto22.com/themes/) — the five presets, rendered.
- [Changelog](https://ui.misoto22.com/changelog/)