# ui_kits/app/ — Atlas Workforce prototype

Runnable applied interface for the Atlas design system. This entry should match the imported Claude Design prototype, not the reduced component demo.

Open [`index.html`](index.html) directly for the full-size app. The project root [`../../index.html`](../../index.html) embeds the same file for Open Design preview.

This README documents the applied kit structure, component files, usage workflow, design notes, and source basis for future reuse.

## Applied kit structure

```
ui_kits/app/
├── index.html          Browser entry — mounts the routed prototype app
├── kit.css             Full applied app styles consuming ../../styles.css tokens
├── icon-paths.js       Inline line-icon registry
├── data.js             Time-bounded workforce ledger, allocation helpers, event log
├── app-shell.jsx       App provider, route/date state, sidebar, topbar, shared UI
├── allocation.jsx      AllocationBar, AllocationStrip, AllocationDiff
├── overview.jsx        Overview and matrix surfaces
├── explorer.jsx        Dimension Explorer default surface
├── detail-screens.jsx  Team, person, functions, reporting, people, events, costs,
│                       timeline, Gantt and detail panels
├── overlays.jsx        Scrubber, command palette, event drawer
├── app.jsx             Routed app entry
└── components/         Earlier modular component experiment kept for reference
```

## Component files

- `app-shell.jsx` owns the app provider, route state, selected `viewDate`, sidebar, topbar, shared buttons, chips, avatar and table helpers.
- `allocation.jsx` owns allocation primitives: `AllocationBar`, `AllocationStrip`, and `AllocationDiff`.
- `overview.jsx` owns the organisation overview and function × work-group matrix.
- `explorer.jsx` owns the default Dimension Explorer (`ExplorerScreen`, `ExpNode`, `ExpDetail`).
- `detail-screens.jsx` owns work-group detail, person detail, Gantt, git log, functions, reporting, people, events, costs, and timeline screens.
- `overlays.jsx` owns the app overlays: scrubber, command palette, and event drawer.
- `components/` keeps the earlier modular UI-kit experiment available for agents that need small isolated examples.

## Components — what they map to in Atlas

| File | Role in Atlas | Source-of-truth backing |
|------|---------------|-------------------------|
| `app-shell.jsx` | App shell, navigation, topbar, route/date state | Attached Claude Design prototype |
| `allocation.jsx` | Allocation strip, bar, and before/after diff | `components/workforce/AllocationBar.jsx` plus prototype usage |
| `overview.jsx` | Overview and matrix surfaces | Prototype `OverviewScreen` / `OverviewMatrix` |
| `explorer.jsx` | Default Dimension Explorer workspace | Prototype `ExplorerScreen`, `ExpNode`, `ExpDetail` |
| `detail-screens.jsx` | Team, person, people, events, costs, functions, reporting, timeline | Prototype routed detail screens |
| `overlays.jsx` | Scrubber, command palette, event drawer | Prototype overlays and Atlas dark-surface rules |

## Required Surfaces

The app must expose the prototype-level surfaces:

- Dimension Explorer: default workspace with all dimensions, tree nodes, detail pane, filters, and date-aware totals.
- Overview: organisational KPI workspace and matrix entry.
- Matrix: function by work-group grid with headcount, FTE, and employee/contractor split bars.
- Work groups and team detail.
- Functions with role rows and role creation drawer.
- Line reporting tree.
- People directory and person detail with side panel, allocation history, Gantt and git-log event history.
- Event log and contractor costs.
- Time machine plus the bottom scrubber. Moving the scrubber changes the app-wide `viewDate` and recomputes people, assignments, totals and planned events.
- Command palette (`⌘K` / `Ctrl+K`) and event drawer.

## Design Contract

- Atlas has one visual system. Dark sidebar and scrubber are dark components inside the same system, not a separate dark theme.
- Use `../../styles.css` / token variables, not ad hoc colour ramps.
- Keep the desktop-first density: 224px sidebar, 48px topbar, 28px controls, 36px rows.
- Keep this kit as the desktop/tablet full-edit app. Phone-sized Atlas surfaces live in `../mobile/` and are consultation + guided actions, not a reduced copy of this app.
- Keep the append-only ledger language: "Capacity re-allocated", "Role changed", "Contract will end".

## Usage workflow

1. Open `index.html` for the full applied product surface.
2. Use the sidebar to verify every route: Overview, Matrix, Work groups, Functions, Line reporting, People, Time machine, Events, and Contractor costs.
3. Use `⌘K` / `Ctrl+K` to verify command palette actions and jump targets.
4. Open Time machine, then `Open scrubber`, and move the range input to verify `viewDate` recomputation across app screens.
5. Open `New event` / event actions to verify the drawer forms.

## Design notes

- The `--mf-*` names in `kit.css` are compatibility aliases mapped onto Atlas `--at-*` tokens; do not treat them as a separate Moneyfarm palette.
- The default surface is the Dimension Explorer, because the imported prototype used it as the main working view.
- The app is desktop-first. Below the intended desktop width, use horizontal scroll for dense matrices rather than collapsing data into mobile cards. Use `../mobile/index.html` for phone UX patterns.
- The old modular `components/` files are references only; the canonical runnable app is the extracted routed prototype.

## Source basis

This app was extracted from the attached Claude Design standalone bundle `mq9u29oo-Atlas-_standalone_.html`, then renamed into stable local modules so future agents can inspect and edit it without decoding the bundle again. The root design-system docs and `DESIGN.md` were updated to make these applied surfaces part of the package contract.

## Related

- [`../../DESIGN.md`](../../DESIGN.md) — canonical rules document.
- [`../../README.md`](../../README.md) — package overview and preview manifest.
- [`../../preview/`](../../preview/) — focused design-system review cards.
- [`../../source_examples/`](../../source_examples/) — preserved original component source.
- [`components/`](components/) — earlier modular component examples retained for reuse.

## Regression Check

Run from the project root:

```bash
node tests/scrubber-regression.test.js
```

Despite the historical filename, the test now verifies the full app contract: routed prototype screens, command palette, drawer, scrubber, matrix styles, and the dark-surface preview semantics.