@dorsk/tsumikit 0.81.0 → 0.82.0

package/principles/14-instant-calm-feedback.md

@@ -0,0 +1,32 @@
+# Feedback is instant and calm
+
+Respond at once, show a spinner only after a short delay and keep it long enough not to flicker, and update optimistically when success is likely.
+
+## Why
+
+Doherty threshold: under about 400 ms people stay in flow. A spinner that flashes for 50 ms makes a fast response feel broken; one that never appears makes a slow response feel dead. Optimistic updates keep the interface at the user's pace, with rollback as the safety net.
+Sources: https://lawsofux.com/doherty-threshold/ , https://vercel.com/design/guidelines
+
+## Do
+
+- Wait about 200 ms before showing a loading indicator, then keep it for at least 500 ms.
+- Apply likely-to-succeed changes immediately and roll back with a message on failure.
+- Keep layout stable while loading: reserve space with skeletons, never shift content.
+- Prefer in-place indicators over page-level overlays.
+
+## Don't
+
+- Show a spinner on every click regardless of duration.
+- Block the whole page for a single row's update.
+- Animate the loading state so much that it draws more attention than the content.
+
+## In tsumikit
+
+- `pending()` helper and `Button` `loadingDelay` / `loadingMin` implement the 200 ms / 500 ms rule; `loading="done"` shows the confirmation tick.
+- `Skeleton`, `Spinner`, `Progress`, `LoadMore` for in-place loading.
+- `toasts.error()` with an action for rollback messages; `toasts.undo()` for reversible changes.
+- Motion tokens `--dur-fast`, `--dur-base`, `--ease-out` keep transitions short.
+
+## Check
+
+Throttle to a fast connection: no spinner should be visible at all. Throttle to slow 3G: a spinner appears once, stays at least half a second, and nothing on the page shifts when the data lands.

package/principles/15-undo-over-confirm.md

@@ -0,0 +1,30 @@
+# Prefer undo over confirmation
+
+Make actions reversible and offer an undo instead of asking "Are you sure?" beforehand.
+
+## Why
+
+Nielsen heuristic 3, user control and freedom: people need a clearly marked emergency exit. Confirmation dialogs are read once and then clicked through by habit, so they stop protecting anyone; undo protects every time.
+Sources: https://www.nngroup.com/articles/ten-usability-heuristics/ , https://vercel.com/design/guidelines
+
+## Do
+
+- Perform the action, then show "Moved to trash. Undo" for a few seconds.
+- Keep a confirm dialog only for truly irreversible or expensive actions (delete an account, send to many people), and name the consequence in the button ("Delete 12 files").
+- Make Escape, Back and Cancel always available and always do what they say.
+
+## Don't
+
+- Ask "Are you sure?" with generic OK / Cancel buttons.
+- Trap the user in a flow with no way out.
+- Make Undo appear only in a hidden menu.
+
+## In tsumikit
+
+- `toasts.undo()` for the reversible pattern; `Toaster` renders the action and keeps it keyboard-reachable.
+- `ConfirmModal` for the remaining irreversible cases, with a labelled destructive `Button` `variant="danger"`.
+- `SwipeRow` exposes undoable row actions on touch.
+
+## Check
+
+Perform each destructive action on the screen. Either an undo appears for it, or a confirm names exactly what will be lost. "Are you sure?" with OK / Cancel is a failure.

package/principles/16-empty-states.md

@@ -0,0 +1,31 @@
+# Empty states are design too
+
+An empty list explains what belongs there and offers the action that fills it.
+
+## Why
+
+Nielsen heuristic 6, recognition over recall, and heuristic 10, help where it is needed: the first screen a new user sees is usually empty, and a blank area makes them guess whether something is broken or missing. The empty state is the onboarding.
+Source: https://www.nngroup.com/articles/ten-usability-heuristics/
+
+## Do
+
+- Say what goes here in one sentence, in the user's words.
+- Offer the one action that fills it as the primary button.
+- Distinguish "nothing yet", "nothing matches your filter" and "failed to load"; each gets its own copy and action.
+- Keep the layout stable: the empty state occupies the same region the content will.
+
+## Don't
+
+- Render an empty table header with no rows and no message.
+- Show "No data" with no action.
+- Use the same empty state for a filtered-to-nothing result as for a fresh account.
+
+## In tsumikit
+
+- `EmptyState` with `title`, `description`, `actionLabel` and `onAction` (or an `action` snippet for several).
+- `Icon` for the illustration slot; `Callout` for the failed-to-load variant with a retry action.
+- `FilterInput` and `FilterSearchBar` give a "clear filters" path for the filtered-empty case.
+
+## Check
+
+Reach every list and table on the screen in three states: new account, filter with no match, load failure. Each must show a message and an action that makes sense for that state.

package/principles/17-errors-in-plain-words.md

@@ -0,0 +1,31 @@
+# Errors say what happened and what to do next
+
+An error message names the problem in plain language, states the cause if known, and offers the next step.
+
+## Why
+
+Nielsen heuristic 9: help users recognise, diagnose and recover from errors. "Request failed with status code 500" tells the user nothing they can act on; "Couldn't reach the indexer. It timed out after 30 s. Check that it's running, then retry." tells them everything.
+Source: https://www.nngroup.com/articles/ten-usability-heuristics/
+
+## Do
+
+- Lead with what the user wanted and could not get ("Couldn't save the profile").
+- Add the cause in one short clause when you know it.
+- Offer a concrete recovery: retry, edit the field, open settings.
+- Place field errors next to the field and mark the field itself.
+
+## Don't
+
+- Surface raw exception text, status codes or stack traces.
+- Blame the user ("Invalid input").
+- Show the error in a place the user is no longer looking at.
+
+## In tsumikit
+
+- `Callout` `tone="error"` for inline errors with an action; `toasts.error()` with an action for transient ones (assertive live region).
+- `Field` shows a field-level error next to its control and links it with `aria-describedby`.
+- Status colour `--danger` always paired with the error icon and text.
+
+## Check
+
+Trigger each failure path on the screen (offline, bad input, server error). Every message must be understandable by someone who does not know what HTTP is, and must contain a next step.

package/principles/18-match-the-real-world.md

@@ -0,0 +1,31 @@
+# Speak the user's language
+
+Words, icons and order follow the user's world, not the system's internals.
+
+## Why
+
+Nielsen heuristic 2: match between the system and the real world. Users should not have to translate "entity", "node" or "sync job" into the things they actually own. Natural ordering (recent first, alphabetical) and familiar formats (relative time, local units) reduce effort.
+Source: https://www.nngroup.com/articles/ten-usability-heuristics/
+
+## Do
+
+- Name things what users call them (a "film", not a "media item"; "folder", not "root path").
+- Format dates and durations the way people say them ("2 hours ago", "1 h 42 min").
+- Order lists the way users scan them, and say what the order is.
+- Use icons whose meaning is already established; add a label where it is not.
+
+## Don't
+
+- Expose database field names, enum values or internal IDs as labels.
+- Show ISO timestamps where a relative time would do.
+- Invent a new icon for a familiar action.
+
+## In tsumikit
+
+- `Timestamp`, `relativeTime()` and `formatTimestamp()` for human time; `TimeDisplay`, `formatMediaTime()` for durations.
+- `formatCount()` for counts with sensible rounding; `Truncate` keeps long paths readable.
+- `Icon` ships a conventional icon set; `Tooltip` adds a label where meaning is not obvious.
+
+## Check
+
+Read every label and message aloud as if to a friend who does not know the codebase. Any word you would have to explain is a label to change.

package/principles/19-consistency-and-standards.md

@@ -0,0 +1,32 @@
+# Consistency beats local cleverness
+
+The same thing looks and behaves the same everywhere, and works the way users expect from the apps they already use.
+
+## Why
+
+Nielsen heuristic 4 and Jakob's law: users spend most of their time in other applications and bring those expectations with them. Every local deviation is something to learn, and every inconsistency is a moment of doubt.
+Sources: https://www.nngroup.com/articles/ten-usability-heuristics/ , https://lawsofux.com/jakobs-law/
+
+## Do
+
+- Reuse the kit component for a job rather than restyling a near copy.
+- Keep one vocabulary: the same action has the same label and icon on every screen.
+- Follow platform conventions for selection, navigation, keyboard shortcuts and dialogs.
+- Put the same things in the same place on every page.
+
+## Don't
+
+- Build a one-off button, input or table because the kit's was "almost right".
+- Use "Remove" here and "Delete" there for the same action.
+- Change the primary button's position between pages.
+
+## In tsumikit
+
+- Atoms are the only place raw controls live; molecules compose them. Lint rule `no-raw-control` flags raw `button`, `input` and `select` in app code.
+- Theme and look tokens (`--r-control`, `--control-height`, `--btn-fill`) make every control share shape and size.
+- `canonicalTone()` and the `Tone` vocabulary unify status naming across components.
+- Lint rule `breakpoints` keeps media queries on the shared 40rem / 48rem / 64rem steps.
+
+## Check
+
+Take screenshots of the same component type across three pages and lay them side by side. They must be indistinguishable in shape, size and behaviour.

package/principles/20-error-prevention.md

@@ -0,0 +1,31 @@
+# Prevent errors before reporting them
+
+Design so the mistake cannot happen: constrain input, show consequences before commit, and make the safe path the default.
+
+## Why
+
+Nielsen heuristic 5: a careful design that prevents a problem is better than a good error message. Slips (wrong button) and mistakes (wrong mental model) have different cures: constraints and defaults for slips, previews and plain language for mistakes.
+Source: https://www.nngroup.com/articles/ten-usability-heuristics/
+
+## Do
+
+- Use the control that only allows valid values: a select, a slider, a date picker, a segmented choice.
+- Validate as the user leaves a field, not after they submit the form.
+- Separate destructive actions from frequent ones in space and style.
+- Default to the safe choice; show the effect of a setting next to it.
+
+## Don't
+
+- Accept free text where the set of valid answers is known.
+- Place "Delete" next to "Save" in the same style.
+- Validate everything only on submit and then scroll the user to the top.
+
+## In tsumikit
+
+- `Select`, `RichSelect`, `Combobox`, `Slider`, `SegmentedControl`, `RadioGroup`, `Switch` constrain input.
+- `Field` attaches help text and inline validation; `Fieldset` groups related choices.
+- `Button` `variant="danger"` plus distance in a `Toolbar` keeps destructive actions apart; `ConfirmModal` for the truly irreversible.
+
+## Check
+
+For each input on the screen, try to enter something invalid. The control should refuse or flag it before submit. For each destructive action, check it cannot be hit by a slip from a neighbouring frequent action.

package/principles/21-recognition-over-recall.md

@@ -0,0 +1,31 @@
+# Recognition over recall
+
+Show options, state and context on screen instead of making people remember them.
+
+## Why
+
+Nielsen heuristic 6 and Miller's law: working memory is small. Visible choices, remembered recent inputs and persistent context (where am I, what is selected) reduce the load; anything a user must remember from a previous screen is a defect.
+Sources: https://www.nngroup.com/articles/ten-usability-heuristics/ , https://lawsofux.com/millers-law/
+
+## Do
+
+- Show where the user is: breadcrumbs, active nav, page title.
+- Offer suggestions and recent values in inputs instead of requiring exact syntax.
+- Keep the selection visible while acting on it (toolbar shows "3 selected").
+- Reveal keyboard shortcuts next to the actions they trigger.
+
+## Don't
+
+- Require typed identifiers the user saw on another page.
+- Hide the current filter behind a closed panel with no summary.
+- Show a modal that covers the data it asks about.
+
+## In tsumikit
+
+- `Breadcrumb`, `NavBar`, `TabBar` and `Tabs` show current location; `SectionHeader` names the block.
+- `Combobox`, `FilterInput` and `suggest()` surface valid values while typing.
+- `Kbd` and `Tooltip` show shortcuts in place; `Popover` and `Drawer` reveal detail without hiding context.
+
+## Check
+
+Open any page cold. Can you tell where you are, what is selected and what filters apply without clicking anything? Then try each input without reading docs: valid values must be discoverable from the control itself.

package/principles/22-flexibility-and-shortcuts.md

@@ -0,0 +1,31 @@
+# Shortcuts for the experienced, defaults for the rest
+
+Frequent actions get accelerators (keyboard, bulk, saved filters) that newcomers can ignore.
+
+## Why
+
+Nielsen heuristic 7, flexibility and efficiency of use: the same interface serves first-time and expert users. Experts want fewer steps; novices want fewer choices. Shortcuts layered on top of a simple default serve both.
+Source: https://www.nngroup.com/articles/ten-usability-heuristics/
+
+## Do
+
+- Add keyboard shortcuts for the top actions and show them in tooltips and menus.
+- Allow bulk selection and bulk actions on lists.
+- Let filters, sort and views be saved or shared via the URL.
+- Support paste, drag and drop and type-ahead wherever they make sense.
+
+## Don't
+
+- Make shortcuts the only way to do something.
+- Override browser or OS shortcuts.
+- Hide bulk actions until a user discovers multi-select by accident.
+
+## In tsumikit
+
+- `Kbd` to display shortcuts; `Menu` items show them inline; `Tooltip` for hover hints.
+- `FilterInput` with the `filters` query grammar for saved, shareable filters; `urlState()` keeps them in the URL.
+- `Dropzone`, `FileButton` and `Composer` for drag, drop and paste; `SortableList` for keyboard-reorderable lists.
+
+## Check
+
+Do the three most frequent tasks on the screen without a mouse. Each should take fewer keystrokes than clicks. The shortcuts must be visible somewhere on the screen.

package/principles/23-url-is-state.md

@@ -0,0 +1,31 @@
+# The URL is state
+
+Filters, tabs, sort and pagination live in the URL so they survive refresh, Back and sharing.
+
+## Why
+
+Vercel and Rauno Freiberg interface guidelines: a view a user cannot link to or return to is lost work. Back must restore both the view and its scroll position; a pasted link must open the same thing the sender saw.
+Sources: https://vercel.com/design/guidelines , https://interfaces.rauno.me/
+
+## Do
+
+- Encode the active tab, filter query, sort column and page in the query string or path.
+- Restore scroll position on Back and Forward.
+- Make the active state of tabs and segments come from the URL, not from component memory.
+- Use `replaceState` for typed-ahead changes and `pushState` for navigational ones.
+
+## Don't
+
+- Keep tab or filter state only in a store that resets on refresh.
+- Reset to page 1 and clear filters when the user presses Back.
+- Encode state that is not shareable (a hover, an open menu).
+
+## In tsumikit
+
+- `urlState()` binds a value to a query parameter.
+- `Tabs`, `SegmentedControl` and `Pagination` accept `href` per item so the active state is a real link.
+- `FilterInput` with `serialize()` and `parse()` round-trips filter queries through the URL.
+
+## Check
+
+Set a filter, switch a tab, go to page 3, then refresh and press Back twice. Every step must restore exactly what was on screen, and the URL at each step must open the same view in a new window.

package/principles/24-links-are-links.md

@@ -0,0 +1,31 @@
+# Links are links, buttons are buttons
+
+Navigation uses an anchor so middle-click, Cmd-click and "open in new tab" work; actions use a button.
+
+## Why
+
+Vercel and Rauno Freiberg interface guidelines, and Nielsen heuristic 4: users expect anything that navigates to behave like a link. A `div` with an onclick breaks the context menu, accessibility and the ability to open several things at once.
+Sources: https://vercel.com/design/guidelines , https://interfaces.rauno.me/
+
+## Do
+
+- `<a href>` for anything that changes the URL; `<button>` for anything that does not.
+- Style a link as a button when needed, but keep the anchor element.
+- Make whole cards clickable with a single anchor, not a click handler on the container.
+- Mark external links and give them accessible names.
+
+## Don't
+
+- Attach `onclick` navigation to a `div`, `span` or card.
+- Use a button for "View details" that only navigates.
+- Nest interactive elements inside the link.
+
+## In tsumikit
+
+- `Link` for text links and button-styled links; `Card` renders an anchor when given `href`.
+- `NavItem`, `TabBar`, `Breadcrumb`, `Pagination`, `Tabs`, `SegmentedControl` take `href` and render real anchors.
+- `AnchorAttributes` type carries the anchor props through.
+
+## Check
+
+Middle-click every navigational element on the screen. Each must open in a new tab. Right-click them: "Copy link address" must be present.

package/principles/25-visible-focus.md

@@ -0,0 +1,32 @@
+# Every control shows a visible focus ring
+
+Keyboard focus is always visible, on every interactive element, with a ring that contrasts with its surroundings.
+
+## Why
+
+WCAG 2.2 (2.4.7 focus visible, 2.4.11 focus not obscured) and the Vercel interface guidelines: keyboard users navigate by watching focus. Removing the outline without a replacement strands them. `:focus-visible` shows the ring only for keyboard focus, so pointer users are not bothered.
+Sources: https://www.w3.org/WAI/WCAG22/quickref/ , https://vercel.com/design/guidelines
+
+## Do
+
+- Use `:focus-visible` with an accent ring at least 2px wide and an offset.
+- Keep focus order the same as visual order.
+- Move focus into dialogs on open and back to the trigger on close.
+- Make the ring visible on dark and light surfaces and inside scroll containers.
+
+## Don't
+
+- Write `outline: none` without a replacement.
+- Rely on a colour change alone to show focus.
+- Let focus disappear behind a sticky header or an overlay.
+
+## In tsumikit
+
+- `--focus-ring`, `--focus-ring-width`, `--focus-ring-offset`, `--focus-ring-offset-inset` tokens; every atom applies them under `:focus-visible`.
+- `Modal`, `Drawer`, `Menu`, `Popover` manage focus trapping and return.
+- Roving focus for `Toolbar`, `RadioGroup`, `Tabs`, `Menu`.
+- Dev-audit warnings flag unlabelled controls (`warnUnlabelled()`).
+
+## Check
+
+Tab through the entire screen from the address bar. At every stop you must see where focus is, in the order you expected, and nothing must be skipped or trapped.

package/principles/26-generous-targets.md

@@ -0,0 +1,31 @@
+# Generous targets
+
+Interactive elements are at least 24px with a pointer and 44px on touch, with no dead zones between them.
+
+## Why
+
+Fitts's law: time to hit a target depends on its size and distance; frequent targets should be big and close. WCAG 2.2 (2.5.8) sets the 24px minimum, mobile platform guidance sets 44px. Gaps between adjacent targets prevent mis-taps.
+Sources: https://lawsofux.com/fittss-law/ , https://www.w3.org/WAI/WCAG22/quickref/
+
+## Do
+
+- Make the whole row or card the target, not just the text inside it.
+- Pad icon buttons to the touch size even when the icon is small.
+- Put frequent actions near where the pointer or thumb already is.
+- Leave at least 8px between adjacent targets.
+
+## Don't
+
+- Ship 16px icon buttons with no padding.
+- Make the hit area smaller than the visible shape.
+- Place a destructive action within thumb reach of a frequent one on mobile.
+
+## In tsumikit
+
+- `--touch-target` (44px) and `--touch-target-compact` (40px); `--control-height` variants for desktop density.
+- `IconButton` and `Button` pad to the target size; `TabBar` and `SwipeRow` are built for thumbs.
+- `AppShell` places primary navigation at the bottom on narrow screens.
+
+## Check
+
+Overlay 44px squares on a phone screenshot and 24px on a desktop one. Every interactive element must contain one. Tap between two neighbouring targets: one of them must respond, never neither.

package/principles/27-cheap-motion-respect-preferences.md

@@ -0,0 +1,32 @@
+# Cheap motion, respected preferences
+
+Animate only transform and opacity, keep durations short, and honour reduced-motion, zoom and paste.
+
+## Why
+
+Vercel and Rauno Freiberg interface guidelines: transform and opacity run on the compositor; animating layout properties janks. `transition: all` animates things you did not intend. Users who set reduced motion, zoom text or paste passwords are telling you something; blocking them is hostile.
+Sources: https://vercel.com/design/guidelines , https://interfaces.rauno.me/ , https://www.w3.org/WAI/WCAG22/quickref/
+
+## Do
+
+- Transition `transform` and `opacity`; keep enter around 180 ms and exit shorter.
+- Wrap decorative motion in `prefers-reduced-motion: no-preference`, or reduce to a fade.
+- Allow pinch and text zoom; never set `user-scalable=no`.
+- Allow paste in every input, including password and code fields.
+
+## Don't
+
+- Write `transition: all`.
+- Animate `height`, `width`, `top` or `margin`.
+- Run looping animations the user cannot stop.
+- Disable autocomplete or paste "for security".
+
+## In tsumikit
+
+- Duration tokens `--dur-fast`, `--dur-base`, `--dur-slow`, `--dur-exit`; easing `--ease-out`, `--ease-spring`; press and shift scales `--press-scale`, `--shift-sm`.
+- The reset collapses motion under `prefers-reduced-motion: reduce`; `MotionSettings` lets users choose in-app.
+- Lint rule `motion` flags `transition: all` and layout-property animations.
+
+## Check
+
+Enable "reduce motion" in the OS and reload: nothing should move except opacity. Record a performance profile while opening a menu: no layout thrash. Zoom to 200%: everything still usable.

package/principles/28-less-but-better.md

@@ -0,0 +1,31 @@
+# Less, but better
+
+Every element earns its place; if removing it loses nothing, remove it.
+
+## Why
+
+Dieter Rams's tenth principle, "good design is as little design as possible", and Nielsen heuristic 8, aesthetic and minimalist design: every extra element competes with the ones that matter. Restraint is what makes the remaining elements legible.
+Sources: https://www.vitsoe.com/us/about/good-design , https://www.nngroup.com/articles/ten-usability-heuristics/
+
+## Do
+
+- Remove decoration that carries no information: borders, icons next to every label, redundant titles.
+- Say things once; a page title does not need to be repeated in a breadcrumb and a heading.
+- Prefer the plain version of a component until the richer one is justified.
+- Review each screen by deleting elements one at a time and asking what was lost.
+
+## Don't
+
+- Add an icon to every button and a badge to every row.
+- Show every field the backend has.
+- Keep a feature on screen because it was expensive to build.
+
+## In tsumikit
+
+- Components default to the quiet form (`Button` `variant="default"`, `Card` without border, `Text` body) and take opt-in props for emphasis.
+- Looks and micro-interactions are opt-in via `parseLook()` and `LookPicker`, not applied by default.
+- Dev-audit warnings surface redundancy such as duplicate primaries and unlabelled controls.
+
+## Check
+
+For each element on the screen, hide it in dev tools. If the screen still answers "what is this, what state is it in, what can I do", the element was decoration.

package/principles/29-colour-is-not-the-only-cue.md

@@ -0,0 +1,31 @@
+# Colour is never the only cue
+
+State conveyed by colour is also conveyed by an icon, a label or a shape.
+
+## Why
+
+WCAG 1.4.1 (use of colour): about one in twelve men cannot reliably distinguish red from green. A dot that is green or red is a dot. Pairing colour with text or an icon also helps everyone in bad light or on a poor display.
+Source: https://www.w3.org/WAI/WCAG22/quickref/
+
+## Do
+
+- Pair every status colour with a word or an icon ("Failed", a cross).
+- Use shape or position as well as colour in charts and legends.
+- Underline or otherwise mark links in running text.
+- Test with a colour-blind-safe theme or a simulator.
+
+## Don't
+
+- Show a bare coloured dot as the only indicator of health.
+- Distinguish chart series by hue alone.
+- Mark required fields by colour only.
+
+## In tsumikit
+
+- `Badge`, `Dot`, `Callout`, `Gauge`, `Meter` take a `tone` and render an icon or label alongside the colour.
+- `CapBar` and `SegmentedProgress` carry a legend; `Swatch` labels colours.
+- A verified colour-blind-safe theme (Okabe-Ito) is available through `ThemePicker`.
+
+## Check
+
+Switch to the colour-blind-safe theme or apply a greyscale filter to a screenshot. Every state that was visible before must still be identifiable.

package/principles/30-help-where-needed.md

@@ -0,0 +1,31 @@
+# Help where it is needed
+
+Explanation appears next to the thing it explains, at the moment it is needed, and is short.
+
+## Why
+
+Nielsen heuristic 10: the best interface needs no documentation, but when help is needed it should be in context, searchable, focused on the task and concise. A manual nobody opens is not help.
+Source: https://www.nngroup.com/articles/ten-usability-heuristics/
+
+## Do
+
+- Put one line of help text under the field it concerns.
+- Use tooltips for icon-only controls and for the meaning of a term.
+- Explain a setting's effect next to the setting, in the user's words.
+- Link to deeper documentation from the place where the question arises.
+
+## Don't
+
+- Replace clear labels with a help icon.
+- Write paragraphs where a sentence will do.
+- Hide the only explanation in a separate help section.
+
+## In tsumikit
+
+- `Field` renders help and error text under its control and links it with `aria-describedby`.
+- `Tooltip` for terse in-place help; `Popover` and `Disclosure` for a little more.
+- `Callout` `tone="info"` for a short contextual note; `Prose` for longer documentation rendered from markdown.
+
+## Check
+
+Find every setting, field and icon-only control on the screen. For each, can a new user learn what it does without leaving the screen? If not, add one line of help there.

package/principles/README.md

@@ -0,0 +1,62 @@
+# Design principles
+
+The principles tsumikit is built to serve, one file each. They distil Nielsen's usability heuristics, Laws of UX, Refactoring UI, Practical Typography, the Vercel and Rauno Freiberg web interface guidelines, WCAG 2.2 and Dieter Rams. Each file states the principle in one line, why it holds (with the source), do and don't lists, what the kit provides for it, and a check you can run on a screen.
+
+They ship in the package: `node_modules/@dorsk/tsumikit/principles/`. Point a design review, or a coding agent, at them.
+
+## Index
+
+| # | Principle | In one line |
+|---|---|---|
+| 01 | [Visibility of system status](01-visibility-of-status.md) | Acknowledge every action within 100 ms and state the outcome. |
+| 02 | [One primary action per view](02-one-primary-action.md) | One filled button; the rest outlined, plain or behind a menu. |
+| 03 | [Emphasise by de-emphasising](03-emphasise-by-de-emphasising.md) | Quiet the surroundings instead of enlarging the subject; three text levels. |
+| 04 | [Labels are a last resort](04-labels-last-resort.md) | Drop labels the value makes obvious; keep the rest small and muted. |
+| 05 | [Tint your greys](05-tint-the-greys.md) | Every grey shares a slight hue; no neutral hexes. |
+| 06 | [Depth from shade, not outlines](06-depth-from-shade.md) | Layers differ by background lightness; borders are faint or absent. |
+| 07 | [One accent, used sparingly](07-one-accent.md) | Accent marks primary, active and focus; status colours mean status. |
+| 08 | [A spacing scale, room to breathe](08-spacing-scale.md) | All spacing from the scale; start airy, then remove. |
+| 09 | [Group with space, not boxes](09-group-with-space.md) | Proximity and shared background group; gaps between groups are larger. |
+| 10 | [A real typeface, a fixed scale](10-real-typeface-fixed-scale.md) | Bundle a screen typeface; fixed type scale, few weights. |
+| 11 | [Monospace only for code](11-mono-only-for-code.md) | Mono for paths, hashes, commands; sans for everything else. |
+| 12 | [Keep lines 45 to 75 characters](12-measure.md) | Cap reading width independent of the viewport. |
+| 13 | [Imagery sets the mood](13-imagery-sets-the-mood.md) | Backdrops with a fade, text on a scrim, designed placeholders. |
+| 14 | [Feedback is instant and calm](14-instant-calm-feedback.md) | Spinner after 200 ms, kept 500 ms; optimistic updates with rollback. |
+| 15 | [Prefer undo over confirmation](15-undo-over-confirm.md) | Reversible actions with undo; confirm only the irreversible. |
+| 16 | [Empty states are design too](16-empty-states.md) | Say what belongs here and offer the action that fills it. |
+| 17 | [Errors in plain words](17-errors-in-plain-words.md) | What happened, why, and what to do next. |
+| 18 | [Speak the user's language](18-match-the-real-world.md) | Names, formats and order from the user's world, not the system's. |
+| 19 | [Consistency beats local cleverness](19-consistency-and-standards.md) | Same thing, same look and behaviour, everywhere; follow conventions. |
+| 20 | [Prevent errors](20-error-prevention.md) | Constrain input, validate early, keep destructive actions apart. |
+| 21 | [Recognition over recall](21-recognition-over-recall.md) | Show location, selection, options and shortcuts on screen. |
+| 22 | [Shortcuts for the experienced](22-flexibility-and-shortcuts.md) | Keyboard, bulk and saved views layered on a simple default. |
+| 23 | [The URL is state](23-url-is-state.md) | Filters, tabs, sort and page survive refresh, Back and sharing. |
+| 24 | [Links are links](24-links-are-links.md) | Anchors navigate, buttons act; middle-click always works. |
+| 25 | [Visible focus](25-visible-focus.md) | Every control shows a focus ring under `:focus-visible`. |
+| 26 | [Generous targets](26-generous-targets.md) | 24px with a pointer, 44px on touch, no dead zones. |
+| 27 | [Cheap motion, respected preferences](27-cheap-motion-respect-preferences.md) | Transform and opacity only; honour reduced motion, zoom, paste. |
+| 28 | [Less, but better](28-less-but-better.md) | Every element earns its place or goes. |
+| 29 | [Colour is never the only cue](29-colour-is-not-the-only-cue.md) | Pair every status colour with an icon, label or shape. |
+| 30 | [Help where it is needed](30-help-where-needed.md) | One line of help beside the thing it explains. |
+
+## Designing a screen: the checklist
+
+Run through this before calling a screen done. Each line points at the principle with the full check.
+
+1. The first viewport answers "what is this, what state is it in, what can I do". (28, 21)
+2. Exactly one filled button; no action bar wraps at 40rem. (02)
+3. Three text levels at most; muted text passes 4.5:1. (03)
+4. Every label left on screen is one the value could not do without. (04)
+5. All greys tinted, layers told apart by shade, borders faint. (05, 06)
+6. Accent only on primary, active, focus, selection; status colours paired with a cue. (07, 29)
+7. Every gap and padding is a scale step; gaps between groups are larger than within. (08, 09)
+8. Bundled typeface, scale sizes only, mono only for code-like text, lines 45 to 75 characters. (10, 11, 12)
+9. Images fade into the page, text over them sits on a scrim, missing images get a placeholder. (13)
+10. Every click changes something within 100 ms; spinners appear after 200 ms and stay 500 ms. (01, 14)
+11. Destructive actions have undo, or a confirm that names the loss. (15, 20)
+12. Empty, filtered-empty and failed states each have copy and an action; errors say what to do next. (16, 17)
+13. Labels and messages read like a person talking; the same thing is named the same everywhere. (18, 19)
+14. Filters, tabs, sort and page are in the URL; navigation is real anchors. (23, 24)
+15. Tab through the screen: focus is visible everywhere; targets are 24px / 44px. (25, 26)
+16. No `transition: all`; reduced motion, zoom and paste all respected. (27)
+17. Help text sits beside the thing it explains; shortcuts are visible. (30, 22)