# Economic Observatory UI — whynot-design workflow

Build UI from what exists in **whynot-design** (`~/whynot-design` or
`gitea:whynot/whynot-design`). Do not invent parallel components or tokens.

## Before you build

1. **Sync the vendor tree** — `make design` (optional `REF=<tag-or-sha>`).
2. **Browse upstream** — inspect `src/elements/` and `src/styles/` in
   whynot-design for an existing `<wn-*>` element or `.wn-*` class that fits.
3. **Check the atelier mock** — layout reference only:
   https://claude.ai/design/p/fb2eef8c-c1fc-4c75-bff4-3782552e5511

## Layer model

| Layer | Source | Observatory usage |
|-------|--------|-------------------|
| **Layer 1** | `colors_and_type.css`, `components.css`, `tokens/*.json` | Global look; CSS variables (`--paper`, `--sp-*`, `--fg-*`) |
| **Layer 2** | `index.js` + `elements/*.js` (Lit) | App chrome: `wn-top-nav`, `wn-sidebar`, `wn-card`, `wn-field-row`, … |
| **Layer 3** | `ui/styles.css`, `ui/app.js` | Observatory-only layout (`.obs-*`) and data binding |

Layer 3 must consume Layer 1 tokens and Layer 2 components. Avoid gradients,
card shadows, and colours outside the token set.

## Implementation rules

1. **Prefer `<wn-*>` over custom markup** — use `wn-card`, `wn-eyebrow`,
   `wn-banner`, `wn-tag`, `wn-field-row`, `wn-table--native` before adding new
   patterns.
2. **Extend with `.obs-*`, not `.wn-*`** — never edit vendored CSS/JS; add
   layout in `ui/styles.css` only.
3. **Tables** — use `<table class="wn-table--native">` for ledger data; the
   shadow-DOM `wn-table` is for Lit-only grids.
4. **Typography** — use `.lead`, `.small`, `.mono` from Layer 1; metric values
   use `.obs-metric__value` with `font-variant-numeric: tabular-nums`.
5. **New upstream needs** — add the component or token in whynot-design first,
   then `make design` to vendor it here. Do not fork one-off elements into
   `ui/`.

## File touch map

| Change | Files |
|--------|-------|
| New section / panel | `ui/index.html`, `ui/app.js`, maybe `ui/styles.css` |
| Chrome or shared widget | whynot-design repo → `make design` |
| Observatory layout only | `ui/styles.css` |
| Data for a panel | `observatory/api.py` + tests |

## Verify

```bash
cd projects/coulomb-pricing
make design   # if vendor changed
make test
make serve    # http://127.0.0.1:8765/
```

Footer shows pinned ref from `ui/vendor/whynot-design/.whynot-design-ref`.