@gjermundgaraba-designs/plain-garden 0.0.0-stage → 0.7.0

package/DESIGN.md

@@ -0,0 +1,671 @@
+---
+name: plain-garden
+description: A design system for a personal site kept as a garden; a quiet white reading page whose working drawings show how finished each note is.
+colors:
+  paper: "oklch(1 0 0)"
+  paper-dark: "oklch(0.18 0.004 265)"
+  ink: "oklch(0.21 0.008 265)"
+  ink-dark: "oklch(0.96 0.003 265)"
+  text: "oklch(0.37 0.01 265)"
+  text-dark: "oklch(0.86 0.005 265)"
+  ink-soft: "oklch(0.53 0.01 265)"
+  ink-soft-dark: "oklch(0.69 0.008 265)"
+  rule: "oklch(0.92 0.004 265)"
+  rule-dark: "oklch(0.3 0.006 265)"
+  wash: "oklch(0.972 0.003 265)"
+  wash-dark: "oklch(0.225 0.005 265)"
+  accent: "oklch(0.52 0.12 60)"
+  accent-dark: "oklch(0.8 0.12 75)"
+  mark: "oklch(0.95 0.07 95)"
+  mark-dark: "oklch(0.4 0.06 85)"
+  selection-bg: "oklch(0.93 0.06 95)"
+  selection-bg-dark: "oklch(0.38 0.06 85)"
+  draw-line: "oklch(0.44 0.15 260)"
+  draw-line-dark: "oklch(0.8 0.1 252)"
+  draw-red: "oklch(0.65 0.17 33)"
+  draw-red-dark: "oklch(0.76 0.14 32)"
+  draw-blue: "oklch(0.62 0.12 248)"
+  draw-blue-dark: "oklch(0.76 0.11 245)"
+  draw-yellow: "oklch(0.86 0.13 90)"
+  draw-yellow-dark: "oklch(0.87 0.13 90)"
+  draw-green: "oklch(0.73 0.09 152)"
+  draw-green-dark: "oklch(0.8 0.1 152)"
+  draw-brown: "oklch(0.67 0.09 62)"
+  draw-brown-dark: "oklch(0.77 0.09 62)"
+  draw-glass: "oklch(0.92 0.025 240)"
+  draw-glass-dark: "oklch(0.64 0.05 240)"
+typography:
+  display-greeting:
+    fontFamily: '"Bricolage Grotesque", "Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "clamp(3.5rem, 7.4vw, 7rem)"
+    fontWeight: 800
+    lineHeight: 0.88
+    letterSpacing: "-0.045em"
+  display-note-title:
+    fontFamily: '"Bricolage Grotesque", "Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "clamp(2.75rem, 5.4vw, 5rem)"
+    fontWeight: 800
+    lineHeight: 0.88
+    letterSpacing: "-0.045em"
+  headline:
+    fontFamily: '"Bricolage Grotesque", "Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "2.25rem"
+    fontWeight: 800
+    lineHeight: 1.05
+    letterSpacing: "-0.03em"
+  title:
+    fontFamily: '"Bricolage Grotesque", "Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "1.75rem"
+    fontWeight: 800
+    lineHeight: 1.05
+    letterSpacing: "-0.03em"
+  section:
+    fontFamily: '"Bricolage Grotesque", "Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "1.25rem"
+    fontWeight: 800
+    lineHeight: 1.35
+    letterSpacing: "-0.03em"
+  standfirst:
+    fontFamily: '"Bricolage Grotesque", "Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "1.5rem"
+    fontWeight: 500
+    lineHeight: 1.3
+    letterSpacing: "-0.015em"
+  subtitle:
+    fontFamily: '"Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "1.0625rem"
+    fontWeight: 700
+    lineHeight: 1.7
+  body:
+    fontFamily: '"Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "1rem"
+    fontWeight: 400
+    lineHeight: 1.7
+    fontFeature: "kern, liga, calt"
+  link:
+    fontFamily: '"Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "1em"
+    fontWeight: 500
+  small:
+    fontFamily: '"Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "0.9375rem"
+    fontWeight: 400
+    lineHeight: 1.5
+  label:
+    fontFamily: '"Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "0.8125rem"
+    fontWeight: 400
+    lineHeight: 1.55
+    fontFeature: "tnum"
+  code-inline:
+    fontFamily: '"Atkinson Hyperlegible Mono", ui-monospace, Menlo, Consolas, monospace'
+    fontSize: "0.875em"
+    fontWeight: 400
+  code-block:
+    fontFamily: '"Atkinson Hyperlegible Mono", ui-monospace, Menlo, Consolas, monospace'
+    fontSize: "0.8125rem"
+    fontWeight: 400
+    lineHeight: 1.65
+  parts:
+    fontFamily: '"Atkinson Hyperlegible Mono", ui-monospace, Menlo, Consolas, monospace'
+    fontSize: "0.6875rem"
+    fontWeight: 500
+    letterSpacing: "0.08em"
+  drawing-marks:
+    fontFamily: '"Atkinson Hyperlegible Mono", ui-monospace, Menlo, Consolas, monospace'
+    fontSize: "11px"
+    fontWeight: 500
+    letterSpacing: "0.08em"
+  hand:
+    fontFamily: '"Architects Daughter", "Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "0.9375rem"
+    fontWeight: 400
+    lineHeight: 1.3
+  hand-in-drawing:
+    fontFamily: '"Architects Daughter", "Atkinson Hyperlegible Next", system-ui, sans-serif'
+    fontSize: "15px"
+    fontWeight: 400
+rounded:
+  sm: "0.25rem"
+  md: "0.375rem"
+spacing:
+  u: "0.5rem"
+  measure: "34rem"
+  page-top: "3.5rem"
+  page-left: "clamp(1.25rem, 8vw, 7.5rem)"
+  page-right: "1.25rem"
+  page-bottom: "5rem"
+  mark-col: "1.5rem"
+  change-date: "9rem"
+  list-indent: "1.5em"
+  pre-pad: "1.125rem"
+  drawn-width: "75rem"
+  margin-note: "15rem"
+  margin-reach: "19rem"
+  margin-note-narrow: "9rem"
+  illustration-small: "10rem"
+components:
+  link:
+    textColor: "{colors.ink}"
+    typography: "{typography.link}"
+  link-visited:
+    textColor: "{colors.text}"
+  skip-link:
+    textColor: "{colors.ink}"
+    typography: "{typography.label}"
+  text-button:
+    textColor: "{colors.ink-soft}"
+    padding: "0"
+  text-button-on:
+    textColor: "{colors.ink}"
+  flag:
+    textColor: "{colors.accent}"
+    typography: "{typography.label}"
+  note-meta:
+    textColor: "{colors.ink-soft}"
+    typography: "{typography.label}"
+  standfirst:
+    textColor: "{colors.ink}"
+    typography: "{typography.standfirst}"
+  stage-mark:
+    textColor: "{colors.ink}"
+    size: "0.75rem"
+  code-inline:
+    backgroundColor: "{colors.wash}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.sm}"
+    padding: "0.1em 0.3em"
+  code-block:
+    backgroundColor: "{colors.wash}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.md}"
+    padding: "0.875rem 1.125rem"
+    typography: "{typography.code-block}"
+  kbd:
+    backgroundColor: "{colors.wash}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.sm}"
+    padding: "0.1em 0.3em"
+  highlight:
+    backgroundColor: "{colors.mark}"
+    textColor: "{colors.ink}"
+  drawn-title:
+    width: "75rem"
+    typography: "{typography.display-greeting}"
+  drawn-title-note:
+    typography: "{typography.display-note-title}"
+  parts-list:
+    textColor: "{colors.draw-line}"
+    typography: "{typography.parts}"
+  illustration-small:
+    width: "10rem"
+  margin-note:
+    textColor: "{colors.draw-line}"
+    typography: "{typography.hand}"
+    width: "15rem"
+  margin-note-narrow:
+    width: "9rem"
+---
+
+# Design System: plain-garden
+
+## Overview
+
+**Creative North Star: "Drafted garden"**
+
+A personal site kept rather than published, set as a quiet white reading page: one column hung from the left, the open space to its right kept for the writer's drawings. The words are calm (Atkinson Hyperlegible Next, ink links a step heavier than the text, hairlines for every division). The drawings carry the character. They are working drawings in a drafting blue on the page's own paper: measurements with arrowheads, dash-dot centre lines, numbered parts on leaders, construction lines past the corners, colour only ever as coloured hatching. Titles in Bricolage Grotesque, heavy and tight, stand on a drawing's ground line.
+
+The garden lives in the structure and in the drawings. Every note has a stage (Rough, Growing, Settled), and the stage picks how its drawings are made: a freehand pencil sketch, the sketch with coloured hatching, an exact drafting with coloured hatching. One Scene is described once and drawn three ways, so the drawing itself tells the reader how finished the note is. Writers never draw; they describe, and a coding agent writes the Scene using the authoring guide under Components.
+
+The density is low and the page is flat: no grounds, no panels, no shadows, no grids, no glows, no rasters in the drawings. Plain HTML is the API; a page without Foldkit looks right in both schemes.
+
+**Key Characteristics:**
+
+- White paper by day, near-black paper by night, followed through `light-dark()` with no script.
+- One column of about 68 characters hung from the left; the space to its right holds margin notes and the drawn title's drawing.
+- Working drawings in a drafting blue, coloured only by hatching in five colours and a pale glass blue.
+- The note's stage picks the drawing's style: sketch, hatched sketch, exact drafting.
+- Bricolage Grotesque 800 for titles and section heads, Atkinson Hyperlegible Next for text, its Mono for code and drawing lettering, Architects Daughter for the writer's hand in margin notes.
+- One movement only: a link's underline firming under the pointer.
+
+## Colors
+
+A neutral paper-and-ink palette with the faintest cool cast, one amber accent for freshness, and a separate drawing palette: a drafting blue for every line and six hatching roles. Every colour is a light/dark pair.
+
+### Primary
+
+- **Drafting Blue** (draw-line / draw-line-dark): every line, arrowhead, measurement, number, part name and parts list in a drawing, diagrams included, and a margin note's words. On the dark paper it becomes a light blue line. It is the colour of the system's character, and it is never a ground.
+
+### Secondary
+
+- **Hatching Red, Blue, Yellow, Green, Brown** (draw-red, draw-blue, draw-yellow, draw-green, draw-brown, each with a -dark pair): coloured hatching laid over a shape in Growing and Settled drawings. Roles a Scene names, not values. Lifted at night so thin lines do not go muddy.
+- **Glass** (draw-glass / draw-glass-dark): a pale blue hatching for water and glass.
+
+### Tertiary
+
+- **Amber** (accent / accent-dark): the words New and Updated beside a link. Nothing else.
+- **Highlighter** (mark / mark-dark): `mark`, and the heading, code line, table row, figure caption or footnote a link put the reader on.
+- **Selection** (selection-bg / selection-bg-dark): selected text, in ink.
+
+### Neutral
+
+- **Paper** (paper / paper-dark): the page, and what a drawing's `paper` fill hides with.
+- **Ink** (ink / ink-dark): headings, links, strong text, code, the current page in the masthead, the stage mark, the focus ring.
+- **Text** (text / text-dark): running text, a step off the ink for a long read; also a visited link.
+- **Soft Ink** (ink-soft / ink-soft-dark): the meta line, dates, captions, a line about a link, list markers, line numbers, the footer, text buttons at rest.
+- **Rule** (rule / rule-dark): hairlines: `hr`, table rows, a box's top, the ring's top, the quote rule, footnotes.
+- **Wash** (wash / wash-dark): code blocks, inline code, keys.
+
+Derived, not separate colours: the link underline is ink at 28% and the soft underline is soft ink at 40%; the scrollbar is soft ink at 70%.
+
+### Named Rules
+
+**The Hatching-Only Rule.** Colour enters a drawing as coloured hatching laid over a shape, never as a coloured ground, a flat fill, a wash or a glow. Every drawing sits on the page's own paper.
+
+**The One Amber Rule.** The accent marks freshness (New, Updated) and nothing else. Links are ink, told apart by weight and underline, not by hue.
+
+**The Pair Rule.** Every colour, drawing colours included, is a `light-dark()` pair in `tokens.css`. A new colour without its dark pair is not finished.
+
+### Forced colours and print
+
+- **Forced colours:** a targeted code line or table row takes a 2px inset outline in `Highlight`; stage marks take `CanvasText`; every pencil stroke, ruled line, solid mark, hatching and letter in a `.drawing` takes `CanvasText`, so a drawing (a diagram too) goes monochrome in the system's text colour and still reads by its lines; a margin note's words, like all text, take the forced text colour; task-list boxes return to the native checkbox. The stage word carries the stage either way.
+- **Print:** white paper and black ink whatever the screen's scheme (text black, soft ink #444, wash white, light colour scheme); no body padding; the skip link, masthead, scheme switch, ring and Copy are hidden; an external link prints its address after it. Drawings keep their drafting blue and hatching.
+
+## Typography
+
+**Display Font:** Bricolage Grotesque (with Atkinson Hyperlegible Next)
+**Body Font:** Atkinson Hyperlegible Next (with system-ui, sans-serif)
+**Label/Mono Font:** Atkinson Hyperlegible Mono (with ui-monospace, Menlo, Consolas)
+**Hand:** Architects Daughter (with Atkinson Hyperlegible Next)
+
+**Character:** A heavy, tight grotesque that can stand on a drawing, over a sans drawn so letters are hard to mistake for one another. The drawings letter in the Mono, in tracked capitals, like a drawing sheet; the writer's margin notes are in a draftsman's hand. All four faces are self-hosted from `fonts/` under the SIL Open Font License.
+
+### Hierarchy
+
+- **Display, greeting** (800, clamp(3.5rem, 7.4vw, 7rem), 0.88, -0.045em): the front page's title standing on its drawing (a DrawnTitle outside a note head), at most 6.5ch wide.
+- **Display, note title** (800, clamp(2.75rem, 5.4vw, 5rem), 0.88, -0.045em): a note's title standing on its drawing, at most 9.5ch wide.
+- **Headline** (800, 2.25rem, 1.875rem on a phone, 1.05, -0.03em): an `h1` with no drawing.
+- **Title** (800, 1.75rem, 1.5rem on a phone, 1.05, -0.03em): `h2`, the front page's group heads.
+- **Section** (800, 1.25rem, 1.35): `h2` inside an `article`, a note's section heads.
+- **Standfirst** (Bricolage 500, 1.5rem, 1.3125rem on a phone, 1.3, -0.015em): the line under a title, in ink.
+- **Subtitle** (Atkinson 700, 1.0625rem): `h3`; `h4` to `h6` the same, in italic.
+- **Body** (400, root 17px, 16px under 600px, 1.7): running text at a 34rem measure, about 68 characters. Links 500; strong 700.
+- **Small** (0.9375rem, 1.5): the masthead, a line about a link, tables, footnotes, the ring.
+- **Label** (0.8125rem, 1.55, tabular figures): meta line, dates, captions, figure notes, the sample note, the footer, New and Updated.
+- **Code** (Mono, 0.875em inline, 0.8125rem in a block at 1.65, 0.75rem on a phone).
+- **Parts** (Mono 500, 0.6875rem, 0.08em, uppercase): the parts list under a drawing.
+- **Drawing marks** (Mono 500, 11 viewBox units, 0.08em, uppercase): numbers, measurements and labels inside a drawing; they scale with the drawing.
+- **Hand** (Architects Daughter 400, 0.9375rem, 1.3, centred): a margin note's words; 15 viewBox units for a one-word label inside a margin sketch.
+
+### Named Rules
+
+**The Two Voices Rule.** Bricolage is for `h1`, `h2` and the standfirst only; every other word that is read is Atkinson. The display face never sets running text.
+
+**The Drawing Sheet Rule.** Words that belong to a drawing (part names, measurements, labels, diagram text) are Mono capitals, tracked, in drafting blue. Words that belong to the writer's pencil are the hand, never capitals.
+
+## Layout
+
+The column hangs from the left and stops at the measure (34rem); the masthead, `main` and the page footer all share that width. Body padding is page-top on top, page-left on the left (clamp(1.25rem, 8vw, 7.5rem), so the left edge holds as the screen widens), page-right on the right and page-bottom below. The space to the right of the column is left empty on purpose: margin notes hang in it, and a drawn title's drawing runs out across it.
+
+The rhythm is one unit (`--u`, 0.5rem). Blocks are 2.5u apart; figures 3.5u; an `h2` opens 8u above and 1.5u below and clears any right-floated drawing; `h3` 4u above; a box or ring sits 5u from its neighbours under a hairline; the masthead stands 8u above the content (5u on a phone).
+
+**Drawn title.** The drawing runs min(75rem, the page inside its side padding and any scrollbar: `body` is an inline-size container and the width is `100cqi`) wide; the `h1` is positioned on the scene's ground line at the left, bottom-anchored, so a longer title grows upward from the ground. The parts list follows, right-aligned to the drawing's width. Under 800px the drawing, cropped to the scene's `focus` range, stands above the title; the title follows under it and the parts list aligns left. The title stays first in the markup, so it is read first.
+
+**Margin notes.** At 1100px and over, a margin note floats right out of the column by margin-reach (19rem), 15rem wide, beside the paragraph after it. Under 1100px there is no open space: it floats right inside the column at 9rem, the text wrapping round it, its words under the sketch and its in-drawing labels hidden.
+
+**Illustrations.** Full: the measure's width, 4u above and below. Small: floated right at 10rem (at most 40% of the column under 600px), the text wrapping round it.
+
+**Small screens (600px and under).** Root 16px, smaller headline, title, standfirst and code; What's new stacks date over line; the ring stacks with All notes last; table cells tighten; long code lines wrap and hang 4ch in past the line number.
+
+### Named Rules
+
+**The Hung Column Rule.** The column keeps its left edge and its measure at every width; nothing centres it, and the space to its right is reserved for the drawings, never filled with sidebars or panels.
+
+**The No Sideways Push Rule.** Nothing a writer can put in a note pushes the page sideways on a phone: long words break, tables and code scroll inside themselves, drawings scale. The page breaks a long word only once it overflows (`overflow-wrap: break-word`), which a flex or grid row does not see when it sizes its items, so the rows that hold a writer's words (the masthead, a note's meta line, a caption with tools, the parts list, the ring) break a long word anywhere instead.
+
+## Elevation & Depth
+
+Flat. There are no shadows, no raised panels and no layered surfaces; the only tonal step is the wash under code. Depth on the page is order and hairlines. Depth inside a drawing is draw order (a later shape hides an earlier one) and the drafting convention of a dashed line for a level, an axis or what is hidden. Two `box-shadow`s in the stylesheet are not elevation: the highlighter's spread around a targeted heading, and the ink edge inset on a targeted code line. A key's 2px bottom border is a key's edge.
+
+### Named Rules
+
+**The Own Paper Rule.** Every drawing sits on the page's paper. No blueprint ground, no dot grid, no card behind a drawing, no frame.
+
+## Shapes
+
+Square by default. A soft radius (md) on code blocks and images, a smaller one (sm) on inline code, keys, task-list boxes and the focus ring. Divisions are 1px hairlines; a blockquote has a 2px rule on its left. The stage mark is a 12-unit circle at 1.5 stroke: an open ring (Rough), a half disc (Growing), a full disc (Settled). Drawing geometry follows the drawing's stage: tapered, wandering pencil strokes that run past their corners in Rough and Growing; ruled lines, filled arrowheads and dash-dot centre lines in Settled.
+
+## Components
+
+The components are Foldkit Views (`X.view(config, h)`) and two Submodels (the scheme switch and Copy), one per directory under `src/`, exported as namespaces from the package (`import { NoteHeader, Scheme } from "@gjermundgaraba-designs/plain-garden"`). Each renders the markup `plain-garden.css` already styles; the classes below are the plain-HTML contract, and the reference for a site without Foldkit is `site/src/example/`: each `.ts` the specimen renders, shown beside the markup it renders, serialised from the same view at build, so the two cannot drift. How a component is built is under "Building components".
+
+### Links and text buttons
+
+- **Links:** ink, weight 500, a 1px underline in ink at 28% sitting 0.22em below, firming to full ink under the pointer over 150ms (instant under reduced motion). Visited steps back to the text tone and keeps its weight (not for in-page anchors or the masthead). Inside secondary text (meta, captions, citations, `.note`, `.about`, the footer) links take the surrounding tone and weight over the soft underline. A heading that links to itself stays ink, underlined only under the pointer.
+- **Text buttons** (`.scheme button`, `.copy`): `<button type="button" tabindex="0">`, as `@foldkit/ui`'s Button renders one; no box; soft ink and a soft underline; the one that is on (`aria-pressed="true"`, `aria-disabled="true"`) in ink with no underline.
+- **Focus:** a 2px solid ink ring, 3px off, small radius, on links, buttons, summaries, inputs and every `[tabindex]` region. The `main` a skip link lands on takes focus with no ring: the ring is for what a reader acts on, not the whole column.
+
+### Skip link
+
+`SkipLink.view(h)`: `<a class="skip-link" href="#main">Skip to content</a>`, first in `<body>`, before the masthead. Hidden until it has focus, it then shows as a plain link at label size at the column's left edge, centred in the band above the masthead, where it covers nothing. The page's main is `<main id="main">`, so after following the link the next Tab starts inside it.
+
+### Masthead
+
+`<header class="masthead">` with `<a class="site-name">` (linking `home`) in ink 700 and `<nav><ul class="site-nav">` of soft-ink links with no underline at rest; the current page (`aria-current="page"` and `data-current`, as `@foldkit/ui`'s Nav marks it) in ink at 500. One wrapping line at the small size. The nav is named "Site" for assistive technology unless the page gives it another name.
+
+### Stage
+
+`<span class="stage">` holding the aria-hidden 12-unit mark (`svg.stage-mark`, the same mark a note list uses) and the word (Rough, Growing, Settled). The word always carries the meaning; the mark is drawn, not read.
+
+### Note header
+
+`<header class="note-head">`: the title (a DrawnTitle when the note has a drawing, drawn at the note's stage, else a plain `h1`), then `<p class="meta">` with the stage in ink, "Started" and "Updated" dates (written out, en-GB, UTC) and the reading length, then `<p class="standfirst">`.
+
+### Note list
+
+`<ul class="note-list">`: each `li` a two-column grid, the stage mark in a 1.5rem column dropped to the title's first line, then the title link, an optional `<span class="flag">` (New or Updated, in amber, label size) and `<p class="about">` with the stage word and one line on what the note holds. The list keeps the writer's order.
+
+### Box, What's new, Pages that link here
+
+`<section class="box">`: a hairline above, a small `h2` at the small size, nothing around it. What's new is `<ul class="changes">` inside it: a 9rem date column in soft ink and the line. LinksHere is a box of links headed "Pages that link here".
+
+### Ring
+
+`<nav class="ring">` after a note: previous, All notes, next in a three-column grid under a hairline; each keeps its column, so a missing neighbour leaves a gap. Stacks on a phone.
+
+### In short
+
+Summary: a plain `h2` ("In short") and an `ol`.
+
+### Figures and code
+
+- **Figure:** `<figure id="fig-N">`, the body, `<figcaption>` "**Fig. N.** caption" in soft ink at label size with any tools on the right, then `<ol class="fig-notes">` whose links point into the figure (`fig-N-l5` for a line, `fig-N-<name>` for a group). A note's link reads "Line N" for a line, and a group's name with spaces for its hyphens. A targeted figure's caption takes the highlighter. FigRef links prose to `#fig-N`.
+- **Code figure:** `pre` on the wash with numbered lines (`span.line`, generated numbers that never land in a copy), a focusable scrolling region, Copy that reads Copied for 1.6s and announces it. Where the clipboard is refused it keeps reading Copy, held for the same beat, and its status announces "copy failed". `CopyButton` is a Submodel the page embeds and passes in as the figure's `copy`, which the figure calls with its own name and code: Idle, Copying, then Copied or Failed, then Idle again after the beat. It renders `<button type="button" tabindex="0" class="copy" aria-label="Copy Fig. N">`, with `aria-disabled="true"` and `data-disabled` while it is held, then `<span class="sr-only" role="status">`, both in a `<span>` that carries its id. A targeted line takes the highlighter and a 2px ink edge.
+- **Plain elements:** headings, lists and nested lists, task lists (a small rounded box, ink when done), definition lists, blockquote with `cite`, `kbd`, `mark`, tables (hairlines, tabular figures, scroll inside), images (rounded), footnotes, `details`. All styled with no class.
+- **Note** (`p.note`): a quiet italic line in soft ink for status or provenance; every sample page carries one.
+
+### Drawing (signature)
+
+`<svg class="drawing" viewBox="0 0 W H">` holding the scene's marks; with a label it is `role="img"` and `aria-label`, without one `aria-hidden`. The renderer writes classes and the stylesheet colours them from tokens: `pen` (a pencil stroke, a filled shape), `ln` (a ruled line), `solid` (an arrowhead, a dot, an ink fill), `paper` (hides), `faint` (construction lines at 0.45), `hatch` (the line of a hatching pattern, its colour set on it as `--hatch: var(--draw-<colour>)`), `tech` (lettering). Hatching is one `<pattern>` per colour in the drawing's `<defs>`, paper with a line every 4.5 units at 45°, 1.2 thick in the sketch and 1 in the drafting, its id the drawing's own; a hatched shape is a single path filled `url(#…)` with it, under its outline. The sketch's hatching is as regular as the drafting's: the hand is in the outlines. Given a figure number, each named group is a `<g id="fig-N-<name>">`; while a note points at it, its lines are drawn heavier.
+
+### Drawn title
+
+`<div class="drawn-title" style="--ground; --focus-width; --focus-start">` holding the `h1` and the drawing, followed by `<ol class="parts">`. See Layout.
+
+### Illustration
+
+`<figure class="illustration">` (add `small` to float it right at 10rem): the drawing at the note's stage, its parts list, an italic caption.
+
+### Margin note
+
+`<div class="margin-note" role="note">`: an aria-hidden drawing always drawn at Growing, then `<p>` with the writer's words in the hand, centred, in drafting blue. Placed just before the paragraph it points at.
+
+### Diagram
+
+A figure the prose reasons about: a numbered Figure holding the scene, always drawn settled, so it reads as exact whatever the note's stage. Each note's `at` names a group in the scene; a followed group's lines are drawn heavier and its words bold. It scales with the column like every drawing, so author it near the column's width (about 520 units) to keep its lettering readable on a phone.
+
+### Parts list
+
+`<ol class="parts">`: the numbered parts named in order, Mono capitals at parts size in drafting blue, "1. " generated, wrapping in a row.
+
+### Scheme switch
+
+`Scheme.SchemeSwitch`, a Submodel embedded with `h.submodel`: `<p class="scheme" role="group">`, "Colour scheme:" in a `<span>` that names the group, then Light, Dark, System as text buttons (`<button type="button" tabindex="0" aria-pressed="…">`), the one in force `aria-pressed="true"`. System follows the OS with no script; a choice is stored on the device under `plain-garden-scheme` and applied before first paint by `Scheme.schemeScript` inlined in `<head>`, writing `data-scheme` on `<html>`. The switch is self-contained: its `init` returns a `ReadScheme` Command that reads `data-scheme` once the page runs (the client runs init's Commands after hydration), so the application lifts init's Commands into its own init (`Update.foldChildInit`); a choice runs `PinScheme`, which writes or removes `data-scheme` and stores or removes the choice in `localStorage` (storage that refuses leaves the page switched, the choice not remembered). It has no Subscriptions: under System the stylesheet follows the reader's system by itself. A choice made in another tab is seen on reload, not live. `./scheme` exports the script and its keys alone, for a build config that writes `schemeScript` into a page.
+
+### Accessibility
+
+- Text at AA in both schemes; running text a step off the ink, secondary text in soft ink, never fainter. The root size is a percentage, so the reader's font size is respected.
+- A stage is never colour or shape alone: the mark is `aria-hidden` and the word is read.
+- Every drawing that says something has `role="img"` and an `aria-label` saying what it shows; decorative ones are `aria-hidden`. A margin note's sketch is decorative and its words are text in `role="note"`. A drawn title's `h1` comes first in the markup even where the drawing shows above it.
+- Code blocks are focusable, labelled scrolling regions; Copy announces Copied, or that the copy failed, through a visually hidden status.
+- Focus is always the 2px ink ring; the only motion stops under `prefers-reduced-motion`.
+- The scheme switch's choice is applied before first paint, so a stored scheme never flashes the other.
+- A skip link is the first thing a keyboard reaches on every page, and it moves focus into `main`.
+
+### Authoring drawings: the guide for agents
+
+Writers never draw. A writer says what they want ("a bucket with a tap dripping into a cup, label the parts"); you, the agent, write a `Scene` (`src/drawing/scene.ts`) and put it in the right component. The renderer draws it in the note's stage. You never write SVG paths for a Scene, never draw three versions, and never ask the writer for coordinates.
+
+**1. Size the scene for where it will show.** Coordinates are the scene's own units (a viewBox, y down), and drawing lettering is 11 of those units, so design near the displayed pixel width:
+
+| Use                                  | Component                                  | Scene size                       |
+| ------------------------------------ | ------------------------------------------ | -------------------------------- |
+| A page's title on its drawing        | `DrawnTitle` (or `NoteHeader`'s `drawing`) | about 1200 wide, 340 to 480 high |
+| A drawing across the measure         | `Illustration`                             | about 640 wide                   |
+| A small drawing the text wraps round | `Illustration` with `isSmall`              | about 180 wide                   |
+| The writer's pencil in the margin    | `MarginNote`                               | about 240 × 130                  |
+| A diagram the prose reasons about    | `Diagram`                                  | about 520 wide                   |
+
+**2. Draw clean geometry; the hand comes from the renderer.** Never wobble a line yourself. Shapes:
+
+- `rect: [x, y, w, h]`, optional `radius`, optional `turn` (degrees, about its centre).
+- `circle: [cx, cy, r]`.
+- `ellipse: [cx, cy, rx, ry]`; with `from`/`to` (degrees, clockwise from 3 o'clock) it is an open arc, and with `closed: true` too it runs back along its chord (a half disc).
+- `poly: [points]`, optional `open`, optional `turn` (about its centroid). Use `poly` only for true corners: an outlined poly is drawn as one pencil stroke per side, so a many-point poly reads as hairy. Round things are `circle`, `ellipse`, `curve` or `dome`.
+- `curve: [points]`: smooth through its points; `closed: true` to make it a shape.
+- `dome: [cx, baseY, rx, ry]`: half an ellipse on its base (a loaf, a hill).
+- `line: [a, b]`.
+- `arrow: [points]`: two points draw a straight arrow, more a smooth one; the head is on the last point.
+- `text: "words", at: [x, y]`: short words in the drawing itself, centred on `at` as a baseline (under each stack of a pile, "+0.1" by a drop), or starting or ending there with `align: "start"` or `"end"` (a column of notes beside a diagram). Mono capitals in a drawing; the hand in a margin note. Words draw in order like any shape, so put them last to keep them on top.
+- `group: [shapes]` with `origin`, `place`, `scale` and `name`. The group's own `origin` (a point in its shapes' coordinates, usually where the object stands) goes to `place`, and `scale` sizes the group about it; without them it stays where its shapes are. Define a reused object once as a `Shape[]` and note where it stands (the sample `jar` stands at [244, 360] in its own coordinates); then place it anywhere at any size (`origin: [244, 360], place: [60, 100], scale: 0.62` stands it on y = 100 in a margin note). A `name` is what a figure's notes point at (see 13): lower-case letters, digits and hyphens, once per scene, never inside another named group; the renderer refuses anything else.
+
+**3. Order is depth.** Later shapes hide earlier ones. A shape with any `fill` hides what is behind it; `fill: "paper"` hides without colour (a wheel's inner disc, a rim, a lid). Draw back to front: handle, body, contents, rim, details.
+
+**4. Colour is a role, not a value.**
+
+- `red`, `blue`, `yellow`, `green`, `brown`, `glass` (water and glass) become coloured hatching in Growing and Settled, in both schemes. **Rough shows no colour at all:** a coloured shape is a paper-filled outline there. Choose colour for the Growing and Settled drawings.
+- `ink` is solid, for small marks: a hub, a pin, a filled stage mark.
+- Most objects take one colour; leave paper, labels and small details uncoloured.
+- Fill and hatching only apply to closed shapes (`rect`, `circle`, a whole `ellipse`, `poly` that is not `open`, `curve` with `closed: true`, `dome`). A `line`, an open poly, an open curve or an arc never fills.
+- Hatching runs at 45° every 4.5 units, regular and edge to edge, under the outline: a shape under about 10 units wide holds only a line or two. Use `ink` for tiny marks, or make the shape bigger.
+
+**5. Stroke.** Default is a full outline. `stroke: "detail"` draws a thinner line (spokes, scoring on a loaf, a cup's handle, a water level, keys). `stroke: "dashed"` draws a dashed line, in every stage: a level, an axis, an edge that is hidden. `stroke: "none"` draws no outline (water inside a bucket, the starter's level in a jar): a blank paper patch in Rough, hatched with no outline in Growing and Settled. Draw a `detail` line along its top edge when the level should read in every stage.
+
+**6. Overruns and construction lines.** In Rough and Growing, outlines run about 8 units past their ends, and a sharp `rect` or a closed `poly` with up to six corners gets faint construction lines running 22 units past every corner. Rounded rects, curves and circles get none. The drawing does not clip, so keep sharp-cornered shapes clear of the viewBox edge or accept a spill into the margin; and give a tiny part a `radius` of 2 or 3 so its construction lines do not swamp it.
+
+**7. Ground and focus.**
+
+- Things stand on a ground. Set `ground` to the y of the line they stand on and draw that line (a `line` across the scene, or a shelf `rect`). It defaults to the scene's height.
+- In a DrawnTitle scene the title stands on the ground at the left, bottom-anchored and growing upward: **keep the left ~45% clear of objects from the ground up.** Put the objects in the right half (the samples start them at x ≈ 540 to 580 of 1200, often by grouping them and moving the group right). Things below the ground (a shelf's brackets) may sit under the title. Leave at least ~300 units above the ground for a three-line title.
+- `focus: [from, to]` is the x-range a phone keeps under 800px, where the drawing is cropped to it and stands above the title. Set it to the objects (the shelf uses [520, 1200]). Without it the whole width shows.
+
+**The drafting marks (8 to 10) are shapes too.** Write each beside what it marks, in the same coordinates: inside a group it moves and scales with the group, so a placed object carries its own parts and measurements. Wherever a mark sits in the list, it draws over every shape (centres under measurements under parts). When a group is reused without its marks (the bucket in a margin note), keep the object a plain `Shape[]` and add the marks in a group that wraps it where they are wanted.
+
+**8. Parts.** Number the parts a reader should name, in reading order: `{ part: "name", at, tag }`; parts are numbered in the order they appear among the shapes. `at` is a point on the object (a dot is drawn there); `tag` is a point in open space where the numbered ring (radius 10) goes, the leader stopping just short of it. Keep tags 12+ units from the viewBox edge and 22+ apart, and clear of other marks. Names are written in plain lower case; they become the parts list under the drawing, set in capitals. Usually three to six parts; a margin note has none.
+
+**9. Measurements: one or two things that matter.**
+
+- Linear: `{ measure: [from, to], offset, label }`, add `vertical: true` for a height. A horizontal dimension sits `offset` below the lower point when positive, above the higher one when negative; a vertical one sits right of the rightmost point when positive, left when negative. Extension lines start 4 off the object; arrowheads at both ends; the label sits 6 above the line (rotated for a vertical one). Put it in clear space, off the object.
+- Diameter: `{ diameter: [cx, cy, r], label }`. A leader crosses the circle from lower left to upper right, runs 26 past the rim to a knee and a 46-unit shelf, label on the shelf: leave clear space up and right of the circle. Write labels like "Ø 184".
+- Labels are short: a number ("80", "124") or a word and a number ("cap 10"). They render in capitals.
+
+**10. Centres.** `{ centre: [cx, cy, r] }`: a dash-dot cross through a round thing, running 14 past its edge each way. Give the main round things one (a wheel, a flower's head, a pin); more reads as noise.
+
+**11. Margin-note scenes.** About 240 × 130 (the samples use 240 × 132; the stages sketch 300 × 124). One object on the right half, and an arrow pointing left at the text, a curve such as `[[100, 112], [64, 128], [16, 112]]`. No parts, no measurements. The note's words are the MarginNote's `words`, never drawn into the scene. A one-word label under a mark is fine; it is lettered in the hand, and it is hidden under 1100px, where the words under the sketch say the same. Margin notes are always drawn at Growing, whatever the note's stage.
+
+**12. The scene seeds the hand.** The same scene and stage always draw the same strokes, on the server and in the browser; change the scene and its strokes change. A scene can be shown in any number of places.
+
+**13. Which component.**
+
+- **DrawnTitle.view**: a page's title standing on its drawing; two elements (the title on its drawing, the parts list), spread into the page. The front page uses it directly; a note passes `drawing: { scene, label }` to NoteHeader and the note's stage draws it.
+- **Illustration.view**: a drawing inside the text, at the note's stage; full measure, or `isSmall` floated right. Put a small one in the section it belongs to (every `h2` clears right floats).
+- **MarginNote.view**: the writer's pencil; place it immediately before the paragraph it points at. Its words are `words`; the sketch is decorative.
+- **Drawing.view**: the bare SVG, for anything else. Give it a label saying what it shows; leave the label out only when it decorates.
+- **Diagram.view**: a figure the prose reasons about, always drawn settled. Put each part a note names, with its words and arrows, in a group with that `name`; the note's `at` is the name. About 520 units wide, so its lettering stays readable when a phone scales it down.
+
+**14. Labels for readers.** Every DrawnTitle, Illustration and labelled Drawing needs an `aria-label`-ready sentence saying what the drawing shows, not how it looks ("A bucket of tokens with a tap near its base, dripping into a cup."). Sample drawings start with "Sample drawing:".
+
+**Worked example.** The writer: "a bucket with a tap dripping into a cup, label the parts." A full-measure illustration, so 640 wide; the bucket stands on a block so the tap clears the cup.
+
+```ts
+import type { Drawing } from "@gjermundgaraba-designs/plain-garden";
+
+export const bucketTapCup: Drawing.Scene = {
+  width: 640,
+  height: 300,
+  ground: 270,
+  shapes: [
+    // back to front: handle, bucket, water, level, rim, stand, tap, drop, cup
+    {
+      curve: [
+        [200, 70],
+        [214, 26],
+        [280, 12],
+        [346, 26],
+        [360, 70],
+      ],
+      stroke: "detail",
+    },
+    {
+      poly: [
+        [196, 60],
+        [364, 60],
+        [348, 190],
+        [212, 190],
+      ],
+      fill: "blue",
+    },
+    {
+      poly: [
+        [201, 100],
+        [359, 100],
+        [348, 190],
+        [212, 190],
+      ],
+      fill: "glass",
+      stroke: "none",
+    },
+    {
+      line: [
+        [201, 100],
+        [359, 100],
+      ],
+      stroke: "detail",
+    },
+    { rect: [188, 52, 184, 12], radius: 6, fill: "paper" },
+    { rect: [200, 190, 150, 80], fill: "brown" },
+    { rect: [348, 160, 40, 12], radius: 3, fill: "yellow" },
+    { rect: [376, 172, 12, 12], radius: 2, fill: "yellow" },
+    {
+      curve: [
+        [382, 200],
+        [377, 210],
+        [382, 214],
+        [387, 210],
+      ],
+      closed: true,
+      fill: "blue",
+    },
+    {
+      curve: [
+        [356, 226],
+        [358, 256],
+        [382, 270],
+        [406, 256],
+        [408, 226],
+      ],
+      closed: true,
+      fill: "red",
+    },
+    {
+      curve: [
+        [408, 232],
+        [426, 234],
+        [426, 250],
+        [404, 256],
+      ],
+      stroke: "detail",
+    },
+    {
+      line: [
+        [20, 270],
+        [620, 270],
+      ],
+    },
+    { part: "bucket", at: [330, 120], tag: [430, 40] },
+    { part: "tap", at: [372, 166], tag: [470, 120] },
+    { part: "cup", at: [390, 250], tag: [490, 210] },
+    {
+      measure: [
+        [196, 60],
+        [212, 190],
+      ],
+      offset: -30,
+      label: "130",
+      vertical: true,
+    },
+    {
+      measure: [
+        [356, 270],
+        [408, 270],
+      ],
+      offset: 18,
+      label: "52",
+    },
+  ],
+};
+```
+
+```ts
+Illustration.view(
+  {
+    scene: bucketTapCup,
+    stage, // the note's own stage
+    label: "A bucket of water on a block, its tap dripping into a cup.",
+    caption: "One drop at a time.",
+  },
+  h,
+);
+```
+
+Why it is built so: the water polygon's top corners sit on the bucket's walls and it has no outline, so Growing and Settled hatch it glass over the bucket's blue; the level `detail` line keeps the water readable in Rough. The rim is a paper-filled rounded rect drawn after the bucket, so it hides the bucket's top edge. The spout has a small radius so its construction lines do not swamp it. Tags sit in the open space to the right, in reading order top to bottom. The cup's width is measured below the ground, clear of the drop; the bucket's height on the left, clear of the tags.
+
+## Building components
+
+How a component in this package is made. The components follow these rules, and a new one follows them too; a review finding against one of them is a defect, not a style note.
+
+**The two kinds.** A **View** is a stateless render helper, `X.view(config, h)`: the caller owns any state and passes its Messages in the config. Copy `src/ring/` (a plain one), `src/figure/` (a container with a `body` slot and `tools`) or `src/drawnTitle/` (a View over the drawing renderer). A **Submodel** has a Model, Message, `init`, `update` and a `view` made with `defineView`, embedded with `h.submodel`: `src/scheme/` (`switch.ts` holds the Model, Messages, update and the Commands from `init` and `update` that read and pin the scheme on the page; `schemeSwitch.ts` adds the view) and `src/copyButton/` (Commands that write the clipboard and wait out a beat).
+
+Each component is `src/<name>/<name>.ts` with an explicit `index.ts` (its public surface: what a page uses, a Submodel's Model, Message, `init`, `update`, `view`, Commands and accessors, and the config types), a colocated `<name>.test.ts` (a Story for update, a Scene for view), an `export * as` line in `src/index.ts`, a section with an example file on the specimen's components page (`site/src/example/`; the page shows its source and the markup it renders) and an entry in this document. Only `src/index.ts` reaches an `index.ts`: inside `src/` a file, tests included, imports the file that defines what it needs (`../stage/stage.ts`). What only other components use has no `index.ts` and is not exported (`src/time/`, the written-out date in a note header and What's new).
+
+1. **A View's config is plain data.** Words are strings (`title`, `caption`, `label`, `words`); a content slot that may hold markup is `ReadonlyArray<Html | string>` (`body`, a note's `body`, a change's `body`, a summary's `points`); a slot that may carry the application's handlers is a function the caller gives, which the View calls with what it knows and which returns the caller's `Html` (a code figure's `copy`, called with the figure's name and code). Booleans read as questions (`isSmall`). A View that renders more than one element (`Summary`, `DrawnTitle` with its parts list) returns `ReadonlyArray<Html>` for the caller to spread.
+2. **Parents never read a child's Model.** A Submodel exports accessors for what a parent needs (`SchemeSwitch.id`, `CopyButton.id`), and the parent calls them, including for `slotId`.
+3. **Instances are scoped by id.** A Submodel takes its id in `init({ id })` and scopes its DOM ids by it, so two can share a page.
+4. **Ids a page addresses are the caller's.** A figure's id is `fig-N` from its number, a note's target `Figure.noteId(figure, at)`; a box's heading id is given (`Box.view({ id })`; `LinksHere`, one per note, is always `links-here`), so a page keeps them unique.
+5. **Drawings come from the renderer.** `Drawing.view` writes the renderer's marks with `h.InnerHTML`, so the server and the browser draw the same strokes. A View never draws an SVG path of its own; the stage mark is the one exception, three marks in `src/stage/`.
+6. **Platform services are the application's.** A component that needs one says so in its TSDoc and here (`CopyButton` writes through Effect's `Clipboard`), and the application provides the Layer in its `resources`. A Command that only touches the page it runs on (`SchemeSwitch`'s `ReadScheme` and `PinScheme`, on `<html>` and `localStorage`) needs no service.
+7. **Fragment links are the browser's.** A link to `#id` (the skip link, a figure's notes, a FigRef) is routed by Foldkit like every click, so a Foldkit application hands a fragment on the page being read back to the browser with `load(href)` from `foldkit/navigation`: a fragment navigation, which scrolls to it and marks it `:target`.
+8. **A Scene test for every accessibility contract** a component adds: roles, accessible names, `aria-pressed`, `aria-current`, `aria-hidden` on what is drawn and not read, held states, the status a copy announces. A Scene queries the view's tree, not the DOM, so what `h.InnerHTML` writes (a drawing's groups) is tested on the renderer's string instead.
+9. **Held means `aria-disabled`.** Copy, from the press until it reads Copy again (copying, then Copied or the copy failed for a beat), keeps focus and drops its handler; it is never natively disabled. Buttons are built on `@foldkit/ui`'s `Button.view`, whose `isDisabled` writes the held state (`aria-disabled="true"` and `data-disabled`) and drops the handler.
+10. **No product in the system.** Routing, storage beyond the scheme choice, and data belong to the site that adopts the system; sample content lives in `site/` only, marked as sample.
+
+## Do's and Don'ts
+
+### Do:
+
+- **Do** let the note's stage pick the drawing's style: Rough a freehand pencil sketch with its drafting marks drawn by hand, Growing the sketch with coloured hatching, Settled an exact drafting with ruled lines, filled arrowheads, dash-dot centre lines and the same hatching.
+- **Do** draw every line, measurement and number in drafting blue on the page's own paper, with colour only as hatching in the five colours and glass.
+- **Do** put a parts list under any drawing with numbered parts.
+- **Do** keep margin notes as the writer's pencil: a small hatched sketch, an arrow to the text, a few words in the hand.
+- **Do** stand a title on its drawing's ground line (the front page's greeting on a drafted shelf, a note's title on the line its drawing stands on), keep margin notes in the open space beside the column, and put illustrations inside the text, full measure or small with the text wrapping round.
+- **Do** set headlines and section heads in Bricolage Grotesque 800, tight; keep Atkinson Hyperlegible Next for text.
+- **Do** give every drawing colour a dark pair; at night the drafting blue is a light blue line on the dark paper.
+- **Do** carry a stage as a word as well as a mark, and label every drawing that says something.
+- **Do** keep sample content marked as sample, in source and on the page.
+
+### Don't:
+
+- **Don't** use a single highlighter wash as a drawing's only colour.
+- **Don't** put a drawing on a blueprint-blue ground, or on any coloured ground.
+- **Don't** use dot grids or design-tool chrome: selection boxes, handles, frame labels, outline mode.
+- **Don't** make flat cut-paper shapes.
+- **Don't** draw pencil without drafting: a sketch always carries its measurements, centres and numbered parts.
+- **Don't** use painted rasters (gouache, crayon, generated images) for the writer's drawings.
+- **Don't** letter a whole drawing in ballpoint and hand lettering; the hand is for margin notes only.
+- **Don't** trace a faint exact drawing over in pencil.
+- **Don't** bring back any late-90s homepage device: grey grounds, raised white panels, bevelled buttons, Georgia and Verdana, web-safe colours, hazard stripes, boxed layouts.
+- **Don't** use a waving-hand greeting, emoji as bullets, or an "edit ✏️" link, and don't lift copy or illustration style from the concept reference.
+- **Don't** add shadows, glows, cards or panels; the page is flat and hung from the left.
+- **Don't** use the amber for anything but New and Updated, or colour links by hue.
+- **Don't** wobble a Scene's coordinates by hand or write three versions of a drawing; describe it once and let the stage draw it.
+- **Don't** add a logo, wordmark or identity beyond the name plain-garden.