Skip to content
Aback UI

Resources

Contributing

Aback UI is judged on reuse, clarity, accessibility, and maintainability, not on component count. This page is for people working on the library itself.

Repository layout

Everything that ships to npm lives in packages/. The website only consumes it.

  • packages/ui/@aback-ui/uiShips to npmThe canonical component source and the npm package built from it. Every other copy of a component comes from here.
  • packages/tokens/@aback-ui/tokensShips to npmThe theme: colour roles, the Aback Blue ramp, and geometry, as one CSS file.
  • packages/cli/aback-uiShips to npmThe command line. Its build bundles the registry, so the published package carries every component.
  • registry/registry.json and blocks/Stays in the repoWhich items exist, their dependencies and targets, and the block source. A build script turns it into item JSON.
  • website/abackui.comStays in the repoThis site: docs, live examples, block previews, and the hosted copy of the registry. It is never published to npm.

Run it locally

The repository uses Bun workspaces.

terminalbash
bun install
bun run dev            # the website on http://localhost:3000
bun run build:registry # regenerate the registry after changing an item
bun run build:cli      # build the CLI with the registry bundled

Try the CLI from source

After bun run build:cli, run node packages/cli/dist/index.js add button inside any React project to install from your working copy.

Adding a component

  1. Write it in packages/ui/src/components with semantic tokens, a keyboard model, and tests beside it, including an axe check.
  2. Export it from packages/ui/src/index.ts and add an item to registry/registry.json with its npm and registry dependencies.
  3. Add a live example in website/src/examples and its API and accessibility notes in website/src/data/component-docs.ts. A test fails if either is missing.
  4. Run bun run build:registry and commit the generated files.

Open a proposal first for a new component or any public API change. Names, props, CSS variables, and registry identifiers are public contracts once released.

Adding a block

  • Write it in registry/blocks, importing components through @/components/ui/* exactly as an installed copy would.
  • Keep example content out of the block. Its preview goes in website/src/block-previews, with example data labelled as such.
  • A block owns no routing, auth, network calls, or product data. It takes callbacks such as onSubmit and shows what they return.

Before a pull request

terminalbash
bun run check   # typecheck, lint, tests, registry freshness, packed-package tests
bun run build   # packages, registry, CLI, and the website

The packed-package test installs the real npm tarballs into a clean project, renders components from them, and runs aback-ui init and add with the network blocked. If it passes, what you publish works.