The PWA’s design system

The phone app is a tool you reach for one-handed, often in a hurry: open, capture, gone. The design follows from that, and from keeping the app tiny: the shell (capture, lists, pages, search) uses no UI framework, icon library or web font, and its JavaScript is held under 16.5 kB gzipped (npm run size, web/scripts/size.mjs). The one exception is the drawing viewer for a photo’s drawing: a separate chunk, fetched only when a drawing is shown, built on React and Excalidraw with Excalidraw’s own fonts (served by scrap from /excalidraw/fonts/), and outside that budget. Everything visual is defined once, in web/src/tokens.css; the components in web/src/style.css (which imports web/src/css/*.css) and web/src/excalidraw.css (the photo panel and the drawing viewer) use nothing else. This page is the portable description, for carrying the design into another tool and back.

Principles

• Paper and ink, one colour. Warm off-white paper and warm black ink in daylight, a warm near-black and cream at night, and a single amber (a sticky note: scrap’s mark). Filled amber is the one hero (the screen’s primary action) and the badge dot; amber-soft means only “selected” or “active” (a chosen chip or segment, the current nav tab, a match highlight), never a label, count or state; and there is no amber decorative text and no amber link in the app’s chrome (counts, headers, Claude’s cards): links there are ink, underlined (Links, below). Amber link text is the owner’s own text’s alone. Red means only “destructive”, “failed” or “overdue”. No blue-greys, no second accent.

• Links: every text link is underlined; its colour says whose it is. A link in the owner’s own text (a page’s Markdown and [[wiki]] links, a topic’s notes, the editor’s Preview: .body) is --accent-ink, underlined. Every other text link, Claude’s (Related, Topics, Sources, a write-up’s links) and the app’s (Regenerate, Clear filters, Clear all, Edit pins, Put back, Discard it, “by Claude”), is its text colour (--ink, or --ink-2 for a quiet control) over a thin underline: --line-strong, 1 px, offset 0.2 em. On a card where --line-strong is under 3:1 (the Claude card’s --sunk, the restored-draft line’s --accent-soft) the underline is --ink-2 (--link-line). Each keeps its weight; Claude’s links are regular. One rule draws them all (a, .link in css/base.css, and :where(.body) a for the owner’s, a write-up’s .body excepted), so a new link follows it without a rule of its own. Not text links, so not underlined: whole-row list items (search, Todos, topic, Pinned and Recent rows), chips and pills (tags, filters, the due chip), icon buttons, the nav and the kind row, buttons that look like buttons (.button, Download, a link card, a file card), the top bar’s Back and jump, footnote marks, and a section’s heading that links (a Type heading, which reads as a heading).

• One hero per screen. Composer and editor: Save, the one amber fill. Todos: no hero (New todo is a quiet + in the top bar). Capture: no hero; its four actions (Camera, Gallery, File, Note) are equal tiles, since none is more likely than the others (on a computer two: Add files and Note). Page: a todo’s or a Later’s Mark done, the toolbar’s one fill; a page with no status has none. Everything else steps down: secondary (outlined surface), then ghost (text only).

• Under the thumb. Actions on the thing in hand live at the bottom: Capture’s actions and the nav on a list screen, a page’s toolbar on a page. Getting around lives in the top bar (Back and the jump to the list), so a page has no nav and its bottom bar only ever acts on that page. On a computer (a mouse and a window 900 px wide or more: css/desktop.css, one media query, so a phone or a touch tablet never changes) things go where the eye and the mouse already are instead: the nav is tabs in the middle of the top bar (icon beside its word, the current one on --accent-soft, the Todos count after the word; on a list screen the top bar’s own column is 960 px there, and a long development version in the wordmark is cut with …, so four tabs clear the wordmark and Settings; a page, which has no nav, keeps its Back, jump to the list and pager on the same column, 800 px by default and as wide as Settings’ Maximum column width allows), Capture’s tiles are a row over the list, a page’s actions are a row of buttons under its title, meta line, dates line and chip row, kept in view under the top bar as it scrolls (Mark done filled, Delete apart at the end), toasts sit at the window’s foot as wide as they need, and rows, chips, tiles and ghost buttons take --sunk on hover. Cancel, Preview and Save sit in the editor’s top bar because the keyboard owns the bottom.

• Drill down, then Back, named. A page is a drill-down. On every phone and browser the top bar swaps the wordmark for Back named for where it goes (‹ Search, ‹ Todos, ‹ Topics, ‹ Capture, or a page’s title), as a mail app’s ‹ Inbox, and it goes up one level: to the page you followed a link from, else to the list you opened it from (past the pages the pager stepped through). When Back doesn’t go to the list, the list’s name follows it as a second target, ‹ A · Search, which jumps straight back to the list. A page opened cold goes up to its parent list (Todos for a todo, Topics for a topic, Capture for any other page): Back goes where its label says, with no request, so while the page is still loading that is Capture and on a stalled link it is never a dead button. Every link to a page, [[slug]] or its full address on any address the server is reached at (the one the app was opened at, and each in SCRAP_PUBLIC_URL, which the server writes into index.html’s scrap-origins meta tag), opens in place, so the phone’s own Back walks back through them one step at a time, as the top bar’s Back does after a link. Delete is one step back (the list, or the page whose link opened it) with Undo; opened cold, it goes where Back names. Whichever Back (the top bar’s, the jump, the phone’s) or Forward, a screen comes back scrolled where it was left (scroll.ts: the position rides in its history entry, put back once the screen is tall enough, never smoothly; the search screen keeps its own).

• Icons with words. Icons help find a control; the word says what it does. Icon-only buttons (close, previous/next photo, remove a photo) carry an aria-label.

• Calm states. Empty, offline and error states are an icon, one plain sentence and at most one action (offline or unreachable, everywhere search included: why, and Retry). On the capture screen a problem is a quiet inline line, never a whole screen; offline there is the badge, the waiting rows and one line, with no card, Retry or toast.

• Say it once. A row shows its kind by its icon alone, and a status that ends it (done, cancelled) as a word on its meta line (”· done”). A page says its kind and status once, in its meta line. A count shown in a header is not said again by an empty state (a search with no results shows no count).

• Few sizes, one style per job. A screen’s text uses few sizes, each for one role (a page’s header: two; a Claude card: two); a pill or chip has one style per job: selected or active on --accent-soft, a tag on --sunk, an editable chip as the others it sits with. One chip size app-wide (Chip, below): --t-sm text in a 32 px pill drawn inside a 48 px target. A label never breaks inside a phrase: a line of “ · “-separated parts breaks only before a “·”, which leads the part after it, so no line ends in one.

• Dark is designed, not inverted. Surfaces get lighter as they come forward; amber is a step lighter; toasts stay dark slabs in both themes.

• Every gesture has a button. Swipes are shortcuts, never the only way: a row’s Edit and Delete are also on its page (and a row’s tick is a button of its own, with Mark done and Reopen on the page too), the page’s swipe is also its ∧ ∨ pager and the arrow keys. Gestures start away from the screen’s edges, which belong to the phone’s Back gesture.

• Motion confirms, never decorates. 90-260 ms, eased out; none under reduced motion. The two looping indicators (busy, loading image) are the only motion that runs longer.

Tokens

Light / dark values, held to WCAG AA (4.5:1 for text, 3:1 for control edges) twice: web/tests/contrast.test.ts reads tokens.css and checks the listed text/background pairs, every rule in web/src/css/ that sets both a text colour and a background from tokens, and white text on --overlay over a white photo; and an end-to-end sweep (the lowContrast helper in web/e2e/contrast.ts, run by web/e2e/view.spec.ts on each screen in both themes and by several other e2e specs) computes the real colour of every visible piece of text and of what lies behind it.

The theme follows the system unless Settings (the top bar’s cog) says otherwise (24. A settings pane in the top bar, with theme overrides): Light or Dark sets data-theme on <html>, which tokens.css reads in place of the media query (web/src/theme.ts). Drawings have a theme of their own, Light by default.

The browser’s theme-color follows the colour scheme: two <meta name="theme-color"> tags in web/index.html, one per scheme, with the --bg values below (theme.ts sets both to the chosen one when the theme is forced). The PWA manifest (web/public/manifest.webmanifest) does not: its theme_color and background_color are a fixed dark #161411.

Token	Light	Dark	Role
--bg	#f6f3ec	#161411	the page; theme-color
--surface	#fffdf9	#211e1a	cards, list groups, fields
--sunk	#ece7dd	#2c2723	wells: tiles, segmented track, placeholders, pressed
--ink	#1e1b16	#f2ece1	text
--ink-2	#5c564c	#b8b0a2	secondary text: dates, hints
--ink-3	#6e675c	#958d80	placeholders, captions
--line	#e2dccf	#423b33	hairlines (decorative)
--line-strong	#8f8778	#706858	field and control edges; the underline of a link that isn’t the owner’s (--ink-2 on --sunk, where it is under 3:1)
--accent	#eba13a	#f0ac4b	the hero’s fill, the badge dot, a selected segment’s icon, a new topic’s dot
--on-accent	#1e1b16	#1e1b16	text on accent
--accent-ink	#8a4f00	#f3b65c	accent as text: links in the owner’s text, focus ring, active icon
--accent-soft	#f8e6c6	#3a2c17	selected or active only: a chosen chip, the active nav pill, a pressed toggle, match highlights, a swipe to Edit
--danger	#b42318	#f29086	destructive, failed (text)
--danger-soft	#fbe4df	#3b201c	failed badge, conflict banner
--toast / --on-toast	#2a2620 / #f6f1e7	#3a352d / #f2ece1	toasts
--toast-action	#f3b65c	#f3b65c	a toast’s action
--viewer	#000000	#000000	the photo viewer’s backdrop
--on-overlay	#ffffff	#ffffff	text and icons over photos
--overlay	rgb(0 0 0 / 65%)	same	pills, scrims and buttons over photos (white on it is over 4.5:1 even on a white photo)

Presses, edges and washes that need a translucent tint mix a token with transparent (color-mix(in srgb, var(--ink) 14%, transparent)) rather than writing a new colour.

Type: the system UI face (Roboto on Android; --font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif, and --mono for code: ui-monospace, "SF Mono", Menlo, Consolas, monospace); a 17 px root, so a rem is 17 px and --t-xs (0.75rem) is 12.75 px. Settings’ Text size sets the root: 100% (the default, 17 px, sized as a web page is, so the browser’s zoom applies) or a percentage of it, inline on <html> (main.ts at the start and when the app comes back, theme-init.js before the first paint), or Phone (data-text="phone"). With Phone, on Android the root follows the phone’s font size: index.html opts in with <meta name="text-scale" content="scale"> (Chrome 146+) and the root is calc(17px * env(preferred-text-scale, 1)); on iPhone the root follows the phone’s text size, Larger Text too (font: -apple-system-body, applied only where -webkit-touch-callout exists, so iOS and not a Mac), with scrap’s own family and line height set again after it; a small check in main.ts keeps it from going under 17 px (the smaller settings, with Phone), measured again whenever the app comes back. --t-xs 0.75rem (labels under icons, chips), --t-sm 0.875rem (meta, small buttons), --t-md 1rem (body, list titles), --t-lg 1.1875rem (wordmark, field titles, a Markdown h2), --t-xl 1.5rem (page title). Markdown headings step down a size a level, all under the page title: h1 1.3125rem, h2 --t-lg, h3 1.0625rem semibold, h4-h6 --t-md. Line height --lh 1.5, --lh-tight 1.25 for titles, 1.6 for page text. Weights 500 (controls), 600 (titles, labels), 700 (page title, active nav).

Space: a 4 px grid, --s-1..--s-7 = 4, 8, 12, 16, 24, 32, 48. Screen gutter 16. Radius: --r-sm 8 (thumbnails, code), --r-md 12 (buttons, fields, toasts), --r-lg 16 (cards, lists, photos), --r-pill (badge, search field, nav indicator). Size: --tap 48 (the touch target, extended with an invisible ::after where the drawn control is smaller; the exceptions are listed under “What we don’t do”), --bar-h 56, --nav-h 64 (max(64px, 1.125rem + 44px): taller when its labels are, at a large text size). Elevation: --shadow (selected segment), --shadow-2 (capture cluster, toasts). Motion: --d-1 90 ms (press), --d-2 180 ms (view enter, toast), --d-3 260 ms (editor sheet, viewer); --ease cubic-bezier(0.2, 0.8, 0.2, 1). Under prefers-reduced-motion all three are 0, and the two looping indicators stop: the placeholder shimmer (1.2 s, alternating) and the busy icon’s pulse (0.8 s, see Busy under States). Those two are not on the --d-* scale: they repeat only while the work or the image is in progress.

Components

Component	Class / element	Notes
Button, secondary	button, .button	surface, hairline edge, 48 high, icon 20 + label; presses scale to 0.97 on --sunk
Button, primary	.primary	amber fill, ink label; one per screen (Save)
Button, ghost	.ghost, button.link	no fill (Cancel, Discard it, the pager’s ∧ ∨)
Button, danger	.danger	red label, never filled
Tile	.tile	icon over a short label on --sunk, 72 high; the capture actions Camera, Gallery, File and Note, four equal columns; on a computer Add files (.desk, shown only on a computer, DESK: one picker for photos and files) and Note, two
Toolbar	.tools	icon-over-label tiles sharing the width by their labels (flex: 1 1 auto), so no word is cut, every label --t-xs; page actions only, no navigation tiles (sticky at the bottom, where the nav would be: a page has none; over the page text: z-index 2), viewer tools. A page’s order: Mark done (a todo or a Later open or in progress: .primary, --accent fill, --on-accent label, --r-md corners, wider at flex: 1.6 1 auto, the check icon), or Reopen in its place once done or cancelled (plain, the retry icon: a cancelled one looks closed, so it offers only Reopen), Edit (or Edit draft), Share, Delete (danger); Download is in Share’s menu, or in Share’s place where the browser can’t share. Four fit whole at 360 px. Always the page’s: a page has no form in place (its tags and due date are changed in the editor, Edit), so the row never changes shape. On a computer the same row under the header
Segmented control	.chips (radio group)	the editor’s kind (.kinds: Note, Todo, Later, Board, Doc: short labels so all five fit one row from 320 px, with the full names Whiteboard and Document as the radios’ accessible names and titles), the search screen’s kind row (.kindrow: All, Notes, Todos, Later, Boards, Docs, each its kind’s 18 px icon over its word, All a grid of four tiles, so all six fit one row from 320 px; always shown, under the filters on; one tap sets or clears kind:, Todos included: it filters in place like the others), the Todos screen’s Now (a clock), Upcoming (the due calendar) and All (the grid), drawn as the kind row; selected = raised surface, amber icon. The editor’s kind picker draws each kind’s icon over its word too (--t-xs), as the kind rows do, so every kind bar shows its icons at every width; at a large text size the kind rows and the picker wrap rather than clip
Chip	.facet, .tags :is(a, button), .chipfield	one chip size app-wide: every chip (the tag picker’s chosen and offered, the due chips, the Filters panel’s When, Order and Group, the Filters on, a page’s own chip row) is --t-sm text (--lh-tight) in a 32 px pill drawn inside a 48 px target: 8 px transparent borders above and below, the fill clipped to the padding box (background-clip: padding-box, so a fill is set with background-color, never the background shorthand) and an outlined chip’s edge an inset 1 px ring (box-shadow: --line, --line-strong for the picker’s offers; none on a chosen one); 0.6em inline padding. Rows of them touch (no row gap), leaving 16 px between the drawn pills. A long tag path wraps inside its chip, which grows a line. The fields beside them, the tag box and the Priority select (.chipfield), are drawn the same: 32 px in a 48 px target, a --line-strong ring, the focus ring an inset 2 px --accent-ink ring. sim/sizes.mjs (the design sim) checks none is larger than --t-sm
Top bar	header	wordmark with the scrap mark; at the right, the queue badge, then Settings (#settings, a ghost cog with eight teeth, “Settings”, on every screen: it opens a sheet like the editor’s with two radio groups, App theme System / Light / Dark and Drawings theme Light / Dark / Same as app, then under Store a Store health link and a Trash link, each with a button’s look and a hint line; Done, Escape or Back close it, and Store health or Trash closes it, then opens its screen). The wordmark’s version (#ver, --t-sm, --ink-2) sits on its baseline. On a page, on every phone and browser, Back in the wordmark’s place (#back, a ghost button 48 high: the arrow, then where it goes in --t-md semibold, #backto: “Search”, “Todos”, “Capture”, or the title of the page a link was followed from; accessible name “Back to Search”): it goes up one level, to the page a link was followed from, else to the list the page was opened from, else up to a parent: Todos for a todo, Topics for a topic, Capture for any other page (go() gives each entry it pushes its depth, the list it came from, kept by a page opened from a page, and, opened from a page, that page’s depth and title, kept by a replace, so Back is one history.go(-n); each screen records its name for its depth (crumbs.ts: a list’s when drawn, a page’s title each time it is shown, so renamed in its editor or by Claude too) in sessionStorage and in memory, so Back names a page as it is now, renamed, stepped on by the pager or replaced by its parent, a reload keeps it, and a browser that refuses storage still has it; a list’s mark says where it was, so only a name recorded there names it). After Back, either the jump to the list or the pager. The jump (#jump, on every phone and computer: a page has no nav), when Back goes to a page that isn’t the list: a dot (aria-hidden), then the list’s name, a ghost text button with no icon (#tolist, --t-sm, --ink-2, 48 high; accessible name “Back to Search”), which goes straight to the list (one history.go(-n)); the pager (below, in #pos) when the page was opened from a list. Then the queue badge and Settings. Back ends where the jump begins (header.crumb), else at the free space before the right-hand controls; its label is cut with …. Beside the jump (header.crumb) Back never shrinks under 6.5 rem (the arrow and a few letters) and the badge and Settings never shrink (flex: none), so Back’s label gives up the width; elsewhere (a list screen, a page with its pager) they may, so the wordmark, a two-part badge, New todo and Settings fit at 320 px, and a pager beside a badge does not widen the page. Sharing the bar with the jump or the pager under 560 px, the badge is compact, its dot and count (”● 2”, a 48 px target with the 36 px pill drawn inside), named with the count and its words (“2 queued: 1 waiting · 1 failed”): at 360 px with it up, Back keeps about 150 px of a title, at 320 about 110. On the Todos screen, New todo (#new, a ghost plus, “New todo”) at the right end, the badge beside it when up: it opens the composer with Todo chosen (kept even if the text is a link), which closes back onto the list; the list fetches again as the upload queue changes, so the new todo joins it
Badge	.badge, .badge.failed	a pill on --sunk with a status dot: the amber dot alone says waiting (the pill is no amber-soft: that means selected); failed is --danger-soft with a red dot and --danger words; “1 waiting · 1 failed”, named with its count first, “2 queued: 1 waiting · 1 failed”, so the compact badge’s “2” leads its name. On a page under 560 px wide whose top bar also holds the jump or the pager: compact, the dot and the count (”● 2”)
Bottom nav	nav	four tabs, Capture, Todos, Search, Topics (the newest last, so the others keep their places): icon over label; active item gets an amber-soft pill and ink label (aria-current). List screens only: a page hides it (body.paged), its toolbar is its only bottom bar, and the top bar’s Back and jump are the way out. It grows with its labels at a large text size (--nav-h)
Nav count	nav .due-n	the Todos tab’s open todos due today or overdue: a 20 px --ink pill with --bg digits on the icon’s corner (after the word on a computer), ringed in --bg: a count, never amber; hidden at 0; the tab’s accessible name says it (“Todos, 3 due”). One count request when the app opens or comes back and after a change, never polled
List group	.list	rows in one rounded card; .pending is dashed (still on the phone)
List row	.list li	48 thumbnail or kind icon (the icon says the kind), title, then one meta line: its date, or for a todo with a due line its due line in the date’s place (“high · due 26 Oct · 1 of 4”, small.due; a priority alone says “low priority”), a Later’s medium (”· Book”), a topic’s “· Topic”, and a status that ends it as a word (”· done”, em, classed by its word); a search hit’s snippet, tidied (snipclean.ts: task boxes out, a web address said as words, “en.wikipedia.org · wiki / Integrated information theory”, a title leading it cut away; a long word breaks rather than being clipped), and none if it only repeats the title (the same whole words in order, punctuation, hyphens, underscores and case aside: echoes() in snippet.ts); a cancelled row (li.cancelled) has its title struck through in --ink-2; actions under it (.rowbar: whole words, the bar wraps to a second line rather than breaking a label such as Split and retry); a focused row draws its ring inside the card
Swipe row	.list li.swipe, .row-under	follows the finger; behind it Edit on --accent-soft (right) or Delete on --danger-soft (left); past the threshold the icon grows (Edit’s turns --accent-ink, its fill staying --accent-soft) and letting go does it
Fold	.claude-text (details)	hairline above, a chevron before the heading: right folded, down open
Pager	.pager	a page opened from a list, in the top bar as a mail app has it: “3 of 23” (.pager .at, --ink-2), then ∧ (previous) and ∨ (next), 40 px ghost links, the one with nothing that way at 35 % opacity. Its group’s label says which list (“In Latest”): “Latest” (Capture’s list, and the search screen’s newest-first list), the kind row’s name when one kind is chosen alone (“Notes”, “Todos”, “Later”, “Boards”, “Docs”), “Search results”, “Todos · Now”, “Todos · Upcoming”, “Todos · All” and “Todos · Done” (the Todos screen’s folded done and cancelled), “Topics”; Back beside it names the list’s screen and goes back to it; the page follows a sideways swipe and slides off to the next. From the Todos screen, Mark done steps on to the next todo with a toast “Done: