ALFMOB-264: Adopt latest design tokens + future-proof TokenLoader for multi-mode collections

[khoinguyen-mindera]

ALFMOB-264 — Adopt latest design tokens + future-proof TokenLoader

Ticket (Epic): ALFMOB-264 · ADR: ALFMOB-293 · Token repo: Alfie-Mobile-Design-Tokens

Scope: this is the remaining Phase-1 slice of the epic — token re-adoption from the now-merged upstream main + a TokenLoader correctness fix. It does not cover Phase-2 (component refactor + snapshot tests); see the coverage table below.

What & why

The token codegen pipeline (ALFMOB-272) and the color/typography/spacing integrations (ALFMOB-274/266/270) already landed. Two gaps remained: (1) the token JSON needed re-pulling from the in-house figma-plugin export once it merged upstream, which surfaced (2) a latent TokenLoader crash risk now that the theme collection ships a second brand mode (selfridges) iOS doesn't use.

Changes

• TokenLoader multi-mode hardening (Tools/DesignTokenGen):
  • Pins theme → alfie-theme (iOS doesn't ship the new selfridges mode).
  • Any future unpinned collection that gains a 2nd mode now fails fast with an actionable message (add a pin to modeForCollection) instead of a downstream opaque fileNotFound.
  • +regression tests (41 generator tests pass).
• Re-adopted token JSON from upstream main (SharedUI/DesignTokens/). Font-weight primitives are now correctly typed fontWeight (previously filtered out) and font-family primitives fontFamily, so generated Swift references symbols (Primitives.Typography.fontWeightRegular) instead of inlining literals (400).
• Fixed body-medium-strikethrough font-weight (was mis-bound to a font-family variable, previously flattened to a silent 400).
• pull-design-tokens.sh gains a DESIGN_TOKENS_REF override (defaults to main) for pre-merge testing.

Reproducibility

Re-ran pull-design-tokens.sh + generate-design-tokens.sh against upstream main: pulled JSON and generated Swift are byte-identical to what's committed here. The work stands entirely on merged upstream sources.

Acceptance-criteria coverage (epic-wide)

#	Criterion	Status
1	DTCG JSON stored in repo	✅ (refreshed here)
2	Build-time codegen → Swift	✅ ALFMOB-272
3	Generated Swift preserves references (theme→primitives)	✅
4	Color/typography/spacing/shape integrated	✅ ALFMOB-274/266/270
5	Typography uses Figma names (display.large…)	✅ ALFMOB-266
6	5 core components use tokens	⬜ Phase 2 (ALFMOB-136)
7	Component APIs backward-compatible	➖ ongoing
8	Snapshot tests validate consistency	⬜ Phase 2 (snapshots disabled repo-wide)

Verification

./Alfie/scripts/verify.sh --skip-integration → ✅ build + unit tests pass (integration skipped — no local BFF).

Notes

• Commits carry over from the earlier draft PR Adopt latest design tokens + future-proof TokenLoader for multi-mode collections #89 (claude/affectionate-hodgkin-b608a2), re-homed onto this feat/ALFMOB-264-* branch — PR Adopt latest design tokens + future-proof TokenLoader for multi-mode collections #89 can be closed as superseded.
• No hand-edits to GeneratedTokens/ or project.pbxproj (both regenerated).

[Copilot]

Pull request overview

This PR completes the remaining Phase-1 work for ALFMOB-264 by re-adopting the latest upstream design-token JSON and updating the token generator’s TokenLoader to be resilient to collections that add additional modes (like theme gaining selfridges).

Changes:

• Hardened TokenLoader.selectedFiles to pin theme to alfie-theme and to fail fast (with an actionable error) when an unpinned collection becomes multi-mode.
• Refreshed committed token JSON and regenerated Swift token surfaces to preserve primitive references (not inline literals), including properly typed fontWeight primitives.
• Added DESIGN_TOKENS_REF to pull-design-tokens.sh to support pre-merge token testing against non-main refs.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
Tools/DesignTokenGen/Tests/DesignTokenGenCoreTests/GeneratorTests.swift	Adds regression coverage for multi-mode theme pinning and unpinned multi-mode fail-fast behavior.
Tools/DesignTokenGen/Tests/DesignTokenGenCoreTests/Fixtures/mini/manifest.json	Extends test fixture manifest with a second theme mode (selfridges) to exercise pinning.
Tools/DesignTokenGen/Sources/DesignTokenGenCore/TokenLoader.swift	Pins theme mode and introduces explicit fail-fast behavior for unpinned multi-mode collections.
Alfie/scripts/pull-design-tokens.sh	Adds DESIGN_TOKENS_REF override and clones that ref for reproducible token pulls.
Alfie/AlfieKit/Sources/SharedUI/GeneratedTokens/Typography+Generated.swift	Regenerated typography styles to reference typed font-weight primitives instead of inlined numeric literals.
Alfie/AlfieKit/Sources/SharedUI/GeneratedTokens/Theme+Generated.swift	Regenerated theme surface to reflect updated upstream theme tokens (new/expanded mappings).
Alfie/AlfieKit/Sources/SharedUI/GeneratedTokens/Primitives+Generated.swift	Regenerated primitives (adds typed font-weight primitives, border style, and normalizes numeric literals).
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/typography.styles.tokens.json	Updates composite typography style definitions to reference per-style font-weight variables.
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/typography.alfie-theme.tokens.json	Updates typography token set including correct fontWeight typing and fixed bindings for strikethrough.
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/theme.alfie-theme.tokens.json	Updates theme tokens to the latest upstream structure and adds new button/border/content tokens.
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/system.ios.tokens.json	Refreshes system/iOS token definitions and ordering to match upstream export.
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/sizing.alfie-theme.tokens.json	Refreshes sizing tokens to match upstream export (including ordering/structure updates).
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/screen-size.small-(s).tokens.json	Refreshes screen-size small mode tokens and ordering to match upstream export.
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/manifest.json	Updates manifest collections/modes (including multi-mode theme) to match upstream export.
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/.primitives.alfie-theme.tokens.json	Refreshes primitives export (now includes font-weight primitives and normalized component formats).
Alfie/AlfieKit/Sources/SharedUI/DesignTokens/.broken-ref-allowlist.json	Clears previously-allowlisted missing font-weight targets now present in the upstream export.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

[hoangnhatdrk]

Nice, tightly-scoped hardening — the fail-fast cascade with actionable messages is a clear improvement over the opaque downstream fileNotFound, and the tests reproduce the exact theme.selfridges regression. 👍

One thing worth calling out explicitly before merge: the regeneration flips Primitives.Border.borderWeightDefault from Int → CGFloat. That's a source-breaking change for any Int consumer of the token. CI is green so the target compiles — just flagging it since it's an easy-to-miss API shift (and it's what lets #92 use the token unwrapped as a lineWidth).