# Atlas Design System
A reusable Open Design package distilled from the **Atlas** prototype — a workforce-organisation ledger built in this workspace. Atlas treats every organisational fact (who sits where, at what capacity %, reporting to whom) as a **time-bounded event**, and its design system carries that posture into a dense, desktop-first internal tool.
This package gives downstream agents everything they need to generate well-branded Atlas surfaces, prototypes, and slides without re-deriving tokens or guessing voice.
---
## Product Overview
> Sourced from the local code snapshot under `context/local-code/atlas-design-system/files/` (originally selected from the Atlas Design System workspace prototype). See [`context/source-context.md`](context/source-context.md) for the intake provenance.
**Atlas** is an internal product — a desktop-first workforce platform built around an organisation ledger. It supports HR, Finance, and Engineering leadership: the tool provides time-bounded events for every organisational change, includes a work-group tree by category (Bubble / Country / Other), and offers per-person allocation accounting with a signature stacked-bar visualization. The desktop application is designed to read like a power-user tool in the spirit of Linear and Retool, not a marketing dashboard.
Atlas mobile is a separate operating mode: **consultation + guided actions**. It uses the same visual system, but it does not expose desktop full-edit mode, dense matrix editing, bulk structural changes, or cost-table maintenance. Mobile surfaces are for reading current state/history, searching, opening details, and completing small ledger-safe workflows through explicit action sheets.
### Primary UI surfaces (evidenced by source files)
| Surface | Source | What it does |
|-----------------------------|-------------------------------------------------------|---------------------------------------------------------------------------|
| **App shell** | `templates/atlas-page/AtlasPage.dc.html` | Dark 224px sidebar + 48px topbar + KPI strip + people allocation card |
| **Dimension Explorer** | `ui_kits/app/explorer.jsx` | Default workspace: dimensions, work-group tree, detail pane, date-aware totals |
| **Workforce overview** | `ui_kits/app/overview.jsx` · `ui_kits/app/` | Organisation KPIs, matrix entry, and product-level routing |
| **People allocation row** | `components/workforce/workforce.card.html` | Avatar + name+role + kind chip + AllocationBar + status chip |
| **Person history (ledger)** | `ui_kits/app/detail-screens.jsx` | Side panel, Gantt, git-log timeline of capacity / role / hire / end events |
| **Matrix view** | `ui_kits/app/overview.jsx` | Function × work-group grid with split bar (employee vs contractor) |
| **Operational overlays** | `ui_kits/app/overlays.jsx` | Command palette, event drawer, and time-machine scrubber |
| **Ledger tables** | `ui_kits/app/detail-screens.jsx` | People, events, reporting, contractor cost, function, and timeline surfaces |
| **Mobile consultation kit** | `ui_kits/mobile/index.html` | Touch-first Work groups, Functions, People, global search/time machine, detail sheet, and guided action |
### Core capabilities (visible in the captured source)
- **Time-bounded events instead of mutable records** — every assignment is reconstructed through date-aware helpers such as `assignmentAt`, `peopleAt`, and `dimensionTotals` in `ui_kits/app/data.js`.
- **Two-colour person encoding** — employees read plum, contractors read flush; visible in `Avatar`, `Chip`, `AllocationBar`, and the matrix split bars.
- **Allocation accounting** — `AllocationBar` stacks per-work-group %, hatches the unallocated tail under 100%, saturates over 100% as a warning.
- **KPI strip** — `StatStrip` joins serif tabular numerals into a single hairline-bordered rectangle (Headcount · FTE · Contractors · Monthly spend).
- **Workforce tree + matrix** — work groups are categorised (Bubble / Country / Other) and rendered as a tree on the left, with a detail pane on the right and a matrix view that splits each cell by kind.
- **Command and drawer workflow** — the applied app exposes `⌘K`, event drawers, and the time scrubber as first-class product surfaces, not as preview-only controls.
- **Mobile consultation mode** — the mobile kit exposes read-first Atlas surfaces and generic guided actions without committing to future domain-specific workflows.
---
## Source context
This package was built from a single linked local code folder; no GitHub or Figma source was attached.
- **Atlas Design System workspace prototype** — local code snapshots originally selected via the Open Design browser intake.
- Provenance: `context/source-context.md` lists the snapshot file inventory.
- Snapshots: `context/local-code/atlas-design-system/files/` mirrors the captured Atlas folder (tokens, components, guidelines, templates, ui_kits, assets, `_ds_manifest.json`, `_ds_bundle.js`, `_adherence.oxlintrc.json`).
- Connector: none (Atlas has no GitHub or Figma link — the prototype is the source of truth).
Every rule in [`DESIGN.md`](DESIGN.md), every token in [`colors_and_type.css`](colors_and_type.css), and every preview card under [`preview/`](preview/) is derived from these snapshots — no values were invented from prose.
---
## Design-system governance
Atlas must be maintained as a layered design-system package, not as a single product mockup.
| Layer | Canonical location | Contract |
|-------|--------------------|----------|
| **Package index** | [`index.html`](index.html) | Catalogues the system: foundations, components, applied kits, and quality gates. It must not iframe directly into only one product app. |
| **Rules** | [`DESIGN.md`](DESIGN.md) | Source of truth for product posture, tokens, typography, layout, component behaviour, mobile contract, voice, and anti-patterns. |
| **Tokens** | [`tokens/`](tokens/) · [`styles.css`](styles.css) · [`colors_and_type.css`](colors_and_type.css) | `tokens/` is the modular source; `styles.css` imports it; `colors_and_type.css` is the single-file downstream entry. |
| **Reusable components** | [`components/`](components/) | Framework-light primitives with source, `.d.ts`, prompt companion, and preview coverage. |
| **Reference previews** | [`preview/`](preview/) · [`guidelines/`](guidelines/) | Focused cards for auditing one foundation/component family at a time. They are not separate themes. |
| **Applied kits** | [`ui_kits/app/`](ui_kits/app/) · [`ui_kits/mobile/`](ui_kits/mobile/) | Product-level examples that prove the system works. They depend on the system; they are not the system root. |
| **Source evidence** | [`source_examples/`](source_examples/) · [`context/`](context/) | Preserved import evidence used to resolve disputes about fidelity and behaviour. |
| **Quality gates** | [`tests/`](tests/) | Contract tests for package shape, app fidelity, mobile IA, scrubber, and icon assets. |
When changing Atlas, start at the lowest layer that owns the behaviour. Token changes belong in `tokens/` and `DESIGN.md`; component changes belong in `components/` plus previews; product-flow changes belong in `ui_kits/` plus the relevant contract test. Do not patch only an applied app and call the design system updated.
---
## Package contents
```
.
├── index.html Design-system catalog: foundations, components, applied kits, quality gates
├── DESIGN.md Canonical rules (this is the source of truth for the visual contract)
├── README.md This file
├── SKILL.md Claude-style skill entry (YAML frontmatter + agent guidance)
├── colors_and_type.css Single-file CSS entry — webfonts + every CSS custom property
├── styles.css Modular CSS entry — @imports each tokens/*.css file
│
├── tokens/ Per-concern token files (consumed by styles.css)
│ ├── colors.css
│ ├── typography.css
│ ├── spacing.css
│ ├── radii-shadows.css
│ └── fonts.css
│
├── assets/ Brand atoms — logo, mark, inverse, inline icon sprite, brand card
│ ├── atlas-app-icon.svg
│ ├── atlas-logo.svg
│ ├── atlas-logo-inverse.svg
│ ├── atlas-mark.svg
│ ├── icons.svg
│ └── brand.card.html
│
├── build/ Runtime asset surfaces (Claude-style build contract)
│ ├── icon.svg App / installer icon — 1024px plum canvas + Flush mark
│ ├── icon-1024.png PNG export for app-store / installer surfaces
│ ├── icon-512.png PNG export for desktop launchers
│ ├── icon-192.png PNG export for web manifests
│ ├── apple-touch-icon.png 180px Apple touch icon
│ ├── favicon-32.png 32px favicon export
│ ├── logo.svg Light lockup
│ ├── logo-inverse.svg Dark lockup
│ └── icons-sprite.svg Full Atlas line-icon sprite (24×24, 1.5px stroke)
│
├── fonts/ Reserved for self-hosted font binaries (currently Google Fonts CDN)
│ └── README.md
│
├── source_examples/ Preserved high-signal source code from the captured snapshot
│ ├── Button.jsx
│ ├── Chip.jsx
│ ├── Avatar.jsx
│ ├── AllocationBar.jsx
│ ├── StatStrip.jsx
│ ├── atlas-data.js Mock workforce dataset (people, allocations, events, helpers)
│ ├── AtlasScreens.jsx Full Overview + Person screen logic
│ └── atlas-runtime.js The runtime that boots AtlasScreens with the dataset
│
├── components/ Reusable React components (framework-light, no deps)
│ ├── core/ Button, Chip, Avatar, Field, FieldRow, Hint, ValidationMessage
│ ├── feedback/ Toast, Banner, ConflictBanner
│ └── workforce/ AllocationBar, StatStrip / StatTile
│
├── guidelines/ Standalone HTML specimen cards (Color, Type, Spacing, Radii/Shadows, Forms, Feedback)
│
├── templates/
│ └── atlas-page/ App shell template — sidebar + topbar + KPI strip + people card
│
├── preview/ Focused Claude-style review cards — see Preview Manifest below
│
├── ui_kits/
│ ├── app/ Runnable applied interface: full Atlas Workforce prototype
│ │ ├── index.html
│ │ ├── icon-paths.js
│ │ ├── data.js
│ │ ├── app-shell.jsx
│ │ ├── allocation.jsx
│ │ ├── overview.jsx
│ │ ├── explorer.jsx
│ │ ├── detail-screens.jsx
│ │ ├── overlays.jsx
│ │ ├── app.jsx
│ │ ├── kit.css
│ │ ├── README.md
│ │ └── components/
│ └── mobile/ Consultation-first mobile reference kit
│ ├── index.html
│ └── README.md
│
└── context/ Intake provenance and original snapshots
├── source-context.md
└── local-code/atlas-design-system/files/
```
---
## Preview Manifest
The `preview/` directory holds focused review cards. Each card is a small self-contained HTML page that links `colors_and_type.css` and demonstrates one slice of the system, so reviewers can audit the package one foundation at a time.
| Path | What to inspect | Source-backed evidence |
|------------------------------------------|------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| [`preview/colors-primary.html`](preview/colors-primary.html) | Flush ramp 50–900 with `--at-flush-600` as primary | `tokens/colors.css` (flush ramp) |
| [`preview/colors-theme-light.html`](preview/colors-theme-light.html) | Light app canvas: plum neutrals + flush accent on bg-tint surfaces | `tokens/colors.css` (plum ramp + semantic bg roles) |
| [`preview/colors-theme-dark.html`](preview/colors-theme-dark.html) | Dark component surfaces inside the single Atlas system (`--bg-dark`) | `templates/atlas-page/AtlasPage.dc.html` sidebar · `tokens/colors.css` |
| [`preview/colors-semantic.html`](preview/colors-semantic.html) | Success / warning / info / role-change pills + the 3 category tints | `tokens/colors.css` (semantic + category) |
| [`preview/typography-specimens.html`](preview/typography-specimens.html) | Newsreader display, Hanken Grotesk UI, IBM Plex Mono — full type scale | `tokens/typography.css` · `tokens/fonts.css` |
| [`preview/spacing-tokens.html`](preview/spacing-tokens.html) | 4px-grid scale 2xs → 5xl + density anchors (row 36, control 28, cell 16×18) | `tokens/spacing.css` |
| [`preview/spacing-radius.html`](preview/spacing-radius.html) | Radii xs / sm / md / lg / pill | `tokens/radii-shadows.css` |
| [`preview/spacing-shadows.html`](preview/spacing-shadows.html) | Plum-tinted shadows sm / md / lg + focus ring | `tokens/radii-shadows.css` |
| [`preview/components-buttons.html`](preview/components-buttons.html) | `Button` (default / primary / ghost / icon-only) at 28px control height | `components/core/Button.jsx` |
| [`preview/components-inputs.html`](preview/components-inputs.html) | Chip tones + Avatar sizes + the kind-encoding contract | `components/core/Chip.jsx` · `components/core/Avatar.jsx` |
| [`preview/components-fields.html`](preview/components-fields.html) | Field, FieldRow, Hint, and ValidationMessage for M2 drawer event creation | `components/core/Field.jsx` · `FieldRow.jsx` · `Hint.jsx` · `ValidationMessage.jsx` |
| [`preview/components-feedback.html`](preview/components-feedback.html) | Toast, Banner, and ConflictBanner for event flow feedback | `components/feedback/Toast.jsx` · `Banner.jsx` · `ConflictBanner.jsx` |
| [`preview/components-workforce.html`](preview/components-workforce.html) | `AllocationBar` (under / at / over 100%) + `StatStrip` KPI strip | `components/workforce/AllocationBar.jsx` · `StatStrip.jsx` |
| [`preview/icons.html`](preview/icons.html) | Full 81-symbol icon sprite grouped by use + usage examples in chrome/nav/chip/input | `assets/icons.svg` · `build/icons-sprite.svg` |
| [`preview/brand-assets.html`](preview/brand-assets.html) | Real brand files loaded via `` / `