# FieldInsight Prototype Style Guide

**Version**: v0.26.0
**Live (HTML, interactive)**: https://fi-prototypes-b488d180d67d.herokuapp.com/build.html
**Raw (this file)**: https://fi-prototypes-b488d180d67d.herokuapp.com/styling-guide.md
**Reference build**: https://fi-supplier-po-616b48f7f1a3.herokuapp.com (proto-multi-supplier-po v1.28)

> **Pending Lead Engineer sign-off (Vadim).** Once approved, every Open Claw prototype maps onto this guide. Locked from the Purchase Order page rebuild — green · orange · purple · blue button hierarchy, dark purple chrome, document-page widgets, tables.

## Contents

1. [Structure](#1-structure)
2. [Text formatting](#2-text-formatting)
3. [Buttons & hierarchy](#3-buttons--hierarchy)
4. [Tables](#4-tables)
5. [Chrome & in-page controls](#5-chrome--in-page-controls)
6. [Document pages & widgets](#6-document-pages--widgets)
7. [AI styling addendum](#7-ai-styling-addendum)
8. [Explicit by design — NAB · NAT · NAS](#8-explicit-by-design--nab--nat--nas)

---

## Quick reference — the rules that never change

- **Prototype action palette: green · orange · purple · blue.** Green = lifecycle hero (Approve, Submit, Finalise) — **ONE per region**. Orange = attention / confirm (Confirm goods received) and general app CTAs. Purple = workflow events (Reconcile Supplier Invoice, Create Credit). Blue tint = working tools and companions. Bright green `#22C55E` = status pips and chips only — not a button fill.
- **Chrome is dark purple** (`#39006B`); active nav uses orange (`--fi-primary`), not lifecycle green.
- **Filled-button budget: max 2 fills per visible region** — typically one green lifecycle hero + one purple workflow event.
- **Every workflow button gets a click-`?` hint** (Description · Example dialog) — no hover-only tooltips on verbs.
- **Explicit, never implicit:** NAB · NAT · NAS — make information discoverable on the page (§8).
- **Chevron disclosure** is the only collapse pattern on document pages — no View/Edit or Expand/Collapse button pairs.
- **Dates always use `var(--fi-primary)`** for today, selected, active month chip, focus rings.
- **Deep purple `#39006B`** is AI-only (sparkle, AI Import zone). Workflow purple is `#6C5AC4` (hover `#513FAD`).
- **Map onto `poButtonTokens.ts`** — never invent per-repo button colours.

---

## 1. Structure

Every FieldInsight page: dark purple **top bar** (48 px), dark purple **left sidebar** (220 px), cream **content area**. Container max-width: `1180 px`.

```html
<div class="app">
  <header class="app-top"> ... </header>
  <aside  class="app-sidebar"> ... </aside>
  <main   class="app-content"> ... </main>
</div>
```

| Use | px |
|---|---|
| Page padding (X) | 36 |
| Section gap | 52 |
| Component gap (button rows) | 14 |
| Disclosure title → action row | 10 (1.25 spacing units) |

---

## 2. Text formatting

**Bricolage Grotesque** — display. **Plus Jakarta Sans** — body. **JetBrains Mono** — codes, IDs.

| Role | Size | Weight | Color |
|---|---|---|---|
| Page title | 32 | 700 | `--fi-text` |
| Section | 22 | 700 | `--fi-text` |
| Body | 14 | 400 | `--fi-text` |
| Caption / eyebrow | 11.5 | 700 UPPERCASE | `--fi-text-muted` |
| Button label | 12–13 | 700 | varies |
| Supplier code (table) | 12 | 700 mono | `#6a1b9a` |
| Internal code (table) | 12 | 700 mono | `#FF6A13` |

---

## 3. Buttons & hierarchy

The PO page defines the canonical stack. Seven levels — map to `poButtonTokens.ts`:

| Level | Token | Size | Colour | Examples |
|---|---|---|---|---|
| **L1 Lifecycle hero** | `BTN_STATUS_GREEN` / `po-btn-status-green` | 32 px | Status green `#1E7A3A` · hover `#166030` | Approve · Submit · Finalise — **ONE per region** |
| **L1 Attention** | `BTN_STATUS_ORANGE` / `po-btn-attention` | 32 px | Orange `#FF6A13` | Confirm goods received |
| **L2 Workflow** | `BTN_PURPLE` / `po-btn-purple` | 28 px | Purple `#6C5AC4` · hover `#513FAD` | Reconcile Supplier Invoice · Create Credit |
| **L3 Standard** | `BTN_STANDARD` / `po-btn-standard` | 28 px | Indigo tint `#F3F0F8` · text `#30025E` | Close · + Find Bill · Receive all · companions |
| **L3b Ghost doc** | `BTN_GHOST_DOC` / `po-btn-ghost-doc` | 28 px | White + `#30025E` border & text | Preview · Download · Email · Copy · Create job ▾ |
| **L4 Inline link** | `LINK_BLUE` / `po-btn-link` | text | `#30025E` | + Add from library · + Add line item |
| **L5 Destructive** | `BTN_GHOST_DANGER` / `po-btn-danger` | 28 px | Red ghost | Delete (Draft only, far right) |

### Per-region map (PO page)

**Footer lifecycle:** Submit/Approve/Finalise → L1 Lifecycle hero (green) · Approve & Email/Receive all/Close → L3 · Preview/Download/Email/Copy/Create job/Export → L3b Ghost · Delete → L5

**Bills (expanded):** Reconcile Supplier Invoice → L2 · + Find Bill / + Generate Bill → L3

**Credit Notes:** Create Credit → L2 · Use Credit → L3

**Import zones:** Attach Choose file → L3 Standard · AI Choose file → L2 Purple + sparkle

**Import preview modal:** Auto-create & add → L1 Lifecycle hero (green) · Add as-is → L3 · Cancel → text

### Click-`?` hints

Every workflow button: hover-revealed `?` glyph → click opens Description + Example dialog. One dictionary per page (`FOOTER_BTN_INFO`). Labels verb-led: "Reconcile Supplier Invoice" not "Supplier Invoice Received".

### Anti-pattern: wall of buttons

Never ship 12 equal purple fills (legacy production PO). One green lifecycle hero, purple workflow where needed, blue/ghost for the rest.

### Do / Don't

✅ One green L1 lifecycle per region · Orange for attention only · Purple for workflow events · Blue for tools · Click-? on every verb · Map to `poButtonTokens.ts`

❌ Multiple green fills per region · 3+ filled buttons per row · Duplicate affordances · `#39006B` on workflow buttons (AI only; chrome uses it for nav)

---

## 4. Tables

Default list table: white card, uppercase-tracking header, hover, status pills.

**PO line table** (document pages):

| Column | Header colour | Notes |
|---|---|---|
| Supplier Code | Purple `#6a1b9a` | Supplier-facing — primary on PO |
| Internal Code | Orange `#FF6A13` | Your inventory / receiving |
| Band | `#F0F0F2` | Calm header, not brand purple fill |

Fully-received rows tint `#f1f8e9` (status semantics — not a button).

---

## 5. Chrome & in-page controls

Top bar (48 px): brand · trial banner · Clock in / Log time (`btn-soft`) · search · icon cluster.

Left sidebar (220 px): profile chip · module nav · Help anchored bottom. Background `--fi-chrome-bg` (`#39006B`). Active nav: `--fi-chrome-active` (orange · `--fi-primary`).

Page header: breadcrumb · PO number + status pill · template select.

Breadcrumbs: single-line `.crumb` with back arrow.

---

## 6. Document pages & widgets

Patterns from proto-multi-supplier-po v1.28. Apply to PO, quote, invoice, bill, credit note.

### Chevron disclosure (only collapse pattern)

- Left chevron ▸/▾ · whole header row clickable · count chip (`4 lines`, `1 bill`, `None`)
- Rich collapsed summary: supplier · dates · `$total` · received progress
- State persists in localStorage
- Never View/Edit or Expand/Collapse button pairs

### Masthead card

- Eyebrow: `PURCHASE ORDER` · supplier name headline · fact grid (PO Date · Delivery · Reference)
- "Edit details ▾" expands form in place

### Uniform rhythm

- One divider between sections (same margin everywhere)
- Fixed gap between disclosure title row and action buttons

### Inline affordance beats banners

No "N lines need a code" banner when the table cell already highlights the problem.

### Screen vs print

```css
.print-only { display: none; }
@media print { .print-only { display: block !important; } .no-print { display: none !important; } }
```

Expand collapsed sections on `beforeprint`; restore on `afterprint`.

---

## 7. AI styling addendum

**This page is the master style guide.** AI rules live here — `fi-ai-styling-guide` Heroku app is **ARCHIVED** (historical demos only).

Any AI feature marks the moment with the canonical Two-Star sparkle in `#39006B`. Three placements: inline icon · circular badge (max one per page) · pill CTA. Approved labels: Ask AI, Re-read, Scan bill, Post to Xero →.

Full pattern: workspace `ai-styling-pattern.md`.

**Don't conflate purples:** workflow purple `#6C5AC4` (§3) vs AI deep purple `#39006B` (this section).

---

## 8. Explicit by design — NAB · NAT · NAS

**Core principle:** Where possible, make information **discoverable and clear**. **Explicit, never implicit behaviour.**

Before adding any new interactive control, run the NAB · NAT · NAS test: can the user already see or reach this from what's on screen? If yes — don't add another button, setting, or toggle.

| Rule | Stands for | Means |
|---|---|---|
| **NAB** | Not Another Button | One entry point per action class — never duplicate the same verb (Attach zone covers file attach; chevron replaces View/Edit; grip column replaces Select items). |
| **NAT** | Not Another Toggle | No mystery switches — label what a toggle controls and show current state; or show read-only state inline. |
| **NAS** | Not Another Setting | Don't bury facts in Settings when they belong on the page — count chips, disclosure summaries, masthead fields, click-? hints. |

### Discoverable by default

- Collapsed section headers answer *"do I need to open this?"* — chevron + title + count chip + inline facts (§6.1).
- Document mastheads show *who, when, reference* without opening Edit (§6.2).
- Workflow buttons explain *why* via click-? — not hover tooltips (§3 · §6.6).

### PO examples

**Do:** Attach zone only (no + File) · chevron only (no View/Edit) · Bills header shows billed total while collapsed · labelled Settings toggles.

**Don't:** Attach zone + File button · Select items + grip column · 12 equal footer buttons · bill status only after three expansions · unlabelled toggles · hover-only workflow tooltips.

Related: §3 filled-button budget · §6 chevron & masthead · `apply-tooltip-pattern.md`.

---

## Appendix · PO palette tokens

```css
:root {
  --fi-chrome-bg:    #39006B;
  --fi-chrome-active: var(--fi-primary); /* orange nav active */
  --po-status-green:       #1E7A3A;
  --po-status-green-hover: #166030;
  --po-orange:       #FF6A13;
  --po-orange-hover: #F35627;
  --po-purple:       #6C5AC4;
  --po-purple-hover: #513FAD;
  --po-blue-text:    #30025E;
  --po-blue-tint:    #F3F0F8;
  --po-blue-border:  #C9BED9;
  --po-ghost-border: #30025E;
  --po-table-head:   #F0F0F2;
  --po-sup-code:     #6a1b9a;
  --fi-accent-deep-purple: #39006B; /* AI only */
}
```

Implementation: `proto-multi-supplier-po/src/theme/poButtonTokens.ts` · per-button table: `affordance-style-guide.md`.

---

## Versioning

- **v0.26.0** (2026-06-11) — Darkened L3 / L3b / L4 tool text & ghost border from bright blue `#1D4ED8` → deep indigo `#30025E` (production Email · Copy outline reference). Tint wash shifted to pale indigo so fills stay coherent.
- **v0.25.0** (2026-06-11) — Section 8 **Explicit by design — NAB · NAT · NAS**: discoverable information, explicit never implicit behaviour; complements §3 button budget and §6 disclosure patterns.
- **v0.24.0** (2026-06-11) — Restored **status green** lifecycle hero (`BTN_STATUS_GREEN` · `#1E7A3A`) in §3; chrome switched from dark teal to **dark purple** (`#39006B`) with **orange** active nav. Clarifies green (lifecycle) vs orange (attention) vs purple chrome (wayfinding).
- **v0.23.0** (2026-06-11) — PO prototype style guide lock: orange·purple·blue button hierarchy (§3), all PO widgets and per-region button map, click-? hints, dual code columns; pending Vadim sign-off.
- **v0.22.0** — document-page workflow palette and click-? rule.
- **v0.21.0** — Section 9 document pages (chevron, masthead).
- See `build.html` for live demos.

---

*FieldInsight Prototype Style Guide · Built by Alfred · Reference: proto-multi-supplier-po v1.28*