For developers

Clone the repository, install the dependencies and start the development server. The documentation then opens at http://localhost:3000, where you can look at every component and value in the browser.

git clone <repository-url>
cd design-system-use-case
npm install
npm run dev

Import the component from its folder. The project uses @/* as a short way to write src/*. Each component has a documentation page that shows its states, its code and how it should be used with assistive technology, and the component overview is the best place to start.

import { Button } from "@/components/buttons/Button";
import { Card, CardBody } from "@/components/cards/Card";

export function ProjectActions() {
  return (
    <Card>
      <CardBody>
        <Button variant="primary">Create project</Button>
      </CardBody>
    </Card>
  );
}

Style components with names that describe what a colour is for, such as --color-content-primary for text, and never write a raw colour code. Then the look of the whole system can change without touching any component, and dark mode works without extra styling. A value that already has a name must not be copied anywhere else.

/* Use the named colours (roles) in styles, not raw values. */
.component {
  color: var(--color-content-primary);
  background: var(--color-surface-subtle);
  border-color: var(--color-border-default);
}

The Colors page lists the raw colours and the named roles, together with a note on what each one is for.

The grid has 4 columns on a phone, 8 on a tablet and 12 on a desktop. Use layout-container for the page width and the space at the sides, layout-grid for the columns, and the width variables such as max-w-[var(--width-text)] to keep text at a readable line length. The values and the reasons are explained in Layout & grid.

<div className="layout-container">
  <div className="layout-grid">
    <main className="col-span-4 md:col-span-8 lg:col-span-8">...</main>
    <aside className="col-span-4 md:col-span-8 lg:col-span-4">...</aside>
  </div>
</div>

Use a real button for an action and a real link for going to another page, because browsers and screen readers understand them without extra work. Everything must work with a keyboard, in a logical order, with a visible focus outline. Tables use proper table markup, a status is never shown by colour alone, and every button and link is at least 44px so it is easy to hit.

The values are kept in two places that are updated by hand. src/data/tokens.ts describes them for the documentation, and src/app/globals.css holds the values that the components actually use. When a value changes, it must be changed in both places and the matching Figma variable must be checked. Changes are always made in Figma first, so the Figma file stays the most current description of the system.

A new component goes in src/components, in a folder named after the type of component, and it is styled with the named colours and with existing components. It also needs its own documentation page under src/app/components, built with the ComponentPage template, at the right level: atom, molecule, organism or template. Finish by adding a short note in plain words to the version history.