# 01 · Principles: glass that stays readable

The owner reads this app on a job site: in bright sun, in a van, sometimes with dirty hands and one free thumb. Glass makes a strong first impression, but readability matters more. These rules come first. Where a rule conflicts with a concept file, the rule wins.

## 1. Glass for chrome, solid for content

There are four materials. Every surface uses exactly one of them.

| Material | Token prefix | Use for | Never use for |
|---|---|---|---|
| **Glass** (concept 6 `.gl`) | `--glass-*` | Nav bar once content scrolls under it, floating tab bar, Remy orb, floating round buttons, segmented controls, search fields and filter chips that sit on the wallpaper, day separators in threads | Anything with more than one line of body text |
| **Sheet glass** | `--glass-fill-strong` | Bottom sheets and popovers | Full-screen content |
| **Frosted** (concept 2 `.card`) | `--frost-*` | Short, glanceable cards: the Today hero, stat tiles, chart card, account tiles | Lists, paragraphs |
| **Solid** (new) | `--surface*` | Lists, conversation rows, message bubbles, transcripts, forms, settings, job cards, calendar events, panels inside sheets | — |

Why: the backdrop blur on glass reads well over a calm wallpaper, but text over moving, colourful content becomes unreadable fast. Concept 6 put lists on glass. That looked great in a demo but failed the sunlight test, so lists move to solid.

**Inside a sheet**, the sheet is glass. The panels inside it (Remy's summary, transcript, key-value tiles) are solid `.panel`.

## 2. Contrast floors (non-negotiable)

- Body and label text: **at least 4.5:1** against the surface it sits on. Large text (24px+, or 19px+ bold): at least 3:1.
- Icons and meaningful graphics: at least 3:1.
- `--text-2` (secondary text) is only allowed on solid or frosted surfaces. On glass, use `--ink`.
- `--text-3` is only for placeholders and disabled states. Never use it for information.
- Accent as **text** uses `--accent-text` (#c2410c light, 5.2:1 on white; #ff8a5c dark). `--accent` (#ff5a1f) is only for fills, icons, dots and indicators, because it is 3.1:1 on white and fails for small text.
- The primary button fill is `--accent-strong`. The white label stays at least 4.5:1 across the button: the lighter `--accent-sheen` only touches the top edge.
- Chips are a soft fill with strong text (`--ok` on `--ok-soft`, etc.). Never put white text on a pale fill.
- **Check against the worst case:** the brightest part of the vivid wallpaper behind the lightest glass. If it fails there, raise the fill opacity. Do not darken the text shadow.

## 3. One accent colour

- **Orange (`--accent`) means "do this" or "needs you"**: the primary button, the unread badge, the active tab, the NOW line, the play progress.
- One primary (orange) button per screen region. Everything else is secondary (neutral) or plain.
- **Channel colours** (SMS blue, WhatsApp green, voicemail purple, web grey) only identify a channel: the avatar, a dot, a spine. Never use them for actions.
- **Status colours** (ok, warn, danger, info, stage colours) only appear as chips, dots and thin bars. Never as button fills.
- **Remy's gradient** (`--remy-gradient`) only appears on the Remy mark. Remy-authored surfaces get `--remy-tint` and a `--remy-edge` outline. It is an identity, not a second accent.

## 4. Hierarchy: one thing per screen

Every screen leads with the single thing that matters, in plain words. Today says "Remy caught 3 new leads overnight." The Inbox says "4 waiting on you." Big type does the work. Avoid decoration.

- Large titles (30/800) on tab roots. They collapse into the glass nav bar title once scrolled.
- Section headings are small caps labels (13/750, uppercase).
- Numbers that matter use tabular figures and the `stat` or `hero` styles.
- Plain English everywhere, short and kind: "Call back", not "Initiate callback". Status labels follow the contract with friendly display names: `closed` shows "Done", `scheduled` shows "Booked", `collections` shows "To collect", and `garbage` shows "Junk" and is never on the board.

## 5. Motion restraint

- **Motion explains change; it never decorates.** Allowed: push/pop between screens, sheets rising, the tab lens sliding, a sent bubble growing from the composer, content rising in on first load (first 6 items only), the countdown bar.
- Nothing moves while the owner is reading. No drifting wallpaper, floating orbs, pointer-follow sheen or tilt parallax. These came from concept 6 and are dropped.
- Two loops are allowed: the Remy mark rotates slowly (7s), and pencilled-in calendar slots "breathe" (2.4s). Both stop under Reduce Motion.
- Springs, not linear easing. Colour changes use a quick ease-out (180ms) and never spring.
- Under Reduce Motion every duration becomes 0 and the end state appears at once. The tokens handle this; components must read durations from tokens.
- The 5-second auto-send countdown is **behaviour**, not decoration. It stays under Reduce Motion (the bar stops animating, the number still counts).

## 6. Built for the job site

- Hit targets of at least 44×44pt, even when the visual is smaller (a 36pt chip gets an invisible 44pt hit area).
- The primary action sits in the bottom half of the screen, inside the thumb zone: sheet CTAs, the composer, the action tiles in a lead.
- Destructive actions (Call off, Sign out, Clear all) always ask first, in plain words, and say what happens.
- Gloves and wet hands: no gestures that are the only way to do something. Swipe and long-press always have a visible button or menu alternative.
- Offline: show what we have (cached), with the "You're offline" pill. Don't block reading. Disable sends with a reason.

## 7. Same behaviour on every platform

iPhone, Android and web are one product. The look may use each platform's native glass, but the **behaviour** must match: the same screens, states, copy, rules and order of actions. Deliberate platform differences (such as the long-press menu on phones being a "…" button on web) must be written down in `08-native-mapping.md`.