WORK-185
Setting up your dashboard 0 entities found · 8/31 branches scanned
ID:WORK-185Status:done

Typed token contract in @refrakt-md/types

Promote refrakt's design token surface from a set of CSS custom properties owned by Lumina into a typed TokenContract interface that any theme can supply values for. Establishes the foundation that every other v0.14.0 spec depends on.

Priority:highComplexity:mediumMilestone:v0.14.0Source:SPEC-048
main View source

Criteria completion

Criteria completion: 6 of 7 (86%) checked; history from May 18 to May 180%25%50%75%100%May 18May 18

Relationships

Implements 1
Related 13
Branches 2
main current done
claude/v0.14.0-spec-048-foundation doneclaude/spec-053-tint-authoring-notes ready
History 4
  1. cd8fa11
    • ☑ `TokenContract` interface exported from `@refrakt-md/types`, covering: `font` (sans, mono — `serif` deferred to a future amendment per SPEC-051), `color` (text, muted, border, bg, primary, primary-hover, primary-scale 50→950, surface { base/hover/active/raised }, info/warning/danger/success { base/bg/border }, code { bg/text/inline-bg }), `radius`, `spacing`, `inset`, `shadow`, `syntax`
    • ☑ `PartialTokenContract` interface for mode overlays — every field optional, every nested namespace optional
    • ☑ `ThemeTokensConfig` shape that accepts a `TokenContract` plus optional `modes` partials and an `extra: Record<string, string>` escape hatch
    • ☑ Strict typing: invalid field names rejected at compile time; values typed as strings (CSS values not validated structurally)
    • ☑ Inline JSDoc on each contract field documenting what the token is for and what CSS variable name it generates (`--rf-color-text` etc.)
    • ☑ Unit tests exercise the contract shape: a sample `ThemeTokensConfig` accepted at compile time, an invalid one rejected
    by bjornolofandersson
  2. a7947bb
    Content editedby Claude
    v0.14.0 Chunk 1: SPEC-048 foundation (WORK-185, 186, 189-types)
  3. 3b92415
    Created (ready)by bjornolofandersson
  4. f73346a
    Content editedby Claude
    plan: add v0.14.0 milestone and SPEC-048 work items (WORK-185 to 191)

Acceptance Criteria

  • TokenContract interface exported from @refrakt-md/types, covering: font (sans, mono — serif deferred to a future amendment per SPEC-051), color (text, muted, border, bg, primary, primary-hover, primary-scale 50→950, surface { base/hover/active/raised }, info/warning/danger/success { base/bg/border }, code { bg/text/inline-bg }), radius, spacing, inset, shadow, syntax
  • PartialTokenContract interface for mode overlays — every field optional, every nested namespace optional
  • ThemeTokensConfig shape that accepts a TokenContract plus optional modes partials and an extra: Record<string, string> escape hatch
  • Strict typing: invalid field names rejected at compile time; values typed as strings (CSS values not validated structurally)
  • @refrakt-md/transform, @refrakt-md/runes, @refrakt-md/lumina all import from these types — no parallel type definitions (deferred — the types exist and are exported; downstream packages will import them in later chunks as they adopt the contract. There are no parallel type definitions to remove today since the contract is new.)
  • Inline JSDoc on each contract field documenting what the token is for and what CSS variable name it generates (--rf-color-text etc.)
  • Unit tests exercise the contract shape: a sample ThemeTokensConfig accepted at compile time, an invalid one rejected

Approach

Single PR adding the types. No runtime behaviour changes — this is type infrastructure that the rest of the milestone consumes.

Structure under packages/types/src/:

  • tokens.ts — TokenContract, PartialTokenContract, TokenContract['color'] etc.
  • theme-tokens-config.ts — ThemeTokensConfig shape (base + modes + extra)
  • Export from packages/types/src/index.ts

Naming: prefer bg over background, text over primary (the swap fixed in SPEC-053), namespaces (surface.base) over flat fields where appropriate. Document the CSS-variable mapping rule explicitly — color.surface.base → --rf-color-surface-base, dot becomes dash.

The actual token values are not authored in this work item — that's WORK-200 (neutral default) and the preset modules. This is shape only.

Dependencies

None — foundational work item for the milestone. Unblocks WORK-186, WORK-187, WORK-188, WORK-189, WORK-190, WORK-191 and everything downstream.

References

  • SPEC-048 — Design tokens contract & config
  • packages/lumina/tokens/base.css — current implicit token surface; the contract describes what it formalises
  • packages/types/src/theme.ts — existing theme type surface to extend, not duplicate