// NAVIGATION
CONNECT ON LINKEDIN
BANGALORE, IN

WorkCase study

Datum design systemA design system built like a cockpit

Datum is the system behind this site: one set of decisions that every page, theme and AI part is drawn from. I built it the way I design safety-critical products, so it stays calm when things are normal and gets exact when they are not.

Datum, exploded: the first five layers, each built only from the one below.
Role
Designer and system author
Scope
8 sheets, 53 parts, 2 themes
Platforms
Web, 320 to 1440px
Status
Live, still evolving
Built to WCAG 2.2 AA 0 automated issuesBoth themes testedKeyboard first See how accessibility is built in

System / 00// Overview

One system, eight sheets

My portfolio started as one page and grew into five kinds of page, two themes and more than fifty versions. Each page was built the week I needed it, and each one quietly made its own decisions. I spend my working days on interfaces where a control that moves is a safety issue, and my own site was breaking the rules I design by.

So I wrote it down as one system and called it Datum: in an engineering drawing, the datum is the reference every other measurement is taken from. Dark mode is the flight deck. Light mode is the drafting paper. Same parts, same names, two rooms.

The problem statement

How might one designer keep a growing, motion-rich product consistent, accessible and recognisably his own, without a team to police it?

Borrowed from

Airbus dark cockpitISA-101 control roomsGOV.UK principlesIBM Carbon motionApple semantic colourShopify Polaris voiceNASA standards manual, 1975
Each layer is built only from the ones before it. Access runs through all of them; governance and evolution keep it working over time.

Datum for AI// 8 of 30 parts

AI parts, up close

Datum has thirty parts that keep a person in charge of an AI. Here are eight, in the order a task meets them: set how far it may go, answer its question, check its reasoning, try the batch, stop it, accept its edits, read the receipt, and take over when it cannot go on.

01 // Molecule · AI

Autonomy dial, try it in Intelligence

How far an agent may act on its own, set per task. The riskiest step sets the ceiling, so R3 work always asks first.

Use whenAny agent task that runs more than once.

Neverlet the agent raise its own level.

02 // Molecule · AI

Clarifying question, try it in Intelligence

When two answers would change the result, the agent asks instead of guessing. Each option says what it leads to.

Use whenGaps only the person can close: a preference, a choice between two real records.

Neverguess when two answers change the result.

03 // Organism · AI

Reasoning trace, try it in Intelligence

What was read, compared, assumed and ruled out. Folded by default, and it asks what you know first.

Use whenAnswers someone acts on: a likely cause, a recommendation, a risk call.

Neveropen by default on a decision the person must make.

04 // Organism · AI

Dry-run preview, try it in Intelligence

A batch simulated before it runs: how many records would change, which are skipped and why, and who gets told.

Use whenBulk changes: rescheduling, reassigning, status updates across many records.

Neverrun on more records than were approved.

05 // Molecule · AI

Run control, try it in Intelligence

An agent at work: the step it is on, what comes next, and Stop one keystroke away. Stopping never asks "are you sure?"

Use whenAny agent run longer than a few seconds.

Neverhide Stop while anything is running.

06 // Organism · AI

Suggestion diff, try it in Intelligence

An AI edit as changes, not a rewrite. Each one is numbered and accepted on its own, and removed text is never red.

Use whenAny AI edit to text people own: notes, reports, procedures.

Neverapply a change before it is accepted.

07 // Organism · AI

Action receipt, try it in Intelligence

One action, fully accounted for: each change before and after, who approved it, proof it worked, and Undo.

Use whenBehind every row of the activity log, and wherever someone asks "what exactly did it do?"

Neverreport success without reading the result back.

08 // Molecule · AI

Handoff, try it in Intelligence

When the agent cannot go on safely, it says why, what is done and what is not, and hands over to a named person.

Use whenSources conflict, confidence is low, access is missing, or a person asks.

Nevermake the person repeat what the agent already knows.

Try all 30 AI parts

Each with when to use it, what an agent must give it and what it never does, in Intelligence. Props, states and code are in the open Datum system (opens in a new tab) .

System / 01// Principles

Seven rules, each with a test

Principles are easy to write and easy to ignore. Each of these comes with a check I run before anything ships. If a design fails the test, the design changes, not the principle.

ClarityP1

Lights out when normal

Calm surfaces, generous space, nothing glows unless it needs you. Straight from the A cockpit philosophy where panel lights stay off while systems are normal, so any light that comes on means something..

Test //Blur a screenshot. You should still find one thing to do next.

ComplexityP2

Tame it, don't hide it

Experts need the dense view; newcomers need a way in. Use Showing the essentials first and revealing detail only when someone asks for it. instead of deleting detail.

Test //A newcomer finishes without the detail. An expert reaches any value in two steps.

ConsistencyP3

Same switch, same place

One action, one name, one position, on every screen. Airbus builds its cockpits so pilots move between aircraft types with minimal retraining.

Test //Two screens side by side. Shared controls match exactly.

TrustP4

Never vague about state

Status has words and a shape, not just a colour. Data says how fresh it is. The system never bluffs.

Test //Switch to grayscale. Nothing becomes ambiguous.

AccessibilityP5

Readable in a hurry, by everyone

12px floor, WCAG's minimum contrast ratio for normal text. 1:1 is no contrast at all; black on white is 21:1., keyboard first, in both themes. Built into the tokens, not added later.

Test //Zero automated issues, then a full keyboard walk.

Human controlP6

The system advises, people decide

Anything automated can be stopped, checked or undone. That goes double for AI.

Test //For every automatic action: where's the stop, and where's the undo?

PurposeP7

Everything earns its place

Motion answers an action. Decoration has a job or it goes.

Test //Remove it. If nothing gets worse, it stays out.

When rules collide//

Order is the tiebreaker

The list is ranked. Clarity beats cleverness. Control beats convenience. Access is never traded away.

System / 02// Foundations

The parts everything is built from

Eight foundations, each cut down to the decisions that matter, plus the grammar that ties them together.

02.1 // Design tokens

Named by job, not by colour

Every value has a name that says what it's for. A theme is just a different set of answers to the same names. Three tiers, each only allowed to use the one beneath it, so a raw value can exist in exactly one place.

Primitive // raw value Live

--p-cyan-400 --p-blue-600 --p-amber-400 --p-paper-100

Semantic // what it's for Live

--cyan act here. Night #00D4FF, paper #0057B8 --amber look here, once per screen --void the surface --alarm failed, or can't be undone --ai made by AI, never status

Component // where it's used Live

--btn-bg = --cyan, gradient on paper --btn-glow glow at night, ink shadow on paper --elev-paper-1 to 3 paper depth

Components reference semantic tokens, never hex values. That's what let a second theme slot in without rebuilding a single component.

Each page is a self-contained file, so it embeds a copy of tokens.css. The token audit compares every copy with the source and flags any that drift. One exception is declared: the site header is a sealed block shared by every page. It keeps its own raw values, and the audit counts them on a separate line.

02.2 // Colour

A budget, not a palette

Most of the screen is neutral. Cyan means you can act. Amber means look here. Red is kept for failures and for actions that can't be undone. Violet marks anything made by AI. Each colour is re-chosen per room so it keeps its job, and most of those choices are forced by contrast.

Neutral carries the page. Cyan marks what you can act on. Amber is rationed to one attention point per screen.

How a colour moves between rooms

Action--cyan

Signal cyan on paper is only ✕ 1.6:1. Aero blue reaches ✓ 6.1:1, but fails at night at 2.9:1. Neither works in both rooms, so one name gets two values.

Attention--amber

Bright amber on paper is ✕ 2.5:1. Deepened to signal orange it holds ✓ 5.4:1.

Alarm--alarm

Coral at night 6.6:1, brick on paper 5.9:1. Amber and red sit close in brightness, so they always differ by shape too: triangle for caution, octagon for alarm.

AI--ai

Soft violet at night 8.8:1, deep violet on paper 6.3:1. It always travels with a spark and the word AI, so it never relies on colour alone.

Text--paper

Off-white at night, 17.1:1, not pure white's 20:1. Navy ink on paper, 15.8:1, not black.

Depth

Glow at night becomes a soft ink shadow on paper. Paper has no light source.

Every colour comes with contrast measured in both rooms before it's allowed in.

02.2 // Colour, second cue

Colour is never the only signal

Roughly 1 in 12 men has some form of colour-blindness, and every screen washes out in sunlight. So in Datum, colour adds meaning but never carries it alone. Both panels below show the same six engines, and one needs a check. Switch to the colour-blind view and see which panel still tells you.

A // Colour only
B // Colour, shape and words

In full colour, both panels point to ENG-208.

Every status gets a Showing the same information in more than one way, like colour plus shape, so it still gets through if one channel is missed.: a shape, a heavier border or a word. It's WCAG 2.2 criterion 1.4.1, and the same rule an ANSI/ISA-101, the standard for designing operator screens in industrial control rooms. It keeps screens neutral and saves colour for abnormal states. control room follows.

02.2 // Colour, human factors

Why the paper feels calmer

The light theme isn't the dark theme turned inside out. Its values were chosen for how eyes respond to them. Three numbers carry most of the story.

Light given off, compared with pure white
Pure white100%
Datum paper89%
Colour intensity
Datum paper4.5%
Signals100%
Text contrast, out of 21
Ink on white17.7
Ink on paper15.8

Calculated from the theme values: How bright a colour appears to the eye, from 0 for black to 1 for white. WCAG contrast ratios are built on it., HSV saturation and WCAG contrast.

  • Optics

    A brighter page makes the pupil contract, which sharpens focus. People proofread better with Dark text on a light background. Light text on dark is negative polarity., most of all at small sizes.

    Piepenbrock et al., Ergonomics 2013; Human Factors 2014
  • Glare

    Full white dazzles over a long read. Dyslexia guidance advises cream or soft pastel instead. Datum's paper gives off about 11% less light.

    British Dyslexia Association Style Guide
  • Arousal

    Saturation is one of the strongest drivers of arousal. The page is under 5% saturated, so alertness is spent only on signals.

    Valdez and Mehrabian 1994; Wilms and Oberfeld 2018
  • Halation

    On dark screens bright letters can This is called halation: a glow or bleed around bright text on a dark background, more noticeable with astigmatism., especially with astigmatism. So night text is off-white, not pure white.

    Trimble Modus dark mode guidance
  • But at night

    In a dim room a bright page is the glare. Dark stays the brand and night theme, and the reader picks the room.

02.3 // Typography

Three voices, one job each

AABarlow Condensed // call-out
AaInter // explanation
AaShare Tech Mono // readout
Aa 12 floorAa 13Aa 15Aa 16Aa 17

Nothing under 12px, including labels inside charts. Body text never lighter than 400. Lines of 60 to 75 characters.

02.3 // Typography, hero on phones

On phones, the name gets bigger

The usual move is to shrink a headline until it fits. The home page does the opposite: two short words can carry a poster, so the name takes 24% of a phone's width against 9% on desktop. Frames are drawn to scale.

  • Phone clamp(4.2rem, 24vw, 7.5rem), desktop clamp(4rem, 9.5vw, 8.5rem). Every fluid size is a A CSS function that lets a size grow with the screen, but never below a minimum or above a maximum. with a floor and a ceiling.
  • Leading tightens from .88 to .84 as the type grows, so two huge lines read as one block.
  • Sentence headlines, like this page's, get a gentler rule and balanced wrapping.
02.4 // Spacing

Room to think

An Spacing values in multiples of 8px, so everything lines up on the same invisible grid.. Sections get the most room on desktop and step down on smaller screens.

Remove something before you shrink anything.

02.5 // Layout and breakpoints

One column first

Mobile first: a single column by default, splitting only when there's room. Content tops out at 1200px with fluid margins.

320
390
768
1025
1280
1440

Nothing scrolls sideways at 320px, except wide data, inside its own box.

02.6 // Icons

Hairline, and never alone

Drawn on a 24px grid with 2px of breathing room, shown dashed. Round ends. Stroke is 1.5 at 24px. Small icons are drawn heavier so they keep their weight: 1.6 for the theme switch at 16px, 1.8 at 15px.

Actions get a label or an accessible name. Severity differs by shape, not just colour.

02.7 // Elevation

Height is light, or shadow

At night each level is a slightly lighter navy with a hairline. On paper each level casts a longer shadow, kept tight under the edge so the sheet stays clean.

Glow is reserved for one thing: a primary action under your cursor.

02.8 // Motion

Two modes, nothing for show

Borrowed from IBM Carbon's Carbon's two motion styles: productive for quick, efficient transitions, expressive for moments that deserve attention. motion. Productive handles changes you need but shouldn't notice. Expressive is for moments you trigger, with a small physical overshoot.

Productive // arrive and settle

Reveals, menus, underlines. 0.2 to 0.5s.

--ease-out-expo

Expressive // a little life

Button release, the theme switch marker and its icons. 0.45 to 0.7s.

--ease-spring-soft

Nothing loops. Every effect answers an action, and reduced motion shows every final state.

02.9 // Visual grammar

One signal, one meaning

Every visual signal in Datum means exactly one thing, everywhere it appears. That's what lets people learn the system once. It also caught a real mistake: the first AI cards were drawn in dashed lines, and dashes already meant "unavailable".

  • Solid lineLive and available: buttons, cards, fields, and AI.
  • Dashed lineNot available, not yet, or planned: disabled controls, planned items, untested status.
  • Heavier lineNeeds your attention: errors, the one caution tile.
  • CyanYou can act: links, buttons, focus, selection.
  • Amber and triangleLook here: caution, low confidence, high risk.
  • RedStop and read. With an octagon, something failed. On an action, it can't be undone.
  • Violet and sparkMade by AI. Never used for status.
Before Both read as "off"
After AI is live, the button is off

If two things look alike, people assume they behave alike. So a signal only ever gets one meaning.

System / 03// Components

A curated set, not a library

Thirteen components carry most product screens, and the last five are for AI. Each is documented the way mature systems do it, from anatomy and states to keyboard behaviour. Each one also says where it is live on this site, where it is only specified, and what has been tested. Product examples are illustrative, not client work.

03.0 // Atoms to pages

How the parts build up

Datum follows Brad Frost's model for design systems: atoms combine into molecules, molecules into organisms, organisms into templates, and templates become pages.. Each tier is built only from the one above it, so a change to a token reaches every page without anyone touching a component. Pick a part to follow it all the way down.

  1. 0
    Tokens

    Named values. The only place a raw value lives.

    50 primitives, 71 semantic · Sheet 02
    --cyan --ai --amber --alarm --space-150 Aa--fs-13 --ease-spring-soft
  2. 1
    Atoms

    The smallest parts that still mean something.

    12 atoms · Sheet 03
    SaveButton View allLink 45Text field FilterChip Icon CheckStatus AIAI label Confidence R3High riskRisk tag 1Citation chip 3 sourcesScope indicator Provenance badge
  3. 2
    Molecules

    A few atoms doing one job together.

    17 molecules · Sheet 03
    Torque45N·mForm field Card Notification Theme switch AIAI header Prompt composer Autonomy dial Suggested actions Run control Feedback capture Clarifying question Tool call Budget meter Caveat banner Handoff Agent role card Answer branches
  4. 3
    Organisms

    A distinct section of a screen.

    15 organisms · Sheet 03
    Navigation Data table Dialog Chart panel AI suggestion card Evidence panel Intent preview Approval gate Activity log Suggestion diff Memory panel Reasoning trace Dry-run preview Action receipt Agent inbox
  5. 4
    Templates

    Organisms arranged to solve a recurring problem.

    8 patterns · Sheet 04
    Multi-step workflowDashboardSearch and filterFormDense tableApprovalSystem statesHuman-in-the-loop AI
  6. 5
    Pages

    Templates filled with real content.

    The live site
    Every page on this siteWork order review (illustrative)This case study

A tier may only use the tiers above it. If an organism needs a raw value, a token is missing, and the fix is a new token, not a one-off.

01Pick a component8 core · 5 for AI

Testedchecked on this pageSpecifiedwritten down, shown as a static exampleNot yetscreen reader testing is next

02Viewing

ButtonsCore component · 1 of 13

03.1 // Buttons

Buttons

Start an action, ranked so the important one is obvious.

Use forThe main action on a view: submit, save, confirm, or the one link the page is for.

Not forOrdinary links in text or lists. Those are text links.

Hover, press and tab to them. marks the focus ring in the states row.

Hover, press and tab to them.

Anatomy

  1. AContainer. 1px radius and a 1px edge: machined, not bubbly.
  2. BLabel. 13px mono, uppercase, verb first.
  3. CArrow. Says where it goes: → stays here, ↗ opens a new tab, ↓ jumps down the page. Hidden from screen readers.
  4. DFocus ring. 2px, offset 2px, with a 4px halo in the background colour.

Variants

States

Spec // every number is the number in the code

Buttons measurements
Height45px. 50px on touch layouts. Small 36px
Padding0.7 by 1.6rem. 0.85 by 1.25rem on touch
Arrow gap8px
Radius1px
Label13px, tracking 0.08em
Focus ring2px, offset 2px, 4px halo

Tokens by state

Buttons tokens by state
Enabledbg --btn-bg // text --on-accent // edge --btn-edge
Hover--btn-bg-hover: white at night, navy on paper. --btn-glow: glow at night, ink shadow on paper. Lifts 2px
Focusoutline --cyan, halo --void
Presseddown 1px, scale 0.97, 80ms
Ghosttext --cyan // edge hairline at 30%
Disabledbg accent tint // text --dim2 // dashed edge

Keyboard and screen reader

Buttons keyboard and screen reader behaviour
TabMoves focus to the button
EnterActivates it. Space too, when it is a true button and not a link
Screen readerAnnounces the label and the role: button for an action, link when it goes somewhere. While loading, the change of label is announced.

Do and don't

✓ DoOne primary per view, named by what it does: "Save draft".

✕ Don'tTwo primaries side by side, or a button labelled "OK".

Agent rules // when an AI builds with it

Button agent rules
Allowed onControlled and declarative screens
Must set
  • A label, verb first.
  • A kind: primary, ghost or danger.
  • A destination or an action, never both.
Never
  • More than one primary in a view.
  • A danger button outside an approval gate.

Where it's used

  • LivePrimary and ghost, on every page: hero actions, case study links and the closing call to action. The two above are the home page's own pair.
  • SpecifiedDanger, small, loading and disabled. No page on this site needs them yet. They are drawn for product screens.

Accessibility testing status

DefaultTestedStatesTestedKeyboardTestedScreen readerNot yet

If everything is a primary button, nothing is.

System / 04// Patterns

Where systems earn their keep

Components are words. Patterns are sentences. This is where a system saves teams the most time, because the hard decisions have already been made, tested and written down.

04.1 // Multi-step workflows

Gated steps, never lost

Long, multi-person tasks fail in the middle: people lose their place, skip a check, or can't hand over cleanly.

  • Gates between steps: nothing is released before it's verified.
  • Progress and save state always visible.
  • Any step can be handed over with its context attached.

re-deciding stepper, save and handover rules for every new workflow.

04.2 // Dashboards

Lights-out dashboards

Dashboards become walls of colour where nothing stands out.

  • Normal tiles stay neutral.
  • Only exceptions get colour, plus a shape and a word.
  • A one-line summary first, detail on demand.

arguing about which metric deserves colour.

04.3 // Search and filtering

Filters you can see

Filters hide results without saying so, and people stop trusting search.

  • Active filters always visible and removable.
  • The result count updates and is announced.
  • Filters live in the URL, so a view can be shared.

rebuilding filter logic and no-result handling for every list.

04.4 // Forms

One mistake, one fix

Long forms punish a single mistake with a wall of red and lost input.

  • One column, labels above, grouped by task.
  • Check a field when people leave it, never on every keystroke.
  • An error summary at the top links straight to each field.

debating validation timing for every form.

04.5 // Tables and dense information

Density is a choice

Experts need to see a lot at once. Everyone else drowns in it. Try the toggle.

  • Comfortable or compact, remembered per person.
  • Header and first column stay put.
  • Bulk actions appear only once something is selected.

reinventing sticky headers, selection and density per table.

04.6 // Approvals

Show the change, not the form

Approvers rubber-stamp because they can't see what changed.

  • The diff comes first; the full record is one step away.
  • Returning needs a reason. Approving doesn't need a speech.
  • Every decision lands in an audit trail.

designing audit trails and diff views from scratch.

Couldn't load inspections

The planning system didn't respond. Nothing you entered was lost.

RetryWork offline
04.7 // Loading, empty and error

The states teams forget

They're the ones users remember. Switch between them above.

  • Loading shows the shape of what's coming.
  • Empty invites the first action.
  • Errors say what happened, what's safe, and what to do next.

every team writing its own "something went wrong".

04.8 // Human-in-the-loop AI

AI drafts, people commit

AI that writes straight into the record takes control away and makes errors hard to trace.

  • AI works in its own marked lane.
  • People accept item by item, never everything by default.
  • Only a person can commit, and the log says who.

inventing an AI review flow per team, and the trust problems that follow.

System / 05// Intelligence

AI that knows its place

In safety-critical work an AI is a crew member, not the captain. These rules keep a person A person reviews or approves what an automated system proposes before it takes effect.: how the AI speaks, shows doubt, acts, and hands control back.

Human control

Nothing applies itself

People can stop, check or undo anything an agent does.

Transparency

Always marked as AI

In the interface and in the record. It never passes as human work.

Confidence

Doubt changes the UI

Shown in words and bars, so people neither over-trust nor under-trust it. Low confidence changes what's offered, not just a number.

Explainability

Every answer has a "why"

The sources it used, and what it couldn't check.

Grounded in Microsoft's 18 Guidelines for Human-AI Interaction, IBM Carbon for AI and Emily Campbell's Shape of AI. The first guideline pair says it best: make clear what the system can do, and how well it can do it. The agent parts build on Victor Yocco's patterns for agentic AI in Smashing Magazine: intent preview, action audit and undo, and a way to escalate.

05.1 // Signals

Three questions, three signals

Before anyone reads a word of AI output, they should be able to answer three questions. Each answer has its own shape, so the three can sit side by side without blurring.

Who made this?

AI marker

AIAI-assisted

Violet, a spark and a word. AI for what it made, AI-assisted once a person has edited or accepted it. No mark means a person made it.

--ai
How sure is it?

Confidence

High confidence Medium confidence Low confidence

A word first, three bars second. Low turns amber and takes the one-tap accept away.

--conf-high--conf-medium--conf-low
What's at stake?

Risk tier

Risk tier 1: Low riskRisk tier 2: Medium riskRisk tier 3: High riskRisk tier 4: Irreversible

A tier code and a word. The action sets the tier, never the AI, and the tier decides the gate.

--risk-low--risk-medium--risk-high--risk-irreversible

Confidence is about the AI. Risk is about the action. They never share a shape, so a confident AI can't make a risky action look safe.

05.2 // Lifecycle and parts

One task, eight stages, thirty parts

An agent is always at exactly one of these stages, and each stage has one look, so people can tell at a glance whether it is waiting, working or done. Pick a stage, then a part, and try it: the buttons inside work, and the switch under it steps through its states, 91 across the 25 parts. The five signals every stage carries, the AI label, confidence, risk tier, citation chip and AI header, are in 05.1.

01Pick a stage, then a part8 stages · 25 parts

Suggesting. Marked as AI, with confidence in words and the sources it used. It proposes; it never applies.

The UILabel, confidence, a citation on each claim, and accept, edit or dismiss.

02Viewing

AI suggestion cardOrganism · 6 states · press anything in it, or step through its states

AISuggestionMedium confidence

Likely cause: bearing wear on ENG-208. The vibration pattern matches two past cases.

6 states

Suggested. Marked as AI, with confidence in words. It proposes; nothing applies itself.

Organism · AI

AI suggestion card

Proposals from a crew member, never instructions. People see at a glance what AI made, how sure it is, and how to undo it.

Use when
Suggestions someone reviews before anything changes.
Not for
Changing records on its own, or hiding that AI was involved.
If an AI builds it, it must set
  • The AI label.
  • Confidence.
  • A source, or a line saying what could not be checked.
  • Accept, edit and dismiss.
Never
  • Apply itself.
  • Show a bare percentage.
  • A one-tap accept at low confidence.

The five core parts are specified in full, with anatomy and keyboard rules, under Components, 09 to 13. Props, variants, states, tokens and code for all thirty are in the open Datum system (opens in a new tab) . Names, IDs and readings are illustrative, not client work.

05.3 // Doubt and risk

The signal changes the screen

A signal that only decorates is noise. In Datum, confidence decides what the AI may offer, and risk decides how hard it is to say yes.

High

Offer a one-tap accept.

Still logged, still undoable.

Medium

Reasons first, then ask for a review.

Sources open by default.

Low

Don't suggest an action.

Hand the case to a person with what was found.

a bare percentage. "87%" tells people nothing about what to do next.

Risk tier 1: Low risk

What countsReads and drafts. Nothing outside the draft changes.Example: Summarise 3 maintenance logs

The gateNo gate. It runs, then shows in the activity log.

UndoNothing to undo.

Risk tier 2: Medium risk

What countsChanges your own work, and can be fully undone.Example: Reassign 3 work orders to Line 2

The gateIntent preview. One tap to proceed.

UndoUndo for a stated time.

Risk tier 3: High risk

What countsChanges other people's work, or many records at once.Example: Reschedule 40 inspections across 2 sites

The gateApproval dialog. Scope listed, focus on Cancel, reason recorded.

UndoUndo for a stated time, then by hand.

Risk tier 4: Irreversible

What countsCan't be taken back: delete, send, release.Example: Release ENG-208 to service

The gateThe agent prepares. A named person carries it out, with a typed confirmation.

UndoNone, and it says so first.

Medium confidence moves an action up one tier. Low confidence offers no action at all.

Scope shown before actingReversible or not, said up frontIrreversible needs explicit confirmationEvery action logged with who approved itStop is one keystroke away

05.4 // Generated interfaces

How much the AI may draw

When an AI assembles the screen itself, the question is how much freedom it gets. Datum sets that by surface, so the answer never depends on who built the feature.

Controlled

What the AI doesThe AI fills in values. The layout is fixed and tested.

What it sendsText and numbers for named slots.

Allowed onAlarm and control screens, approval gates, anything at R3 or R4.

Declarative

What the AI doesThe AI picks and arranges parts from the catalog.

What it sendsA description that names parts from catalog.json. Anything else is refused.

Allowed onWork screens: dashboards, tables, forms and the assistant panel.

Open-ended

What the AI doesThe AI writes its own markup.

What it sendsMarkup of its own, outside the catalog.

Allowed onSandboxes and prototypes only, in a labelled frame with no access to real records.

An approval gate is always controlled. An agent can ask for one. It can never draw one.

The three levels follow CopilotKit's split of generative UI into static, declarative and fully generated. This is policy, not a shipped renderer. Nothing on this site is generated while you read it, so here none of the three is in use.

Every AI part, by the stage of a task it belongs to, is in 05.2 Lifecycle and parts above. Eight of them are drawn large near the top of this page.

On the bench // dashed means planned, not built

Embedded app frameGenerated region statesAI-filled form fieldsAI-filtered tablesThinking and streaming motion

System / 06// Data visualisation

Charts on the same colour budget

A chart is a small screen with the same rules as the big one. Neutrals carry it, hue is spent only on meaning, and every hue has a second cue, so no reading depends on telling two colours apart.

Neutrals first

Grey does the work

Gridlines, axes and labels stay neutral. Hue is spent only where it means something.

Identity

Four series at most

In a fixed order, never cycled. A fifth folds into Other, or the chart becomes small multiples.

Attention

Amber is spent once

With several charts on a screen, limits and targets are neutral. Amber marks the one reading that needs a person.

Second cue

Colour is never the key

A direct label, a legend shape or a printed value goes with every hue, and every chart has a one-sentence summary.

06.1 // The colour budget

Six colours, each with a job

Charts don't get a palette of their own. Every chart colour is a token the rest of the screen already uses, so a chart can never out-shout the alarm next to it. Four series carry identity, in a fixed order. Two colours are locked to a meaning and only appear when the data means it.

Identity // fixed order, never cycled

  • Series 1--cyanA direct label where the line endsNight10.6 to 1Paper6.5 to 1
  • Series 2--cyan at 65%A direct labelNight5.0 to 1Paper3.2 to 1
  • Series 3--paperA direct labelNight16.0 to 1Paper16.8 to 1
  • Series 4--dim2A direct labelNight5.1 to 1Paper5.9 to 1

Locked to a meaning

  • Made by AI--aiThe spark in the legendNight8.2 to 1Paper6.7 to 1
  • Failed--alarmThe octagon in the legendNight6.2 to 1Paper6.2 to 1

Contrast against the chart panel, measured in both themes. Every series mark clears 3:1 and every label clears 4.5:1.

Sequential scale // one hue, five steps

  1. 0Close to nothing
  2. 1Low
  3. 2Middle
  4. 3High
  5. 4Peak

For magnitude, as in the heatmap. Always drawn with its numbers. The lightest step on Paper is only 2.15:1, which is why cells keep a 2px gap and the scale is always labelled.

Never a series

  • AmberThe screen's one attention point. If every limit were amber, nothing would stand out.
  • IndigoOn Paper it is nearly the same blue as the first series. Two colours nobody can tell apart are one colour.

Checked for colour blindness too: under simulated protan and deutan vision, neighbouring series stay well apart in OKLab, at least 17 on Paper and 19 at Night against a floor of 8.

06.2 // Anatomy

The same card, every chart

Every chart sits in the same card, in the same order: what it is, how fresh it is, and one sentence that says what it shows. People read the takeaway first and the drawing second, so the drawing only has to confirm it.

Top agents // Success rate

7 days

Four of six agents clear the 95% target.

Triage-02 98.4% Records-01 97.6% Diag-01 96.9% Triage-05 95.3% Diag-04 92.7% Plan-03 88.9%
  • Tasks closed without rework
  • Target

Bar chart of success rate by agent over 7 days: Triage-02 98.4%, Records-01 97.6%, Diag-01 96.9%, Triage-05 95.3%, Diag-04 92.7%, Plan-03 88.9%. The target is 95%.

The bar chart, pinned. Readings are illustrative.
  1. ATitle. SECTION // DETAIL in the label style, so every card reads the same way.
  2. BFreshness. Top right. A chart that looks live but isn't is worse than no chart.
  3. CTakeaway. One line at 15px, weight 500, that says what the chart shows.
  4. DReference line. 1px dashed, 5 on and 4 off, always labelled. Neutral when charts share a screen.
  5. EAxis labels. Real text outside the drawing, never under 12px.
  6. FLegend. A swatch and a word, kept even when lines are labelled where they end.
  7. Tooltip. Specified for hover and keyboard focus. It adds, it never gates: every value is also in a label, the legend or the summary.

Marks // every number is the number in the code

Chart marks
Line2px, round joins
Bar8px thick, from zero, 1px radius at the data end
Marker8px, inside a 2px panel ring
Touching fillsA 2px panel gap, never a border
Ring and arc12px ring on the donut, 8px arc on the gauge, square ends
NumbersShare Tech Mono, tabular, 12px floor

Confidence // the word comes first

High confidence 86 of 100

Medium confidence 71 of 100

Low confidence 52 of 100

Never "86%". Band lines mark where Medium and High start, and the product sets them. The Datum AI console uses 60 and 80. Confidence never borrows the risk tag's shape.

States // what a chart says when it can't draw

  • LiveFreshness shown.
  • StaleGreys out to the quietest grey and says how old.
  • LoadingThe shape of what is coming, a named step and one progress line. No spinner, no shimmer.
  • EmptyA dashed frame, the reason in plain words, one next step. Dashed means not available, so empty is never amber.
  • ErrorOctagon, what is safe, retry.

06.3 // Chart parts

Ten parts, one question each

Pick a chart by the question it answers, not by how it looks. Stacked area for how a total moves and who carries it. Gauge for where one score sits against its bands. Heatmap for when it gets busy. Each part below comes with its anatomy, tokens, states and the rules an AI agent has to follow when it builds with it. Night and Paper are drawn one above the other, and the readings are illustrative.

01Pick a chart part7 charts · 3 around them

Testedchecked on this pageSpecifiedwritten down, shown as a static exampleNot yetscreen reader testing is next

02Viewing

Stacked area chartOrganism · Specified · 1 of 10

06.3 // Stacked area chart

Stacked area chart

How a total moves over time, and who carries it.

Use forA total over time, split into four series at most.

Not forSeries that cross or need comparing one to one. A stack hides that. Use lines.

Agent activity // By agent type

Updated 2 min ago

Volume peaked at 11:00 with 1,045 tasks an hour. Triage carries 44% of the load.

  • Triage
  • Diagnosis
  • Planning
  • Records
Tasks per hour
Triage 44% Diagnosis 27% Planning 18% Records 11%
Hour, IST

Stacked area chart of tasks per hour by agent type over the last 24 hours. Volume fell to about 200 an hour overnight and peaked at 1,045 at 11:00. Triage 44%, Diagnosis 27%, Planning 18%, Records 11%.

Agent activity // By agent type

Updated 2 min ago

Volume peaked at 11:00 with 1,045 tasks an hour. Triage carries 44% of the load.

  • Triage
  • Diagnosis
  • Planning
  • Records
Tasks per hour
Triage 44% Diagnosis 27% Planning 18% Records 11%
Hour, IST

Stacked area chart of tasks per hour by agent type over the last 24 hours. Volume fell to about 200 an hour overnight and peaked at 1,045 at 11:00. Triage 44%, Diagnosis 27%, Planning 18%, Records 11%.

Anatomy

  1. ATitle and freshness. SECTION // DETAIL on the left, the last update on the right.
  2. BTakeaway. One line that says what the chart shows.
  3. CLegend. One swatch per series, in stack order.
  4. DPlot. A wash per band, a 2px line on top of each.
  5. EEnd labels. The series name and its share, where each band ends.
  6. FHover. A crosshair, a marker on each line and a tooltip with every value and the total.

Tokens used

Stacked area chart tokens
Series 1 line and wash--cyan, --cy-rgb at 26%
Series 2 line and wash--cy-rgb at 65%, --cy-rgb at 12%
Series 3 line and wash--paper, --paper at 14%
Series 4 line and wash--dim2, --dim2 at 22%
Gridline--hl-rgb at 12%
Baseline--hl-rgb at 35%
Crosshair--hl-rgb at 45%
Tooltip--panel2, --hl-rgb at 30%

Spec // every number is the number in the code

Stacked area chart measurements
Line2px, round joins
Marker8px, in a 2px panel ring
Plot height300px at least
Axis column--space-500
End label column--space-1400
Gaps--space-100
Labels12px mono, real text, never inside the drawing

Variants

  • Four series
  • Fewer series, same order

States

  • LiveFreshness shown
  • HoverCrosshair, markers, tooltip
  • StaleLines grey out to --dim2, says how old
  • Loading, emptySee ChartState

Keyboard and screen reader

Stacked area chart keyboard and screen reader behaviour
Arrow keysMove the crosshair one point at a time
Screen readerA one-sentence summary of the trend and the shares
DataThe values are available as a table

Do and don't

✓ DoPut the largest or steadiest series at the bottom. It gets the flat baseline.

✓ DoLabel each band where it ends, and keep the legend.

✕ Don'tA second y-axis. Two scales invent a link the data does not have.

✕ Don'tA fifth series. Fold the tail into "Other".

Agent rules // when an AI builds with it

Stacked area chart agent rules
Allowed onControlled and declarative screens.
Must set
  • A title.
  • A unit.
  • A takeaway.
  • A legend and end labels.
  • The time of the last update.
Never
  • More than four series.
  • Colour as the only key to a series.
  • A second y-axis.

Where it's used

  • SpecifiedAgent activity by agent type on the Datum AI console. The readings are illustrative.

See it in the console

Accessibility testing status

ContrastTestedKeyboardSpecifiedScreen readerNot yetHoverSpecified

A stack answers "how much in total" first. If the question is "which one is higher", it is the wrong chart.

06.4 // In use

One screen, one amber

The Datum AI operations console puts nine of the chart parts on one screen with the AI parts from System / 05. It is the test of the colour budget: six charts, a review queue and an audit trail, and exactly one reading in amber, the low-confidence task that needs a person. Every limit and target around it stays neutral.

Datum AI consoleAgent operations // Last 24 hours

Static example. Readings are illustrative.

A static, illustrative operations console for AI agents. Four headline numbers: 12,480 tasks processed, most of them auto-resolved by AI, and 37 waiting on review. Below them, activity by agent type over 24 hours, a confidence gauge reading high, a donut of task outcomes, a heatmap of busy hours, a bar chart of agent success rates against a 95% target, and a flow from intake to done. Then a review queue of four tasks, one of them low confidence, an audit trail with undo, and an AI insight that Planning agents sit about 9 points below their stated confidence.

Not done yet, and said plainly: hover is specified but not built, there is no table view behind each chart yet, and none of this has been through a screen reader. The summaries are written; the testing is next.

Thread// Accessibility

Not a checklist. A layer.

Accessibility runs through every sheet, so building without it takes more effort than building with it. Then every release is checked anyway with axe-core, an open-source automated accessibility checker made by Deque. and a keyboard walk, because automated tools only catch part of the problem.

2.2 AAWCAG target, both themes
0Automated issues, desktop and phone, dark and light, normal and high contrast
4.5:1Lowest text contrast anywhere
24pxSmallest tap target
01 Principles

Access is rule five, and it's never traded away.

When rules collide, the order decides, but access isn't on the table.
02 Foundations

Contrast is baked into token pairs, in both rooms.

Text at least 4.5:1, focus and selected states at least 3:1, 12px floor, reflow to 320px.
03 Components

Names, focus and targets come built in.

Visible focus ring, 24px minimum targets, pressed and selected states announced.
04 Patterns

Failures are designed, not apologised for.

Error summaries link to fields, result counts are announced, nothing typed is lost.
05 Intelligence

AI is marked by colour, a spark and the word AI, and doubt is in words.

Confidence never relies on colour, and stop is reachable from the keyboard.
06 Data visualisation

Every series mark clears 3:1, and every hue has a second cue.

Direct labels, a legend shape for AI and failed, printed values and a one-sentence summary for screen readers.
Contrast

Turn up contrast in your system settings and the page follows.

Secondary text, labels, hairlines, field edges and the paper blue get stronger. Surfaces and signals stay as they are.
Motion

A device setting for people who find animation dizzying or distracting. Sites can read it and calm down. is honoured everywhere.

Nothing loops. Short demo animations stop within five seconds, and every final state shows without them.

All 13 WCAG 2.2 criteria, and how they're met

WCAG 2.2 success criteria and how Datum meets them
CriterionHow Datum meets itLevel
1.3.1 Info and RelationshipsReal headings in order, tables with headers and captions, lists marked as lists.A
1.4.1 Use of ColorEvery status has a second cue: shape, border weight or a word. See the side-by-side test in 02.2.A
1.4.3 Contrast (Minimum)Every text pair at least 4.5:1 in both themes. Body text 17.1:1 at night, 15.8:1 on paper.AA
1.4.10 ReflowOne column down to 320px. Only wide data scrolls, inside its own box.AA
1.4.11 Non-text ContrastFocus rings and selected states clear 3:1: cyan 10.6:1 at night, blue 6.1:1 on paper.AA
2.1.1 KeyboardEvery control works from the keyboard, including the component tabs, which use arrow keys.A
2.2.2 Pause, Stop, HideNothing loops. Demo animations and the one ambient effect stop within five seconds.A
2.4.1 Bypass BlocksA skip link jumps straight to the content.A
2.4.7 Focus VisibleA 2px ring with a 4px background-coloured halo, on everything focusable.AA
2.4.11 Focus Not Obscured (Minimum)Focus and jumps land below the sticky header and chapter bar. Checked by tabbing the whole page.AA
2.5.8 Target Size (Minimum)Every target is at least 24 by 24px.AA
4.1.2 Name, Role, ValueToggles announce pressed, tabs announce selected, the menu reports open or closed.A
2.3.3 Animation from InteractionsWith reduced motion on, decorative motion is removed and every final state still shows.AAA bonus

Being honest about itA clean automated audit is the floor, not the finish line. Screen reader testing with VoiceOver and NVDA is next on the bench.

System / 07// Governance

How it stays one system

A system without governance is a style guide with a short life. This is the lightest process that still works, for one designer, a whole team, or an AI agent.

  1. Find

    Search the system first. Most needs already have an answer.

    Anyone
  2. Propose

    A need seen three times, with screenshots and the problem it solves.

    Designer
  3. Build together

    Design and build use the same token names, so nothing gets renamed in handoff.

    Designer and engineer
  4. Review

    Design, engineering and accessibility sign off against the pre-flight checklist.

    Design, build, access
  5. Release

    Versioned and logged. Pages are replaced whole, never patched.

    System owner

How it's used feeds the next proposal

On a team, review is three people. On this site it's three passes I make myself: design, build and accessibility, each against the checklist.

Before building something new

Does it already exist?Use it
Is it nearly right?Add a variant
Needed in three or more places?Propose it
Truly a one-off?Build locally, log it

One name, one job

Name // --cyan⇄Job // you can act here⇄Values // #00D4FF night, #0057B8 paper

Pre-flight checklist // nothing ships unticked

  1. Accessibility auditZero issues, both themes, desktop and phone.
  2. Keyboard walkEvery control reachable, focus never hidden.
  3. Six widths, real fontsNo overflow or clipping from 320 to 1440.
  4. Principle testsBlur, grayscale, shared controls match.
  5. VoicePlain words, verbs on buttons, no em dashes.

06.1 // Two readers

Read by people, and by AI agents

This page was built over many AI-assisted sessions, and an AI forgets everything between sessions. Without a written system it guessed, and the guesses drifted. These are real problems from earlier versions of this page:

  • Name collisionsA new label reused a class from another section and drew a stray box around it.
  • Leftover rulesOld CSS squeezed the colour panel into one narrow column.
  • Silent lossThe red and amber styles on state chips disappeared during a clean-up, and nobody noticed for two versions.
  • Broken floorChart labels shrank to 5 or 6px on phones, under the 12px rule.

So Datum now has a second form, written for machines. It follows the method in Hardik Pandya's "Expose your design system to LLMs" (opens in a new tab), adapted for single-file pages.

  1. Specs

    68 markdown files every session reads first: principles, foundations, guidelines, then atoms to templates.

    Fixes: no memory between sessions
  2. Closed tokens

    Three tiers. Datum's raw colours exist in one block only; everything else picks a name. The sealed site header is the one declared exception.

    Fixes: invented values
  3. Audit

    A script flags every raw value with the token to use instead, and fails on any error.

    Fixes: drift inside a session
  4. Sync check

    Each page embeds a copy of the tokens; the audit flags any copy that differs from the source.

    Fixes: pages falling out of step
  5. Token export

    tokens.json is generated from tokens.css in the Design Tokens Community Group format, version 2025.10, so tools that can't read CSS get the same values.

    Fixes: tools keeping their own copy
  6. Catalog

    catalog.json lists all 44 parts with their props, states, tokens and agent rules. A script checks it against its schema, the specs and the tokens.

    Fixes: agents inventing parts
The machine-readable system
datum-system/
├── AGENTS.md            read first, every session
├── tokens.css           primitives → semantic
├── tokens.json          same values, DTCG 2025.10
├── catalog.json         44 parts, agent rules
├── catalog.schema.json
├── scripts/
│   ├── token-audit.js
│   ├── tokens-to-json.js
│   └── catalog-check.js
└── specs/
    ├── principles.md  voice.md
    ├── foundations/     10 files
    ├── tokens/          token reference
    ├── guidelines/      gen UI tiers, agent rules
    ├── atoms/           12
    ├── molecules/       17
    ├── organisms/       15
    └── templates/       8
Token audit, this page
Before // v8 709errors
  • Raw colours193
  • Raw spacing324
  • Raw text sizes192
Now // v16 0errors
  • Raw colours0
  • Raw spacing0
  • Raw text sizes0

When the tokens went in at v9, the page was compared pixel by pixel in both themes: nothing you could see had changed. Still open, as warnings: 224 off-grid spacing values and 92 raw durations. The header is the site's sealed block, copied byte for byte from the home page, so the audit reports it on its own line and leaves it alone: 12 raw colours, 32 raw spacing values and 7 raw text sizes that have to be fixed at the source.

Taste goes in once, as a written rule. After that, every session, human or AI, starts from the same place.

06.2 // Open system

Take it, build on it

Datum is open to anyone with the link: the tokens, the foundations, and all 44 parts with their guidelines, agent rules and a live preview. Read it, hand it to your AI agent, and build your own screens on it.

Open the Datum system (opens in a new tab)

System / 08// Evolution

Value that compounds

A system costs more at the start and less on every screen after. The value isn't the library. It's the decisions nobody has to make twice.

EffortBreak-evenScreens built →
One-off designWith a system
Illustrative, not measured. It's the shape every system follows: pay once, save on every screen after.
Reuse

Built once, used everywhere

The header here is the home page's, copied byte for byte. Buttons, footer and focus ring carry the same values.

Consistency

One header, one memory

The same controls in the same place, and one saved theme choice that follows you between pages.

Less duplication

Defined once, by job

Every raw colour Datum owns lives in one block of tokens.css. The audit fails if one appears anywhere else, and counts the sealed header's on its own line.

Speed

No blank pages

This case study started from the Writing page's shell and tokens, and took its header from the home page.

Accessibility

Inherited, not retrofitted

Contrast and focus live in tokens and components, so new pages start from passing values.

Scalability

One source, many outputs

Two themes and six screen widths from one set of decisions.

Evolution

Replaced, not patched

53 versions of the home page, each rebuilt whole on the last.

Shared language

Arguments about problems

Tokens are named by job, so a review can say "action" instead of a hex code.

Flight log

v5

The dark instrument-panel look, built from scratch.

v37

The drafting-paper theme, and a theme switch on every page.

v38

Motion tokens. Every effect answers an action.

v41

Each case study gets its own phone card.

v47

The switch becomes two icons. Connect becomes an outline.

v53

Current reference. One sealed header, one paper palette.

  1. Principles without tests are posters

    Once each rule had a check, arguments got shorter. It passes or it doesn't.

  2. Constraints made it more expressive

    Rationing colour made the moments that use it land harder. Quiet gives a signal its volume.

  3. Patterns matter more than parts

    Teams rarely struggle to draw a button. They struggle with approvals, errors and AI. That's where the system pays back.

Next on the benchScreen reader testing with VoiceOver and NVDA, moving the last 224 off-grid spacing values onto the grid, moving the sealed header onto these tokens at its source, and running the token audit on every page of the site, not just this one.

End of case study

Building where
signals matter? Let's connect.

Open to safety-critical products, design systems and AI that people have to trust. Or read why every design system is also a safety system.