Atlas Design System

Use the tree to inspect foundations, component families, applied kits, and quality gates without leaving the catalog.

Atlas is an organisation ledger for workforce management: every organisational fact is stored as a time-bounded event, not a mutable record. The system runs on one Flush accent, warm Plum neutrals, and the Newsreader display serif, and is governed in layers from tokens up to applied kits.

Canonical docs

Rules

DESIGN.md

Canonical product, visual, interaction, and anti-pattern contract. Read it before producing Atlas work.

Open rules

Agent guide

SKILL.md

How to generate or extend Atlas components without treating an app screen as the whole system.

Open guide

Overview

README.md

Package governance, layer map, preview manifest, and the reuse workflow.

Open readme

Package layers

tokens/Canonical colors, typography, spacing, radii, shadows, and font declarations.
components/Reusable React primitives with typings and agent prompts.
preview/ · guidelines/Specimen cards and usage rules that prove token and component behaviour.
ui_kits/Applied desktop and mobile reference implementations.
source_examples/ · context/Preserved source used for fidelity comparisons.
tests/Contract tests that prevent package-shape and product-fidelity regressions.

tokens/colors.css

Primary palette

Flush is the action color. Use 600 for the primary action, focus marker, active row, and allocation segments; keep it out of decorative page washes.

50background

100tint

200soft

300support

400hover

500active

600primary

700error

800strong

900deep

Success Warning Info Error

Neutral palette

Plum is the warm charcoal neutral. The dark sidebar and overlays sit at plum-900, the app canvas is plum-100, and the default hairline is plum-300. Surfaces are flat plum tints, never neutral grey.

50cell

100canvas

200hover

300border

400line

500muted

600meta

700fg-3

800deep

900sidebar

950deepest

Category & on-dark tokens

Category tints give up to five distinguishable series hues for work-group categories, matrix split bars, and Gantt bars. The on-dark status variants are brighter, for dots and markers on plum-900 surfaces (sidebar, scrubber).

cat-1raspberry

cat-2blue

cat-3amber

cat-4green

cat-5teal

success-on-dark warning-on-dark role

tokens/typography.css

Typography specimens

Newsreader carries display hierarchy and tabular numbers; Hanken Grotesk carries UI copy; IBM Plex Mono is reserved for references, dates, hashes, and money.

Display · Newsreader

--fs-display-lg 24.2 · 30 people 48 / 52 · -0.01em

--fs-h1 Workforce overview 32 / 38

--fs-h2 People & allocation 24 / 30

--fs-h3 Capacity & cost 20 / 26

UI · Hanken Grotesk

--fs-h5 Reporting tree (10) 14 / 20 · 600

--fs-body-1 Atlas treats every organisational fact as a time-bounded event rather than a mutable record. 13 / 18

--fs-body-2 Staff Engineer · Milan · Reports to Elena Russo 12 / 16

--fs-body-3 Capacity re-allocated on 01 Jan 2026 by Riccardo Conti 11 / 15

.at-eyebrow Monthly contractor spend 10 · 0.16em

Mono · IBM Plex Mono

.at-mono CC-AP-001 · NS-2042 · e-021 · 31 Jul 2026 tabular nums

numerals €540 · 4 days/wk · €11.7k/month refs & money

Spacing scale

Atlas spacing is a compact operational scale: small steps for dense controls, larger bands for section rhythm, and explicit mobile breathing room where touch targets need it.

tokens/spacing.css

--space-2xs2xs · 4px

--space-xsxs · 8px

--space-smsm · 12px

--space-mdmd · 16px

--space-lglg · 24px

--space-xlxl · 32px

--space-2xl2xl · 40px

--space-3xl3xl · 48px

--space-4xl4xl · 64px

--space-5xl5xl · 80px

Rows--row-height · 36pxTable rows, sidebar items, and compact navigation.

Controls--control-height · 28pxButtons, pills, filters, and dense form controls.

Matrix Y--cell-pad-y · 16pxVertical padding inside allocation and timeline cells.

Matrix X--cell-pad-x · 18pxHorizontal padding for readable operational tables.

Radius scale

Use small radius for controls, medium radius for operational surfaces, pill radius only for compact metadata, and plum-tinted shadows only when elevation clarifies hierarchy.

tokens/radii-shadows.css

--radius-xs · 4px

--radius-sm · 6px · controls

--radius-md · 10px · cards

--radius-lg · 14px · large

Contractor--radius-pill · 999px

Shadow scale

Shadows are plum-tinted and functional. Use them to separate overlays or raised panes from the workspace, not as a decorative glow layer.

Small elevation--shadow-smSubtle hover and compact raised controls.

Medium elevation--shadow-mdPopovers, small drawers, and floating panels.

Large elevation--shadow-lgModals and decisive foreground surfaces.

Lockups

Use the full lockup for package identity, the inverse lockup on plum surfaces, and the compact mark for tight chrome or identity anchors.

assets/atlas-logo.svg assets/atlas-logo-inverse.svg assets/atlas-mark.svg

assets/atlas-logo.svg

assets/atlas-logo-inverse.svg

assets/atlas-mark.svg

App icon

The launch icon is its own asset, not the 40px mark scaled up. It uses a plum product canvas, ledger geometry, and a Flush mark built from paths.

assets/atlas-app-icon.svg

Plum product canvas + Flush app mark Use the 1024px app icon for installer, favicon, launch surfaces, and app stores. Use the 40px mark only for avatars and dense UI chrome. Flush-600 · #E03A63

Runtime build assets

The build folder mirrors the source marks used by the packaged app. Keep parity between source SVGs and runtime exports.

build/icon.svg

build/icon-1024.png

build/logo.svg

build/logo-inverse.svg

assets/icons.svg

Icon vocabulary

Atlas icons are 24px line glyphs with 1.5px strokes and currentColor inheritance. Use them as quiet operational signals, not decorative badges.

Status & feedback alert · check · info · cancel

alert check-circle info-circle cancel-circle

Navigation & hierarchy arrow · chevron · search · filter-horizontal

arrow-right chevron-down search filter-horizontal

Workforce objects person · team · dashboard · calendar

user user-multiple dashboard calendar

Finance & allocation bank · coins · euro · card

bank coins euro card

build/icons-sprite.svg

Complete sprite inventory

All 87 source symbols are rendered here from assets/icons.svg. The grouping is for scanning only; implementation should reference the exact symbol ID shown beside each glyph.

Status and feedback 9 icons

alert alert-square check check-circle check-square cancel cancel-circle info-circle question

Arrows and hierarchy 11 icons

arrow-up arrow-down arrow-left arrow-right arrow-up-down arrow-growth arrow-turn chevron-up chevron-down chevron-left chevron-right

Finance and allocation 13 icons

bank card coins euro pound percent wallet money-add money-remove money-success money-withdraw invoice exchange

Charts and planning 8 icons

chart-up chart-line chart-decrease pie-chart dashboard target calendar clock

People and communication 9 icons

user user-advisor user-multiple user-square chat chat-user mail notification phone

Controls and navigation 11 icons

home search settings settings-sliders filter-horizontal filter-vertical menu more-horizontal more-vertical plus sorting

Security and access 7 icons

lock lock-open shield key fingerprint eye eye-slash

Files and actions 7 icons

file upload download share copy edit delete

Signals and objects 12 icons

globe leaf lightbulb star sparkles support umbrella compass gift infinity champion megaphone

ui_kits/app/icon-paths.js

Usage scale

Keep icons subordinate to labels. Size them by surface density, preserve currentColor, and avoid introducing one-off filled variants.

12-14px

Inline metadata and compact pills Use for small status chips, table metadata, and dense toolbar affordances.

16px

Default controls Pair with button labels, sidebar rows, filters, search fields, and form actions.

20-24px

Surface anchors only Reserve larger icons for empty states, panel headers, and product navigation landmarks.

currentColor

Color comes from the component state The sprite should inherit text color; status meaning belongs to the host component token.

Motion & interaction

Atlas moves the least amount that still reads as responsive. Transitions are short and token-timed; nothing bounces, scales, or spins forever. Motion confirms an action or eases a surface in; it never decorates. Hover over the rows and replay the panel below to see each rule live.

DESIGN.md § 7

Transitions & hover

0.1 to 0.18s ease on colour, border-colour, background, and box-shadow. Nothing slower, nothing infinite. Hover darkens borders to plum-700, fills ghost buttons to plum-200, and washes rows to plum-100.

Hover — live

Move the pointer over each to see the only sanctioned hover treatments.

Table or tree row, washes to plum-100 Card, border darkens to plum-700

Entering surfaces

Panels, drawers, and the command palette enter with a soft fade and a 4px rise — opacity 0 to 1, translateY(4px) to 0, over roughly 0.16s. No scale, no slide-in from the edge.

Fade + rise

New event

Drawer body fades up 4px as it mounts.

Press & progress

Press is a colour shift only, never a transform — no shrink, no bounce. The single exception to the no-loop rule is a tiny indeterminate spinner at flush-600 for genuine waits.

Press & spinner

Hold the button down: the fill shifts to flush-700, the box never moves.

Saving to the ledger

Reduced motion

When the operating system requests reduced motion, Atlas drops the rise and fade and the segmented slide, keeping only the colour transition at 120ms or less. Nothing essential depends on movement.

prefers-reduced-motion: reduce

Honoured through a single media query: entering surfaces appear instantly, the segmented thumb snaps, hovers still recolour.

Voice & writing

Atlas states facts; it does not sell. Copy is calm, operational, and precise — mostly declarative noun phrases and short verbs. The same rules govern labels, buttons, hints, and event history so every surface reads in one voice.

DESIGN.md § 8

Tone

Declarative and operational. Report the state of the organisation; never market it. Second person stays rare.

Operational, not promotional

AvoidAtlas voice

Supercharge your team's productivity 30 people · 24.2 FTE

Oops! Something went wrong. Allocations must total 100% — currently 80%

Casing & spelling

Sentence case for body, buttons, and chips. Uppercase with 0.16em tracking for eyebrows and column headers. British English throughout.

Casing

Monthly contractor spend

British English

organisation · allocation · cancelled · prioritise · licence. Not organization, canceled, prioritize.

Numbers

Numbers are first-class and always tabular. Headline metrics use the display serif; everything else follows fixed formats.

Formats

Headline metric24.2 FTE24.2 (one decimal) Percentage30% (whole number) Money€47.7k (compact) Date01 Jan 2026

Event language

Every change reads as a ledger entry, never a destructive edit. Past tense for history, future tense for planned events.

Ledger, not edit

AvoidAtlas voice

Edited allocations Capacity re-allocated

Delete contract Contract will end 31 Jul 2026

Anti-patterns

The regressions an agent must not reach for when generating Atlas artifacts. Each is paired with the canonical move, so the list reads as a correction, not just a ban. Markers are line SVGs, never emoji — the page holds itself to its own rules.

DESIGN.md § 9

Colour & accent

Backgrounds are flat plum tints; Flush is the single accent.

AvoidAtlas

Aggressive purple/violet hero gradients Flat plum tints

Beige, cream, or peach "AI canvas" washes Warm plum neutrals

Flush for secondary or decorative fills One accent, at most twice per surface

A left-border accent stripe on every card The 2px Flush bar only on the active row

Type & iconography

Newsreader is the only display face; icons are line SVGs; Atlas does not market itself.

AvoidAtlas

Inter, Roboto, or Arial as a display face Newsreader for every display headline

Emoji, unicode glyph icons, or stock photos Line SVGs on a 24x24 grid, 1.5px stroke

Generic feature-grid icon rows Plain facts; no self-marketing

Display headlines above 140px Dense type, never poster-like

Depth & motion

Hover is colour-only, shadows are plum-tinted, nothing decorates.

AvoidAtlas

Bouncy or scale-up hover micro-interactions Colour-only hover, no transform

Heavy neutral-black shadows Plum-tinted shadows

Hand-drawn humans, blobs, gradient meshes No decorative illustration

Scope & honesty

Real numbers only; product surfaces stay clean; applied kits are evidence, not the system.

AvoidAtlas

Filler stat-slop ("10x faster", "99.9% uptime") Real Atlas numbers or honest placeholders

Theme knobs or demo controls in a product surface Product surfaces stay free of meta controls

Treating the applied kits as the whole system Tokens and components stay canonical

Accessibility

Accessibility is a property of the tokens, not a later pass. Every focusable element wears the same ring, text colours meet WCAG AA on their intended backgrounds, every action is reachable from the keyboard, and touch surfaces respect a 44px minimum.

DESIGN.md § 5-6

Focus

Focus-visible is the flush ring — flush-600 at 18% alpha — on every focusable element, identical across buttons, inputs, and selection controls. Shown forced below; tab through any real control to see it.

One ring, everywhere

Checkbox

Contrast

Text pairs target at least WCAG AA (4.5:1). The brightest accent, flush-600, is a fill behind bold or large text; flush-700 carries small text and borders on light surfaces.

Token pairs

Body copy

fg-1 on white · 18.9:1AAA

Secondary copy

fg-3 on white · 8.1:1AAA

Inverse on accent

white on flush-700 · 5.6:1AA

Error text

flush-700 on flush-50 · 5.1:1AA

Keyboard

Every surface is fully operable from the keyboard. The command palette is the global entry point; Escape always backs out; Tab follows reading order.

Core shortcuts

⌘KOpen the command palette

TabMove through controls in reading order

EscClose the drawer, palette, or sheet

↵Commit the focused action or event

Touch targets

On touch, targets are at least 44px, body copy at least 14px, and meta at least 12px. Hover-only affordances always carry a visible touch equivalent.

44px minimum

44px hit area around a 24px control Body ≥ 14px · meta ≥ 12px

Form controls

The bare input primitives the rest of the system composes. Field wraps these with a label, hint, and validation; here they stand alone so any surface can reuse them. One baseline: 30px tall, hairline border, small radius, Flush focus ring, token colours only. Flush stays scarce, surfacing only in the focus ring and in the on state of selection controls.

Each control is a self-contained component in components/core/, drop-in like Button and Field and consuming the same tokens. Field composes these for labelled drawer forms. One card per file below; variants live inside their component's card.

Input

Text, numeric, search, and date — all one component. Default on white, Flush focus ring, Flush-700 border on error, tinted fill when disabled.

components/core/Input.jsx

Text — states

Numeric — variant="numeric"

Serif tabular figures, right-aligned, for headcount, allocation, and money.

Search — leading icon (icon prop)

A leading icon shares the control box; the wrapper, not the input, owns the focus ring.

Date — native picker

First iteration uses the native date control on the same .at-control box, so the OS picker opens on click. A fully styled Atlas calendar is a planned follow-up.

Select

Native select with a token chevron; appearance reset so it matches the input box.

components/core/Select.jsx

Textarea

Resizes vertically only; use for notes and rationale on an event.

components/core/Textarea.jsx

Checkbox

Checked fills Flush; the tick is drawn in token white. The type="radio" variant gives the round single-choice control with a Flush dot.

components/core/Checkbox.jsx

Checkbox

Notify the reporting line Backfill the role Locked by policy

Radio — type="radio"

At the next ledger date On a chosen date Backdated

Switch

A binary that takes effect immediately; on slides to Flush.

components/core/Switch.jsx

Show contractors Include future-dated events Sync to payroll

Segmented

A few mutually exclusive options inline; the active option rises on a neutral pill that slides, so Flush stays reserved.

components/core/Segmented.jsx

Field primitives

Drawer form primitives promoted from the workforce app. Field, FieldRow, Hint, and ValidationMessage share label, hint, and validation rhythm so drawers feel consistent across event types.

Specimens

Promoted from the event drawer pattern: label above, 30px control, 11px hint, Flush focus/error states, and compact equal-column rows. See the Usage rules below.

Field — anatomy

Label sits above the control; the control is 30px on white with a hairline and the flush focus ring; the hint is one sentence below at 11px, tied to the field.

components/core/Field.jsx

Effective from Future-dated changes are accepted

Field — states

Field is label and hint; the control carries the border and ring. Required marks controls that block commit; an error turns the control border flush-700 and reddens the hint. Disabled dims the whole field.

End date *

Focused role Uses the shared Flush focus ring.

Current function Disabled fields reduce the whole field.

Allocation total Allocations must total 100%

FieldRow — 2 columns

For related pairs or short triples; keep textareas and allocation controls as full-width Fields.

components/core/FieldRow.jsx

Function

Role

FieldRow — 3 columns

Capacity

Start

End

Hint — tones

components/core/Hint.jsx

Neutral helper outside a single field. Effective date is in the past. Allocations must total 100%.

Validation messages

Section-level conditions such as allocation totals; prefer copy that includes the current value. Hint is preventive; error/ValidationMessage report a failure.

components/core/ValidationMessage.jsx

! Allocations must total 100% — currently 80% ! Effective date is in the past i Future-dated changes are accepted ✓ All allocations balanced

AllocationBar — under / at / over 100%

Stacks per-work-group capacity %, colour-coded by category. Under 100% leaves a hatched plum tail; over 100% saturates as a warning.

components/data/AllocationBar.jsx

The bar in its three states, with the optional total badge (showTotal) on the right — the bar's own balanced / under / over readout. Names, roles, and category chips belong to the Allocation summary surface.

At 100%

30%

20%

10%

40%

100%

Under 100% — hatched plum tail

60%

20%

80%

Over 100% — saturates to flush-700

60%

50%

110%

AllocationChip — legend pill

A colour swatch, the work-group label, and its share. The legend primitive composed by Allocation summary and diff.

components/data/AllocationChip.jsx

Wealth48% Country Italy28% Other14%

CodeValue — reference token

Monospace pill for literal system values: cost centres, NetSuite ids, account refs. Reads as a verbatim code, distinct from prose and from tabular numbers.

components/data/CodeValue.jsx

CC-TR-002 NS-2078 EVT-014

Date pill

The topbar "as of" control that opens the scrubber. A dot encodes whether the global view date is today, in the past, or in the future.

ui_kits/app/app-shell.jsx

Today18 Jun 2026 As of01 Jan 2026 As of31 Jul 2026

Scrubber

A dark plum-900 overlay component. The timeline carries ledger events colour-coded by kind, a flush today cursor, a legend, and jump chips.

components/surfaces/Scrubber.jsx · applied instance ui_kits/app/overlays.jsx

Time machine

Rebuild the organisation at any past or future date.

21 May 2026

Jan 24

Jul 24

Jan 25

Jul 25

Jan 26

Jul 26

Today

Upcoming events · jump to

08 Junhire · Isabella

30 Junend · Eleonora

31 Julend · Hannes

31 Julend · Beatrice

Grid layout

A row × column grid shell: headers on both axes and count cells with an optional employee/contractor split bar and meta; empty cells stay muted. You give it columns and rows. Shown here with function × work-group sample data; the live function × work-group matrix in the app is an instance bound to the ledger.

components/surfaces/Matrix.jsx · applied instance ui_kits/app/overview.jsx

	Engineering14 people	Finance5 people	Design4 people
Core Platform 9.8 FTE	8 6.4 FTE	—	2 1.8 FTE
Country Italy 6.8 FTE	4 3.2 FTE	3 2.6 FTE	—

Dense table

The dense table shell: uppercase 11px column labels, hairline rows, tabular numerics, right-aligned numeric columns, and a PersonCell helper. You give it columns and rows. The applied people, events, reporting, and contractor-cost tables in the app are instances of this chrome.

components/surfaces/Table.jsx · applied instance ui_kits/app/detail-screens.jsx

Person	Function	Team	FTE
MFMarco Ferraro Director of Product	Product	Core Platform	1.0
APAlina Petrov Software Engineer II	Engineering	Country Italy	0.8
ENEva Novak Finance partner	Finance	Revenue Ops	1.0

Event log

A vertical timeline of event cards — kind + icon, mono event id, date, title, key/value relationship badges, and an author with relative time. You give it events; planned (future) events get an amber node ring. The append-only ledger event log in the app is an instance; every change is a new record, never a destructive edit.

components/surfaces/EventLog.jsx · applied instance ui_kits/app/detail-screens.jsx

Event log 2 events · most recent first Append-only · every change creates a new record

End · Planned 022 31 Jul 2026

Contract will end

closescontract ends

CG by Chiara Galli · in 71 days

Hire 014 08 Jan 2026

Beatrice Sanna joined Trading

roleProduct Manager typecontractor

CG by Chiara Galli · 133 days ago

Summary

Current-state metrics and a drill-down list. Serif numerals in a hairline grid; each row carries a person-count chip and an allocation bar.

ui_kits/mobile/index.html

Headcount33

FTE28.4

Groups9

Planned3

Event feed

Replaces dense ledger tables on mobile: chronological cards with a kind dot, ledger copy, and a mono event reference.

ui_kits/mobile/index.html

Capacity re-allocated

Ledger entry visible at the selected global view date.

hash: b81244

Contract will end

Marco Silva · effective 31 Jul 2026.

ev: 0c91d2

Detail sheet

Full-height sheet for a person, team, or event: sticky title, current allocation, and the ledger row tied to the view date.

ui_kits/mobile/index.html

Detail

Core Platform

Work group · 12 people · 9.8 FTE

Current allocationWork group

Core Platform 48% · Country Italy 28% · Other 14%

Capacity re-allocated

Ledger entry visible at the selected global view date.

hash: b81244

Decision queue

Pending manager decisions as stacked rows, not a data table. Mobile prepares a ledger event; the full edit stays on desktop.

ui_kits/mobile/index.html

Action sheet

One guided action flow: a single primary action, an explicit impact preview, and the ledger-event preview before confirmation.

ui_kits/mobile/index.html

Action

Review guided action

Small mobile action · explicit impact · ledger event preview.

Impact preview

Before24.2 FTE

After24.7 FTE

Affects 2 people and 1 work group. Effective date stays visible before confirmation.

Ledger event to append

Capacity re-allocated · effective 01 Jul 2026.

draft: ev_pending_capacity

Impact preview

Explains the result before confirmation: before/after totals, affected people, and the effective date.

ui_kits/mobile/index.html

Impact preview

Before24.2 FTE

After24.7 FTE

Affects 2 people and 1 work group. Effective date stays visible before confirmation.

DESIGN.md

SKILL.md

README.md

Primary palette

Neutral palette

Category & on-dark tokens

Typography specimens

Spacing scale

Radius scale

Shadow scale

Lockups

App icon

Runtime build assets

Icon vocabulary

Complete sprite inventory

Usage scale

Motion & interaction

Transitions & hover

Entering surfaces

Press & progress

Reduced motion

Voice & writing

Tone

Casing & spelling

Numbers

Event language

Anti-patterns

Colour & accent

Type & iconography

Depth & motion

Scope & honesty

Accessibility

Focus

Contrast

Keyboard

Touch targets

Button

Specimens

Chip & Avatar

Specimens

Form controls

Input

Select

Textarea

Checkbox

Switch

Segmented

Field primitives

Specimens

Toast

Banner

ConflictBanner

AllocationBar — under / at / over 100%

AllocationChip — legend pill

CodeValue — reference token

Allocation summary

Allocation diff

Sidebar

Date pill

Scrubber

Grid layout

Dense table

Stat strip

Assignment timeline

Event log

Detail list

Command palette

Drawer

Topbar

Bottom nav

Summary

Event feed

Detail sheet

Core Platform

Decision queue

Action sheet

Review guided action

Impact preview

Command search

Date scrubber