// case study 01

Soar: a design system that themes an open-source library instead of forking it

Most teams that adopt a component library end up forking it to match their brand, then fall behind on every upstream release. Soar shows the alternative: own the look and the larger patterns, inherit everything else, and let tooling enforce the line between the two.

Role
Architect and engineer
Type
Design system proposal, fictional brand
Base library
Web Awesome 3 (Web Components)
Stack
Lit, TypeScript, Storybook, axe-core, Changesets, Turborepo

The problem

A design system team usually faces a bad choice. Build every component from scratch, which is slow and hard to make accessible, or fork an existing library and restyle it, which works until the next upstream release. After a few versions the fork drifts, accessibility fixes stop flowing in, and upgrades become projects.

The same tension shows up in day-to-day work: designers change values in Figma, engineers hand-edit CSS to match, and nobody can say which of the two is right.

Three rules

  1. Figma is the only source of visual values. No hand-written hex codes, pixel or rem values anywhere in the system.
  2. Web Awesome is never forked or patched. Soar restyles it only through its own --wa-* custom properties, and uses a ::part() rule only where no property exists.
  3. Every value has exactly one writer, so a Figma sync and a Web Awesome upgrade can't silently overwrite each other.

Each rule is enforced by a script, not a style guide. npm run check:ownership fails the build when someone breaks one.

How it fits together

Pipeline from Figma to apps
Figma variables
  └─ normalize ──▶ --ax-* tokens (light, dark, base)
       └─ alias map ──▶ --wa-* = var(--ax-*)   (the ownership contract)
            └─ theme CSS in cascade layers + ::part() fixes

Web Awesome atoms   used as-is, never forked
Soar molecules      ax-field, control-info      (Lit)
Soar organisms      ax-data-table               (Lit)

ship ──▶ npm tarball  +  single-file CDN bundle with SRI hashes

Tokens. Figma variables are pulled into a JSON export and normalized into a flat token list. Names become CSS variables, modes become light, dark or base, unitless Figma numbers get units by name and scope, and aliases stay as var() chains so the lineage is visible.

The alias map is the contract. It lists each Web Awesome property Soar owns and the Figma variable that drives it. Anything not in the map is explicitly inherited. CI fails on any hand edit to generated CSS.

Components. Atoms come straight from Web Awesome. Soar adds molecules and organisms in Lit, the same library Web Awesome uses, on a shared base class: a validated field, a control-info pattern and a filterable, selectable data table.

Quality gates

Every pull request runs a component audit across all 27 components. Each one is checked for:

  • token use, with no raw values in component CSS
  • Web Awesome dependencies and drift from the upstream snapshot
  • accessibility, with axe running against every story in a real Chrome browser
  • documented exceptions, docs and unit tests

The results render as a page inside Storybook, so designers and product owners see the same report engineers do.

Upgrades are safe by design. A snapshot of the installed Web Awesome is checked in CI, and npm run upstream:bump shows exactly which owned and inherited values change before anyone merges an upgrade.

Accessibility

Building on Web Awesome means keyboard support, focus handling and ARIA roles come from a library that is already tested for them, and Soar inherits every upstream fix instead of maintaining its own copy.

The components Soar does own are held to the same bar: axe runs on every story in a real browser, not jsdom, because shadow DOM behaves differently there. A failing check blocks the pull request.

One build, any framework

Soar ships as an npm package and a single minified CDN bundle with Lit inlined and Web Awesome loaded separately. Working samples cover Angular, React, Vue and plain HTML.

A second Storybook, built in Vue, loads everything from the CDN build exactly as a consuming app would. That catches packaging problems a source-level Storybook never sees.

Versions are managed with Changesets. A staging step assembles the CDN release with integrity hashes, and a guard blocks publishing to any public registry by mistake.

Why it matters

This is the same set of problems I worked on as Design Systems Engineer Lead at TruStage: Web Components shared across products, tokens driven from design, release and versioning standards, and tooling that keeps Figma and code in step. Soar is a public version of that approach that anyone can open, run and read.

The repo includes a full handbook covering every tool, package and workflow, plus coding standards with a review checklist, because a design system is only as good as the next engineer's ability to contribute to it.