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.
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, manifestmonochrome),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 lightpreview-dimis #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 inpreview-dim, then "More like this" and "Open original" as underlined text actions. Both arrows look the same at rest (--textat 70 %); the one with nowhere to go is hidden. The phone keeps its own layout. - Browser and launch colours. The
theme-colormeta (the phone's status bar) is each theme'schrome(THEME_COLORintheme.ts), andpublic/theme-init.jspaints<html>in the theme'sbgbefore 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.tschecks 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-lineoutline in the theme's ink (3:1 against the page).
Accent budget¶
The accent (ink) means one of four things, and nothing else:
- selection on images: the tile corners and check (the theme's
--canvas-focus, white on dark and gallery, dark grey on light); - the focus ring;
- ratings (stars);
- 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-h28 px tall with--ctl-radius6 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 (
--chevronin themes.css, the theme's dim text colour),appearance: none, still real<select>s. - One
.btn-primaryper view (Upload, Save, New token).button.dangeris a quiet button with--dangertext. - 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 Kas a keycap inside it that opens the palette), a spacer, Paste and Upload (the only primary control), a--chrome-linehairline (.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-titlewith a.title-eyebrowon 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 mobilein 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--chromewith a--chrome-linerule 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
--chromethat 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-linehairline, and on the right zoom, List, background, Export and Share. The active tool is the pressed fill plus the thin--selected-lineoutline. 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'saria-label. -
Stacks: a closed stack's entry (
.tile.stacked) has a second sheet 4 px up and right behind it (--tile-waitfill,--field-borderedge, 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/sidebarCountin query.ts). A search or filter shows just its number of results. -
Empty states (
EmptyStatein GridExtras.tsx): the outline mark (OutlineMark, Brand.tsx: brackets as thin--canvas-dimlines, the kept item a solid--accentsquare;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 inemptyState, query.ts); the view's subtitle hides while the grid is empty so nothing is said twice.
Sidebar¶
- Labels get their own section head under Cull: 12 px colour dots
with a 1 px
--field-borderring (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--textring. 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-softwith a 1 px--selected-lineedge). 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-sizein the stylesheets isvar(--fs-N)(orinherit).web/tests/type-scale.test.tsfails 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–h6are 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..monois 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-dimis #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 }withvector-effect: non-scaling-stroke, so components never passstrokeWidth(onlystrokeWidth={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-sheet380 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-outbefore it unmounts (usePresenceinsrc/motion.ts, whoseDUR_IN_MS/DUR_OUT_MSmatch 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: reduceevery 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-hoverfor hovered rows inside it; - a hairline
--float-lineborder; --float-shadow: an inner top highlight plus a far and a near shadow (--float-sheen,--float-shadow-far,--float-shadow-near);--float-radius10 px (menus, popovers, toasts) or--dialog-radius12 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 asfitSelect.ts PHONE_ROWmeasures 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-raisedwith the--chrome-linepinstripe 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
--chromewith 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-capsuleat 72 % withbackdrop-filter: blur(20px) saturate(1.4), a 16 % hairline and a soft shadow. Underprefers-reduced-transparencyorprefers-contrast: moreit 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-floatglass (solid under reduced transparency), with 48 × 44 buttons. - 44 px hit areas (A8). Small phone controls keep their look and get a
transparent
::afterthat 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".