# Strata usage rules — do / don't

> Founder rulings, distilled. These override personal taste and any generic
> convention. When a rule here conflicts with something you'd normally do,
> the rule wins. Read this before ANY visual or copy work.

## Spacing & sizing

- **8px grid.** Spacing values are multiples of 8; 4px is the acceptable
  fallback. 6px (or any off-grid value) is never acceptable.
- Don't invent arbitrary CSS values (heights, offsets, spacing). If the
  design doesn't specify one, ask.
- Toolbar controls are uniformly 32px: `size="sm"` on every control inside a
  toolbar.

## Typography

- The Strata type scale is dense (`text-base` = 14px — see `tokens.md`).
  Never assume Tailwind's defaults.
- **Mono (Berkeley Mono) only on ALL-CAPS text** — section labels, table
  headers, eyebrows. Never on mixed-case values, IDs, emails, or URLs.
- The mono label recipe:
  `font-mono text-xxs font-medium text-muted-foreground uppercase tracking-widest`
  — for column headers, calendar day names, section markers. Never for data
  values or body text.
- **No letter-spacing on body text.** `tracking-tight` belongs on display
  headings only.
- The 16px input exception is MARKETING-ONLY: the marketing hero composer
  uses literal `text-[16px]` so mobile Safari does not zoom on focus for
  prospective signups, and the hero display context warrants the break.
  In-app composer/chat inputs stay on the standard scale.

## Buttons & icons

- **No icon+text buttons.** A button is text-only, or icon-only with
  `size="icon"` + `aria-label`. (One deliberate exception exists: the chat
  view-link's sheet glyph — see `AGENT_APP_UI_CONVENTIONS.md`.)
- Platform/brand icons come from `PlatformIcon`, never Lucide.
- The logo always sits inside its bounded squircle box (`BrandLogo` /
  `.logo-wrap`) — never a bare mark.

## Surfaces & frames

- **Band captions live OUTSIDE the frame**: mono captions go `mt-4` below a
  rounded band, never padded inside it (inside creates unbalanced negative
  space).
- Squircles: authored ~2x radius + half-value `@supports` fallback; never
  inline-style the radius (see `tokens.md`).
- Semantic color tokens only — never `text-neutral-900`-style raw utilities.

## Interaction

- **No optimistic saves.** Mutations get an explicit Save button with a
  spinner; the one exception is picker modals. Never silently persist edits.
- No silent fallbacks and no swallowed errors — degraded states are shown
  honestly ("data unavailable"), never faked.

## Copy & voice

- **No em dashes in user-facing copy** (a dead AI tell) — restructure the
  sentence instead. Code comments and internal docs are exempt.
- The verb is **"post"**: "Post", "Posted", "Live Posts" — never "publish"
  in user-facing copy (code identifiers stay as they are).
- **No industry jargon**: "Comments", not "Engagement". Exception: "agents"
  and "agentic" are embraced in product/marketing copy — they're the thesis.
- **No `@` prefix on usernames.**
- No vendor names in partner-facing docs and no naming convention-models in
  marketing copy; describe capabilities behaviorally (real integrations may
  be named).
- Treat any copy you're handed as a draft — refine it to these rules rather
  than pasting it verbatim.

## Process

- Batch small visual tweaks into a round rather than one PR per tweak.
- Spacing instructions bind to their stated target: flex areas adapt,
  fixed-width elements change only on explicit ask — never silently resize a
  fixed element to absorb a tweak.
- When several findings cluster in one area, fix the structural cause, not
  each symptom.