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.

• 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 — the design tokens:

colour, typography, spacing, radius, elevation, motion, z-index, breakpoints, and theming. Everything else is built on these.

• Component catalog — 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.