@gjermundgaraba-designs/simple-rat 0.0.0-stage → 0.7.0

package/DESIGN.md

@@ -0,0 +1,397 @@
+---
+name: simple rat
+description: A plain page design system for references, docs and blogs. One monospace font, one 80ch column, a warm grey page, underlined blue links, the browser's own lists and tables; tokens, one stylesheet and Foldkit components.
+colors:
+  ground: "#e8e7e3"
+  ground-dark: "#080807"
+  ink: "#34322b"
+  ink-dark: "#e3ded5"
+  muted: "#5f5b53"
+  muted-dark: "#958f85"
+  rule: "#b7b5ad"
+  rule-dark: "#3a3834"
+  link: "#1f3fc4"
+  link-dark: "#9db8ff"
+  visited: "#5a2e91"
+  visited-dark: "#c9a9f2"
+  code-fill: "#dad8d1"
+  code-fill-dark: "#1a1917"
+  code-rule: "#a9a69d"
+  code-rule-dark: "#44423d"
+  code-ink: "#3d3a34"
+  code-ink-dark: "#d4cec4"
+  mark: "#eed596"
+  mark-dark: "#3b3222"
+  red: "#b0342d"
+  red-dark: "#f2645b"
+  t-kw: "#7832d2"
+  t-kw-dark: "#cba6f7"
+  t-str: "#2a6a1c"
+  t-str-dark: "#a6e3a1"
+  t-num: "#9d3e07"
+  t-num-dark: "#fab387"
+  t-ty: "#815211"
+  t-ty-dark: "#f9e2af"
+  t-fn: "#1955cb"
+  t-fn-dark: "#89b4fa"
+  t-prop: "#10666b"
+  t-prop-dark: "#94e2d5"
+  t-op: "#026389"
+  t-op-dark: "#89dceb"
+  t-com: "#595b6a"
+  t-com-dark: "#9399b2"
+  t-del: "#b90d32"
+  t-del-dark: "#f38ba8"
+typography:
+  display:
+    fontFamily: '"Berkeley Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace'
+    fontSize: "2em"
+    fontWeight: 700
+    lineHeight: 1.25
+  headline:
+    fontFamily: '"Berkeley Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace'
+    fontSize: "1.5em"
+    fontWeight: 700
+    lineHeight: 1.25
+  title:
+    fontFamily: '"Berkeley Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace'
+    fontSize: "1.17em"
+    fontWeight: 700
+    lineHeight: 1.25
+  body:
+    fontFamily: '"Berkeley Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace'
+    fontSize: "100%"
+    fontWeight: 400
+    lineHeight: 1.5
+  code-block:
+    fontFamily: '"Berkeley Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace'
+    fontSize: "0.875em"
+    fontWeight: 400
+    lineHeight: 1.25
+  diagram:
+    fontFamily: '"Berkeley Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace'
+    fontSize: "0.875em"
+    fontWeight: 400
+    lineHeight: 1.15
+spacing:
+  hair: "0.25rem"
+  sm: "0.5rem"
+  md: "0.75rem"
+  base: "1rem"
+  lg: "1.5rem"
+  xl: "2.75rem"
+  footer: "3rem"
+  indent: "4ch"
+  column: "80ch"
+components:
+  code-inline:
+    backgroundColor: "{colors.code-fill}"
+    textColor: "{colors.ink}"
+    padding: "0.1em 0.25em"
+  code-block:
+    backgroundColor: "{colors.code-fill}"
+    textColor: "{colors.code-ink}"
+    typography: "{typography.code-block}"
+    padding: "0.75rem 1rem"
+  code-tab:
+    backgroundColor: "{colors.code-fill}"
+    textColor: "{colors.muted}"
+    padding: "0 1ch"
+  copy-tab:
+    backgroundColor: "{colors.code-fill}"
+    textColor: "{colors.link}"
+    padding: "0 1ch"
+  prose-block:
+    backgroundColor: "{colors.code-fill}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body}"
+    padding: "0.75rem 1rem"
+  scheme-switch:
+    textColor: "{colors.link}"
+  skip-link:
+    backgroundColor: "{colors.ground}"
+    textColor: "{colors.link}"
+    padding: "0.25rem 1ch"
+  note:
+    textColor: "{colors.ink}"
+    padding: "0.75rem 1rem"
+  table-cell:
+    textColor: "{colors.ink}"
+    padding: "0.25rem 0.5rem"
+  kbd:
+    textColor: "{colors.ink}"
+    padding: "0 0.25ch"
+  swatch:
+    width: "2ch"
+    height: "1em"
+---
+
+# Design System: simple rat
+
+## Overview
+
+**Creative North Star: "The Rendered Markdown File"**
+
+simple rat is a page that reads like the Markdown it came from, made with more care than it lets on. Every word is set in one monospace, named Berkeley Mono first (the user's licensed font, which the package never ships; the specimen uses an installed copy) with the system monospace behind it, which is the design for anyone without a licence. Text sits at the reader's own default size, inside one 80-character column on a warm grey page (warm near-black in dark). Links are blue and underlined, purple once visited (nav links excepted), lists have bullets, the browser draws the disclosure triangles and the scrollbars. Code sits on a warm fill a clear step off the ground behind a 1px border, coloured with Catppuccin syntax (Latte in light, Mocha in dark), diagrams are drawn in box-drawing characters, and a footer is an `<hr>` and one line. The content is the interface; nothing on the page is chrome.
+
+It ships as a package with three layers on one set of values: `tokens.css` holds every colour, type, space and motion value; `simple-rat.css` styles plain elements and the few classes the design names, using the tokens only; the Foldkit components write exactly the markup the stylesheet styles and add the behaviour a stylesheet cannot. The stylesheet is the design: a page written in plain HTML against it looks the same as one built from the components.
+
+The look is a faithful port of [ratstack.sh](https://ratstack.sh/), pinned by the brief and not open for redesign. Everything the source does is kept as the source does it, except the page colours, which the user moved to anoma.ly's warm neutral, and the font, which is the user's licensed Berkeley Mono where licensed. What simple rat adds sits in two clearly separate groups: **extensions** (elements the source does not have: file tabs, notes and warnings, colour swatches, boxed keys, the copy tab, heading self-links, the `:target` wash, the scheme switch, the skip link, prose blocks) and **refinements** (precision applied to source behaviour: AA-darkened Latte accents, warm page colours in both modes, a muted token for metadata, a symmetric figure inset, diagram leading, underline offset, a focus ring). Refinement adds precision, never decoration.
+
+The world refuses the design-system showcase (swatch grids, component cards, a hero) and the developer-docs chrome (sidebars, search boxes, icon callouts); its own specimen is a set of plain pages, not a catalogue. There is no title mark before the h1: the user dropped the source's emoji slot. Nothing from Rat Stack carries over except the look and one credit line ("The look comes from ratstack.sh.").
+
+**From ratstack.sh (kept as the source does it):**
+
+- One monospace family for every word at the reader's default size (100%) with 1.5 leading.
+- One 80ch body column with 1rem padding, centred.
+- Lowercase text nav separated by middots, over an `<hr>`.
+- Blue underlined links.
+- Code and pre on a fill with a 1px border; pre set a step under the text at 1.25 leading; Catppuccin Latte syntax colours.
+- ASCII box-drawing diagrams in a `figure`, labelled as an image with `role="img"` and an `aria-label`, with a `figcaption`.
+- 1px currentColor table rules; under 40rem, stacked tables become labelled cards.
+- Footer = `<hr>` + one line.
+
+**simple rat extensions:**
+
+- File tabs (`figure.file`): a file name tab on a code block's top-left edge.
+- Notes (`aside.note`) and warnings (`aside.note.warn`).
+- Colour swatches (`.swatch`) inline in table cells.
+- Boxed `kbd`.
+- The `copy` tab on a copyable block, announced to screen readers.
+- Prose blocks: a copyable block with no language (a prompt) wraps at text size.
+- Heading self-links (`#`), shown on hover and focus, named "Link to <heading>".
+- A "Skip to content" link, visible only on keyboard focus.
+- The `:target` yellow wash, the only motion; reduced motion gets a dashed outline.
+- The scheme switch at the end of the nav: `theme: system/light/dark`, the current choice in plain text, the others as underlined words.
+
+**simple rat refinements:**
+
+- Latte accents darkened where needed to pass AA on the code fill (re-fitted to the stronger fill).
+- Page colours from [anoma.ly's notes](https://anoma.ly/notes/opencode-reloaded/) (user's choice): its warm grey ground in light and warm near-black in dark, with text one step brighter than that site's prose; muted, rules, links, visited, code fill, rule and ink, the mark wash and red all tuned to that warm neutral. Catppuccin stays in the syntax colours only (Latte, AA-darkened, in light; Mocha in dark). Both palettes via `light-dark()`; the browser baseline (evergreen, about two years) needs no fallback.
+- Berkeley Mono ([U.S. Graphics](https://usgraphics.com/products/berkeley-mono), TX-02 v2.004) named first (user's choice): the system SF Mono read too thick, Commit Mono was tried, then the user chose their licensed Berkeley Mono. Text antialiased on macOS so strokes stay thin; contextual alternates off, so text shows as typed.
+- A muted token, used only for dates, captions, file names and sample labels.
+- Figures inset symmetrically by 4ch on both sides.
+- Code blocks at 0.875em (14px at a 16px default; user's choice, 14.5px read slightly too big).
+- Diagram leading 1.15: Berkeley Mono's box glyphs are exactly 1.2em tall, so 1.2 opened hairline gaps where rows rounded to pixels; `role="img"` and the `aria-label` sit on the diagram's `pre`, not the figure, so a diagram too wide for the screen can take focus and scroll.
+- Link underline offset 0.2em, 1px thick, 2px on hover.
+- A 2px link-colour focus ring, offset 2px.
+- Nav links never show visited purple; the current page is plain text, the current section plain but underlined.
+- Coarse-pointer touch sizing on nav links, footnote numbers, the copy tab and the scheme switch, none of which moves the line it sits on; code blocks with a top-edge tab get 3.25rem of room above them so the taller tab never overlaps the text before it.
+- On a phone (≤40rem), a copyable block outside a file figure wraps instead of hiding its end.
+
+**Key Characteristics:**
+
+- One font family, one column, browser-native affordances on a warm neutral page.
+- Flat: no shadow, no radius, no gradient anywhere.
+- Every rule is 1px; the one exception is the warning's 3px double border.
+- Two palettes from one set of custom properties; the page follows the system unless `html[data-scheme]` pins it.
+- Tokens, one stylesheet on the tokens, and components that only write its markup; without a Berkeley Mono licence the system monospace is the design.
+
+## Colors
+
+A warm neutral page taken from anoma.ly's notes, blue underlined links, and Catppuccin only in the syntax colours inside code. Light is a warm grey ground with dark warm ink; dark is a warm near-black with warm off-white ink. Each token in `tokens.css` holds both values through `light-dark()`; the `-dark` keys in the frontmatter are the second value of the same custom property, not separate tokens.
+
+### Primary
+
+- **Softened Link Blue / Dark Link Blue** (`link`): every link, the `copy` tab, the scheme switch, the skip link, and the focus ring. Still unmistakably link blue, softened from pure browser blue to sit on the warm ground; a light periwinkle in dark.
+- **Visited Purple / Visited Lilac** (`visited`): visited links in the text only. Kept because the page keeps the browser's history signal; links inside a `nav` stay link blue, because a nav is a map, not a reading history.
+
+### Neutral
+
+- **Warm Grey Page / Warm Near-Black Page** (`ground`): the page background, anoma.ly's own ground in both modes, and the skip link's backing when it shows.
+- **Warm Ink / Warm Off-White Ink** (`ink`): all body text, headings, table rules (as currentColor), note borders, kbd borders, swatch outlines. One step brighter than anoma.ly's prose colour in each mode.
+- **Warm Stone / Dark Warm Stone** (`muted`): dates, figure captions, file-name tabs, sample labels (`.muted`), post meta lines, the heading `#`. Metadata only.
+- **Warm Rule Grey / Dark Warm Rule** (`rule`): the `<hr>`, blockquote bar, page scrollbar thumb, and the reduced-motion target outline.
+- **Warm Code Fill / Dark Warm Code Fill** (`code-fill`): the fill behind inline code, code blocks, file tabs and the copy tab. A clear step darker than the ground in light, a clear step lighter in dark, so a code block reads as a surface at a glance.
+- **Warm Code Rule / Dark Warm Code Rule** (`code-rule`): the 1px border on code and tabs, the text selection fill, and the code scrollbar thumb.
+- **Warm Code Ink / Dark Warm Code Ink** (`code-ink`): default text inside highlighted code blocks.
+
+### Tertiary
+
+- **Warm Yellow Wash / Dark Umber Wash** (`mark`): `<mark>` highlighting and the start colour of the `:target` wash.
+- **Warning Brick Red / Dark Warning Red** (`red`): the bold first word of a warning. Nowhere else outside code.
+- **Syntax colours** (`t-kw`, `t-str`, `t-num`, `t-ty`, `t-fn`, `t-prop`, `t-op`, `t-com`, `t-del`): Catppuccin Latte in light, every one darkened until it passes AA on the warm code fill (lowest: function blue at 4.6:1); Catppuccin Mocha, unchanged, in dark. Comments and shell command words are also italic. Diff insertions share the string green; deletions take the syntax red (`t-del`), not the page red.
+
+### Named Rules
+
+**The Warm Page Rule.** The page colours are anoma.ly's warm neutral: warm grey ground and dark warm ink in light, warm near-black ground and warm off-white ink in dark, with every other neutral tuned to the same warm hue. Links stay blue, underlined, and purple when visited. Catppuccin lives only in the syntax colours inside code. Don't cool the ground, swap link blue for a brand hue, or drop the underline.
+
+**The Muted-Is-Metadata Rule.** The muted token is for dates, captions, file names, sample labels and the heading `#`. Body prose, headings and table text are never muted.
+
+**The Earned AA Rule.** Every colour that carries text passes AA on its own fill in both palettes, syntax colours included. A new Latte accent is darkened until it passes on the code fill before it ships; if the code fill changes, every light syntax colour is re-fitted to it.
+
+## Typography
+
+**Display Font:** none separate; headings use the body stack.
+**Body Font:** Berkeley Mono, where licensed (with ui-monospace, SFMono-Regular, Menlo, Consolas, monospace, which is the design without a licence)
+**Label/Mono Font:** the same family; there is only one.
+
+**Character:** One neutral monospace for every word, shown exactly as typed, at whatever size the reader set. Hierarchy comes from the browser's own heading sizes and bold, nothing else.
+
+**Font files.** The stack lives in the `--font` token. Berkeley Mono ([U.S. Graphics](https://usgraphics.com/products/berkeley-mono), TX-02 v2.004) is licensed to the user, so the package declares no `@font-face` and ships no font. A site with its own licence serves the four unmodified vendor faces under the family name `"Berkeley Mono"`: `BerkeleyMono-Regular` (400 normal), `BerkeleyMono-Oblique` (400, declared `font-style: italic`), `BerkeleyMono-Bold` (700) and `BerkeleyMono-Bold-Oblique` (700 italic), about 30 KB each, `font-display: swap`; it may preload the regular face. The specimen serves no font files: `site/fonts.css` declares the four faces from a copy installed on the machine (`local()`, by PostScript name, the static faces or the variable font), so the font is never in the repository and nothing is requested; without an installed copy the page uses the system monospace. A site without a licence does nothing, and the system monospace is the design. On macOS and Linux it has Berkeley Mono's 0.6em advance; on Windows, Consolas is narrower (0.55em), so there the column widens about 9% when Berkeley Mono arrives. Lines never re-wrap: the column is measured in `ch`. The page is antialiased on macOS (`-webkit-font-smoothing: antialiased`, `-moz-osx-font-smoothing: grayscale`) and contextual alternates are off (`font-variant-ligatures: no-contextual`) so `=>` never turns into an arrow and `...` never merges.
+
+### Hierarchy
+
+- **Display** (bold, 2em, 1.25): the page h1, once per page. Balanced wrapping.
+- **Headline** (bold, 1.5em, 1.25): h2 sections, with 2.75rem above and 1rem below.
+- **Title** (bold, 1.17em, 1.25): h3 subsections, 2rem above and 0.75rem below.
+- **Body** (normal, 100% of the reader's default, 1.5): prose, lists, tables, nav, footer. The line is capped at 80ch by the column.
+- **Code block** (normal, 0.875em, 1.25): every `pre`; 14px at a 16px default, a step under the text so code and prose read as two voices. Measured capacity: a little over 80 characters in a full-width block on desktop (83), 74 in an indented figure, 38 on a 390px phone. Tab size 2.
+- **Prose block** (normal, 1em of the body, 1.5): a copyable block whose code has no language, such as an agent prompt; it wraps (`pre-wrap`) and reads like prose on the code fill.
+- **Diagram** (normal, 0.875em, 1.15): `pre[role="img"]`. Keep a diagram within 70 characters to fit an indented figure on a wide screen, within 36 to fit a phone (36 fits a 375px phone). Wider ones scroll. Draw in light box drawing, double for at most one box, with ▶ (U+25B6), ▲ and ▼ as arrowheads. Berkeley Mono has light and double lines and those arrowheads, but no heavy lines (━ ┃ ┏ …), no rounded corners (╭ ╮ ╯ ╰) and no ► (U+25BA).
+- Inline `code`, `kbd` and `small` inherit the body size; `sup` is 0.75em.
+
+### Named Rules
+
+**The One Stack Rule.** Every word is Berkeley Mono where it is licensed, with the system monospace stack (ui-monospace, SFMono-Regular, Menlo, Consolas, monospace) behind it, the same width on macOS and Linux and a little narrower on Windows. One family: no second family, no display face.
+
+**The Reader's Size Rule.** The root is 100%; all sizes are em or rem from there. Never pin the root in px.
+
+**The Three Leadings Rule.** Prose (and prose blocks) 1.5, code and headings 1.25, diagrams 1.15 (`--leading`, `--leading-tight`, `--leading-diagram`). Nothing else.
+
+**The Own Licence Rule.** Berkeley Mono is licensed to the user and is never part of the package. Use it only with a licence of your own; otherwise the system monospace fallback is the design.
+
+## Layout
+
+One column, 80ch wide (`--column`), centred, with 1rem padding on every side and every viewport. There is no grid, sidebar or multi-column section; wide tables, code and diagrams scroll sideways inside the column instead of breaking it. Long words that would overflow break (`overflow-wrap: break-word`) in prose; table cells do not break words, and code in a table cell does not wrap.
+
+Vertical rhythm is in rem, from the spacing tokens: 0.25rem between list items (`--space-hair`), 0.5rem around the `<hr>` and under the nav (`--space-sm`), 1rem between paragraphs and blocks (`--space-base`), 1.5rem around figures, tables and notes (`--space-lg`), 2.75rem above an h2 (`--space-xl`), 3rem above the footer (`--space-footer`). Horizontal insets are in ch: lists, definitions and blockquotes indent 4ch (`--indent`); figures inset 4ch on both sides (file figures sit flush). The post list is a two-track grid: a 10ch date track and the title, 2ch apart. A few single-use geometries stay literal in the stylesheet: 2.25rem of room above a tabbed block (3.25rem on coarse pointers), 2.5rem above the pager and footnotes, 0.625rem touch padding.
+
+At 40rem and below: stacked tables (cells carrying `data-label`) drop their header and stack each row into a 1px-bordered card whose cells are prefixed by their bold column label and break long words anywhere; tables without labels stay tables and scroll sideways; figures lose their inset; a copyable block outside a file figure wraps (`pre-wrap`, `overflow-wrap: anywhere`) so a one-line command keeps its end in view. On coarse pointers, nav links and footnote numbers get `0.625rem 0.5ch` of padding taken back by `-0.5ch` inline margin, the copy tab and scheme switch grow 0.625rem of padding top and bottom (the switch takes it back in negative margin, so the nav line does not move).
+
+**The One Column Rule.** Every page is the same 80ch column. Anything wider scrolls inside it.
+
+## Elevation & Depth
+
+Flat. There are no shadows, no gradients and no layering. Depth is conveyed only by the code fill (a warm surface one step off the ground: darker in light, lighter in dark) and 1px rules. The one moment of change is the `:target` wash: a followed anchor, footnote or back-reference washes yellow and fades to transparent (`--wash`: 1.6s, `cubic-bezier(0.16, 1, 0.3, 1)`, 0.1s delay); under reduced motion it is a static 1px dashed muted outline instead.
+
+**The Flat Paper Rule.** Nothing lifts. If an element needs separation, it gets a 1px rule or the code fill.
+
+**The One Moment Rule.** The `:target` wash is the only motion. Links and controls change underline thickness on hover, instantly.
+
+## Shapes
+
+Square corners everywhere (no radius is declared). Borders are 1px solid: `currentColor` for tables, notes and kbd; `code-rule` for code and tabs; `rule` for the hr and blockquote bar. The warning is the one heavier line, a 3px double border. Tabs sit on a code block's top edge, open at the bottom, so tab and block read as one shape. Diagrams are drawn in box-drawing characters, not CSS boxes.
+
+**The 1px Rule.** Every line is 1px. The warning's 3px double is the only exception.
+
+## Components
+
+The components are Foldkit: Views and Submodels over `foldkit`, each a namespace exported from `src/index.ts` and living in `src/<name>/`. Each renders exactly the markup below it and nothing the stylesheet does not already style; plain elements (paragraphs, lists, quotes, definitions, `kbd`, `mark`, `small`, `time`, `details`) have no component. A View is `X.view(config, h)`; a Submodel (`Scheme.SchemeSwitch`, `CopyTab`) has a Model, Message, `init`, `update` and a `view` the page embeds with `h.submodel`.
+
+### Links and text controls
+
+- **Links:** link blue, 1px underline at 0.2em offset; visited purple; hover thickens the underline to 2px. A link wrapping `code` takes the link colour.
+- **Focus:** 2px solid link-colour outline, 2px offset, on links, buttons, summaries and scrollable `pre`.
+- **`SkipLink`** (`a.skip`): "Skip to content" first in the body, held off-screen until focused, then shown at 1rem, 1rem on the ground with 0.25rem 1ch padding; lands on `main#main`. A Foldkit application hands a fragment on the page being read back to the browser with `load(href)` from `foldkit/navigation`, so `:target` and the skip land.
+- **`.visually-hidden`** (class, no component): a 1px clipped box for words only assistive tech needs, such as the copy tab's status.
+- **Text controls** (the `copy` tab, the scheme switch): buttons that look like links, link blue and underlined, with no fill (the copy tab keeps the code fill so it reads as a tab).
+
+**The Text Control Rule.** Controls are words. No filled buttons, no icons, no pills.
+
+### Navigation
+
+- **`Header`** writes `header > nav[aria-label="Primary navigation"] + hr`. Its first item stands alone; each later item sits in a `span` with a middot and a space before it (`<span>· …</span>`, an `inline-block` at most the line wide), so a wrapped line starts with the middot and never ends on one; an item wider than the line breaks inside (`overflow-wrap: anywhere`) rather than widening the page.
+- **`NavLink`** (`a`) is a lowercase link. `current: "Page"` writes `aria-current="page"`: plain ink, no underline. `current: "Section"` writes `aria-current="true"`: ink, underline kept (a post's blog link). Nav links never turn visited purple.
+- **`Scheme.SchemeSwitch`** (a Submodel; `span.theme[role=group][aria-label=Theme]` of three `button[type=button][tabindex="0"][aria-pressed]`, each built on `@foldkit/ui`'s Button), last in the header: `theme: system/light/dark`, the words written in the view. The current choice is plain text in the ink colour; the other two are underlined link-blue words. System follows the reader's system through `color-scheme` alone, with no script. Light or dark pins `html[data-scheme]` (`light` or `dark`) and saves the same value in `localStorage` under `simple-rat-scheme`, through its own `PinScheme` Command (storage that refuses still switches the page; System takes both away); `Scheme.schemeScript`, inline in the head, applies a saved `light` or `dark` before first paint and ignores anything else, which falls back to System. The switch needs no service and no Subscription: it renders on a server as System, and its `init` returns a `ReadScheme` Command, which the browser runs after hydration (the server ignores it) to read the scheme the script pinned. A choice made in another tab is seen on reload, not live.
+
+### Code
+
+- **Inline:** code fill, 1px code-rule border, 0.1em 0.25em padding, body size.
+- **`CodeBlock`** writes `pre > code`: code fill, 1px code-rule border, 0.75rem 1rem padding, 0.875em / 1.25, scrolls sideways. `lang` (one of `Code.LANGUAGES`: `ts`, `tsx`, `sh`, `json`, `css`, `html`, `diff`) sets `code.language-*`, which gives the block the code-ink. `lines` colours the code: spans whose inline colour is a `var(--t-*)` token, italic for comments and shell commands; the rest takes code-ink, and a block without `lines` is plain text. The lines are data, made by Shiki with the package's theme while the site is built, so a page carries the colours and no highlighter: an import with the query `?lines=<lang>` is a file's `{ code, lines }`, spread into the config (`codeLines()`, see Adopting the system). Only a block that actually overflows takes focus: `Scrolls.WatchOverflow`, a Mount on the `pre`, makes it `role="region"` named "Code: <file or first line>, scrolls sideways" with `tabindex="0"`, re-checked whenever the block changes size, and takes the attributes away when the block leaves the page; blocks that fit stay out of the tab order. The Mount reports through `toParentMessage`, which the page may ignore.
+- **Prose block:** a block with a `copy` tab and no `lang`; same fill and border, body size, 1.5 leading, wrapping.
+- **File tab:** a `file` wraps the block in `figure.file` with the name in its `figcaption`, a muted tab on the top-left edge. The tabs stand in a row of their own on the block's top edge: a long name wraps inside its tab, and the copy tab keeps its width beside it, so the two never overlap and the page never widens.
+- **Copy tab:** `copy` is the page's **`CopyTab`** (a Submodel) rendered through `h.submodel` with `CodeBlock.copyInputs(code, file?)` and the block's `toBlockView`; it sets `pre[data-copy]` and wraps it in `div.copyable` with a `button[type=button][tabindex="0"]` after it, built on `@foldkit/ui`'s Button, and a visually hidden `role="status"`. The link-blue `copy` tab on the top-right answers `copied` (or `select and copy` when the clipboard refuses) and turns back after 1.6s; it takes a press only while it reads `copy`, so one answer ends before the next copy starts (from the press until it reads `copy` again, the button is held: `aria-disabled="true"` and `data-disabled`, with no click handler); its accessible name is "Copy <file name or first line>". It writes through Effect's `Clipboard` port: provide `Clipboard.layer` from `@effect/platform-browser` in the application's `resources`. Both tabs: code fill, 1px code-rule border with no bottom edge, 0 1ch padding, 1.5 leading; a block with only the copy tab gets 2.25rem of room above for it.
+
+### Figures and diagrams
+
+- **`Diagram`** writes `figure > pre[role="img"][aria-label] > code` then a muted `figcaption` 0.5rem below (the `caption`, defaulting to the `label`). The role sits on the `pre`, so an overflowing diagram can take focus and scroll (`Scrolls.WatchOverflow`, given no name, gives it `tabindex="0"` and leaves its image role alone). Inset 4ch each side; 0.875em, leading 1.15; at most 70 characters wide, 36 to fit a phone. Light lines, double for at most one box, arrowheads ▶ ▲ ▼; never a glyph the font lacks.
+
+### Tables
+
+- **`Table`** writes `div.table-scroll > table > thead + tbody`. The table keeps `display: table`; the wrapper (`overflow-x: auto`) scrolls a table wider than the column sideways, on a phone too. 1px currentColor cell rules, 0.25rem 0.5rem padding, left and top aligned. Headers, code in cells and swatch cells never wrap. **`isStacked: true`** (opt-in; off by default) also writes `data-label` on each cell from its column and the ARIA table roles on every part (`table`, `rowgroup`, `row`, `columnheader`, `cell`), because WebKit drops table semantics once CSS changes a table's display, which the stacked cards do: under 40rem each labelled row becomes a bordered card with bold `label:` prefixes. A table that is not stacked needs no roles.
+- **`Swatch`** (`span.swatch`): a 2ch × 1em box with a 1px ink outline before a colour value in a cell.
+
+### Notes and warnings
+
+- **`Note`** (`aside.note > p > strong + …`): a 1px currentColor box, 0.75rem 1rem padding, the first word bold ("Note."). At most one per screen.
+- **`isWarn`** (`aside.note.warn`): a 3px double border and a red first word ("Warning."). Only for real consequences.
+
+### Footnotes
+
+- **`Footnotes`**: `refView` writes `sup > a#ref-N[href="#fn-N"]`; `view` writes `section.footnotes[aria-label="Footnotes"] > hr + ol > li#fn-N`, each note ending in a `Back` link to its reference, named "Back to reference N" so each note's link says where it goes. The section sits 2.5rem below the text; both ends take the `:target` wash.
+
+### Blog pieces
+
+- **`PostList`** (`ul.posts > li > time + a`): a two-track grid, a 10ch date track and the title, 2ch apart, grouped under year headings.
+- **`PostMeta`** (`p.meta`): everything about a post on one muted line, pulled 0.5rem up under the h1: the `time`, then " · " and the rest, e.g. "5 min read · sample post, fictional date".
+- **`Pager`** (`nav.pager`): Newer, Older and the way back to all posts, one line each, 2.5rem below; a missing neighbour becomes a muted "This is the newest post." or "This is the oldest post."
+
+### Small pieces
+
+- **kbd** (extension): a 1px currentColor box, 0 0.25ch padding, the body font.
+- **Blockquote** (source): 1px rule bar on the left, 4ch indent.
+- **`Heading`** (extension; `h2`/`h3 > a.self`): writes the heading (level 2 or 3) with a muted `a.self` `#` after it, visible on hover and focus only, named "Link to <text>". The page title is a plain `h1`.
+- **`Footer`** (source): `footer > hr + p`, one line, ending with the credit "The look comes from ratstack.sh."
+- **Not found:** a plain page like the rest; the host must serve it with a 404 status for every unknown address. The specimen writes it at `/404`, which is no route of its own: it parses to the `NotFound` fallback like any address nothing lives at.
+
+### Adopting the system
+
+Install the package (README.md beside this file says how), install its peers (`foldkit`, `@foldkit/ui`, `effect`, `@effect/platform-browser`, and `@foldkit/vite-plugin` for `./highlight/vite`) and import the stylesheet once. The package is compiled JavaScript with its types and its views already branded, so the site's build needs only `foldkit()` beside what it imports:
+
+- `.`: every component above as a namespace, `Code` (`LANGUAGES` and the types of a block's coloured lines), `Scheme` (`Scheme`, `SchemeSwitch`, `schemeScript`) and `Scrolls`. Nothing it reaches imports Shiki. Every component renders on a server.
+- `./highlight`: `highlight(code, lang)`, which colours code with Shiki and the package's theme (its scopes mapped to the `--t-*` tokens) and returns the lines `CodeBlock` takes. It is for a build, never a page: importing it builds the highlighter. Shiki comes with the package.
+- `./highlight/vite`: `codeLines()`, a Vite plugin that runs `highlight` while the site is built; add it to the build's `plugins`, beside `foldkit()`. An import with the query `?lines=<lang>`, as in `import retry from "./code/retry.txt?lines=ts"`, is the file's text and its lines, `{ code, lines }`, and the file is watched, so a change colours it again. Code the toolchain should not check or format goes in a `.txt`; a source file can be imported twice, to run and to show. The imports are typed by `src/code/lines.d.ts`, an ambient module declaration for each language, which `src/code/code.ts` references: a program that imports `simple-rat` has them, with nothing to add to its `tsconfig`. A build without Vite calls `highlight` itself and passes the lines on.
+- `./scheme`: `schemeScript`, `SCHEME_STORAGE_KEY` and `SCHEME_ATTRIBUTE` alone, for a build that writes `schemeScript` into a page's head.
+- `./tokens.css`: the tokens alone.
+- `./simple-rat.css`: the stylesheet; it imports `tokens.css` from beside it.
+
+Without Foldkit, link `simple-rat.css` (with `tokens.css` beside it) and write the markup each component above names: the page frame is `body > a.skip + header + main#main + footer`; for code colours write a `span` for each coloured run, as the code blocks on the reference do (the colours name the `--t-*` tokens, so they follow the page's scheme); wrap each table in `div.table-scroll` so a wide one scrolls; only a table that should stack needs `data-label` cells and the ARIA table roles (`role="table"`, `rowgroup`, `row`, `columnheader`, `cell`), and a table that stays a table needs neither; put `schemeScript` inline in the head and build the switch from the Navigation contract, or leave dark mode to the system. Behaviour that needs script (copy tabs, the scheme switch, focus on scrolling blocks) is the components' job; a plain page reads the same without it.
+
+## 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/note/` or `src/footer/`; a View that owns a Mount (`src/codeBlock/`, `src/diagram/`) takes a required `toParentMessage`. A **Submodel** has a Model, Message, `init`, `update` and a `view` made with `defineView`, embedded with `h.submodel`. Copy `src/copyTab/` (a Command through a platform port; `src/copy/copy.ts` holds the Model, Messages, Commands and update, the same file in every system, and `copyTab.ts` adds this system's view) or `src/scheme/` (Commands that touch the document directly and a Command from `init`; `switch.ts` holds the Model, Messages, Commands and update, the same file in every system, and `schemeSwitch.ts` adds this system's view). A browser service that Effect already ports (`Clipboard`) is required from the application; what the component can do itself in a Command (an attribute on `<html>`, a `localStorage` entry) it does there, with no service.
+
+Each component is `src/<name>/<name>.ts` with an explicit `index.ts` (its public surface, which only `src/index.ts` imports; a sibling or a test imports the file that defines what it needs), a colocated `<name>.test.ts` (a Story for update, a Scene for view), an `export * as` line in `src/index.ts`, a place on the specimen (the reference page, or for the blog pieces the blog and post pages), and an entry in this document.
+
+1. **Markup is the contract.** A component writes exactly the markup the Components section names, with the classes, roles and ids a page without Foldkit writes by hand; the stylesheet styles that markup and nothing else.
+2. **One vocabulary.** `label` is a control's or a link's words (`NavLink`'s, each of `Pager`'s links) or a group's name; `text` is a heading's words; `body` is content, `ReadonlyArray<Html | string>`. Booleans read as questions (`isWarn`, `isStacked`); an `Option` is `maybe*` (`Scrolls.WatchOverflow`'s `maybeName`); literal choices are capitalised in the domain (`"System"`, `"Light"`, `"Dark"`; `NavLink`'s `"Page"`, `"Section"`) and shown in the page's own words, written in the view (`system`, `light`, `dark`).
+3. **Slots.** A content slot in a View's config is a value. In a Submodel's view inputs, markup that carries the page's handlers or Mounts is a top-level function, `toXView: () => Html` (`CopyTab`'s `toBlockView`), never nested Html, because a Submodel's view runs in its own Message boundary.
+4. **Parents never read a child's Model.** A Submodel exports accessors for what a parent needs (`CopyTab.id`, `Scheme.SchemeSwitch.id`), and the parent calls them, including for `slotId`.
+5. **Instances are scoped by id.** A Submodel's `slotId` is its own id from `init`.
+6. **A Mount owns what it writes.** A Mount that adds attributes (`Scrolls.WatchOverflow`'s `tabindex`, `role`, `aria-label`) takes them away in its release, and reports that it ran (`CompletedWatchOverflow`, named for the Mount) through the parent's `toParentMessage`; in a Scene, let the test's parent take the Mount's Message as its own (an identity `toParentMessage`) and resolve the Mount by its definition.
+7. **Platform services are the application's.** A component that needs one says so in its TSDoc and here (`CopyTab` writes through Effect's `Clipboard`), and the application provides the Layer in its `resources`; `SchemeSwitch` needs none.
+8. **A Scene test for every accessibility contract** a component adds: roles, accessible names, `aria-pressed`, `aria-current`, `data-label`, the status region. Behaviour that only a real element shows (the overflow Mount) gets a test with real DOM in happy-dom, no mocks.
+9. **Fragment links go back to the browser.** A link to `#id` (the skip link, footnotes, heading links) is routed by Foldkit, so the application hands a fragment on the page being read back to the browser with `load(href)` from `foldkit/navigation`, which marks `:target` and moves the keyboard.
+10. **No module-level state and no clocks in views.** Build-time code lives in `highlight/`, beside `src/` and never inside it: Shiki's highlighter, built once as a module constant (`highlight/highlight.ts`), and the Vite plugin that reads files (`highlight/vite.ts`), published as `./highlight` and `./highlight/vite`. The folder is the boundary: `highlight/` may import from `src/`, and nothing in `src/` imports from `highlight/`. Everything that changes lives in a Model or inside a Mount's scope.
+
+## Do's and Don'ts
+
+### Do:
+
+- **Do** adopt by installing the package and importing the `./simple-rat.css` export once; write plain semantic HTML and reach for a component only where the design names one.
+- **Do** put `schemeScript` inline in the head of every page, before the stylesheet, when the site has a `SchemeSwitch`.
+- **Do** keep every word in one monospace (Berkeley Mono where licensed, the system monospace otherwise) at the reader's default size, 1.5 leading, in one 80ch column with 1rem padding.
+- **Do** give every diagram a `label` and a visible caption (`Diagram` does both).
+- **Do** keep diagrams within 70 characters for a wide screen and within 36 to fit a phone (36 fits 375px).
+- **Do** draw diagrams in light box drawing, double for at most one box, with ▶ ▲ ▼ arrowheads.
+- **Do** keep sample content labelled on the page and in source; a sample post says so at the end of its meta line ("sample post, fictional date"), and a sample index says so once in a muted line.
+- **Do** darken any new light-mode syntax accent until it passes AA on the code fill.
+- **Do** change values in `tokens.css` only; the stylesheet and components read them from there.
+- **Do** keep the footer to an `<hr>` and one line carrying the credit "The look comes from ratstack.sh."
+- **Do** serve the 404 page with a 404 status for every unknown address.
+
+### Don't:
+
+- **Don't** add a second family or a display face; the one font is Berkeley Mono, with the system monospace as its fallback.
+- **Don't** use a glyph Berkeley Mono lacks inside a diagram: heavy lines (━ ┃ ┏ …), rounded corners (╭ ╮ ╯ ╰) or ► (U+25BA); the fallback font draws it at another width and breaks the grid.
+- **Don't** ship or declare Berkeley Mono in the package; it is licensed per user, and without your own licence the system monospace is the design.
+- **Don't** add shadows, radius, gradients or any rule heavier than 1px (the warning's 3px double excepted).
+- **Don't** add a title mark or emoji before the h1.
+- **Don't** add sidebars, search boxes, icon callouts, a hero, or grids of component cards or swatches.
+- **Don't** use icons for controls; controls are underlined words.
+- **Don't** add motion beyond the `:target` wash.
+- **Don't** give a component markup the stylesheet does not style, or a look the plain HTML cannot reach.
+- **Don't** name Rat Stack, its products or its vocabulary anywhere but the footer credit and one sentence on the name.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gjermund Garaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @gjermundgaraba-designs/simple-rat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A design system from [my-designs](https://github.com/gjermundgaraba/my-designs): tokens, a
+stylesheet, fonts where it ships its own, and [Foldkit](https://foldkit.dev) components.
+`DESIGN.md`, beside this file, is the design record: what each component is for, its markup
+and classes, and the rules. It ships in the package, so an adopting project's agents can
+read it in `node_modules`.
+
+## Install
+
+```bash
+pnpm add @gjermundgaraba-designs/simple-rat
+```
+
+Install its peers beside it, the `peerDependencies` in `package.json`: `foldkit`,
+`@foldkit/ui`, `effect` and `@effect/platform-browser`. Foldkit pins `effect` and
+`@effect/platform-browser` exactly as peers; an app on a later patch keeps one Effect
+instance by allowing it in pnpm:
+
+```yaml
+# pnpm-workspace.yaml
+peerDependencyRules:
+  allowedVersions:
+    effect: <the app's version>
+    "@effect/platform-browser": <the app's version>
+```
+
+## Set up
+
+The package is compiled JavaScript with its types, its views already branded for Foldkit's
+view identity, so it needs nothing in the app's build beside `foldkit()`. Import the
+stylesheet once, from the client entry:
+
+```ts
+import "@gjermundgaraba-designs/simple-rat/simple-rat.css";
+import { Scheme } from "@gjermundgaraba-designs/simple-rat";
+```
+
+The stylesheet follows the reader's colour scheme with no script; `Scheme.SchemeSwitch`
+lets them pin one, and `schemeScript` applies it before first paint. Write it into the
+head, in a Vite app from `vite.config.ts`:
+
+```ts
+import { schemeScript } from "@gjermundgaraba-designs/simple-rat/scheme";
+
+export default defineConfig({
+  plugins: [
+    foldkit(),
+    {
+      name: "scheme-script",
+      transformIndexHtml: () => [
+        { tag: "script", children: schemeScript, injectTo: "head-prepend" },
+      ],
+    },
+  ],
+});
+```
+
+Provide `Clipboard.layer` as the application's resources where a component copies.
+`DESIGN.md` has the rest: each component, how links and fragments are handled, and the
+rules a new component follows.
+
+## Licence
+
+MIT. Fonts in `fonts/`, where the package has them, carry their own licence beside them.

package/dist/highlight/highlight.d.ts

@@ -0,0 +1,5 @@
+import type { Language, Lines } from "../src/code/code.ts";
+/** A block's runs, line by line, for `CodeBlock`'s `lines`. A run in the plain code ink,
+    upright, has no colour. */
+export declare const highlight: (code: string, lang: Language) => Lines;
+//# sourceMappingURL=highlight.d.ts.map

package/dist/highlight/highlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight.d.ts","sourceRoot":"","sources":["../../highlight/highlight.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAwG3D;8BAC8B;AAC9B,eAAO,MAAM,SAAS,SAAU,MAAM,QAAQ,QAAQ,KAAG,KAQtD,CAAC"}

package/dist/highlight/highlight.js

@@ -0,0 +1,120 @@
+import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
+// Syntax colours for code blocks, by Shiki, for a build to run: the theme maps TextMate
+// scopes to the --t-* tokens in tokens.css (Catppuccin: Latte in light, darkened for AA;
+// Mocha in dark), so the colours switch with the page. It sits outside src/, which never
+// imports it: a page is given the lines `highlight` made (vite.ts makes them of a file).
+import { createHighlighterCoreSync } from "shiki/core";
+import { createJavaScriptRawEngine } from "shiki/engine/javascript";
+import css from "@shikijs/langs-precompiled/css";
+import diff from "@shikijs/langs-precompiled/diff";
+import html from "@shikijs/langs-precompiled/html";
+import json from "@shikijs/langs-precompiled/json";
+import shellscript from "@shikijs/langs-precompiled/shellscript";
+import tsx from "@shikijs/langs-precompiled/tsx";
+const t = (token) => __foldkitBrandViewResult((`var(--t-${token})`), "@gjermundgaraba-designs/simple-rat/highlight/highlight.js#t");
+const codeTheme = {
+    name: "simple-rat",
+    type: "light",
+    colors: { "editor.foreground": "var(--code-ink)", "editor.background": "var(--code-fill)" },
+    tokenColors: [
+        {
+            scope: ["comment", "punctuation.definition.comment", "meta.diff.header"],
+            settings: { foreground: t("com"), fontStyle: "italic" },
+        },
+        {
+            scope: [
+                "string",
+                "punctuation.definition.string",
+                "string.unquoted.argument",
+                "markup.inserted",
+            ],
+            settings: { foreground: t("str") },
+        },
+        {
+            scope: [
+                "constant.numeric",
+                "constant.language",
+                "constant.character",
+                "constant.other.color",
+                "keyword.other.unit",
+                "support.constant.property-value",
+                "variable.language.this",
+            ],
+            settings: { foreground: t("num") },
+        },
+        {
+            scope: [
+                "keyword",
+                "storage.type",
+                "storage.modifier",
+                "keyword.control.at-rule",
+                "support.function.misc.css",
+                "support.function.transform.css",
+                "meta.diff.range",
+            ],
+            settings: { foreground: t("kw") },
+        },
+        {
+            scope: [
+                "keyword.operator",
+                "punctuation.definition.tag",
+                "storage.type.function.arrow",
+                "punctuation.separator.pipe",
+            ],
+            settings: { foreground: t("op") },
+        },
+        {
+            scope: [
+                "entity.name.type",
+                "support.type.primitive",
+                "support.class",
+                "entity.other.inherited-class",
+                "entity.other.attribute-name",
+                "entity.name.tag.css",
+                "support.type.builtin",
+            ],
+            settings: { foreground: t("ty") },
+        },
+        {
+            scope: [
+                "entity.name.function",
+                "support.function",
+                "entity.name.tag",
+                "support.class.component",
+                "support.type.property-name",
+                "variable.css",
+            ],
+            settings: { foreground: t("fn") },
+        },
+        {
+            scope: ["entity.name.command", "support.function.builtin.shell"],
+            settings: { foreground: t("fn"), fontStyle: "italic" },
+        },
+        {
+            scope: [
+                "variable.other.property",
+                "variable.other.object.property",
+                "meta.object-literal.key",
+                "variable.argument.css",
+            ],
+            settings: { foreground: t("prop") },
+        },
+        { scope: "markup.deleted", settings: { foreground: t("del") } },
+    ],
+};
+// Built once, when a build first imports this file. The grammars come precompiled, so
+// nothing translates their patterns. TypeScript is read with the TSX grammar.
+const highlighter = createHighlighterCoreSync({
+    themes: [codeTheme],
+    langs: [css, diff, html, json, shellscript, tsx],
+    langAlias: { ts: "tsx" },
+    engine: createJavaScriptRawEngine(),
+});
+/** A block's runs, line by line, for `CodeBlock`'s `lines`. A run in the plain code ink,
+    upright, has no colour. */
+export const highlight = (code, lang) => __foldkitBrandViewResult((highlighter.codeToTokens(code, { lang, theme: "simple-rat" }).tokens.map((line) => __foldkitBrandViewResult((line.map((token) => {
+    // Italic is bit 1 of Shiki's font style.
+    const isItalic = ((token.fontStyle ?? 0) & 1) === 1;
+    const isPlain = token.color === "var(--code-ink)" && !isItalic;
+    return __foldkitBrandViewResult(({ content: token.content, color: isPlain ? undefined : token.color, isItalic }), "@gjermundgaraba-designs/simple-rat/highlight/highlight.js#anonymous~2");
+})), "@gjermundgaraba-designs/simple-rat/highlight/highlight.js#anonymous"))), "@gjermundgaraba-designs/simple-rat/highlight/highlight.js#highlight");