One system, three surfaces.

Tokens flow downhill

Colors, dimensions, type, and motion live in a single source module. A zero-dependency generator expands the nine brand anchors into tonal ramps, verifies every semantic pairing against a WCAG contrast contract, and emits the file each surface consumes. Nothing downstream is hand-edited.

What changed

The decisions this page reflects, newest first. Each one was made and shipped in the app first; this is where the design record catches up.

Logo & lockups

The mark is a ristra — four chilies strung together, one per household member pulling the same list. It hangs on one of two brand fields: sand in light contexts, earth in dark ones. Variant names describe the ink, not the background: use the light-ink files on earth, the dark-ink files on sand.

Full-color lockups

logo-color-dark.svg — on sand / light surfaces

logo-color-light.svg — on earth / dark surfaces

Launch lockup: mark and wordmark, no tagline

Approved 2026-09-14 for the launch screen and the web loading screen (see Launch & loading). Derived from the full-color lockups: tagline paths removed, the wordmark moved down to centre on the mark, the viewBox cropped with equal padding. Same ink naming. These two files are the canonical source; the app keeps verbatim copies.

ristra-lockup-color-dark.svg — on --bg, light

ristra-lockup-color-light.svg — on --bg, dark

Monochrome lockups

For single-color contexts: embossing, watermarks, partner co-branding, or anywhere the full palette would fight the surrounding design.

logo-dark.svg — earth ink on light

logo-light.svg — sand ink on dark

logo-bright.svg — sweet ink, high-energy moments

Icon tiles & bare mark

icon-light.svg — light-mode tile

icon-dark.svg — dark-mode tile

mark-full.svg — transparent, either field

Wordmark & tagline

Two display faces, two jobs, and they never trade. Solitreo sets the wordmark — and only the wordmark. Jua sets the tagline and short display moments on marketing surfaces. Neither ever sets body copy; body and UI text are always the native system stack.

wordmark.svg — Solitreo, outlined, turquoise-500

tagline.svg — Jua, outlined, sand

Live specimens

--font-display: 'Solitreo' · --font-tagline: 'Jua' · webfonts are Latin-subset woff2 (~16–22 KB)

Clearspace & minimum sizes

Give the ristra room to hang. Keep a clearspace of one chili-height (¼ of the mark's height) on all sides of any lockup, and never let other elements cross it.

Don'ts

• Don't recolor the chilies outside the four brand body colors.
• Don't set the wordmark in any face but Solitreo, or the tagline in any face but Jua.
• Don't place the dark-ink lockups on earth, or light-ink lockups on sand.
• Don't rotate, outline, shadow, or add effects to any lockup.
• Don't use the app-icon glass palette in UI or marketing surfaces.

Launch & loading

The first thing anyone sees. The launch screen shows the launch lockup 240 pt wide, centred on --bg in both appearances. The web loading screen draws the same lockup at the same size and position, so the hand-off from the native launch to the app doesn't move.

Light · earth-50

Dark · earth-975

To scale: a 402 pt screen with the 240 pt lockup · iOS: storyboard + named color + appearance-variant image set · web: Splash.svelte

• It follows the phone's appearance, not the in-app theme. A launch screen can't read the app's setting, and the only override would force the keyboard and system sheets into one mode too.
• The loading screen paints in its first frame: it inlines the SVG rather than loading an image. If loading runs past three seconds, "Loading your list…" fades in 24 px below the lockup in --text-muted.
• iOS gets PNGs at @2x and @3x, generated from these SVGs and tokens.css; an SVG in a launch image view has black-screen reports. Never set a splash background color in the shell's config: it paints one color over dark mode.

Color

Nine brand anchors — the four chili bodies, the stem, the two fields, and the two wordmark turquoises — expand into seven tonal ramps. Anchors are brand and illustration colors; interface color always comes from the semantic tokens, which are locked to contrast-safe ramp steps by a generator-enforced WCAG contract.

Brand anchors

Values are verbatim from the Figma brand file and the SVG assets. Anchors flagged brand only fail AA as text on their field — use their ramp's deeper steps in UI instead. Click any swatch to copy its hex.

Tonal ramps

Twelve steps per ramp, 50→975, built on an OKLCH lightness ladder. The dot marks the step where the brand anchor survives verbatim. The earth ramp doubles as the warm-neutral ladder: sand sits at 100, earth at 950, and every surface, border, and text tone between them is brand-derived. The 975 near-black exists for dark-mode backgrounds — in dark themes, cards sit at earth-950 (the brand field) on an earth-975 page.

Semantic tokens

The interface vocabulary. Names match the app's custom properties exactly, so a value change here is a value change there. Status colors are text colors (item names), so they carry the 4.5:1 text contract; the swipe colors are the same in both themes. Live values follow the page theme — flip the toggle up top and watch them re-resolve.

Materials (app-level)

The app layers these over the tokens in its app.css. None of them carries text: every color text or glyphs are drawn in is a semantic token above.

Contrast, proven live

Every pair in the contrast contract, read from the generated token file: each swatch draws its actual token pair and computes the WCAG ratio in your browser. The generator enforces the same minimums at build time — a failing pair can't ship. Pairs held to 3:1 are large text or glyphs, so their sample is set large. The app's test suite then checks, with axe-core, that every screen uses these pairs as intended.

Light theme

Dark theme

Typography

Body and UI text is always the platform's native stack: SF on Apple platforms, Roboto on Android. Zero font payload in product surfaces; the two brand faces appear only where the brand rules allow.

Token scale

The general-purpose ladder: settings screens, forms, this page, and the marketing site.

Interface text styles

The native-iOS layout (2026-09-14) sets its text at the iOS text-style sizes: Large Title 34, Body 17, Footnote 13. They apply on every platform, as literals in the components named.

Spacing & layout

A twelve-step scale for general spacing, plus the layout metrics of the native-iOS layout the app adopted on 2026-09-14. Those were measured against the retired native app and are pinned at 402 pt (iPhone 17 Pro) by the app's metrics suite, within 0.5 px.

Layout metrics

Widths: the floating bar caps at 640 px and centres, so on a desktop window the cart and the + stay near the list; sign-in and join forms cap at 440 px. The app respects device safe areas through the --safe-* insets.

Radius & elevation

Soft, and flat by default. Inset-grouped cards take the iOS 26 corner (26 px) with no border and no shadow: the --surface fill alone separates them from the --bg page. Shadow is for things that float or lift.

Motion

Quick and settled — rows glide, sheets rise, nothing wobbles. Three durations, two curves. Click a chip to play its timing.

• Reduced motion: every movement above has an instant or still fallback. The Tour's swipe step holds one still frame with both swipes open.
• Reduced transparency: glass and the bar material flatten to solid --surface / --bg, and Home's texture layers hide.
• The rubber band is scroll physics, not animation. The iOS shell keeps the native bounce, which shows --bg past the edge; it locks while any sheet or dialog is open.

Iconography

One family, two weights, every surface. Ristra draws Font Awesome Sharp from its licensed kit: Sharp Regular for interface chrome, Sharp Solid for aisle and list-type glyphs. Weight is the only thing separating the two roles. The app bundles its glyphs so they render offline; this page and getristra.com load a generated sprite of exactly the same glyphs, so all three always agree.

Interface chrome · Sharp Regular (fasr)

Sizes: 16–20 in nav controls, 18 on floating buttons, 13 in aisle headers and the lens row, 14 in quick-acts, 22 in What's New tiles. Chrome glyphs take --accent inside glass controls; the back chevron reads as text.

List-type icons · Sharp Solid (fass)

A list's type picks its default icon; people can choose any of these from the picker. The household document stores only the key.

Departments

Twenty-six aisles with stable keys: fourteen in the default grocery walk, eleven specialty aisles that appear only through a store's department set (hardware, garden, and the like), and Other. Each gets a Sharp Solid glyph, rendered muted in its aisle header; departments never get their own accent colors.

Buttons

Shape follows placement. Form actions on a page or sheet are rectangles; the button that closes a dialog spans it; anything in a bar or floating over the list is a circle or a capsule. Accent is the default action color. Teal is reserved for finishing a trip.

Form and dialog buttons

Form: app.css .btn (--accent, 9px, 16/600) and .btn-ghost (--accent-strong label, --border hairline) · Dialog: 14px, 16/700, full width; the paired ghost sits on --surface-sunken (Tour.svelte, WhatsNew.svelte)

Bar and floating controls

Glass circle 44 · capsule 103 (two 44 buttons) · floating 48: glass cart (--accent-strong), glass camera (--status-incart), prominent + (--accent) · Finish capsule (--finish-*) · Join (Home) · app.css .glass / .fab, BottomBar.svelte

Text actions

Change (lens row): --accent-strong 13/700 · End (trip band): --text-muted 12/700, underlined, a 45 x 34 hit area · Skip (Tour): --text-muted 15/600, 44 px hit area

• Teal means finish. --finish-bg is used by the Finish capsule, the in-list Finish shopping button, and the Complete count, and nowhere else. It passes AA in both themes (4.59:1 light, 8.1:1 dark).
• The Finish capsule's name is exactly its label. It has no aria-label, so assistive tech hears "Finish", the word on screen.
• Focus rings are a 2 px --title outline, offset 2 px (drawn inward inside clipped cards).
• Destructive text and buttons (delete a list, delete an account) use --danger: chili-700 in light, chili-400 in dark, with --on-danger for a label on the fill. It replaced a hard-coded red that measured 2.34:1 in dark.

Inputs & forms

Quiet fields on surface with hairline borders; focus is a turquoise ring and the border steps aside. 16px minimum font size, always. Quick add is the one pill-shaped field: it's a composer, not a form.

Field: --surface, 1px --border, 9px, 12/14 padding · focus: 2px --title outline, transparent border · composer: pill on --surface-sunken + 46px --accent go (QuickAdd.svelte) · stepper 40 x 40, radius 10 · checkbox accent-color --accent

Pills & badges

Counts and quantities ride the sand pill in mono. Status pills sit in the nav bar. The one teal badge counts what's in the cart.

Quantity + aisle count: mono 12/16, --text-muted on --pill-bg · bought quantity: --finish-* · Complete count: --finish-* · offline: 11/700 caps --status-unavailable · saving: --text-faint on --surface-sunken · staple chip: dashed --accent (QuickAdd) · toast: BottomBar flash

Toggles

Choices of three are equal chips with the pick filled in accent — the theme picker in app settings is the canonical instance. On/off settings are full-width rows with a dot that fills. Try both.

Chips: 1px --border, 9px, 15/600 --text-muted · selected: --accent fill, --on-accent label · toggle row: --accent border and dot when on · AppSettings.svelte .theme-chips / .toggle

Navigation bar

The retired native app's shape, on every platform: glass controls either side, a 34 px large title that scrolls away with the page, and a 17 px bar title that fades in once the large one is under the bar. The bar is transparent at rest; its material appears only when content passes beneath it.

• Leading: a glass circle back button whose chevron reads as text (--text). Its accessible name is the screen it returns to: "Lists" from a list, the list's name from Staples.
• Trailing: one glass capsule of two 44 px buttons. The list carries Share and More (Past trips, Staples, Settings); Home carries My Stores and Settings. Offline and saving pills sit just before the capsule (see Trip & status).
• During any live trip the list's title moves into the bar and the trip band pins beneath it, so neither scrolls away (see App shell).
• Exactly one heading level 1 at a time: the large title, or the bar title when it's inline.

NavBar.svelte · sticky, z-index 30 · material: --bar-material, blur 20, saturate 180% · bar title fades in over 150ms

List item row

The flagship component — the row a household touches a hundred times a week. No checkbox: the name leads, a tap opens the editor, and swipes do the rest. A single-line row is 52 px, with an inset hairline between rows.

• Anatomy: name 17/22 medium; quantity pill when above 1; a coupon glyph in --accent-strong; one line of note (or the photo read) that ellipsizes rather than growing the row; a 48 px photo thumbnail at the trailing edge, radius 8.
• Press: the row goes --surface-sunken while a finger is down. A tap opens the edit sheet.
• Long press under a store lens lifts the row to drag within its aisle (see Aisle cards).

ItemRow.svelte inside SwipeRow.svelte · padding --row-pad-y / --row-pad-x · separator: 1px --separator, inset --row-pad-x both sides, hidden on the last row and whenever the row is displaced

Swipe actions

Completion is a leading full swipe; skipping is a trailing full swipe at the screen edge; Delete sits inboard and is tap-only. A destructive action never rides a flick.

• Feel: the row captures after 10 px of travel; a full swipe commits past 55% of the row's width or on a fast fling; open states snap to 84 px per action. The left 24 px are a dead zone, left to the system's back gesture. One row is open at a time, and a tap anywhere else closes it.
• Compact rows: under 64 px tall there's no room for circle and label, so the action goes icon-only on a 30 px circle, the way Mail does.
• Never gesture-only: on a mouse or keyboard, hovering or focusing a row reveals the same actions as 28 px buttons.
• The write lands after the exit animation, so the row finishes leaving before the list re-sorts.

SwipeRow.svelte (zones, thresholds) · ItemRow.svelte (actions per status, quick-acts) · zone colors: --swipe-got-bg turquoise-600, --swipe-skip-bg ochre-600, --swipe-delete-bg terra-600, all the same in both themes; white labels clear 4.5:1 on each

Aisle cards

Items group into borderless inset-grouped cards, one per aisle, in the walking order of the chosen store. Each header sits on the page above its card and scrolls with it. Headers are wayfinding, not content: they stay quiet.

• The lens row names the order: "Aisles ordered for {store}" or "Default aisle order", with Change opening the store sheet. The choice is per person and per device. During your own trip it locks to a faint label, so the order can't shift mid-shop.
• Header: Sharp Solid glyph at 13 px, the label in sentence case (13/18 bold), a count pill, and, only under a store lens, a grip. Drag the grip to reorder aisles for that store.
• Rows reorder too: under a store lens, long-press a row and drag it within its aisle. The order is saved per store by item name, so it survives items being cleared and re-added every trip.
• Order down the page: aisles, then Skipped (after the last aisle, so aisle counts show only what's left to get), then Complete, then Finish shopping.
• Skipped wears the skipped color on its glyph and count. Complete collapses, fills with --trip-wash, and tints its hairlines teal.

DepartmentSection.svelte (variant aisle · skipped · complete) · ListView.svelte (lens row, drags, Finish shopping) · card: --surface, --group-radius, no border, no shadow · header padding 26 / 10

Home

Your lists in one inset-grouped card, a shortcuts dashboard under it, and two floating buttons: + for a new list, Join for a shared one. Home is the one screen with texture.

• List rows are 76 px: a 42 px icon tile (radius 12, the list's Sharp Solid glyph in --accent on --surface-sunken), the name at 17/22 semibold, members at 13/18 muted, a faint chevron. The hairline starts at the text, not the tile.
• Shortcuts are two-column tiles in the Reminders shape: a round glyph top left, the count large top right, the title under them. Tapping Staples asks which list first when you have more than one.
• Texture is decoration only. Paper grain at 35% in light only (on the dark field it lifted the page to #1e1916, too close to the cards, so dark Home paints --bg flat), and the brand mark oversized at 5% in both themes. Both are click-through, and both hide under reduced transparency.

ListsScreen.svelte · InstallBanner.svelte and UpdateNudge.svelte appear above the lists when relevant (see Trip & status)

Sheets & dialogs

Choices rise from the bottom as sheets. Moments that need a pause — the Tour, What's New — are centred cards. Both dim the page, trap focus while open, and close on Escape.

• Every overlay marks itself (data-modal) so the iOS page bounce locks while it's open.
• Dialogs own the Tab key while open: focus moves to the title on open, stays inside, and returns to whatever opened it.
• The Tour is the same centred card as a seven-step carousel: add, photo, staples, store lens and aisle drag, swipes, Finish, share. Each step has art on a 376 x 150 slot (--surface-sunken, radius 16) drawn in tokens with the real glyphs, dots in --border with the current one in --accent, Skip top right, and "Let's go" on the last step. It shows once per device.
• What's New shows once per device per version, after an update, never on a first run (the Tour shows then). Settings > Help reopens it.
• Confirming a finish uses the system alert, not a custom dialog.

Menus

HeaderMenu.svelte (More, in the list's capsule) · --surface, 1px --border, radius 12, --shadow · items 15/600 with --accent glyphs · StoreChoiceSheet.svelte · WhatsNew.svelte · Tour.svelte

Trip & status

A live trip is the list's loudest state and it's still quiet: a sage band pinned under the nav bar with a pulsing dot. Connection state is a small pill beside the nav controls, never a banner.

• The band is 34 px: 13/18 bold --trip-text on --trip-wash, a --trip-border hairline drawn as an inset shadow so it adds no height, and a 7 px --trip-dot pulsing every 2 s.
• End vs Finish. End (your trip only) cancels and leaves every item as it is. Finish, on the capsule or under Complete, saves the trip and clears what you got.
• Offline reads the device's connection, not the sync layer's cache flag, which reads "not confirmed" far too often to mean offline. Saving… appears while local edits wait to sync.
• The freshness line under the large title says who changed the list last and when: the trust signal of a shared list.
• Home cards (install on the web, update in the app) are --surface tiles at radius 14 with no border.

ListView.svelte .trip-band · FreshnessBadge.svelte · InstallBanner.svelte · UpdateNudge.svelte

App shell

One layout on every platform since 2026-09-14: the retired native iOS app's. The page is --bg; a large-title nav bar sits over it; aisles are inset-grouped cards at the layout margin; three floating buttons hover at the bottom with no dock behind them. The document itself is the scroller.

Platform dialects

The root element carries data-platform (web, ios, and later android), set before first paint. Only iOS has a dialect today.

Marketing hero

Marketing surfaces lead with chili. getristra.com is built on Bold & Strung, a Graft kit (~/Sites/Graft/kits/bold-and-strung) that takes these ramps exactly as this repo emits them and casts them into three color fields, with heavy system type, cards set down by hand and one marker per headline. The hero at the top of this page is an older, darker cousin.

Tokens & downloads

Everything on this page's color sections is generated from one source module. Regenerate with node scripts/gen-tokens.mjs — the contrast contract runs on every build and refuses to emit failing tokens.

Ristra · a Longbrook Studio project · getristra.com · app.getristra.com