Skip to content

Kist brand

Kist is a self-hosted visual library for people and their AI agents.

Tagline: Keep what catches your eye.

Every asset here is generated by docs/brand/build_brand.py from one construction, so a change to the mark is one edit plus a re-run (python docs/brand/build_brand.py --raster, needs fontTools and Pillow; see the script header). Masters live in docs/brand/, the shipped icons in web/public/, and the inline paths the app uses in web/src/brandPaths.ts.

The mark: Corners

Two L-shaped brackets at opposite corners of an implied square, and a small square in the middle: the kept item. It reads three ways at once: the brass corner guards on a wooden chest, the paper corners that hold a photo in an album, and a designer's crop marks. Chest, photographs, picked.

mark

Construction (64-unit grid)

Every length is a multiple of 4, so at 16 px (4 units per pixel) every edge lands on a whole pixel.

Part Bare mark (GLYPH) On an app tile (APP) On a small tile (TAB)
Frame 4–60 12–52 8–56
Bracket arm length 24 20 20
Bracket thickness 8 8 8
Kept item 8 × 8, centred 8 × 8 8 × 8
Used for favicon.svg, mono, dashboards, in-app, lockup apple-touch, 192/512, maskable favicon.ico, favicon-32.png
  • Outer corner of each bracket: radius 2. Inner corner and the arm ends: radius 0.5, so it looks stamped from metal rather than drawn as a line icon. Kept item: radius 1.5.
  • The two brackets never overlap or run past each other (that is what keeps it apart from Lucide's crop).
  • At 16 px the mark is two 2 px-thick Ls and a 2 px dot: ⌜ · ⌟.
  • Maskable: full-bleed tile, the APP mark scaled to 0.8 about the centre. Its corners sit 22.6 units from the centre, inside the 25.6-unit (40 %) safe circle.
  • Monochrome: the mark is solid shapes only, so it survives iOS tinting and single-colour use without change. icon-mono.svg (black, manifest monochrome), kist-light.svg (white, for dark dashboards), kist-dark.svg (#1C1B19, for light dashboards).
  • Clear space: at least the bracket thickness (8 units = 1/7 of the bare mark) on every side; in the lockup, the gap between mark and wordmark.
  • Minimum size: 16 px for the bare mark; the tile versions from 16 px.

Icon kit (web/public)

Tiles are dark grey #3A3A3A with the mark in white (#1C1C1A with a brass mark until Nov 2026).

File Size Notes
favicon.svg any bare mark; dark grey #2B2B2B on light browser chrome, #ECEAE4 on dark (prefers-color-scheme)
favicon.ico 16, 32, 48 small tile; each size rendered from the SVG, not downscaled
favicon-32.png 32 small tile
apple-touch-icon.png 180 opaque, full bleed (iOS rounds the corners itself)
icon-192.png, icon-512.png 192, 512 rounded tile, purpose: any
icon-maskable-512.png 512 full bleed, mark inside the safe circle
icon-mono.svg any single colour, purpose: monochrome
manifest.webmanifest name, short name, standalone, colours, icons

Bump the ?v= on every icon URL (index.html, manifest) when an icon changes: browsers cache icons by URL.

Wordmark

Lowercase kist in Instrument Serif Regular, tracking −1 %, outlined to paths (no font needed at runtime). The dot of the i is a small square that echoes the kept item in the mark (it replaces the round dot, centred where it was, 92 % of its width).

  • Lockup: mark height = cap height × 1.25, centred on the cap height; gap = twice the i's stem width. (lockup-dark.svg, lockup-light.svg)
  • Ink: #ECEAE4 on dark, #1C1B19 on light. Dot: the same ink as the letters (brass until Nov 2026).
  • Never set the name in capitals in the wordmark; in running text it is "Kist".

Palette

The images carry the colour; the chrome stays neutral and the accent is monochrome: the theme's own ink (near-white on dark and gallery, dark grey #2B2B2B on light). Brass was dropped in Nov 2026 (Jay); the only hues left in the chrome are danger red, success green and info blue. All colours are CSS variables in web/src/themes.css; nothing else in the stylesheet hard-codes a theme colour (the only fixed colours are the dark badges and captions drawn over images).

Token Dark Light Gallery grey
bg #131312 #FAF9F6 #5C5C5C
bg-raised #1C1C1A #FFFFFF #565656
text #ECEAE4 #1C1B19 #F5F5F5
text-dim #9C9A93 #5F5D57 #DADADA
accent / focus / stars / warn #ECEAE4 #2B2B2B #FFFFFF (warn #F5F5F5)
primary / on-primary / primary-line (primary button: fill, label, outline) #3A3A38 / #FFFFFF / #ECEAE4 #2B2B2B / #FFFFFF / #2B2B2B #2B2B2B / #FFFFFF / #F5F5F5
on-accent #131312 #FFFFFF #2B2B2B
field outline #6E6C66 #8A877F #BDBDBD
danger #F2716A #B42318 #FFD0CC
chip-bg / chip-text #31302D / #ECEAE4 #E6E3DC / #1C1B19 #4A4A4A / #F5F5F5
bg-float (menus, dialogs) #21211F #FFFFFF #454545
accent-soft (selected fill, neutral) / soft-dim #31302D / #9C9A93 #E6E3DC / #5F5D57 #4A4A4A / #DADADA
selected-line (1 px outline on selected/pressed) #9C9A93 #77746D #CFCFCF
success #5FC48A #1E7A46 #A8F0C4
chrome (top bar, side panels) #1C1C1A #FFFFFF #5C5C5C
chrome line (chrome / images edge) #34332F #E2DFD8 white 28 % (#FFFFFF47)
canvas (image surround) #131312 #ECECEC #5C5C5C
preview surround (preview-bg) #0D0D0C #5C5C5C #5C5C5C
Present surround, grey (present-grey) #5C5C5C #5C5C5C #5C5C5C
Present surround, black (present-black) #000000 #000000 #000000
Present caption title (present-text) #F5F5F5 #F5F5F5 #F5F5F5
Present caption credit (present-text-dim) #DADADA #DADADA #DADADA
phone-fill (phone controls) #2C2C29 #EFEDE8 #6A6A6A
phone-sunken (phone search pill) #121211 #EBE9E4 #4B4B4B
preview-capsule / preview-star (phone preview capsules) #262624 / #ECEAE4 #2A2A2A / #FFFFFF #2A2A2A / #FFFFFF
  • Gallery grey is for judging colour: one neutral mid-grey (#5C5C5C) behind everything, top bar, side panels, grid and full-screen preview alike, so the images are the only colour on screen. A thin light pinstripe (chrome-line) marks where the chrome meets the images. Two greys side by side read as a mistake, so the chrome never steps away from the canvas; menus and dialogs, which float, step darker (--bg-float). (Until Nov 2026 the canvas was the 18 % grey #767676, but on that grey only pure white text passes AA, so one surface there would have cost the accent links and coloured error text.)
  • Light theme: neutral canvas, grey preview. The chrome (top bar, sidebar, panels) stays warm paper, but the image canvas is a neutral #ECECEC: a warm near-white surround makes photos look cooler and darker than they are. The full-screen preview in light is the gallery grey #5C5C5C with gallery's preview colours, not near-black: jumping from paper to #0D0D0C was hard on the eye, and the mid-grey is the neutral surround photo apps offer for judging. This reverses the earlier "the preview always stays dark" rule; Jay approved it in the Nov 2026 aesthetic pass. Dark keeps its near-black preview.
  • Preview tokens. The preview and compare/survey overlays take their colours from --preview-* in themes.css (text, dim, accent, buttons, notes panel, field line, danger), contrast-checked like everything else, instead of hard-coded overrides. In gallery and light preview-dim is #dadada, a visible step below the white text (the caption's extension and dimensions).
  • Preview layout (desktop). Nothing sits on the picture: 64 px bands above and below the image (--preview-band; the image gets --preview-room, 100vh − 128 px) hold the controls. Top right: Loupe, Notes and Close as matching 32 px ghost buttons in one row (.preview-band). Bottom: a one-line Inter 13 caption, "name.ext · 3840 × 2628 px · 1 of 41" with the extension and facts in preview-dim, then "More like this" and "Open original" as underlined text actions. Both arrows look the same at rest (--text at 70 %); the one with nowhere to go is hidden. The phone keeps its own layout.
  • Browser and launch colours. The theme-color meta (the phone's status bar) is each theme's chrome (THEME_COLOR in theme.ts), and public/theme-init.js paints <html> in the theme's bg before the stylesheet loads (THEME_BG), so gallery and light never flash the dark #131312. The manifest's splash colour can only follow the OS scheme, not the stored theme. tests/theme.test.ts checks all three against themes.css.
  • The primary button is the one place dark grey is a fill in dark and gallery: #3A3A38 / #2B2B2B alone sinks into the page there, so it carries a 1 px --primary-line outline in the theme's ink (3:1 against the page).

Accent budget

The accent (ink) means one of four things, and nothing else:

  1. selection on images: the tile corners and check (the theme's --canvas-focus, white on dark and gallery, dark grey on light);
  2. the focus ring;
  3. ratings (stars);
  4. links and small accent fills (pick stamps, count badges, map pins).

The primary action (.btn-primary: Upload, Save, New token; one per view) is its own kind: a dark grey fill (--primary) with a white label and an ink outline (--primary-line). Warnings (--warn) are neutral too; only danger keeps its red.

Everything else is neutral: tag, folder and board chips use --chip-bg / --chip-text (tags are pills, folders have 6 px corners), inspector links are --text with a thin underline, and a pressed toggle is a fill, not a second primary button.

A selected row, section, chip or pressed toggle (sidebar, Settings nav, ⌘K active row, tag chips, the Info toggle, tile-shape and board tools) is a neutral fill (--accent-soft / --bg-active, both neutral greys despite the name) with a 1 px --selected-line outline that follows the control's own corners. No accent bars on a side or underneath: Jay found they read like a bracket hanging off the control (Nov 2026). Native checkboxes, radios, sliders and progress bars use accent-color: var(--text), and the date scrubber's position mark is --canvas-text, so neither adds an accent.

Contrast (WCAG 2.2 AA, computed from themes.css)

npm test fails if any pair drops below its minimum (web/tests/contrast.test.ts); node --experimental-strip-types scripts/contrast.ts in web/ prints this table. 4.5 = text (1.4.3); 3 = UI parts and focus indicators (1.4.11, 2.4.11/2.4.13).

Pair Min dark light gallery
body text (text on bg) 4.5 15.45 16.35 6.13
text on panels (text on bg-raised) 4.5 14.19 17.21 6.73
text on buttons (text on bg-hover) 4.5 12.44 14.84 7.40
text on pressed buttons (text on bg-active) 4.5 10.97 13.43 8.13
secondary text (text-dim on bg) 4.5 6.60 6.25 4.78
secondary text on panels (text-dim on bg-raised) 4.5 6.06 6.58 5.25
secondary text on hover (text-dim on bg-hover) 4.5 5.31 5.68 5.77
text in the top bar and side panels (text on chrome) 4.5 14.19 17.21 6.13
secondary text in the top bar and side panels (text-dim on chrome) 4.5 6.06 6.58 4.78
links in the top bar and side panels (accent on chrome) 4.5 14.19 14.16 6.69
links (accent on bg) 4.5 15.45 13.45 6.69
links on panels (accent on bg-raised) 4.5 14.19 14.16 7.34
label on an accent fill (pick stamps, badges) (on-accent on accent) 4.5 15.45 14.16 14.16
label on an accent fill, hover (on-accent on accent-hover) 4.5 18.59 18.88 11.34
primary button label (on-primary on primary) 4.5 11.40 14.16 14.16
primary button label, hover (on-primary on primary-hover) 4.5 9.32 18.88 11.73
primary button edge in the top bar (primary-line on chrome) 3 14.19 14.16 6.13
primary button edge (primary-line on bg) 3 15.45 13.45 6.13
primary button edge in dialogs (primary-line on bg-float) 3 13.41 14.16 8.79
selected row / chip text (text on accent-soft) 4.5 10.97 13.43 8.13
Present: caption title on the grey surround (present-text on present-grey) 4.5 6.13 6.13 6.13
Present: caption credit on the grey surround (present-text-dim on present-grey) 4.5 4.78 4.78 4.78
Present: caption title on the black surround (present-text on present-black) 4.5 19.26 19.26 19.26
Present: caption credit on the black surround (present-text-dim on present-black) 4.5 15.02 15.02 15.02
counts on a selected row (soft-dim on accent-soft) 4.5 4.69 5.14 6.34
selected-row outline (selected-line on accent-soft) 3 4.69 3.64 5.69
pressed-toggle outline (selected-line on bg-active) 3 4.69 3.64 5.69
selected outline against the chrome (selected-line on chrome) 3 6.06 4.66 4.29
active palette row outline (selected-line on float-hover) 3 4.69 4.02 5.02
phone: pressed toggle outline (selected-line on phone-fill) 3 4.97 3.99 3.47
selected outline in the preview and compare (preview-dim on preview-soft) 3 6.22 5.33 5.33
pressed-toggle outline in the preview (preview-dim on preview-active) 3 6.22 5.68 5.68
field outline (field-border on bg) 3 3.54 3.41 3.56
field outline on panels (field-border on bg-raised) 3 3.25 3.59 3.91
focus ring (focus on bg) 3 15.45 13.45 6.69
focus ring on panels (focus on bg-raised) 3 14.19 14.16 7.34
rating stars (star on bg-raised) 3 14.19 14.16 7.34
error text (danger on bg) 4.5 6.50 6.24 4.82
error text on panels (danger on bg-raised) 4.5 5.97 6.57 5.29
server banner (danger-on on danger-bg) 4.5 10.90 8.84 10.58
done marker (success on bg-raised) 3 7.92 5.35 5.57
warning icon (warn on bg-raised) 3 14.19 14.16 6.73
info text (info on bg-raised) 4.5 7.90 6.09 5.25
grid heading on the canvas (canvas-text on canvas) 4.5 15.45 14.57 6.13
grid counts on the canvas (canvas-dim on canvas) 4.5 6.60 5.57 4.78
tile focus ring (canvas-focus on canvas) 3 18.59 11.99 6.69
edge of a stack's second sheet on the canvas (field-border on canvas) 3 3.54 3.04 3.56
bar on a pressed toggle / selected section (accent on bg-active) 3 10.97 11.05 8.86
tag / folder / board chips (chip-text on chip-bg) 4.5 10.97 13.43 8.13
counts on chips (text-dim on chip-bg) 4.5 4.69 5.14 6.34
tile selection check (on-accent on canvas-focus) 4.5 18.59 14.16 14.16
phone: filled controls (top bar row two, sheet actions) (text on phone-fill) 4.5 11.64 14.71 4.96
phone: the sheet's Trash icon (danger on phone-fill) 3 4.90 5.62 3.90
phone: search pill text (text on phone-sunken) 4.5 15.58 14.18 8.00
phone: search pill placeholder (text-dim on phone-sunken) 4.5 6.66 5.43 6.24
phone preview: capsule buttons (preview-text on preview-capsule) 4.5 12.60 14.35 14.35
phone preview: stars in their capsule (preview-star on preview-capsule) 3 12.60 14.35 14.35
text on menus, dialogs, palette (text on bg-float) 4.5 13.41 17.21 8.79
secondary text on menus and dialogs (text-dim on bg-float) 4.5 5.73 6.58 6.86
links on menus and dialogs (accent on bg-float) 4.5 13.41 14.16 9.59
focus ring on menus and dialogs (focus on bg-float) 3 13.41 14.16 9.59
field outline in dialogs (field-border on bg-float) 3 3.07 3.59 5.10
error text in dialogs (danger on bg-float) 4.5 5.64 6.57 6.92
hovered / active menu row (text on float-hover) 4.5 10.97 14.84 7.17
secondary text on a hovered menu row (text-dim on float-hover) 4.5 4.69 5.68 5.59
active-row bar in the palette (accent on float-hover) 3 10.97 12.21 7.81
text in the full-screen preview (preview-text on preview-bg) 4.5 16.16 6.69 6.69
secondary text in the preview (preview-dim on preview-bg) 4.5 9.16 4.78 4.78
links and focus ring in the preview (preview-accent on preview-bg) 4.5 16.16 6.69 6.69
preview buttons (preview-text on preview-raised) 4.5 14.19 10.86 10.86
preview buttons, hover (preview-text on preview-hover) 4.5 12.44 9.29 9.29
preview buttons, pressed (preview-text on preview-active) 4.5 10.97 7.94 7.94
focus ring on preview buttons (preview-accent on preview-raised) 3 14.19 10.86 10.86
field outline in the preview (preview-line on preview-bg) 3 3.70 3.56 3.56
primary button in the preview (preview-on-accent on preview-accent) 4.5 15.45 18.88 18.88
notes panel text (preview-text on preview-panel) 4.5 15.45 13.58 13.58
notes panel secondary text (preview-dim on preview-panel) 4.5 8.76 9.71 9.71
error text in the notes panel (preview-danger on preview-panel) 4.5 6.50 9.79 9.79
selected chip in the preview (preview-text on preview-soft) 4.5 10.97 7.46 7.46
counts on a selected chip in the preview (preview-soft-dim on preview-soft) 4.5 4.69 7.46 7.46

all 240 pairs pass

Selected tiles use accent corners (--canvas-focus) with a 1 px black halo plus a check badge (--on-accent on --canvas-focus, #1A1408 outline), so the state reads on any image; the keyboard focus ring is a separate 2 px ring outside the tile.

Shared primitives (for anyone building UI)

Use these instead of new one-off values; each is documented below.

Need Use
A bar or side panel next to the images background: var(--chrome), edge 1px solid var(--chrome-line) (never --bg-raised / --border; tests/chrome.test.ts)
A button plain <button> (quiet), .btn-primary (one per view), .icon-btn (28 × 28 icon-only)
A pressed toggle .on (fill; .btn-icon / .icon-btn / .seg add the 1 px --selected-line outline)
A field or select <input>, <select> (own chevron), <textarea>
A selected row in a list fill + box-shadow: inset 3px 0 0 var(--accent)
A chip (tag, folder, board) .chip (--chip-bg / --chip-text), .chip.folder-chip for square-ish corners
Something that floats .float-surface (or --bg-float, --float-line, --float-shadow, --float-radius / --dialog-radius)
Appearing / leaving --dur-in + --ease-out with @keyframes float-in / float-up / panel-in; exit with fade-out over --dur-out (usePresence in motion.ts)
Phone sheet or drawer motion --dur-sheet + --ease-sheet
A view title / folder page title .view-title (24 px serif) / .page-title (34 px) + .title-eyebrow, count in .title-count
A small section label .section-label
A machine string .mono
Tile corners --tile-radius (4 / compact 0), --board-radius (2)
The preview surround --preview-* tokens

Controls

One height, three kinds. Nothing else.

Kind Class At rest Hover Pressed / on
Quiet any plain <button> (incl. .icon-btn, .btn-icon) no fill, no border --bg-hover fill --bg-active fill + 1 px --selected-line outline (.on)
Primary .btn-primary --accent fill, --on-accent label --accent-hover
Field input, select, textarea --field-border outline on --bg --accent border on focus
  • Every control is --ctl-h 28 px tall with --ctl-radius 6 px corners and 8 px side padding (--ctl-pad-x); icon-only quiet buttons are exactly 28 × 28. Phone layouts keep 44 px hit areas with their own min-height or an ::after (phone.css), not by changing the look.
  • Fields need the 3:1 outline (1.4.11); quiet buttons don't, because their label or icon identifies them. Keep a label on anything that isn't a well-known glyph.
  • Selects are fields with Kist's own chevron (--chevron in themes.css, the theme's dim text colour), appearance: none, still real <select>s.
  • One .btn-primary per view (Upload, Save, New token). button.danger is a quiet button with --danger text.
  • Links inside a sentence (.linkish, .link-btn, .btn-link, .link-like) are underlined --text, sized like text, not 28 px tall.

Top bar and grid header (desktop)

  • The top bar is one 48 px line: brand, the search box (32 px, one line, starting over the grid's left edge, the palette's ⌘K / Ctrl K as a keycap inside it that opens the palette), a spacer, Paste and Upload (the only primary control), a --chrome-line hairline (.topbar-sep), then the quiet icons (Info, Recent changes, Share, Appearance, Settings). Filter chips stay on the line and scroll sideways.
  • The view controls (tile shape, size, type, filters, rating, sort) sit in the grid header (.grid-meta) on the right, next to what they change; the title (.view-title, or .page-title with a .title-eyebrow on a folder or tag page) and its count on the left, on the tiles' left edge. Narrow grids (container query) drop the Size and Filters words. The header stays while a new list loads, so a control keeps focus.
  • The phone keeps its own two-row bar (ViewControls mobile in the top bar).
  • The selection bar (.bulkbar) shows only with two or more selected (one selected: the info panel has every action). It is one 40 px row docked under the grid, in the flow, on --chrome with a --chrome-line rule above: no float, no shadow. Order: count, clear, Tag field, Folder, Board, Pick, Reject, Label, then More (everything else, opening upward) and Trash last in --danger.

Settings and Appearance layout

  • Settings content is one 640 px column (--settings-col); a section's head puts its buttons (New token, Check again) on that column's right edge, not the window's.
  • The Appearance theme options show each theme's image canvas as a 20 × 14 colour chip (System: half light, half dark), and radios and chips sit on the first line of a two-line option.

Boards

  • The board bar is one 48 px row on --chrome that never wraps: back, the board's name as the view title (Instrument Serif 24, sized to its text), save state, then tool groups split by a --chrome-line hairline, and on the right zoom, List, background, Export and Share. The active tool is the pressed fill plus the thin --selected-line outline. Below about 1240 px the text labels (Boards, Library, List, Export) fold to icons and stay in the accessible name. The phone has its own header.
  • Items on a board are prints on a table: --board-radius (2 px), a contact shadow plus a soft lift (0 1px 2px #0006, 0 14px 30px -10px #000a); below 30 % zoom only the contact shadow stays.
  • Board background "Theme" (canvas.bg: "theme" in board.json) is the default for new boards: the board sits on the theme's image canvas, and text and arrows without their own colour use --canvas-text / --canvas-dim. Boards from before the design pass keep their colour. Exports and the board thumbnail have no theme, so a theme board renders on the gallery grey #5c5c5c with white default ink.

Corners

Photos are prints, not app cards: small radii on images, none where the image is judged.

Where Radius Token
Grid tiles (comfortable, gallery density) 4 px --tile-radius
Grid tiles, compact density (a contact sheet) 0 --tile-radius
Full-screen preview image 0
Board items 2 px --board-radius
Controls (buttons, fields) 6 px --ctl-radius
Menus, popovers, toasts 10 px --float-radius
Dialogs and the command palette 12 px --dialog-radius

Grid tiles

The images lead; anything drawn on them earns its place.

  • Loading: a tile with no ThumbHash or colour yet is --tile-wait (one step off --canvas: gallery #676767, dark #232321, light #E0E0E0; decorative, no contrast minimum) with a faint 1.4 s sheen (none under reduced motion). Badges stay hidden until the thumbnail has loaded (img.loaded), or failed (img.failed, which also stops the sheen).
  • Ratings (quiet tiles): one star (white on the caption's gradient) and a tabular number ("★ 5"), bottom right on the caption's dark gradient, only on hover, keyboard focus or selection; on every tile while the grid is filtered or sorted by rating (.ratings-shown, ratingsShown() in query.ts). Never on a phone tile. The rating is always in the tile's aria-label.
  • Stacks: a closed stack's entry (.tile.stacked) has a second sheet 4 px up and right behind it (--tile-wait fill, --field-border edge, 3:1 on the canvas), drawn with box shadows. Its count badge shows on hover, focus and selection; compact density has no room for the sheet and keeps the badge. The count is in the aria-label ("stack of 2 items").

  • Gutters and the date rail: 12 px from the sidebar to the first tile and 12 px from the last tile to the 30 px date rail; the rail starts 8 px below the grid header, year labels are centred in it and hang 4 px below their tick (clear of the accent mark and the info panel's line).

  • Counts: the grid header leads with the same number as the sidebar (every item) and adds the tiles when closed stacks make fewer: "43 items · 41 tiles" (gridCountText / sidebarCount in query.ts). A search or filter shows just its number of results.

  • Empty states (EmptyState in GridExtras.tsx): the outline mark (OutlineMark, Brand.tsx: brackets as thin --canvas-dim lines, the kept item a solid --accent square; aria-hidden), one Instrument Serif line (24 px, at most 22ch), one dim 13 px line and at most one action. Empty Unfiled, Trash, Picks, Rejects, a folder, a tag, a smart folder and a search with no hits all use it (words in emptyState, query.ts); the view's subtitle hides while the grid is empty so nothing is said twice.

  • Labels get their own section head under Cull: 12 px colour dots with a 1 px --field-border ring (the ring carries the 3:1 boundary, since some label colours alone don't reach it on the grey), each in a 24 px target, the first on the icon column; pressed adds a --text ring. The info panel's and triage's label pickers stay 24 px discs (editing controls).
  • Tags show as a wrapped cloud of 24 px neutral chips (.tag-cloud-chip: --chip-bg / --chip-text, count in --text-dim, no # icon); a tag you're filtering by takes the selected fill (--accent-soft with a 1 px --selected-line edge). Two small toggles in the Tags head switch to the list (better for hundreds of tags); the choice is a pref (kist.tagView).

Type

Role Face Where
Title (.view-title) Instrument Serif 400, 24 px (--fs-5), line-height 1.05, −0.005em every view, page and panel title: Timeline, Map, Boards, Triage, each Settings and Organise section, "No selection"
Page title (.page-title) Instrument Serif 400, 34 px (--fs-6) a folder or tag page, with a .title-eyebrow (Inter 11 px, dim) naming the parent folder above it
UI Inter Variable everything below a title
Counts (.title-count, .count) Inter, tabular-nums numbers a person reads: counts, sizes, dates, "1 of 41"
Data (.mono) JetBrains Mono Variable, 11 px strings a machine made: hash, MIME type, URL, pixel dimensions, hex, version
Wordmark, empty states, crash page Instrument Serif sparingly

Instrument Serif is a display face: never below 18 px, never bold, never for UI labels. On the image canvas a title uses --canvas-text and its count --canvas-dim (the grid header).

All three are OFL and self-hosted through Fontsource (no CDN). Inter's italic is loaded as its own file (wght-italic.css), and body sets font-synthesis: none, so the browser never fakes an italic or a bold: Instrument Serif exists only at 400, so never set it bold. Scale (six steps): 11 / 13 / 15 / 18 / 24 / 34 px (--fs-1 … --fs-6); 13 px is the body size. Counts and sizes use tabular figures.

  • Every font-size in the stylesheets is var(--fs-N) (or inherit). web/tests/type-scale.test.ts fails on any raw size; a genuine exception carries /* type-scale: allow (why) */ on the same line. The allowed ones today: 16 px phone fields (iOS Safari zooms into anything smaller), the 28 px default of a board text node (board content, the user's own scale) and the font-specimen glyphs (the item's own font).
  • h1–h6 are reset (no browser margins; 15 px / 600, h3–h6 13 px / 600), so a heading never picks up the browser's 1.5em/1.17em sizes.
  • .mono is 11 px.
  • Prose (paragraphs, hints, notes, descriptions, view subtitles): line-height 1.5, at most 64 characters a line (max-width: 64ch).
  • Small labels and section heads (.section-label, sidebar heads, palette groups, Appearance legends): 11 px / 600, uppercase, letter-spacing: .08em, font-feature-settings: 'case', --text-dim. Caps only for these labels, never inside content.
  • Sentence case for every UI string: "Triage unfiled", "In trash", "Go to all items". The copy carries the case; no text-transform: capitalize. A view's name used as a name stays as written ("Nothing in Unfiled").
  • Secondary text is a visible step dimmer: --text-dim / --canvas-dim is #DADADA in gallery (4.78:1 on the grey, against 6.13:1 for --text); dark and light already step from ~15–16:1 down to ~6:1.

Icons

Lucide (ISC), imported per icon. Icon-only buttons keep a visible target of at least 24 × 24 (28 × 28 for quiet controls) and an aria-label; icons themselves are aria-hidden.

  • Three sizes: 14 px (dense rows, chips, badges), 16 px (the default: toolbars, menus, sidebar), 20 px (stars, phone bars, empty states). A few glyphs drawn as illustrations (the preview's arrows, empty-state and missing-image glyphs) are larger and named in tests/icons.test.ts.
  • One stroke: 1.5 px on screen at every size. styles.css sets .lucide { stroke-width: 1.5 } with vector-effect: non-scaling-stroke, so components never pass strokeWidth (only strokeWidth={0} for a filled glyph such as a tile star).
  • One meaning per glyph:
Meaning Icon
AI (meaning search, suggestions, More like this) Sparkles (AI only)
Picks Flag (sidebar, palette, cull controls)
Rejects Ban
Boards Presentation
All items LayoutGrid
Unfiled Inbox
Triage ListChecks
Templates Stamp
Tag cleanup Eraser
Theme / appearance SunMoon (palette), Palette (Appearance button)
Add from URL Link2
New folder FolderPlus
An action with no icon of its own Zap (fallback only)
Stars (ratings) Star, filled when set

Motion

Token Value Used for
--dur-1 120 ms hover, press, captions
--dur-2 200 ms panels, sheets, drawer, thumbnails fading in
--dur-3 280 ms the grid tile growing into the preview
--dur-in 120 ms something appearing: menus, popovers, dialogs, toasts, the info panel
--dur-out 80 ms something leaving (faster than it came)
--dur-sheet 380 ms phone sheet and drawer (with --ease-sheet)

Easings: --ease cubic-bezier(.2, .8, .2, 1) for state changes, --ease-out cubic-bezier(.16, 1, .3, 1) for things appearing, and --ease-sheet cubic-bezier(.32, .72, 0, 1) (the iOS sheet curve) for the phone sheet and drawer only.

  • On a phone the item sheet slides up, the drawer slides in, its backdrop fades, and the Move to… / Tags bottom sheets rise with their scrim, all over --dur-sheet 380 ms on --ease-sheet (phone.css; the sheet's drag-release snaps back on the same curve). Desktop never uses these tokens (tests/motion.test.ts).

  • Menus, popovers, dialogs and the palette fade in and slide 4 px down (@keyframes float-in); toasts and notices rise 4 px (float-up). Keep it under 150 ms: no bounce, no scale-up.

  • The info panel slides in 8 px from the right (panel-in) and fades out over --dur-out before it unmounts (usePresence in src/motion.ts, whose DUR_IN_MS / DUR_OUT_MS match the CSS; a test checks).
  • Buttons give way on press: scale(.98).
  • Opening and closing the preview is a shared-element View Transition when the browser supports it.
  • Under prefers-reduced-motion: reduce every duration token drops to ~0, every animation and transition is cut, the press scale is off, the info panel closes at once and no view transition runs. (Kist has no in-app motion setting; the OS setting is the switch.)

Floating surfaces

Anything that floats over the page (menus, popovers, dialogs, the ⌘K palette, toasts, notices) uses one recipe, so it reads as one family:

  • surface --bg-float (dark #21211F, light #FFFFFF, gallery #454545: a clear step darker than the page, which the old --bg-raised #565656 wasn't), with --float-hover for hovered rows inside it;
  • a hairline --float-line border;
  • --float-shadow: an inner top highlight plus a far and a near shadow (--float-sheen, --float-shadow-far, --float-shadow-near);
  • --float-radius 10 px (menus, popovers, toasts) or --dialog-radius 12 px (dialogs, palette);
  • behind dialogs a lighter 40 % --scrim, so the images don't go muddy.

New floating things use the .float-surface class (styles.css), which also brings the float-in animation. The palette's footer shows its keys as keycaps (<kbd>).

Phone

The phone is its own layout (.app-shell.mobile, rules in phone.css), built to sit next to Photos on a home screen rather than look like the desktop shrunk down.

  • Top bar. Row one: a 44 px borderless menu button, the mark, and a 44 px pill search field sunk into the chrome (--phone-sunken, 22 px radius). No ⌘K button (a phone has no ⌘ key) and no Export button: Share and Export sit in the drawer head. Row two: every control (tile shape, − n +, Type, Filters, Rating, Sort) has one borderless fill (--phone-fill, 10 px radius); widths stay as fitSelect.ts PHONE_ROW measures them.
  • Large title. The view title is Instrument Serif 34 px (--fs-6) on the canvas, its count Inter 11 px tabular.
  • Item sheet. --bg-raised with the --chrome-line pinstripe on its top edge, 20 px top corners and a long soft shadow, so it lifts off the grid; a visible 36 × 5 grabber (--field-border); neutral chips; Move to… fills the action row and Trash is a 52 px icon button in --danger (its accessible name stays "Trash"). The tile that is open in the sheet shows the accent corners only, no multi-select check.
  • Drawer head. Mark and wordmark on the left, Share/Export and a 44 px borderless ✕ on the right, on --chrome with the pinstripe below.
  • Preview capsules. Everything over the full-screen image (Notes, close, the arrows, the stars, Tags / Move / Trash) floats in one glass surface: --preview-capsule at 72 % with backdrop-filter: blur(20px) saturate(1.4), a 16 % hairline and a soft shadow. Under prefers-reduced-transparency or prefers-contrast: more it is the solid --preview-capsule. Stars sit in their own 24 px-radius capsule above a 30 px-radius bar of 64 × 54 buttons; the arrows are 48 px circles on the bar's line. Stars there use --preview-star (light's dark grey accent is too dark on the capsule). Blur is kept to these few elements.
  • Board header. One 57 px row: a 44 px back button, the board name in Instrument Serif 24 px, "Saved" 11 px dim, and a 44 px ••• menu (PhoneBoardMenu.tsx) holding List, Export (PNG, PDF, HTML) and Share. The zoom (−, %, +, fit) floats in a capsule at the bottom centre on the --bg-float glass (solid under reduced transparency), with 48 × 44 buttons.
  • 44 px hit areas (A8). Small phone controls keep their look and get a transparent ::after that grows the tap target: −/+ and the other row-two controls to 44 px tall (−/+ share the count between them: about 36 × 44, the row has no more width), and in the item sheet the close button, View, the colour swatches, More like this, Edit and History to about 44 px tall (40–44 where two neighbours' areas meet; neither steals the other's tap). The list in phone.css uses :where() so each control's own inset wins.

Voice

  • Calm and concrete. Name the file, the folder, the count.
  • Verbs: keep, find, file, pick.
  • No exclamation marks.
  • Errors say what happened, what's safe, and what to do next.
  • The name. In Scots and Dutch "kist" can also mean a coffin. The main sense everywhere is a chest you keep treasures in, and nothing in the brand should pull the other way:
  • never use "kist" as a verb;
  • never write hoard, stash, bury, rest, laid, dead or deceased;
  • no tapered or hexagonal box shapes, no black lidded box;
  • pair the name with the descriptor where people meet it first: "Kist, a self-hosted visual library".