@dorsk/tsumikit 0.81.0 → 0.82.0

package/lint/rules/no-raw-font.mjs

@@ -0,0 +1,64 @@
+import { inlineDeclarations, walkDeclarations, walkMarkup } from '../context.mjs';
+
+/**
+ * @typedef {import('../context.mjs').Context} Context
+ * @typedef {import('../context.mjs').DeclarationLike} DeclarationLike
+ */
+
+const TOKEN_ONLY = /^(?:var\(--font-[\w-]+\)|inherit|initial|unset|revert)\s*(?:,\s*(?:var\(--font-[\w-]+\)|[a-z-]+))*$/i;
+const MONO = /var\(--font-mono\)/;
+const CODE_WORDS = new Set([
+	'code', 'pre', 'kbd', 'samp', 'tt', 'mono', 'monospace', 'term', 'terminal', 'console', 'shell',
+	'cmd', 'command', 'prompt', 'log', 'logs', 'diff', 'json', 'yaml', 'toml', 'hash', 'sha', 'digest',
+	'path', 'snippet', 'editor', 'trace', 'stack', 'output', 'stdout', 'stderr', 'hex', 'uuid', 'ansi'
+]);
+
+/** @param {string[]} selectors */
+export function isCodeIsh(selectors) {
+	return selectors.some((s) =>
+		s
+			.replace(/([a-z])([A-Z])/g, '$1 $2')
+			.toLowerCase()
+			.split(/[^a-z0-9]+/)
+			.some((w) => CODE_WORDS.has(w))
+	);
+}
+
+/**
+ * @param {Context} ctx
+ * @param {DeclarationLike} declaration
+ * @param {string[]} selectors
+ */
+function check(ctx, declaration, selectors) {
+	if (declaration.property !== 'font-family') return;
+	if (selectors.some((s) => /:root|:host|\[data-theme|\[data-look/.test(s))) return;
+	const value = declaration.value.trim();
+	if (!TOKEN_ONLY.test(value)) {
+		ctx.report(
+			'no-raw-font',
+			declaration.start,
+			`raw font-family "${value}"; use var(--font-sans) / var(--font-mono) / var(--font-numeric) / var(--font-label)`
+		);
+		return;
+	}
+	if (MONO.test(value) && !isCodeIsh(selectors)) {
+		ctx.report(
+			'no-raw-font',
+			declaration.start,
+			`--font-mono on a non-code element (${selectors.at(-1) ?? 'inline style'}); use var(--font-numeric) for values or var(--font-label) for labels, or add tsumikit-lint-ignore if it really is code`
+		);
+	}
+}
+
+export default /** @type {import('../context.mjs').LintRule} */ ({
+	id: 'no-raw-font',
+	description: 'font-family other than the --font-* tokens; --font-mono only on code-ish elements',
+	check(ctx) {
+		walkDeclarations(ctx, (d, { selectors }) => check(ctx, d, selectors));
+		walkMarkup(ctx, (node) => {
+			if (node.type !== 'RegularElement' && node.type !== 'Component') return;
+			const selectors = node.type === 'RegularElement' ? [node.name] : [];
+			for (const d of inlineDeclarations(node)) check(ctx, d, selectors);
+		});
+	}
+});

package/lint/rules/one-primary.mjs

@@ -0,0 +1,74 @@
+import { staticAttribute } from '../context.mjs';
+
+/**
+ * @typedef {import('../context.mjs').Fragment} Fragment
+ * @typedef {import('../context.mjs').MarkupNode} MarkupNode
+ * @typedef {import('../context.mjs').ElementLike} ElementLike
+ */
+
+/**
+ * Returns the primaries that can render at the same time inside `node`.
+ * Exclusive branches (if/else, await states) contribute the largest branch;
+ * snippets are separate scopes checked on their own.
+ * @param {MarkupNode | Fragment | null | undefined} node
+ * @param {Fragment[]} scopes
+ * @returns {ElementLike[]}
+ */
+function primaries(node, scopes) {
+	if (!node || typeof node !== 'object') return [];
+	switch (node.type) {
+		case 'Fragment':
+			return node.nodes.flatMap((n) => primaries(n, scopes));
+		case 'IfBlock':
+			return largest(primaries(node.consequent, scopes), primaries(node.alternate, scopes));
+		case 'AwaitBlock':
+			return largest(
+				primaries(node.pending, scopes),
+				primaries(node.then, scopes),
+				primaries(node.catch, scopes)
+			);
+		case 'EachBlock':
+			return largest(primaries(node.body, scopes), primaries(node.fallback, scopes));
+		case 'KeyBlock':
+			return primaries(node.fragment, scopes);
+		case 'SnippetBlock':
+			scopes.push(node.body);
+			return [];
+		case 'Component':
+		case 'RegularElement':
+		case 'SvelteElement':
+		case 'SvelteBoundary':
+		case 'SvelteComponent':
+		case 'SvelteSelf': {
+			const own =
+				node.type === 'Component' && staticAttribute(node, 'variant') === 'primary' ? [node] : [];
+			return [...own, ...primaries(node.fragment, scopes)];
+		}
+		default:
+			return [];
+	}
+}
+
+/** @template T @param {T[][]} lists */
+function largest(...lists) {
+	return lists.reduce((a, b) => (b.length > a.length ? b : a), /** @type {T[]} */ ([]));
+}
+
+export default /** @type {import('../context.mjs').LintRule} */ ({
+	id: 'one-primary',
+	description: 'more than one variant="primary" rendered in the same branch',
+	check(ctx) {
+		if (!ctx.fragment) return;
+		const scopes = [ctx.fragment];
+		while (scopes.length) {
+			const found = primaries(scopes.shift(), scopes);
+			for (const node of found.slice(1)) {
+				ctx.report(
+					'one-primary',
+					node.start,
+					`${found.length} primary actions render together (first at line ${ctx.loc(found[0].start).line}); keep one primary per view`
+				);
+			}
+		}
+	}
+});

package/lint/rules/spacing-scale.mjs

@@ -0,0 +1,66 @@
+import { inlineDeclarations, walkDeclarations, walkMarkup } from '../context.mjs';
+
+/**
+ * @typedef {import('../context.mjs').Context} Context
+ * @typedef {import('../context.mjs').DeclarationLike} DeclarationLike
+ */
+
+const PROPERTY = /^(padding|margin|gap|row-gap|column-gap|inset|top|right|bottom|left|scroll-padding|scroll-margin)(-|$)/;
+const LENGTH = /(?<![\w.-])(-?\d*\.?\d+)(px|rem)(?![\w%])/g;
+
+/** @type {ReadonlyArray<readonly [string, number]>} */
+export const SPACING_SCALE = [
+	['--sp-0-5', 0.125],
+	['--sp-1', 0.25],
+	['--sp-1-5', 0.375],
+	['--sp-2', 0.5],
+	['--sp-3', 0.75],
+	['--sp-4', 1],
+	['--sp-5', 1.25],
+	['--sp-6', 1.5],
+	['--sp-8', 2],
+	['--sp-10', 2.5],
+	['--sp-12', 3]
+];
+
+/** @param {string} value */
+function stripFunctions(value) {
+	return value.replace(/\b(var|env|url)\((?:[^)(]|\([^)(]*\))*\)/gi, ' ');
+}
+
+/** @param {number} amount @param {string} unit */
+export function tokenFor(amount, unit) {
+	const rem = unit === 'px' ? amount / 16 : amount;
+	const match = SPACING_SCALE.find(([, v]) => Math.abs(v - Math.abs(rem)) < 1e-6);
+	if (!match) return null;
+	return rem < 0 ? `calc(-1 * var(${match[0]}))` : `var(${match[0]})`;
+}
+
+/** @param {Context} ctx @param {DeclarationLike} declaration */
+function check(ctx, declaration) {
+	if (!PROPERTY.test(declaration.property)) return;
+	for (const m of stripFunctions(declaration.value).matchAll(LENGTH)) {
+		const amount = Number(m[1]);
+		const unit = m[2];
+		if (amount === 0 || (unit === 'px' && Math.abs(amount) === 1)) continue;
+		const token = tokenFor(amount, unit);
+		const hint = token ? `use ${token}` : 'not on the --sp-* scale';
+		ctx.report(
+			'spacing-scale',
+			declaration.start,
+			`raw ${m[0]} in "${declaration.property}"; ${hint}`
+		);
+	}
+}
+
+export default /** @type {import('../context.mjs').LintRule} */ ({
+	id: 'spacing-scale',
+	description: 'px/rem in padding/margin/gap/inset that is not a --sp-* token (1px allowed)',
+	check(ctx) {
+		walkDeclarations(ctx, (d) => check(ctx, d));
+		walkMarkup(ctx, (node) => {
+			if (node.type !== 'RegularElement' && node.type !== 'Component') return;
+			for (const d of inlineDeclarations(node)) check(ctx, d);
+		});
+	}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorsk/tsumikit",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "description": "Minimal, dependency-free Svelte 5 + pure-CSS UI kit. Token-driven atoms, molecules & layouts with theming out of the box.",
   "type": "module",
   "license": "MIT",
@@ -24,8 +24,13 @@
     "**/*.css"
   ],
   "files": [
-    "dist"
+    "dist",
+    "lint",
+    "principles"
   ],
+  "bin": {
+    "tsumikit-lint": "./lint/cli.mjs"
+  },
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -34,6 +39,10 @@
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./dev-audit": {
+      "types": "./dist/dev-audit.d.ts",
+      "default": "./dist/dev-audit.js"
+    },
     "./styles/app.css": "./dist/styles/app.css",
     "./styles/variables.css": "./dist/styles/variables.css",
     "./styles/tokens.css": "./dist/styles/tokens.css",
@@ -41,6 +50,7 @@
     "./styles/reset.css": "./dist/styles/reset.css",
     "./styles/utilities.css": "./dist/styles/utilities.css",
     "./styles/syntax.css": "./dist/styles/syntax.css",
+    "./styles/font.css": "./dist/styles/font.css",
     "./looks/*.css": "./dist/looks/*.css"
   },
   "publishConfig": {

package/principles/01-visibility-of-status.md

@@ -0,0 +1,32 @@
+# Visibility of system status
+
+Every action gets an acknowledgement within 100 ms, and the outcome is stated, not implied.
+
+## Why
+
+Nielsen heuristic 1: users forgive slowness but not silence; a button that goes quiet after a click gets clicked again or abandoned. The Doherty threshold adds the budget: below about 400 ms people stay in flow, above it they need visible progress.
+Sources: https://www.nngroup.com/articles/ten-usability-heuristics/ , https://lawsofux.com/doherty-threshold/
+
+## Do
+
+- Change the control the moment it is pressed: keep its label, add a busy indicator next to it.
+- State the result in words ("Saved. 3 fields updated."), and offer the way back when there is one.
+- Show progress for anything that can take more than a second; show how much is done if you know.
+- Mark long-running background work somewhere persistent (a status bar, a queue count).
+
+## Don't
+
+- Disable the button and show nothing else.
+- Swap the label for a spinner, so the user forgets what they pressed.
+- Report success only by closing the dialog.
+
+## In tsumikit
+
+- `Button` with `loading` (true while pending, `'done'` for the confirmation tick) and the `pending()` helper with `loadingDelay` / `loadingMin` for flicker-free timing.
+- `Spinner`, `Progress`, `SegmentedProgress`, `Skeleton` for in-place state; `StatusBar` for persistent status.
+- `Toaster` with `toasts.info()` / `toasts.error()` for outcome messages; errors use the assertive live region.
+- Motion tokens `--dur-fast`, `--dur-base` keep the acknowledgement under the 100 ms threshold.
+
+## Check
+
+Click every action on the screen with the network throttled to "slow 3G". Within 100 ms something must change on or next to the control, and after completion the screen must say what happened.

package/principles/02-one-primary-action.md

@@ -0,0 +1,31 @@
+# One primary action per view
+
+Each view has exactly one filled button, for the thing most people came to do; everything else is quieter or behind a menu.
+
+## Why
+
+Hick's law: decision time grows with the number and complexity of choices. Two filled buttons cancel each other out, and an action bar that wraps is a bar with too many actions.
+Sources: https://lawsofux.com/hicks-law/ , Refactoring UI (hierarchy of actions) https://www.refactoringui.com/
+
+## Do
+
+- Filled accent for the primary action, outlined for secondary, plain text or icon-only for tertiary.
+- Move rare or destructive actions into an overflow menu.
+- Keep the primary action visible in the first viewport.
+
+## Don't
+
+- Fill two buttons in the same toolbar.
+- Let an action bar wrap onto a second line.
+- Give the primary slot to "Cancel" or "Back".
+
+## In tsumikit
+
+- `Button` `variant="primary"` for the one filled button; `variant="default"` for secondary, `variant="ghost"` or `IconButton` for tertiary.
+- `SplitButton` when a primary action has variants; `Menu` for the overflow.
+- `Toolbar` lays actions out with the shared control height.
+- Lint rule `one-primary` flags more than one primary button in a view.
+
+## Check
+
+Count filled buttons in each viewport-sized region of the screen. The answer is one. Then shrink the window to 40rem: no action bar may wrap.

package/principles/03-emphasise-by-de-emphasising.md

@@ -0,0 +1,31 @@
+# Emphasise by de-emphasising
+
+Make the important thing stand out by making everything around it quieter, not bigger.
+
+## Why
+
+Refactoring UI: hierarchy is built with weight and colour first, size last. When every element shouts, nothing does. Three text levels are enough for most screens: a title, values, labels.
+Source: https://www.refactoringui.com/
+
+## Do
+
+- Title: large and bold. Value: normal weight, full contrast. Label: small, muted.
+- Lower the contrast of supporting text instead of raising the size of primary text.
+- Keep muted text at or above 4.5:1 contrast; faint text is for placeholders and disabled states only.
+
+## Don't
+
+- Use size alone to signal importance.
+- Use four or more text styles on one card.
+- Push secondary text so faint that it fails contrast.
+
+## In tsumikit
+
+- Text colour levels: `--text` for values, `--text-muted` for labels (>= 4.5:1), `--text-faint` for placeholder and disabled text only (~3:1).
+- `Heading` for titles; `Text` with `tone="muted"` for labels and `variant="caption"` for small supporting copy.
+- Weight tokens `--fw-normal`, `--fw-medium`, `--fw-semibold`, `--fw-bold`; size tokens `--fs-xs` to `--fs-3xl`.
+- `KeyValue`, `Metric`, `StatTile` already encode the title / value / label structure.
+
+## Check
+
+Squint at the screen (or blur a screenshot). You should see one title, a few strong values, and quiet labels. Run a contrast check on muted text: 4.5:1 or better.

package/principles/04-labels-last-resort.md

@@ -0,0 +1,30 @@
+# Labels are a last resort
+
+Show a label only when the value cannot explain itself; when you do, make it small and quiet so the value carries the weight.
+
+## Why
+
+Refactoring UI: "Year: 2023" makes the eye scan words, "2023" alone reads as a fact. Labels at the same weight as values double the text and halve the information density.
+Source: https://www.refactoringui.com/
+
+## Do
+
+- Drop labels where the format is self-evident: years, file sizes, durations, email addresses.
+- Fold the label into the value where it reads naturally ("3 files", "Korean audio").
+- When a label stays, set it small, muted, often uppercase and tracked, with the value in full contrast.
+- Lay out label and value pairs as a strip or grid that reads in one glance.
+
+## Don't
+
+- Write "Label: value" lists in the same weight and colour.
+- Separate related facts with " · " in a single run of text where a strip would scan faster.
+
+## In tsumikit
+
+- `KeyValue` renders muted label and strong value; `Metric` and `StatTile` for numeric facts.
+- `Text` `variant="eyebrow"` for small uppercase labels; `tone="muted"` for the label colour `--text-muted`.
+- `--font-label` and `--font-numeric` (default to sans; opt into mono for data-dense views).
+
+## Check
+
+Read each label on the screen and ask whether the value would be ambiguous without it. Remove the ones that would not. Remaining labels must be visibly quieter than their values.

package/principles/05-tint-the-greys.md

@@ -0,0 +1,30 @@
+# Tint your greys
+
+Neutral greys look dead on screen; give every grey a slight shared hue so the whole page has one mood.
+
+## Why
+
+Refactoring UI: pure greys read as "admin panel". Saturating them a little, cool or warm, makes the palette feel intentional. Material's tonal surfaces follow the same idea: surfaces are tinted shades of one hue.
+Sources: https://www.refactoringui.com/ , https://m3.material.io/foundations
+
+## Do
+
+- Pick one hue for the whole neutral ramp and tint backgrounds, borders and muted text with it.
+- Keep lightness steps the same as a neutral ramp; only the hue changes.
+- Let the accent colour and the grey tint come from nearby hues so they agree.
+
+## Don't
+
+- Use `#2a2a2a`-style neutral hexes.
+- Mix cool greys in one component with warm greys in another.
+- Hard-code any grey in a component; read it from the theme.
+
+## In tsumikit
+
+- Theme ramps `--c-bg`, `--c-bg-elev`, `--c-bg-elev-2`, `--c-surface`, `--c-border`, `--c-text-muted`, `--c-text-faint` are tinted per theme; components read the semantic aliases `--bg`, `--bg-elevated`, `--bg-elevated-2`, `--surface`, `--border`, `--text-muted`.
+- `ThemePicker` and `chooseTheme()` switch the whole ramp at once; `Swatch` previews it.
+- Lint rule `no-raw-color` rejects hex or rgb literals in app styles.
+
+## Check
+
+Sample three greys from a screenshot (background, card, border). Each must have non-zero saturation in HSL and the same hue family.

package/principles/06-depth-from-shade.md

@@ -0,0 +1,30 @@
+# Depth from shade, not outlines
+
+Layers are told apart by background lightness and soft shadow; borders are faint or absent.
+
+## Why
+
+Refactoring UI and Apple's dark-mode guidance: in dark themes the base is near black and each level above it is a few percent lighter. When every panel has a strong border, the borders become the loudest thing on the page and the content loses.
+Sources: https://www.refactoringui.com/ , https://developer.apple.com/design/human-interface-guidelines/
+
+## Do
+
+- Stack `--bg` < `--bg-elevated` < `--bg-elevated-2` < `--surface` as you go up.
+- Use a single light direction for shadows and keep them soft.
+- Reserve visible borders for inputs and for cases where two equal-lightness areas must be separated.
+
+## Don't
+
+- Put a 1px solid border on every card, table and panel.
+- Combine a strong border with a shadow on the same element.
+- Lighten text and darken background in the same step; adjust one at a time.
+
+## In tsumikit
+
+- Elevation tokens `--bg`, `--bg-elevated`, `--bg-elevated-2`, `--surface`; `--border` for faint lines, `--border-strong` only where needed.
+- Shadow tokens `--shadow-sm`, `--shadow-md`, `--shadow-lg`.
+- `Card` reads surface fill and edge from `--surface-fill` / `--surface-edge`; look tokens `--raised-fill`, `--overlay-fill` cover popovers and menus.
+
+## Check
+
+Desaturate a screenshot and count the borders. Each one should be doing something spacing or shade could not. Layers must still read as layers with all borders hidden.

package/principles/07-one-accent.md

@@ -0,0 +1,31 @@
+# One accent, used sparingly
+
+A single accent hue marks the primary action, the active item and focus; status colours mean status and nothing else.
+
+## Why
+
+Von Restorff effect: the one item that differs is the one noticed and remembered. An accent used everywhere signals nothing. Separating accent from green, amber and red keeps "here" distinct from "ok", "warning", "error".
+Source: https://lawsofux.com/von-restorff-effect/
+
+## Do
+
+- Accent only on: the primary button, the active nav or tab, the focus ring, a selected row.
+- Green, amber, red, blue only for semantic state; pair them with an icon or text.
+- Keep counts, badges and chips neutral unless they carry state.
+
+## Don't
+
+- Colour every nav item or badge with the accent.
+- Pick an accent that resembles one of the status colours.
+- Use colour as the only carrier of meaning.
+
+## In tsumikit
+
+- `--accent`, `--accent-dim`, `--text-on-accent` for the single accent; themes keep the accent distinct from the status hues.
+- Status tokens `--ok`, `--warn`, `--danger`, `--info`; `Badge`, `Dot`, `Callout` take a `tone` and always pair colour with an icon or label.
+- `canonicalTone()` normalises tone names so there is one vocabulary.
+- Lint rule `no-raw-color` keeps app styles on these tokens.
+
+## Check
+
+List every element using the accent colour. Each must be one of: primary action, active item, focus, selection. Then check every green, amber or red element has a non-colour cue beside it.

package/principles/08-spacing-scale.md

@@ -0,0 +1,30 @@
+# A spacing scale, and more room than feels right
+
+All spacing comes from a fixed scale; start with too much whitespace, then remove some.
+
+## Why
+
+Refactoring UI: cramped layouts feel cheap even when every pixel is correct, and arbitrary gaps make a page look accidental. A scale (4, 8, 12, 16, 24, 32, 48, 64) with no in-between values keeps rhythm consistent without thought.
+Source: https://www.refactoringui.com/
+
+## Do
+
+- Use scale steps for padding, gaps and margins; jump a step rather than nudging by 2px.
+- Give cards and sections generous inner padding (16 or 24), and larger gaps between sections than inside them.
+- Align every element to an edge, grid or baseline that other elements also use.
+
+## Don't
+
+- Use 10px, 14px, 18px or other off-scale values.
+- Use the same gap everywhere; it flattens grouping (see "Group with space").
+- Reach for `margin-top: 3px` to fix alignment; fix the line height or the scale step.
+
+## In tsumikit
+
+- Spacing tokens `--sp-1` (4px) through `--sp-12` (48px), with `--sp-0-5` and `--sp-1-5` for hairline cases.
+- Layouts `Stack`, `Cluster`, `AutoGrid`, `Container` take gaps from the scale; `--content-max` caps reading width.
+- Lint rule `spacing-scale` flags raw pixel spacing in app styles.
+
+## Check
+
+Inspect padding and gap values on the screen; every one must be a scale step. Then double the main gaps in dev tools; if it looks better, the original was too tight.

package/principles/09-group-with-space.md

@@ -0,0 +1,31 @@
+# Group with space, not boxes
+
+Related items sit closer together or on a shared background; unrelated items are separated by more space, not by borders.
+
+## Why
+
+Gestalt laws of proximity and common region: things close together, or inside one region, are read as a group. Space between groups must be clearly larger than space within them, or the grouping disappears.
+Sources: https://lawsofux.com/law-of-proximity/ , https://lawsofux.com/law-of-common-region/
+
+## Do
+
+- Within a group: one small step (4 or 8). Between groups: at least two steps larger (24 or 32).
+- Use a shared background tint to group without a border.
+- Put a label or heading closer to the content it describes than to the content above it.
+
+## Don't
+
+- Space twelve items evenly and expect the reader to find the four groups.
+- Draw a border around each group when a gap would do.
+- Let a section heading float equidistant between two sections.
+
+## In tsumikit
+
+- `Stack` with a per-group gap and a larger gap between stacks; `Cluster` for inline groups.
+- `Card` and `Fieldset` for common region; `Divider` only when space cannot separate.
+- `SectionHeader` attaches a heading to the block that follows.
+- Spacing tokens `--sp-2`, `--sp-6`, `--sp-8` give the within / between contrast.
+
+## Check
+
+Blur a screenshot until text is unreadable. The groups you intended must still be visible as clusters. If you see one even grid, the gaps are too uniform.

package/principles/10-real-typeface-fixed-scale.md

@@ -0,0 +1,33 @@
+# A real typeface, a fixed scale
+
+Bundle a typeface designed for screens and use a fixed type scale with few weights.
+
+## Why
+
+Practical Typography and Refactoring UI: typography carries most of an interface. System font fallback changes the design per machine; a flat scale (heading same size as body) removes hierarchy. A typeface such as Inter, Geist or IBM Plex Sans is built for UI sizes.
+Sources: https://practicaltypography.com/summary-of-key-rules.html , https://www.refactoringui.com/
+
+## Do
+
+- Bundle the font files with the app; do not depend on the user having the face installed.
+- Use the kit's type scale and at most two body weights plus one bold for titles.
+- Tighten letter-spacing slightly on large headings; never on body text.
+- Use real typographic characters: an ellipsis, en dash, multiplication sign, curly quotes.
+
+## Don't
+
+- Set `font-family: system-ui` and hope.
+- Introduce ad-hoc font sizes outside the scale.
+- Use more than three weights on a page.
+
+## In tsumikit
+
+- Inter bundled via `styles/font.css`; `--font-sans` is the default stack, `--font-mono` for code.
+- Type scale `--fs-2xs` (11) through `--fs-3xl` (36), scaled by `--fs-scale` (see `FontScalePicker`).
+- Weights `--fw-normal`, `--fw-medium`, `--fw-semibold`, `--fw-bold`; line heights `--lh-heading`, `--lh-normal`.
+- `Heading` and `Text` cover titles, body, labels, captions and eyebrows.
+- Lint rule `no-raw-font` flags font-family or font-size literals in app styles.
+
+## Check
+
+Open dev tools on headings and body and list the font sizes in use. They must all be scale steps and the rendered family must be the bundled one, not a fallback. Count the weights: three at most.

package/principles/11-mono-only-for-code.md

@@ -0,0 +1,30 @@
+# Monospace only for code
+
+Use a monospace face only for things that are literally code-like: paths, hashes, identifiers, commands.
+
+## Why
+
+Practical Typography: monospace is slower to read and takes more width per character. Set as prose or labels it makes an interface feel like a terminal and wastes space; set on genuine code it signals "copy this exactly".
+Source: https://practicaltypography.com/summary-of-key-rules.html
+
+## Do
+
+- Mono for file paths, commit hashes, IDs, shell commands and code blocks.
+- Sans for labels, nav, buttons, descriptions, timestamps and numbers in running text.
+- Tabular numerals (`font-variant-numeric: tabular-nums`) in tables and stats so columns line up without going mono.
+
+## Don't
+
+- Set a whole sidebar or label system in mono.
+- Use mono for numbers only to align them.
+- Mix two mono faces.
+
+## In tsumikit
+
+- `--font-mono` is only applied in code slots; `--font-numeric` and `--font-label` default to sans and can be switched to mono per app.
+- `Text` `variant="code"`, `CodeBlock`, `Kbd`, `WorkingDir`, `GitRef` are the mono components.
+- `Prose` and `renderMarkdown()` set inline code in mono and prose in sans.
+
+## Check
+
+Select all monospace text on the screen. For each run ask: would a user copy this character by character? If not, it should be sans.

package/principles/12-measure.md

@@ -0,0 +1,29 @@
+# Keep lines between 45 and 75 characters
+
+Body text runs 45 to 75 characters per line so the eye finds the next line without effort.
+
+## Why
+
+Practical Typography: lines shorter than about 45 characters break the rhythm; longer than about 75, the eye loses its place on the return sweep. Line length matters more than font size for reading comfort.
+Source: https://practicaltypography.com/summary-of-key-rules.html
+
+## Do
+
+- Cap reading columns with a max width in `ch` or `rem`, independent of the viewport.
+- Raise line height slightly as lines get longer.
+- On wide screens, add columns or margins rather than stretching the text.
+
+## Don't
+
+- Let descriptions, prose or form help text run the full width of a 1600px window.
+- Shrink the font to make long lines fit.
+
+## In tsumikit
+
+- `--measure` sets the default reading width; `--content-max` caps page content.
+- `Prose` and `EmptyState` descriptions are measure-limited; `Container` constrains layouts.
+- Line-height tokens `--lh-normal`, `--lh-snug`.
+
+## Check
+
+Count characters on a full line of body text at the widest supported viewport. Between 45 and 75.

package/principles/13-imagery-sets-the-mood.md

@@ -0,0 +1,32 @@
+# Let imagery set the mood, keep the chrome quiet
+
+Content imagery carries atmosphere; UI chrome stays neutral, text over images sits on a scrim, and a missing image gets a designed placeholder.
+
+## Why
+
+Aesthetic-usability effect: interfaces perceived as beautiful are perceived as easier to use and are forgiven more. A backdrop fading into the page does more than any amount of styled chrome. An empty grey box where an image should be breaks the spell instantly.
+Sources: https://lawsofux.com/aesthetic-usability-effect/ , https://www.refactoringui.com/
+
+## Do
+
+- Lead detail pages with a backdrop or hero image that fades into the page background.
+- Place text over images only on a gradient scrim that guarantees contrast.
+- Generate a placeholder from the item itself (initials, a hue derived from its name) when the image is missing or still loading.
+- Give every meaningful image alt text; decorative images get an empty alt.
+
+## Don't
+
+- Compete with the image using coloured chrome or heavy borders.
+- Render white text directly on an unpredictable photo.
+- Show an empty or broken-image box, even briefly.
+
+## In tsumikit
+
+- `Backdrop` layout for the hero-with-fade; `Scrim` for readable text over images.
+- `Artwork` shows a designed placeholder while loading or missing, via `artworkGradient()`, `artworkHue()` and `initials()`; `Avatar` does the same for people.
+- `Skeleton` for placeholders that are shapes rather than pictures.
+- Lint rule `img-alt` requires alt text on images.
+
+## Check
+
+Load the page with images blocked. Every image slot must still show an intentional placeholder. Then re-enable images and verify text over them passes 4.5:1 at its lightest point.