Skip to content

ui: a Storybook for Llama UI and Llama Chat - #67

Draft
allozaur wants to merge 22 commits into
masterfrom
allozaur/docs/llama-ui-storybook
Draft

allozaur wants to merge 22 commits into
masterfrom
allozaur/docs/llama-ui-storybook

Conversation

@allozaur

@allozaur allozaur commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Overview

Llama UI and Llama Chat get Storybooks with two jobs: documentation that people and coding agents read for context, and a test environment in which every story runs as a test. The brand pages live in ggml-org/llama-brand, and Philosophy and Architecture are in #80.

Additional information

flowchart LR
    subgraph code["In the repo, next to the code"]
        D["DESIGN.md"]
        L["Llama UI stories<br/>ui/lib/ui"]
        C["Llama Chat stories and pages<br/>ui/apps/chat"]
    end
    subgraph docs["Documentation, for people and agents"]
        SB["Llama Chat's Storybook<br/>Llama UI and Llama Chat sections"]
        HF["Hugging Face Space<br/>ggml-org/llama-ui-storybook"]
    end
    subgraph tests["Testing, in CI"]
        LT["Library checks<br/>npm test"]
        CT["E2E Tests<br/>story tests"]
    end
    D --> SB
    L --> SB
    C --> SB
    SB -->|"on master"| HF
    L --> LT
    C --> CT
Loading
  • Documentation: every Llama UI part and Llama Chat component in its states, with an introduction and the design guidelines agents follow (from DESIGN.md). It's published to a Hugging Face Space on every UI change on master.
  • Testing: each story is a test, run in Chromium: the library's in its npm test, now in CI, and Llama Chat's in its story tests.

Part 1 of the fork's stack, on master. Its first commit, the fork-only dev-proxy commit, stays off upstream: ggml-org#32485 has the same tree without it, in six commits. The deploy needs HF_TOKEN_UI_STATIC_OUTPUT to have write access to the Space.

What changed
  • Two sections, one per layer:
    • Llama UI (ui/lib/ui/tests/stories): Foundations, Components (the 29 base components as Actions, Forms, Display, Overlays and Navigation), App components (ActionIcon, SearchInput, SyntaxHighlightedCode), Models and Mockups.
    • Llama Chat (ui/apps/chat/tests/stories): its own Foundations (Safe areas, Brand), then one folder per src/lib/components/app/<area>, with each accessibility story next to its component's.
  • Each story with its code: every library story lives with the library and imports it by its published names (@ggml-org/llama-ui/..., aliased onto src/lib). It runs in the library's npm test and is covered by its type check. Llama Chat's Storybook includes these stories as they are, and its own story tests leave them to the library. Llama Chat's Tailwind also scans the library's stories, so the classes only they use (the Elevation samples, for one) are generated. The 13 stories that were kept twice, once in each package, are now kept once. ActionIcon's and SearchInput's stories keep the library's parts, and Chat's ActionIconCopyToClipboard and HighlightedMatch get their own stories.
  • Old links: links to the former UI section redirect to the new places, and AGENTS.md says where a new story goes.
  • CI: the Library checks job now runs the library's tests, its stories among them.
  • Pages: the introduction and Agents › Design guidelines. The flat pages this Storybook had (chat message, chat form, markdown content, the PWA refresh alert and their fixtures) go, because the new sections cover them.
  • Moved to llama-brand: Brand (logo, type, colours), Communications, BRAND.md and the scripts that render llama-brand's README art. The brand parts the remaining pages draw with stay: the logo geometry, the fonts and the splash screens. Their logo files come from @ggml-org/llama-brand instead of copies.
  • Philosophy and Architecture, in ui: Philosophy and Architecture sections for the Storybook #80: Ideology, Product and Design, with the communications pieces only their figures used, and Architecture (Stack, Chat, Extensions, Channels). Architecture describes parts that come in later PRs, so the stack's edits to it (ui: run Llama Chat with npx @ggml-org/llama-chat #69's npx note, ui: move the agentic loop into @ggml-org/llama-harness, in ui/lib/harness #55's ui/ paths, ui: make MCP a built-in extension, on MCP SDK v2 #61's Extensions page, and the Architecture parts of ui: prompt library, a System message submenu and a Library page #29 and ui: navigate through resolve() with typed route ids #73) went there too. The Introduction was set in Philosophy's frame, so Editorial, its chapter list and Figure move to editorial/ and the products figure moves to introduction/. Nothing in this PR points to Philosophy or Architecture any more.
  • No Scrapbook: the proposals pages (Composer keys, Simple and powerful, ChatForm single row and llama.app's in the library) and the ChatForm single-row fixture are gone. The sidebar, the introductions, AGENTS.md, DESIGN.md and the library's README no longer mention them.
  • Color modes by name: the color scheme helper, the mode decorator and the surface toolbar take mode-watcher's storage key, the ColorMode and SurfaceTheme enums, MEDIA_QUERIES.PREFERS_DARK and applySurfaceTheme instead of string literals.
  • Dependencies: the library's Storybook addons take version ranges instead of latest.
  • Deploy: a new UI Storybook workflow builds ui/apps/chat's Storybook whenever ui/apps/chat or ui/lib/ui changes on master, and on demand. It uploads the build to the static Space ggml-org/llama-ui-storybook and removes files the new build no longer has. It runs only in ggml-org/llama.cpp and uses the UI's Hugging Face token (HF_TOKEN_UI_STATIC_OUTPUT), which needs write access to that Space.
  • Floating panels' edge: menus, popovers, dialogs and the other matte-float panels drew their inner highlight as an inset shadow inside a transparent 1px border, so the fill between it and the outer ring showed as a second edge. The border now draws the highlight, right inside the ring, and the edge is one line.
  • One story fix: the ChatScreen story waits for its reply to be stored before the next story resets the stores.
Known gaps
  • npm run check in ui/apps/chat passes as CI runs it, with only Chat's dependencies installed. If ui/lib/ui/node_modules is also installed, it reports errors from a second copy of Svelte (5.57.2 in the library, 5.57.3 in Chat). That also happens on master.
  • Coverage still to come in follow-ups:
    • Foundations pages for motion, iconography and z-order. The tokens for motion and layering don't exist yet.
    • A toast, which is used but has no story or styling of its own.
    • Stories for most of Llama Chat's dialogs and shared menus, and for four Model UI components.
Testing
  • ui/apps/chat, with only its own dependencies installed as in CI: the type check and lint pass, and so do its 166 story tests. npm run build-storybook builds with the library's stories in it (218 entries), and old story links redirect (all 205 old IDs checked).
  • ui/lib/ui: the type check (stories included), prepack and its 63 tests (the story tests among them) pass, and its Storybook builds.

Requirements

@allozaur
allozaur added this pull request to stack #68 November 16, 2026 13:45
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch from 1e11686 to e53c531 Compare November 16, 2026 13:52
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Nov 16, 2026
@allozaur
allozaur removed this pull request from stack #68 November 16, 2026 16:12
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch from e53c531 to 33cdd56 Compare November 16, 2026 16:12
@allozaur
allozaur added this pull request to stack #71 November 16, 2026 16:13
@allozaur
allozaur removed this pull request from stack #71 November 16, 2026 16:49
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch from 33cdd56 to 7388192 Compare November 16, 2026 16:50
@allozaur
allozaur added this pull request to stack #72 November 16, 2026 16:50
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch 2 times, most recently from e36eafc to 469bb99 Compare November 16, 2026 18:58
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch 2 times, most recently from d2a9da1 to d3611b1 Compare November 17, 2026 05:55
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch from d3611b1 to fe20107 Compare November 17, 2026 10:31
@allozaur
allozaur removed this pull request from stack #72 November 17, 2026 11:15
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch from fe20107 to 2e54d38 Compare November 17, 2026 11:15
@allozaur
allozaur added this pull request to stack #76 November 17, 2026 11:16
…ma-ui

As Llama Chat does since it moved onto the library: the pages import the
base components as @ggml-org/llama-ui/ui/<name>, and the design system export
reads the tokens from ui/lib/ui.

Assisted-by: Claude (Opus 5.5 Medium)
…/apps/chat

The move to ui/ rewrote every tools/ui in these pages to ui/apps/chat, which
put the library there too, and Architecture > Stack still drew the ui/
folder as a proposal. The Stack, Introduction and Product pages and the
Design guidelines now say where each part lives, and the library's own
Storybook introduction says that Llama Chat is built on the package.

Assisted-by: Claude (Opus 5.5 Medium)
The design system commit was squashed from allozaur/docs/storybook-overhaul
at 4bddabf. This adds what that branch gained since (up to a83b110),
in the ui/ folders, so there is one Storybook to work on:

- Brand: a Lockup page for Llama and llama.cpp with their clear space and
  smallest size, Llama Sans and Llama Mono on their own Typography pages,
  Llama Mono's glyph grid, and the brand's repository named
  ggml-org/llama-brand
- Fonts: Llama Sans and Llama Mono from llama-brand's latest, with optical
  sizes from 10 to 36; they live in ui/lib/ui
- Communications: the Virtual models post, and brand files that download as
  files, also through a CDN redirect
- Architecture: Llama Harness as its own package, Llama Connect by name with
  its two figures in Channels, brand.llama.app next to ui.llama.app
- Scrapbook: five key visual proposals after four reference sets
- Bash code blocks mark shell commands and flags
- export:brand-readme, which exports the logo, font and palette pieces for
  llama-brand's README

Assisted-by: Claude (Opus 5.5 Medium)
The brand pages named the app "the web UI" where they meant Llama Chat:
the asset grid, a communications board, the Llama Mono interface sample and
the logo usage notes. Descriptions of what it is (the built-in web UI, the
legacy web UI it replaces) and sample chat text stay as they are.

Assisted-by: Claude (Opus 5.5 Medium)
The brand (logo, type and colours), Communications (direction, foundations,
elements, modules, key visuals and applications, the store pages and their
scenes), the brand book BRAND.md as Agents > Brand guidelines, the key visual
proposals in the Scrapbook, and the scripts that render llama-brand's README
art and export the design system for Claude, now live in
ggml-org/llama-brand, next to the files they draw, with their own Storybook.

This Storybook keeps Llama UI and Llama Chat: the introduction, the design
guidelines, the philosophy, the architecture, the UI and the UI scrapbook.
The brand parts the remaining pages draw with (the post frames, the logo
geometry, the fonts and the splash screens) stay. Links to the moved pages
are no longer redirected here, and the .svx type declaration moves to the
stories' root, out of the logo showcase that held it.

Assisted-by: Claude (Opus 5.5 Medium)
The ContinueConversation story ended while its reply was still being stored,
and the next story reset the stores under it. It now waits for the reply to
finish.

Assisted-by: Claude (Fable 5.2)
…elling them out

The Storybook's color scheme helper, its mode decorator and its surface
toolbar compared string literals: the mode-watcher storage key, 'dark',
'light', 'system', 'paper', 'matte' and the dark media query. They take
mode-watcher's modeStorageKey, the ColorMode and SurfaceTheme enums,
MEDIA_QUERIES.PREFERS_DARK and applySurfaceTheme from the app instead.

Assisted-by: Claude (Opus 5.5 Medium)
Six ways to set the add key and the model selector apart from the white chat
form in light: a darker fill, a tighter shadow, a hairline edge or a flat
shade. C, the tighter shadow, was chosen and is --elevation-key; the others
stay as the record.

Assisted-by: Claude (Opus 5.5 Medium)
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch from 430f34b to a5c8ac4 Compare November 17, 2026 13:44
@allozaur
allozaur removed this pull request from stack #76 November 17, 2026 13:44
@allozaur
allozaur changed the base branch from allozaur/style/glass-surfaces to master November 17, 2026 13:44
@allozaur
allozaur added this pull request to stack #78 November 17, 2026 13:44
…to llama-brand

AGENTS.md still filed proposals under Scrapbook › Brand and Communications
and pointed to LogoShowcase, DESIGN.md had a proposals folder and a
Design system › Foundations path that no longer exist, and the library's
Introduction and Scrapbook still listed the brand sections. Proposals now go
to Scrapbook › UI here and to llama-brand's Scrapbook for the brand, and a
chosen proposal stays as a record, as Scrapbook › About says.

Assisted-by: Claude (Opus 5.5 Medium)
@allozaur
allozaur removed this pull request from stack #78 November 17, 2026 16:25
…book's sections

Safe areas and GlassKey were titled Design system/..., which made a second
top-level section next to UI, and ChatForm single row sat at the Scrapbook's
root. They are now UI › Foundations › Safe areas (after Surfaces),
UI › Patterns › GlassKey and Scrapbook › UI › ChatForm single row, whose
file moves into scrapbook/.

Assisted-by: Claude (Opus 5.5 Medium)
@allozaur
allozaur added this pull request to stack #79 November 17, 2026 16:26
Twelve logo SVGs under brand/assets/files were byte-for-byte copies of
@ggml-org/llama-brand's, which Llama Chat already depends on; the stories
import them from the package now. The download rule in Storybook's config
and modern-screenshot went with the brand pages that used them: no story
offers a file to download or takes a screenshot any more.

Assisted-by: Claude (Opus 5.5 Medium)
@chromatic-com/storybook and @storybook/addon-svelte-csf were "latest",
so a fresh install could take a new major. They now take a caret range
from the versions in the lock, like the library's other dependencies.

Assisted-by: Claude (Opus 5.5 Medium)
The Scrapbook's proposals (Composer keys, Simple and powerful, ChatForm
single row and llama.app's in the library) leave both Storybooks, with
the ChatForm single row fixture only they used. The sidebar order, the
introductions, the sections figure, the uses figure, the library's README
and AGENTS.md no longer point to it, and DESIGN.md drops the proposals
section that filed changes there.

Assisted-by: Claude (Opus 5.5 Medium)
Philosophy (Ideology, Product, Design and their figures) goes to its own
PR. The pages that stay were set in its frame, so the Editorial, its
chapter list and Figure move to editorial/ in both Storybooks, and the
products figure the Introduction draws moves into introduction/. The
communications pieces only Philosophy's figures drew with go with it.

The sidebar order, the sections figure (which now lists Architecture),
the Introduction, the Design guidelines, AGENTS.md, DESIGN.md and the
redirects for old Philosophy links no longer point to it.

Assisted-by: Claude (Opus 5.5 Medium)
A new UI Storybook workflow builds ui/apps/chat's Storybook whenever
ui/apps/chat or ui/lib/ui changes on master (or on demand) and uploads it
to the static Space ggml-org/Llama-UI-storybook, with a Space card naming
the commit it was built from. Files the new build no longer has are
removed; the Space's .gitattributes stays. It runs only in
ggml-org/llama.cpp, takes the UI's Hugging Face token
(HF_TOKEN_UI_STATIC_OUTPUT), and the Space can be changed with the
HF_SPACE_UI_STORYBOOK variable.

Assisted-by: Claude (Opus 5.5 Medium)
Architecture (Stack, Chat, Channels) describes products, packages and
release channels that are not built yet when this Storybook lands, so it
goes to the PR that holds Philosophy. The sidebar order, the sections
figure, AGENTS.md and the library's Introduction (which still named
Philosophy too) no longer point to either.

Assisted-by: Claude (Opus 5.5 Medium)
…tory with its code

The sidebar's UI section held the library's foundations and components and
the app's blocks together, its Patterns were single components of either,
and 13 of the library's stories were kept twice, once in each package. It
now has two sections, one per layer:

- Llama UI (ui/lib/ui/tests/stories): Foundations, Components (the 29 base
  components as Actions, Forms, Display, Overlays and Navigation), App
  components (ActionIcon, SearchInput, SyntaxHighlightedCode), Models and
  Mockups. Every library story lives with the library, imports it by its
  published names (@ggml-org/llama-ui/..., aliased onto src/lib) and runs
  as the library's tests; its type check now covers them too.
- Llama Chat (ui/apps/chat/tests/stories): Foundations (Safe areas, Brand),
  then one folder per src/lib/components/app/<area>, each accessibility
  story next to its component's.

Llama Chat's Storybook shows the library's stories as they are (only this
app's packages are installed beside them, so Storybook resolves from here)
and its story tests leave them to the library. ActionIcon's and
SearchInput's stories keep the library's parts; Chat's own
ActionIconCopyToClipboard and HighlightedMatch get stories of their own.
Old links to the UI section redirect to the new places, and AGENTS.md says
where a new story goes.

Assisted-by: Claude (Opus 5.5 Medium)
The Library checks job type-checked and packed ui/lib/ui but never ran its
tests, so the library's stories, which now hold every library component's,
went untested in CI. It installs Chromium and runs `npm test`.

Assisted-by: Claude (Opus 5.5 Medium)
Menus, popovers, dialogs and the other matte-float panels carry a 1px border that the
surface made transparent, and drew their inner highlight as an inset shadow. An inset
shadow sits inside the border, so the 1px of fill between it and the outer ring showed
as a second edge. The border now draws the highlight, right inside the ring.

Assisted-by: Claude (Opus 5.5 Medium)
@allozaur
allozaur force-pushed the allozaur/docs/llama-ui-storybook branch from 0be135e to 2858836 Compare November 17, 2026 22:35

This branch has not been deployed

No deployments
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 server/ui

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant