Buzz design system
The next Buzz web client starts with a living design system. /design is the
visual overview; /design/components contains 55 searchable live examples;
/design/compositions shows product patterns and generated responses.
. ./bin/activate-hermit
pnpm install --frozen-lockfile
pnpm --filter buzz-desktop-next dev
Open http://localhost:1430/design. Use another port when needed:
pnpm --filter buzz-desktop-next dev --port 5188.
Focused component pages
Click a section’s eyebrow link (the category followed by →) in the catalog to open
/design/components/<id> (for example, /design/components/input). Every catalog
entry has a dedicated URL with its title and live example in a small shared Card.
The examples retain their interactions and variants. Component pages have no
playground label, state guide, source disclosure, picker, or extra page actions.
Every component is indented beneath All components in the navigation, like Token table beneath Color. The navigation list scrolls independently so theme and density controls remain available. Use these links to move through the catalog. Direct links and refreshes work with the same SPA fallback as the rest of the site; unknown component IDs have a recovery link. Theme and density preferences are shared.
Logic & grammar
/design/grammar is a BlockUI reference under System. Every topic is displayed
as a flat table of selection rules and usage boundaries, with links to the
verified upstream snapshot. Tables scroll horizontally on narrow screens. Topic links support direct loading and refresh. It covers foundations,
component contracts, applet composition, and generation constraints; the final
topic records differences from Buzz's active token contract and upstream gaps.
Source links require Block access, but the page has no private runtime dependency.
Appearance
The navigation contains independent theme and Normal / Compact controls. Density applies to every page, shared component, composition, and portaled overlay. It is saved locally, restored before mounting, and synchronized across open tabs. An unavailable storage write leaves the current visit usable and displays a retry message. Normal preserves the original dimensions; Compact retains text sizes while reducing spacing and control sizes. The Spacing and Radius pages show the values for the selected density.
Packages and portability
packages/design-tokens: semantic registry, CSS roles, typography, geometry, and motion. Color and type pages render from this source.packages/ui: React components, public behavior primitives, portable CSS, generated-response schema and renderer, and third-party notices.desktop-next: documentation and examples, consuming those packages.
pnpm --filter buzz-desktop-next build creates a self-contained static site in
desktop-next/dist, including local fonts and license notices. Serve at the host
root with an SPA fallback to index.html for /design/* routes. No authentication,
Blockcell, Storybook, private package registry, relay, or Tauri runtime is required.
The Design system GitHub workflow uploads this site as a build artifact; it does
not publish a website or an npm package automatically.
Checks
pnpm --filter buzz-desktop-next check
pnpm --filter buzz-desktop-next test:e2e
The first command checks formatting, typography roles, contrast, token output,
compiled utility mappings, schema bounds, and renderer action safety. The second
builds the production app and exercises it in Chromium. Install the browser once
with pnpm --filter buzz-desktop-next exec playwright install chromium if needed.
See TESTING.md for coverage and screenshot paths.
Read DESIGN.md for visual rules and OPEN_SOURCE.md for the adaptation contract.
The existing desktop and mobile clients are not migrated by this foundation.