the design system was a side project until it wasn't

semantic tokens are the mechanism that makes a design system more than a component library. khaos.machine learned this in one afternoon on April 12–13 2026, when the standalone @khaos/ui package shipped alongside a workspace-wide migration that moved seven consuming applications off hard-coded color values and onto a shared token set. the migration took one afternoon. the token churn it exposed took the following week to stabilize.

what @khaos/ui was before April 12

@khaos/ui had existed inside the khaos-gui pnpm workspace since the early GUI development work. it was a package — a directory under packages/ui/ — that exported shared Vue components. every khaos-gui app imported from it via the workspace symlink. there was no standalone build, no versioned release, no Storybook surface, and no consumer outside the workspace.

this worked because all seven apps lived in the same repo and changed together. the component library was an implementation detail of how the apps shared code, not a product artifact with its own lifecycle.

the design-system extraction changed the premise. 000cfe7 is the founding commit of the khaos-design-system repo — a separate git repository, a pnpm workspace of its own, with @khaos/ui as its primary package and Storybook as the development surface. the package now has its own versioning, its own release CI, and a published artifact that khaos-gui consumes as a dependency rather than a workspace package.

semantic tokens and what they mean in practice

the token set in @khaos/ui distinguishes between primitive tokens and semantic tokens. primitive tokens are raw values: --color-amber-500: #E8A040. semantic tokens assign meaning to those primitives: --color-surface-action: var(--color-amber-500). components consume semantic tokens; they never reference primitive values directly.

the distinction matters when the theme changes or a dark/light variant is introduced. a component that hardcodes background: #E8A040 needs to be updated when the action color changes. a component that uses background: var(--color-surface-action) follows the semantic change automatically. the component is not aware of whether the action color is amber, blue, or conditionally set based on a media query.

prior to the migration, khaos-gui’s apps mixed both patterns. some components used CSS custom properties that had been informally established during initial development — --khaos-amber, --khaos-dark — and some used Tailwind utility classes with explicit color values. neither set was versioned or documented; the names had accumulated through usage rather than through a naming convention.

the migration at 273fee9

273fee9 is the convergence commit on the khaos-gui side. it migrated the workspace to the semantic token set from @khaos/ui v1.0.0. the change touched every app — projects, settings, dashboard, console, character-builder, story-player, and coverage — plus the shared component packages.

the mechanical change was replacement of informal custom properties and hardcoded Tailwind color classes with their semantic token equivalents. --khaos-amber → var(--color-surface-action). bg-gray-900 → class:surface-base. the replacement was not one-to-one in every case because the semantic layer has a richer vocabulary than the informal set it replaced — --color-text-muted covers cases that had previously been expressed as text-gray-400 or text-zinc-500 without a principled distinction between them.

the migration also removed 23 locally-scoped CSS custom property declarations that had been defined in individual app components and never intended for reuse. each one was a candidate for drift: a property defined in the dashboard that happened to have the same name as one in the console but carried a different value for an accidental reason.

the Welcome app and what it surfaces

cf976c6 through 17b5926 cover the Welcome app — khaos.machine’s eighth GUI surface, added in the same April window. the Welcome app is the adaptive help hub: it detects the user’s current setup state and routes them to the relevant onboarding step, documentation reference, or troubleshooting path. it ships inside khaosd’s embedded bundle alongside the other seven apps.

the Welcome app was the first new surface built entirely on top of the migrated token set and the standalone @khaos/ui package, rather than the prior informal system. dc91266 added the readiness checklist — a status panel that checks daemon health, binary versions, API key configuration, and KSPD path validity. 6334c4b handled the auth_invalid state: when khaosd detects that a stored API key has been rejected by a provider, the Welcome app surfaces a targeted recovery action rather than a generic error.

14fc83f and 9fe0455 added the inline-editable project title — a pattern that appears in the projects view and was extracted into @khaos/ui as a reusable component during the Welcome app build. 469c633 and 17b5926 addressed layout polish and token conformance issues surfaced by the Storybook automated visual regression run against the new Welcome app stories.

what convergence costs

the migration itself was one afternoon. the token churn that followed was a week. several semantic names chosen for the initial token set turned out to be overloaded: --color-surface-raised was used in some components to mean “a panel above the base surface” and in others to mean “a button in its hover state.” those two concepts need distinct tokens. the renaming passes — --color-surface-raised → --color-surface-panel + --color-interactive-hover — landed across three separate PRs in the week after April 13.

this is the standard cost of a token naming exercise: you cannot discover overloading until components are consuming the tokens at scale. a Storybook story for a single button does not reveal that --color-surface-raised means two things. seven apps consuming the same token set in different contexts does.

the benefit is visible in the subsequent review cycles. a color change to the action surface — a single token value edit — propagates across all seven apps without a per-app PR. a new app consuming @khaos/ui starts with a correctly-colored interface by default because the semantic token set encodes the design intent, not the raw values. the reviewer who approved 273fee9 spent their time on structural correctness, not on checking whether a particular button matched a Figma frame.

seven apps, one component library, one token set, one Storybook. the design system is no longer a side project.