Veltofit: I audited my own design system

What this is

Veltofit is a fitness SaaS I designed and built myself, with AI from the first commit: Cursor for the MVP, then Claude. Git only shows Claude's co-author tag from March 2026, because that's when I switched. Since July, almost every commit carries it.

Since the rebuild there's no Figma file. The design system is the code. So I audited it the way I'd audit a client's: read-only, every number from a command you can rerun. Being your own client has one advantage: there's nobody else to blame. All figures are a snapshot as of October 6, 2026.

Veltofit in one paragraph

Veltofit is a trainer-first platform: plans, clients and progress in one place, instead of PDFs, spreadsheets and WhatsApp. The constraint behind most design decisions: a trainer uses it with one hand, between sets. That's all the product you need. The rest is about the system underneath.

From MVP to a system

The first version ran on Tailwind, designed from Figma mocks. It was an MVP to test the idea, and it did that job. In January 2026 I started v2: my own design system plus a back-end refactor, on SCSS modules from the first commit. The reasons I wrote down at the time:

"SCSS Modules over Tailwind: Better for 1:1 design match, smaller bundle" (v2/REFACTOR_PROGRESS.md)

"Convert to SCSS modules for exact control" (v2/docs/audits/DESIGN_SYSTEM_AUDIT.md)

"Smaller bundle" was a reason, not a result: I never measured it. And the tool wasn't the point. Tailwind lets you write p-[13px]; SCSS lets you write padding: 13px. What matters is whether the system allows raw values, and whether something checks.

The turning point: agents

On April 4, 2026 I gave the project agents and skills, so the output stopped depending on how well I phrased each request. There are 7 agents now. Every UI change takes the same route: frontend-dev → design-reviewer → code-reviewer. The design reviewer is read-only (tools: Read, Grep, Glob): it can fail a change, never fix it.

6. **No Tailwind.** SCSS modules only. Use `@use '@/app/_mixins' as *;` at top of every SCSS file.
7. **No hardcoded values in SCSS.** Every color → `var(--*)`. Every spacing → `var(--spacing-*)`. Every radius → `var(--radius-*)`. Every font → mixin.
8. **Use existing components.** Check `src/components/ui/` before building any UI element.

**FAIL if you find:**
- Any hardcoded hex/rgb/hsl color (e.g., `#437AB1`, `rgb(...)`, `hsl(...)`) — must use `var(--primary)` etc.
- Any hardcoded `px` spacing value (e.g., `padding: 16px`, `gap: 8px`) — must use `var(--spacing-*)` tokens
- Any hardcoded font-size, font-weight, line-height — must use typography mixins like `@include heading-2`
- Any hardcoded border-radius (e.g., `border-radius: 8px`) — must use `var(--radius-md)` etc.
- Any hardcoded z-index number — must use `var(--z-*)` tokens
- Any hardcoded shadow/transition values — must use tokens

After that, the output got noticeably more precise: with the review agents in the loop, it matched what I wanted almost every time. That's my experience, not a metric. The audit shows where it held.

Scorecard: 5 AI-ready, 5 not

AI-ready:

1. One source of truth. All 195 tokens in globals.scss, one rule against raw values.
2. A read-only reviewer with explicit FAIL conditions.
3. Comments record the reason, a measurement and a date, so an agent can check a value instead of "fixing" a deliberate choice.
4. Predictable file shape. Every component is index.tsx plus styles.module.scss.
5. Reference material: 37 design-system pages, a token skill, a self-audit script, a "Last verified" date on CLAUDE.md.

  /* Text-on-tint variants (dark on light) — brighter siblings live in :root.
     Lightness is tuned so each clears WCAG AA (4.5:1) against its own faint
     tint composited over BOTH --bg-surface (#FFFFFF) and --bg-base (#F8FAFC):
       --warning-text on --color-streak-bg   → 5.00:1 / 4.81:1
       --error-text   on --error-10          → 7.14:1
       --success-text on --color-progress-bg → 4.96:1 / 4.78:1
     --warning-text was 35% (3.87:1, failed AA) — dropped to 30%.
     Hue tracks the tint each one sits on: 38 = --color-streak, 142 = --success. */
  --warning-text: hsl(38, 92%, 30%);
  --error-text: hsl(0, 84%, 35%);
  --success-text: hsl(142, 71%, 28%);

Not AI-ready:

1. Names that mislead. --neutral-white is dark navy in dark mode; --line-height-relaxed is tighter than --line-height-normal.
2. Instructions that disagree with the code. See below.
3. A measuring tool that's wrong. 9 "unused" components are in use.
4. Missing primitives. No variant helper, no shared motion presets. Skeleton has no size props, so it has 102 inline styles.
5. Dead code that looks alive. PlanCard and WorkoutCard are documented as complete and rendered nowhere.

What the audit found

97% tokenized, and the 3% isn't random. There are 6,692 token references in SCSS against about 205 raw values. The raw values cluster in the oldest components, ported from the Tailwind MVP; components added since July mostly use tokens. Six findings matter most for AI:

  for (const folder of componentFolders) {
    const importPattern = `@/components/ui/${folder}`;
    const usedInFiles: string[] = [];

    for (const file of tsxFiles) {
      const content = readText(file);
      if (content.includes(importPattern)) {
        usedInFiles.push(relative(ROOT, file));

  const { profile } = useAuthStore();
  const themeColor = profile?.theme_color || null;
  const { accent, hex } = getThemeColor(themeColor);

  // Accent color (dynamic theme)
  const accentColor = hex ?? `hsl(${accent})`;

  // Accent background colors (for secondarySolid and hover states)
  const accentBg = hex ? 'rgba(23,23,23,0.06)' : `hsl(${accent} / 0.06)`;
  const accentBgMedium = hex ? 'rgba(23,23,23,0.1)' : `hsl(${accent} / 0.1)`;

The drift is real, but visible, because the system writes down why.

What broke, and what I'd do differently

Agents earlier. They arrived two and a half months into v2, and the raw values cluster in the components ported before that. I can't prove one caused the other, but next time the reviewer exists before the first component.

Treat instructions as code. A reviewer is only as current as its rules. Instructions, skills and audit scripts need the same tests and freshness checks as the code they guard.

What I wouldn't change: a quick Tailwind MVP to test the idea.

The same lesson showed up in the 18 runs behind this site's demo. The model wasn't careless: given a library that never marked its brand teal, every pricing card and settings form came out with a blue button, and the empty-state runs switched between two primary buttons because nothing said which one was current. It couldn't know intent the system never wrote down. See the demo→

All figures: read-only scan of main at 0a1757a, October 6, 2026, including uncommitted changes in the working tree.