Skip to content

ui: Llama UI design system: tokens, surfaces and fonts - #22

Closed
allozaur wants to merge 1 commit into
masterfrom
allozaur/style/glass-surfaces
Closed

allozaur wants to merge 1 commit into
masterfrom
allozaur/style/glass-surfaces

Conversation

@allozaur

@allozaur allozaur commented Oct 31, 2026 •

Copy link
Copy Markdown
Owner

Overview

Llama UI, the design system and component library published as @ggml-org/llama-ui, comes into llama.cpp as ui/lib/ui, with three tiers of tokens, matte glass surfaces and Llama Sans and Llama Mono. Llama Chat is built on it, taking its components, tokens, fonts and shared code from the library instead of keeping its own copy, and the library takes the brand's colours and logo from @ggml-org/llama-brand.

Demo

Demo

Recorded at e24a39d; click the preview for the full video.

Additional information

Part 1 of 13 of a work-in-progress stack on the fork, based on master, which has SvelteKit 3 since ggml-org#32463 was merged. Its first commit is fork-only and was #70's first: the dev proxy calls llama-server without the page's Origin, so vite dev passes the server's cross-origin check from a LAN or Tailscale address. Upstream, this PR is the other 11 commits on master (ggml-org#32468).

The Storybook is left alone here, apart from one import that the move of the base components needs. Llama UI's own Storybook, Llama Chat's stories on the new design system and the Submenus story that tests the submenu fixes are in the next PR, #67. The brand and communications pages moved to ggml-org/llama-brand#10.

Read it commit by commit: the one after the dev proxy brings in the library as it was in the temporary ggml-org/llama-ui repository at edaf518, without its Storybook (119 new files). @ggml-org/llama-ui 0.3.0 on npm is published from this ui/lib/ui.

Known gaps: the Docker and Nix builds were not run locally. The fonts are still the library's own WOFF2 copies: llama-brand ships them as TTF only, three times the size, so they move to llama-brand's once it has WOFF2 builds. @ggml-org/llama-brand is a dependency of the published package by its GitHub tarball, as Llama Chat already installs it, now under the same name. tw-animate-css is now a peer dependency of the library, so llama.pages needs to import it before theme.css when it moves to 0.3.0. DESIGN.md describes the UI of the whole stack, so it also names pages and packages from later PRs. The demo was recorded on an earlier version of this layer and needs recording again.

What changed
  • The library (ui/lib/ui): the tokens, fonts, surfaces, base components and Model UI, built with @sveltejs/package. A CI job type-checks and packs it, and ui/README.md describes the layout of ui/. The npm scope is @ggml-org for every package.
  • The design system: three tiers of tokens (primitives, semantic, component), matte glass surfaces and Llama Sans and Llama Mono, with Llama Chat restyled on them. DESIGN.md holds the tokens, roles and rules for agents.
  • Llama Chat on the library:
    • ui/lib/ui gets the 17 base components it lacked (alert, alert-dialog, button-group, checkbox, collapsible, context-menu, dialog, drawer, dropdown-menu, empty, hover-card, radio-group, scroll-area, skeleton, table, tabs, textarea) and the inset-group and selected-row tokens and surfaces. It now holds all 29.
    • The library's sources import each other by relative path instead of $lib, which in an app points at the app's own src/lib.
    • ui/apps/chat imports base components as @ggml-org/llama-ui/ui/<name> and cn/tv as @ggml-org/llama-ui/utils, and app.css imports the library's theme.css. Its src/lib/components/ui, styles/tokens, styles/surfaces.css and assets/fonts are gone.
    • The app compiles the library from source, with no install or build of it. scripts/vite-plugin-llama-ui.ts resolves the library's entry points and what its sources import from the app's own node_modules, and the SvelteKit config gives TypeScript the same paths (a unit test checks they match), so there is one copy of Svelte and bits-ui in the bundle and in the types.
    • CMake stages ui/lib/ui next to the app and rebuilds when a library source changes. The Dockerfiles copy the library's sources, and the Nix derivation takes ui/ as its source.
  • Fonts: Llama Sans and Llama Mono from llama-brand's latest, with optical sizes from 10 to 36. Bash code blocks mark shell commands and flags.
  • Submenus were cut off by the menu they open from: they rendered inside it, and the glass blur and the open animation make the menu hold even a fixed-position submenu, so its scroll box clipped them.
    • Dropdown and context-menu submenus render in a portal, as the menus themselves do. CSS alone cannot get the submenu out while the menu has to scroll.
    • Submenus take their menu's corners and height cap, and open 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. Context menus take the dropdown's glass surface and slide-in.
    • The submenus' height cap and zoom origin named the dropdown's CSS variables, which bits-ui does not set on submenus; they use its --bits-menu-* ones now. The chat group submenu takes the actions menu's z-[999999] layer, as it no longer renders inside that menu.
  • Llama Chat on the library's Model UI and app components: ActionIcon, SearchInput, SyntaxHighlightedCode, Logo, ModelCapabilityIcons, ModelDownloadProgressBar and ModelDraftSidecars come from the library, and Chat's copies go. The library's ModelId gains what Chat's had (the model's own draft kind, draft sidecars with their quant, aliases, a raw-id tooltip), and Chat keeps ModelId and ModelOrgAvatar as thin wrappers for its settings. New entry points: @ggml-org/llama-ui/app/<group> and @ggml-org/llama-ui/models.
  • Shared constants, enums and helpers: Chat re-exports the library's where the two were the same (the shared classes and code-block constants, byte units, memory-fit constants, capability and modality icons and labels, ColorMode, TooltipSide, the model enums, formatParameters, minMemoryTierGb, highlightCode), from @ggml-org/llama-ui/constants, /enums, /code and /models. It keeps its own where they differ (UI_DATA_ATTRS, formatFileSize).
  • @ggml-org/llama-brand: the library's primitives build on its css/colors.css, which apps import before theme.css, instead of keeping copies of its 25 colours, and Logo draws llama-brand's icon.
  • The chat form's keys: the add key and the model selector trigger, white on the white chat form in light, take a tighter shadow (--elevation-key, through --chat-form-key-shadow): a 0.5px hairline and a 1px drop instead of the control elevation's soft spread. Chosen from the options in Scrapbook › UI › Composer keys; dark keeps the control elevation.
  • A store race: updateCurrentNode awaited the database write and then wrote the node to whichever conversation was active by then. When the conversation closed during the write the reply ended in a streaming error dialog, and when another one opened it got the wrong node. It now sets the node in memory only while the same conversation is still active.
Testing
  • ui/lib/ui: npm ci, npm run check, npm run prepack (svelte-package and publint) and its 11 unit tests pass.
  • ui/apps/chat: npm run check, npm run lint and npm run build pass, with 794 unit tests, 270 client tests and the 49 story tests this layer has.
  • Type-check and lint also pass at the library, design system and Llama Chat move commits on their own.
  • No visual change from moving Llama Chat onto the library, comparing the commits before and after it:
    • The built CSS has the same rules, apart from these, and none changes what the app renders. The @font-face rules, the :where(code, pre, kbd, samp) rule and the :root blocks move, and the body base rule is split in two. Two tokens are new. 21 utilities come from library components the app does not use (Tabs, ModelCard, ModelFamilyCard).
    • Screenshots of all 51 stories in light and dark: 99 of 102 are pixel-identical. The other three (an animated compaction line and a video preview) differ just as much between two shots of the same commit.
  • The last three commits (Model UI and app components, llama-brand, shared constants) moved code without changing what it does. For the first, the built CSS differs only in Svelte scope hashes, all 49 stories match their DOM, and 92 of 98 screenshots are pixel-identical (the other 6 also differ between two shots of the same commit). The other two rely on CI.
  • Not run: the E2E tests, scripts/ui-assets.cmake, and the Docker and Nix builds.
Demo script
test.use({ settings: { theme: 'system' } });

test('demo', async ({ demo, page }) => {
	const input = page.getByRole('textbox', { name: 'Type a message...' });

	await demo.click(page.locator('button[aria-label="Expand navigation"]'));
	await demo.pause(800);

	await demo.caption('Start two conversations');
	await demo.type(input, 'Name a color.');
	await demo.click(page.getByRole('button', { name: 'Send' }));
	await demo.pause(3000);

	await page.goto('/');
	await demo.type(input, 'Name a planet.');
	await demo.click(page.getByRole('button', { name: 'Send' }));
	await demo.pause(3000);

	const row = page.locator('[data-conversation-row]').first();

	await demo.caption('Matte glass surfaces in the light theme');
	await demo.hover(row);
	await demo.pause(600);
	await demo.click(page.getByRole('button', { name: 'More actions' }).first());
	await demo.pause(1200);
	await demo.press('Escape');

	await demo.caption('Chat form and message bubbles');
	await demo.hover(input);
	await demo.pause(1000);

	await demo.caption('Switching to the dark theme');
	await page.emulateMedia({ colorScheme: 'dark' });
	await demo.pause(1500);

	await demo.hover(row);
	await demo.pause(600);
	await demo.click(page.getByRole('button', { name: 'More actions' }).first());
	await demo.pause(1200);
	await demo.press('Escape');

	await demo.caption('The same surfaces in the dark theme');
	await demo.hover(input);
	await demo.pause(1500);
});

Requirements

@allozaur
allozaur added this pull request to stack #30 October 31, 2026 16:46
@allozaur
allozaur removed this pull request from stack #30 October 31, 2026 17:28
@allozaur
allozaur added this pull request to stack #33 October 31, 2026 17:29
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from 97e1edd to e24a39d Compare November 2, 2026 13:37
@allozaur
allozaur force-pushed the allozaur/feat/sidebar-sections branch from cd054b7 to 2fe53cb Compare November 2, 2026 13:37
@allozaur
allozaur removed this pull request from stack #33 November 2, 2026 13:39
@allozaur
allozaur added this pull request to stack #34 November 2, 2026 13:40
@allozaur
allozaur removed this pull request from stack #34 November 2, 2026 14:31
@allozaur
allozaur added this pull request to stack #37 November 2, 2026 14:32
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from e24a39d to ab65713 Compare November 3, 2026 10:02
@allozaur
allozaur force-pushed the allozaur/feat/sidebar-sections branch from 2fe53cb to 2286d80 Compare November 3, 2026 10:02
@allozaur
allozaur removed this pull request from stack #37 November 3, 2026 10:02
@allozaur
allozaur added this pull request to stack #41 November 3, 2026 10:03
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from ab65713 to 4f55550 Compare November 9, 2026 10:05
@allozaur
allozaur force-pushed the allozaur/feat/sidebar-sections branch from 2286d80 to 441d36f Compare November 9, 2026 10:05
@allozaur
allozaur removed this pull request from stack #41 November 9, 2026 10:06
@allozaur
allozaur added this pull request to stack #42 November 9, 2026 10:06
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from 4f55550 to 3853ab3 Compare November 9, 2026 11:29
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Nov 9, 2026
@allozaur allozaur changed the title ui: matte glass surfaces and three-tier design tokens ui: Llama UI design system: tokens, surfaces, brand and Storybook Nov 9, 2026
@allozaur
allozaur force-pushed the allozaur/feat/sidebar-sections branch from 441d36f to 002e45f Compare November 9, 2026 11:56
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch 2 times, most recently from 3265809 to f11e13f Compare November 9, 2026 12:44
@allozaur
allozaur removed this pull request from stack #42 November 9, 2026 12:45
@allozaur
allozaur changed the base branch from allozaur/feat/sidebar-sections to master November 9, 2026 12:45
@allozaur
allozaur added this pull request to stack #44 November 9, 2026 12:45
@allozaur
allozaur force-pushed the allozaur/feat/model-configuration branch from eb7c0b4 to 03936d0 Compare November 10, 2026 15:00
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from 5325f6f to c979bf7 Compare November 10, 2026 15:01
@allozaur
allozaur force-pushed the allozaur/feat/model-configuration branch from 03936d0 to 18e8a0c Compare November 10, 2026 15:01
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from c979bf7 to d41ca69 Compare November 10, 2026 15:56
@allozaur
allozaur force-pushed the allozaur/feat/model-configuration branch from 18e8a0c to 06d2547 Compare November 10, 2026 15:57
@allozaur
allozaur removed this pull request from stack #50 November 10, 2026 16:22
@allozaur
allozaur force-pushed the allozaur/feat/model-configuration branch from 06d2547 to 9818bed Compare November 10, 2026 16:22
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from d41ca69 to 8da8b1e Compare November 10, 2026 16:22
@allozaur
allozaur added this pull request to stack #51 November 10, 2026 16:23
@allozaur
allozaur removed this pull request from stack #51 November 10, 2026 17:22
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from 8da8b1e to cc1caa6 Compare November 10, 2026 17:23
@allozaur
allozaur force-pushed the allozaur/feat/model-configuration branch from 9818bed to f43fa70 Compare November 10, 2026 17:23
@allozaur
allozaur changed the base branch from allozaur/feat/model-configuration to allozaur/feat/prompt-library November 10, 2026 17:23
@allozaur
allozaur added this pull request to stack #52 November 10, 2026 17:23
@allozaur
allozaur removed this pull request from stack #52 November 10, 2026 18:04
@allozaur
allozaur force-pushed the allozaur/style/glass-surfaces branch from cc1caa6 to 455ed4b Compare November 10, 2026 18:04
@allozaur
allozaur force-pushed the allozaur/feat/prompt-library branch from da46e19 to 2d4c882 Compare November 10, 2026 18:04
@allozaur
allozaur added this pull request to stack #53 November 10, 2026 18:04
@allozaur
allozaur removed this pull request from stack #53 November 12, 2026 01:28
@allozaur
allozaur force-pushed the allozaur/feat/prompt-library branch from 2d4c882 to 12fb4f6 Compare November 12, 2026 01:29
llama-server refuses browser requests whose Origin does not match its own
host unless --cors-origins allows it, and the Vite proxy forwarded the
page's Origin (localhost:5173, or a LAN or Tailscale address). Loading a
model, saving tools and /v1 calls failed with 403 under `vite dev`.

The proxy now calls the server with its own Host and no Origin, WebSocket
upgrades included. Sec-Fetch-Site still passes through, so requests from
other sites stay refused.

Assisted-by: Claude (Opus 5.5 Medium)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

devops documentation Improvements or additions to documentation ggml model nix server/ui

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant