Contributing

The design system is a pnpm workspace. One source of truth for class names, two packages that emit them, plus a docs site that previews both side-by-side.

packages/
  admin-css/      Tailwind v4 source → pre-built CSS + semantic class names.
  admin-react/    React wrappers around Base UI; emit the same class names.
apps/
  docs/           Astro + Starlight; imports admin-css *source* in dev.
skills/
  admin-design-system/   Generated agent skill bundle. See Writing docs.

A change in one package almost always implies a change in the other — see Adding a component.

Local setup

Requires pnpm ≥ 10 and Node ≥ 22. .npmrc pins exact versions — don’t introduce caret ranges.

pnpm install
pnpm dev        # docs at http://localhost:4321, HMR into source CSS + React

pnpm dev watches packages/admin-css/src/** and packages/admin-react/src/** through the docs site. Editing a component’s CSS or React source reloads the docs immediately.

Commands

pnpm build          # admin-css → admin-react → docs (order matters)
pnpm check-types    # tsc on admin-react + astro check on docs
pnpm test           # vitest on admin-react (happy-dom + RTL)
pnpm lint           # oxlint
pnpm format         # oxfmt
pnpm check-docs     # docs links, anchors, and class-name drift
pnpm generate-skill # regenerate skills/ from docs MDX

CI runs lint, format:check, build, check-docs, check-types, test, and verifies skills/ is in sync via git diff --exit-code. Replicate locally before pushing.

Releasing

pnpm release        # interactive: patch / minor / major

release-it computes the next version, cuts ## [Unreleased] into a dated section in CHANGELOG.md with fresh compare links, writes the version into both packages’ package.json, then commits chore(release): v<version> and pushes to main. Both packages share one version and release together.

It does not publish, tag, or cut a GitHub release — .github/workflows/release.yml does, triggered by the change to packages/*/package.json. For each package whose version is ahead of its <name>@<version> tag it re-runs the full check suite, requires a matching ## [version] section in CHANGELOG.md, then publishes with npm publish --provenance and tags. Don’t hand-bump a package.json: it skips the changelog step, and the release job fails on the missing section rather than publishing something undocumented.

Docs deploy is a separate workflow — every push to main publishes apps/docs/dist to GitHub Pages.