Skip to content

Design language

KADLS — Kovent Design Language System

Status: Locked for foundations and primitives. Domain components evolve with the specs. Version: 0.2 Date: 2026-08-11

The supervisor is at this screen for eight hours. Every rule below exists to survive that.

The design system and a working supervision prototype live in the repository at design/ui/kovent-next-supervision. It is built in Next.js and Tailwind for design velocity; the production UI is web components served by Quinoa, and these tokens are the source of truth for both.

cd design/ui/kovent-next-supervision
pnpm install && pnpm dev
Route Shows
/ The design system — foundations, primitives, domain signatures
/supervision Returns triage register
/supervision/returns/{ref} Return detail — the screen a supervisor works in

Laws

1. Calm carries state

State is expressed by a tinted surface plus a hairline border, never by saturated fills or competing colour. A page with forty findings must not look like an emergency, because a supervisor who sees an emergency on every page stops seeing emergencies.

Applied consistently: a failed validation row is a 40%-opacity critical surface tint, not a red block. An alert is a tinted panel with a hairline, not a banner.

2. Density without noise

Supervisors scan hundreds of rows. Density comes from tight vertical rhythm and restrained borders — not from shrinking type below readability or removing the whitespace that makes columns scannable.

3. Sans for language, mono for identity

Plus Jakarta Sans for all interface text. Geist Mono only for references, identifiers, amounts, ratios, and timestamps — the things a supervisor reads character by character or compares column to column.

Numbers in tables use tabular figures so digits align down a column. Monospace is not the same as tabular, and reaching for mono when tabular was the actual need was the mistake in the first pass at this system.

4. Gold is the accent, not the theme

Gold marks brand, primary action, and current selection. It is not a status colour. Teal is the alternate accent for deployments that need to differentiate, switchable at runtime.

Status has its own scale — success, warning, critical, info — each with a foreground and a surface tint, and each meaning exactly one thing.

5. Light first, dark complete

The default canvas is light: a cool near-white with white surfaces. Dark is a full peer, not a filter — every token has a dark value, and overlays dim with a neutral scrim rather than inverting the foreground.

6. Every figure states its provenance

A number never appears alone. A computed figure is marked platform-derived. A variance shows its comparison period. A validation failure shows the field it binds to and the directive it cites. A risk score shows its drivers.

This is law ten expressed as an interface rule: if the UI shows a conclusion, it must offer the path to its cause.

7. Screens end in a decision

A supervisory screen is not a report. It ends in an action — approve, reject, query, flag, escalate — and the action is visibly gated by the checks that must clear first. A disabled primary action explains why it is disabled.

8. Nothing destructive without a reason

Reject, escalate, and query all require typed justification before they can be confirmed. The reason goes to the audit trail and to the firm. This is law five at the interaction layer.

Foundations

Token group Rule
Radius 0.5rem base. Cards and panels lg, controls md, pills full.
Border Single hairline at 1px. Elevation is a hairline plus a small shadow, never a heavy shadow.
Surfaces background → surface → surface-2 → elevated. Four levels, no more.
Spacing 4px base scale. Table rows at py-2.5, panels at p-4.
Status success warning critical info, each with -surface and -foreground.
Accent gold default, teal alternate, each with -surface, -muted, -foreground.

The exact token values live in design/ui/kovent-next-supervision/app/globals.css, expressed in oklch for perceptually even lightness steps. This documentation site uses the same values, so the docs and the product cannot drift.

Primitives

Built and shown in the design system route: buttons, inputs, selects, checkboxes, radios, switches, cards, badges, avatars, tabs, breadcrumbs, pagination, progress bars, step indicators, alerts, modals, toasts, empty states, and loading skeletons.

Two primitives carry most of the supervisory weight:

The data table. Hairline-separated rows, tabular figures right-aligned, status carried by a coloured dot plus a plain label rather than a pill in every row. Row actions appear on hover and are keyboard reachable.

The panel. A hairline-bordered surface with a title, an optional caption, and a body. Almost every supervisory screen is panels in a grid, which is why the panel's restraint sets the tone for everything.

Domain signatures

Components that exist because the regulatory domain demands them, not because a UI kit had them:

Component What it carries
Lifecycle rail The obligation's state as a dated, attributed chain — prepared, certified, submitted, reviewed, outcome
Field table with variance Reported figure, prior period, movement, and any flag with its citation
Validation panel Pass / advisory / fail per rule, with the field and the directive
Reviewer rail Checklist, blocking explanation, and the gated outcome set
Query thread Regulator and firm turns, bound to a field, with the amendment that answered it
Capital summary Early warning ratio against its floor, with the surplus or deficit
Risk summary Band, score, and named drivers
Version history Every version retained, with the event and actor that produced it

What we rejected

Rejected Why
Bloomberg-terminal aesthetic Density is worth learning from. Black backgrounds, all-caps mono, and amber-on-black are cosplay, and they fail accessibility.
Monospace as the interface font Tried it. It reads as a machine talking, and it makes prose harder to scan. Mono earns its place on identifiers only.
Status pills in every row At two hundred rows the register becomes a colour field. A dot plus a label is quieter and denser.
Saturated alert banners They train users to dismiss. Tinted surfaces with hairlines hold attention without shouting.
Icon-only actions A supervisor's action goes in an audit trail. It gets a word.