feat: harden native design-token semantics

[altaywtf]

Closes #158

Summary

Turns the generic @putdotio/design artifact into a dark-only native Apple adapter with semantic colors, exhaustive token coverage, and selective Dynamic Type scaling for content-coupled spacing and meaningful icons.

Changed

• generates one universal dark/global value per semantic color asset; unused light-theme inputs are explicitly excluded
• loads compiled assets through Bundle.module on product targets and generated inline fallbacks during direct macOS SwiftPM tests
• classifies all 449 upstream tokens and rejects unclassified tokens, divergent aliases, light-mode semantic sources, or generated-output drift
• adds text-style-relative metric and icon roles while keeping structural spacing, radii, borders, overscan, and interaction geometry fixed
• exercises accessibility-sized iOS rendering and stabilizes tvOS headless relaunch proof

Review aids

flowchart LR
  A["@putdotio/design public export"] --> B["coverage and invariant audit"]
  B --> C["generated Swift roles"]
  B --> D["dark-only color catalog"]
  C --> E["PutioCore"]
  D --> E
  E --> F["iOS"]
  E --> G["watchOS"]
  E --> H["tvOS"]

Loading

Headless exercised-state evidence for the dark-only catalog, pinned to 7dcdbd0:

• iOS at accessibility Dynamic Type size
• paired watchOS
• tvOS

Later commits only strengthen generator invariants and direct SwiftPM color resolution; mise run verify covers them at b37490f.

Risks

• adding or changing an upstream token intentionally blocks generation until coverage and semantic invariants are satisfied
• scalable metrics require an explicit semantic text style; the raw spacing ramp remains fixed

Verification

• mise run verify
• seven generator tests covering boundary parsing, public export, dark-only assets/modes, classification, aliases, and drift
• direct SwiftPM runtime color-resolution test
• PutioCore and harness Swift package tests
• headless all-platform proof
• independent Codex autoreview after fixes: clean, 0 findings

Complexity

The adapter keeps one generated public surface and one explicit coverage manifest; no runtime token parsing or additional generator dependency was added.

[Copilot]

Pull request overview

This PR hardens the @putdotio/design → Apple-native adapter by generating a semantic Swift surface (PutioTheme) plus a Bundle.module-backed adaptive color asset catalog, and by enforcing exhaustive upstream-token classification via an explicit coverage manifest. It also introduces selective Dynamic Type scaling for content-coupled spacing and meaningful icon roles, and tightens harness exercise behavior (notably for tvOS relaunch).

Changes:

• Switch token ingestion to the package’s public export, generate semantic adaptive colors into PutioColors.xcassets, and validate drift/coverage via scripts/design-token-coverage.json.
• Add scalable metric/icon roles (PutioMetricRole, @PutioScaledMetric, PutioIconRole) while keeping structural spacing/radii/borders fixed.
• Update app shells, tests, docs, and harness logic to exercise accessibility Dynamic Type on iOS and stabilize tvOS exercised relaunch.

Reviewed changes

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

Show a summary per file

File	Description
Tools/PutioHarness/Sources/PutioHarnessKit/SimulatorHarness.swift	Adds tvOS-specific termination + liveness wait to stabilize exercised relaunch in harness runs.
scripts/generate-design-tokens.ts	Resolves tokens via package export, generates adaptive color asset catalog, and enforces exhaustive coverage/drift checks.
scripts/generate-design-tokens.test.ts	Adds tests for public-export resolution, asset-catalog rendering, and coverage enforcement on new tokens.
scripts/design-token-coverage.json	Introduces explicit coverage manifest classifying every upstream token (generated/aliased/excluded).
README.md	Documents semantic adapter output, coverage requirements, and the fixed-vs-scaled metric policy.
Packages/PutioCore/Tests/PutioCoreTests/SignedOutPresentationTests.swift	Extends harness scenario tests to cover the new isHarnessExercise convenience.
Packages/PutioCore/Tests/PutioCoreTests/PutioThemeTests.swift	Updates tests for new metric/icon roles and removes obsolete dynamic-color behavior checks.
Packages/PutioCore/Sources/PutioCore/SignedOutPresentation.swift	Adds isHarnessExercise instance convenience for view logic.
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/Contents.json	Adds root asset-catalog metadata for the generated adaptive colors.
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioBackground.colorset/Contents.json	Adds generated adaptive semantic background color (light/dark variants).
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioSurface.colorset/Contents.json	Adds generated adaptive semantic surface color (light/dark variants).
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioTextPrimary.colorset/Contents.json	Adds generated adaptive semantic primary text color (light/dark variants).
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioTextSecondary.colorset/Contents.json	Adds generated adaptive semantic secondary text color (light/dark variants).
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioAccent.colorset/Contents.json	Adds generated semantic accent color.
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioAccentForeground.colorset/Contents.json	Adds generated semantic accent-foreground color.
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioSuccess.colorset/Contents.json	Adds generated semantic success color.
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioSuccessForeground.colorset/Contents.json	Adds generated semantic success-foreground color.
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioDestructive.colorset/Contents.json	Adds generated semantic destructive color.
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioDestructiveForeground.colorset/Contents.json	Adds generated semantic destructive-foreground color.
Packages/PutioCore/Sources/PutioCore/Resources/PutioColors.xcassets/PutioSeparator.colorset/Contents.json	Adds generated semantic separator color (light/dark variants).
Packages/PutioCore/Sources/PutioCore/Generated/PutioTheme+Generated.swift	Replaces ad-hoc dynamic colors with semantic asset-backed colors; adds scalable metric/icon roles.
Packages/PutioCore/Package.swift	Declares Resources for SwiftPM so Bundle.module asset colors work in PutioCore and tests.
docs/HARNESS.md	Documents iOS exercised-state using accessibility Dynamic Type size for proof coverage.
CONTRIBUTING.md	Updates token workflow guidance (coverage audit + generated asset catalogs + drift enforcement).
Apps/watchOS/Sources/PutioWatchApp.swift	Adopts semantic colors and scaled content gap via @PutioScaledMetric.
Apps/tvOS/Sources/PutioTVApp.swift	Adopts semantic colors and renames TV color roles to semantic names.
Apps/iOS/Sources/PutioApp.swift	Adds harness-only accessibility Dynamic Type modifier and adopts scaled metrics + semantic colors/icons.
AGENTS.md	Updates contribution guidance to include generated asset catalogs and token coverage audits.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cubic-dev-ai]

No issues found across 28 files

_{Re-trigger cubic}

[cubic-dev-ai]

1 issue found across 11 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/generate-design-tokens.ts">

<violation number="1" location="scripts/generate-design-tokens.ts:404">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

The PR description claims this change introduces an *adaptive* color catalog and *semantic adaptive colors*, but the generator now produces static dark-only universal colorsets. The old `adaptiveColorRoles` mapped each role to both `light` and `dark` tokens and emitted a `.colorset` with a `luminosity: dark` appearance, while the new `semanticColorRoles` hardcodes a single dark token and `renderAssetCatalog` outputs only one universal color. This means `Color("PutioBackground", bundle: .module)` will resolve to the same dark color regardless of the system color scheme. Please either restore the dual-appearance colorset generation (light + dark) so the catalog is actually adaptive, or update the PR description to accurately reflect that the colors are intentionally static/dark-only.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>