# Folio

> 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-accent`: clay | cobalt | forest | ink | moss | plum (unset = ink)
- `data-chart-palette`: accent | chroma (unset = the neutral series ramp)
- `data-density`: comfortable | 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 | hairline | quiet (unset = hairline)
- `data-surface`: cool | glass | paper | warm (unset = paper)
- `data-table-density`: compact (unset = comfortable — whatever `data-density` is doing around it)
- `data-type`: bookish | editorial | 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. `data-accent`
re-points one token, `--clay`, which every component reads through
`--accent`; a brand that is none of the shipped values re-points that token
in a stylesheet instead of setting the attribute.

## 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:

- `ARTICLE_HTML_AND_CHILDREN`
- `BREADCRUMB_CRUMB_NOT_LINKED`
- `BUTTON_ICON_ONLY_UNNAMED`
- `CLIPBOARD_WRITE_REJECTED`
- `DIAGRAM_ACCENT_ON_CONTAINER`
- `DIAGRAM_CELL_COLLISION`
- `DIAGRAM_DIRECTION_ON_LEAF`
- `DIAGRAM_DUPLICATE_ID`
- `DIAGRAM_EDGE_DANGLING`
- `DIAGRAM_LANE_UNKNOWN`
- `DIAGRAM_REF_UNKNOWN`
- `DIAGRAM_SPEC_MUTATED`
- `DIAGRAM_STAGE_OUT_OF_RANGE`
- `DIALOG_TITLE_MISSING`
- `FIELD_CONTROL_NOT_LABELLABLE`
- `FIELD_CONTROL_NOT_WIRED`
- `REQUIRED_NAME_BLANK`
- `SEARCHABLE_MENU_LABEL_UNREADABLE`

## 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.
- [NumberField](https://ui.misoto22.com/components/number-field/llms.txt): A number, typed or swept to.
- [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.
- [ColorPicker](https://ui.misoto22.com/components/color-picker/llms.txt): A colour, chosen or typed.
- [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.
- [Sidebar](https://ui.misoto22.com/components/sidebar/llms.txt): A navigation rail down the side of an application.
- [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.
- [PageHeader](https://ui.misoto22.com/components/page-header/llms.txt): A page opening: what this page is, and what qualifies it.
- [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.
- [CalendarHeatmap](https://ui.misoto22.com/components/calendar-heatmap/llms.txt): A year of daily readings, as a week-by-week grid.
- [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.
- [Metric](https://ui.misoto22.com/components/metric/llms.txt): One reading, on a plate: a label, a figure, and what qualifies 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.

## Website

Page-shaped compositions of the components above, imported from `@misoto22/design/website`.
The host supplies content, routes and service state.

- [SiteShell](https://ui.misoto22.com/components/site-shell/llms.txt): Page landmarks, footer groups and shared section headings.
- [SiteNavigation](https://ui.misoto22.com/components/site-navigation/llms.txt): Responsive navigation and explicit language or appearance choices.
- [Portfolio](https://ui.misoto22.com/components/portfolio/llms.txt): An editorial introduction, featured images, records and a question card.
- [PortfolioIndex](https://ui.misoto22.com/components/portfolio-index/llms.txt): Tabbed collections with a supporting editorial column.
- [Collection](https://ui.misoto22.com/components/collection/llms.txt): Collection headings, search controls, featured records and empty states.
- [Reading](https://ui.misoto22.com/components/reading/llms.txt): Article and project layouts, outlines, media and installation instructions.
- [Contact](https://ui.misoto22.com/components/contact/llms.txt): A correspondence form, contact facts, questions and location imagery.
- [Music](https://ui.misoto22.com/components/music/llms.txt): Featured recordings, track rows and playlist collections.
- [Timeline](https://ui.misoto22.com/components/timeline/llms.txt): Career records, profile narratives and chronological lists.
- [Recovery](https://ui.misoto22.com/components/recovery/llms.txt): Loading, unavailable and missing-page states with recovery actions.
- [Media](https://ui.misoto22.com/components/media/llms.txt): Photograph collections, lightboxes, image details and map controls.
- [Metrics](https://ui.misoto22.com/components/metrics/llms.txt): Metric panels, accessible data tables and chart arrangements.
- [SearchPalette](https://ui.misoto22.com/components/search-palette/llms.txt): Search results, actions and a detail view in one accessible modal.
- [Content](https://ui.misoto22.com/components/content/llms.txt): Formatted code, clipboard actions, step sequences and rich-content elements.
- [Actions](https://ui.misoto22.com/components/actions/llms.txt): Share action menus and a scroll-to-top control.
- [Conversation](https://ui.misoto22.com/components/conversation/llms.txt): Conversation threads, answers, citations, composers and floating chat surfaces.
- [Evidence](https://ui.misoto22.com/components/evidence/llms.txt): Expandable traces, source stages, scores and timing summaries.

## 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 five 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/): Filled paths rather than strokes, three size tokens over six sizes in the source, and a set that ships brand marks again.
- [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.
- [Activity board](https://ui.misoto22.com/templates/activity-board/): One screen of a working week: four figures, two lanes over time, a ranked attention column, a grouped table and two bar charts.
- [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/)