@tamsensedev/runner 0.0.0-stage → 0.2.1

package/library/skills/interface-design/references/writing.md

@@ -0,0 +1,52 @@
+# Writing interface text
+
+Read this when you write or change any visible text: labels, buttons, headings, empty states, errors, toasts, helper text. The product's existing voice, terminology and capitalization win; match the strings around yours.
+
+Words are part of the design, not decoration on it. Each string does one job: helping the person understand where they are and what to do.
+
+## Defaults
+
+- **Sentence case** for headings, buttons, tabs, menu items, labels and table headers ("Invite members", not "Invite Members"), unless the product already uses Title Case.
+- **Name things by what people understand**, not by how the system is built: "Notifications", not "Webhook config".
+- **Active voice and plain verbs.** A button says exactly what happens: "Save changes", "Delete project", not "Submit", "OK" or "Continue" when a specific verb exists.
+- **One name per action through the flow.** The button "Publish" leads to the toast "Published". Do not switch between "remove", "delete" and "archive" for the same thing.
+- **Numerals for counts** ("8 deployments"), real plurals ("1 member", "2 members"; use the project's i18n or `Intl.PluralRules`), and units with a non-breaking space ("10 MB").
+- **Second person**, no first person from the product ("Your projects", not "My projects" or "We could not").
+- **Short.** Cut words that repeat the heading. If the title already explains the state, the line under it adds new information or goes.
+
+## By situation
+
+| Situation | Write | Avoid |
+|---|---|---|
+| Button | Verb plus object: "Create invoice" | "Submit", "Click here", "Get started" when a precise verb exists |
+| Destructive confirmation | Name the object and consequence: "Delete 'Q3 launch'? Its 12 tasks are deleted too." Buttons: "Delete project" / "Cancel" | "Are you sure?" with "Yes" / "No" |
+| Error | What failed, why if known, how to recover: "Couldn't save the invoice. The connection dropped. Try again." | "Something went wrong", raw codes or stack traces, apologies, jokes |
+| Validation | Next to the field, says what is needed: "Enter a date after the start date" | Blaming ("Invalid input"), clearing what the person typed |
+| Empty, first use | Why it is empty and the first action: "No invoices yet. Create your first invoice to bill a client." | "Nothing here", illustrations with no action |
+| Empty, no results | Say the filter caused it and offer to clear it | The same text as first use |
+| Loading | Name the operation, end with an ellipsis: "Loading invoices…" | Invented progress percentages |
+| Success | Brief, past tense: "Invoice sent" | Celebration for routine actions |
+| Disabled control | Say why nearby or in a tooltip: "Add a payment method to upgrade" | A grey button with no reason |
+| Helper text | Answers the question the label raises: format, limits, why it is asked | Restating the label |
+| Placeholder | An example value, never the label | Placeholder as the only label |
+
+## Things that read as generated
+
+Remove these unless the product's own voice uses them:
+
+- Genre verbs and adjectives: unlock, unleash, supercharge, elevate, empower, streamline, seamless, effortless, robust, cutting-edge, next-generation, world-class, all-in-one, blazing fast.
+- The correction pattern: "Not just X, it's Y." Tricolon headlines ("Fast. Simple. Secure.").
+- Performative section labels: "Field notes", "Our philosophy", "Quietly trusted by". A heading can just say "Pricing".
+- Furniture text: version stamps, coordinates, "Scroll to explore", "Available for work" status dots, strings joined by middle dots.
+- Long dashes as a habit; use a full stop or a comma.
+- Captions that narrate the design ("A clean, minimal layout for…").
+- Three items everywhere because three feels complete. Use the number the content has.
+- Invented proof: customer counts, ratings, quotes, logos, benchmarks. Never write these unless the task supplies them.
+
+## Micro-typography
+
+- A real ellipsis (…) and curly quotes (“ ” ’) where the project's strings use them.
+- No centred paragraphs over three lines; no justified text.
+- Write complete translatable messages, not fragments glued together, so translators can reorder variables.
+
+Sources: adapted from the writing section of the frontend-design skill in anthropics/claude-plugins-official (Apache-2.0, changed: condensed into defaults and a table), pbakaus/impeccable clarify reference (Apache-2.0, changed: rewritten, "ask before changing" steps removed), Leonxlnx/taste-skill copy reference (MIT) and vercel-labs/web-interface-guidelines (MIT).

package/library/skills/interface-polish/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: interface-polish
+description: Use when finishing or refining UI so it feels right: alignment, radii, borders and shadows, icons, type details, hover, focus and press states, hit areas, overflow with long or missing data. Also for stress-testing a component with realistic worst-case data, or when a task says the UI "feels off" or needs polish.
+---
+
+# Interface polish
+
+Polish is a hundred small details that compound: concentric corners, icons that sit optically centred, numbers that do not jitter, a name that wraps instead of pushing the menu off the row. It is refinement inside the existing design, never a redesign in disguise. If the concept itself is wrong, say so in the report instead of quietly replacing it.
+
+Express every fix in the project's own styling system (Tailwind in a Tailwind project, CSS modules, plain CSS, the established CSS-in-JS) and with its tokens. Never introduce a second styling system or a new dependency for a polish fix. The project's design system wins over every value below; the values are defaults where it has none.
+
+## Process
+
+### 1. Establish the system and scope
+
+Read the design sources (see `interface-design` step 1) and the components on the path you are polishing. Bound the scope: the screens and components the task touches.
+
+For each inconsistency, classify it before fixing:
+
+- **Missing token**: the system needs a reusable value it does not have. Add it in the token layer, once.
+- **One-off implementation**: a shared component or pattern already exists. Replace the copy with it.
+- **Conceptual mismatch**: this flow or hierarchy differs from comparable screens. Align it with its siblings.
+- **Local defect**: simply incomplete or inconsistent. Fix it in place.
+
+Fix at the narrowest correct level. Do not create a shared abstraction for a single exception.
+
+### 2. Gather evidence
+
+Render the screens at desktop and phone widths and walk every state (procedure in `design-review`): hover, focus, active, disabled, loading, empty, error, long content. What looks slightly wrong in a screenshot is usually one of the rules below.
+
+### 3. Triage and fix in this order
+
+1. Broken or blocked tasks, misleading state, unreachable actions, inaccessible paths.
+2. Missing states: loading, empty, error, success, disabled, permission.
+3. Hierarchy, layout and responsive problems, drift from the design system.
+4. Visual and motion inconsistencies (the rules below).
+5. Code cleanup: dead styles, duplicated values, debug output.
+
+Do not perfect one corner while the rest of the path stays below the same bar.
+
+### 4. Stress-test with worst-case data
+
+Demo data is chosen, usually without anyone noticing, to make the design look good. Feed the UI the realistic worst case: long and short names, unbreakable emails, missing optional fields, counts of 0, 1 and 1,284, translated labels, emoji, huge lists. Follow [references/worst-case-data.md](references/worst-case-data.md). Change the data at the boundary it enters (fixture, mock, API response), never by editing markup to provoke a break.
+
+### 5. Verify
+
+Walk the path again with mouse, keyboard and touch-size viewports. Re-take screenshots. Check the diff for accidental churn and leftover debug code.
+
+## The rules
+
+Code examples for each are in [references/detail-rules.md](references/detail-rules.md).
+
+**Surfaces**
+1. **Concentric radius.** Outer radius = inner radius + padding. Equal radii on nested surfaces are the most common reason a card "feels off". Over about 24px of padding, treat layers as separate.
+2. **Optical alignment.** When geometric centring looks wrong, align optically: the icon side of a button gets about 2px less padding than the text side; a play triangle shifts about 2px right; fix lopsided icons in the SVG itself when you can.
+3. **Elevation follows the product's depth strategy.** A border or a shadow, not both. A layered transparent shadow (ring plus soft depth) can replace a border on cards and buttons that sit on varied backgrounds; keep real borders for dividers, table rules and input outlines.
+4. **Image outlines.** A 1px inset outline in pure black at 10% opacity on light, pure white at 10% on dark. Never a tinted near-black, which reads as dirt on the edge.
+5. **Hit areas.** 44 x 44px for touch, at least 40 x 40 in dense desktop UI. Extend small controls with padding or a pseudo-element. Two hit areas never overlap.
+
+**Type**
+6. **Tabular figures** on numbers that update or line up: counters, prices, timers, table columns. Check the font actually has them.
+7. **Text wrapping.** `text-wrap: balance` on headings and short centred text; `text-wrap: pretty` on paragraphs and captions; neither on long text or code.
+8. **Font smoothing.** `-webkit-font-smoothing: antialiased` once on the root, if the project does not set it.
+9. **Overflow.** Flex and grid children holding text get `min-width: 0`; long unbroken strings get `overflow-wrap: anywhere`; fixed-size items (avatars, icons, badges, trailing actions) get `flex-shrink: 0`.
+
+**Icons**
+10. **Stroke matches the text beside it**: 1.5px next to regular text, 2px next to semibold. One icon set and one stroke weight per surface.
+11. **One SVG, recoloured by state** with `currentColor`; outline by default, filled for the active state.
+12. **Design at render size**: use the set's native sizes (16, 20, 24), check at the smallest size used.
+
+**Interaction**
+13. **Every interactive element has hover, focus-visible, active and disabled states.** Hover, active and focus are more prominent than rest. Gate hover effects with `@media (hover: hover) and (pointer: fine)` when they move or scale things.
+14. **Press feedback**: `scale(0.97)` on `:active` for buttons and pressable cards (never below 0.95), as an interruptible transition. Skip it where motion would distract (large surfaces, dense toolbars).
+15. **Never `transition: all`.** Name the properties. Animate `transform` and `opacity` where possible. Timings in `motion-design`.
+16. **Focus is visible** on keyboard focus (`:focus-visible`), never removed without a replacement, and not hidden under sticky headers.
+17. **Overlays escape their container**: a dropdown inside an `overflow: hidden` parent gets clipped; use `<dialog>`, the popover API, `position: fixed` or the project's portal.
+
+**Content**
+18. **Truncate, wrap or clamp per field**, never globally (rules in the worst-case reference). Never truncate numbers, amounts or dates.
+19. **Images** have explicit dimensions or `aspect-ratio`, and `object-fit: cover` where the source ratio varies.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Same radius on a card and the button inside it | Outer = inner + padding |
+| Icon looks off-centre in a button | Less padding on the icon side, or fix the SVG |
+| 1px border plus a wide soft shadow on resting cards | One or the other, per the product's depth strategy |
+| Numbers shift as they update | `tabular-nums` |
+| Avatar squashed into an oval in a long row | `flex-shrink: 0` on the avatar |
+| Email pushes the row menu off-screen | `min-width: 0` on the text column, `overflow-wrap: anywhere` on the email |
+| "1 members" | Plural rules from the project's i18n or `Intl.PluralRules` |
+| `transition: all 300ms` | Named properties, under 300ms, ease-out |
+| Hairline icon next to bold text | Match stroke to the text weight |
+| Polish fix written in a second styling system | Rewrite it in the project's system |
+
+## Output
+
+In a code step: fix, re-check, and summarise the main fixes in the report. In a review (or when asked only to assess), return a table per category with **Severity** (high: inaccessible, misleading, unreadable or repeatedly disruptive; medium: noticeable usability or consistency problem; low: isolated polish), **Location** (`file:line` or screen and component), **Before**, **After** and **Why**. Merge a repeated issue into one row with all locations. List what you inspected per category, and label anything you did not verify as "Not verified".
+
+Related: `interface-design`, `motion-design`, `web-interface-guidelines`, `design-review`, `accessibility`.
+
+Sources: adapted from jakubkrehel/make-interfaces-feel-better (MIT, changed: React and Motion specifics made optional, values reconciled with other sources), emilkowalski/skills break-ui (MIT, changed: no stop-and-ask step, no shipped toggle), Dammyjay93/interface-design (MIT) and pbakaus/impeccable polish and harden references (Apache-2.0, changed: rewritten, critique storage and ask steps removed).

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).