spa/TRM_Design_System-handoff/trm-design-system/project/README.md

# TRM — Tracking & Race Management

**Design System v1.0**

TRM (Tracking & Race Management) is a multi-sport, generic event-timing platform — race directors, timing officials, athletes, and spectators all live in one product family. Think of the way an F1 pit-wall display, a marathon results board, a triathlon transition mat, and a sailing nav screen all need to coexist visually: high-density numerical data, instant readability under any light, and absolute trust in the numbers on screen.

The system covers four surfaces:

| Surface | Audience | Density |
|---|---|---|
| **Web dashboard** | Race directors, timing officials, race control | Very high |
| **Live tracking / leaderboard** | Spectators, broadcast, kiosk | Very high, glanceable |
| **Mobile app** | Athletes, spectators following a friend | Medium |
| **Marketing website** | Race organizers evaluating the product | Editorial |

---

## Sources & provenance

This system was built **from scratch** — no existing codebase, Figma file, or brand guide was provided. The only input was a **logo PNG** (`uploads/logo-1777578841639.png` → `assets/logo-trm.png`): a bold geometric wordmark with three inset glyphs — a 3D **cube** in the T, a **pixel grid** in the R, and a **folded map** in the M. That triad — *object · data · place* — is the conceptual core of the brand and runs through the rest of the system.

If you receive updated source material (real product screenshots, Figma, fonts, a brand book), treat this document as a starting hypothesis to be replaced — not as canon.

---

## CONTENT FUNDAMENTALS

TRM copy reads like a **race-control radio call**: short, factual, present tense, no hype. The product is responsible for numbers people care about (a podium finish, a qualifying time), so the voice is calm and exact. Drama lives in the data, not in the prose.

### Voice attributes

- **Precise over expressive.** "Lap 14 / 22" not "Almost there!"
- **Active, present tense.** "Smith passes Jones" not "Smith has just managed to pass Jones."
- **Short.** Most UI strings are ≤ 4 words. Sentences in marketing rarely exceed 16.
- **No exclamation marks** in product UI. Marketing may use one per page, max.
- **Second person ("you") in marketing.** First person plural ("we") only when explicitly speaking as the company. Product UI prefers no pronoun at all ("Add bib" not "Add a bib to your event").
- **Numerals beat words.** "3 laps left," not "three laps remaining."
- **Time is sacred.** Always render times in mono with tabular figures: `01:23:45.678`. Leading zeros on minutes/seconds. Milliseconds when relevant.

### Casing

| Context | Style |
|---|---|
| Buttons, links, menu items | **Sentence case** ("Start race", "Export results") |
| Labels above fields | **UPPERCASE** with letter-spacing (overline class) |
| Section headings | **Sentence case** |
| Table column headers | **UPPERCASE** mono, e.g. `POS  BIB  NAME  GAP` |
| Status flags | **UPPERCASE** ("LIVE", "DNF", "DSQ", "DNS") |
| Brand wordmark | **TRM** — always uppercase, never "Trm" |

### Vocabulary — preferred terms

| Use | Not |
|---|---|
| Event | Race (use "race" only for a single heat within an event) |
| Participant | User, racer, runner (sport-specific only when the event is single-sport) |
| Bib | Number, ID |
| Wave | Group, batch |
| Split | Checkpoint *(use "checkpoint" only when split is geographic)* |
| Leaderboard | Ranking, scoreboard |
| DNF / DSQ / DNS | Did not finish / Disqualified / Did not start *(spell out only on first use)* |
| Live | Real-time *(reserve "real-time" for technical copy)* |

### Emoji & symbols

- **No decorative emoji** anywhere in product UI. None.
- Marketing may use **🏁** or **▲ ▼** as standalone graphic elements but never inline in sentences.
- Race-flag glyphs are part of the design system as **CSS-drawn flags or SVG**, not emoji.
- Mathematical / typographic symbols *are* used freely: `+`, `−`, `±`, `→`, `·`, `°`, `Δ`.

### Sample copy

> **Marketing hero:**
> *Run any event. Time any sport. TRM is the race-day operating system used by 4,000+ event organizers — from 5K fun runs to 24-hour endurance races.*

> **Empty state in dashboard:**
> *No events yet. Create your first event to start timing.*

> **Toast on save:**
> *Saved · 14:02:11*  *(timestamped, mono)*

> **Race-control alert:**
> *Bib 247 — missed split 3 — flagging for review*

> **Push notification, athlete app:**
> *Maya passed split 2 — 00:42:18 — pace 4:13/km*

---

## VISUAL FOUNDATIONS

The system is **ink on paper, with one race-flag accent**. Square-edged. Hairline-bordered. Mono-numeric. The visual mood sits between a Bloomberg terminal and a printed race program.

### Colors

- **Paper / Ink palette** drives 90% of screens. Off-white `#FAFAF7` ground, deep ink `#0E0E0C` strokes and type. No true black, no true white — both are exhausting on data screens.
- **Night mode** (`#0B0D10`) is the default for live tracking, kiosk, and trackside displays. It is not a "dark theme toggle" — it's a separate context.
- **Race-flag red `#E8412B`** is the only brand accent. Reserved for: primary CTAs, "live" pulse, danger states, the leading position in a leaderboard. Used sparingly. If everything is red, nothing is.
- **Amber `#F2A516`** = caution / yellow flag / warnings.
- **Green `#2E8C4A`** = go / improvement / personal best / passed checkpoint.
- **Blue `#2563C8`** = informational, link, "tracking" pulse.
- **Categorical viz palette** is 8 hues, ordered by frequency of use; never assign meaning to a viz hue beyond chart legend.

### Typography

- **Display & UI:** *Goldplay* (Semibold supplied; 400 / 700 synthesized). The brand face — humanist sans with confident curves and a slightly editorial register. Used for headings, buttons, navigation, labels.
- **Mono / data:** *JetBrains Mono* (400 / 500 / 600). Tabular figures are non-negotiable for any time, gap, distance, or ranking. Every number that could change is mono.
- **Body / long-form prose:** *Inter* (400 / 600). Used only in marketing long-form and documentation. The dashboard does not have body prose.
- **Letter-spacing:** display is tight (`-0.02em`). Overlines / table headers are open (`+0.10em`) and uppercase.

> ✅ **Goldplay (display/UI)** — brand face installed with three weights: Regular `400` (`fonts/goldplay-regular.ttf`), Semibold `600` (`fonts/goldplay-semibold.woff2`), Bold `700` (`fonts/goldplay-bold.ttf`). No synthesis. **Mono / body** are still Google Font substitutes — share licensed faces if available.e *Berkeley Mono* or *GT America Mono*), please provide the `.woff2` / `.ttf` files and we'll swap them in.

### Spacing & grid

- **4-px base** unit. Standard scale: 4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64 · 80 · 96.
- **12-column grid** at 1280 px container, 24 px gutters, 16 px column gap.
- **Table density** is the system's defining choice. Default row height is **36 px**, "dense" is **28 px**, and dense is the dashboard default — race directors look at hundreds of rows.

### Corners & borders

- **Square by default.** `--r-0: 0`. Cards, inputs, buttons, modals: all square.
- **2 px radius** for chips and small inputs only.
- **4–10 px radius** reserved for marketing cards and the mobile app surface.
- **Hairline 1 px borders** — `var(--hairline)` for division within a card; full ink `1px solid var(--ink)` for the outer edge of any "first-class" container (modal, primary card, button).
- **No rounded pills**, except for status badges where pill is functionally meaningful (`LIVE`, `DNF`).

### Shadows & elevation

TRM uses a **printed offset shadow** as its primary elevation model — a sharp 2 px or 4 px ink-colored offset, no blur. It says "the chip is sitting on the page," not "the chip is glowing." Soft blurry shadows are allowed only on mobile sheets and marketing site.

| Token | Use |
|---|---|
| `--shadow-2` (2 px ink offset) | Buttons at rest, primary cards |
| `--shadow-3` (4 px ink offset) | Buttons / cards on hover |
| `--shadow-soft` | Mobile bottom sheets |
| `--shadow-pop` | Marketing testimonial / floating dropdowns |

### Backgrounds & imagery

- **No gradients** in product UI. Marketing may use a **flat ink-to-night vertical gradient** behind a hero — never multi-color.
- **Imagery vibe:** high-contrast B&W or duotone (ink + flag) photography of race-day moments — start lines, timing mats, marshals, finish tape. Crops are **tight and asymmetric**. Color photos are allowed in marketing but should be **slightly desaturated and warm-graded** so they coexist with the ink palette.
- **Patterns:** a subtle **dot-grid** (`2 px dot, 24 px spacing`, ink at 8% opacity) and a **diagonal hatch** (used sparingly to mark "in progress" or "estimated" data). These are CSS-drawn, never image files.
- **No hand-drawn illustrations.** No abstract blobs. No gradients-as-backgrounds. The brand is photographic + typographic.

### Animation

- **Functional, never decorative.** Transitions are 120–320 ms, almost always `--ease-snap`.
- Hover changes use `120 ms`. Modal / sheet entrances use `180 ms`. Chart redraws use `320 ms`.
- **The "live" pulse** is the one signature motion: a 2 s loop where a red dot scales from 1.0 → 1.15 and a fading ring expands from 0 → 16 px. Used at most once per screen, next to the word LIVE.
- **No bouncy / spring easing.** No fly-ins from off-screen. No micro-interactions on every button.

### States — hover, press, focus, disabled

| State | Treatment |
|---|---|
| **Hover** (button) | Shadow grows from `--shadow-2` → `--shadow-3`, button translates `1px ↑ 1px ←` |
| **Hover** (link) | Color shifts `--ink` → `--flag` |
| **Hover** (table row) | Background shifts to `--paper-2`, no elevation change |
| **Press** | Shadow collapses to `0 0 0 0`, button translates back to `0,0` |
| **Focus** | 2 px outline in `--flag`, 2 px offset, *never* removed. Keyboard users matter on race day. |
| **Disabled** | Opacity 40%, cursor `not-allowed`, no shadow |

### Transparency & blur

- **Backdrop blur** used only on mobile bottom sheets and the kiosk overlay (`backdrop-filter: blur(12px)` over a `rgba(11,13,16,0.7)` scrim).
- Tints (`--flag-tint`, `--amber-tint`, `--green-tint`, `--blue-tint`) are flat 10–15% mixes, never alpha layers, so they composite predictably over `--paper-2`.

### Layout rules — fixed elements

- **Top bar** is `56 px`, full-width, ink border on the bottom, sticky.
- **Side nav** is `240 px` collapsed to `64 px`, ink border on the right, sticky.
- **Live tracking pages** use a **3-column** layout: leaderboard (40%) · map (40%) · selected-athlete detail (20%).
- **Tables fill remaining space**, scroll independently of the page.
- **Time/clock** is always pinned top-right of any "race in progress" view, mono, jumbo size.

### Iconography

See the **ICONOGRAPHY** section below.

---

## ICONOGRAPHY

TRM uses **Lucide** as its icon system — a clean, square-cornered, 2 px stroke library that pairs with Goldplay's humanist sans and the square-edged component language. Lucide is loaded via CDN (`unpkg.com/lucide@latest`) in HTML examples and via the `lucide-react` package in production code.

> ⚠ **Substitution flag:** Lucide is a substitute. The TRM logo's three inset glyphs (cube, pixel-grid, map) suggest the brand may have a custom-drawn icon set in the same blocky style. If that set exists, swap it in — Lucide is the closest CDN-available match (clean strokes, square caps, geometric).

### Icon rules

- **Stroke weight:** 2 px (Lucide default). Never 1.5 / 1 — strokes get lost on dark mode.
- **Sizes:** 14 / 16 / 20 / 24 / 32 px. Never in between.
- **Color:** inherits `currentColor`. Default `--ink-3`; hover state inherits whatever the parent's hover color is.
- **Alignment:** icons are **box-aligned**, not optically aligned. The tabular feel beats the typographic feel here.
- **Race-specific iconography** that Lucide doesn't cover (checkered flag, timing chip, transition area, podium, finish-line tape, sailing buoy, lap split) is rendered as **inline SVG** in the same 2 px stroke style. A small set lives in `assets/icons/` as we encounter the need.

### Emoji

**Not used** in product UI. Only race-flag glyphs (🏁) are tolerated in marketing, and even then only as standalone graphic elements at large size — never inline in sentences.

### Unicode glyphs

Used freely for compact mathematical / directional indicators:

- `↑ ↓ → ←` for trend arrows in leaderboards
- `▲ ▼` for sort direction
- `±` for tolerance ("split window ±5s")
- `·` as a compact bullet between meta items ("Wave 3 · 4.2 km · 47 starters")
- `°` for temperature ("18°C, dry")
- `Δ` for delta ("Δ +1.4s")

### Logo

- `assets/logo-trm.png` — primary wordmark, ink on transparent, 286×158.
- Minimum width: 80 px.
- Clear space: half the cap-height of the wordmark, all sides.
- **Never** stretch, recolor (except inversion to paper-on-ink), or place on a busy photograph without a 1 px ink-bordered paper plate behind it.

---

## INDEX — what's in this folder

| Path | Purpose |
|---|---|
| `README.md` | This file. Read first. |
| `SKILL.md` | Agent-Skill manifest for Claude Code / portable use. |
| `colors_and_type.css` | All design tokens as CSS custom properties + base type styles. **Import this first** in any HTML mock. |
| `assets/` | Logos, icons, brand imagery. |
| `assets/logo-trm.png` | Primary wordmark. |
| `preview/` | Per-token / per-component preview cards rendered into the Design System tab. Useful as visual reference. |
| `ui_kits/dashboard/` | Web dashboard for organizers — sidebar, tables, race control. |
| `ui_kits/leaderboard/` | Live tracking / spectator leaderboard view. |
| `ui_kits/mobile/` | Athlete & spectator mobile app inside an iOS frame. |
| `ui_kits/marketing/` | Marketing site — homepage hero, features, pricing strip. |

Each `ui_kits/<name>/` folder contains its own `README.md` describing the screens, an `index.html` you can open directly, and JSX components for the major UI pieces.

---

## Quick start for designers

```html
<link rel="stylesheet" href="colors_and_type.css">
<script src="https://unpkg.com/lucide@latest"></script>
```

Then build with the tokens. The preview cards in `preview/` are good copy-paste starting points for any new screen.