feat(apple): reconcile tier-2 SwiftUI contract - #48
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
🟡 Changes recommended
The new verification adds brittle hard-coded contract metadata checks and the updated “system-owned” navigation chrome guidance is contradicted by remaining Phosphor back chevrons in the iOS preview cards.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Reconciles the Tier‑2 (tokens-only) Apple SwiftUI contract with the system preview cards by clarifying what remains system-owned (SF typography, control tracks, NavigationLink disclosures, etc.) vs what put.io supplies (tint, surfaces, app content typography, icons), and adds a verifier to keep the contract + previews in sync.
Changes:
- Updates Apple platform contract wording (version bump to 0.2.0) to distinguish system-rendered chrome vs app-authored content and to refine control guidance (ProgressView/Gauge tracks, glass usage, NavigationLink disclosure, etc.).
- Adjusts iOS/watchOS/tvOS preview cards + shared
_apple.cssto reflect those contract clarifications (system typography, system-chevron disclosures, progress/gauge preview helpers, action styling). - Extends
pnpm verifydesign-system checks withcheckAppleContract()to assert key invariants across the Apple contract and preview artifacts.
File summaries
| File | Description |
|---|---|
| system/preview/watchos-s00-shell.html | Tightens Tier‑2 watchOS copy around system-owned rendering and app-provided tint/content. |
| system/preview/tvos-s00-shell.html | Clarifies SF vs GT America usage on tvOS (system tab labels vs app content). |
| system/preview/ios-s02-transfers.html | Updates transfers screen guidance to system-owned tracks + gauge sizing and preview helpers. |
| system/preview/ios-s01-files.html | Switches folder disclosure to a system-chevron stand-in; updates empty-state action styling. |
| system/preview/ios-s00-shell.html | Refines Tier‑2 iOS shell copy and spec language for system vs app typography. |
| system/preview/ios-e16-gauge.html | Reworks Gauge element card to encode the five download states and new gauge track guidance. |
| system/preview/ios-e15-emptystate.html | Updates empty-state action to a bordered-style stand-in and adjusts token callouts. |
| system/preview/ios-e12-sheet.html | Updates sheet card token list and clarifies selection/checkmark tint behavior. |
| system/preview/ios-e11-navbar.html | Updates navbar card copy/specs to reflect system-rendered SF titles/back labels and tint. |
| system/preview/ios-e10-tabbar.html | Updates tab bar card copy/specs to reflect SF labels + glyph sizing guidance. |
| system/preview/ios-e09-progress.html | Updates ProgressView card to treat the track as system-owned and tint as fill-only. |
| system/preview/ios-e05-glass-button.html | Clarifies glass-vs-content button style boundaries and prominent glass constraints. |
| system/preview/ios-e03-segmented.html | Adjusts segmented control spec text around label typography ownership. |
| system/preview/ios-e00-list-row.html | Updates list-row card to reflect List+NavigationLink disclosure ownership and “don’t” guidance. |
| system/preview/_apple.css | Introduces system-typography styling for system chrome + adds browser-only progress/gauge preview helpers. |
| scripts/verify-design-system.ts | Adds checkAppleContract() to verify the Apple contract + previews stay consistent. |
| platforms/apple/DESIGN.md | Bumps contract to v0.2.0; expands Tier‑2 guidance around typography ownership, control tracks, and glass constraints. |
Review details
Suppressed comments (1)
system/preview/ios-s01-files.html:108
- This screen still uses a Phosphor caret-left for the back chevron, but the updated Apple tier-2 contract states navigation chrome (including back chevrons/labels) is system-rendered SF. Using a system glyph stand-in here would keep the preview consistent with the contract.
<div class="cuv-a ios-bordered-action">Search All Files</div>
- Files reviewed: 17/17 changed files
- Comments generated: 4
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cffc5987d3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0198afab1c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <div class="el-states rows"> | ||
| <div class="el-state"><div class="demo"><div style="position:relative;width:393px;height:96px;background:var(--app-bg);border-radius:12px;overflow:hidden"> | ||
| <div class="ios-tabfloat" style="bottom:16px"><div class="glass ios-tabbar"><div class="tab on"><i class="ph-fill ph-folder"></i><span>Files</span></div><div class="tab"><i class="ph ph-arrow-circle-down"></i><span>Transfers</span></div><div class="tab"><i class="ph ph-clock-counter-clockwise"></i><span>Activity</span></div><div class="tab"><i class="ph ph-user-circle"></i><span>Account</span></div></div><div class="glass ios-searchcap"><i class="ph-bold ph-magnifying-glass"></i></div></div> | ||
| <div class="ios-tabfloat" style="bottom:16px"><div class="glass ios-tabbar"><div class="tab on"><i class="ph-fill ph-folder"></i><span>Files</span></div><div class="tab"><i class="ph ph-arrow-circle-down"></i><span>Transfers</span></div><div class="tab"><i class="ph ph-clock-counter-clockwise"></i><span>Activity</span></div><div class="tab"><i class="ph ph-user-circle"></i><span>Account</span></div></div><div class="glass ios-searchcap"><span class="system-glyph system-search" aria-hidden="true">🔍︎</span></div></div> |
There was a problem hiding this comment.
In the web-rendered Apple guide, the fresh follow-up replaces the Phosphor search icon with the raw U+1F50D emoji code point (and similarly uses font characters for back, clear, check, and disclosure controls). On Windows and Linux, the -apple-system stack falls through to platform-dependent fonts, so these 1:1 reference cards can display different glyph geometry or emoji rendering instead of Apple-like system chrome. Use deterministic inline SVG stand-ins while retaining the system-* ownership markers.
AGENTS.md reference: AGENTS.md:L46-L46
Useful? React with 👍 / 👎.
| for (const [index, screen] of screens.entries()) { | ||
| const start = screen.index ?? 0; | ||
| const end = screens[index + 1]?.index ?? source.length; | ||
| const prominentCount = (source.slice(start, end).match(/class="(?:gbtn|gcap) prominent"/g) ?? []).length; |
There was a problem hiding this comment.
When a screen adds another class or merely reorders its classes, this regression check stops counting an otherwise valid prominent control because it only recognizes the exact substring class="gbtn prominent" or class="gcap prominent". For example, two controls written as class="glass gbtn prominent" pass verification even though both still match .gbtn.prominent and violate the new one-per-screen contract; parse each opening tag's class list, as the helpers below already do, before counting.
Useful? React with 👍 / 👎.
Summary
Closes #44.
Versions the Apple Tier-2 contract at
0.2.0and reconciles it with stock SwiftUI behavior measured during the putio-ios 3.0.0 conformance round.The token graph and package manifest remain unchanged.
Changed
Gauge(.accessoryCircularCapacity)geometry and system-derived track.ProgressViewandGauge.NavigationLinkthe sole owner of folder disclosure accessories.Verification
pnpm verifypnpm verify:fullfor token, guide, package, or deploy-affecting changes3.1.0.gpt-5.6-sol, high-reasoning Slopguard review: clean with 0 findings.Review Notes
Screenshots or recordings for visual guide changes:
Gauge and five states
iOS and iPadOS shell
Files, disclosure, actions, and empty state
watchOS and tvOS typography evidence
Package, deploy, or release impact: Conventional
featrequests a semantic-release minor. No token payload or dependency delta. Do not hand-editpackage.json.Follow-up work: adopt the first published release containing these rulings in putio-ios #176. The two later tvOS conflicts remain separate rulings and are not changed here.