Canonical
Rules document
The file every downstream agent must read before producing Atlas work.
DESIGN.md
Atlas Design System
Use the tree to inspect foundations, component families, guidelines, applied kits, and quality gates without leaving the catalog.
Atlas is a layered design-system package: canonical rules, tokens, reusable components, preview evidence, guidelines, applied UI kits, source evidence, and tests. The root catalog should help you move across those layers without mistaking one applied app for the whole system.
Tokens
Token entry
Aggregated color, type, spacing, radius, shadow, and font contracts.
styles.css
Applied kits
Product examples
Desktop and mobile implementations prove the system, but do not replace it.
ui_kits/
Canonical
DESIGN.md
Design-system package contract, foundations, component rules, mobile contract, and applied-kit boundaries.
Agent guide
SKILL.md
Instructions for generating or extending Atlas components without treating an app screen as the system.
- README.mdDesign-system governance, layer map, and entry-point guidance.
- tokens/Canonical colors, typography, spacing, radii, shadows, and font declarations.
- components/Reusable React primitives with typings and agent prompts.
- preview/Specimen cards that prove component and token behavior.
- guidelines/Usage rules for forms, feedback, spacing, and UI type.
- ui_kits/Applied desktop and mobile reference implementations.
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
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
--fs-h1
Workforce overview
--fs-h2
People & allocation
--fs-h3
Capacity & cost
Headcount30
FTE24.2
Contractors6
Monthly spend€47.7k
UI · Hanken Grotesk
--fs-h5
Reporting tree (10)
--fs-body-1
Atlas treats every organisational fact as a time-bounded event rather than a mutable record.
--fs-body-2
Staff Engineer · Milan · Reports to Elena Russo
--fs-body-3
.at-eyebrow
Monthly contractor spend
Mono · IBM Plex Mono
.at-mono
CC-AP-001 · NS-2042 · e-021 · 31 Jul 2026
numerals
€540 · 4 days/wk · €11.7k/month
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.
--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.
--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
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
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
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
Arrows and hierarchy
11 icons
Finance and allocation
13 icons
Charts and planning
8 icons
People and communication
9 icons
Controls and navigation
11 icons
Security and access
7 icons
Files and actions
7 icons
Signals and objects
12 icons
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.
Commands
The Core command primitive that backs every actionable surface — drawer footers, table row actions, header controls, and inline confirmations.
Button
Command primitive
Primary, secondary, ghost, danger, icon, and disabled command states. Renders consistent height, focus ring, and loading spinner so every entry point reads the same.
components/core/Button.jsxIdentity & status
Compact metadata primitives used in tables, lists, and dense headers. Variants are driven by props instead of new components.
Chip
Status & metadata
Inline status, tag, and filter pill with neutral, success, warning, and danger tones. Drives allocation legends, event states, and inline filters.
components/core/Chip.jsx
Avatar
Identity
Single-letter and image avatar with size and tone variants. Used in workforce explorer rows, assignee summaries, and compact stacks.
components/core/Avatar.jsxFields & validation
Drawer form primitives promoted from the workforce app. They share label, hint, and validation rhythm so drawers feel consistent across event types.
Field
Form primitive
Labelled input wrapper with hint slot, validation slot, optional adornments, and consistent focus styling. The base of every drawer form row.
components/core/Field.jsx
FieldRow
Form primitive
Two-column row that pairs related fields (start/end, role/grade, currency/amount) while preserving Field's vertical rhythm and validation spacing.
components/core/FieldRow.jsx
Hint
Field guidance
Secondary helper text for Field. Carries the same metadata tone used across tables and matrix cells so guidance never competes with errors.
components/core/Hint.jsx
ValidationMessage
Field validation
Error, warning, and success message used directly under Field. Aligns with the Feedback family tones so errors look the same in drawers and banners.
components/core/ValidationMessage.jsxButton
The Core command primitive. Primary, secondary, ghost, danger, and icon variants share height, focus ring, and loading spinner so every entry point reads the same.
Specimens
Rendered directly in the catalog as native markup — 28px tall, hairline border, flush focus ring. Primary uses --at-flush-600; default sits on white; ghost is transparent until hovered.
Variants
With leading icon
Focus-visible · ring
Same ring on every focusable element: --ring-accent.
Chip & Avatar
Compact metadata primitives used in tables, lists, and dense headers. Variants are driven by props instead of new components.
Specimens
Two-colour person encoding everywhere: employees read plum, contractors read flush. The same anchors appear in the chip, the avatar, and downstream in AllocationBar / matrix split bars.
Chip — tones
Employee
Contractor
100%
80%
Ended
Engineering
Avatar — sizes & kind tinting
MF
MF
MF
Marco Ferraro
Director of Product · Employee
AP
AP
AP
Alina Petrov
Software Engineer II · Contractor
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. Use the tree's Forms guideline for usage rules.
Field — anatomy
Future-dated changes are accepted
Field — states
Uses the shared Flush focus ring.
Disabled fields reduce the whole wrapper.
Allocations must total 100%
FieldRow — 2 columns
FieldRow — 3 columns
Hint — tones
Neutral helper outside a single field.
Effective date is in the past.
Allocations must total 100%.
Validation messages
! Allocations must total 100% — currently 80%
! Effective date is in the past
i Future-dated changes are accepted
✓ All allocations balanced
Toast
Transient post-commit feedback. Success, error, and info tones share anatomy: status glyph, title, and optional description.
✓
Event committed
Capacity re-allocated for Marco Ferraro
!
Could not commit
Server unreachable. Retrying…
i
View date changed
Showing organisation as of 01 Jan 2024
Banner
Persistent section status the user keeps while working: time-travel, connection, and environment states.
ConflictBanner
Full drawer-body replacement for concurrency conflicts. Requires a reload or discard decision; never used for validation or network errors.
!
This drawer is out of date
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.
Marco FerraroDirector of Product
100%
Alina PetrovSoftware Engineer II · Contractor
80%
Matteo GrecoStaff Engineer
110%
StatStrip — KPI strip
Joins KPI tiles into one hairline-bordered rectangle: uppercase label, display-serif numeral, and optional meta line.
Headcount
30
FTE
24.2
Contractors
6
Monthly spend
€47.7k
Test
Design system contract
Validates the root catalog and layered package shape.
node tests/design-system-contract.test.jsTest
M2 component families
Validates form, validation, and feedback primitive coverage.
node tests/m2-component-families.test.jsTest
Mobile contract
Validates Work groups, Functions, People, global search/time machine, and spacing constraints.
node tests/mobile-contract.test.jsTest
Brand assets
Validates app icon source/runtime parity and exported PNG dimensions.
node tests/app-icon.test.js