AkurAI-Framework / site/content/docs/design-system.md

Latest change 7e151d05ebb2cc20f1fd7b8b22d5d4a016bb8f7d - docs(design-system): extensive component catalog + foundations; deploy.sh live-changelog sync by Ólafur Búi Ólafsson

# Design system

The AkurAI design system is the set of UI primitives the framework ships so that
any app built on it — and the built-in admin — looks coherent without a single
line of bespoke CSS. It is **no-build, like the rest of the framework**: plain
semantic HTML classes, design tokens as CSS custom properties, and (soon) an
atomic CSS engine in `crates/css` that emits only the classes a project actually
uses. No Tailwind dependency, no PostCSS, no bundler — the same win-by-subtraction
philosophy as the runtime.

This section is the **specification** for that system. It documents the
components we want to create, what each must do, and how we tell when one is
done. Treat it the way the crate map in `AGENTS.md` is treated: the source of
truth, updated in the same commit as the work.

## How it works

- **Tokens, not literals.** Colour, radius, type, spacing, motion, and elevation
  live as CSS custom properties on `:root`. Components reference tokens; they
  never hard-code a value. Change a token, reload, everything updates — and a
  theme (or a per-tenant brand) is just an alternate token set. See
  [Foundations](/docs/design-system/foundations).
- **Semantic classes.** A component is `block` + modifiers, written as separate
  classes to match the existing CSS — `btn btn-primary`, `alert alert-danger`,
  `badge badge-ok`. The planned atomic engine generates these from source scans
  and ships only what's used.
- **Native first.** Interactivity uses platform elements before script:
  `<details>` for disclosure and menus, `<dialog>` for modals, `:focus-within`
  and `:focus-visible` for state, real `<button>`/`<label>`/`<table>` for
  semantics. JavaScript is an enhancement, never the only path.
- **Accessibility is a requirement, not a pass.** Every component lists its a11y
  contract (labels, roles, keyboard, focus management). A component is not done
  until that contract holds under keyboard-only and screen-reader use.

## The two pages

- **[Foundations](/docs/design-system/foundations)** — the design tokens:
  colour, typography, spacing, radius, elevation, motion, z-index, breakpoints,
  and theming. Everything else is built on these.
- **[Component catalog](/docs/design-system/components)** — every component,
  grouped by job (actions, forms, data display, feedback, navigation, overlays,
  layout, and the admin shell), each with variants, states, markup,
  accessibility, and the tokens it consumes.

## Status model

Components and tokens carry one of three marks, kept current in the catalog:

- **✅ shipped** — implemented, all states reachable, a11y verified, on the live
  `/components` page.
- **🟡 partial** — exists but incomplete (missing states, not yet tokenised, or
  no a11y pass).
- **⬜ planned** — specified here, not yet built. The bulk of the catalog: this
  is the work ahead.

Where things stand today: a hand-written CSS layer already ships buttons, form
controls, cards, alerts, badges, tables, and disclosure, plus the layout
primitives behind this very site (nav, hero, features, stats, split, sidebar,
prose). The catalog promotes those to a documented, tokenised system and lays out
the full target set — including the toasts, overlays, navigation, and admin shell
that turn the framework into a complete PocketBase-style product.

## Relationship to the roadmap

This system is roadmap step 9 (`CSS engine + frontend + admin UI`). The catalog
is what step 9 builds against: the `crates/css` engine produces the classes, the
frontend layer assembles primitives into the admin shell, and each component's
spec here is its acceptance check. Building the design system before (or
alongside) the auto-API means the day the API generates routes, there is already
a UI ready to render them.