The Aback design system

One library, vendored rather than installed

Every Aback product renders the same components. The kit does not ship a forked design system: it carries the Aback UI source at a pinned commit under src/vendor/aback-ui, and imports it through a single entry point.

The source is vendored instead of installed because the kit is sold as source code. A buyer must be able to read, debug and change the components without access to a private registry, and a library upgrade must show up as a reviewable diff rather than an opaque version bump.

/components renders the live library, grouped by job, so you can see exactly what the archive contains before you write a line of code.

• src/vendor/aback-ui/components: the component source.
• src/vendor/aback-ui/tokens.css: the colour roles, the Aback Blue ramp, the type stack and the square geometry.
• src/vendor/aback-ui/SOURCE.md: the pinned commit and the component count.
• src/app/globals.css: imports the tokens and adds only the chrome the library does not own.

Import from the entry point only

Importing a component file directly bypasses the barrel, which makes a future rename a repository-wide edit. The barrel is the only public surface.

import { Button, Card, Field, Input } from "@/vendor/aback-ui";

export function Example() {
  return (
    <Card className="p-6">
      <Field htmlFor="name" label="Project name">
        <Input id="name" />
      </Field>
      <Button>Create project</Button>
    </Card>
  );
}

Updating the snapshot

The aback-ui repository is the source of truth. Change a component there, then refresh the snapshot here. Both commands are executable as written from the repository root.

1. 1Refreshbun run ui:sync copies the components, the tokens and the license from the aback-ui checkout named by ABACK_UI_PATH, or from ../aback-ui by default.
2. 2ReviewThe generated files carry a header and the staged diff is the actual library change. Read it before you commit.
3. 3Verifybun run ui:check fails when the snapshot and the source disagree. It skips with a notice when no aback-ui checkout is present, so a clean clone still passes.

bun run ui:sync
bun run ui:check

Changing a component

If you own the aback-ui checkout, change the component there so every product inherits the fix. If you are working from the archive alone, treat src/vendor/aback-ui as your own source and stop running ui:sync; the kit is yours to fork.

Either way, do not add a second primitive beside the library. A page that needs a variant should compose the existing component, not copy its classes into the page.

src/components/ui now holds only composition: a native select for form submission, native toggles, the labelled input and select shells, and the mobile sheet wrapper. There is no second button, card, badge, input, alert, separator, progress or table. The library dialog, tabs and accordion replaced the local copies, so there is exactly one implementation of each.

Tokens before utility values

Colour, radius, spacing and type decisions belong to DESIGN.md and the shared tokens. A hard coded hex value or a one-off radius is a bug even when it looks right on one screen.

• --primary is the neutral ink fill. Aback Blue is a brand accent, not the default button colour.
• --border is the hairline on cards and controls. --separator is page chrome. --input is a form outline.
• Every radius resolves to zero. Rounded corners are not a local design choice.
• Dark mode is the dark class on the html element, never a media query alone.

What the library does not include

The library is components and tokens, not a theme editor, a page builder or a charting package. The kit adds the application specific compositions it needs on top, and documents each one rather than hiding it in a page.