Decksmith

Appearance

ADR-0015: Design System Architecture — Tokens, Theming, and No-Figma Workflow ​

Last Updated: 2026-05-30
Status: Active
Context: Decksmith

Context ​

Decksmith needs a design system that:

  • Supports a dark theme (primary) and a light theme, switchable at runtime without a page reload
  • Encodes MTG-specific visual language: mana colour tokens and mana symbol icons
  • Can eventually be consumed by both apps/web (React/Tailwind) and apps/mobile (React Native)
  • Can be iterated on without a dedicated designer or separate design tool

Four interrelated decisions had to be made:

  1. Where and how is the visual language defined? (tokens strategy)
  2. How is theming implemented? (CSS custom properties vs Tailwind dark: variant)
  3. How do we design without Figma? (no-Figma workflow)
  4. How are MTG mana symbols rendered? (Keyrune vs custom icons vs coloured circles)

Note: Phase 4.0 produced documentation. packages/tokens and packages/web-ui are not yet built. Specific values (colour hex codes, spacing scale, typography sizes, component APIs) are current best thinking and will be refined during Phase 4.1 implementation. The architectural patterns documented here — CSS custom properties, token package, Keyrune — are stable.

Current Decision ​

1. Tokens in packages/tokens ​

All design tokens are defined once in packages/tokens and consumed by platform packages:

  • apps/web/tailwind.config.ts imports decksmithPreset from packages/tokens/src/tailwind.ts
  • apps/mobile (future) reads raw token values directly from packages/tokens/src/tokens.ts

Token categories:

CategoryExamples
Semanticbg, surface, surface-raised, border, text, text-muted, text-faint
Accentaccent, accent-hover, accent-subtle, accent-border
MTG colourmtg-white, mtg-blue, mtg-black, mtg-red, mtg-green, mtg-colorless, mtg-multi
TypographyFont families, size scale (xs → 4xl), weights
SpacingShared spacing scale

MTG colour tokens are defined as a separate group from semantic tokens — they represent Magic's colour identity system, not UI states. mtg-red ≠ error even though both are red hues.

2. CSS Custom Properties for Theming ​

Dark/light theme is implemented via CSS custom properties on :root (light) and .dark (dark override), not via Tailwind's dark: class variant.

css
:root {
  --color-bg: #faf9f4;
  --color-surface: #ffffff;
  --color-text: #1c1b22;
}

.dark {
  --color-bg: #0f0e17;
  --color-surface: #1a1827;
  --color-text: #e8e6f0;
}

Tailwind classes reference the CSS var through decksmithPreset:

ts
// packages/tokens/src/tailwind.ts
colors: {
  bg: 'var(--color-bg)',
  surface: 'var(--color-surface)',
  text: 'var(--color-text)',
}

Components use semantic class names (bg-bg, bg-surface, text-text-muted). Theme switches by toggling .dark on <html> — no page reload, no class proliferation in JSX.

3. No-Figma Workflow ​

Figma is not used as design source of truth. The design-to-code workflow is:

ASCII mocks (apps/docs/design/screens/)
    ↓
packages/tokens  (visual language — colours, type, spacing)
    ↓
Tailwind config  (decksmithPreset applied to apps/web)
    ↓
packages/web-ui  (shadcn/ui base + Decksmith-specific components)
    ↓
Storybook        (visual iteration + living documentation)

ASCII mocks in apps/docs/design/screens/ define screen structure and layout regions. They live in version control alongside the specs they reference. packages/web-ui + Storybook replace Figma for visual component iteration.

4. Mana Symbol Icons — Inline SVG (mana-font paths) ​

MTG mana symbols ({W} {U} {B} {R} {G} {C} {X} etc.) are rendered using inline SVG path data sourced from mana-font. The implementation consists of three composed components:

  • ManaIcon — pure SVG element, fill="currentColor", zero dependencies. Takes a symbol key ('w', 'u', 'b', 'r', 'g', 'c', 'x', 'tap', numeric generics, etc.).
  • ManaSymbol — wraps ManaIcon in a rounded pip container with the correct bg-mtg-* token color. This is the canonical colored pip that mirrors physical card appearance.
  • HybridManaSymbol — diagonal split pip via SVG clipPath triangles for hybrid costs ({W/U} etc.)
  • ManaCost — parses a cost string and renders a row of ManaSymbol / HybridManaSymbol.

Convention: {W}, {U}, {B}, {R}, {G} notation in ASCII mocks maps to <ManaSymbol symbol="W" /> in React. In Storybook stories, Lucide icons are used for decoration; mana glyphs always use these components.

WUBRG colour tokens (mtg-white, mtg-blue, etc.) are the canonical source for pip background colors, text in color-identity badges, and rarity chips — always via tokens, never hardcoded.

Rationale ​

Why packages/tokens rather than values directly in tailwind.config.ts? ​

apps/mobile cannot use Tailwind — it needs raw token values. Centralising tokens in a shared package prevents the web and mobile implementations from drifting apart. The same principle as packages/schema for data contracts: one source, multiple consumers.

Why CSS custom properties over Tailwind dark: variant? ​

The dark: variant requires every component to duplicate its classes: bg-white dark:bg-gray-900. As the component library grows, this creates two problems:

  1. Verbosity: every new component must remember both variants — a maintenance burden, not a one-time cost.
  2. Semantics: bg-gray-900 is a colour value, not a meaning. bg-surface is a meaning whose value changes with the theme. Semantic names are more readable and more robust to palette changes.

With CSS vars, a component uses one class (bg-surface). Runtime theme switching is one line: document.documentElement.classList.toggle('dark'). No rebuild, no page reload.

Why no Figma? ​

Figma creates a second source of truth. Design drift — where Figma shows one thing and the code does another — is a constant maintenance tax. Every Figma change requires a code update (or vice versa), and without a dedicated designer to enforce the sync, it breaks quickly.

For a solo/small-team project, the cost of maintaining Figma sync outweighs its benefits:

  • ASCII mocks are version-controlled, co-located with specs, and reviewed in the same PR
  • Storybook provides the living component gallery that Figma would otherwise be used for
  • The no-Figma workflow forces decisions to be made in code, where they actually live

Why inline SVG paths instead of Keyrune or bare coloured circles? ​

Every MTG player recognises {W} {U} {B} {R} {G} as canonical symbols — they see them on every card they own. Bare coloured circles lose the iconic semantics: the white mana symbol (sun) is immediately understood; a white circle is ambiguous and requires text labels to communicate meaning.

Keyrune (the original decision) was planned before implementation. The inline SVG approach was adopted instead for three reasons:

  1. No external asset load — Keyrune requires loading mana.css (a CSS icon font). Inline SVG paths are bundled directly, with zero network dependency after the initial page load.
  2. Tree-shakeable — only the symbols actually used appear in the bundle. Keyrune ships all symbols regardless.
  3. Full styling control — fill="currentColor" on ManaIcon means any CSS color applies. Combined with mtg-* token pip backgrounds, the result matches the physical card appearance exactly — which Keyrune with a CSS font would require additional CSS to achieve.

The mana-font SVG path data covers the same symbol set as Keyrune (including {W/U} hybrids, {C}, {X}, {T}, numeric generics 0–20, Phyrexian mana, snow, energy, etc.).

Trade-offs ​

Benefits:

  • Single token source shared across web and mobile — no duplication or drift
  • Runtime theme switching with zero changes to component code
  • Semantic class names (bg-surface) are more meaningful and more stable than colour names
  • Mana icons are immediately recognisable to the target audience (canonical WotC glyph shapes)
  • No external tool dependency for design iteration
  • Design decisions are version-controlled and reviewed in PRs

Costs:

  • CSS vars are slightly less discoverable in JSX than explicit dark: classes
  • Storybook must be set up before visual component iteration is possible
  • packages/tokens must be built before apps/web or packages/web-ui can start
  • mana-paths.ts adds bundle weight, but only the symbols used are included (tree-shaken)

Risks:

  • Token names agreed here may not match what feels natural when building components
    • Mitigation: names are not committed in code yet — they will be finalised during Phase 4.1 (packages/tokens scaffold). ADR to be updated then.
  • Without Figma, no high-fidelity mockup to show stakeholders
    • Mitigation: Storybook serves as the live component gallery; ASCII mocks are sufficient for planning at this stage

Evolution History ​

2026-06-10: Web output format updated — Tailwind v4 CSS-first confirmed ​

The ADR-0015 section on tokens referenced a Tailwind v3 JS preset approach (decksmithPreset in tailwind.config.ts). The actual implementation (Phase 4.1) uses the Tailwind v4 CSS-first architecture: packages/tokens/src/web/tokens.css uses @import 'tailwindcss' with @theme inline (for dynamic theme-aware tokens) and @theme (for static tokens). No tailwind.config.ts or JS preset object exists. Details in ADR-0017.

2026-06-08: Token values finalised — Session A (Phase 4.0.5) ​

  • Accent colour shifted from Tailwind amber-500 (#f59e0b) to golden #e8b84b — less orange, more "doré chaud". Light mode accent-text set to #8a6a0c for WCAG AA compliance on light bg.
  • New tokens: on-accent (text on amber button — always #0f0e17), accent-text (accent-hued text that passes contrast).
  • Tailwind v4 @theme CSS confirmed as the web output format — no JS preset object needed.
  • Implementation details (layer structure, output format, motion system, Storybook requirements) documented in ADR-0017.
  • This ADR remains the source of truth for strategic decisions (where, how, why); ADR-0017 owns the concrete implementation.

2026-05-30: Initial decision ​

  • Decided after completing Phase 4.0 design documentation (PR #16)
  • ASCII mocks created for all 7 screens — documented in apps/docs/design/screens/
  • Visual identity defined: #0f0e17 dark bg, #faf9f4 light bg, amber #f59e0b accent, Outfit typeface, JetBrains Mono for numbers/stats
  • All individual design decisions logged in apps/docs/design/decisions.md
  • Status: architectural patterns locked, specific values (hex, spacing, type scale) will be refined during Phase 4.1 implementation

References ​

Built with VitePress