DESIGN: resolve rituals space/radius/border scale divergence (decision memo 2026-07-23)

peterswimm commented

2026-07-24 14:25:03 +00:00

Owner

docs/reviews/token-divergence-2026-07-23.md (landed via PR #48) documents that the Rituals Flutter package and this repo publish the SAME token names with DIFFERENT values:

space1–8: app linear 4/8/12/16/20/24/32 (no space7; space5=20 from rituals#164) vs canon modular 4/8/16/24/32/40/56/64 — silent collision via token_manifest.dart 1:1 mapping
radius sm/md/lg: app 4/8/12 vs canon 3/9/18
border: app borderDefault/borderAccent/focusRing=2, borderThick=3 (1px retired per ville 2026-07-02) vs canon width=1 / width-emphasis=3; borderAccent/focusRing have no upstream names

Verified blast radius: rituals-web is the ONLY surface that visibly moves under a space re-value; forgejo theme (colors only), WP (not a rituals consumer), macOS (already linear, compile-time) are unaffected. App→modular migration ≈ 433 non-test call sites with RenderFlex-overflow risk.

Options per tier (memo §2/§3): (a) rituals dtcg override to app values + RATIONALE.yml · (b) app migrates to canon · (c) rename to make the fork explicit.

Ask: @ville + @peterswimm pick per tier. Blocks a meaningful sign-off on rituals#174.

cc @ville

docs/reviews/token-divergence-2026-07-23.md (landed via PR #48) documents that the Rituals Flutter package and this repo publish the SAME token names with DIFFERENT values: - space1–8: app linear 4/8/12/16/20/24/32 (no space7; space5=20 from rituals#164) vs canon modular 4/8/16/24/32/40/56/64 — silent collision via token_manifest.dart 1:1 mapping - radius sm/md/lg: app 4/8/12 vs canon 3/9/18 - border: app borderDefault/borderAccent/focusRing=2, borderThick=3 (1px retired per ville 2026-07-02) vs canon width=1 / width-emphasis=3; borderAccent/focusRing have no upstream names Verified blast radius: rituals-web is the ONLY surface that visibly moves under a space re-value; forgejo theme (colors only), WP (not a rituals consumer), macOS (already linear, compile-time) are unaffected. App→modular migration ≈ 433 non-test call sites with RenderFlex-overflow risk. Options per tier (memo §2/§3): (a) rituals dtcg override to app values + RATIONALE.yml · (b) app migrates to canon · (c) rename to make the fork explicit. Ask: @ville + @peterswimm pick per tier. Blocks a meaningful sign-off on rituals#174. cc @ville

ville commented

2026-07-28 11:20:07 +00:00

Member

My side of this: the actual values stand. space5=20 and border 2px were deliberate calls I already
made (#164, 2026-07-02) — they're not up for re-litigation here, just formalization.

(b) is off the table from my side either way — space migration is 400+ call sites with real
overflow risk for zero design benefit, and border (b) would mean reversing my own 2026-07-02
retirement of the 1px border, which I'm not doing.

So it's really (a) vs (c) — override rituals-dtcg to the app's values with a RATIONALE.yml entry,
vs. renaming so the fork is explicit instead of silent. That's more a call about how the shared
design system wants to represent a documented per-product fork than it is a Rituals design
decision, so I'll defer to you on which one, Peter — happy to sign off on either.

Two things need solving regardless of which option wins:

space7 has no linear equivalent on the Rituals side — my preference is to just drop it in the
override rather than leave a dangling unused value, but open to other takes if there's a reason
to keep the name reserved.
borderAccent / focusRing have no upstream names at all right now — that naming gap needs
filling no matter what we pick for the value question.

@peterswimm

My side of this: the actual values stand. space5=20 and border 2px were deliberate calls I already made (#164, 2026-07-02) — they're not up for re-litigation here, just formalization. (b) is off the table from my side either way — space migration is 400+ call sites with real overflow risk for zero design benefit, and border (b) would mean reversing my own 2026-07-02 retirement of the 1px border, which I'm not doing. So it's really (a) vs (c) — override rituals-dtcg to the app's values with a RATIONALE.yml entry, vs. renaming so the fork is explicit instead of silent. That's more a call about how the shared design system wants to represent a documented per-product fork than it is a Rituals design decision, so I'll defer to you on which one, Peter — happy to sign off on either. Two things need solving regardless of which option wins: - space7 has no linear equivalent on the Rituals side — my preference is to just drop it in the override rather than leave a dangling unused value, but open to other takes if there's a reason to keep the name reserved. - borderAccent / focusRing have no upstream names at all right now — that naming gap needs filling no matter what we pick for the value question. @peterswimm

peterswimm commented

2026-07-28 14:42:36 +00:00

Author

Owner

Direction: going with (a) override — adding Brand/UDG/products/rituals/dtcg/{space,radius,border}.json overrides so upstream matches the app's existing shipped values, rather than (c) renaming. The app already ships these values in production (token_registry.dart), so this requires zero Flutter/macOS code changes — only rituals-web and this repo's own design-tool previews move to match on next build. Option (c) would mean a ~700-occurrence Dart rename sweep in Toolville_Rituals, which is out of this repo's scope.

Resolving the two open technical questions:

space7: omitted from the override, per your preference. Baseline keeps 56px in the export; the app has no space7 consumer, so nothing dangles.
borderAccent / focusRing naming gap: adding a new canonical border.width-accent (2px) for borderAccent, which has real production usage (~15+ call sites). Not adding a canonical name for focusRing — traced its call sites and it has zero production callers in the app today (dead code, separate from the existing --focus-ring color token, which is unrelated and unaffected). Will file a Toolville_Rituals cleanup issue to remove it instead of inventing an upstream name for an unused token.

PR incoming with the override files + a version bump (1.1.0 → 1.2.0) + just build/just check. Will link it here.

Direction: going with **(a) override** — adding `Brand/UDG/products/rituals/dtcg/{space,radius,border}.json` overrides so upstream matches the app's existing shipped values, rather than (c) renaming. The app already ships these values in production (`token_registry.dart`), so this requires zero Flutter/macOS code changes — only `rituals-web` and this repo's own design-tool previews move to match on next build. Option (c) would mean a ~700-occurrence Dart rename sweep in Toolville_Rituals, which is out of this repo's scope. Resolving the two open technical questions: - **space7**: omitted from the override, per your preference. Baseline keeps 56px in the export; the app has no space7 consumer, so nothing dangles. - **borderAccent / focusRing naming gap**: adding a new canonical `border.width-accent` (2px) for `borderAccent`, which has real production usage (~15+ call sites). **Not** adding a canonical name for `focusRing` — traced its call sites and it has zero production callers in the app today (dead code, separate from the existing `--focus-ring` *color* token, which is unrelated and unaffected). Will file a Toolville_Rituals cleanup issue to remove it instead of inventing an upstream name for an unused token. PR incoming with the override files + a version bump (1.1.0 → 1.2.0) + `just build`/`just check`. Will link it here.

peterswimm referenced this issue

2026-07-28 17:17:38 +00:00

DESIGN: derived interaction-state tests assume a per-product CSS var scheme the color.json files explicitly reject #72

peterswimm referenced this issue from a commit

2026-07-28 17:46:49 +00:00

feat(rituals): override space/radius/border tokens to match app (design #51)

peterswimm referenced this issue from a pull request that will close it,

2026-07-28 18:05:56 +00:00

feat(rituals): override space/radius/border tokens to match app (design #51) #73

peterswimm closed this issue

2026-07-29 01:02:29 +00:00

peterswimm referenced this issue from a commit