tovr-design

Files (5)

• SKILL.md
• artifact-starter.html · assets/
• primitives.md · references/
• rules.md · references/
• tokens.md · references/

SKILL.md (first lines)

# TOVR Design System

TOVR is a freight-intelligence platform for European road transport. The UI is **calm, dense, and monochrome** — structure and typography carry the design, not color.

**The source of truth is the code, not this skill.** Before writing production UI, read the live files (paths below) for current values. This skill encodes the *rules, philosophy, and a token cheat-sheet* so you design as an expert in the brand without copying values that will drift.

## Live source of truth (read these in the monorepo)
- `apps/web/app/[locale]/globals.css` — all tokens (Tailwind v4 CSS-first; `@theme inline`). **No `tailwind.config.*` exists** — the theme lives here.
- `apps/web/components/ds/` (+ `ds/index.ts` barrel) — the on-brand primitive layer. Compose pages from these.
- `apps/web/components/ui/` — the Shadcn (new-york, neutral) base layer that `ds/` sits above.
- `apps/web/eslint.config.mjs` — the monochrome guard (bans raw palette classes). Your CSS must pass it.
- `apps/web/components/map/map-colors.ts` — the ONE sanctioned place for literal hex (WebGL/Mapbox canvas can't read CSS vars).
- `specs/general/design-audit-private-pages.md` — the authoritative rules doc.

## What's in this skill
- `references/tokens.md` — the grayscale ramp, semantic tokens, type, radius, tracking, motion (cheat-sheet + source pointer).
- `references/primitives.md` — the `ds/` inventory and when to use each (Panel over Card, Stat/StatGrid over Card grids, Container 1180, Eyebrow, PageHeader).
- `references/rules.md` — overlays (Sheet/Dialog/AlertDialog), page identity, single-scroll, semantic-color usage, the ESLint ban list, known debt.
- `assets/artifact-starter.html` — a self-contained, theme-aware, monochrome **Artifact scaffold**. Copy it to start any UI Artifact on-brand in seconds.

## Artifact-first workflow (required for UI work)
Any UI issue labelled `needs-artifact` must produce a **published, signed-off Artifact before code**. To do it:
1. Copy `assets/artifact-starter.html`, build the screen(s) with the token variables it defines.
2. Publish via the Artifact tool (load the `artifact-design` skill first). It renders theme-aware — style both light and dark.
3. **Artifacts run under a strict CSP that blocks external fonts** — Geist can't be network-loaded there. Use the starter's system-sans fallback stack and keep the monochrome + tight tracking; the brand still reads. (In production code, Geist loads via `next/font` and is already wired.)

## Non-negotiables
- **Monochrome only.** Neutrals are zero-chroma OKLCH; `--primary` *is* the foreground. The only chromatic tokens are `--destructive` (red), `--success` (green), `--warning` (amber), each with a `-foreground`. Tints come from **opacity modifiers** on those tokens (`bg-success/10`, `border-warning/30`, `text-destructive`) — **never** palette scales (`bg-green-50`, `text-red-600`). The ESLint guard fails the build otherwise.
- **Semantic, not decorative.** Color = status meaning (good/warn/bad), never per-category rainbow. Analytics icons, stat icons, CTAs are monochrome.
- **Type:** Geist (UI/body), Geist Mono (data, numbers, eyebrow labels). Headings use tight negative tracking (`-0.03em`…`-0.04em`); body tracking is `-0.02em` globally. Eyebrows are mono, uppercase, wide-tracked, muted.
- **Structure over decoration:** hairline `--border` surfaces, whisper shadows, generous density. No gradients, no rainbow.
- **Compose from `ds/`:** `Panel`/`PanelHeader` over `ui/card`; `Stat`/`StatGrid` over card grids; `Container` (max 1180px) for page width. Pages must **not** render their own title header — identity comes from the shell breadcrumb (`lib/breadcrumb-config.ts`). The single scroll container is the shell's `<main>`.
- **Overlays:** `Sheet` = detail/master-detail; `Dialog` = focused create/edit; `AlertDialog` = every destructive confirm. Never native `confirm()` or a hand-rolled `fixed inset-0` (the fOS agent surface is the one sanctioned exception).

## How to work
- **Visual artifact / mock / slide:** copy `assets/artifact-starter.html`, build static HTML with the token vars, publish as an Artifact.
- **Production UI:** read the live source above, compose from `ds/` + `ui/`, honor the non-negotiables, and verify against the ESLint guard. Add i18n keys in all three locales (`bg`/`en`/`de`) for any user-facing string (see the monorepo CLAUDE.md i18n section).

If invoked without specifics, ask what surface they're building (marketing page vs app screen vs artifact/mock), then act as an expert TOVR designer.

From the-tovr/tovr-skills, MIT.

More from the-tovr/tovr-skills