# Mirage Planning App — Design System

Enterprise components for a project planning & resource-management tool (Dubai
architecture group). Calm, dense, information-first — desktop power users, not
consumer SaaS. Brand: petrol-navy + warm sand, Roboto / Roboto Slab.

## Setup

**No provider or theme wrapper is needed** — components are self-contained and the
design tokens are global CSS. Just ensure `styles.css` is loaded (it carries the
tokens, the Tailwind utility classes, and the brand fonts). Import components from
the library and compose them:

```jsx
import { AppShell, KpiTile, StatusPill, Button } from 'mirage-planning-app'
```

## Styling idiom — Tailwind utilities backed by design tokens

Style your own layout with **Tailwind utility classes** whose colours come from
the design tokens (never hard-code hex). Use these real, token-backed families
(all present in `styles.css`):

| Purpose | Classes |
|---|---|
| Surfaces | `bg-canvas` (app bg), `bg-surface`, `bg-surface-2`, `bg-surface-3` |
| Text | `text-ink` (primary), `text-ink-2` (secondary), `text-ink-3` (muted) |
| Borders | `border-line`, `border-line-strong` |
| Brand | `bg-brand`, `text-brand-strong`, `bg-brand-soft` |
| Plan (editable) vs Actual (read-only) | `text-plan` / `bg-plan-soft` · `text-actual` / `bg-actual-bg` |
| Variance | `text-pos`/`bg-pos-soft` (favourable), `text-neg`/`bg-neg-soft` (adverse), `text-warn`/`bg-warn-soft` |
| Other semantics | `text-contingency`/`bg-contingency-soft`, `text-fusion`/`bg-fusion-soft` (Fusion sync/lock) |

Typography: body is **Roboto** (default `font-sans`); headings use **Roboto Slab**
(`font-[var(--font-heading)]`). Put `tnum` on any element showing numbers for
tabular figures. Density is deliberately tight — prefer `gap-2`/`gap-3`, small
paddings, and 12–13px text in data-dense areas.

## Component API carries the design language

Style variation lives in **props**, not ad-hoc classes:
- `Button` — `variant`: `primary` | `default` | `subtle` | `ghost`; `size`: `sm` | `md`.
- `StatusPill` — `tone`: `brand` | `plan` | `actual` | `pos` | `neg` | `warn` | `contingency` | `fusion` | `neutral`.
- `KpiTile` — `label`, `value`, `sub`, `valueTone`: `pos` | `neg` | `warn` | `plan` | `brand`.
- `Segmented` — `options` (string[]), `value` (timescale / period toggles).
- `DataTable` — `columns` (with `render`, `align`, `cellClassName`), `rows`, `getRowKey`.

## Where the truth lives

Read `styles.css` (tokens + utilities) before styling, and each component's
`<Name>.d.ts` (the prop contract) and `<Name>.prompt.md` (usage) before composing.

## Idiomatic snippet

```jsx
import { KpiTile, StatusPill } from 'mirage-planning-app'

function ProjectHeader() {
  return (
    <div className="bg-surface border border-line rounded-md p-4 flex items-center gap-4">
      <h2 className="font-[var(--font-heading)] text-[16px] text-ink">Address RAK</h2>
      <StatusPill tone="brand">In Progress</StatusPill>
      <div className="ml-auto flex gap-2">
        <KpiTile label="Contract Value" value="AED 8.5M" />
        <KpiTile label="Forecast Margin" value="17.4%" valueTone="pos" />
      </div>
    </div>
  )
}
```

# MirageDS (mirage-planning-app@0.0.0)

This design system is the published mirage-planning-app React library, bundled as a single
browser global. All 14 components are the real upstream code.

## Where things are

- `_ds_bundle.js` — the whole-DS bundle at the project root; loads every component to `window.MirageDS`. First line is a `/* @ds-bundle: … */` metadata header.
- `styles.css` — the single stylesheet entry: it `@import`s the tokens, fonts, and component styles (`_ds_bundle.css`). Link this one file.
- `components/<group>/<Name>/<Name>.prompt.md` (example JSX + variants), `<Name>.d.ts` (types), `<Name>.html` (variant grid).
- `tokens/*.css` — CSS custom properties, names verbatim from upstream.
- `fonts/` — `@font-face` files + `fonts.css` (when the package ships fonts).
- `guidelines/` — the design system's own usage guidance (1 doc(s), see `guidelines/index.md`). Read these before composing larger layouts.

For a specific component, `read_file("components/<group>/<Name>/<Name>.prompt.md")`.

## Loading

Add these two lines to your page once (React must be on the page first):

```html
<link rel="stylesheet" href="styles.css">
<script src="_ds_bundle.js"></script>
```

Components are then available at `window.MirageDS.*`. Mount into a dedicated child node (e.g. `<div id="ds-root">`), not the host page's own React root, so the two trees don't collide:

```jsx
const { AppShell } = window.MirageDS;
ReactDOM.createRoot(document.getElementById('ds-root')).render(<AppShell />);
```

## Tokens

93 CSS custom properties from mirage-planning-app. Names are
preserved verbatim from upstream. They are declared inside `_ds_bundle.css` (this DS ships one compiled stylesheet rather than separate token files).

- **color** (39): `--tw-border-spacing-x`, `--tw-border-spacing-y`, `--tw-border-style`, …
- **spacing** (5): `--tw-space-y-reverse`, `--tw-inset-shadow`, `--tw-inset-shadow-alpha`, …
- **typography** (13): `--tw-font-weight`, `--tw-tracking`, `--font-sans`, …
- **radius** (3): `--radius-xs`, `--radius-sm`, `--radius-md`
- **shadow** (7): `--tw-shadow`, `--tw-shadow-alpha`, `--tw-ring-shadow`, …
- **other** (26): `--tw-rotate-x`, `--tw-rotate-y`, `--tw-rotate-z`, …

## Components

### design-system
- `AppShell`
- `Avatar`
- `Button`
- `CostSummaryStrip`
- `DataTable`
- `FusionLock`
- `Gantt`
- `KpiTile`
- `ProgressBar`
- `ProjectSelector`
- `Segmented`
- `StatusPill`
- `Toolbar`
- `ToolbarDivider`