@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/ui-demo-recording/references/playwright-recording.md

@@ -0,0 +1,63 @@
+# Playwright recording script
+
+Video is written when the browser context closes. Without an explicit size, Playwright scales the viewport down to fit in 800x800, so always set both `viewport` and `recordVideo.size`.
+
+```js
+// demos/onboarding/record.mjs
+import { chromium } from 'playwright';
+import { cursorOverlay } from './cursor-overlay.mjs';
+
+const W = 1920, H = 1080;
+const BASE = process.env.DEMO_URL ?? 'http://localhost:3000';
+
+const browser = await chromium.launch();
+const context = await browser.newContext({
+  viewport: { width: W, height: H },
+  deviceScaleFactor: 1,
+  colorScheme: 'light',
+  locale: 'en-GB',
+  timezoneId: 'Europe/London',
+  storageState: 'demos/.auth/demo-user.json',
+  recordVideo: { dir: 'demos/onboarding/raw', size: { width: W, height: H } },
+});
+await context.addInitScript(cursorOverlay);
+await context.route(/(google-analytics|segment|intercom|hotjar)/, (r) => r.abort());
+
+const page = await context.newPage();
+await page.clock.setFixedTime(new Date('2026-03-02T10:00:00Z'));
+
+async function clickLike(locator) {
+  await locator.waitFor({ state: 'visible' });
+  const box = await locator.boundingBox();
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 25 });
+  await page.waitForTimeout(200);
+  await locator.click();
+}
+const hold = (ms = 1200) => page.waitForTimeout(ms);
+const caption = (text) => page.evaluate((t) => window.__demoCaption?.(t), text);
+
+// Scene 1
+await page.goto(`${BASE}/projects`);
+await caption('Create a project in seconds');
+await hold();
+
+// Scene 2
+await clickLike(page.getByRole('button', { name: 'New project' }));
+await page.getByLabel('Project name').pressSequentially('Harbour Bridge refit', { delay: 60 });
+await hold(600);
+await clickLike(page.getByRole('button', { name: 'Create' }));
+await page.getByRole('heading', { name: 'Harbour Bridge refit' }).waitFor();
+await caption('');
+await hold(1500);
+
+const video = page.video();
+await context.close();            // finishes the file
+await video.saveAs('demos/onboarding/raw/take.webm');
+await browser.close();
+```
+
+Notes:
+- `page.clock` exists in Playwright 1.45 and later; on older versions, override `Date` with an init script.
+- With Playwright Test, set `use: { video: { mode: 'on', size: { width: 1920, height: 1080 } }, viewport: { width: 1920, height: 1080 } }` in a separate `demo` project. Recent versions also accept `video.show.actions` (outline and title for each action) and `video.show.test`; these are debugging annotations, usually unwanted in a marketing demo, and missing in older versions.
+- Chromium gives the most consistent recordings; record in headless mode on the same machine type each time.
+- Record a fresh take for each language or theme instead of editing one video.

package/skills/ui-demo-recording/references/post-processing.md

@@ -0,0 +1,57 @@
+# Post-processing a Playwright take
+
+Playwright writes VP8 WebM. Probe it first: `ffprobe -v error -show_entries format=duration:stream=width,height,r_frame_rate -of json take.webm`.
+
+## Trim and convert to web MP4
+
+```bash
+ffmpeg -ss 0.6 -i take.webm -t 40.4 -vf "fps=30,format=yuv420p" -c:v libx264 -crf 18 -preset slow -movflags +faststart -an demo.mp4
+```
+
+`-ss` before `-i` with re-encode is frame-accurate; give the output length with `-t` (seconds kept after the start point), since `-to` combined with input seeking is easy to misread. Drop `-an` if you add audio below.
+
+## Find dead frames to trim
+
+```bash
+ffmpeg -i take.webm -vf "freezedetect=n=0.001:d=2" -an -f null - 2>&1 | grep freeze_
+```
+
+## Speed up a dull stretch (10 s to 18 s at 2x)
+
+```bash
+ffmpeg -i demo.mp4 -filter_complex "[0:v]trim=start=0:end=10,setpts=PTS-STARTPTS[a];[0:v]trim=start=10:end=18,setpts=(PTS-STARTPTS)/2[b];[0:v]trim=start=18,setpts=PTS-STARTPTS[c];[a][b][c]concat=n=3:v=1:a=0[v]" -map "[v]" -c:v libx264 -crf 18 -pix_fmt yuv420p demo_fast.mp4
+```
+
+## Fade in and out
+
+```bash
+ffmpeg -i demo.mp4 -vf "fade=t=in:st=0:d=0.4,fade=t=out:st=40.4:d=0.6" -c:v libx264 -crf 18 -pix_fmt yuv420p demo_fade.mp4
+```
+
+## Captions
+
+```bash
+# soft captions (keeps them accessible and editable)
+ffmpeg -i demo.mp4 -i demo.srt -map 0 -map 1 -c copy -c:s mov_text -metadata:s:s:0 language=eng demo_cc.mp4
+# burned in
+ffmpeg -i demo.mp4 -vf "subtitles=demo.srt:force_style='FontSize=22,Outline=1'" -c:v libx264 -crf 18 demo_burned.mp4
+```
+
+## Music bed (licensed track supplied by the user)
+
+```bash
+ffmpeg -i demo.mp4 -i bed.mp3 -filter_complex "[1:a]volume=0.25,afade=t=out:st=38:d=3[m]" -map 0:v -map "[m]" -shortest -c:v copy -c:a aac -b:a 160k demo_music.mp4
+```
+
+## GIF (two-pass palette)
+
+```bash
+ffmpeg -i demo.mp4 -vf "fps=12,scale=800:-1:flags=lanczos,palettegen=stats_mode=diff" palette.png
+ffmpeg -i demo.mp4 -i palette.png -lavfi "fps=12,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5" demo.gif
+```
+
+## Final check
+
+```bash
+ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height,pix_fmt -of compact demo.mp4
+```

package/skills/ui-design-polish/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ui-design-polish
+description: Visual design direction and design-engineering finish for product UI - choosing a deliberate aesthetic instead of template defaults, then applying a spacing scale, a modular type scale, semantic colour tokens, hover, focus, active and disabled states, optical alignment, and real empty, loading and error states; also inventories an existing codebase's ad-hoc colours, sizes and components into a design-system audit. Use when a screen looks generic, unfinished or inconsistent, someone asks to make the UI look better or more professional, or wants the de facto design system extracted from scattered styles.
+license: MIT
+compatibility: Any Agent Skills host. Works with plain CSS, CSS Modules, Tailwind or CSS-in-JS. Running the app and a browser for screenshots helps but is optional.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# UI design polish
+
+Make an interface look intended. Two jobs: pick a visual direction and hold it, then sweat the details that separate "works" from "finished". Most "it looks off" complaints are inconsistent spacing, too many font sizes, unmanaged colour and missing states, not a lack of decoration.
+
+Neighbours: `css-architecture` decides how styles are organised (layers, naming, theming plumbing); `web-accessibility` owns WCAG conformance; `ui-motion` owns animation. This skill decides what things look like.
+
+## 0. Before you start
+
+1. Ask, or infer from the product, three things: **who uses it**, **the tone** (calm and dense for a tool, warm for consumer, editorial for content), and **constraints** (existing brand, component library, dark mode). If there is a brand guide or design file, it wins; **stop and ask** before overriding it.
+2. Find the current styling approach and any token file (`tokens.css`, `theme.ts`, `tailwind.config.*` `theme.extend`, CSS custom properties on `:root`). Polish goes through tokens, not one-off values.
+3. Look at the real screens. Run the app if you can and capture the screens you will change, at mobile and desktop widths, before touching anything.
+
+## 1. Choose a direction (new UI or redesign)
+
+Write the direction down in 4-6 lines before coding, for example:
+
+```
+Direction: quiet utility. Neutral warm greys, one accent (teal 600) used only for primary actions and focus.
+Type: one sans (system stack or Inter), 4 sizes; weight carries hierarchy, not colour.
+Density: compact, 4px base grid, 8/12/16/24/32 spacing.
+Shape: 6px radius on controls, 10px on cards; borders over shadows.
+Signature: tabular numbers and a thin top rule on section headers.
+```
+
+Rules:
+
+- One accent colour, used sparingly. If everything is highlighted, nothing is.
+- Pick one signature detail and repeat it; do not add five.
+- Avoid the template look: centred hero with gradient blob, three equal cards with icons, purple-to-blue gradients, everything rounded-2xl with a drop shadow. Use them only if the brief asks.
+- Restraint beats decoration. Remove before adding.
+
+## 2. Foundations as tokens
+
+Set these up (or tighten the existing ones). Value tables and naming in `references/tokens.md`.
+
+- **Spacing**: a scale on a 4px or 8px base. Every margin, padding and gap uses it. Related things sit closer together than unrelated things.
+- **Type**: 4-6 sizes from a ratio (1.2-1.25 for dense UI, up to 1.333 for marketing). Body 16px on the web, line-height 1.4-1.6 for body and 1.1-1.25 for headings, measure 60-75 characters.
+- **Colour**: raw palette (`--gray-50`...`--gray-950`, one accent ramp, red/amber/green for status) mapped to **semantic** tokens (`--color-bg`, `--color-surface`, `--color-text`, `--color-text-muted`, `--color-border`, `--color-accent`, `--color-danger`). Components only use semantic tokens. Dark mode redefines the semantic layer.
+- **Radius, border, shadow, z-index**: 2-3 values each.
+
+Check text contrast against WCAG AA (4.5:1 body, 3:1 large text and UI component boundaries) as you choose colours.
+
+## 3. Interactive states
+
+Every control needs all of these, designed, not browser defaults left by accident:
+
+| State | Rule |
+|---|---|
+| Default | Clear affordance: a button looks pressable, a link looks like a link |
+| Hover | Subtle shift (background one step on the ramp); only on `@media (hover: hover)` devices |
+| Focus-visible | A visible ring (`:focus-visible`, 2px outline with offset, accent or high-contrast colour). Never `outline: none` without a replacement |
+| Active / pressed | Slightly darker or inset; immediate |
+| Disabled | Reduced contrast plus `cursor: not-allowed`; still readable; explain why nearby if it is not obvious |
+| Loading | Keep the button's width; spinner or label change; block double submit |
+| Selected / current | Distinct from hover (`aria-current`, `aria-selected` styled) |
+| Invalid | Border and message in danger colour plus an icon or text, never colour alone |
+
+## 4. Screen states
+
+For each data-driven view, design: **loading** (skeleton matching the final layout, not a page-centre spinner, for waits over ~300ms), **empty** (what this is, why it is empty, the one action that fills it), **error** (what happened in plain words, what to do, a retry), **partial** (some items failed), and **overflow** (long names, 0 / 1 / 1,000 items, missing images). Write the copy too.
+
+## 5. Detail pass
+
+Go through `references/detail-checklist.md` on each changed screen. The highest-yield items:
+
+- Align to a grid; left edges line up across sections.
+- Optical alignment: icons next to text are centred on the text's x-height or cap height, not the box; play icons nudge right; round shapes overshoot squares slightly.
+- Tabular numbers (`font-variant-numeric: tabular-nums`) in tables, prices and timers.
+- Consistent icon set, size and stroke weight.
+- No orphaned single words in headings where `text-wrap: balance` can fix it.
+- Hit targets at least 24x24 CSS px (44x44 on touch-first screens).
+
+## 6. Design-system audit (existing codebase)
+
+When asked to extract or audit the design system:
+
+1. Search the styles for raw values: hex/rgb/hsl colours, `px`/`rem` font sizes, spacing values, radii, shadows, z-indexes, breakpoints. Count each distinct value and where it is used.
+2. Cluster near-duplicates (`#1f2937` vs `#1e293b`, `14px` vs `0.875rem` vs `13.5px`).
+3. Propose the token set: the clusters that survive, with a mapping from each old value to its token.
+4. Inventory components: list every button, input, card and modal variant found, with file paths, and mark duplicates.
+5. Report with the format below. **Stop and ask** before a mass find-and-replace; do it per component or per page so diffs stay reviewable.
+
+## Never
+
+- Never introduce a new colour, size or spacing value that is not a token.
+- Never remove focus styles, or rely on colour alone for meaning.
+- Never restyle a brand's logo, colours or fonts without the owner's approval.
+- Never ship a visual change you have not looked at in a rendered page at mobile and desktop widths, in light and dark if both exist.
+
+## Report back
+
+```
+## UI polish: <screen or scope>
+Direction: <the 4-6 line direction, or "kept existing">
+Tokens added/changed: <list>
+Changes: <file: what changed and why, one line each>
+States covered: <loading / empty / error / hover / focus / disabled per component>
+Before/after: <screenshot paths, or "not captured">
+Audit (if run): <N colours -> M tokens, N font sizes -> M, duplicate components found>
+Left for later: <items and why>
+```

package/skills/ui-design-polish/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Our settings page works but looks amateur, tighten the spacing, type and colours so it feels professional",
+    "This dashboard looks like every other AI-generated template, give it a distinct visual direction",
+    "Go through the codebase and tell me how many different greys, font sizes and button styles we actually use, then propose a token set",
+    "The projects list has no empty state, loading state or error state, design all three",
+    "Polish the buttons: hover, pressed, disabled and loading states all look like browser defaults",
+    "The icons and labels in the sidebar look slightly misaligned, fix the optical alignment and spacing"
+  ],
+  "should_not_trigger": [
+    "Introduce cascade layers so the vendor CSS stops overriding our component styles",
+    "Audit the signup form against WCAG 2.2 AA and fix the screen reader problems",
+    "Add a spring animation when the modal opens and a fade when it closes",
+    "Write a brand voice guide for our marketing emails",
+    "Our homepage LCP is 4 seconds, make it load faster",
+    "Build a slide deck for Friday's product review"
+  ]
+}

package/skills/ui-design-polish/references/detail-checklist.md

@@ -0,0 +1,45 @@
+# Detail checklist
+
+Run per changed screen. Tick what passes, fix or list what does not.
+
+## Layout and spacing
+- [ ] Every gap, margin and padding is on the spacing scale.
+- [ ] Proximity groups related items; space between groups is larger than within.
+- [ ] Left edges align across header, content and footer.
+- [ ] Content width is capped for reading (about 65ch); wide tables scroll inside their container, not the page.
+- [ ] Nothing touches the viewport edge at 320px width; no horizontal page scroll.
+
+## Typography
+- [ ] No more than the scale's sizes; no stray 13px or 15px.
+- [ ] Hierarchy is readable with colour removed (size and weight carry it).
+- [ ] Line length and line height suit the text size.
+- [ ] Headings use `text-wrap: balance`; paragraphs may use `text-wrap: pretty`.
+- [ ] Numbers in tables, prices and counters use `tabular-nums`; right-aligned in numeric columns.
+- [ ] Truncation has a full-text fallback (tooltip, title or expand) and does not cut mid-character.
+
+## Colour
+- [ ] Only semantic tokens in components.
+- [ ] Accent is used for the primary action and focus, not decoration.
+- [ ] Text contrast meets 4.5:1 (body) and 3:1 (large text, control borders, icons that carry meaning).
+- [ ] Status is never shown by colour alone.
+
+## Alignment details
+- [ ] Icons are optically centred with their label (adjust by 1px when the glyph box misleads).
+- [ ] Icon size matches text size (16px icon with 14-16px text, 20px with 18-20px).
+- [ ] Inputs, buttons and selects in the same row share a height.
+- [ ] Nested radii are concentric (inner = outer - padding).
+- [ ] Borders are 1px and the same colour token; no double borders where cards meet.
+
+## States
+- [ ] Hover, focus-visible, active, disabled, loading, selected and invalid exist for each control.
+- [ ] Loading skeleton matches the final layout; no layout shift when data arrives.
+- [ ] Empty state explains and offers the next action.
+- [ ] Error state says what happened and how to recover, with retry.
+- [ ] Long, short, zero, one and many items all render well.
+
+## Polish
+- [ ] Images have fixed aspect ratios (`aspect-ratio`) and a placeholder background.
+- [ ] Cursor is `pointer` only on clickable elements.
+- [ ] Scrollbars and overflow do not shift the layout (`scrollbar-gutter: stable` where needed).
+- [ ] Selection colour and caret colour suit the theme (`::selection`, `caret-color`), when the direction calls for it.
+- [ ] Favicon, page title and social preview exist for public pages.

package/skills/ui-design-polish/references/tokens.md

@@ -0,0 +1,68 @@
+# Token starting points
+
+Adjust to the direction; these are defaults, not rules.
+
+## Spacing (4px base)
+
+| Token | px | Typical use |
+|---|---|---|
+| `--space-1` | 4 | icon-to-label gap |
+| `--space-2` | 8 | inside compact controls, tight stacks |
+| `--space-3` | 12 | control padding, list item gap |
+| `--space-4` | 16 | card padding (dense), form field gap |
+| `--space-6` | 24 | card padding, group gap |
+| `--space-8` | 32 | section gap |
+| `--space-12` | 48 | page section gap |
+| `--space-16` | 64 | hero / marketing sections |
+
+Tailwind's default spacing scale is already 0.25rem steps; use it rather than arbitrary `p-[13px]` values.
+
+## Type scale (ratio 1.25, base 16px)
+
+| Token | rem | px | Use |
+|---|---|---|---|
+| `--text-xs` | 0.75 | 12 | captions, badges (avoid for body) |
+| `--text-sm` | 0.875 | 14 | secondary text, dense tables |
+| `--text-base` | 1 | 16 | body |
+| `--text-lg` | 1.25 | 20 | card titles |
+| `--text-xl` | 1.563 | 25 | page titles |
+| `--text-2xl` | 1.953 | 31 | hero / display |
+
+Use `rem` so user font-size settings apply. For fluid headings, `clamp(1.5rem, 1rem + 2vw, 2.5rem)`; keep body text fixed.
+
+Weights: 400 body, 500-600 labels and buttons, 600-700 headings. Two or three weights per family.
+
+## Colour: palette to semantic layer
+
+```css
+:root {
+  /* palette */
+  --gray-50: #f8f8f7; --gray-100: #efeeec; --gray-200: #dddbd7; --gray-500: #79756e;
+  --gray-700: #45423d; --gray-900: #1d1c1a;
+  --teal-600: #0d7c74; --teal-700: #0a645e;
+  --red-600: #c4321f; --amber-600: #b26b00; --green-600: #2f7d32;
+
+  /* semantic */
+  --color-bg: var(--gray-50);
+  --color-surface: #fff;
+  --color-text: var(--gray-900);
+  --color-text-muted: var(--gray-700);
+  --color-border: var(--gray-200);
+  --color-accent: var(--teal-600);
+  --color-accent-hover: var(--teal-700);
+  --color-danger: var(--red-600);
+}
+@media (prefers-color-scheme: dark) {
+  :root { --color-bg: var(--gray-900); --color-surface: #262522; --color-text: var(--gray-50); /* ... */ }
+}
+```
+
+These hex values are illustrative; check each text/background pair with a contrast checker before use. `oklch()` makes even lightness steps easier to build when the project's browser targets support it.
+
+Dark mode is not inverted light mode: lower the surface contrast, desaturate the accent slightly, and use lighter surfaces (not shadows) for elevation.
+
+## Radius, shadow, z-index
+
+- Radius: `--radius-sm` 4px (inputs, tags), `--radius-md` 8px (buttons, cards), `--radius-full` 9999px (pills, avatars). Nested radius = outer radius minus padding.
+- Shadow: `--shadow-sm` for raised controls, `--shadow-lg` for popovers and dialogs only.
+- Z-index: named layers (`--z-dropdown: 10; --z-sticky: 20; --z-overlay: 30; --z-modal: 40; --z-toast: 50`), never `9999`.

package/skills/ui-flow-audit/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: ui-flow-audit
+description: Static trace of every user-facing control in a frontend, following each click, toggle or submit through its event handler, state setters, effects, store actions, network calls and their responses to the final rendered state, to find interactions that each work alone but cancel each other, race, double-fire or leave the screen in the wrong state, reported flow by flow. Use when a feature behaves correctly in isolation yet breaks when actions are combined or repeated, a toggle snaps back, a filter or form resets unexpectedly, or someone wants an audit of how the UI's state changes fit together before a release.
+license: MIT
+compatibility: Any Agent Skills host. Framework-neutral (React, Vue, Svelte, Angular, vanilla); reading code is enough, running the app and its tests confirms findings.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# UI flow audit
+
+Bugs in interactive UIs often live between handlers, not inside them: a click sets state, an effect reacts and resets it, a response from an earlier request lands last and overwrites the newer one. Each piece passes its unit test. This audit traces the whole chain for each control and checks what the user finally sees.
+
+The audit does not change source files. It may run the app or tests to confirm a finding, with the user's permission. It produces a report; fixing is a separate step the user approves. Neighbours: `browser-qa` clicks through a running app; `react-reviewer` reviews a diff; `react-patterns` says how to structure state. This skill maps cause and effect across a whole screen or feature.
+
+## 0. Scope
+
+1. Agree the scope with the user: one screen, one feature, or a list of routes. A whole app at once gives a shallow report; **ask** to narrow it if there are more than ~30 controls.
+2. Identify the framework and the state tools in use (component state, context, Redux/Zustand/Pinia/NgRx stores, a query cache such as TanStack Query or SWR, URL/search params, form libraries, local storage).
+3. Note the expected behaviour for each flow. If there is a spec, PRD or test describing it, read it. If not, write your assumption next to each flow and flag it for confirmation.
+
+## 1. Inventory controls
+
+Search the scoped components for every user-facing trigger and list them:
+
+- Event props: `onClick`, `onChange`, `onSubmit`, `onBlur`, `onKeyDown`, `@click`, `v-model`, `(click)`, `bind:value`, `on:submit`.
+- Indirect triggers: route changes, URL param edits, drag/drop, keyboard shortcuts, timers and polling, websocket or SSE messages, window focus refetch, `storage` events from other tabs.
+
+Give each an ID (`F1`, `F2`...) with file and line.
+
+## 2. Trace each flow
+
+For each control, follow the chain until nothing else changes. Write it as a sequence:
+
+```
+F3 "Apply filter" button (Filters.tsx:42)
+ 1. onClick -> setFilters({...filters, status})            Filters.tsx:44
+ 2. filters is a dependency of useEffect -> setPage(1)     ResultsList.tsx:18
+ 3. [filters, page] in query key -> GET /api/items?status&page   useItems.ts:9
+ 4. URL sync effect writes ?status=... but not page        useUrlState.ts:31
+ 5. Response -> cache -> list renders
+ Final state: filter applied, page 1, URL missing page
+```
+
+At each step record: what changed, who reads it, and what that reader does. Follow:
+
+- Every setter call and every place that state is read (search for its name).
+- Effects/watchers/computed values that depend on it, and what they set in turn.
+- Store actions, reducers and middleware/sagas/listeners they trigger.
+- Network calls: request, success path, error path, and what happens if two are in flight.
+- Derived or mirrored state (props copied into state, state copied to URL or storage), the commonest source of fights.
+
+## 3. Cross-check pairs and sequences
+
+The bugs are in combinations. For each flow, check against the others that touch the same state:
+
+| Check | Question | Typical bug |
+|---|---|---|
+| Shared writes | Do two flows write the same state, URL param or cache key? | Second handler or an effect silently undoes the first |
+| Effect loops | Does an effect write state that triggers another effect that writes back? | Value snaps back, infinite render loop, flicker |
+| Order | Does the final state depend on which handler or effect runs first? | `onBlur` save vs `onClick` cancel; parent and child both handle the event |
+| Stale closure | Does a handler, timer or subscription capture an old value? | Increment uses the value from mount; interval sees initial filters |
+| Races | Can responses arrive out of order? Is there cancellation (`AbortController`, query keys, ignore flag)? | Typing "ab" shows results for "a" |
+| Repeat | What if the user clicks twice, double submits, or toggles fast? | Duplicate POST, toggle ends in wrong state, optimistic update not rolled back |
+| Optimistic updates | Is rollback on error correct, and does a refetch overwrite a newer local change? | Item reappears after delete; like count jumps |
+| Reset paths | What resets this state (route change, logout, form reset, key change)? Does it reset everything it should, and nothing else? | Old filter survives navigation; modal reopens with last user's data |
+| Remount | Does a changing `key`, conditional render or route remount the component and lose state? | Input clears while typing |
+| Disabled/loading | Is the control disabled while its action runs, and re-enabled on error? | Stuck spinner after a failed request |
+| External sync | Back/forward buttons, a second tab, a websocket event: do they agree with local state? | URL says page 3, list shows page 1 |
+
+## 4. Confirm
+
+For each suspected problem, try to confirm it before reporting:
+
+1. Re-read the exact lines; check the framework's semantics (for example, React 18+ batches all setters in the same tick, including in promises and timeouts; `useEffect` normally runs after paint, but after a discrete event such as a click React flushes it before the browser paints; Vue watchers are batched and by default run before the next component update, `flush: 'pre'`).
+2. If tests exist, look for one covering the combination. If the user allows running things, run the app and reproduce, or write a throwaway test outside the source tree (or delete it afterwards), and note the result. Do not commit anything.
+3. Mark each finding **confirmed** (reproduced or provable from the code alone) or **suspected** (depends on timing or data you could not check). Drop anything you cannot point to a line for.
+
+## Never
+
+- Never edit source files during the audit. Suggested fixes go in the report.
+- Never report a hypothetical without the sequence of steps that produces it.
+- Never assume a library's behaviour; check its docs or source when a finding depends on it (cache invalidation, batching, debounce semantics).
+
+## Report
+
+```
+## UI flow audit: <scope>
+Assumptions to confirm: <list>
+
+### Flow map
+F1 <control> (file:line): <one-line chain> -> final state OK | PROBLEM
+F2 ...
+
+### Findings (most severe first)
+1. [confirmed|suspected] <title>  Flows: F3 + F7
+   Steps: <user steps that trigger it>
+   Chain: <file:line -> file:line -> ...>
+   Expected: <...>  Actual: <...>
+   Fix: <smallest change, e.g. derive instead of mirror, cancel stale request, single owner for the URL param>
+   Test to add: <the combination test that would catch it>
+2. ...
+
+### Clean flows
+<IDs that were traced and are fine>
+
+### Not traced
+<controls or triggers skipped and why>
+```

package/skills/ui-flow-audit/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "When I change the sort order and then the filter, the sort snaps back to default; trace what every control on the search page actually does",
+    "Each button on the cart screen works on its own but combinations leave the wrong total, audit how the handlers and effects interact",
+    "Map every click handler, effect and store update on the booking form and find where they fight each other",
+    "The dark mode toggle flips back after a second, follow the state through the context, the effect and localStorage to see why",
+    "Before release, audit the kanban board's interactions for races, double submits and stale state between actions"
+  ],
+  "should_not_trigger": [
+    "Click through the staging build and write up any bugs you find before the demo",
+    "Review my React pull request for missing useEffect dependencies",
+    "Should this modal's open state live in the URL or in component state?",
+    "Write React Testing Library tests for the cart total component",
+    "Draw the user journey for onboarding as a flowchart for the product team",
+    "Our dashboard renders slowly when filters change, profile it"
+  ]
+}

package/skills/ui-motion/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: ui-motion
+description: Interface animation for the web with the Motion library (motion/react, formerly Framer Motion) and plain CSS transitions, keyframes and the View Transitions API - motion duration and easing tokens, spring physics, hover, tap and drag gestures, AnimatePresence exit animations, layout and shared-element transitions, route changes, prefers-reduced-motion fallbacks, and keeping animation on transform and opacity within the frame budget. Use when adding or fixing a micro-interaction, modal or list animation, page transition or draggable element, an animation stutters or causes layout shift, or motion must respect reduced-motion settings.
+license: MIT
+compatibility: Any Agent Skills host. Motion examples need React 18+ and the motion npm package; CSS and View Transitions sections apply to any framework.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# UI motion
+
+Animation in a product UI has a job: show where something came from, confirm an action, or keep the user oriented during a change. If it does none of these, leave it out. Good UI motion is short, consistent, interruptible and optional.
+
+Neighbours: `remotion-video` and `manim-animations` render video; `ui-design-polish` sets the visual direction; `react-performance` covers render cost. This skill is live interface animation.
+
+## 0. Before you start
+
+1. Check what the project has: `motion` or `framer-motion` in `package.json`, a CSS animation convention, or existing duration/easing variables. Use what is there. Do not add Motion for something a CSS transition does.
+2. Note the import path in use. Current Motion: `import { motion, AnimatePresence } from "motion/react"`. Older code imports the same names from `"framer-motion"`; both work, do not mix them in one codebase. Migrating is a separate change; **ask first**.
+3. Ask what the motion is for if it is not obvious. "Make it feel alive" needs a concrete target: which element, which change, what it should communicate.
+
+## 1. Decide: CSS or Motion
+
+| Need | Use |
+|---|---|
+| Hover, focus, colour or simple show/hide state | CSS `transition` |
+| Looping or decorative keyframes (spinner, shimmer) | CSS `@keyframes` |
+| Exit animation when React unmounts an element | Motion `AnimatePresence` |
+| Element changes size/position because layout changed (reorder, expand) | Motion `layout` |
+| Same thing moves between two components (thumbnail to detail) | Motion `layoutId`, or View Transitions |
+| Drag, swipe, pan with momentum | Motion `drag` |
+| Interruptible, velocity-aware motion | Motion springs |
+| Page or route change in a multi-page or SPA app | View Transitions API where supported, else Motion `AnimatePresence` around the route |
+
+## 2. Motion tokens
+
+Define once and reuse (values to start from in `references/tokens.md`):
+
+- Durations: `--duration-fast` 100-150ms (hover, press), `--duration-base` 200-250ms (small enter/exit), `--duration-slow` 300-400ms (modals, page-level). UI animation over 500ms feels slow.
+- Easing: ease-out for entering (`cubic-bezier(0.2, 0, 0, 1)` style curves), ease-in for leaving, ease-in-out for moving on screen. Never linear except for progress and spinners.
+- Springs: two or three named presets (`snappy`, `gentle`, `bouncy`) as Motion transition objects.
+- Exits are faster than entrances (about 75% of the enter duration).
+
+## 3. Build it
+
+Core patterns with code in `references/patterns.md`:
+
+- **Enter/exit**: wrap conditionally rendered elements in `<AnimatePresence>`, give each child a stable `key`, set `initial`, `animate` and `exit`. Use `mode="wait"` when one element replaces another; `initial={false}` on `AnimatePresence` to skip the animation on first page load.
+- **Gestures**: `whileHover`, `whileTap`, `whileFocus` for feedback. Tap feedback is a small scale (0.97-0.98), not a bounce.
+- **Drag**: `drag` (`true`, `"x"` or `"y"`), `dragConstraints` (pixel object or a ref to a container), `dragElastic` (0-1), `dragMomentum={false}` to stop on release, `onDragEnd={(e, info) => ...}` using `info.offset` and `info.velocity` to decide a swipe. Always provide a keyboard or button alternative to a drag action.
+- **Layout**: `layout` on elements whose position or size changes; `layout="position"` when only position should animate (stops text squashing); `layoutId` for shared elements. Wrap siblings that affect each other in `<LayoutGroup>`.
+- **Lists**: stagger with `transition={{ delay: index * 0.03 }}` or variants with `staggerChildren`; cap total stagger at about 300ms so long lists do not take seconds.
+- **Springs**: `transition={{ type: "spring", visualDuration: 0.3, bounce: 0.2 }}` is easiest to reason about; or `stiffness`/`damping`/`mass` (these override `bounce` and `duration`). Bounce 0 for UI chrome, 0.1-0.3 for playful elements.
+- **Bundle size**: in bundle-sensitive apps use `LazyMotion` with `domAnimation` (no drag or layout) or `domMax` and the `m` component from `"motion/react-m"`.
+
+## 4. Reduced motion
+
+Required, not optional (WCAG 2.2 SC 2.3.3 Animation from Interactions is AAA, but vestibular disorders are common and the OS setting is the user's explicit request).
+
+- App-wide in Motion: `<MotionConfig reducedMotion="user">` at the root. It disables transform and layout animations when the OS setting is on and keeps opacity and colour changes.
+- Per component: `const reduce = useReducedMotion();` then swap movement for a fade.
+- CSS: `@media (prefers-reduced-motion: reduce) { ... }` removing translation, parallax, auto-play and large scale changes. Keep short opacity fades so state changes are still visible.
+- Auto-playing or looping motion longer than 5 seconds needs a pause control (WCAG 2.2.2).
+- Nothing should flash more than three times per second (WCAG 2.3.1).
+
+## 5. Performance
+
+- Animate `transform` (`x`, `y`, `scale`, `rotate`) and `opacity`. These can run on the compositor. Animating `width`, `height`, `top`, `left`, `margin` or `box-shadow` triggers layout or paint every frame; use `layout` animations or `transform: scale` instead.
+- Frame budget: 16.7ms at 60Hz, 8.3ms at 120Hz. Check with the browser's Performance panel (look for long tasks and layout/paint during the animation) and the Rendering panel's paint flashing.
+- `will-change: transform` only on elements about to animate, removed after; not on everything.
+- Do not drive animation from React state set every frame; use Motion values (`useMotionValue`, `useTransform`, `useScroll`) which update without re-rendering.
+- Scroll-linked effects: prefer CSS scroll-driven animations (`animation-timeline: scroll()` / `view()`) where browser support fits, or Motion `useScroll`; never a `scroll` event listener that sets state.
+- Test on a throttled CPU (4x slowdown) and a real low-end phone if the audience uses them.
+
+## 6. Verify
+
+1. Trigger each animation, then interrupt it (click again mid-animation, navigate away). It must not jump, stack or leave an element half-visible.
+2. Turn on the OS reduced-motion setting (or emulate `prefers-reduced-motion` in browser devtools) and repeat.
+3. Record a performance profile of the heaviest animation; no dropped frames on the target device class.
+4. Check keyboard: focus lands correctly after a modal opens or a route changes, and is not lost to an exiting element.
+5. Check no layout shift is introduced (elements entering should not push content after load).
+
+## Never
+
+- Never block input until an animation finishes, or make users wait for motion to reach content.
+- Never animate on page load just because you can; entrance animations on every scroll section get tiring.
+- Never use motion as the only signal of a state change.
+- Never mix `framer-motion` and `motion/react` imports, or two animation libraries on one element.
+
+## Report back
+
+```
+## Motion: <scope>
+Added/changed: <element: trigger -> animation, duration/spring, file>
+Tokens: <defined or reused>
+Reduced motion: <how each animation degrades>
+Performance: <properties animated; profile result or "not profiled">
+Interruptions tested: <yes/no, what>
+Not done: <items and why>
+```

package/skills/ui-motion/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Make the notification toasts slide in and fade out when dismissed using motion/react",
+    "Our accordion animates height and it janks on mobile, make it smooth",
+    "Add a shared-element transition so the product thumbnail grows into the detail page image",
+    "Let users swipe cards left or right to dismiss them, with a spring back if they don't swipe far enough",
+    "How do I make all our Framer Motion animations respect prefers-reduced-motion?",
+    "Define duration and easing tokens so every hover and modal transition in the app feels consistent"
+  ],
+  "should_not_trigger": [
+    "Render a 30 second promo MP4 from React components with spring animations",
+    "Animate a visual proof of the chain rule for a maths video",
+    "Pick a colour palette and type scale so the admin panel stops looking generic",
+    "The product grid re-renders on every filter change, profile and fix it",
+    "Check that our modal traps focus and is announced by screen readers",
+    "Write Playwright tests for the drag-and-drop kanban board"
+  ]
+}