WORK-196
Setting up your dashboard 0 entities found · 6/29 branches scanned
ID:WORK-196Status:done

mergeThemeConfig extends support + remove deprecated RefraktConfig.tints

Extend mergeThemeConfig (packages/transform/src/merge.ts) so tint definitions with extends?: string resolve their base before overlaying overrides. Reject circular extends chains with a clear error. The shallow per-name merge stays — extends is the canonical way to derive a tint variant from another.

Priority:highComplexity:smallMilestone:v0.14.0Source:SPEC-053
main View source

Criteria completion

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

Relationships

Implements 1
Related 5
Branches 2
main current done
claude/v0.14.0-spec-053-tint-vocab doneclaude/spec-053-tint-authoring-notes ready
History 4
  1. c1d4f32
    • ☑ Per-name overrides remain *shallow* (same name in two layers replaces the earlier one entirely) — `extends` is the explicit deep-override path
    by bjornolofandersson
  2. 7c7dd33
    Content editedby Claude
    v0.14.0 Chunk 5: SPEC-053 tint vocabulary alignment (WORK-195-199)
  3. 3b92415
    Created (ready)by bjornolofandersson
  4. 0d5a42c
    Content editedby Claude
    plan: add SPEC-053 tint shape alignment work items (WORK-195 to 199)

Acceptance Criteria

  • mergeThemeConfig walks each tint definition, resolves extends recursively via resolveTintExtends, and produces a fully-expanded final tint config
  • Circular extends chains rejected at merge time with a chain trace: "Circular tint extends chain: a → b → c → a"
  • References to non-existent tint names rejected with: "Tint 'X' extends unknown tint"
  • Per-name overrides remain shallow (same name in two layers replaces the earlier one entirely) — extends is the explicit deep-override path
  • Unit tests cover: single-level extends, multi-level chain, circular detection (including direct self-reference), unknown base, lockMode inheritance and override, diamond chains (no infinite recursion) — 10 new tests in tint-extends.test.ts
  • RefraktConfig.tints removed from packages/types/src/theme.ts; config-normalize no longer mirrors tints between flat and per-site shapes

Approach

Two related changes in one PR since they touch the same files and form a coherent slice of SPEC-053:

  1. Extends resolution. Before merging tint definitions, run a resolution pass that for each tint with extends, recursively expands the chain and applies the tint's own light / dark / lockMode on top. Cycle detection via a visited-set.
  2. Remove RefraktConfig.tints. The flat-shape shorthand is @deprecated today; v0.14.0 is the v1.0-cleanup window, drop it. Any code that reads it (likely in packages/transform/src/config-normalize.ts) gets updated to require sites.<name>.tints.

Dependencies

  • WORK-195 — types must reflect the new shape including extends.

References

  • SPEC-053 — "extends is the canonical override idiom" design principle
  • packages/transform/src/merge.ts — current mergeThemeConfig
  • packages/transform/src/config-normalize.ts — where tints is currently in the deprecated mirror list