feat: sync cheers-design with impeccable 4.5.0

NOTICE.md

@@ -9,7 +9,7 @@ Package-local notices and license texts are kept next to the code or skill mater
 `skills/cheers-design` adapts material from Impeccable.
 
 - Original work: <https://github.com/pbakaus/impeccable>
-- Upstream sync/base: `f636bd065a11234bfc7f1b0e0cd9d1ba7a0eb209`
+- Upstream sync/base: `508d7e8955de3b3caf2d8676e85206723d41a887`
 - Copyright: 2025-2026 Paul Bakaus
 - License: Apache License 2.0
 - Local notice: [`skills/cheers-design/NOTICE.md`](skills/cheers-design/NOTICE.md)

skills/cheers-design/NOTICE.md

@@ -6,9 +6,10 @@ This skill adapts material from Impeccable.
 - Copyright: 2025-2026 Paul Bakaus
 - License: Apache License 2.0
 - License text: [`LICENSES/impeccable-Apache-2.0.txt`](LICENSES/impeccable-Apache-2.0.txt)
-- Changes: adapted the design-skill guidance for Cheers/Rust/Datastar, added a clear boundary with the main `cheers` implementation skill, kept only design-level interaction guardrails such as backend-confirmed state and no optimistic UI, migrated setup language to `init`, added critique snapshot persistence under `.cheers-design/critique/`, and adopted Google Stitch-style `DESIGN.md` frontmatter guidance.
+- Upstream sync/base: `508d7e8955de3b3caf2d8676e85206723d41a887`
+- Changes: adapted the design-skill guidance for Cheers/Rust/Datastar, added a clear boundary with the main `cheers` implementation skill, kept only design-level interaction guardrails such as backend-confirmed state and no optimistic UI, migrated setup language to `init`, added critique snapshot persistence under `.cheers-design/critique/`, and adopted Google Stitch-style `DESIGN.md` frontmatter guidance. The new-work flow, visitor modes, craft floor, and finish review are reworked to run without the upstream `impeccable` binary: direction rounds are run by hand instead of the concept-seed roll and decision page, surface briefs live under `.cheers-design/surfaces/`, the finish reviewer is a generic subagent prompt, and the `impeccable detect` scan is optional. Live mode, variant generation, image comps, hooks, doctor, and native iOS/Android guidance are not included.
 
-Upstream Impeccable `NOTICE.md` attribution is reproduced below:
+Upstream Impeccable `NOTICE.md` attribution, as published at upstream commit `f636bd065a11234bfc7f1b0e0cd9d1ba7a0eb209` (the previous sync base), is reproduced below. The current upstream `NOTICE.md` only attributes the iOS and Android platform references, which this skill does not include.
 
 ```text
 # Notice

skills/cheers-design/reference/adapt.md

@@ -1,58 +1,93 @@
 # Adapt
 
-Adapt an existing Cheers design to another viewport, device, input method, or usage context. Adaptation is not scaling pixels; it is rethinking structure for the new context.
+Adapt an existing Cheers design to another viewport, device, input method, or usage context. Adaptation is not scaling pixels; it rethinks structure and interaction for the new context. Ask for target devices and usage context when the request and product docs do not name them.
 
-## Discover
+## Visitor mode
 
-Identify:
+- **Persuade + Experience:** each context may get its own composition when the world earns it. A phone first viewport is a composition of its own, not a squeezed desktop, and still makes the offer intelligible with the primary action in reach.
+- **Operate + Read:** the same information architecture, terms, and navigation model in every context. Structure collapses, reflows, and discloses; it never reorganizes into something the user must relearn.
 
-- source context and assumptions: screen size, input, density, connection, user posture
-- target context: phone, tablet, desktop, kiosk, print, embedded panel, slow network
-- what must remain available
-- what can move behind progressive disclosure
-- what interaction patterns break: hover-only controls, tiny targets, wide tables, dense sidebars
+Refinement preserves: keep the visual world, copy, behavior, and everything outside the adapted contexts. Identity replacement belongs to [new-work.md](new-work.md).
 
-Ask for target devices and usage context if missing.
+## Two isolated assessments
 
-## Adaptation strategy
+When a subagent tool is available and permitted, run these independently; otherwise run them yourself in this order.
+
+1. **Adaptation assessment.** Inspect the target in its source context and each target context. Answer each question with rendered or source evidence:
+   - **Source assumptions:** What was it designed for: screen size, pointer, hover, keyboard, connection, posture, glance or focus? What works well there and must survive?
+   - **Target context:** Phone, tablet, desktop wide, kiosk, print, email, embedded panel, slow network? Portrait and landscape? Touch, mouse, keyboard, or several at once?
+   - **Fit:** What will not fit: wide tables, dense sidebars, multi-column forms, long navigation? What can move behind progressive disclosure without hiding core functionality?
+   - **Input:** What depends on hover, precise pointing, right-click, drag, or keyboard shortcuts? Which targets are too small or too close?
+   - **Gestures:** Which custom controls (sliders, drag surfaces, carousels, swipe rows, scrollable control strips) exist, and does each have a non-gesture path?
+   - **Regions:** Do backend-refreshed regions keep one stable home across breakpoints, or does a duplicated mobile tree leave a patch updating only one copy?
+2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) with `--scope layout`, once at desktop width and once with `--viewport 390x844`, or check by hand when it is unavailable. Also look for fixed widths, horizontal overflow, and `user-scalable=no` the scan may miss.
+
+Keep scan results out of the first assessment, then synthesize both before editing. A clean scan says nothing about whether a gesture works.
+
+## Set the adaptation plan
+
+Before editing, state for each target context: what leads, what moves behind disclosure, what changes interaction model, where the content (not a device list) forces each breakpoint, and which regions reflow, collapse, or stay fixed. State the interaction contract for any control whose input model changes.
+
+## Apply
+
+Read [craft-floor.md](craft-floor.md) before editing. Implement through `cheers`.
 
 ### Mobile
 
-- Stack content into one clear flow.
-- Keep primary actions reachable and large enough.
-- Avoid hover-dependent interactions.
-- Replace wide tables with summary rows, detail pages, or horizontally scrollable tables only when acceptable.
-- Use normal navigation and links for page movement.
-- Keep forms short; split only when it reduces cognitive load.
+- One clear flow: single column, full-width components, primary content first, secondary content in disclosure.
+- Primary actions within thumb reach; the bottom of the screen is easier to reach than the top.
+- Navigation collapses to a drawer, disclosure, or a short bar; keep a way back and a sense of place.
+- Wide tables become summary rows with detail pages, stacked label-value cards, or a horizontally scrollable table with a visible affordance, chosen by what the user compares.
+- Forms stay short; split only when it reduces cognitive load. Body and input text at least 16px, or iOS Safari zooms focused inputs and breaks the layout.
 
 ### Tablet
 
-- Use master-detail or two-column patterns when useful.
-- Support touch and pointer.
-- Let side panels collapse based on orientation or container size.
+- Two columns, master-detail, or a collapsible side panel, adapting to orientation or container size.
+- Support touch and pointer together; touch-size targets with denser layout than a phone.
 
-### Desktop and wide screens
+### Desktop and wide
 
-- Use horizontal space for persistent navigation, side panels, filters, and data comparison.
-- Avoid stretching prose or forms across the whole viewport.
-- Add keyboard affordances for power workflows where appropriate.
+- Use horizontal space for persistent navigation, filters, side panels, and comparison.
+- Cap prose and forms with a max width; never stretch to the viewport.
+- Add hover detail, keyboard shortcuts, multi-select, and drag where they speed power workflows, each with a non-hover, non-drag path. Desktops have touchscreens too.
 
-### Print or static export
+### Print and email
 
-- Hide interactive controls and navigation.
-- Expand hidden details that matter.
-- Preserve semantic heading order.
-- Use print-specific CSS rather than a separate data model when possible.
+- **Print:** hide navigation and interactive controls, expand disclosed content that matters, show full URLs, break pages at logical points, keep heading order, and use print CSS rather than a separate data model.
+- **Email:** about 600px, single column, inline styles, table layout for client compatibility, large obvious buttons, no hover, deep links back to the app for anything interactive.
 
-## Cheers fit
+### Touch and input
 
-- Prefer CSS media/container queries and semantic markup over duplicate component trees.
-- If structure truly differs, compose smaller reusable UI pieces.
-- Keep conceptual update regions stable across breakpoints.
-- Use local affordances for disclosure, not to remove core functionality from a device class.
+- Touch targets at least 44x44 CSS px with spacing between them. A small visible mark can sit inside a larger hit area.
+- Detect input, not screen size: `(hover: hover)` and `(pointer: coarse)` queries. Nothing essential lives behind hover; touch gets a visible control or an active state instead.
+- Every swipe, drag, pinch, or multi-finger gesture has a single-tap alternative: buttons for carousel steps, a menu or visible action for swipe-to-delete, steppers or inputs beside a slider, move buttons beside drag reorder.
+- Long-press is never the only way to an action; surface the same action in a visible menu.
+- Never disable pinch zoom. Custom pan or zoom surfaces set `touch-action` so the page still scrolls around them.
+- Gesture results that change data follow the guardrails: a swipe-delete or drag-reorder shows a pending state and changes the list only after the backend confirms.
+- Give touch feedback on press; keep it on the control, not on an image inside it.
 
-Use `cheers` for exact component and patch mechanics.
+### Responsive technique
+
+- Mobile-first: base styles for narrow, `min-width` queries layer complexity. Usually three content-driven breakpoints suffice.
+- Container queries for components that appear in contexts of different widths.
+- Safe areas: `env(safe-area-inset-*)` with `viewport-fit=cover`, using `max()` for fallbacks on fixed bars.
+- Responsive images: `srcset` with width descriptors and accurate `sizes`; `<picture>` only for art direction.
+- `<details>` and `<summary>` for native progressive disclosure; signals for local open and closed affordances.
+- `display: none` still downloads the hidden content's assets; hide sparingly, and prefer not rendering it or `<picture>` and `srcset` for imagery.
+- Prefer CSS over duplicate component trees. When structure truly differs, compose smaller reusable pieces so each backend-refreshed region still exists once.
+
+Never hide core functionality on a device class, switch information architecture between contexts, forget landscape, or assume desktop means a powerful device.
 
 ## Verify
 
-Test narrow mobile, mobile landscape, tablet/small laptop, desktop wide, keyboard-only, touch, and 200% zoom. For action-driven UI, verify the interaction that changes state.
+Inspect in one batched round: narrow phone (320 and 390), phone landscape, tablet, desktop wide, keyboard only, touch, and 200% zoom, on the major engines (Chromium, WebKit/Safari, Firefox) and a throttled connection, plus any named target. Fix everything it shows in one batch and confirm with at most one more round. For action-driven UI, exercise the interaction that changes state in each context.
+
+Exercise each custom control in scope in the same round:
+
+- **Primary gesture:** tap it and confirm it responds as designed, then drag it with the target input; the drag must complete, not just start.
+- **Scroll across it:** a swipe along the page's scroll axis across the control scrolls the page or container without activating it; a drag that starts on the control along its own axis moves the control, not the page. Neither failure throws an error, so try both.
+- **Alternative path:** the non-gesture path reaches the same result.
+
+Say what produced the evidence: an emulated viewport, synthesized touch through a browser tool, which engine ran it (Chromium is not Safari), or a physical device. Screenshots and resized viewports verify layout, never a gesture. Name what stayed untested and move on; unreachable hardware is a reported gap, not a blocker.
+
+Format changed templates with `cargo cheers fmt --rustfmt <files>`. When each context feels native, hand off to `cheers-design polish`.