@acmelabs/design-system

The house design system as web components. Geist foundations and every Geist component at Geist's values, set in Google Sans Flex and Google Sans Code, plus the house parts the Vercel dashboard adds. Built with Lit, one directory per element, shadow DOM with a shared global stylesheet.

Docs: https://acmelabs-15.github.io/design-system/

Use it from a CDN

No build step. Two tags:

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Google+Sans+Flex:[email protected]&family=Google+Sans+Code:[email protected]&display=swap">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@acmelabs/[email protected]/tokens.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@acmelabs/[email protected]/dist/bundle/design-system.min.js"></script>

<acme-button variant="primary">Deploy</acme-button>
<acme-badge hue="green" subtle>Ready</acme-badge>

A host that admits a script from a CDN but no stylesheet from one (the Claude artifact CSP is one) takes the standalone bundle, which installs tokens.css into the document on import:

<script type="module" src="https://cdn.jsdelivr.net/npm/@acmelabs/[email protected]/dist/bundle/design-system.standalone.min.js"></script>

tokens.css is the global layer: the color scales, the semantic tokens, the reset, the type classes and the layout utilities. The bundle is self-contained (Lit and the labs packages are inside it) and registers every acme-* element. dashboard.css carries the page-level recipes the Vercel dashboard composes in light DOM.

Install from npm

bun add @acmelabs/design-system

import "@acmelabs/design-system"; // every element registers on import
import "@acmelabs/design-system/tokens.css";

The unbundled build under dist/ keeps Lit as a dependency, so one copy of Lit serves the whole app. Single elements import from @acmelabs/design-system/dist/components/<name>/<name>.js.

Layout

src/
  base.ts                       AcmeElement, the shared shadow reset, the icon glyphs
  index.ts                      re-exports every element
  shared/                       helpers used by several elements; element-less style families
  components/<name>/
    <name>.ts                   the element
    <name>.styles.ts            its Lit css`` module (generated from the audited sheet)
    __tests__/<name>.test.ts    bun:test with happy-dom
docs-src/                       the docs site: a Lit app on @lit-labs/router, one fragment per page
docs/                           the built site (GitHub Pages serves it)
scripts/                        split-css, build, dev server

Scripts

| Command | What it does | |---|---| | bun run build | Transpiles src/ with the Lit template compiler into dist/, then bundles dist/bundle/design-system(.min).js | | bun run docs | Builds the docs site into docs/ | | bun run dev | Rebuilds on change and serves the docs at http://localhost:4180 | | bun test | Unit tests plus a render test of every docs page | | bun run lint | Biome | | bun run split | Regenerates tokens.css and the style modules from the audited house sheet |

Release

Publishing runs in GitHub Actions through npm's Trusted Publisher (OpenID Connect), workflow publish-package.yml, environment publish-package; no npm token anywhere.

npm version patch        # bumps package.json and tags v0.1.x
git push --follow-tags   # the tag starts the publish

Conventions

• Every element is acme-*. Properties reflect from attributes; array and object values take JSON in the attribute. Events are acme-change, acme-select, acme-toggle and so on, and they bubble and are composed.
• Values come from vercel.com/geist. Where Geist has the component, Geist's value is the value.
• The type families never change: Google Sans Flex for text, Google Sans Code for numbers, labels and code.
• Labs packages in use: @lit-labs/signals (shared theme and toast state), @lit-labs/motion (collapse), @lit-labs/virtualizer (tables past a few hundred rows), @lit-labs/router (the docs app), @lit-labs/compiler (build-time template compilation). @lit-labs/testing is not used: the package does not support SSR.