@tamsensedev/runner 0.0.0-stage → 0.1.0

package/library/skills/interface-polish/references/detail-rules.md

@@ -0,0 +1,154 @@
+# Detail rules with code
+
+Read this when applying a specific polish rule and you want the exact values. Examples are in plain CSS with a Tailwind equivalent where it helps; translate them into the project's styling system and tokens.
+
+## Concentric radius
+
+```css
+.card       { border-radius: 16px; padding: 8px; }  /* 8 + 8 */
+.card-inner { border-radius: 8px; }
+```
+
+Tailwind: `rounded-2xl p-2` (16px radius, 8px padding) on the outer element, `rounded-lg` (8px = 16 - 8) on the inner one.
+
+With padding over about 24px, the layers read as separate surfaces; choose each radius from the scale.
+
+## Optical alignment
+
+```css
+.button-with-trailing-icon { padding-inline: 16px 14px; } /* icon side = text side - 2px */
+.play-button svg { translate: 2px 0; }                    /* triangle's visual centre */
+```
+
+For lopsided icons (stars, carets), adjust the SVG `viewBox` or path so no wrapper offset is needed.
+
+## Shadow as border, and elevation
+
+```css
+:root {
+  --shadow-border:
+    0 0 0 1px rgb(0 0 0 / 0.06),
+    0 1px 2px -1px rgb(0 0 0 / 0.06),
+    0 2px 4px 0 rgb(0 0 0 / 0.04);
+  --shadow-border-hover:
+    0 0 0 1px rgb(0 0 0 / 0.08),
+    0 1px 2px -1px rgb(0 0 0 / 0.08),
+    0 2px 4px 0 rgb(0 0 0 / 0.06);
+}
+.dark {
+  --shadow-border: 0 0 0 1px rgb(255 255 255 / 0.08);
+  --shadow-border-hover: 0 0 0 1px rgb(255 255 255 / 0.13);
+}
+.card { box-shadow: var(--shadow-border); transition: box-shadow 150ms ease-out; }
+.card:hover { box-shadow: var(--shadow-border-hover); }
+```
+
+| Prefer a shadow | Keep a border |
+|---|---|
+| Cards and buttons on varied backgrounds | Dividers between list items |
+| Floating layers (menus, popovers, dialogs) | Table cell boundaries |
+| Hover lift on clickable cards | Form input outlines |
+
+Use this only if it matches the product's depth strategy; a product built on plain borders keeps borders.
+
+## Image outlines
+
+```css
+img.media { outline: 1px solid rgb(0 0 0 / 0.1); outline-offset: -1px; }
+.dark img.media { outline-color: rgb(255 255 255 / 0.1); }
+```
+
+Tailwind: `outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10`. Pure black or white only, never a tinted grey from the palette.
+
+## Hit areas
+
+```css
+.icon-button { position: relative; width: 20px; height: 20px; }
+.icon-button::after {
+  content: "";
+  position: absolute;
+  inset: 50% auto auto 50%;
+  width: 44px; height: 44px;
+  translate: -50% -50%;
+}
+```
+
+If the extended area would overlap a neighbour, shrink it to the largest size that does not.
+
+## Type rendering
+
+```css
+html { -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
+h1, h2, h3 { text-wrap: balance; }      /* short text only: browsers balance up to about 6 lines */
+p, li, figcaption { text-wrap: pretty; }
+.num { font-variant-numeric: tabular-nums; }
+```
+
+`tabular-nums` belongs on counters, timers, prices that update and table columns, not on phone numbers, version strings or decorative display numbers. Some fonts change the look of "1" with it; check it renders well.
+
+Font family is not a polish decision: use the product's type system and never add a paid face for polish.
+
+## Overflow in rows
+
+```css
+.row        { display: flex; align-items: center; gap: 12px; }
+.row-avatar { flex-shrink: 0; }
+.row-text   { min-width: 0; flex: 1; }
+.row-email  { overflow-wrap: anywhere; }
+.row-badge  { flex-shrink: 0; white-space: nowrap; }
+.row-menu   { flex-shrink: 0; }
+```
+
+Grid equivalent: `grid-template-columns: auto minmax(0, 1fr) auto`. When text can wrap to several lines, top-align the row (`align-items: flex-start`) so the avatar does not drift.
+
+## Icons
+
+| Text beside the icon | Stroke on a 24px grid |
+|---|---|
+| Regular (400), 14 to 16px | 1.5px |
+| Medium or semibold (500 to 600) | 2px |
+| Bold (700) or standalone emphasis | 2.5px |
+
+```html
+<svg fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true">...</svg>
+```
+
+```css
+.icon-button { color: var(--text-muted); }
+.icon-button:hover { color: var(--text); }
+.icon-button[aria-pressed="true"] { color: var(--accent); }
+```
+
+Strip hard-coded `fill` and `stroke` colours from imported icons. Inline icons are about 1em to 1.25em. Directional icons (back, forward, chevrons, send) flip in RTL; logos, checkmarks, clocks and media controls do not. Icon-only buttons need an accessible name; decorative icons get `aria-hidden="true"`.
+
+## Press feedback and transitions
+
+```css
+.button {
+  transition-property: transform, background-color;
+  transition-duration: 150ms;
+  transition-timing-function: cubic-bezier(0.23, 1, 0.32, 1);
+}
+.button:active:not(:disabled) { transform: scale(0.97); }
+
+@media (hover: hover) and (pointer: fine) {
+  .card-link:hover { background-color: var(--surface-hover); }
+}
+```
+
+Tailwind: `transition-[transform,background-color] duration-150 active:not-disabled:scale-[0.97]`. Never `transition-all`. Use `will-change: transform` only to cure an observed first-frame stutter, never broadly.
+
+## Focus
+
+```css
+:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 2px; }
+.input:focus-visible { outline-offset: 0; }
+```
+
+Never `outline: none` without a replacement. Sticky headers and footers must not cover the focused element: `scroll-padding-top` on the scroll container equal to the header height.
+
+## Overlays and clipping
+
+A menu inside an `overflow: hidden` or `overflow: auto` ancestor is clipped. Use the project's popover or portal component, `<dialog>`, the `popover` attribute, or `position: fixed` with collision handling. Popovers scale from their trigger (`transform-origin` at the trigger), dialogs from the centre.
+
+Sources: adapted from jakubkrehel/make-interfaces-feel-better surfaces, typography, icons, animations and performance references (MIT, changed: values reconciled to scale(0.97), Motion-specific code removed, plain CSS first), emilkowalski/skills break-ui failure signatures (MIT) and pbakaus/impeccable operate reference (Apache-2.0, changed: rewritten).

package/library/skills/interface-polish/references/worst-case-data.md

@@ -0,0 +1,158 @@
+# Stress-testing with worst-case data
+
+Read this when checking that a component or screen survives real data, before finishing UI work or as part of a review.
+
+The component was almost certainly built against kind data: "Jane Doe, jane@acme.com, 12 members". Production has Aleksandra Wiśniewska-Kowalczyk, `bartholomew.fitzgerald@northwind-industries-holdings.example.com`, an intern called Jo and a workspace with 1,284 members.
+
+## Rules
+
+1. **Plausible or schema-backed, never random.** Each value is something a real user could produce, or the actual limit from the validation schema, database column or API contract. Five thousand "a" characters prove nothing. If no limit exists, that is a finding ("unbounded"); test something long but believable.
+2. **Change the data, not the component.** The worst case enters through the same boundary as the demo data: the fixture, mock, story args, seed, or an intercepted API response. Never edit markup or CSS to provoke a break.
+3. **One dataset, many failures.** Spread different worst cases across the first rows (row 1 the long name, row 2 the long email, row 3 the one-letter name), the way real data mixes them.
+4. **Do not stop at long text.** The breaks that ship are the short name, the missing avatar, "1 members", the empty list, the translated badge.
+5. **Leave no test toggles in product code.** In a code step, a worst-case fixture may be committed only where the project keeps fixtures (tests, stories, mocks), following its conventions. In a review step, use only interception or existing fixtures and change nothing.
+
+## Phase 1: map what the component renders
+
+List every value it shows, with its source, type, limit and whether it is optional:
+
+| Field | Source | Type | Limit | Optional |
+|---|---|---|---|---|
+| name | member.name | string | 255 (schema.ts:14) | no |
+| email | member.email | string | none found | no |
+| role | member.title | string | 120 | yes |
+| status | enum | active / invited / expired | n/a | no |
+| count | workspace.memberCount | int | n/a | no |
+
+Include the values people forget: counts in headers, relative times, badge and status text, labels that come from data, tooltips, avatar images, and the list length itself. Find limits in validation schemas, migrations, API types and `maxlength` attributes; note where front end and back end disagree.
+
+## Phase 2: build the worst case
+
+Pick values from the catalog below. Also cover cases that are not one dataset:
+
+- **Empty**: zero items, and no results after filtering.
+- **One**: a single item, and every count at exactly 1.
+- **Huge**: the realistic upper bound (1,000 or more rows if unpaginated).
+
+## Phase 3: look
+
+Check the worst case:
+
+- at the component's real container width (a sidebar list is not a full-page list), then at 320px and the widest supported layout;
+- with browser zoom at 200%, because text grows and boxes do not;
+- in dark mode and with `dir="rtl"` if the product supports them.
+
+Screenshot both demo and worst case at each width (procedure in `design-review`). Say which findings you saw and which you inferred from code.
+
+## Catalog
+
+Use `example.com`, `example.org` or `.test` domains so fixtures never point at real inboxes.
+
+**People and names**
+
+| Value | Breaks |
+|---|---|
+| `Aleksandra Wiśniewska-Kowalczyk` | Long, hyphenated, diacritics; wraps at the hyphen |
+| `Christopher Alexander Montgomery III` | Suffix; naive initials give "CI" |
+| `Jo`, `J` | Near-empty name column; one-letter initials; tiny click target if the name is the link |
+| `Đặng Thị Ngọc Hân` | Stacked diacritics clipped by tight line height with `overflow: hidden` |
+| `王秀英` | No spaces; "first plus last word" initials find one word |
+| `نور الهدى عبد الرحمن` | RTL; punctuation and icons on the wrong side without `dir="auto"` |
+| `Seán O'Brien-Ó Súilleabháin` | Apostrophe and accents: escaping, initials, search |
+| A name starting with an emoji ("Fox" after a fox emoji), or with a skin-tone and joiner sequence before "Priya" | `charAt(0)` returns half a character; slicing splits the sequence |
+| `  Sam   Lee ` | Leading, trailing and repeated spaces |
+| missing name | Only an email; the UI needs a fallback |
+
+**Emails, URLs, identifiers**
+
+| Value | Breaks |
+|---|---|
+| `bartholomew.fitzgerald@northwind-industries-holdings.example.com` | No wrap points; pushes siblings off the row |
+| `a@b.co` | Layout that assumed a long email looks empty |
+| `first.last+billing-notifications@example.com` | Plus addressing rejected or truncated |
+| A long URL with query string | End truncation hides the part that differs |
+| `9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f` | UUID width; candidate for middle truncation |
+| `Q3 Board Deck FINAL (revised) v12 [approved].pdf` | End truncation hides version and extension |
+
+**Labels and text from data**
+
+| Value | Breaks |
+|---|---|
+| `Senior Product Design Engineer, Platform Infrastructure` | Wraps to three lines in a secondary slot |
+| `Invitation expired 12 days ago` as a badge | Badge wraps or squeezes the name |
+| `Benachrichtigungseinstellungen` | German compound, no break points |
+| French or German UI strings | About 30% longer than English |
+| Twelve tags on one item | Tag rows become a wall; needs "+8" |
+| Empty string or whitespace title | Collapsed heading, zero-height row |
+| `<script>alert(1)</script>`, `&amp;`, `**bold**` | Must render as literal text |
+| A 2,000-character description | Clamping, "show more", textarea growth |
+
+**Numbers and money**
+
+| Value | Breaks |
+|---|---|
+| 0 | "0 members", empty bars, division by zero in percentages |
+| 1 | "1 members", "1 days ago" |
+| 1284, 1000000 | Missing separators; badge width; consider compact form where precision does not matter |
+| 12345678.9 as currency | Overflowing totals columns |
+| -42.5 | Sign, colour logic, accounting parentheses |
+| 0.1 + 0.2 | `0.30000000000000004` rendered raw |
+| 142%, -3% | Progress bars past their bounds |
+| null, undefined, NaN | Rendered literally |
+| A live value 99 then 100 | Width jump without tabular figures |
+
+**Collections**: 0 items; 1 item (grids that look broken with one card); exactly the page size and one more; 1,000+ unpaginated; one item ten times larger than the others; items with identical names.
+
+**Time**: now ("0 seconds ago"); 12 days, 11 months, 3 years ago (switch to absolute dates); a future date; `1970-01-01`; a time near midnight in another time zone; a duration of 1,284 hours.
+
+**Images**: avatar URL that fails (fallback to initials); no avatar; a 4000 x 200 panorama and a 200 x 4000 strip (need `object-fit: cover`); a dark transparent logo on a dark theme; a slow image (needs fixed dimensions).
+
+**States**: loading; API error (no raw `TypeError` text on screen); partial data; every status value at once; no permission; the current user in the list.
+
+## Failure signatures
+
+| What you see | Cause | Fix |
+|---|---|---|
+| Avatar or icon squashed into an oval | Flex child shrinking | `flex-shrink: 0` on fixed-size items |
+| Text overflows instead of wrapping or truncating | `min-width: auto` on a flex or grid child | `min-width: 0`, or `minmax(0, 1fr)` |
+| Email or URL runs past the edge | No break opportunities | `overflow-wrap: anywhere` on that element |
+| Trailing menu pushed off-screen | Middle content took 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`, decide what yields |
+| Avatar adrift beside a three-line name | `align-items: center` on rows of varying height | Top-align once text can wrap |
+| Last row cut mid-glyph | Fixed height without scroll affordance | Visible scroll or a fade, intended `overflow` |
+| Heading breaks mid-word | `word-break: break-all` | `overflow-wrap: anywhere` |
+| Wrong initials | `split(' ')[0][0]` | Grapheme-aware initials (`Intl.Segmenter`), first and last word, icon fallback |
+| Orphaned dash where an optional field was | Placeholder for a missing value | Omit the line, or reserve its height on purpose |
+| "1 members" | Hard-coded plural | `Intl.PluralRules` or the project's i18n |
+| Numbers jitter as they update | Proportional figures | `tabular-nums` |
+| `1284`, `NaN`, `undefined` | Raw number rendered | `Intl.NumberFormat`, guard null |
+| Translated button label overflows | Fixed width | Width from content with a `min-width` |
+| Tall scripts clipped | Tight line height with hidden overflow | Looser line height, no clipping on text |
+| Broken-image icon | No error fallback | Fall back to initials or a neutral icon |
+| Truncated text with no way to read it | Ellipsis only | Title or tooltip, and the full value in a detail view |
+| 1,000 rows stutter | Every row rendered | Virtualize or paginate |
+| Raw `<b>`, `&amp;` or `**text**` shown | Wrong escaping layer | Escape once at render; never inject user HTML |
+
+## Truncate, wrap or clamp
+
+Decide per field:
+
+- **Wrap** what identifies something (names, titles in a detail view). Two lines is fine; four means the column is too narrow.
+- **Truncate at the end** for secondary metadata where the start carries the meaning (role, preview text), always with a way to see the full value.
+- **Truncate in the middle** where items differ at the end (file names, paths, hashes, emails sharing a long domain).
+- **Clamp** (`line-clamp: 2`) multi-line previews in cards so heights stay predictable.
+- **Never truncate** numbers, amounts, dates, or anything people compare.
+
+## Output
+
+| # | Severity | Field | Worst-case value | What happens | Fix (`file:line`) |
+|---|---|---|---|---|---|
+| 1 | Broken | email | `bartholomew.fitzgerald@...example.com` | Menu unreachable at 400px | `min-width: 0` on text column, `overflow-wrap: anywhere` on email |
+| 2 | Ugly | count | 1 | "1 members" | Plural rules |
+| 3 | Fragile | name | n/a | No max length in schema or form | Matching limits in both |
+
+Severity: **Broken** (unreadable, unreachable, wrong data), **Ugly** (readable but visibly wrong), **Fragile** (fine now, one realistic step from breaking). Also list what held up, so the test is visibly real.
+
+In a code step, fix the breaks; where there are several right answers (truncate or wrap, what an empty role shows), choose by the rules above, apply it, and list the choice in the report. In a review step, report only.
+
+Sources: adapted from emilkowalski/skills break-ui SKILL.md and CATALOG.md (MIT, changed: no interactive toggle shipped, no "report and wait for the user" step; code steps fix, review steps report) and pbakaus/impeccable harden reference (Apache-2.0, changed: rewritten).

package/library/skills/motion-design/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: motion-design
+description: Use when adding, changing or reviewing UI animation or transitions: press and hover feedback, menus, dialogs, drawers, toasts, list changes, view transitions, marketing-page motion. Covers whether to animate at all, durations, easing, performance, interruption and reduced motion, CSS first, then the project's motion library.
+---
+
+# Motion design
+
+Motion should be felt, not watched. Good motion explains a change (where the menu came from, that the click registered, what was removed) and then gets out of the way. Generated UI tends to do the opposite: a fade-up on every block, hover lifts on every card, bounce easing, 400ms dropdowns.
+
+The project's motion tokens, existing transitions and installed animation library win over every value here. If the codebase already animates dialogs at 200ms with its own curve, new dialogs do the same.
+
+## Decide before you animate
+
+### 1. Should this animate at all?
+
+| How often people see it | Decision |
+|---|---|
+| 100+ times a day (keyboard shortcuts, command palette, typing, list navigation by keys) | No animation |
+| Tens of times a day (hover, tab switches, row selection) | Instant, or a 100 to 150ms colour or opacity change |
+| Occasionally (menus, dialogs, drawers, toasts, expanding sections) | Standard animation |
+| Rarely (first run, a completed setup, an empty state the first time) | May carry a little more character |
+
+Never animate keyboard-initiated actions. Product screens load into the task: no orchestrated page-load sequences.
+
+### 2. What is it for?
+
+Valid purposes: feedback (the press registered), state (open, selected, saved), spatial continuity (the toast leaves the way it came, the drawer slides from its edge), preventing a jarring jump (content appearing or disappearing), and on marketing pages, explaining how something works. "It looks nice" is not a purpose for something seen often.
+
+### 3. Easing
+
+- Entering or exiting: **ease-out**. Default curve `cubic-bezier(0.23, 1, 0.32, 1)`.
+- Moving or morphing on screen: **ease-in-out**, `cubic-bezier(0.77, 0, 0.175, 1)`.
+- Hover and colour changes: `ease`.
+- Constant motion (progress, marquee): `linear`.
+- Drawers and sheets: `cubic-bezier(0.32, 0.72, 0, 1)` reads like native mobile sheets.
+- Never `ease-in` for UI: it delays the first frame, exactly when the person is watching. No bounce or elastic curves by reflex.
+
+### 4. Duration
+
+| Element | Duration |
+|---|---|
+| Press feedback | 100 to 160ms |
+| Hover, colour | 100 to 150ms |
+| Tooltip, small popover | 125 to 200ms |
+| Dropdown, select, menu | 150 to 250ms |
+| Dialog, drawer, sheet | 200 to 300ms (large drawers up to 500ms) |
+| Layout or view transition | 250 to 400ms |
+| Authored moment on a marketing page | 500 to 800ms |
+
+UI motion stays under 300ms. Exits are faster and quieter than entrances (about 75% of the enter time, a small offset rather than the full distance).
+
+## Rules
+
+1. **Animate `transform` and `opacity`.** They skip layout and paint. Animate `width`, `height`, `top`, `left` or margins only with a technique built for it (FLIP, grid-template-rows `0fr` to `1fr`, View Transitions). `filter`, `clip-path` and shadows are fine on small, bounded elements.
+2. **Never `transition: all`.** Name the properties.
+3. **Interruptible by default.** Use CSS transitions (or springs) for anything the person can trigger again mid-way; they retarget. Keyframes restart from zero; keep them for one-shot sequences.
+4. **Nothing appears from nothing.** Enter from `scale(0.95)` to `scale(0.97)` with opacity 0, never `scale(0)`.
+5. **Origin-aware popovers.** Menus, popovers and tooltips scale from their trigger (`transform-origin` at the trigger side). Dialogs stay centred.
+6. **Stagger only real lists**, 30 to 80ms between items, total under about 300ms, and never block interaction while it plays.
+7. **Press feedback**: `scale(0.97)` on `:active` for buttons (not below 0.95).
+8. **Tooltips**: a short delay before the first one; once one is open, neighbours open instantly with no animation.
+9. **Hover motion only for fine pointers**: wrap it in `@media (hover: hover) and (pointer: fine)`.
+10. **Content is visible by default.** If a script fails or an observer never fires, nothing stays hidden. Scroll reveals start from an already-visible state or have a no-script fallback.
+11. **Reduced motion means fewer and gentler, not none.** Under `prefers-reduced-motion: reduce`, remove movement, scaling and parallax; keep short opacity and colour changes that confirm state. Stop decorative loops. Autoplaying motion over 5 seconds needs a pause control.
+12. **Motion is never the only signal.** Every animated state change also has a static cue (colour, icon, text).
+13. **`will-change` only to cure an observed first-frame stutter**, on the element and only during the animation.
+14. **No new dependency for an effect the stack can already express.** CSS transitions, `@starting-style`, the Web Animations API and View Transitions cover most UI needs.
+
+## Implement with what the project has
+
+In order: CSS transitions and keyframes; the Web Animations API for programmatic control; the project's existing library (Vue `<Transition>`, Svelte transitions, Angular animations, Motion for React, GSAP); View Transitions for continuity between states or routes. Recipes for each are in [references/recipes.md](references/recipes.md).
+
+## Marketing pages
+
+A page read once may carry one authored moment: a hero sequence, one interactive demo, a single scroll-linked reveal whose scroll relationship means something. One strong idea beats an identical fade-up on every section. Keep it under about 800ms, make it skippable by scrolling, give it a reduced-motion version, and keep the page complete without it.
+
+## Check
+
+- Play it at slow speed (DevTools Animations panel at 10%, or multiply durations by 5 temporarily). Look for two states overlapping in a crossfade, wrong origins, properties out of sync, a jump at the end.
+- Trigger it twice quickly and mid-way: it reverses smoothly, nothing sticks.
+- Toggle reduced motion (DevTools rendering panel, or Playwright `reducedMotion: 'reduce'`): state changes still read.
+- Throttle the CPU 4x: no dropped frames on the common path.
+- A screenshot taken mid-load shows no blank bands where a reveal did not fire.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| `transition: all 300ms` | `transition: transform 200ms var(--ease-out), opacity 200ms var(--ease-out)` |
+| `scale(0)` entrance | `scale(0.95)` with opacity 0 |
+| `ease-in` on a dropdown | ease-out, custom curve |
+| Popover scaling from its centre | `transform-origin` at the trigger |
+| Animation on a keyboard shortcut | Remove it |
+| 400ms dropdown | 150 to 250ms |
+| Keyframes on a toggle that can be re-triggered | A transition |
+| Hover scale that fires on tap | Gate with the hover and pointer media query |
+| Every section fades up on scroll | Remove; one authored moment at most, on marketing pages |
+| Exit as slow as the enter | Shorter, smaller exit |
+
+## Output in reviews
+
+A table with **Before**, **After** and **Why**, one row per issue, citing `file:line`.
+
+Related: `interface-polish`, `interface-design`, `accessibility`.
+
+Sources: adapted from emilkowalski/skills emil-design-eng (MIT, changed: framework-neutral, React and Motion specifics moved to examples, "initial response" step removed), jakubkrehel/make-interfaces-feel-better animations reference (MIT) and pbakaus/impeccable animate and operate references (Apache-2.0, changed: rewritten, ask steps removed).

package/library/skills/motion-design/references/recipes.md

@@ -0,0 +1,243 @@
+# Motion recipes
+
+Read this when implementing a specific transition. Use the project's existing motion tokens and library if it has them; these recipes are CSS first, then examples in common libraries. Do not add a library to use a recipe.
+
+## Tokens
+
+```css
+:root {
+  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
+  --duration-press: 150ms;
+  --duration-popover: 180ms;
+  --duration-dialog: 240ms;
+}
+```
+
+## Reduced motion pattern
+
+Define movement only for people who have not asked to reduce it; keep the opacity change for everyone.
+
+```css
+.toast { transition: opacity 200ms ease; }
+
+@media (prefers-reduced-motion: no-preference) {
+  .toast {
+    transition:
+      opacity 200ms var(--ease-out),
+      transform 200ms var(--ease-out);
+  }
+}
+```
+
+## Press feedback
+
+```css
+.button {
+  transition: transform var(--duration-press) var(--ease-out);
+}
+.button:active:not(:disabled) { transform: scale(0.97); }
+```
+
+## Popover or menu (native popover, no JavaScript)
+
+```css
+.menu[popover] {
+  transform-origin: top left;
+  opacity: 0;
+  transform: scale(0.97);
+  transition:
+    opacity var(--duration-popover) var(--ease-out),
+    transform var(--duration-popover) var(--ease-out),
+    overlay var(--duration-popover) allow-discrete,
+    display var(--duration-popover) allow-discrete;
+}
+.menu[popover]:popover-open { opacity: 1; transform: scale(1); }
+
+@starting-style {
+  .menu[popover]:popover-open { opacity: 0; transform: scale(0.97); }
+}
+```
+
+Browsers without `@starting-style` simply show the menu without animation. Set `transform-origin` to the side of the trigger. With a headless library, use the origin variable it exposes (for example `var(--radix-popover-content-transform-origin)` or `var(--transform-origin)`).
+
+## Dialog
+
+Same pattern on `dialog[open]`, centred origin, `--duration-dialog`, plus a backdrop fade:
+
+```css
+dialog::backdrop { background: rgb(0 0 0 / 0.4); transition: opacity var(--duration-dialog) ease; }
+```
+
+Exit about 75% of the enter duration.
+
+## Drawer or bottom sheet
+
+```css
+.sheet {
+  transform: translateY(100%);
+  transition: transform 300ms var(--ease-drawer);
+}
+.sheet[data-open="true"] { transform: translateY(0); }
+```
+
+Percent translations move by the element's own size, so they work at any height. Add `overscroll-behavior: contain` on the sheet's scroll area.
+
+## Expand and collapse without animating height
+
+```css
+.collapsible {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 250ms var(--ease-out);
+}
+.collapsible[data-open="true"] { grid-template-rows: 1fr; }
+.collapsible > .inner { overflow: hidden; }
+```
+
+## Toast
+
+Enter from the edge it lives on, leave the same way, a little faster:
+
+```css
+.toast { transform: translateY(0); opacity: 1; }
+.toast[data-state="entering"], .toast[data-state="leaving"] { transform: translateY(100%); opacity: 0; }
+.toast[data-state="leaving"] { transition-duration: 150ms; }
+```
+
+Pause auto-dismiss timers while the toast is hovered or the tab is hidden.
+
+## Icon swap (copy to copied, play to pause)
+
+Keep both icons in the DOM, one positioned over the other, and cross-fade:
+
+```css
+.icon-swap { position: relative; display: inline-grid; }
+.icon-swap > * {
+  grid-area: 1 / 1;
+  transition:
+    opacity 250ms cubic-bezier(0.2, 0, 0, 1),
+    transform 250ms cubic-bezier(0.2, 0, 0, 1),
+    filter 250ms cubic-bezier(0.2, 0, 0, 1);
+}
+.icon-swap > [data-hidden="true"] { opacity: 0; transform: scale(0.25); filter: blur(4px); }
+```
+
+## Skeleton
+
+A flat muted block at the final size. If the project pulses skeletons, use a slow opacity pulse (1.5 to 2s) and stop it under reduced motion. No shimmer gradient sweeping across the screen.
+
+## Web Animations API
+
+```js
+const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches
+element.animate(
+  reduce
+    ? [{ opacity: 0 }, { opacity: 1 }]
+    : [{ opacity: 0, transform: 'translateY(8px)' }, { opacity: 1, transform: 'none' }],
+  { duration: 200, easing: 'cubic-bezier(0.23, 1, 0.32, 1)', fill: 'backwards' },
+)
+```
+
+## View Transitions
+
+```js
+function update(change) {
+  if (!document.startViewTransition) return change()
+  document.startViewTransition(change)
+}
+```
+
+```css
+::view-transition-old(root),
+::view-transition-new(root) { animation-duration: 200ms; }
+
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) { animation: none; }
+}
+```
+
+Use them when continuity between two states is the point (a card expanding into its detail), not on every route change. Many routers (Astro, Nuxt, SvelteKit, Next.js) have their own switch for this; use it.
+
+## Vue
+
+```vue
+<template>
+  <Transition name="pop">
+    <div v-if="open" class="menu">...</div>
+  </Transition>
+</template>
+
+<style>
+.pop-enter-active { transition: opacity 180ms var(--ease-out), transform 180ms var(--ease-out); }
+.pop-leave-active { transition: opacity 120ms var(--ease-out), transform 120ms var(--ease-out); }
+.pop-enter-from,
+.pop-leave-to { opacity: 0; transform: scale(0.97); }
+</style>
+```
+
+For lists, `<TransitionGroup>` with a `.list-move { transition: transform 200ms var(--ease-out); }` class animates reordering.
+
+## Svelte
+
+```svelte
+<script>
+  import { fly } from 'svelte/transition'
+  import { cubicOut } from 'svelte/easing'
+</script>
+
+{#if open}
+  <div class="menu" transition:fly={{ y: -4, duration: 180, easing: cubicOut }}>...</div>
+{/if}
+```
+
+## Motion for React
+
+Only if `motion` or `framer-motion` is already installed; import from whichever the project uses.
+
+```jsx
+import { AnimatePresence, motion } from 'motion/react'
+
+<AnimatePresence initial={false}>
+  {open && (
+    <motion.div
+      key="panel"
+      initial={{ opacity: 0, transform: 'scale(0.97)' }}
+      animate={{ opacity: 1, transform: 'scale(1)' }}
+      exit={{ opacity: 0, transform: 'scale(0.97)', transition: { duration: 0.12 } }}
+      transition={{ duration: 0.18, ease: [0.23, 1, 0.32, 1] }}
+    />
+  )}
+</AnimatePresence>
+```
+
+`initial={false}` stops elements already present on first render from animating in. Full `transform` strings stay on the compositor when the main thread is busy; the `x` and `y` shorthands do not. For gestures and drags, springs (`{ type: 'spring', duration: 0.3, bounce: 0 }`) keep their velocity when interrupted; keep bounce at 0 in product UI. `useReducedMotion()` returns the user's preference.
+
+## GSAP
+
+Only if GSAP is already installed.
+
+```js
+import { gsap } from 'gsap'
+
+const mm = gsap.matchMedia()
+mm.add('(prefers-reduced-motion: no-preference)', () => {
+  gsap.from('.step', { opacity: 0, y: 12, duration: 0.4, ease: 'power3.out', stagger: 0.06 })
+})
+```
+
+`gsap.matchMedia()` reverts the animation when the media query stops matching. Keep scroll-triggered work for marketing pages, and give it a version that leaves content visible.
+
+## Drag and gestures
+
+- Capture the pointer once dragging starts (`setPointerCapture`) so the drag continues outside the element.
+- Ignore extra touch points after the drag begins.
+- Dismiss on velocity as well as distance (a quick flick is enough).
+- Past a boundary, apply friction instead of a hard stop.
+- On `pointercancel`, `lostpointercapture` and window `blur`, clear the dragging state so the next drag works.
+- Offer a click or keyboard alternative for every gesture.
+
+Sources: adapted from emilkowalski/skills emil-design-eng (MIT, changed: examples made framework-neutral, Vue, Svelte and GSAP examples added), jakubkrehel/make-interfaces-feel-better animations reference (MIT, changed: icon swap duration aligned to 250ms, CSS grid variant) and pbakaus/impeccable animate and harden references (Apache-2.0, changed: rewritten).