A Design System That Compiles

Several products displayed similar data but had separate implementations of their user interfaces. This toolkit provides shared components and conventions, with static checks and documentation to guide both engineers and coding agents using it.

Some code using the toolkit is written with coding agents. Documented rules and automated checks make it easier for both engineers and agents to use the components consistently.

The base colour token table, each token listed with a swatch, its hex value and the CSS custom property it compiles to

Semantic tokens

Components use semantic tokens rather than base colours directly. These include a three-step surface ramp, separate light and dark shadows, and role-based palettes (solid, subtle, surface, outline and plain).

Semantic token tables listing shadow and colour tokens with their light value, dark value and generated CSS variable side by side

Named tokens give components specific values to use. A linter can check references such as surface.subtle, while visual descriptions such as “a slightly lighter grey” cannot be enforced consistently.

Contrast pairs are checked against AA in the preview for both themes. The accent colour was adjusted after its contrast check failed.

The type scale rendered at each step, with the token name and resolved size beside every sample

Chart colours

Charts need categorical series colours, and products may need to customize that palette.

A line chart and a bar chart drawn with the charting package, both taking their series colours from the shared chart token family

Charts use a dedicated chart.* token family for series colours. The chart inherits the active light or dark theme without selecting it directly. Token names are a union type checked at compile time, with a development guard for unknown names. This guard followed a case where an invalid token name caused a palette swatch to render transparent.

Compiling the styles

Panda CSS extracts styles from source at build time. The browser does not need a style engine, and server rendering can use the generated static stylesheet. The tradeoff is that styles must be known at build time.

Panda reads source at build time to find recipe variants. If a variant value is only known at runtime, Panda cannot generate its rule; the class may be present without corresponding CSS.

A virtualised data table with faceted column filters and a selected row highlighted, the kind of runtime-driven variant whose CSS has to be pre-generated

Panda’s staticCss option emits every variant of a recipe. It is a root configuration key and is ignored inside presets, so the library cannot set it for consumers. The package exports the recipe list for consumers to include in their root configuration; it uses the same map internally.

A doctor command checks consumer configuration for missing Panda recipes and undefined palette roles. An audit also found two lint rules that were configured so they could not fail; those rules were corrected.

These tools document and validate the build-time requirements, including which recipes consumers need to configure and which tokens are valid.

Documentation and agent support

Installable guidance documents the toolkit’s tokens, recipes, charting package, Ark UI composition, state attributes, layout and typography.

There are agents as well as skills, each scoped narrowly enough to be useful: one for implementation, one for Playwright-backed visual verification, one for auditing token discipline without a browser, one for checking that the happy path still works, one for performance. Two more skills exist purely for the iteration loop: one that captures screenshots and runs a structured feedback conversation when someone says the UI looks wrong, and one for selecting and annotating elements in a live app to compare variants in place.

A documentation generator produces product, design and preview references from the token data and recipe definitions.

Diagram of the working loop: a change from a person or an agent, caught by static tooling over tokens, recipes and layers, then seen as a visual diff of only the affected stories, feeding back into the next change

Visual tests capture every component story and compare it with a baseline using a small pixel tolerance. The module graph identifies which stories a change affects, limiting baseline updates to those stories. Additional checks detect snapshots for removed stories and prevent tests from running against a stale build.

Static checks validate token and recipe rules; screenshot comparisons identify visual changes that require review.

Interaction with application styles

Panda emits styles into cascade layers: reset, base, tokens, recipes and utilities. Unlayered CSS takes precedence over layered styles regardless of specificity. For example, an unlayered button { font: inherit } rule overrides the font specified by the design system. Applications should place their base styles in a layer as well.

What it costs to ship

The library still ships JavaScript, despite having no runtime style engine. A separate bundle analysis found a charting dependency barrel that added 82.6 kB minified. The package was split into core, primitives and chart tiers, with sideEffects: false to support tree-shaking.

Source · Component preview