Docs/refine apple design skills

.agents/skills/README.md

@@ -12,6 +12,7 @@ These source-controlled skills are intentionally general Apple-development workf
 | swiftui-tab-navigation | native app-level SwiftUI tabs and system Liquid Glass tab chrome | page-style tabs, segmented controls, or business-specific screens |
 | swiftui-component-author | reusable SwiftUI components | app-specific screen copy |
 | apple-design-system | design-system changes | application branding |
+| apple-error-states | error-state UX and error handling | error propagation without UI, token-only work |
 | apple-app-marketing-site | Apple app marketing sites (Astro + Tailwind): scaffold, polish, retheme, deploy | SwiftUI app UI, App Store screenshots, or general non-marketing web apps |
 | ios-macos-platform-adaptation | divergent platform behavior | shared identical behavior |
 | swift-package-module-author | a reusable package target in the active workspace | an app-local feature or archived package work in this repository |

.agents/skills/apple-accessibility-review/SKILL.md

@@ -12,7 +12,7 @@ Review **reusable SwiftUI** in the **consumer workspace** for accessibility and
 Work top-down through the component or shared UI under review:
 
 1. **VoiceOver** — meaningful labels, traits, values, hints only when needed; correct grouping/combine; decorative images hidden; custom controls expose actions.
-2. **Dynamic Type** — layouts reflow; no truncated essential text at large sizes; avoid fixed heights that clip content.
+2. **Dynamic Type** — layouts reflow; scroll by default; primary text grows first; no truncated essential text at large sizes; avoid fixed heights that clip content.
 3. **Focus and keyboard** — logical order on platforms with keyboard/focus (especially macOS); no keyboard traps; actionable elements reachable.
 4. **Touch and hit targets** — controls remain usable; spacing does not rely on tiny hit areas alone.
 5. **Color and contrast** — text and essential icons remain readable; Increased Contrast considered when the project supports it.

.agents/skills/apple-app-marketing-site/SKILL.md

@@ -76,14 +76,15 @@ Full token tables, component inventory, and page patterns:
 
 - [references/retheme-guide.md](references/retheme-guide.md)
 - [references/structure-and-pages.md](references/structure-and-pages.md)
+- [references/landing-page-recipe.md](references/landing-page-recipe.md) — proven homepage anatomy (screens, benefits, social proof, pricing, FAQ), real-screenshot capture, and the mandatory link/form/width verification pass
 
-Human-facing template pack (copy into consumer projects): repository path `Templates/AppMarketingSite/` (`README.md`, `RETHEME.md`, `STRUCTURE.md`, `CHECKLIST.md`, `TOKEN_REFERENCE.css`).
+Human-facing template pack (copy into consumer projects): repository path `Templates/AppMarketingSite/` (`README.md`, `RETHEME.md`, `STRUCTURE.md`, `CHECKLIST.md`, `LANDING_RECIPE.md`, `TOKEN_REFERENCE.css`).
 
 ## Implementation order
 
 1. Scaffold Astro + Tailwind in `web/`; configure `site` + trailing slashes.
 2. Tokens + `BaseLayout` / `Header` / `Footer` (static).
-3. Homepage (hero, mockup, trust, story, feature, privacy band).
+3. Homepage (hero, trust, screenshot gallery, benefits, clarity visual, social proof, pricing, FAQ, final CTA band — anatomy in `references/landing-page-recipe.md`).
 4. Secondary pages with shared `PageIntro` + `LegalProse`.
 5. Minimal islands only where needed.
 6. `npm run build`; responsive pass; Vercel config.
@@ -94,7 +95,7 @@ Human-facing template pack (copy into consumer projects): repository path `Templ
 cd web && npm run build
 ```
 
-Confirm routes emit under `dist/` with trailing-slash directories, header/footer present **without** client JS, and no third-party script tags. Optional: `npm run preview` and check mobile hero + mockup.
+Confirm routes emit under `dist/` with trailing-slash directories, header/footer present **without** client JS, and no third-party script tags. Then run the full verification pass (every link, forms, desktop + mobile widths, a11y spot-checks) described in `references/landing-page-recipe.md`.
 
 ## Reference implementation
 

.agents/skills/apple-app-marketing-site/references/landing-page-recipe.md

@@ -0,0 +1,131 @@
+# Homepage recipe — anatomy, real screenshots, verification
+
+This reference is the complete homepage spec — self-contained, with no
+external checkout required before building. Structure, tokens, and workflow
+stay identical across products; only frontmatter content changes. A consumer
+example may exist at `GroupTripMoney/web/` where that checkout is available;
+it is optional and illustrative only, never the source of truth.
+
+## Homepage anatomy (section order)
+
+All copy lives in frontmatter `as const` arrays at the top of
+`src/pages/index.astro` (`screens`, `benefits`, `testimonialPlaceholders`,
+`pricingPoints`, `faqs`) so the next product swap only edits data.
+
+1. **Hero** — eyebrow, `h1.display-title` (two short lines), `.lede`, CTA
+   trio, CSS device mockup right.
+   CTA trio: status pill (`span.btn.btn-coming-soon`, `role="status"`,
+   `aria-describedby` → microcopy note), `a.btn.btn-secondary[href="#screens"]`
+   "See it in action", text link to `/help/`.
+2. **Trust strip** — thin divider + centered row of three privacy/product
+   promises that match the app's real behavior.
+3. **Screenshot gallery** (`id="screens"`) — exactly 4 real captures, one
+   per main app screen. Mobile: horizontal
+   `snap-x snap-mandatory` scroll, `w-[72vw] max-w-[16.5rem]` cards; `sm+`:
+   `grid sm:grid-cols-2 lg:grid-cols-4`. Each item: `figure` → rounded frame
+   (`rounded-[1.4rem] ring-1 ring-black/10 shadow-soft`) → `img`
+   (`width="640" height="1391"`, `loading="lazy"`, descriptive `alt`) →
+   `figcaption` (bold title + muted caption). Never CSS illustrations here —
+   only captures of the real app.
+4. **Benefits** — full-bleed `#efeff1` band, `ul.grid sm:grid-cols-2
+   lg:grid-cols-3` of 6 cards (`rounded-[1.25rem] border border-line
+   bg-surface p-6 shadow-soft`) with uppercase kicker, `h3`, muted body.
+   One benefit per real capability.
+5. **Clarity / product visual** — two-column grid; calm diagram card
+   (flat cards, `shadow-soft`, no stickers/gradients) + copy + short bullet
+   list with 5px ink dot markers.
+6. **Social proof placeholders** — full-bleed band, `md:grid-cols-3` quote
+   cards: `blockquote` in curly quotes + `footer` with 36px initials avatar
+   (soft pastel bg), name, context line. Pre-launch: array is
+   `testimonialPlaceholders` with a `// PLACEHOLDER` comment — never present
+   invented people as real customers.
+7. **Pricing** — centered; one card (`max-w-md`, `rounded-[1.5rem]`,
+   `p-8 md:p-10`) with app name + "Free" (or real price), border-t bullet
+   list with ink dots, full-width coming-soon status pill, microcopy. Only
+   state pricing facts the product really has.
+8. **FAQ** — `max-w-3xl border-t border-line` list of 5 native
+   `details.faq-item` rows (`border-b border-line`, `+`/`−` circle
+   indicators), plus a muted line linking `/help/`. Answers describe the
+   app's real behavior (accounts? money movement? storage? launch timing).
+9. **Final CTA / privacy band** — dark `bg-night rounded-[1.5rem]` panel:
+   eyebrow + `h2` (product promise), body combining privacy posture + launch
+   status (`#a1a1a6`), right column with `a.btn.btn-on-dark`
+   → `#screens` and underline link → `/privacy/`.
+
+Section rhythm: page canvas (`#f5f5f7`) alternating with full-bleed
+`#efeff1` bands; `py-24 md:py-32` section padding; `site-shell`
+(`min(1120px, calc(100% - 2.5rem))`).
+
+## Honesty conventions
+
+- Pre-launch CTAs are **status controls**, not fake buttons: `role="status"`
+  + `aria-describedby` + microcopy ("The App Store listing is not available
+  yet."). No dead App Store links.
+- Social proof is placeholder data until real users exist, marked in code.
+- Every claim traces to something the app actually does — read the app
+  source first; never invent features, pricing, or privacy posture.
+
+## Capturing real screenshots
+
+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:
+
+- Do **not** include `launchApp` in the flow: Maestro restarts the app and
+  its `arguments:` map does not reproduce `-useFixtureData` on iOS, so the
+  app relaunches without fixtures. Drive the already-running app.
+- `assertVisible` only text guaranteed on screen (below-fold assertions
+  fail); scroll first (`swipe: {direction: UP}`) for below-fold shots.
+- Tap rows/buttons by text; tap tab bars by percentage points across the
+  bar at ~94% height (e.g. 17% / 50% / 83% for a three-tab bar). Toolbar
+  buttons exist only on the screen that owns them — inspect the current
+  screen before tapping.
+- Maestro terminates the app between runs: one flow covering every screen,
+  or relaunch with fixtures before each flow.
+- Assert distinctive text on every screen before screenshotting; names on
+  `takeScreenshot` map to content.
+
+Downscale to 640px wide into `web/public/screenshots/`:
+`sips --resampleWidth 640 shot.png --out web/public/screenshots/name.png`
+(optionally `xcrun simctl io booted screenshot /tmp/x.png` for full-res).
+Delete unused captures; register each in the `screens` array.
+
+## Verification pass (mandatory)
+
+1. `cd web && npm run build` — all routes emit, no errors.
+2. `npm run preview -- --port 4321`; every route and asset returns 200
+   (`/`, `/help/`, `/support/`, `/privacy/`, `/terms/`, screenshots, favicon).
+3. Browser automation (agent-browser CLI or equivalent): desktop 1440×900 —
+   no console/page errors; no horizontal overflow
+   (`document.documentElement.scrollWidth <= innerWidth`); **every link**
+   clicked (scroll the element into view first — below-fold clicks miss),
+   URLs/hashes confirmed; support form: empty submit shows per-field errors
+   and focuses the first invalid field, valid submit reveals the toast and a
+   correctly built `mailto:` href; help search filters with result count and
+   empty state; FAQ `<details>` toggles; skip link (Tab → Enter → `#main`);
+   `img` naturalWidth > 0 with non-empty `alt`; heading order h1→h2→h3
+   without jumps; `role="status"` pills present.
+4. Mobile 390×844 (plus the 320px minimum width): overflow still false
+   (gallery scrolls internally); menu
+   toggle sets `aria-expanded` and a nav link closes it.
+5. Full-page screenshots at both widths; if the model cannot view images,
+   pixel-sample the PNGs (canvas `#f5f5f7`, bands `#efeff1`, night
+   `#1d1d1f`, white cards) to confirm sections render.
+6. Re-sweep all routes for console errors; commit only intended files
+   (revert incidental lockfile churn).
+
+Regenerate screenshots whenever the app UI changes — stale captures are
+worse than none.
+
+## Per-project swap table
+
+| What changes | Where |
+| --- | --- |
+| Product name, domain, support email | `astro.config.mjs`, `BaseLayout` meta, `Header`/`Footer`, `SupportForm` address |
+| Screenshots | recapture from THIS app |
+| Reviews / social proof | `testimonialPlaceholders` array |
+| Hero, benefits, FAQ, pricing copy | frontmatter arrays on `index.astro` |
+| Privacy / trust claims | `TrustStrip`, final band — match real posture |
+| Phone mockup content | `PhoneMockup.astro` (illustrative) |
+| Favicon / brand mark | `public/favicon.*`, `BrandMark.astro` |

.agents/skills/apple-app-marketing-site/references/structure-and-pages.md

@@ -47,13 +47,19 @@ export default defineConfig({
 
 ## Homepage sections (order)
 
-1. **Hero** — eyebrow, display title, lede, coming-soon (or App Store) CTA, secondary text link, device mockup
+1. **Hero** — eyebrow, display title, lede, CTA trio (coming-soon status pill, "See it in action" → `#screens`, help link), device mockup
 2. **Trust strip** — three short privacy / product promises
-3. **Story / journey** — three numbered beats (before / during / after)
-4. **Clarity / feature** — diagram or simple visual + bullets
-5. **Privacy band** — inverted night panel + link to privacy policy
-
-Keep copy product-specific; keep rhythm and component reuse.
+3. **Screenshot gallery** — 4 real app captures, one per main screen; snap-scroll on mobile, 4-col grid on desktop
+4. **Benefits** — six cards, one per real capability
+5. **Clarity / feature** — diagram or simple visual + bullets
+6. **Social proof** — quote cards; placeholder data until real users exist
+7. **Pricing** — single centered card; only real pricing facts
+8. **FAQ** — native `<details>` rows + help link
+9. **Final CTA / privacy band** — inverted night panel, privacy link, `#screens` CTA
+
+All copy lives in frontmatter `as const` arrays (screens, benefits,
+testimonialPlaceholders, pricingPoints, faqs); keep structure and rhythm,
+swap only product data. Full spec: `references/landing-page-recipe.md`.
 
 ## Secondary pages
 

.agents/skills/apple-design-system/SKILL.md

@@ -13,10 +13,11 @@ Change **shared** semantic tokens or design-system components in the **consumer
 2. **Semantic tokens before chrome.** Prefer roles (`background`, `label`, `accent`, `danger`, spacing scale, type styles) over raw hex or one-off sizes. Map tokens to light/dark (and increased contrast when the project supports it).
 3. **Native first.** Prefer system materials, typography, and controls. Custom tokens should wrap or complement platform defaults, not fight them.
 4. **Appearance and motion.** New visual tokens must remain readable in light and dark appearance. Prefer Reduce Motion–safe defaults; avoid decorative motion that is the only affordance of meaning.
-5. **Differentiate without color alone.** Status and state must not rely only on hue when color is the sole signal.
-6. **Layering.** Tokens feed shared components; app screens consume components/tokens. Do not hardcode magic numbers for shared UI when a token should exist.
-7. **Document usage.** Name tokens for role, not for a single marketing campaign or temporary experiment. Note deprecations when replacing tokens.
-8. **Verify.** Add or update focused tests/examples or a gallery surface when the project has one. Build the affected target. Accessibility audits of screens belong to `apple-accessibility-review`, not this skill alone.
+5. **Polish defaults.** Content layer stays solid/opaque; reserve Liquid Glass for system navigation/control chrome (not content lists, cards, or tables). A Liquid Glass request means adopting native `TabView`, navigation bars, toolbars, and sheets before considering custom effects; never rebuild that chrome with materials, overlays, or safe-area bars. Use brand/accent for primary actions and content highlights, not full custom chrome. Shared interactive targets must remain usable at ~44×44 pt. Prefer system text styles and Regular/Medium/Semibold/Bold; avoid Ultralight/Thin for UI copy.
+6. **Differentiate without color alone.** Status and state must not rely only on hue when color is the sole signal.
+7. **Layering.** Tokens feed shared components; app screens consume components/tokens. Do not hardcode magic numbers for shared UI when a token should exist.
+8. **Document usage.** Name tokens for role, not for a single marketing campaign or temporary experiment. Note deprecations when replacing tokens.
+9. **Verify.** Add or update focused tests/examples or a gallery surface when the project has one. Build the affected target. Accessibility audits of screens belong to `apple-accessibility-review`, not this skill alone.
 
 ## Stop conditions
 

.agents/skills/apple-development-foundation/SKILL.md

@@ -11,6 +11,11 @@ or comparison is explicitly requested.
 
 ## Procedure
 
+Read [skill sync](../../../docs/reference/skill-sync.mdx) before trusting this
+repository's installed skills for any routing decision. In an autonomous session
+with no human present, first reconcile installed skills against HEAD with
+`./Scripts/install-skills.sh --status` and re-sync before routing on divergence.
+
 1. Read [master-skill.json](master-skill.json) as the machine-readable catalog.
 2. Use its IDs, roles, and purposes to shortlist only the children relevant to
    the request. Do not scan the repository, audit inventories, install skills,
@@ -39,3 +44,6 @@ override their exclusions, install global files, or claim automatic activation.
 For host-local skills that compete with this catalog (generic macOS development
 guides, design-only skills, and similar), see
 [references/competing-macos-skills-plan.md](references/competing-macos-skills-plan.md).
+For Liquid Glass, animation polish, and motion-audit routing (foundation first,
+host depth only if needed), see
+[references/design-motion-glass-routing.md](references/design-motion-glass-routing.md).

.agents/skills/apple-development-foundation/master-skill.json

@@ -61,6 +61,12 @@
       "role": "ui-foundation",
       "purpose": "Add or change reusable semantic design-system tokens and components"
     },
+    {
+      "id": "apple-error-states",
+      "path": ".agents/skills/apple-error-states/SKILL.md",
+      "role": "ui-foundation",
+      "purpose": "Design, implement, or review user-facing error handling and error states"
+    },
     {
       "id": "apple-app-marketing-site",
       "path": ".agents/skills/apple-app-marketing-site/SKILL.md",

.agents/skills/apple-development-foundation/references/competing-macos-skills-plan.md

@@ -19,8 +19,20 @@ catalog’s bootstrap → design-system → verification chain.
 | Feature planning (no implement) | `$apple-development-foundation` → `$apple-platform-planner` | Review skills only if asked |
 | Ordinary feature/component in an existing consumer app | Child skill directly (`swiftui-component-author`, …) | `$swift-testing-verification` |
 | Pure HIG / visual critique with no foundation workflow | External design skill is fine | Do not invent bootstrap |
+| Gesture polish / fluid motion depth | Foundation first (native chrome, a11y, craft defaults) | Host-local `apple-design` only if still needed |
+| iOS 26 Liquid Glass **API** patterns | Foundation “system chrome first” (`swiftui-tab-navigation` + `liquid-glass-chrome`) | Host-local `liquid-glass-design` only after restraint rules |
+| “What should animate?” / opportunity map | Foundation craft first (`swiftui-component-author` frequency gate) | Host-local `find-animation-opportunities` |
+| Audit / improve motion across the app | Foundation craft + a11y baselines | Host-local `improve-animations` (read-only plans) |
 | Foundation skill inventory / installer audit | `$apple-development-foundation` (audit path) | Foundation verify scripts only |
 
+Host-local skills such as `apple-design`, `liquid-glass-design`,
+`find-animation-opportunities`, `improve-animations`, and
+`animation-vocabulary` are **not** in this catalog and are not installed by
+`./Scripts/install-skills.sh` unless later promoted.
+
+Procedure detail (Liquid Glass steps, animation delete-first refactor, host
+skill IDs and discovery): [design-motion-glass-routing.md](design-motion-glass-routing.md).
+
 ## Description / discovery levers (done or next)
 
 1. **Done in this change:** Strengthen the master skill `description` so bootstrap