Files
llama.cpp/ui/lib/ui
Aleksander Grygier b81aa847c2 ui: slim the design tokens and set all text through type roles (#32615)
* ui: drop component tokens that only alias a semantic token

A component token now exists only for what a component decides itself:
a value no semantic token has, or one that only this component changes
between themes. Components that take a semantic token as it is read it
directly, so 88 of the 118 component tokens go, with no change to what
is drawn.

Also drops semantic tokens that repeat another one (status-* is fill-*,
elevation-tooltip is elevation-surface), the unused info lamp tokens and
14 primitives nothing reads, and adds fg-soft for the label of an option
that is not the picked one (tabs, toggle group).

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add a short summary on top of DESIGN.md

The rules most changes need, in one screen: components, colour, type,
shape, sizes, surfaces, tokens and no arbitrary values. The sections
below keep the detail.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: derive design tokens by rule and drop the alias layers

Semantic tokens are either a pick (a primitive per theme) or a derivation,
mixed from another semantic token by a fixed rule and declared once: hover
fills, status surfaces and lines, dark shadows (--elevation-strength), the
middle of a matte edge, a lamp's rim and glyph.

Primitives keep colours only. shadcn's colour names stay as Tailwind
utilities and no longer exist as variables; neutral semantic utilities that
duplicated them are gone.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: set all text through type roles and move off-scale values onto the scale

Tailwind's text sizes and bracketed sizes become the type roles, with a new
text-caption-sm (10px) for tags and counts. Body and caption roles no longer
set a weight, and line heights are written as Tailwind writes its own, so the
swap from text-sm and text-xs changes no pixel. A unit test keeps old sizes
from coming back.

Arbitrary values with a scale equivalent use it (z-20, max-w-4/5, min-w-32),
and the two easing curves repeated across the app are ease-out-quint and
ease-sheet. DESIGN.md is updated and regenerated.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: bump @ggml-org/llama-ui to 0.5.0

Removed and renamed tokens are breaking for an app that reads them.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add a display type role for the biggest headline

The greeting on a new chat keeps its 30px from md up, now as text-display
instead of a Tailwind size.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: one corner scale, one set of shadows and three more derived tokens

Six corner roles named values Tailwind's rounded-md to rounded-4xl
already have, and components used the Tailwind names nine times out of
ten. The roles are gone; the whole scale is computed from --radius.

Tailwind's shadow sizes were restated next to the elevation tokens and
did not follow the theme, so they were five times fainter in dark. The
five uses take elevation tokens and a unit test keeps both from coming
back.

A button group's seam is the button's own text colour at 25%, the dark
status text is the dark status fill, and the pressed shadow scales with
--elevation-strength like the inset one.

Assisted-by: Claude (Opus 5.5 Medium)
2026-11-20 11:26:26 +01:00
..

@ggml-org/llama-ui

Llama UI, the design system of Llama Chat and the Llama apps, as a package: its tokens, fonts, surfaces and components, for Llama Chat (ui/apps/chat) and llama.pages (llama.app). It lives in llama.cpp at ui/lib/ui, beside the apps built on it in ui/apps.

Use

/* app.css */
@import 'tailwindcss';
@import 'tw-animate-css';
@import '@ggml-org/llama-brand/css/colors.css';
@import '@ggml-org/llama-ui/theme.css';
<script lang="ts">
	import { Badge, Button } from '@ggml-org/llama-ui';
</script>

<Button variant="secondary">View on Hugging Face</Button>
<Badge variant="success">Downloaded</Badge>
  • theme.css: everything: fonts, tokens, surfaces, the Tailwind theme and base styles. It needs Tailwind 4, tw-animate-css (both peer dependencies) and @ggml-org/llama-brand's css/colors.css imported before it.
  • tokens.css: the three tiers of tokens only, also after @ggml-org/llama-brand's css/colors.css. fonts.css: Llama Sans and Llama Mono. surfaces.css: the matte surface utilities.
  • Dark mode is the dark class on <html>; the Matte light surfaces are the theme-matte class.

What's in it

  • Foundations: the primitive, semantic and component tokens, the type roles (text-body, text-label…), corner, icon and control-height roles, the matte surfaces and elevations, Llama Sans and Llama Mono.
  • Components: every base component of Llama Chat: Alert, AlertDialog, Badge, Button, ButtonGroup, Card, Checkbox, Collapsible, ContextMenu, Dialog, Drawer, DropdownMenu, Empty, HoverCard, Input, Label, Popover, RadioGroup, ScrollArea, Select, Separator, Skeleton, Switch, Table, Tabs, Textarea, Toggle, ToggleGroup and Tooltip. Each is also its own entry point (@ggml-org/llama-ui/ui/dialog), with cn and tv at @ggml-org/llama-ui/utils. Then ActionIcon (an icon button with a tooltip), SearchInput (a search field with a clear button), SyntaxHighlightedCode (code as Llama Chat shows it, in highlight.js's GitHub themes; needs mode-watcher) and Logo (the brand mark, llama-brand's icon), at @ggml-org/llama-ui/app/actions, app/forms, app/content and app/misc. FILTER_TRIGGER_CLASS and FILTER_TOGGLE_ITEM_CLASS style a filters bar the way Llama Chat's Models Manager does.
  • App mockups: MacMenu (Llama for Mac's menu) and WindowsTray (Llama for Windows' tray flyout), the native apps' UIs as the brand's communications draw them, with an annotate snippet to pin a page's numbered callouts to their edges.
  • Model UI: how a model is shown in Llama Chat and on llama.app: ModelCard, ModelFamilyCard (a family as llama.app's catalog shows it), ModelId (name, badges, capability, context and size icons), ModelCapabilityIcons (icons or labelled badges), ModelOrgAvatar, ModelMetadataItem, ModelQuantOptions, ModelQuantChip, ModelQuantRow, ModelDraftSidecars, ModelDownloadProgressBar, plus the formatters and minMemoryTierGb and summarizeSizes, at @ggml-org/llama-ui/models. They take model data in and report what the user did out; fetching and downloading stay in the app.

Next: llama.app's model page.

The constants, enums and code helpers the components use are entry points too, for an app that shows the same things: @ggml-org/llama-ui/constants (the shared classes and code-block constants), @ggml-org/llama-ui/enums (ColorMode, TooltipSide, BooleanString) and @ggml-org/llama-ui/code (highlightCode, trimCodePadding). The model data (constants, enums, formatters and types) comes with the Model UI at @ggml-org/llama-ui/models.

How the apps in this repo use it

Llama Chat does not install the package: it compiles these sources as part of its own build, so a change here shows in the app at once and the app keeps no copy of a component or a token. For that to work:

  • Sources under src/lib import each other by relative path, never through $lib, which in an app points at the app's own src/lib.
  • What they import from npm is listed in dependencies or peerDependencies: the app reads that list to resolve those packages from its own node_modules (ui/apps/chat/scripts/llama-ui.js).
  • Stylesheets import no package. An app imports Tailwind, tw-animate-css and @ggml-org/llama-brand's css/colors.css (the brand's colours, under the names the primitives use) itself, before theme.css.
  • A component added with shadcn-svelte (components.json) arrives with $lib imports: make them relative.

Development

  • npm run storybook: the package's Storybook, with a story for everything it holds; the stories run as tests in npm test, and Llama Chat's Storybook (in ui/apps/chat) shows them under Llama UI
  • npm run dev: Storybook and a small SvelteKit check page (src/routes)
  • npm run check: svelte-check
  • npm run prepack: build the library into dist/ and run publint
  • node scripts/npm-version-check.mjs: what the release workflow would make of this folder, against the real registry

Releases

The package is published from here by ui-lib-publish.yml, which runs when a commit reaches master with ui/lib/ui in it. The version in package.json is the release: land a bump together with the change that should ship and the workflow type-checks, builds, lints and publishes that version to npm, with a provenance attestation. A library change that carries no bump publishes nothing and leaves a warning on the run.

  • npm version <patch|minor> --no-git-tag-version and commit: it moves package.json and both version fields of the lockfile together.
  • Below 1.0: a breaking change bumps the minor, a feature bumps the patch.
  • A version with a prerelease suffix (0.5.0-beta.1) publishes under the next tag, so latest stays a stable build.
  • Publishing needs no token in the repo: the job trades its OIDC identity for one, so the only place to look when a publish is refused is the package's trusted-publisher settings on npm. A publisher names a workflow that must already exist under .github/workflows, so it is added after this workflow lands, and it allows staged publishing until npm publish is permitted for it. Provenance is generated without asking, and only on a GitHub-hosted runner: a self-hosted one cannot publish this way.