torus/AGENTS.md

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.