# Torus — agent instructions

Torus is a web app for exercise. Primary focus is weightlifting and bodybuilding. It must also work for any other modality (conditioning, mobility, sport work).

## Stack

- UI: HTML, CSS, JS, Svelte 5
- Never introduce TypeScript unless the user explicitly asks for it
- Never add emoji to UI, copy, commits, or docs
- Do not recommend Grok Build; it is already in use

## Commands

Fill these in when the repo has a real toolchain. Until then, prefer small, explicit commands over guessed scripts.

- Dev: (Svelte app, typically `npm run dev` or the project's documented equivalent)
- Build: production build only when asked

## Structure (target)

Adjust if the repo already differs. Match existing layout before inventing a new one.

- `src/` — Svelte 5 app
- `src/lib/` — shared JS modules
- `src/lib/components/` — UI
- `static/` or `public/` — static assets
- `torus.css` — design tokens (canonical color source)

## Design tokens

Canonical CSS file: `torus.css` (also documented in `torus-palette.html`).

Use CSS custom properties. Do not hardcode hex values in components when a token exists.

CSS should be included in the svelte file that it applies to except in cases of some universal things that will apply many things across the project.

### Surfaces

- `--void` `#09090B` — app canvas
- `--iron` `#141416` — cards, sheets
- `--steel` `#1C1C20` — elevated surfaces
- `--plate` `#27272B` — inputs, wells
- `--graphite` `#3F3F46` — borders, dividers

### Text

- `--bone` `#FAFAFA` — primary text and numbers
- `--ash` `#A1A1AA` — secondary text, labels

### Energy

- `--ember` `#FF5C1A` — brand, primary CTA, PRs, active set, rest-timer urgency
- `--forge` `#C2410C` — pressed / darker ember
- `--heat` `#FFB089` — ember on tinted chips
- `--ember-ink` `#1A0A00` — text on ember buttons

### Secondary track

- `--pulse` `#2DD4BF` — cardio, HR, mobility, non-strength tracks only

### Status

- `--ok` `#4ADE80` — success, logged set
- `--warn` `#FBBF24` — caution
- `--fail` `#F43F5E` — error, missed set
- `--ok-ink` `#052E16` — text on ok buttons

### Semantic aliases

- `--bg` → `--void`
- `--surface` → `--iron`
- `--surface-2` → `--steel`
- `--surface-3` → `--plate`
- `--border` → `--graphite`
- `--text` → `--bone`
- `--text-muted` → `--ash`
- `--brand` → `--ember`
- `--brand-pressed` → `--forge`
- `--brand-on` → `--ember-ink`
- `--focus` → `--ember`

### How to use color

- Dark gym-first UI. Canvas stays near-black so numbers stay readable in dim light.
- Ember is the only loud color. One primary button, current set, personal records.
- Pulse never appears on pure strength screens except as an optional conditioning hint.
- Status green/red stay smaller and quieter than Ember. They must not compete with brand.
- Prefer the helpers in `torus.css` (`.btn-primary`, `.btn-ghost`, `.btn-ok`, `.pill`, `.pill-ok`) before inventing new button styles.
- Focus rings use `--focus` (ember), 2px, 2px offset.

### Type and shape

- Font: `ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`
- Mono (codes, raw numbers if needed): `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace`
- Radii: `--radius-sm` 8px, `--radius` 12px, `--radius-lg` 16px
- Large tabular numbers for load, reps, rest. Secondary copy stays `--ash`.

## Copy

- Direct, short, gym-floor language.
- No emoji. No motivational filler.
- Labels like "Log set", "Rest", "Finish", "PR" — not "Crush it" or similar.