Files
llama.cpp/ui/apps/chat/DESIGN.md
T
Aleksander Grygier 7f106b5459 ui: Llama UI design system: tokens, surfaces and fonts (#32468)
* ui: bring @ggml-org/llama-ui into ui/lib/ui

The design system package (tokens, fonts, surfaces, components and Model UI), so far in the temporary ggml-org/llama-ui
repository at edaf518, moves to its home in ui/lib/ui, built with @sveltejs/package and published as @ggml-org/llama-ui
from here. ui/lib holds the packages, one folder each. Its references to tools/ui now name ui/apps/chat, its
package.json points at this repository, and the UI workflow type-checks and packs it. ui/README.md describes the
layout.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: Llama UI design system: tokens, surfaces and brand

The design system from allozaur/docs/storybook-overhaul: three tiers of
tokens, matte glass surfaces, Llama Sans and Llama Mono, and the base
components on the new tokens (Tabs and GlassKey among them). It also
restyles the stack's features with it, replacing the plain stand-ins they
used until now. DESIGN.md is generated from the tokens. The Storybook that
documents it is the next PR.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: have Llama Chat use @ggml-org/llama-ui for its base components, tokens and fonts

Llama Chat kept its own copy of the design system: 29 base components, the
three tiers of tokens, the surfaces, the theme and the fonts, next to the 12
components ui/lib/ui held. The copy goes, and the library gets what it lacked.

ui/lib/ui
- the 17 base components the app had and the library did not (alert,
  alert-dialog, button-group, checkbox, collapsible, context-menu, dialog,
  drawer, dropdown-menu, empty, hover-card, radio-group, scroll-area,
  skeleton, table, tabs, textarea), with vaul-svelte for the drawer
- the inset-group and selected-row tokens and surfaces
- sources import each other by relative path instead of $lib, which in an
  app points at the app's own src/lib
- theme.css no longer imports tw-animate-css: it is a peer dependency that
  the consumer imports before the theme, as it does Tailwind
- 0.3.0

ui/apps/chat
- imports the base components as @ggml-org/llama-ui/ui/<name> and cn/tv as
  @ggml-org/llama-ui/utils; app.css imports the library's theme.css
- compiles the library from source, with no install or build of it:
  scripts/vite-plugin-llama-ui.ts resolves its entry points and what it
  imports, and svelte.config.js gives TypeScript the same paths
- src/lib/components/ui, styles/tokens, styles/surfaces.css and assets/fonts
  are removed; components.json moves to the library

Builds
- CMake stages ui/lib/ui next to the app, keeping the layout of ui/, and
  rebuilds when a library source changes
- the Dockerfiles copy the library's sources; the Nix derivation takes ui/
  as its source

The built CSS has the same rules in the same order, apart from one
zero-specificity rule and the @font-face rules moving, plus ten utilities
and two tokens that only the library's own components use.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: AGENTS.md places Llama UI in ui/lib/ui

Llama Chat's AGENTS.md says where each part lives: Llama UI is
ui/lib/ui, and Chat imports its tokens, fonts and base components
from there.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: Llama Sans and Llama Mono from llama-brand's latest, and shell commands marked in bash code

The fonts in ui/lib/ui come from llama-brand's latest, with optical sizes
from 10 to 36. Bash code blocks mark shell commands and flags.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: open submenus outside the menu they come from

A submenu was rendered inside its parent menu, so the menu's scroll box
clipped it: the glass menus' backdrop filter, and the filter and transform
of the open animation, make the menu the containing block even for the
fixed-position submenu. Dropdown and context submenus now render in a
portal, like the menus themselves.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: draw submenus like the menu they open from

Submenus had smaller corners than their menus, and context menus had none
of the dropdown's glass. Context-menu parts now match the dropdown's, and
both submenus take the menu's corners and height cap, with their first row
level with the row that opens them, 4px past the menu's edge. Sub-triggers
take the items' radius and pointer.

The submenus' height cap and zoom origin named the dropdown's CSS variables,
which bits-ui does not set on submenus; they now use its --bits-menu-* ones.
The chat group submenu takes the actions menu's z-[999999] layer, as it no
longer renders inside that menu.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep a late current-node write off a closed or switched conversation

updateCurrentNode checked the active conversation, awaited the database write, then wrote currNode to whatever was active after it. When the conversation closed during the write it threw, and the reply ended in a streaming error dialog. When another conversation opened, that one got the wrong node.

Assisted-by: Claude (Fable 5.2)

* ui: have Llama Chat use the library's Model UI and app components

Llama Chat still kept its own copies of what the library holds above the
base components. It now takes them from @ggml-org/llama-ui too, and its
copies go.

ui/lib/ui
- ModelId gains what Chat's had: the model's own draft kind, draft
  sidecars with their quant (ModelDraftSidecars, new), aliases, hideName
  and a tooltip, in the same badge order
- entry points for them, like ui/<name>: @ggml-org/llama-ui/app/<group>
  (actions, content, forms, misc) and @ggml-org/llama-ui/models

ui/apps/chat
- ActionIcon, SearchInput, SyntaxHighlightedCode, Logo,
  ModelCapabilityIcons, ModelDownloadProgressBar and ModelDraftSidecars
  come from the library; Chat's copies and the two constants only they
  used are removed
- ModelId and ModelOrgAvatar stay as thin wrappers: ModelId parses the raw
  id and applies the user's display settings, ModelOrgAvatar hides the
  avatar while Hub metadata is off
- the svelte/* TypeScript path falls back to Svelte's types/index.d.ts:
  svelte/reactivity has no file of its own, so a library source importing
  it got its types from ui/lib/ui's own install when there was one

Assisted-by: Claude (Opus 5.5 Medium)

* ui: Llama UI takes the brand's colours and logo from llama-brand

@ggml-org/llama-brand is now a dependency of the library, by the same GitHub
tarball Llama Chat already installs, which now names it @ggml-org/llama-brand
too.

- primitives.css drops the 25 tokens it held copies of (the neutral
  greys, sand, the skies and cinder) and builds on llama-brand's
  css/colors.css instead; the skies' gradients point at llama-brand's.
  Apps import that file before theme.css, as they do Tailwind and
  tw-animate-css: the library's stylesheets import no package, so an app
  that compiles them from source resolves it from its own node_modules
- Logo draws llama-brand's icon, in currentColor, and assets/logo.svg goes
- Llama Chat's TypeScript paths resolve llama-brand from its own
  node_modules, like the library's other dependencies

The fonts stay as the library's WOFF2 copies until llama-brand ships
WOFF2 builds of them.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: have Llama Chat take the library's constants, enums and helpers

Llama Chat redefined most of what the library exports next to its
components. Where the two were the same, Chat now re-exports the library's
from the files that held them, so its own imports stay as they are.

- the library gets entry points for them: @ggml-org/llama-ui/constants,
  @ggml-org/llama-ui/enums and @ggml-org/llama-ui/code, and
  @ggml-org/llama-ui/models carries the model data with the Model UI
- from the library now: the shared CSS classes and code-block constants,
  the byte units, the memory-fit constants and minMemoryTierGb, the bit
  depth labels, the capability and modality icons, labels and order,
  ColorMode, TooltipSide, BooleanString, the model enums, ModelModalities,
  formatParameters, highlightCode and trimCodePadding
- the library's modality order follows Chat's: vision, video, audio
- Chat keeps its own where they differ: UI_DATA_ATTRS and
  ModelDownloadProgress are supersets of the library's (the latter extends
  it now), and formatFileSize counts in 1024s

Assisted-by: Claude (Opus 5.5 Medium)

* ui: give the chat form's add key and model selector a tighter shadow

In light, the two keys inside the chat form, white on its white glass, took
the control elevation, whose soft spread blended into the form. They take a
new elevation-key instead: a 0.5px hairline all round and a 1px drop. In
dark they keep the control elevation. Chosen from the options in
Scrapbook › UI › Composer keys.

- semantic tokens: --elevation-key (light: the hairline and the drop; dark:
  the control elevation)
- component token: --chat-form-key-shadow, for the add key and every model
  selector trigger
- DESIGN.md names it next to the other elevations

Assisted-by: Claude (Opus 5.5 Medium)
2026-11-17 14:39:03 +01:00

56 KiB

version, name, description, colors, typography, rounded, spacing, components
version name description colors typography rounded spacing components
alpha Llama UI - Matte Glass Llama UI, the design system and components of Llama Chat, the chat client llama-server bundles. Neutral and quiet: frosted matte surfaces with faint blue-grey hairlines, near-flat fills, and status colours for success, warning, error and info. Tokens come in three tiers: primitives, semantic tokens (with a "-dark" twin where dark mode differs) and components. Generated from ui/lib/ui/src/lib/styles/tokens/*.css.
primary neutral-0 neutral-25 neutral-50 neutral-100 neutral-150 neutral-200 neutral-300 neutral-400 neutral-500 neutral-750 neutral-800 neutral-900 neutral-925 neutral-950 cool-gray-50 cool-gray-100 cool-gray-200 cool-gray-300 cool-gray-400 art-day-sky art-night-sky art-cinder art-cinder-light sand-50 sand-100 sand-200 sand-400 sand-900 red-400 red-500 red-450 red-550 red-600 red-800 yellow-300 yellow-400 yellow-800 green-400 green-450 green-500 green-550 green-650 green-800 amber-250 amber-400 amber-650 blue-400 blue-450 blue-500 blue-550 blue-650 blue-800 white-a2 white-a4 white-a6 white-a9 white-a12 white-a18 white-a20 white-a30 white-a50 black-a6 black-a30 black-a40 surface-page surface-muted surface-emphasis surface-selected surface-raised surface-lifted surface-pressed surface-glass surface-code surface-overlay fg-default fg-muted fg-on-action fg-on-danger fg-code fg-danger fg-success fg-warning fg-info line-default line-field line-control line-focus line-danger fill-success fill-warning fill-danger fill-info surface-success surface-warning surface-danger surface-info line-success-soft line-warning-soft line-danger-soft line-info-soft edge-rest-side edge-rest-mid edge-focus-side edge-focus-mid edge-ambient-side edge-ambient-mid edge-faint edge-raised action-primary action-primary-hover action-danger action-danger-hover action-quiet action-quiet-hover action-ghost-hover field-background field-shade status-danger status-danger-rim status-danger-glyph status-warning status-warning-rim status-warning-glyph status-success status-success-rim status-success-glyph status-info status-info-rim status-info-glyph highlight-inner highlight-inverse sheen-start sheen-end surface-page-dark surface-muted-dark surface-emphasis-dark surface-selected-dark surface-raised-dark surface-lifted-dark surface-pressed-dark surface-glass-dark surface-code-dark fg-default-dark fg-muted-dark fg-on-action-dark fg-code-dark fg-danger-dark fg-success-dark fg-warning-dark fg-info-dark line-default-dark line-field-dark line-control-dark line-focus-dark line-danger-dark fill-success-dark fill-warning-dark fill-danger-dark fill-info-dark surface-success-dark surface-warning-dark surface-danger-dark surface-info-dark line-success-soft-dark line-warning-soft-dark line-danger-soft-dark line-info-soft-dark edge-rest-side-dark edge-rest-mid-dark edge-focus-side-dark edge-focus-mid-dark edge-ambient-side-dark edge-ambient-mid-dark edge-faint-dark edge-raised-dark action-primary-dark action-primary-hover-dark action-danger-dark action-danger-hover-dark action-quiet-dark action-quiet-hover-dark action-ghost-hover-dark field-background-dark field-shade-dark highlight-inner-dark sheen-start-dark
{colors.action-primary} oklch(1 0 0) oklch(0.988 0 0) oklch(0.985 0 0) oklch(0.97 0 0) oklch(0.95 0 0) oklch(0.922 0 0) oklch(0.87 0 0) oklch(0.708 0 0) oklch(0.556 0 0) oklch(0.29 0 0) oklch(0.269 0 0) oklch(0.205 0 0) oklch(0.16 0 0) oklch(0.145 0 0) oklch(0.958 0.002 250) oklch(0.938 0.004 250) oklch(0.91 0.005 250) oklch(0.86 0.007 250) oklch(0.81 0.01 250) oklch(0.78 0.075 245) oklch(0.33 0.07 256) oklch(0.68 0.18 46) oklch(0.85 0.065 46) oklch(0.965 0.01 80) oklch(0.936 0.015 81) oklch(0.89 0.02 80) oklch(0.72 0.025 76) oklch(0.272 0.013 72) oklch(0.69 0.2 27) oklch(0.6 0.235 27) oklch(0.635 0.229 28) oklch(0.588 0.236 28) oklch(0.55 0.22 27) oklch(0.43 0.17 27) oklch(0.9 0.14 84) oklch(0.85 0.17 84) oklch(0.5 0.1 84) oklch(0.81 0.16 148) oklch(0.756 0.197 147) oklch(0.73 0.2 148) oklch(0.669 0.197 147) oklch(0.52 0.17 147) oklch(0.45 0.14 148) oklch(0.842 0.165 84) oklch(0.752 0.157 78) oklch(0.547 0.116 74) oklch(0.7 0.163 255) oklch(0.67 0.173 256) oklch(0.62 0.15 255) oklch(0.587 0.177 256) oklch(0.535 0.177 256) oklch(0.42 0.11 255) oklch(1 0 0 / 0.02) oklch(1 0 0 / 0.04) oklch(1 0 0 / 0.06) oklch(1 0 0 / 0.09) oklch(1 0 0 / 0.12) oklch(1 0 0 / 0.18) oklch(1 0 0 / 0.2) oklch(1 0 0 / 0.3) oklch(1 0 0 / 0.5) oklch(0 0 0 / 0.06) oklch(0 0 0 / 0.3) oklch(0 0 0 / 0.4) {colors.neutral-0} {colors.neutral-100} {colors.neutral-150} {colors.neutral-150} {colors.neutral-0} {colors.neutral-0} {colors.neutral-0} oklch(0.97 0 0 / 0.6) {colors.neutral-50} {colors.black-a40} {colors.neutral-950} {colors.neutral-500} {colors.neutral-50} {colors.neutral-0} {colors.neutral-950} {colors.red-600} {colors.green-650} {colors.amber-650} {colors.blue-650} {colors.neutral-300} {colors.neutral-200} {colors.neutral-300} {colors.neutral-400} {colors.fill-danger} {colors.green-550} {colors.amber-400} {colors.red-550} {colors.blue-550} color-mix(in oklab, {colors.fill-success} 11%, {colors.surface-page}) color-mix(in oklab, {colors.fill-warning} 11%, {colors.surface-page}) color-mix(in oklab, {colors.fill-danger} 11%, {colors.surface-page}) color-mix(in oklab, {colors.fill-info} 11%, {colors.surface-page}) color-mix(in oklab, {colors.fill-success} 34%, {colors.line-default}) color-mix(in oklab, {colors.fill-warning} 34%, {colors.line-default}) color-mix(in oklab, {colors.fill-danger} 34%, {colors.line-default}) color-mix(in oklab, {colors.fill-info} 34%, {colors.line-default}) {colors.cool-gray-200} {colors.cool-gray-100} {colors.cool-gray-400} {colors.cool-gray-300} {colors.cool-gray-100} {colors.cool-gray-50} {colors.cool-gray-100} {colors.cool-gray-200} {colors.neutral-900} oklch(0.205 0 0 / 0.9) {colors.fill-danger} color-mix(in oklch, {colors.fill-danger} 90%, transparent) oklch(0.97 0 0 / 0.3) {colors.neutral-100} oklch(0.556 0 0 / 0.1) oklch(1 0 0) {colors.black-a6} {colors.fill-danger} {colors.red-400} {colors.red-800} {colors.fill-warning} {colors.yellow-300} {colors.yellow-800} {colors.fill-success} {colors.green-400} {colors.green-800} {colors.fill-info} {colors.blue-400} {colors.blue-800} {colors.white-a50} {colors.white-a12} {colors.white-a20} transparent {colors.neutral-925} {colors.neutral-800} {colors.neutral-750} {colors.neutral-800} {colors.neutral-900} oklch(0.371 0 0 / 0.8) oklch(0.985 0 0 / 0.14) oklch(0.269 0 0 / 0.75) {colors.neutral-900} {colors.neutral-50} {colors.neutral-400} {colors.neutral-900} {colors.neutral-300} {colors.red-450} {colors.green-450} {colors.amber-250} {colors.blue-400} {colors.white-a30} {colors.white-a30} {colors.white-a12} {colors.neutral-500} {colors.fill-danger-dark} {colors.green-450} {colors.amber-250} {colors.red-450} {colors.blue-450} color-mix(in oklab, {colors.fill-success-dark} 16%, {colors.surface-page-dark}) color-mix(in oklab, {colors.fill-warning-dark} 16%, {colors.surface-page-dark}) color-mix(in oklab, {colors.fill-danger-dark} 16%, {colors.surface-page-dark}) color-mix(in oklab, {colors.fill-info-dark} 16%, {colors.surface-page-dark}) color-mix(in oklab, {colors.fill-success-dark} 38%, {colors.line-default-dark}) color-mix(in oklab, {colors.fill-warning-dark} 38%, {colors.line-default-dark}) color-mix(in oklab, {colors.fill-danger-dark} 38%, {colors.line-default-dark}) color-mix(in oklab, {colors.fill-info-dark} 38%, {colors.line-default-dark}) {colors.white-a6} {colors.white-a4} {colors.white-a18} {colors.white-a12} {colors.white-a4} {colors.white-a2} {colors.white-a4} {colors.white-a9} {colors.neutral-200} oklch(0.922 0 0 / 0.9) color-mix(in oklch, {colors.fill-danger-dark} 58%, transparent) color-mix(in oklch, {colors.fill-danger-dark} 68%, transparent) oklch(0.708 0 0 / 0.15) oklch(0.708 0 0 / 0.25) oklch(0.708 0 0 / 0.1) {colors.white-a9} {colors.black-a30} {colors.white-a4} {colors.white-a2}
heading title body body-sm label label-sm caption code
fontFamily fontSize fontWeight lineHeight
system-ui 1.5rem 600 2rem
fontFamily fontSize fontWeight lineHeight
system-ui 1.125rem 600 1.75rem
fontFamily fontSize fontWeight lineHeight
system-ui 1rem 400 1.5rem
fontFamily fontSize fontWeight lineHeight
system-ui 0.875rem 400 1.25rem
fontFamily fontSize fontWeight lineHeight
system-ui 0.875rem 500 1.25rem
fontFamily fontSize fontWeight lineHeight
system-ui 0.75rem 500 1rem
fontFamily fontSize fontWeight lineHeight
system-ui 0.75rem 400 1rem
fontFamily fontSize fontWeight lineHeight
Llama Mono 0.875rem 400 1.25rem
control panel card container surface surface-lg full
0.5rem 0.625rem 0.875rem 1rem 1.5rem 2rem 9999px
xs sm md lg xl 2xl
4px 8px 12px 16px 24px 32px
chat-form chat-form-dark chat-form-placeholder chat-form-placeholder-dark chat-form-edge chat-form-edge-dark chat-form-edge-focus chat-form-edge-focus-dark card card-dark card-edge card-edge-dark sidebar sidebar-dark sidebar-edge sidebar-edge-dark inset-group inset-group-dark inset-group-edge inset-group-edge-dark selected-row selected-row-dark user-bubble user-bubble-dark user-bubble-edge user-bubble-edge-dark floating-panel floating-panel-dark floating-panel-edge floating-panel-edge-dark dialog dialog-dark tooltip tooltip-dark button-primary button-primary-dark button-primary-hover button-primary-hover-dark button-secondary button-secondary-dark button-secondary-hover button-secondary-hover-dark button-secondary-border button-secondary-border-dark button-tertiary button-tertiary-dark button-tertiary-hover button-tertiary-hover-dark button-tertiary-border button-tertiary-border-dark button-outline button-outline-dark button-outline-border button-outline-border-dark button-outline-hover button-outline-hover-dark button-ghost button-ghost-dark button-ghost-hover button-ghost-hover-dark button-destructive button-destructive-dark button-destructive-hover button-destructive-hover-dark toggle-on toggle-on-dark toggle-hover toggle-hover-dark toggle-group toggle-group-dark toggle-group-border toggle-group-border-dark toggle-group-seam toggle-group-seam-dark toggle-group-key-muted toggle-group-key-muted-dark toggle-group-key-on toggle-group-key-on-dark tabs-list tabs-list-dark tabs-trigger tabs-trigger-dark tabs-trigger-active tabs-trigger-active-dark switch-track switch-track-dark switch-track-on switch-track-on-dark switch-thumb switch-thumb-dark switch-thumb-on switch-thumb-on-dark copy-feedback copy-feedback-dark input input-dark input-placeholder input-placeholder-dark input-border input-border-dark input-border-focus input-border-focus-dark input-border-invalid input-border-invalid-dark badge-default badge-default-dark badge-secondary badge-secondary-dark badge-outline badge-outline-dark badge-outline-border badge-outline-border-dark badge-destructive badge-destructive-dark badge-success badge-success-dark badge-warning badge-warning-dark badge-danger badge-danger-dark badge-info badge-info-dark code-block code-block-dark dialog-overlay list-row-selected list-row-selected-dark panel-muted panel-muted-dark chip-emphasis chip-emphasis-dark page page-dark chat-form-edge-mid chat-form-edge-mid-dark chat-form-edge-mid-focus chat-form-edge-mid-focus-dark sidebar-edge-mid sidebar-edge-mid-dark inset-group-edge-mid inset-group-edge-mid-dark glass-highlight glass-highlight-dark tooltip-highlight user-bubble-sheen user-bubble-sheen-dark field-shade field-shade-dark status-lamp-danger-rim status-lamp-warning-rim status-lamp-success-rim status-lamp-danger status-lamp-warning status-lamp-success
backgroundColor textColor rounded typography
#f9f9f9 {colors.fg-default} {rounded.surface} {typography.body}
backgroundColor textColor
#202020 {colors.fg-default-dark}
textColor
{colors.fg-muted}
textColor
{colors.fg-muted-dark}
backgroundColor
{colors.edge-rest-side}
backgroundColor
{colors.edge-rest-side-dark}
backgroundColor
{colors.edge-focus-side}
backgroundColor
{colors.edge-focus-side-dark}
backgroundColor textColor rounded padding
#f9f9f9 {colors.fg-default} {rounded.card} 24px
backgroundColor textColor
#202020 {colors.fg-default-dark}
backgroundColor
{colors.edge-rest-side}
backgroundColor
{colors.edge-rest-side-dark}
backgroundColor textColor rounded
#f9f9f9 {colors.fg-default} {rounded.container}
backgroundColor textColor
#1c1c1c {colors.fg-default-dark}
backgroundColor
{colors.edge-ambient-side}
backgroundColor
{colors.edge-ambient-side-dark}
backgroundColor textColor rounded
oklch(1 0 0 / 0.85) {colors.fg-default} {rounded.card}
backgroundColor textColor
oklch(0.985 0 0 / 0.03) {colors.fg-default-dark}
backgroundColor
{colors.edge-ambient-side}
backgroundColor
{colors.edge-ambient-side-dark}
backgroundColor textColor
oklch(0.145 0 0 / 0.05) {colors.fg-default}
backgroundColor textColor
oklch(0.985 0 0 / 0.05) {colors.fg-default-dark}
backgroundColor textColor rounded typography
#f3f3f3 {colors.fg-default} {rounded.surface} {typography.body}
backgroundColor textColor
#181818 {colors.fg-default-dark}
backgroundColor
{colors.edge-faint}
backgroundColor
{colors.edge-faint-dark}
backgroundColor textColor rounded typography
#ffffff {colors.fg-default} {rounded.panel} {typography.body-sm}
backgroundColor textColor
#161616 {colors.fg-default-dark}
backgroundColor
{colors.edge-raised}
backgroundColor
{colors.edge-raised-dark}
backgroundColor textColor rounded
#ffffff {colors.fg-default} {rounded.panel}
backgroundColor textColor
#0d0d0d {colors.fg-default-dark}
backgroundColor textColor rounded typography
{colors.action-primary} {colors.fg-on-action} {rounded.control} {typography.caption}
backgroundColor textColor
{colors.action-primary-dark} {colors.fg-on-action-dark}
backgroundColor textColor rounded typography height
{colors.action-primary} {colors.fg-on-action} {rounded.control} {typography.label} 36px
backgroundColor textColor
{colors.action-primary-dark} {colors.fg-on-action-dark}
backgroundColor textColor
#2e2e2e {colors.fg-on-action}
backgroundColor textColor
#cfcfcf {colors.fg-on-action-dark}
backgroundColor textColor rounded typography height
#f9f9f9 {colors.fg-default} {rounded.control} {typography.label} 36px
backgroundColor textColor
#202020 {colors.fg-default-dark}
backgroundColor textColor
#f7f7f7 {colors.fg-default}
backgroundColor textColor
{colors.surface-muted-dark} {colors.fg-default-dark}
backgroundColor
oklch(0.87 0 0 / 0.3)
backgroundColor
oklch(1 0 0 / 0.06)
backgroundColor textColor rounded typography height
#fcfcfc {colors.fg-default} {rounded.control} {typography.label} 36px
backgroundColor textColor
#232323 {colors.fg-default-dark}
backgroundColor textColor
{colors.action-quiet-hover} {colors.fg-default}
backgroundColor textColor
#323232 {colors.fg-default-dark}
backgroundColor
{colors.surface-muted}
backgroundColor
{colors.surface-muted-dark}
backgroundColor textColor rounded typography height
{colors.field-background} {colors.fg-default} {rounded.control} {typography.label} 36px
backgroundColor textColor
#232323 {colors.fg-default-dark}
backgroundColor
{colors.line-control}
backgroundColor
{colors.line-control-dark}
backgroundColor textColor
#f1f1f1 {colors.fg-default}
backgroundColor textColor
#1c1c1c {colors.fg-default-dark}
textColor rounded typography
{colors.fg-default} {rounded.control} {typography.label}
textColor
{colors.fg-default-dark}
backgroundColor textColor
#f1f1f1 {colors.fg-default}
backgroundColor textColor
#1c1c1c {colors.fg-default-dark}
backgroundColor textColor rounded typography height
{colors.action-danger} {colors.fg-on-danger} {rounded.control} {typography.label} 36px
backgroundColor textColor
#952420 {colors.fg-on-danger}
backgroundColor textColor
#ea262d {colors.fg-on-danger}
backgroundColor textColor
#ac2824 {colors.fg-on-danger}
backgroundColor textColor rounded typography height
{colors.surface-selected} {colors.fg-default} {rounded.control} {typography.label} 36px
backgroundColor textColor
{colors.surface-selected-dark} {colors.fg-default-dark}
backgroundColor textColor
#f1f1f1 {colors.fg-default}
backgroundColor textColor
#1c1c1c {colors.fg-default-dark}
backgroundColor textColor rounded typography height
#f9f9f9 {colors.fg-default} {rounded.control} {typography.label} 32px
backgroundColor textColor
#202020 {colors.fg-default-dark}
backgroundColor
oklch(0.87 0 0 / 0.3)
backgroundColor
oklch(1 0 0 / 0.06)
backgroundColor
{colors.line-control}
backgroundColor
{colors.line-control-dark}
backgroundColor textColor
{colors.surface-muted} oklch(0.145 0 0 / 0.7)
backgroundColor textColor
{colors.surface-muted-dark} oklch(0.985 0 0 / 0.7)
backgroundColor textColor
{colors.surface-pressed} {colors.fg-default}
backgroundColor textColor
#2e2e2e {colors.fg-default-dark}
backgroundColor rounded height padding
{colors.surface-muted} {rounded.panel} 36px 2px
backgroundColor
{colors.surface-muted-dark}
backgroundColor textColor rounded typography
{colors.surface-muted} oklch(0.145 0 0 / 0.7) {rounded.control} {typography.label}
backgroundColor textColor
{colors.surface-muted-dark} oklch(0.985 0 0 / 0.7)
backgroundColor textColor
{colors.surface-lifted} {colors.fg-default}
backgroundColor textColor
#363636 {colors.fg-default-dark}
backgroundColor rounded height width
{colors.surface-muted} {rounded.full} 18px 32px
backgroundColor
{colors.surface-muted-dark}
backgroundColor
{colors.action-primary}
backgroundColor
{colors.action-primary-dark}
backgroundColor rounded size
{colors.surface-lifted} {rounded.full} 16px
backgroundColor
{colors.surface-lifted-dark}
backgroundColor
{colors.surface-lifted}
backgroundColor
{colors.surface-raised-dark}
backgroundColor textColor
{colors.surface-page} {colors.fg-success}
backgroundColor textColor
{colors.surface-page-dark} {colors.fg-success-dark}
backgroundColor textColor rounded typography height
{colors.field-background} {colors.fg-default} {rounded.control} {typography.body-sm} 36px
backgroundColor textColor
#232323 {colors.fg-default-dark}
textColor
{colors.fg-muted}
textColor
{colors.fg-muted-dark}
backgroundColor
{colors.line-field}
backgroundColor
{colors.line-field-dark}
backgroundColor
{colors.line-focus}
backgroundColor
{colors.line-focus-dark}
backgroundColor
{colors.line-danger}
backgroundColor
{colors.line-danger-dark}
backgroundColor textColor rounded typography padding
{colors.action-primary} {colors.fg-on-action} {rounded.control} {typography.label-sm} 2px 8px
backgroundColor textColor
{colors.action-primary-dark} {colors.fg-on-action-dark}
backgroundColor textColor rounded typography
#dadada {colors.fg-default} {rounded.control} {typography.label-sm}
backgroundColor textColor
#252525 {colors.fg-default-dark}
textColor rounded typography
{colors.fg-default} {rounded.control} {typography.label-sm}
textColor
{colors.fg-default-dark}
backgroundColor
{colors.line-default}
backgroundColor
{colors.line-default-dark}
backgroundColor textColor rounded typography
{colors.action-danger} {colors.fg-on-danger} {rounded.control} {typography.label-sm}
backgroundColor textColor
#952420 {colors.fg-on-danger}
backgroundColor textColor rounded typography
{colors.surface-success} {colors.fg-success} {rounded.control} {typography.label-sm}
backgroundColor textColor
{colors.surface-success-dark} {colors.fg-success-dark}
backgroundColor textColor rounded typography
{colors.surface-warning} {colors.fg-warning} {rounded.control} {typography.label-sm}
backgroundColor textColor
{colors.surface-warning-dark} {colors.fg-warning-dark}
backgroundColor textColor rounded typography
{colors.surface-danger} {colors.fg-danger} {rounded.control} {typography.label-sm}
backgroundColor textColor
{colors.surface-danger-dark} {colors.fg-danger-dark}
backgroundColor textColor rounded typography
{colors.surface-info} {colors.fg-info} {rounded.control} {typography.label-sm}
backgroundColor textColor
{colors.surface-info-dark} {colors.fg-info-dark}
backgroundColor textColor rounded typography
{colors.surface-code} {colors.fg-code} {rounded.panel} {typography.code}
backgroundColor textColor
{colors.surface-code-dark} {colors.fg-code-dark}
backgroundColor
{colors.surface-overlay}
backgroundColor textColor rounded
{colors.surface-selected} {colors.fg-default} {rounded.control}
backgroundColor textColor
{colors.surface-selected-dark} {colors.fg-default-dark}
backgroundColor textColor rounded
{colors.surface-muted} {colors.fg-default} {rounded.panel}
backgroundColor textColor
{colors.surface-muted-dark} {colors.fg-default-dark}
backgroundColor textColor rounded
{colors.surface-emphasis} {colors.fg-default} {rounded.control}
backgroundColor textColor
{colors.surface-emphasis-dark} {colors.fg-default-dark}
backgroundColor textColor
{colors.surface-page} {colors.fg-default}
backgroundColor textColor
{colors.surface-page-dark} {colors.fg-default-dark}
backgroundColor
{colors.edge-rest-mid}
backgroundColor
{colors.edge-rest-mid-dark}
backgroundColor
{colors.edge-focus-mid}
backgroundColor
{colors.edge-focus-mid-dark}
backgroundColor
{colors.edge-ambient-mid}
backgroundColor
{colors.edge-ambient-mid-dark}
backgroundColor
{colors.edge-ambient-mid}
backgroundColor
{colors.edge-ambient-mid-dark}
backgroundColor
{colors.highlight-inner}
backgroundColor
{colors.highlight-inner-dark}
backgroundColor
{colors.highlight-inverse}
backgroundColor
{colors.sheen-start}
backgroundColor
{colors.sheen-start-dark}
backgroundColor
{colors.field-shade}
backgroundColor
{colors.field-shade-dark}
backgroundColor
{colors.status-danger-rim}
backgroundColor
{colors.status-warning-rim}
backgroundColor
{colors.status-success-rim}
backgroundColor textColor rounded size
{colors.status-danger} {colors.status-danger-glyph} {rounded.full} 8px
backgroundColor textColor rounded size
{colors.status-warning} {colors.status-warning-glyph} {rounded.full} 8px
backgroundColor textColor rounded size
{colors.status-success} {colors.status-success-glyph} {rounded.full} 8px

Overview

Llama UI is the design system and component library this file describes. Llama Chat, built from it, is the local, private chat client that llama-server bundles, and the native Llama apps (Llama for Mac, Llama for Windows) open it in their own window. It should feel calm and tool-like: neutral greys, plenty of space, and surfaces that read as frosted matte glass rather than shiny plastic. Depth comes from blur, a faint hairline edge and soft shadows, never from strong gradients. Colour is reserved for meaning: the status colours (success, warning, error and info), destructive actions, and the content itself.

There are three layers between a person and a model: the model (the weights, a GGUF file), the service (the server that runs inference: llama.cpp and llama-server) and the application (the harness, the UI and UX). The harness, the agentic loop, is its own headless package, Llama Harness (@ggml-org/llama-harness), next to Llama UI (@ggml-org/llama-ui). Llama UI and Llama Chat are the application layer. Running all three locally is the point: people choose their model and keep their conversations and traces, so the UI never assumes a cloud account or hides which model runs. The service need not be on the same machine: a server can be run by one person and shared by many (a family, a team, a community), so the UI should make clear which server a model runs on.

This file is the how, written for agents first. Its principles, as rules to apply here:

  • Function first. Every element has a job and takes its measurements from a shared role (control heights, corners, icon sizes, type roles); never give one component its own.
  • Simple by default, deep on request. The first screen offers a suggested model and sensible defaults; advanced settings (sampling, penalties, system prompts, recipes) sit one step away behind a disclosure, never on the default path. Prefer plain words to terms like GGUF, quantization or speculative decoding, and explain a term where it must appear.
  • The content is the loudest thing. The conversation carries the weight and the colour; the interface around it stays neutral and quiet.
  • Colour has one job. Greys build everything; status colours show status and nothing else; art colours and cinder are for artwork and the odd brand detail, never for the UI's controls.
  • Recognisable, easy to change. Keep the character in the icon, the type and one accent, so an app built on Llama UI can restyle it through component tokens alone.
  • Design lives in code. The CSS is the source of truth; prefer what is generated or derived over hand-tuned values, and record the reason next to the value.
  • Reuse before adding. An existing role before a new token, an existing component before a new one.

Design tokens come in three tiers, each in its own file under ui/lib/ui/src/lib/styles/tokens/:

  1. Primitives (primitives.css): raw values named by what they are, such as neutral-900, cool-gray-200, red-500, white-a30, font-size-14 or length-24. Only semantic tokens point at them.
  2. Semantic tokens (semantic.css): named by purpose, such as surface-glass, fg-muted, line-field, edge-focus-side, action-primary or status-warning. They point at primitives and are the only tier that changes between light and dark. The type, corner, icon size and control height roles live here too and are Tailwind utilities: text-label, rounded-control, size-icon-md, h-control-md.
  3. Component tokens (components.css): one group per component, named [component]-[variant]-[property]-[state], such as chat-form-edge-side-focus or button-secondary-background-hover. They point at semantic tokens, and components read them as bg-(--button-primary-background) and similar.

The front matter of this file mirrors those three files. When they disagree, the CSS wins and this file should be updated to match.

Light mode is the base. A semantic token whose dark value differs has a -dark twin here, and components list a -dark entry wherever their colours change. Translucent component fills are given as they render over the page, so contrast checks see the real colour.

Colors

The palette is achromatic. Hue appears only in the hairline edges (a cool grey at hue 250, kept almost neutral) and in the status colours, which serve function only: green for success, amber for warning, red for errors and blue for information, saturated enough to read at a glance and tuned to text contrast in both modes. Each status has one root colour, its fill (fill-*), and everything in that status derives from it: the soft surface and line of alerts and badges, the border of an invalid field, the lamp. Red keeps to the same rule, so there is one red: the danger button and the solid danger badge are the fill itself (action-danger), solid in light mode and frosted, translucent matte glass in dark (58% of the fill over the page). Never style a danger control with its own red (bg-destructive, bg-red-500 …): use the destructive variant, which AlertDialog.Action takes too, or the status tokens. Cinder (art-cinder, oklch(0.68 0.18 46), #ee6c1e) is the brand's one accent orange: the .cpp of the llama.cpp logotype, the mark on a detail in the brand pages and the warm pop in artwork. It is not part of the UI palette. Sand (sand-50 to sand-900) is the warm neutral for communications (posters, boards, the site); the UI itself stays on the greys.

Backgrounds stay neutral as a rule, in the UI and in communications alike: greys and sand behind, colour only where it serves a purpose, functional (status, a selection, focus) or creative (a shape, a numeral, an illustration). Artwork takes its colours from the greys, sand and the art-* primitives: the day sky and the night sky (llama.app's light and dark hero grounds) and cinder, the accent orange; never from the status colours, and never red.

Light mode has two surface themes, which share everything else (the palette, buttons, fields, badges, shadows and dark mode): Paper, the default, sets white panels, fields and keys on a faint grey page (neutral-25); Matte sets grey glass on a white page. Matte is the theme-matte class on <html>, chosen with the Light surfaces setting (Settings → General), and only its surface tokens differ: surface-page, surface-glass, surface-code, field-background and float-panel-background-modal.

  • Surfaces: surface-page for the page, surface-muted for quiet panels, surface-emphasis and surface-selected for stronger fills and hover or selected rows, surface-raised for menus and dialogs, surface-lifted for a selection raised on a recessed track, surface-pressed for a key pressed in, surface-glass for the translucent matte fill, surface-code for code and surface-overlay behind dialogs.
  • Foreground: fg-default and fg-muted for text and icons, fg-on-action and fg-on-danger on filled buttons, fg-code for code, fg-danger for errors, fg-success for confirmations such as a copied check, fg-warning for cautions and fg-info for neutral notices.
  • Lines: line-default for dividers, line-control for outlined controls (soft in dark mode), line-field for inputs, line-focus for focus and line-danger for invalid fields.
  • Edges: the hairlines of matte surfaces, darker at the sides than in the middle. edge-rest-* at rest, edge-focus-* when focus is inside, edge-ambient-* for large quiet containers whose edge never changes, edge-faint for the user bubble and edge-raised for floating panels.
  • Actions: action-primary (near black in light mode, near white in dark mode) and its hover, action-danger and its hover, and action-ghost-hover.
  • Status fills: fill-success, fill-warning, fill-danger and fill-info are each status colour at its brightest, for dots, lamps and other small solid marks. They are brighter than the matching fg-* text colour, which keeps to a readable lightness (4.5:1 on the soft surfaces), and are a little lighter again in dark mode.
  • Status surfaces: surface-success, surface-warning, surface-danger and surface-info are soft tints of each status fill for alerts and soft badges, with line-*-soft hairlines to match. They are mixed in oklab so the hue holds over the page. Soft status badges are pills with a small dot in the status fill before the label.
  • Status: status-danger, status-warning, status-success and status-info are the lamp fills for error or stopped, loading or warning, ready or connected, and informational. They take the status fills, and each has a lighter -rim and a darker -glyph. Known gap: the glyph on the red lamp reaches only about 2:1 and on the green lamp about 3.2:1, below WCAG AA, so the lamp colour must never be the only signal; pair it with a label or tooltip.

Typography

The UI uses Llama Sans for all text, headings included (with the system sans-serif stack as its fallback), and Llama Mono for code (with the system monospace stack as its fallback). Llama Sans is one variable font with an optical size axis: the browser sets it from the font-size, so text at 16px gets the UI spacing and kerning, 36px and up the tighter Display setting and text under 16px a looser Small one, with a blend in between. Nothing needs choosing per element; pin a point only to show it, with font-variation-settings: 'opsz' 16 or 36. Its line box is 1.25 at every size, centred on the cap height; large headings set line-height: 1.15 themselves. Llama Mono keeps every character, its coding ligatures included, in one cell, so code and numbers line up in columns. Type is set through roles that fix size, line height and weight together:

  • body (16/24, 400): chat messages and the chat input.
  • body-sm (14/20, 400): most text, fields and lists.
  • label (14/20, 500): buttons and field labels.
  • label-sm (12/16, 500): badges and compact labels.
  • caption (12/16, 400): tooltips, hints and metadata.
  • title (18/28, 600) and heading (24/32, 600): rare headings; there is no display size.

When a component lets callers override the size, keep an explicit weight class next to the role (text-label font-medium) so a size override does not drop the weight. Placeholders in the chat form are engraved: muted text with a 1px highlight below it in light mode and a 1px shadow above it in dark mode (the engraved utility).

Layout

Spacing follows a 4px grid. Gaps of 4 to 12px (xs to md) dominate inside controls and lists; 16 to 32px (lg to 2xl) separate sections. Controls are 32, 36 or 40px tall (h-control-sm, h-control-md, h-control-lg) and icons are 12, 14, 16 or 20px (size-icon-xs to size-icon-lg). Square boxes use size-N, never a matching h-N w-N pair, and icons use the size-icon-* roles. Inside buttons, toggles and menu items an icon is 16px (size-icon-md) unless a smaller control calls for less. The chat column is centred with a generous bottom offset so the floating chat form never covers the last message. The desktop sidebar is 18rem wide by default, can be resized, and collapses to a 3rem strip.

Safe areas

The page runs under the status bar and over the home indicator (viewport-fit=cover), which an installed iPhone app always shows and a browser tab mostly does not. The insets are --safe-area-top and --safe-area-bottom (0 where there is none). Anything pinned to a screen edge keeps clear of them with the safe-area utilities from src/lib/styles/safe-area.css, never a hand-written calc():

  • pt-safe, pb-safe: padding of just the inset, e.g. a sheet that fills the screen.
  • pt-safe-N, pb-safe-N: a spacing step plus the inset, e.g. pt-safe-12 for the chat, whose messages start 3rem below the top on a phone.
  • pt-(--page-top): where a page with a title, like Models, Projects or Library, starts on a phone: a row below the corner controls, so the title clears both the menu key and the fade under the status bar.
  • top-safe-N, bottom-safe-N: the same for absolutely or fixedly placed controls, e.g. top-safe-2.5 for the expanded chat form's collapse button.
  • top-(--corner-control-top), bottom-(--corner-control-bottom), right-(--corner-control-side): the phone's corner controls, like the menu key and a page's floating key. They follow the insets differently in the installed app (see Corners below).

Corners in the installed app. The status bar and the home indicator set the screen's top and bottom apart on their own, so a corner control does not add its usual gap on top of their insets there. At the top it sits just below the status bar (--corner-control-top, the inset plus 0.25rem). At the bottom the home indicator is a short bar in the middle and the corners beside it are free, so a bottom corner action ignores its inset instead of stacking above the indicator. Its gaps from the bottom and the side are always equal, 1.75rem (--corner-control-bottom is defined from --corner-control-side), which keeps a 56px key about concentric with an iPhone's rounded screen corner. Only what spans the bottom edge's middle, like a sheet's last row, clears the inset with pb-safe or bottom-safe-N. In a browser tab the top keeps 1rem and the bottom its 1.75rem beyond the insets.

A control placed inside a padded box still needs its own top-safe-N: absolute positions ignore the padding. Dialogs keep clear of the insets on their own (see Dialogs on phones under Components). At the top, every route on a phone has the status-bar-fade from the root layout: solid behind the status bar and the row of corner controls under it, fading out down to --page-top, like the fade under the desktop tab bar, so content scrolls away under them instead of colliding with the clock or the chat's header. A route needs no fade of its own; what covers the whole screen, like the expanded chat form, hides it, and it fades out as the page slides aside for the sidebar. Check pinned content with the insets simulated, since they are 0 in a desktop browser.

Elevation & Depth

Depth is built from the matte utilities in ui/lib/ui/src/lib/styles/surfaces.css. Pick the one that matches the role of the surface instead of combining raw shadows.

  • matte-glass: large resting surfaces. A translucent fill with a backdrop blur, an inner highlight, a soft drop shadow and a 1px hairline whose sides are slightly darker than its middle. The hairline is drawn on a masked ::before so it never tints the fill. Focus inside swaps the hairline to the focus edge; the shadow stays the same. Its colours come from slot variables, and chat-form-surface, card-surface, sidebar-surface and inset-group-surface point those slots at one component's tokens, so each component needs a single class.
  • matte-float and matte-float-modal: menus, popovers, select lists, hover cards and drawers, and dialogs over the page colour. An 86% opaque panel with blur, a faint edge and a deeper shadow. The edge is a hairline ring baked into the shadow as its last layer, never a border next to a shadow, which would read as a double edge; the panel's border stays transparent so its size does not change. In light mode dialogs are solid white instead: over the dimmed page a translucent white turns grey.
  • matte-key: buttons, selects, toggles and tabs. The matte finish: on top of the button's own fill it adds a light blur, a fill barely lighter at the top (--key-sheen, 12% white in light mode, 2% in dark) and a small drop shadow. It never changes the button colour and draws no rim of its own: every matte-key control has a border, and a rim inside it would double the edge. Nothing marks the top edge alone, so the edge looks the same all round, with no gloss.
  • matte-key-solid: primary and danger buttons. The same sheen, fainter (--key-sheen-solid), the same blur, and an even 1px hairline in a shade of the fill drawn inside the button (--key-edge), so the width does not change. The danger key stays matte glass rather than metal: its sheen is almost none (--button-danger-sheen), and in dark mode it is a frosted, translucent red (red-500 at 58%) whose edge is a soft tint of the red, never a lighter rim.
  • elevated-control, elevated-surface and elevated-raised: cards, floating bars and thumbnails. An elevation token with a hairline ring baked in as its last layer, so the edge melts into the shadow and the shadow deepens in dark mode. The ring is --elevation-ring (black 5%, white 18% in dark) at --elevation-ring-width (1px). They replace a border plus a shadow; never add a border to them.
  • matte-well: inputs, textareas and checkboxes. A shallow inset shade so fields read as recessed.
  • matte-sheen and matte-sheen-solid: the user message bubble and badges. An almost invisible top-to-bottom sheen, fainter on solid fills.
  • status-lamp and matte-orb with orb-danger, orb-warning or orb-success: small status dots and the recording button. A near-flat fill barely lighter at the top and an even hairline, with no glow.

The elevation tokens are elevation-surface, elevation-control, elevation-raised, elevation-inset and elevation-tooltip. The drop shadows are smooth stacks: a few soft layers instead of one hard one, the closest the darkest and smallest, each further layer about twice the offset and blur and fainter, the far ones pulled in with a negative spread, so the shadow fades out instead of ending in a visible edge. They stay as close as upstream's Tailwind shadows: elevation-surface reaches about 20px, like shadow-lg, elevation-raised about 38px, like shadow-xl, and elevation-control is three tight layers reaching no further than 4px, so buttons and other controls sit close to the page. Two softer steps sit below them: elevation-soft for the chat form, which floats only a little, and elevation-faint for the user message bubble, which barely lifts. The keys inside the chat form, the add key and the model selector, take elevation-key (--chat-form-key-shadow): a 0.5px hairline all round and a 1px drop, since the control elevation's soft spread blends into the white form; in dark it is the control elevation. Dark mode deepens the same stacks. Tailwind's own shadow-xs to shadow-2xl are built the same way (tokens/semantic.css), each reaching about as far as Tailwind's default for it. Every button carries elevation-control (--button-shadow); a ghost button only while hovered. Overlays behind dialogs are surface-overlay with a 2px blur.

Shapes

Corners are soft and consistent, set through roles: control (8px) for buttons, fields and badges, panel (10px) for menus and dialogs, card (14px) for cards, container (16px) for the sidebar, and surface (24px) for the chat form and message bubbles, rising to surface-lg (32px) for the chat form on small screens. Status lamps, avatars and the round icon buttons in the chat form are fully round.

Brand

  • Logo: the llama.cpp mark, one inline SVG (Logo) filled with the current text colour, so it follows the theme with no light and dark copies. It is sized by --size, 1rem by default: 14px in model rows, 16px in the sidebar. Colour it with a text token such as fg-default or fg-muted, never a raw colour.
  • App icons: the mark in #111111 on white, or #fafafa on #111111 in dark mode (FAVICON_COLORS, THEME_COLORS). The favicon keeps a 4% margin (FAVICON_PADDING), so the logo spans 96% of it. The maskable and Apple touch icons are white squares with the logo at 67% (the generator's 30% padding); its farthest point reaches 73%, inside the 80% maskable safe zone. The PWA icons are white circles with the logo at 57% (make-icons-circular.js, 85% of the square icon).
  • Splash screens: white, or #111111 in dark mode, with the logo centred at 24% of the screen's shorter side (SPLASH_PADDING).
  • The icons and splash screens in static/ are build output of npm run build-pwa-assets, drawn from logo.svg; change the source or the constants, never the generated files.

Components

  • Buttons: six variants.

    • default: the solid primary button, including the chat submit button.
    • secondary: the matte glass button, the same fill as the chat form with a faint border, also used for the chat form's Stop and Skip reasoning buttons.
    • tertiary: a faint grey tint with a soft muted border, quieter than secondary and still a visible button; kept for low-emphasis actions that need more presence than ghost.
    • outline: the input fill with a line-control border, for secondary actions in dialogs and forms.
    • ghost: no fill until hovered, for icon buttons and quiet actions.
    • destructive: red, for deleting and other irreversible actions.

    All except ghost carry matte-key. Sizes are sm (32px), default (36px) and lg (40px), plus square icon sizes.

  • Badges: four variants with the same names: default, secondary (a light foreground tint), outline and destructive, plus the soft status badges success, warning, danger and info. Badges are a fill or a border with the faint matte sheen and no inner rim.

  • Toggles: the same corners, type, heights, padding and icon size as buttons, with square icon-sm, icon and icon-lg sizes for icon-only toggles. default has no fill until hovered; outline borrows the outline button. Pressed toggles take toggle-background-on.

  • Button groups: joined buttons share one shadow, drawn by the group, and one border at each seam. A group separator replaces the seam border. Filled buttons draw a seam in their own text colour (button-primary-seam, button-danger-seam) instead.

  • Selection on a track: a choice that moves along a track is a recessed track with the selection raised on it, never a row of outlined buttons. The track is surface-muted with the inset shade (elevation-inset); the selection is a surface-lifted chip with elevation-control, and unselected options are softened text with no fill. Tabs use the same track for their list, with the active tab raised (tabs-*); a line variant underlines the active tab instead. The chip or underline slides between tabs in 300ms on a plain ease-out, with a stretch of at most 5% along the move that is gone by the time it lands; with reduced motion it jumps instead. The switch is the same track with a raised thumb; switched on, the track takes the primary colour. The message statistics view switcher uses the tabs tokens.

  • Toggle groups: a row of keys, like an old stereo's, not a track. At rest the group is a secondary button, the same glass fill, border and shadow as a select trigger, with a line-control seam between keys. A pressed key turns white (surface-pressed, the lightest fill in dark mode) and sinks in under a subtle inner shadow (elevation-pressed), its label a pixel lower. While any key is pressed, the others turn grey in light mode (surface-muted) and mute their labels, so the pressed one stands out. A group is as tall as a control of its size.

  • Chat form: one chat-form-surface holding the input, attachments and actions. Its fill is the muted grey at 60% in light mode and 75% in dark mode.

  • User message bubble: the primary colour at 5% with matte-sheen and the very faint edge-faint hairline, so it separates from the page without a visible border.

  • Sidebar: sidebar-surface, the muted fill at 60% with no inner highlight and the ambient edge. On small screens it keeps a plain shadow-md instead.

  • Inset groups: inset-group-surface gathers rows inside a glass panel, like the sidebar footer's Models, MCP and Settings, instead of a rule between them and the rows above. In light mode it is a soft white (surface-raised at 85%) on the grey glass; in dark mode a raised fill would be darker than the glass, so it is a 3% tint of the text colour. It takes the sidebar's ambient edge, no inner highlight and only a faint, wide shade under it (0 2px 8px -4px, 8% black in light, 40% in dark), with the card radius. It reads as part of the panel: no tight contact shadow and no solid border, which make a button, and no inset shade, which makes a field. Unlike the other matte-glass surfaces it does not blur: it already sits on glass, and a second backdrop blur re-paints the panel's fill behind it and turns the group visibly lighter, whatever its own fill.

  • Selected rows: selected-row-surface marks the row a sidebar list is on: a conversation, a project or a top action, on desktop and on a phone. It is a 5% tint of the text colour, under hover's 10%, with the inset group's edge and shade, so the selected row reads as picked out rather than hovered, in both modes. It keeps the row's own radius, and hover and press fills still paint over it.

  • Fields: matte-well with a 1px line-field outline and the standard 3px focus ring.

  • Floating panels: every menu, popover, select list, hover card and drawer uses matte-float; dialogs use matte-float-modal.

  • Chat header on phones: a chat shows its title and, under it, its working directory centred between the menu key and the context gauge, on the top fade. The directory is the folder's name (the full path is its title) and tapping it opens the directory picker, which on a phone is a drawer. A new chat has no header yet: it offers "Set working directory" in the + menu instead, and no chip sits under the form on a phone. The header steps aside with the corner keys while the expanded chat form covers the screen.

  • Dialogs on phones: below md every dialog is full screen, whatever size it takes on a desktop. The shared Dialog.Content does this, so a dialog sets only its desktop size and never its own phone size. Its top and bottom borders take the height of the status bar and the home indicator, transparent, so the content keeps clear of both with no change to its padding (see Safe areas). A dialog that draws its own full-screen content instead, like the attachment preview, keeps clear with pt-safe, pb-safe and top-safe-N itself. Alerts (AlertDialog: confirmations, renames, errors) are the exception: a short question with a button or two, they stay small and centred on a phone too. A place the sidebar opens, like Settings, MCP Servers or Servers, is no dialog on a phone at all but a page at its own route (#/settings, #/mcp-servers, #/servers), with the menu key and a title like any phone page; a desktop or tablet keeps it a dialog over the page it was opened from.

  • Glass keys: a round key that floats over the page and lets it show through, like the menu and context gauge keys at a phone's top corners and the key back to a chat's bottom, is a GlassKey (GLASS_KEY_CLASS): white glass (surface-glass), a faint line-default hairline, and matte-key's blur and saturation with its small shadow, so what scrolls under it softens instead of showing sharp behind the icon. 40px at the corners, 36px over the page; its icon is a 2px-stroke glyph in fg-default on the 24px icon grid, the context gauge's dial drawn the same way. Don't rebuild one from a ghost Button plus classes: the button's own blur overrides matte-key's.

  • A page's main action on phones: below md the action that adds to a page, like New project or New prompt, leaves the page's header for a FloatingActionButton: a round 56px default (primary) key with a large shadow and only a + icon, pinned in the bottom-right corner 1.75rem from both edges (--corner-control-side, --corner-control-bottom; in the installed app beside the home indicator rather than above it, see Safe areas), where the thumb rests. It is portalled to the body, so its place on screen never depends on the page's box, and slides with the page when the sidebar opens, by the same offset and ease (--sidebar-reveal-x), taking no taps while the page is aside. The page keeps room under its last row (max-md:pb-safe-24) so the key never covers it. One per page, only for its main action; from md up the action stays a button in the header.

  • Copy feedback: a copy action turns its icon into a fg-success check for 1.5s (COPY_FEEDBACK_RESET_MS), only when the copy succeeded, then back. The icon pops in with a 150ms fade and scale, skipped on first render and with reduced motion.

  • Tooltips: the inverse of the page, the primary colour with a faint inner rim.

  • Status: server, model and MCP connection states use the status lamps, never coloured text alone.

Do's and Don'ts

  • Do keep fills flat. Gradients, if any, must be barely perceptible; a visible gradient makes the UI look like a 2000s interface.
  • Do keep edges faint. At rest a hairline should blend in; on focus it should be noticeable but never strong.
  • Do keep the shadow the same on focus. Focus is shown by the edge and the focus ring, not by lifting the surface.
  • Do use the status colours only for status. Buttons keep their neutral colours, and the submit button stays black in light mode and white in dark mode.
  • Do read component tokens in components, semantic tokens in shared styles, and primitives only in semantic tokens.
  • Do add a new colour as a primitive first, then give it a semantic name before any component uses it.
  • Do give motion a job: show where something went or what changed, like a selection sliding to its new place. A barely visible stretch along a move, or a settle past the target by a pixel or two, can make that feel physical; keep it under about 5% and 300ms, and drop it entirely with reduced motion. Never let a bounce carry something past the edge of its container, such as a tab indicator past its track; there, slide without one. If you notice the effect itself rather than the change it shows, it is too much.
  • Do reach for the surface utility that matches the component instead of adding raw shadow-*, border-* and backdrop-blur-* combinations.
  • Don't use Tailwind's palette classes (text-amber-500, bg-green-500/10) for meaning in new code; use the semantic tokens. Some older components still do and are being moved over.
  • Don't introduce new accent hues (such as a blue submit button) without a design decision.
  • Don't put white rims or highlights on large ambient containers such as the sidebar.
  • Don't animate for decoration: no motion on things that did not change, no bounces on entrances, and nothing that delays the user.
  • Don't stack two glass surfaces with blur directly on top of each other.
  • Don't give a dialog its own size on a phone: every dialog is full screen there. Only alerts stay small and centred.
  • Don't put more than one floating key on a phone page, or use one for anything but the page's main action.
  • Don't lift a bottom corner action above the home indicator's inset in the installed app, or give it a different gap from the bottom than from the side: the corners beside the indicator are free, and --corner-control-bottom and --corner-control-side keep the two gaps equal.