@brunosps00/dev-workflow 2.5.0 → 2.7.0

package/scaffold/skills/dw-ui-discipline/references/content-stress.md

@@ -0,0 +1,246 @@
+# Content stress — break the UI with realistic worst-case data
+
+> Adapted from the `break-ui` skill in [`emilkowalski/skills`](https://github.com/emilkowalski/skills)
+> (MIT © 2026 Emil Kowalski). The worst-case catalog, failure signatures and truncate/wrap/clamp rule come
+> from there, condensed. Injection at the data boundary, severity mapping and routing into `/dw-qa`,
+> `/dw-review` and `/dw-redesign-ui` are written for dev-workflow.
+
+The state matrix (`state-matrix.md`) asks *which states* a surface has. This reference asks the other
+question: what happens when the data inside a state is the data real users actually produce. Demo data is
+chosen, usually without anyone noticing, to make the design look good: `Jane Doe`, `jane@acme.com`,
+`12 members`, every optional field filled in. Production has `Aleksandra Wiśniewska-Kowalczyk`, an email
+with a 40-character domain, an intern called `Jo`, and a workspace of 1,284 members.
+
+## Two failure modes (the first is worse)
+
+1. **Nonsense data.** `"aaaaaaaaaaaaaaaaaaaaaaaa"` and 5,000-character names prove nothing, and the team rightly
+   stops listening. Every worst-case value must be something a real user could produce, or the actual
+   limit the backend accepts.
+2. **Stopping at long text.** The breaks that ship are usually the short ones: the one-letter name, the
+   missing avatar, the count of exactly 1 (`1 members`), the empty list, the badge whose text got
+   translated.
+
+## Rules
+
+1. **Plausible or schema-backed, never random.** Each value is a realistic example or the real limit from
+   the validation schema (Zod, Yup, Valibot), the database column, the API contract or the form
+   `maxLength`. No limit found is itself a finding: record the field as `unbounded`. A 50-character input
+   that saves to a 255-character column will eventually receive 255 characters through an import or the
+   API.
+2. **Change the data, not the component.** The worst case enters through the same boundary the demo data
+   does: the fixture, the mock, the story args, the API stub, or a network route in the browser test. Never
+   hand-edit markup or CSS to produce a break; that tests the edit, not the component.
+3. **One dataset, many failures.** Spread different failures across the first rows of a list (row 1 the
+   long name, row 2 the unbreakable email, row 3 the one-letter name), the way real data mixes them.
+4. **Dev-only.** A worst-case switch (`?data=worst`, a story, a prototype route) never ships to production.
+5. **Report before fixing.** Some breaks are design decisions (truncate or wrap? hide the role or reserve
+   its line?). List every break with a proposed fix; fixing is the owning command's call.
+6. **Keep the fixture.** It is the regression test for the next person who touches the component.
+7. **Fixture domains:** use `example.com`, `example.org` or `.test` so a fixture never points at a real
+   inbox or site.
+
+## Step 1 — map the surface
+
+List every value the component renders, with its source and limit:
+
+| Field | Source | Type | Limit | Optional? |
+|---|---|---|---|---|
+| `name` | `member.name` | string | 255 (`schema.ts:14`) | No |
+| `email` | `member.email` | string | unbounded | No |
+| `role` | `member.title` | string | 120 | Yes |
+| `count` | `workspace.memberCount` | int | — | No |
+
+Include the values people forget: counts in headers, relative timestamps, badge and status text, button
+labels that come from data, tooltips, avatar images, and the list itself (its length is a value too).
+
+**Done when** every rendered value is in the table with a source and a limit or `unbounded`.
+
+## Step 2 — build the worst case from the catalog
+
+Pick from the rows that apply to the fields in the table.
+
+### People and names
+
+| Value | Breaks |
+|---|---|
+| `Aleksandra Wiśniewska-Kowalczyk` | Long, hyphenated, diacritics; wraps, and the hyphen is a break point |
+| `Christopher Alexander Montgomery III` | Suffix; naive first + last initials give `CI` |
+| `Jo` / `J` | Name column mostly empty; naive initials, tiny click target when the name is the link |
+| `Đặng Thị Ngọc Hân` | Stacked diacritics clipped by tight `line-height` + `overflow: hidden` |
+| `王秀英` | CJK, no spaces; "first + last word" initials finds one word |
+| `نور الهدى عبد الرحمن` | RTL; punctuation and icons land on the wrong side without `dir="auto"` |
+| `María José de la Cruz y Fernández` | Lowercase particles; initials and last-name sorting |
+| `🦊 Fox` / `👩🏽‍💻 Priya` | Emoji first: `.charAt(0)` returns half a surrogate pair; ZWJ sequences split when sliced |
+| `  Sam   Lee ` | Leading, trailing, repeated spaces; initials from empty words |
+| *(missing)* | Only an email exists; the UI must fall back to something |
+
+### Emails, URLs, identifiers (unbreakable strings)
+
+| Value | Breaks |
+|---|---|
+| `bartholomew.fitzgerald@northwind-industries-holdings.example.com` | Pushes every sibling off the row without `overflow-wrap: anywhere` |
+| `a@b.co` | Layout that assumed a long email looks empty |
+| `first.last+billing-notifications@example.com` | Validation rejecting `+`; truncation hiding the meaningful part |
+| A 100-character URL with path and query | Overflow; end-truncation hides the part that differs |
+| `9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f` | UUID; middle-truncation candidate |
+| `Q3 Board Deck — FINAL (revised) v12 [approved].pdf` | End-truncation hides version and extension |
+
+### Labels and copy from data
+
+| Value | Breaks |
+|---|---|
+| `Senior Product Design Engineer, Platform Infrastructure` | Wraps to three lines in a secondary slot |
+| `Invitation expired 12 days ago` | Long status badge squeezes the name column |
+| `Benachrichtigungseinstellungen` | 30-character German compound, no break opportunity |
+| French or German translation of a short label | UI copy runs ~30% longer in translation |
+| Twelve tags on one item / one 45-character tag | Tag wall without a `+N` overflow; a tag wider than its container |
+| `Untitled` / empty string / `   ` | Collapsed heading, zero-height row |
+| `<script>alert(1)</script>` / `&amp;` / `**bold**` | Must render as literal text |
+| Newline inside a single-line field | Doubles row height or is silently dropped |
+| A 2,000-character pasted description | Clamp, "show more", textarea growth |
+
+### Numbers and money
+
+| Value | Breaks |
+|---|---|
+| `0` / `1` | Zero states, division by zero in percentages; `1 members`, `1 days ago` |
+| `1284` / `1000000` | Thousands separator; badge width (consider compact `1M` where precision does not matter) |
+| `12345678.9` as currency | Overflows totals columns |
+| `-42.5`, `142%`, `-3%` | Sign and color logic; bars and meters past their bounds |
+| `0.1 + 0.2`, `null`, `undefined`, `NaN` | Rendered raw |
+| `1.284` (de-DE) vs `1,284` (en-US) | Hardcoded separators are wrong for half the world |
+| A value that changes live (`99` → `100`) | Width jump and jitter without `tabular-nums` |
+
+### Collections
+
+| Value | Breaks |
+|---|---|
+| 0 items / 1 item | The empty state (and whether one exists); grids that look broken with one card |
+| Exactly page size, and page size + 1 | `Showing 40 of 40`, an empty page 2 |
+| 1,000+ items unpaginated | Scroll performance, memory, `Showing 40 of 1,284` copy |
+| One item 10× larger than the others | Rows and masonry stretching to the tallest item |
+| Items with identical names | Lists where the name is the only distinguishing field |
+
+### Time
+
+| Value | Breaks |
+|---|---|
+| Now | `0 seconds ago` instead of "just now" |
+| 12 days, 11 months, 3 years ago | Relative time past about a week should become an absolute date |
+| A future date | `-3 days ago` |
+| `1970-01-01` | A zero timestamp shown as a real date |
+| `2025-12-31T23:30:00-08:00` | A different day in UTC and in the user's timezone |
+
+Use `Intl.RelativeTimeFormat` and `Intl.DateTimeFormat`, not hand-built strings.
+
+### Images and media
+
+| Value | Breaks |
+|---|---|
+| Avatar URL that 404s / no avatar | Broken-image icon; the initials fallback's size and color parity |
+| 4000×200 or 200×4000 image | Distortion without `object-fit: cover`; blown-out card height |
+| Dark or transparent logo in dark mode | Invisible on the background |
+| Slow image without dimensions | Layout shift without fixed size or `aspect-ratio` |
+
+### States mixed into one list
+
+Partial data (some optional fields filled, others not), every enum status at once, a row without
+permission, the current user in the list (`You`, actions that should not apply to yourself), and an API
+error rendered raw (`TypeError: Cannot read properties of undefined`).
+
+## Step 3 — inject at the boundary
+
+Pick the first that exists, in this order:
+
+1. The project's own mock layer: fixtures, MSW handlers, Storybook stories, a seed script.
+2. A network route in the browser test (`page.route()` in Playwright) returning the worst-case payload.
+   This changes no application code and is the default for `/dw-qa`.
+3. A dev-only switch (`?data=worst` read where the fixture is chosen), only when the owning command is
+   allowed to edit code (`/dw-redesign-ui` implement step, `/dw-run`).
+
+Also cover the cases one dataset cannot hold: **empty** (0 items), **one** (single item, every count at
+exactly 1) and **huge** (the realistic upper bound, 1,000+ rows when unpaginated).
+
+## Step 4 — break it
+
+View the worst case and check each failure signature:
+
+- at the component's **real container width** (a sidebar list is not a full-page list), then at **320px**
+  and at the **widest** layout it supports;
+- at **200% browser zoom** (or a raised root font size), because text grows and fixed boxes do not;
+- in **dark mode** and **RTL** (`dir="rtl"` on a wrapper) when the product supports either;
+- on **touch**: hover-only actions (the `•••` that appears on hover) are unreachable.
+
+Screenshot each state when browser tooling exists. Without it, reason from the CSS and say which findings
+were seen and which were inferred.
+
+### Failure signatures
+
+| What you see | Cause | Fix |
+|---|---|---|
+| Avatar or icon squished into an oval | Flex child shrinking | `flex-shrink: 0` on fixed-size boxes |
+| Text overflows its box | Flex/grid child keeps `min-width: auto` | `min-width: 0` on the text column (`minmax(0, 1fr)` in grid) |
+| Email or URL runs past the edge | No break opportunities | `overflow-wrap: anywhere` on that element |
+| Trailing action pushed off-screen | Middle content took all the space | `min-width: 0` on the middle, `flex-shrink: 0` on the action |
+| Badge wraps onto two lines | Badge allowed to shrink | `white-space: nowrap; flex-shrink: 0`, and decide what yields instead |
+| Avatar adrift next to a three-line name | `align-items: center` on rows of varying height | `align-items: flex-start` once text can wrap |
+| Heading breaks mid-word | `word-break: break-all` | `overflow-wrap: anywhere` breaks only when it must |
+| Wrong initials (`J` for Jo, `CI`, `�`) | `.split(' ')[0][0]`, `.charAt(0)` | Grapheme clusters via `Intl.Segmenter`, first + last word, fallback icon |
+| Orphaned `—` or empty line | Placeholder rendered for a missing optional field | Omit the line, or reserve its height on purpose |
+| `1 members`, `0 member` | Hardcoded plural | `Intl.PluralRules` or per-count strings |
+| Numbers jitter, columns misalign | Proportional figures | `font-variant-numeric: tabular-nums` |
+| `1284`, `1,284.000000001`, `NaN` | Raw number rendered | `Intl.NumberFormat` with the user's locale; guard null |
+| Translated button label overflows | Fixed-width button | `min-width` and content width, never a fixed `width` |
+| Diacritics or tall scripts clipped | Tight `line-height` + `overflow: hidden` | Looser `line-height`, no clipping on text boxes |
+| Broken-image icon in the avatar | No error fallback | Fall back to initials; `object-fit: cover` |
+| Truncated text with no way to read it | `text-overflow: ellipsis` and nothing else | `title` or tooltip, plus the full value elsewhere |
+| Last row cut mid-glyph | Fixed height without scroll affordance | Visible scrollbar or fade mask; confirm `overflow` is intended |
+| 1,000 rows stutter | Every row rendered | Virtualize or paginate, and say which |
+| Raw `<b>`, `&amp;`, `**text**` on screen | Wrong escaping layer | Escape once, at render; never `dangerouslySetInnerHTML` user data |
+
+### Truncate, wrap or clamp — decide per field
+
+- **Wrap** text the user needs whole to identify something (names, titles in a detail view). Two lines is
+  usually fine; four means the column is too narrow.
+- **Truncate at the end** secondary metadata whose start carries the meaning (role, description, message
+  preview), always with a way to see the full value.
+- **Truncate in the middle** when items differ at the *end*: file names, emails sharing a domain, paths,
+  hashes. End-truncation makes them identical.
+- **Clamp** (`line-clamp: 2`) multi-line previews in cards, so card heights stay predictable.
+- **Never truncate** numbers, amounts, dates, or anything the user compares.
+
+## Severity mapping
+
+| Content-stress class | dev-workflow severity | Meaning |
+|---|---|---|
+| Broken | high | Content unreadable, action unreachable, or wrong data shown |
+| Ugly | medium | Readable but visibly wrong: squished avatar, wrapped badge |
+| Fragile | low | Fine now, one realistic step from breaking: no limit, no fallback |
+
+Raise to critical only when the break hides or misstates money, permissions, or destructive actions.
+
+## Static signals for code review
+
+`/dw-review` cannot render, but these patterns in a UI diff are candidates (each still goes through
+`dw-review-rigor`):
+
+- Initials built with `.split(' ')`, `[0]`, `.charAt(0)` or `.slice(0, 1)` on a name.
+- A count interpolated next to a fixed plural noun (`` `${n} members` ``).
+- `text-overflow: ellipsis` / `truncate` with no `title`, tooltip or detail path.
+- A fixed `width` on a button or badge whose label comes from data or translation.
+- A flex row with an avatar or trailing action and no `flex-shrink: 0`, or a text column with no
+  `min-width: 0`.
+- Numbers rendered without `Intl.NumberFormat` / dates without `Intl.DateTimeFormat`.
+- `dangerouslySetInnerHTML` (or `v-html`, `innerHTML`) fed by user or API data — also a security finding.
+- A new string field rendered in UI with no limit in the schema (`Fragile`).
+
+## Output
+
+One row per break, worst first:
+
+| # | Severity | Field | Worst-case value | What happens | Fix (`file:line`) |
+|---|---|---|---|---|---|
+
+Then **Decisions for you** (breaks with more than one right answer, one line each with a recommendation)
+and **What held up** (worst cases the component already handles — proof the test was real, and a list of
+what not to touch).

package/scaffold/skills/dw-ui-discipline/references/motion.md

@@ -1,52 +1,222 @@
-# Motion — easing, duration, stagger, reduced motion
+# Motion — whether to animate, easing, duration, physicality, performance
 
-> Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
-> Anthropic's frontend-design skill). Read when adding animation or transitions.
+> First version adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
+> Anthropic's frontend-design skill). Rewritten 2026-11 from the `emil-design-eng`, `review-animations`,
+> `animation-performance` and `remove-animations` skills in
+> [`emilkowalski/skills`](https://github.com/emilkowalski/skills) (MIT © 2026 Emil Kowalski): the
+> frequency gate, easing table, curves, physicality rules, escalation triggers and removal gate come from
+> there. Read when adding, reviewing or removing animation or transitions.
 
-## Motion conveys state, not decoration
+Project motion tokens (`DESIGN.md`, CSS variables, Tailwind config) win over the values below. These are
+the defaults when the project has none, and the bar when reviewing motion it already has.
 
-Animate to explain a change: where did this come from, what just happened, where did it go. If a motion
-doesn't answer one of those, cut it. Decorative motion is a visual-slop pattern.
+## 1. Should it animate at all?
 
-## Easing — avoid bounce/elastic
+Decide this before choosing any curve. Frequency first:
 
-Real objects decelerate smoothly. Bounce and elastic easing feel dated and tacky (the detector flags
-`bounce-easing` / spring overshoot like `cubic-bezier(0.68,-0.55,0.27,1.55)`).
+| How often the user sees it | Decision |
+|---|---|
+| 100+ times a day (keyboard shortcuts, command palette, tab switches, in-app route changes, list rows) | No animation. Any duration reads as delay. |
+| Tens of times a day (hover, frequent toggles, list expansion) | Remove, or reduce to near-imperceptible |
+| Occasional (modals, drawers, toasts) | Standard motion |
+| Rare or first-time (onboarding, success, empty state) | Room for delight |
 
-- **Enter** (element appears): ease-out — fast start, soft landing. `cubic-bezier(0.16, 1, 0.3, 1)`
-  (ease-out-expo) or `ease-out`.
-- **Exit** (element leaves): ease-in — accelerate away. `cubic-bezier(0.4, 0, 1, 1)`.
-- **Move/resize on screen:** ease-in-out (standard) `cubic-bezier(0.4, 0, 0.2, 1)`.
-- Never linear for UI (only for continuous things like spinners/marquees).
+**Keyboard-initiated actions never animate.** They repeat hundreds of times a day.
 
-## Duration
+Then purpose. Valid purposes: spatial consistency (where did this come from / go), state indication,
+explanation, feedback, preventing a jarring change. "It looks nice" on a frequently seen element is not a
+purpose. Functional data (charts, tables, numbers) does not re-animate on every mount or refresh; it
+animates only to show a real change in value.
 
-- Micro (hover, small fades): 100–150ms.
-- Standard (dropdowns, toggles, cards): 200–300ms.
-- Large (page/route, full-screen sheets): 300–500ms.
-- Over ~500ms feels sluggish; under ~80ms is imperceptible (just snap with no transition).
+Deleting everything is also wrong: a toast that would otherwise teleport in, or a panel that needs to show
+where it came from, earns its motion.
 
-## Stagger
+## 2. Easing
 
-When several items enter together, stagger them 20–50ms apart so the eye follows the sequence — but cap
-total stagger (don't make the 12th list item wait 600ms). Stagger entrances, not exits.
+| Motion | Easing |
+|---|---|
+| Entering or exiting | `ease-out` (starts fast, feels responsive) |
+| Moving or morphing on screen | `ease-in-out` |
+| Hover, color change | `ease` |
+| Constant motion (marquee, progress, spinner) | `linear` |
+| Default | `ease-out` |
 
-## What to animate (performance)
+**Never `ease-in` on UI**, exits included. It starts slow and delays the exact moment the user is watching;
+`ease-out` at 200ms feels faster than `ease-in` at 200ms.
 
-Animate only `transform` and `opacity` — they run on the compositor and don't trigger layout/paint.
-Animating `width`, `height`, `top`, `left`, `margin` janks. Use `transform: translate/scale` instead.
+The built-in keywords are weak. Default curves when the project has none:
 
-## `prefers-reduced-motion` (required)
+```css
+--ease-out: cubic-bezier(0.23, 1, 0.32, 1);      /* UI enter/exit */
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);  /* on-screen movement */
+--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);   /* iOS-like drawer/sheet */
+```
 
-Honor it. Replace movement with an instant or opacity-only change.
+### Bounce and springs
 
-```css
-@media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    transition-duration: 0.01ms !important;
-  }
-}
+No bounce, elastic or overshooting `cubic-bezier` (e.g. `cubic-bezier(0.68, -0.55, 0.27, 1.55)`) on UI
+transitions — the `ui-slop-detect` gate flags these as `bounce-easing`.
+
+**Springs are allowed only for gesture-driven motion:** drag with momentum, drag-to-dismiss sheets,
+swipe, and anything the user may reverse mid-motion. Springs keep velocity when interrupted, which is what
+a gesture needs. Keep bounce subtle:
+
+```js
+{ type: "spring", duration: 0.5, bounce: 0.2 } // bounce 0.1–0.3
 ```
 
-Don't remove *feedback* entirely — a state change still needs to be visible, just not kinetic.
+A spring on a button, dropdown, modal or toast is out of scope for this exception.
+
+## 3. Duration
+
+| Element | Duration |
+|---|---|
+| Button press feedback | 100–160ms |
+| Tooltips, small popovers | 125–200ms |
+| Dropdowns, selects | 150–250ms |
+| Modals, drawers | 200–500ms |
+| Marketing / explanatory | Can be longer |
+
+**UI animations stay under 300ms** unless a reason is written down. Under ~80ms is imperceptible: snap
+instead. After the first tooltip in a group opens, the next ones open instantly (no delay, no animation).
+
+## 4. Physicality
+
+- **Never `scale(0)`.** Nothing appears from nothing. Start from `scale(0.95)` (0.9–0.97) with `opacity: 0`.
+- **Popovers, dropdowns and tooltips scale from their trigger**, not the center:
+  `transform-origin: var(--transform-origin)` (Base UI / Radix expose it). **Modals are exempt** — they
+  appear centered and keep `transform-origin: center`.
+- **Press feedback:** `transform: scale(0.97)` on `:active` (0.95–0.98), 100–160ms `ease-out`, on every
+  pressable element. It works on touch, unlike hover.
+- **`translateY(100%)`** moves an element by its own height, so drawers and toasts of unknown size need no
+  hardcoded pixels.
+
+## 5. Interruptibility and timing
+
+- **Transitions over keyframes** for anything triggered rapidly (toasts being added, toggles). A transition
+  retargets from its current state; a keyframe animation restarts from zero.
+- Entry without JS: `@starting-style` on the transitioned element.
+- **Asymmetric timing:** slow where the user is deciding (a hold-to-confirm, a destructive press), fast
+  where the system responds (the release, the result).
+- **Stagger** group entrances 30–80ms per item, capped so the whole group finishes within ~300ms.
+  Stagger entrances, not exits, and never block interaction while it plays.
+- An imperfect crossfade can be bridged with `filter: blur(2px)` during the transition; keep any animated
+  blur under 20px.
+
+## 6. Performance
+
+Every frame has **16.7ms at 60fps and 8ms at 120Hz** (most phones). Design against 8ms. A fast laptop hides
+almost every problem below; say which findings were verified from code and which need a recording on a
+mid-range device.
+
+| Tier | Properties | Cost |
+|---|---|---|
+| Composite only | `transform`, `opacity` (and in current browsers `filter`, `clip-path`) | Cheapest |
+| Paint + composite | `box-shadow`, `border-radius`, `color` | Redraw every frame |
+| Layout + paint + composite | `width`, `height`, `padding`, `margin`, `top`, `left`, `border-width` | Most expensive |
+
+- Animate `transform` and `opacity` by default. Swaps: `width`/`height` → `scale()`; `top`/`left`/`margin` →
+  `translate()`; animated `box-shadow` → `filter: drop-shadow()`.
+- **Never `transition: all`.** List the exact properties; `all` animates whatever changes next, including
+  layout properties nobody meant to animate. (Tailwind: `transition-transform`, `transition-opacity`, not
+  `transition-all`.)
+- Do not drive child transforms through a CSS variable set on a parent; it recalculates style for every
+  child. Set `transform` on the element itself.
+- In React, a hand-rolled animation writes to `ref.current.style`, never `setState` every frame.
+- Predetermined motion runs in CSS or WAAPI (off the main thread); JS/rAF for dynamic, gesture-driven
+  motion. Motion's `x`/`y`/`scale` shorthands are hardware-accelerated from `motion` 14.2; on older versions
+  animate the full `transform` string. Layout animations (`layout`, `layoutId`) always run on the main
+  thread.
+- `will-change` is the last step, added only after a measured problem (a 1px shift at start/end, dropped
+  frames on a recording). Never on `*` or large containers.
+- Name the cause before changing code. "Added `will-change`, seems smoother" is not a diagnosis.
+
+## 7. Accessibility
+
+- **`prefers-reduced-motion` means fewer and gentler, not zero.** Drop movement (translate, scale,
+  parallax, slide); keep the opacity and color changes that explain a state change.
+
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    .drawer { transition: opacity 200ms ease; transform: none; }
+  }
+  ```
+
+  ```jsx
+  const reduce = useReducedMotion();
+  const closedX = reduce ? 0 : "-100%";
+  ```
+
+  A global `animation-duration: 0.01ms !important` reset is an acceptable project-wide fallback, not the
+  design: state changes still have to be visible.
+- **Gate hover motion** behind `@media (hover: hover) and (pointer: fine)`. Touch fires a fake hover on tap
+  and leaves it stuck (see `responsive.md`).
+
+## 8. Removing motion
+
+When the job is to cut motion (an over-animated product, a performance pass), walk each animation through
+this gate and record the deciding branch:
+
+1. Keyboard-triggered? → **delete**.
+2. Seen 100+ times a day? → **delete**.
+3. On functional data? → **delete**, unless it shows a real change in value.
+4. No nameable purpose? → **keep** if it is a rare first-time moment, otherwise **delete**.
+5. Purpose, seen tens of times a day? → **reduce**.
+6. Purpose, rarer: over 300ms, or a slide/scale where a fade carries the same meaning? → **reduce**,
+   otherwise **keep**.
+
+Marketing pages get more latitude (one hero entrance, explanation), but scroll-reveal on every section
+still fails.
+
+| Today | Reduced to |
+|---|---|
+| Hover with scale, lift or shadow growth | Color/opacity only, ≤150ms, `ease` |
+| Slide or scale entrance on a frequent surface | Opacity only, 150ms, `ease-out` |
+| UI animation over 300ms | 200–250ms, same curve |
+| Stagger over 80ms per item or 300ms total | 30ms per item, or fade the group as one |
+| Infinite loop (pulse, shimmer, glow) on a persistent element | Run once, or keep the static end state |
+
+Spinners and skeletons on work that resolves under 300ms are deleted too (see `state-matrix.md`).
+
+**Removal hazards** — check before deleting, or the removal becomes a regression:
+
+- **Hidden start states.** `initial={{ opacity: 0 }}`, a keyframe from `opacity: 0` with
+  `fill-mode: forwards`, a reveal class waiting for an observer. Remove the start state with the animation
+  or the element stays invisible.
+- **Code waiting on the animation:** `onAnimationEnd`, `transitionend`, `onExitComplete`, `setTimeout`
+  sized to a duration.
+- **Exit animations delaying unmount** (`AnimatePresence`): move what ran on exit-complete to the close.
+- **Layout animations masking a jump** (`layout`, FLIP): if the jump appears, keep the animation and report
+  the layout shift.
+- **Focus moved in an animation callback** must move immediately.
+- **Tests and selectors** that wait for animation classes or durations.
+
+Then delete what the removal orphaned (unused `@keyframes`, `motion.div` with no motion props left, empty
+`AnimatePresence`, unused variants and imports). Propose — never perform — removing a motion library
+dependency.
+
+## 9. Review escalation triggers
+
+`/dw-review` treats each of these in a UI diff as a candidate finding (still subject to `dw-review-rigor`
+refutation). Default severity **medium**; **high** when the motion runs on a keyboard-triggered or
+100+/day action, or when it blocks interaction.
+
+- `transition: all` / Tailwind `transition-all`.
+- `scale(0)` as a start state.
+- `ease-in` on any UI enter, exit or interaction.
+- Animation on a keyboard shortcut, command-palette toggle or other 100+/day action.
+- UI duration over 300ms with no stated reason.
+- `transform-origin: center` on a trigger-anchored popover, dropdown or tooltip.
+- Keyframes on toasts, toggles or anything triggered rapidly.
+- Animating `width`, `height`, `margin`, `padding`, `top` or `left` when a transform does the same.
+- A CSS variable on a parent driving child transforms.
+- Movement with no `prefers-reduced-motion` handling.
+- `:hover` motion not gated by `(hover: hover) and (pointer: fine)`.
+- Bounce/overshoot easing, or a spring outside gesture-driven motion.
+- Symmetric timing on a press-and-hold or destructive-confirm interaction.
+
+Fix preference, earliest first: delete → reduce → fix easing → fix origin → make interruptible → move to
+composite-only properties → asymmetric timing → polish → accessibility and cohesion.
+
+When feel cannot be judged from code (hover feel, perceived speed, gesture physics), say so and ask for a
+slow-motion pass (DevTools animation panel at 2–5× duration) or a real device, instead of guessing.

package/scaffold/skills/dw-ui-discipline/references/responsive.md

@@ -1,7 +1,9 @@
 # Responsive — mobile-first, container queries, fluid space
 
 > Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
-> Anthropic's frontend-design skill). Read when a surface must work across devices.
+> Anthropic's frontend-design skill). The "Mobile platform fixes" section is adapted from the
+> `mobile-native` skill in [`emilkowalski/skills`](https://github.com/emilkowalski/skills)
+> (MIT © 2026 Emil Kowalski). Read when a surface must work across devices.
 
 ## Mobile-first
 
@@ -43,10 +45,50 @@ Keep body text fixed (≥16px); fluid body harms readability.
 - Touch targets ≥ 24×24 CSS px (≥ 44×44 recommended on mobile). Spacing between targets matters as much
   as size.
 - Don't hide primary actions behind hover — hover doesn't exist on touch. Provide a tap-visible path.
-- Respect safe-area insets on mobile (`env(safe-area-inset-*)`) for notches/home indicators.
+- Respect safe-area insets on mobile (`env(safe-area-inset-*)`) for notches/home indicators — this needs
+  `viewport-fit=cover` in the viewport meta, or every inset is `0px` (see below).
 
 ## Layout reflow
 
 State explicitly how elements reorganize between breakpoints: stack vs. side-by-side, what collapses into
 a menu, what hides (and whether hidden content is still reachable). "Hidden on mobile with no alternative"
 is a bug, not a layout decision.
+
+## Mobile platform fixes
+
+Most "the app feels janky on mobile" reports are not animation problems: they are a tap delay, a gray
+flash on tap, or a hover state that will not let go. **None of these reproduce in desktop device
+emulation.** Gate by capability with media queries, never by user-agent sniffing or screen width — touch
+and mouse coexist (iPads with trackpads, touchscreen laptops). Apply each fix where its reason applies, not
+globally out of habit.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Hover state stuck after tap | Touch fakes `:hover` on the first tap and keeps it | Put `:hover` rules inside `@media (hover: hover) and (pointer: fine)` (Tailwind v4 `hover:` already does; v3 needs `future.hoverOnlyWhenSupported`) and give touch an `:active` state |
+| Gray/blue flash on tap | Browser tap highlight | `html { -webkit-tap-highlight-color: transparent; }`, then make sure every tappable element has its own `:active` feedback |
+| Bottom-pinned UI hidden under the URL bar | `100vh` is the largest viewport | `100dvh` for app shells, drawers and bottom-pinned UI; `100svh` for heroes (stable, no shift on scroll) |
+| Page zooms into an input and stays zoomed | iOS zooms on inputs under 16px | `font-size: 16px` on `input, textarea, select` (scope it with `@media (pointer: coarse)` if desktop needs smaller). **Never** `user-scalable=no` or `maximum-scale=1` — that is an accessibility failure (`accessibility-floor.md` §11) |
+| Tap feels laggy | Double-tap-zoom wait; feedback on release | `touch-action: manipulation` on buttons, links, `[role="button"]`; press feedback on `:active` (100–160ms `ease-out`, see `motion.md`), `pointerdown` not `click` when JS must react |
+| Pull-to-refresh or rubber band hijacks an app | Scroll chaining to the page | `overscroll-behavior: none` on `html, body` in apps (not documents); `contain` on inner scrollers. Never a `touchmove` + `preventDefault()` listener |
+| Content cut by the notch / home indicator | Safe area | `viewport-fit=cover` in the viewport meta + `padding-top: env(safe-area-inset-top)` / `padding-bottom: env(safe-area-inset-bottom, 0px)` on fixed headers, tab bars, toasts and sheets |
+| Long-press selects a button label | Text selection on controls | `user-select: none; -webkit-user-select: none; -webkit-touch-callout: none;` on controls only — never on `body`; users copy addresses and order numbers |
+| Carousel drags the page vertically | Ambiguous gesture axis | `touch-action: pan-y` on a horizontal carousel, `none` only on surfaces that own every axis; prefer native `scroll-snap-type: x mandatory` |
+| Status bar color wrong in one scheme | Single `theme-color` | One `<meta name="theme-color" media="(prefers-color-scheme: …)">` per scheme, matching the top of the page, plus `color-scheme: light dark` |
+
+Inputs also set the right keyboard: `type="email"` / `type="tel"`, `inputmode="numeric"` for codes and
+`"decimal"` for amounts, `autocapitalize="none"` on usernames and codes, `enterkeyhint` naming what Return
+does.
+
+Baseline for a mobile-facing app:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
+```
+
+`interactive-widget=resizes-content` makes the Android software keyboard shrink the layout viewport, so
+`100dvh` and bottom-pinned inputs react to it the way they do on iOS.
+
+**Real hardware is the bar.** Sticky hover, tap delay, URL-bar height, input zoom, overscroll, safe areas
+and the software keyboard only show on a device: dev server on `0.0.0.0`, open it by LAN IP, inspect with
+Safari Web Inspector or `chrome://inspect`. When no device is available, report which fixes were verified
+from code and which still need a phone — never declare them fixed from emulation.