Canvas Design System
Main Site Tokens

Start Here

One entry point for designers, developers, and Claude. It tells you which file is authoritative for what, and where to go next. The written companion is /design-system/START-HERE.md.

The source-of-truth hierarchy

Several documents describe Workshopr's look, voice, and components. They do not rank equally. When two files disagree, the higher one wins.

Rank File Authoritative for Audience
1 /DESIGN.md · /motion.md Brand, voice, visual system, UX, forms · motion stack — the canonical intent Human + Claude
2 platform-tokens.css · helpers.php The literal token values and component behavior every app imports Code
3 workshopr-design-system.json Machine-readable mirror of tokens + component catalog + rules (hand-maintained) Claude / tooling
4 workshopr-style-guide.md Long-form written spec Human
5 This site · app-*.php · components/*.php Live, rendered demos and per-app guides Human (browser)

Plain version: DESIGN.md + motion.md decide intent. platform-tokens.css + helpers.php are the implementation truth. The JSON is a convenience mirror, guarded against drift by check-drift.php. These demo pages are illustrative, not law.

Pick your on-ramp

🤖 Claude / AI

  1. /DESIGN.md — non-negotiable brand/voice/UX rules
  2. workshopr-design-system.json — tokens, full ws_* catalog, the rules block
  3. helpers.php — ground truth if JSON and a real function disagree
  4. app-<name>.php — layout + the phase color to use

🎨 Designer

  1. /DESIGN.md — the brand and voice bible
  2. Browse this site: Colors, Typography, Components
  3. workshopr-style-guide.md — the written deep-dive
  4. App Theming — per-app phase colors

🔨 Developer

  1. @import 'platform-tokens.css' — every color/space/type/radius/shadow var
  2. Use ws_* helpers (49 of them) — live demos
  3. ADOPTION.md — what each app has migrated
  4. After any change: php design-system/check-drift.php

Keeping it honest: drift control

The JSON is a hand-maintained mirror, so two guards keep it from silently falling out of sync with the CSS and PHP. CI and the pre-commit hook enforce both.

check-drift.php

Fails if any ws_* helper is undocumented in the JSON (or vice-versa), or if phase-color tokens in platform-tokens.css disagree with the JSON. Resolves var() aliases.

npm run lint:ds:drift

generate-catalog.php

Generates components.generated.json, a source-derived roster of every ws_* helper (signature, summary, declared options) parsed from the helpers.php docblocks. The can't-drift companion to the curated JSON.

npm run gen:ds:catalog

Four phases & documented color exceptions

LEARN (#E54D4D) → PLAN (#0284C7) → FACILITATE (#7C4DFF) → REFLECT (#10B981). Each app uses its phase color — with these sanctioned exceptions:

  • Tips ships Facilitate purple (#7C4DFF), not Learn red — a deliberate cross-phase brand choice. (apps.tips.colorNote)
  • Academy/Training is Learn red (#E54D4D). The unimplemented "training = green" mapping was retired.
  • DNA surface primary is the lighter #34D399; the Reflect phase anchor is #10B981 — layering within one phase, not drift.