Docs/refine apple design skills - #3
Conversation
- Fill MIT copyright holder; add SECURITY.md and cut changelog 0.2.0 - Clarify archive boundary and mark Website README as superseded - Ignore .swiftpm/.cursor; set GitHub About outside this commit
- Say preview commands must run from archive/ with --prefix Website
- Document deterministic Maestro app, simulator, state, fixture, artifact, and accessibility contracts.\n- Add active onboarding first-run and permission guidance.\n- Verified with verify-skills, npm validate, and consumer guidance tests.
Close foundation skill gaps from the design-guidance audit without expanding archive docs or promoting host-local skills into the install catalog. - apple-design-system: polish defaults (opaque content, glass restraint, ~44pt targets, avoid thin UI weights) - swiftui-tab-navigation: selective bar tinting, system-materials verification, and a thin liquid-glass-chrome restraint reference - swiftui-component-author: visual craft plus large Dynamic Type layout (scroll by default, primary text growth) and frequency-gated motion defaults (critically damped, touch-down press, source-anchored presentation, no input lock during transitions) - apple-accessibility-review: align Dynamic Type inspection with author policy - apple-platform-planner: name 2026 HIG principles as audit language - competing-macos-skills-plan: route deep motion and glass APIs to host-local skills after foundation restraint rules Verified with ./Scripts/verify-skills.sh.
Keep audit/research dumps under tinyfish-results/ out of version control so skill refinements stay product-focused.
- Always-on feature-screen polish; keyboard/high-frequency never-animate; path symmetry + motion verification - Add design-motion-glass routing reference and wire host-depth rows without catalog promotion - Liquid Glass Don’t: materialize-not-fade and steady-state content/glass separation
![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: f02999aba7
ℹ️ 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".
| | Intent | Foundation first | Then | Host depth only if needed | | ||
| | --- | --- | --- | --- | | ||
| | New app / major skeleton | `$apple-development-foundation` → `$codex-bootstrap` → design-system, tabs, a11y | Chained children | — | | ||
| | Liquid Glass / materials | System chrome + `swiftui-tab-navigation` + `liquid-glass-chrome.md` | Custom `glassEffect` only after restraint | `~/.agents/skills/liquid-glass-design/SKILL.md` | |
There was a problem hiding this comment.
In the supported Codex setup—especially when CODEX_HOME is customized—skills are discovered under ${CODEX_HOME:-$HOME/.codex}/skills, not ~/.agents/skills. These literal pointers therefore send the master router outside the repository's verified host contract and cause the advertised depth handoff to be missed or fail unless a user happens to maintain an unrelated directory. Refer to discovered skill IDs or make the external-host path explicitly host-dependent instead.
AGENTS.md reference: AGENTS.md:L3-L3
Useful? React with 👍 / 👎.
| - Exact simulator/configuration: simulator ID `<EXACT_SIMULATOR_ID>`, scheme | ||
| `<SCHEME>`, and build configuration `<CONFIGURATION>`; use the same | ||
| destination and configuration for XcodeBuildMCP, Maestro MCP, and CLI runs |
There was a problem hiding this comment.
When this canonical template is initialized for a macOS-only app, visionOS/watchOS project, or Swift package that does not use Maestro, the new unconditional section still requires an exact simulator ID, .maestro/ layout, bundle ID, fixtures, and onboarding state. Because the surrounding template instructs users to customize every placeholder, those supported consumer types cannot complete the contract truthfully and may leave agents following an inapplicable iOS destination. Gate this section on Maestro/iOS E2E use or provide an explicit not configured/n/a form.
AGENTS.md reference: AGENTS.md:L15-L16
Useful? React with 👍 / 👎.
- Resolve host-depth skills by ID under the active Codex discovery path instead of hard-coded ~/.agents/skills pointers - Gate the consumer E2E/Maestro section with not configured/n/a for non-iOS and non-Maestro consumers
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1b8279932c
ℹ️ 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".
| | --- | --- | --- | --- | | ||
| | New app / major skeleton | `$apple-development-foundation` → `$codex-bootstrap` → design-system, tabs, a11y | Chained children | — | | ||
| | Liquid Glass / materials | System chrome + `swiftui-tab-navigation` + `liquid-glass-chrome.md` | Custom `glassEffect` only after restraint | Host skill ID `liquid-glass-design` | | ||
| | Animation polish on a screen/component | `swiftui-component-author` craft defaults + a11y Reduce Motion | Delete high-frequency motion first | Host skill ID `apple-design` (gesture physics) | |
There was a problem hiding this comment.
When the request is animation polish on a business-specific or one-off feature screen, this row selects swiftui-component-author, but that skill explicitly rejects those screens in its description and stop conditions. Since apple-design is positioned only as depth after the foundation workflow, routing stops without an applicable workflow; route screen-level polish to a feature-screen workflow or permit the suitable host skill to lead.
AGENTS.md reference: AGENTS.md:L20-L26
Useful? React with 👍 / 👎.
| Optional. Fill this section only when the project uses Maestro (or another UI | ||
| E2E tool) for iOS simulator journeys. For macOS-only apps, visionOS/watchOS |
There was a problem hiding this comment.
For an iOS project using XCUITest, Appium, or another non-Maestro E2E tool, this wording says to fill the section, but the required fields below still prescribe .maestro/, Maestro MCP, and Maestro CLI. Fresh evidence in the updated text is the newly added “or another UI E2E tool” scope while the contract remains Maestro-specific; either limit this section to Maestro or make its fields tool-neutral.
Useful? React with 👍 / 👎.
|
|
||
| All SwiftUI components must support Dynamic Type, VoiceOver, keyboard access, contrast, Reduce Motion, Differentiate Without Color, and a descriptive label for an icon-only control. Validate imports before reading them. Never log credentials, tokens, private content, raw imports, complete sensitive paths, or security-scoped URLs. | ||
|
|
||
| - For any SwiftUI UI (including feature screens, not only shared components): keep content opaque; reserve glass for system navigation chrome; ~44×44 pt targets; system text styles (no Ultralight/Thin for UI); selective accent; frequency-gated motion (no animation on high-frequency or keyboard paths). Defer deep gesture physics to host-local motion skills. |
There was a problem hiding this comment.
For macOS consumer UI, this always-on rule requires every control target to be approximately 44×44 points even though standard pointer-driven macOS controls use substantially denser native sizing. Applying the touch-target minimum across every supported SwiftUI platform will produce oversized desktop controls and conflict with the native-first guidance; qualify it for iOS/touch interaction and retain platform-native sizing on macOS.
AGENTS.md reference: AGENTS.md:L3-L3
Useful? React with 👍 / 👎.
- require risk-based screenshot and hierarchy evidence for UI changes\n- provide reusable consumer guidance for deterministic inspection
- make system navigation chrome the default interpretation of Liquid Glass\n- propagate opaque content and restrained custom-glass rules across foundation skills and workflows\n- verify the skill catalog and static docs build
- allow Maestro, XCUITest, Appium, or another configured UI E2E runner\n- make all E2E fields n/a when the consumer has no UI E2E\n- keep the public AGENTS template mirror synchronized
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 77aafb24ea
ℹ️ 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".
| - E2E-only launch arguments/environment beyond the UI inspection contract: | ||
| `<LAUNCH_ARGUMENTS_OR_N_A>` and `<ENVIRONMENT_VARIABLES_OR_CONFIG_SOURCE_OR_N_A>`; | ||
| inject secrets locally or in CI rather than committing them |
There was a problem hiding this comment.
When an iOS/iPadOS consumer copies this website template, the new E2E fields refer to the “UI inspection contract,” but that entire section is present only in the canonical asset and omitted from this purported mirror. The updated bootstrap and verification workflows require its deterministic routes, evidence matrix, and artifact location, so consumers following the website cannot configure the required UI evidence and receive dangling references instead.
Useful? React with 👍 / 👎.
| | Destinations | exact `simulatorId`; macOS arch or `n/a` | | ||
| | Formatter / linter / checks | repo-native commands or `not configured` | | ||
| | Targeted and full tests | repo-native or MCP test scope | | ||
| | E2E / Maestro contract | `configured` with real values, or `not configured` / `n/a` for non-iOS or non-Maestro repos | |
There was a problem hiding this comment.
For a consumer using XCUITest, Appium, or another non-Maestro runner, this new summary row recommends not configured/n/a, even though the contract below explicitly supports those tools. Following the customization table therefore suppresses a legitimate E2E setup and can make agents skip its journeys. The fresh evidence is this newly added website summary row; the canonical asset has since become tool-neutral.
Useful? React with 👍 / 👎.
- include the UI inspection contract in the website copy-paste template\n- describe configured UI E2E tools without classifying non-Maestro runners as unconfigured
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8a755e5d24
ℹ️ 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".
|
|
||
| Patterns for **device → many independent HTTP APIs** apps (home-lab dashboards, ops clients, multi-vendor read-only mesh). Neutral and reusable: no product branding, no private hosts, no secrets. | ||
|
|
||
| **Provenance:** distilled from Harborlight-style Phase 2–3 work (Sonarr / Radarr / Plex / qBittorrent-class peers). Apply in the **consumer workspace**, not this foundation’s `archive/`. |
There was a problem hiding this comment.
This live agent playbook is linked from the generic task recipes but names Harborlight and specific consumer products despite describing itself as neutral; agents and downstream consumers will inherit product-specific provenance and assumptions that belong in the consumer app’s documentation. Remove the brand/vendor references and express the examples in domain-neutral terms.
AGENTS.md reference: AGENTS.md:L12-L12
Useful? React with 👍 / 👎.
| For a user-visible iOS/iPadOS change, use the consumer's UI inspection contract | ||
| after a launch smoke. Choose the smallest risk-based evidence matrix: the primary | ||
| affected route by default, plus an affected sheet, appearance variant, or large | ||
| Dynamic Type scenario only when that risk changed. For each selected scenario, | ||
| capture a screenshot, visually inspect the rendered image, and capture | ||
| `snapshot_ui` to verify semantic controls, labels, values, and scrollability. |
There was a problem hiding this comment.
This makes screenshot inspection plus snapshot_ui mandatory for user-visible iOS/iPadOS verification, while Evaluations/skill-routing.json remains unchanged and has no user-visible UI or non-UI exemption case. Consequently, the repository’s behavioral verifier still passes even if an agent skips this new contract or applies it to non-UI work; add matching positive and boundary fixtures when changing this verification behavior.
AGENTS.md reference: AGENTS.md:L16-L16
Useful? React with 👍 / 👎.
- remove consumer and vendor-specific assumptions from the multi-service workflow\n- add UI-positive and non-UI verification fixtures with enforced boundary coverage\n- update evaluation documentation for the expanded framework boundaries
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 57e7746393
ℹ️ 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".
- enforce UI and non-UI verification evidence boundaries\n- harden neutral multi-service security guidance\n- keep the website AGENTS template synchronized
- neutralize the multi-service playbook and harden reusable security guidance\n- make UI E2E contracts tool-neutral and keep website copy synchronized\n- enforce positive and boundary UI verification evidence in fixtures
- Drop-in DotMatrixLoader + FeatureLoadingView template - Design rationale and integration checklist - Task recipe for full-surface liquid orb loading
- Update README: presets, InlineLoadingRow, ScrollView layout, anti-box checklist - Refresh drop-in Swift from current Harborlight implementation - Expand task recipe for full-surface and inline loading patterns
- Micro economy path and tile-safe sizing in drop-in Swift - Document per-surface loading copy and ScrollView rule for Services/release sheets - Task recipe: micro cost + screen-specific detail
- Add landing-page-recipe.md to apple-app-marketing-site: homepage anatomy (screens, benefits, social proof, pricing, FAQ), honesty conventions, real-screenshot capture via XcodeBuildMCP + Maestro, and the mandatory link/form/width verification pass - Update structure-and-pages.md homepage sections and SKILL.md implementation order to the proven anatomy - Add LANDING_RECIPE.md to the AppMarketingSite template pack; update README table, STRUCTURE composition, and CHECKLIST items Verification: ./Scripts/verify-skills.sh (16 skills, 77 fixtures) and generate-skill-catalog.py --check both pass.
…idths - Document the actual capture height (640x1391) instead of 1392 - State the mobile overflow check consistently as 320px and 390px across the skill reference and the template pack Verification: ./Scripts/verify-skills.sh passes (16 skills, 77 fixtures).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 66160eabd6
ℹ️ 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".
| raise EvaluationError(f"{location}.{field} must be a string array") | ||
| if len(actions) != len(set(actions)): | ||
| raise EvaluationError(f"{location}.{field} must be a unique array") | ||
| if not all(action in UI_EVIDENCE_ACTIONS for action in actions): |
There was a problem hiding this comment.
For a fixture that puts focused-code-tests in ui_evidence.forbidden_actions, this check accepts it because it validates forbidden actions against the full action set, while Evaluations/schema.json deliberately omits that value from the forbidden_actions enum. Since verify-skills.sh relies on this validator as the dependency-free schema contract, a schema-invalid fixture can still pass verification; validate forbidden actions against UI_EVIDENCE_FORBIDDEN_ACTIONS instead.
Useful? React with 👍 / 👎.
| The proven homepage pattern from **Group Trip Money** (`GroupTripMoney/web/`). | ||
| Everything is data-driven: structure, tokens, and workflow stay identical | ||
| across products; only frontmatter content changes. Read the example repo | ||
| before building; keep this reference as the spec. |
There was a problem hiding this comment.
When this skill is installed in a consumer repo that does not also have a GroupTripMoney/web checkout, the recipe makes a branded external app the source of truth and requires reading it before building. That leaves agents blocked or copying product-specific assumptions instead of following a reusable skill spec; make the recipe self-contained and keep any example optional and neutral.
AGENTS.md reference: AGENTS.md:L12-L12
Useful? React with 👍 / 👎.
| | Poster tiles | `DotMatrixLoader.micro` (economy path) | | ||
| | Poster progress banner | `InlineLoadingRow(..., micro: true)` | | ||
| | Add media search / defaults | `InlineLoadingRow` in form sections | | ||
| | Detail: episodes / *arr submit / qBit check | `InlineLoadingRow` | |
There was a problem hiding this comment.
When this template is copied into another consumer app, the wiring table carries Harborlight-specific media-stack terms such as *arr and qBit as the recommended integration surface. That leaks one consumer domain into a reusable template and can steer adopters toward app-specific loading copy and states; replace these with neutral surface categories.
AGENTS.md reference: AGENTS.md:L12-L12
Useful? React with 👍 / 👎.
- validate ui_evidence.forbidden_actions against the schema enum so a schema-invalid fixture cannot pass verification - keep the homepage recipe self-contained; GroupTripMoney example is optional and illustrative only, never the source of truth - replace Harborlight-specific wiring surfaces (media search, *arr, qBit) with neutral surface categories in the LiquidOrbLoader template - carry the same neutralization into structure-and-pages and the consumer LANDING_RECIPE template
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7786a22a18
ℹ️ 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".
| Fixture mode first: launch the app with its fixture launch argument (e.g. | ||
| `-useFixtureData` seeding an in-memory container) via XcodeBuildMCP | ||
| (`build_run_sim` with `launchArgs`). Then drive navigation with a throwaway | ||
| Maestro flow in `/tmp` — never the repo's committed `.maestro/` suite: |
There was a problem hiding this comment.
This recipe is mandatory for the marketing-site skill, which is advertised for iOS or macOS apps, but the real-screenshot path only tells agents to launch with build_run_sim and drive an iOS Maestro flow. For a macOS app landing page, following this blocks screenshot capture or produces the wrong app evidence instead of using build_run_macos/macOS screenshots or a platform-neutral branch; split this section by platform before making it required.
AGENTS.md reference: AGENTS.md:L3-L3
Useful? React with 👍 / 👎.
| | Verify | No rectangular glow box; light/dark; ring/orb clearance; Reduce Motion freeze; loader not collapsed in scroll | | ||
| | Do not | Keyboard chrome; private hostnames in detail; expand foundation `archive/Sources/` for this drop-in | | ||
|
|
||
| Proven consumer: Harborlight Home/Library/Calendar/Downloads/Services + forms/details/posters. Full notes: `Templates/LiquidOrbLoader/README.md`. |
There was a problem hiding this comment.
Fresh evidence here is this newly added task recipe: for consumers using the foundation docs, naming Harborlight and its Home/Library/Calendar/Downloads/Services surfaces makes the reusable loader guidance carry a specific product’s screen model, so agents can copy those assumptions into unrelated apps instead of neutral loading surfaces. Replace it with generic surface examples or make the provenance non-authoritative outside the recipe.
AGENTS.md reference: AGENTS.md:L12-L12
Useful? React with 👍 / 👎.
1 participant
No description provided.