# Atlas Design System > Canonical rules document. Category: Custom · Surface: web (dense desktop-first internal tool). > > Source of truth for color, typography, spacing, radii/shadows, components, motion, voice, and anti-patterns. Treat this file as authoritative; downstream agents must read it before generating any artifact that links `colors_and_type.css` or `styles.css`. --- ## 1. Product context & visual theme Atlas is a standalone internal product — an **organisation ledger** for workforce management. Every organisational fact (who sits in which work group, at what capacity %, reporting to whom, in which function) is stored as a **time-bounded event** rather than a mutable record. The visual language is a **dense desktop-first admin tool** in the spirit of Linear / Retool / Mercury Treasury, optimised for HR / Finance / Engineering leadership. It pairs: - **A raspberry-coral accent (Flush)** used sparingly — a single primary action, the active selection, and the contractor encoding. - **Warm plum-charcoal neutrals (Plum)** — the dark sidebar is `plum-900` (#241420), the app canvas is `plum-100` (#F5F1F4). The whole product reads premium-fintech rather than neon. - **An editorial display serif (Newsreader)** for page titles and big numerals, paired with a **humanist grotesk (Hanken Grotesk)** for all UI text, and **IBM Plex Mono** for event hashes / NetSuite refs / cost centres. What this system is **not**: - Not a marketing site. No hero gradients, no oversized headlines, no decorative illustration. - Not a generic Inter/Roboto SaaS sketch. The Newsreader serif is load-bearing. - Not a beige/peach "AI canvas." The neutrals are explicitly **warm plum**, not warm beige. - Not a single app mockup. The desktop and mobile apps are applied kits that prove the system; the root package is a design-system catalog. ### Design-system package contract Atlas is governed in layers. Maintain the layer that owns the change: | Layer | Files | Rule | |-------|-------|------| | Package index | `index.html` | Must catalogue foundations, components, previews, applied kits, and quality gates. It must not collapse into only `ui_kits/app/index.html`. | | Rules | `DESIGN.md` | Canonical product, visual, interaction, mobile, and anti-pattern contract. | | Tokens | `tokens/`, `styles.css`, `colors_and_type.css` | Token source first; downstream entries second. Do not invent one-off colours in applied kits. | | Components | `components/` | Reusable primitives with source, typing, prompt companion, and preview coverage. | | Preview cards | `preview/`, `guidelines/` | Focused evidence cards for auditing system foundations. They are not product screens and not alternate themes. | | Applied kits | `ui_kits/app/`, `ui_kits/mobile/` | Product examples that consume the system. They can reveal missing components, but they do not replace the component layer. | | Evidence | `source_examples/`, `context/` | Preserved source used for fidelity comparisons. | | Tests | `tests/` | Contract tests that prevent package-shape regressions and product-fidelity regressions. | If a UI kit exposes a missing pattern, integrate it back into the system: document the rule in `DESIGN.md`, add or update reusable components/previews when the pattern is generic, and add a regression test. Do not leave the fix only inside the applied app. --- ## 2. Color Defined in [`tokens/colors.css`](tokens/colors.css) and aggregated in [`colors_and_type.css`](colors_and_type.css). ### Accent — Flush (raspberry-coral) | Token | Hex | Use | |--------------------|------------|----------------------------------------------------| | `--at-flush-50` | `#FFF1F4` | Accent wash / row hover | | `--at-flush-100` | `#FFE2E9` | Active row, chip background | | `--at-flush-200` | `#FFC8D4` | — | | `--at-flush-300` | `#F7A3B6` | — | | `--at-flush-400` | `#F0738F` | Decorative gradient pair | | `--at-flush-500` | `#E94E72` | Primary button :hover | | `--at-flush-600` | `#E03A63` | **Primary accent** — buttons, dots, contractor kind | | `--at-flush-700` | `#C12B51` | Active text, focus border | | `--at-flush-800` | `#981F3F` | — | | `--at-flush-900` | `#6C162C` | — | ### Neutral — Plum (warm plum-charcoal) | Token | Hex | Use | |--------------------|------------|----------------------------------------------------| | `--at-plum-950` | `#1E1019` | Deepest dark surface | | `--at-plum-900` | `#241420` | Sidebar, scrubber, dark overlays | | `--at-plum-800` | `#3C2A38` | — | | `--at-plum-700` | `#5D4A57` | Secondary copy, `--fg-3`, hover border | | `--at-plum-600` | `#877A84` | Tertiary / meta copy, `--fg-4` | | `--at-plum-500` | `#B2A8AF` | Sidebar muted label | | `--at-plum-400` | `#D1CACF` | `--border-line`, sidebar inactive text | | `--at-plum-300` | `#E3DDE1` | `--border-subtle`, the default hairline | | `--at-plum-200` | `#EEE9EC` | Ghost-button :hover, employee chip bg | | `--at-plum-100` | `#F5F1F4` | App canvas (`--bg-tint`), table header, row hover | | `--at-plum-50` | `#FAF8FA` | Empty matrix cell | ### Base + semantic - `--at-black #150F14` · `--at-ink #221C26` · `--at-white #FFFFFF` - **Success** `--at-success-fg #1B6E48` on `--at-success-bg` (13% alpha green) - **Warning** `--at-warning-fg #8A5A12` on `--at-warning-bg` (16% alpha amber) - **Info** `--at-info-fg #2F5B92` on `--at-info-bg` (14% alpha blue) - **Role change** `--at-role #B07FE0` lavender (used only on role-change event nodes) ### Category tints (work-group categories) `--at-cat-1 #E03A63` Bubble · `--at-cat-2 #3F73B5` Country · `--at-cat-3 #C58A2C` Other. ### Semantic role tokens (always reach for these, not raw ramps) ``` --fg-1 (black) → primary body & headings --fg-2 (ink) → default text --fg-3 → secondary copy --fg-4 → tertiary / meta --fg-accent → flush-600 --fg-inverse → white --bg-page → white --bg-tint → plum-100 (app canvas) --bg-tint-accent → flush-50 --bg-dark → plum-900 (sidebar / overlays / scrubber) --bg-accent → flush-600 --border-subtle → plum-300 (default hairline) --border-line → plum-400 (stronger divider) --border-accent → flush-600 --kind-employee → plum-900 --kind-contractor → flush-600 ``` ### Color rules - **One accent, used sparingly.** Flush appears on the single primary action per surface, the active row marker, the contractor encoding, allocation segments, and the focus ring — nothing else. - **Two-colour person encoding everywhere.** Employees read `plum-900`, contractors read `flush-600`. AllocationBar / Avatar / Chip / matrix split bars all honour the same two anchors. - **Backgrounds are flat plum tints only.** No gradients, no imagery, no texture. The single exception is the sidebar avatar fallback (`linear-gradient(135deg, flush-400 → flush-700)`) — a deliberate sparkle of identity. - **Shadows are plum-tinted**, not neutral black — see `--shadow-sm/md/lg`. Depth is hairline borders + soft tinted elevation, never heavy. --- ## 3. Typography Defined in [`tokens/typography.css`](tokens/typography.css) and [`tokens/fonts.css`](tokens/fonts.css). ### Stacks ``` --font-display "Newsreader", "Spectral", Georgia, serif --font-sans "Hanken Grotesk", "Helvetica Neue", Arial, sans-serif --font-mono "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, monospace ``` Loaded from Google Fonts via `tokens/fonts.css` (and re-loaded by `colors_and_type.css`). For production, swap for licensed binaries dropped into [`fonts/`](fonts/) and rewrite `@font-face` rules there. ### Type scale (dense internal-tool) | Token | Size | Line | Use | |-------------------|-------|-------|--------------------------------------| | `--fs-display-lg` | 48px | 52px | Page hero numerals | | `--fs-h1` | 32px | 38px | Page titles (display serif) | | `--fs-h2` | 24px | 30px | Card section titles | | `--fs-h3` | 20px | 26px | Drawer / modal titles | | `--fs-h4` | 16px | 22px | Card titles (serif) | | `--fs-h5` | 14px | 20px | Sans semibold heading | | `--fs-h6` | 13px | 18px | Card header label | | `--fs-body-1` | 13px | 18px | Default UI text | | `--fs-body-2` | 12px | 16px | Table cell / dense body | | `--fs-body-3` | 11px | 15px | Meta / caption / role line | ### Helpers - `.at-h1`/`.at-h2`/`.at-h3` — display serif, 600 weight, `-0.01em` tracking. - `.at-h5` — sans 600 (used for card titles in UI chrome). - `.at-body` / `.at-meta` — Hanken Grotesk body and meta. - `.at-mono` — IBM Plex Mono, tabular figures. - `.at-num` — display serif, 600, tabular figures (big metric numerals). - `.at-eyebrow` — sans 600, 10px, `0.16em` tracking, uppercase, accent colour. ### Rules - **Display serif for page titles, card headlines, and big numerals only.** UI chrome (buttons, labels, body) is Hanken Grotesk. - **Tabular figures everywhere.** `font-variant-numeric: tabular-nums` is on `body`, on `.at-num`, and on every component that renders a metric. - **Eyebrows are uppercase, tracked `0.16em`, accent-coloured, 10px.** Not 12px. Not navy. Not bold-sans. - **Mono is reserved for event hashes, NetSuite refs, cost centres, keyboard hints, and any code-like identifier.** Never use mono for body copy. - **No Inter, Roboto, Arial as display.** Body fallback is allowed (`Helvetica Neue → Arial`), but the display face is always a serif. --- ## 4. Spacing Defined in [`tokens/spacing.css`](tokens/spacing.css). ``` --space-2xs 4px (tight icon gap) --space-xs 8px (chip gap, control gap) --space-sm 12px (card-head padding) --space-md 16px (default card padding) --space-lg 24px (section gap) --space-xl 32px (page padding) --space-2xl 40px --space-3xl 48px --space-4xl 64px --space-5xl 80px ``` ### Density anchors | Token | Value | Where | |--------------------|-------|-----------------------------------------| | `--row-height` | 36px | Table rows, nav items, tree rows | | `--control-height` | 28px | Buttons, pills, inputs | | `--cell-pad-y` | 16px | Matrix cell vertical padding | | `--cell-pad-x` | 18px | Matrix cell horizontal padding | ### Rules - **4px base grid.** Everything snaps to multiples of 4. - **Dense but breathable.** 28px controls, 36px rows. Resist the temptation to inflate (Atlas is a power-user tool). - **Page padding is `20–24px` vertical · `24–28px` horizontal.** Cards sit inside with 14px `card-head` padding and 12px between rows. --- ## 5. Layout & composition ### App shell (`templates/atlas-page/AtlasPage.dc.html`) ``` ┌──────────┬─────────────────────────────────────────────────┐ │ Sidebar │ Topbar (48px, breadcrumb · spacer · pill · btn) │ │ 224px ├─────────────────────────────────────────────────┤ │ plum-900 │ Page (eyebrow + h1 + meta) │ │ │ StatStrip (4 KPI tiles, hairline-joined) │ │ │ Card: People & allocation (rows of avatar + │ │ │ name+role + chip + AllocationBar + status chip) │ └──────────┴─────────────────────────────────────────────────┘ ``` - **Sidebar:** 224px, `--at-plum-900` background, white text, accent-tinted active row (`rgba(224,58,99,0.16)`) with a 2px flush bar on the left edge. - **Topbar:** 48px, white/translucent, `border-bottom: 1px solid --border-subtle`, breadcrumb on the left, "As of Today" pill + primary button on the right. - **Canvas:** `--bg-tint` (plum-100). Cards float as white rectangles with `--radius-md` and `--border-subtle`. ### Information density - Tables use **table header bg = `--at-plum-100`** with `10px / 0.06em tracked / uppercase` column headers. - Matrix cells render **headcount as serif 18px**, optional **FTE as 10px meta**, and a **4px split bar** showing employee vs contractor share. - Cards group hairline-divided rows. Header is a single 12–14px padded row with a 13px semibold title and a 11px meta on the right. ### Responsive posture Atlas is desktop-first for full editing. Minimum desktop working width is `1280px`; below that the sidebar collapses to icon-only and dense matrices scroll horizontally. Mobile is now a **consultation + guided actions** mode, not a shrunken copy of the desktop app. ### Mobile operating model Mobile Atlas must support high-confidence inspection and small ledger-safe actions. It must not expose full-edit workflows or dense desktop maintenance screens. - **Consultation first:** people, team, reporting line, current allocation, compact history, event status, and date context are readable in one-hand layouts. - **Guided actions only:** mobile actions are short, explicit flows with a confirmation sheet, impact preview, and ledger-event outcome. They are never freeform matrix edits, bulk changes, cost-table editing, or organisation restructuring. - **No future-domain commitments:** mobile patterns stay generic (`Guided action`, `Decision queue`, `Impact preview`, `Event feed`) so future workflows can plug in without the design system naming a feature before the product owns it. - **Same Atlas system:** mobile uses the same Flush + Plum palette, Newsreader / Hanken / IBM Plex Mono stacks, semantic tokens, status colours, and ledger language. It is not a separate mobile brand. - **Native touch contract:** touch targets are at least 44px, body copy is at least 14px, meta copy is at least 12px, and hover-only affordances always have visible touch equivalents. Mobile surface primitives: | Primitive | Purpose | Contract | |-----------|---------|----------| | `MobileTopbar` | Current workspace/date + global search + global time-machine actions | 56px high, white surface, hairline bottom border, icon-only search/time controls | | `MobileBottomNav` | Primary consultation routes: Work groups, Functions, People | 64px high, 3 items, Flush only for active route | | `MobileCommandSearch` | Full-screen search and jump targets | Search field first, grouped results, keyboard hints hidden on touch | | `MobileSummary` | Person/team current state | Serif metric or title, compact allocation bar, status chip | | `MobileDetailSheet` | Person/team/event detail | Full-height sheet, sticky header, ledger rows and next action | | `MobileActionSheet` | Guided action flow | One primary action, one cancel, explicit ledger event preview | | `MobileDecisionQueue` | Manager/leadership pending decisions | Stacked decision rows with impact preview, not a data table | | `MobileImpactPreview` | Explain the result before confirmation | Before/after allocation, affected people, effective date | | `MobileEventFeed` | Replace ledger tables on mobile | Chronological cards with mono event IDs and status chips | | `MobileDateScrubber` | Global compact time-machine control | Bottom sheet timeline opened from the topbar; selected date applies across Work groups, Functions, and People | Desktop-only surfaces must stay desktop/tablet: matrix editing, bulk structural changes, contractor cost tables, full event drawer composition, and dense reporting tables. On mobile these become read-only summaries, drill-down lists, or guided action handoffs. --- ## 6. Components All components are framework-light React (no deps) that inject their own scoped `