# ploxum

> Cinematic dark-mode operational intelligence UI library.

## Changelog

### 0.0.0 — 2026-05-31

Initial workspace scaffold:

* DTCG tokens (`tokens.json`) — cinematic dark palette
* Primitives: `Button`, `StatusPip`, `Badge`, `Kbd`, `Separator`, `PloxumProvider`
* Brand mark: "The Reticle"
* Storybook 10 + Vocs docs scaffolding
* CI workflows (ci.yml, deploy-docs.yml, release.yml)
* Cloudflare Workers + Assets deployment ready


## Getting started

```bash
pnpm add @roger-emerson/ploxum-primitives @roger-emerson/ploxum-tokens
```

Wrap your app in `PloxumProvider`:

```tsx
import { PloxumProvider } from '@roger-emerson/ploxum-primitives';
import '@roger-emerson/ploxum-tokens/css';

export function App({ children }) {
  return <PloxumProvider density="comfortable">{children}</PloxumProvider>;
}
```

Density persists per operator account — wire it to your user-prefs store, not session state.


## Motion

| Token                 | Value      | Use                                      |
| --------------------- | ---------- | ---------------------------------------- |
| `duration.micro`      | 80ms       | Toggle, checkbox check, icon swap        |
| `duration.standard`   | 200ms      | Panel slide, dropdown open, tooltip      |
| `duration.emphasized` | 320ms      | Sheet/drawer entry, tab transition       |
| `duration.data`       | 250ms      | New data point fade-in, sparkline redraw |
| `duration.cinematic`  | 600ms      | Command palette open, map focus          |
| `spring.soft`         | k=120 d=18 | Map pin hover, KPI tile hover lift       |
| `spring.firm`         | k=300 d=28 | Command palette open, drawer entry       |

### What never animates

* Alert and toast appearance — instant
* Status pip color change — instant
* Critical metric value updates — instant
* Form validation errors — instant
* Live/recording pulse — opacity only, no transform

### Cinematic flourishes (exactly two)

1. **Command palette open** — backdrop dims 200ms, palette scales 96 → 100 with translate +12 → 0 over 280ms using `spring.firm`.
2. **Map focus transition** — camera eases with `spring.soft` over 500–600ms. The primary cinematic moment in the product.


## Principles

1. **Canvas time is always visible.** LIVE pill or REPLAY timestamp never hides, truncates, or covers.
2. **The focal canvas is never blocked without operator intent.** The right rail pushes; modals are forbidden in the focal zone.
3. **Critical alerts are immediate and motionless.** No slide-in, no fade. Motion implies optional; P1 is not optional.
4. **Every status uses shape + color.** Color alone is never a signal.
5. **No more than 7 visible chrome surfaces.** Sidebar, top bar, tabs, canvas, rail, timeline, toasts — that's the budget.
6. **Density is a persistent operator preference.** Stored per account, not session.
7. **Destructive actions require exactly one-step confirm.** No double modals; no zero-step.
8. **Every non-obvious state surfaces a "why" tooltip.** The text answers "why," not "what."
9. **Keyboard nav is a first-class workflow.** Command palette (Cmd+K) reaches every action.
10. **Shift handoff state persists every 30s.** The incoming operator sees the outgoing operator's working state.


## Tokens

DTCG source: `tokens.json`. Generated outputs:

* `tokens.css` — CSS custom properties (`--ploxum-color-*`, `--ploxum-font-*`, `--ploxum-density-*`)
* `tailwind.preset.mjs` — Tailwind v4 preset (extends `theme.colors`, `theme.fontFamily`, `theme.fontSize`, `theme.borderRadius`)
* `tokens.mjs` — Runtime JS object (read in components for non-CSS contexts)

The full color, type, motion, density, and layout system is described in `CLAUDE.md` at the repo root.