@ketecode/loom 0.1.0 → 0.2.0

package/skills/transactional-email/references/providers.md

@@ -0,0 +1,63 @@
+# Provider notes for transactional email
+
+Read the section for the provider in use. Confirm field names against the provider's current API reference before shipping.
+
+## Postmark
+
+- Send: `POST https://api.postmarkapp.com/email` (`From`, `To`, `Subject`, `HtmlBody`, `TextBody`, `MessageStream`, `Tag`, `Metadata`). Templates: `POST /email/withTemplate` with `TemplateAlias` or `TemplateId` and `TemplateModel`; batch with templates: `POST /email/batchWithTemplates`, up to 500 messages, returns 200 even if some fail, so check each result's `ErrorCode`.
+- Auth header: `X-Postmark-Server-Token`. Test token: send `POSTMARK_API_TEST` as the server token to validate requests without delivering.
+- Streams: `outbound` is the default transactional stream; create a broadcast stream for bulk mail. Omitting `MessageStream` uses `outbound`.
+- Idempotency: no idempotency key in the API. Rely on your outbox unique key.
+- Webhooks: Delivery, Bounce, Spam complaint, Open, Click, Subscription change. Postmark does **not** sign webhooks: protect the URL with HTTP basic auth credentials in the URL, HTTPS, and an allow-list of Postmark's published webhook IPs. Retries 5xx, 408, 429 and network failures (1, 5, 10, 10, 10, 15 minutes); other 4xx are dropped, so return 2xx once stored.
+- Suppressions are per stream; hard bounces and spam complaints suppress automatically; a `SubscriptionChange` webhook tells you when one is added or removed.
+
+## Amazon SES (API v2)
+
+- Send: `SendEmail` (SDK `SESv2Client` + `SendEmailCommand`) with `Content.Simple`, `Content.Template` (stored template) or `Content.Raw`, `ConfigurationSetName`, and `EmailTags` for your own message key.
+- Sandbox (per Region): send only to verified addresses or the mailbox simulator, at most 200 messages per 24 hours and 1 per second. Request production access per Region.
+- Mailbox simulator (works in the sandbox, does not hurt reputation, still billed): `success@simulator.amazonses.com`, `bounce@`, `complaint@`, `ooto@`, `suppressionlist@`. Add labels (`bounce+order123@simulator.amazonses.com`) to match events to messages.
+- Events: configuration set event destinations to SNS, EventBridge, Firehose or CloudWatch. For SNS over HTTPS, confirm the `SubscriptionConfirmation` and verify every message's SNS signature (the AWS SDK message validator) before trusting it; also check the topic ARN.
+- Account-level suppression list (on by default for bounces and complaints in accounts created after 25 Nov 2019; enable older ones with `aws sesv2 put-account-suppression-attributes --suppressed-reasons BOUNCE COMPLAINT`); manage with `PutSuppressedDestination`, `DeleteSuppressedDestination`, `ListSuppressedDestinations`. Only hard bounces (not soft) are added. Sending treats address case as equal, but the suppression management API needs the exact case stored, so keep the original address alongside your normalised one. Configuration sets can override it. Messages to suppressed addresses are accepted, not delivered, and still count toward the daily sending quota.
+- Gmail does not send complaint feedback to SES, so a Gmail "Report spam" will not reach your suppression list.
+- Idempotency: none in the API. Rely on your outbox key.
+
+## Resend
+
+- Send: `POST https://api.resend.com/emails` with `from`, `to`, `subject`, `html`/`text` or `react` (Node SDK), `tags`. Header `Authorization: Bearer re_...`.
+- Idempotency: `Idempotency-Key` header (SMTP: `Resend-Idempotency-Key`), 1-256 chars, kept 24 hours. Same key with a different payload returns `409 invalid_idempotent_request`; a request still in flight returns `409 concurrent_idempotent_requests` (safe to retry later).
+- Test addresses: `delivered@resend.dev`, `bounced@resend.dev`, `complained@resend.dev` (these three accept `+label`, e.g. `bounced+signup1@resend.dev`) and `suppressed@resend.dev` (no labels). Test sends count against the account's sending quota.
+- Webhooks are signed via Svix: headers `svix-id`, `svix-timestamp`, `svix-signature`; verify the raw body string with `resend.webhooks.verify` or the `svix` library `Webhook` class. Email events: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.suppressed`, `email.opened`, `email.clicked`, `email.scheduled`, `email.received`. Suppress on `email.bounced` and `email.complained`; mark the outbox row on `email.failed` and `email.suppressed`.
+
+## Mailtrap
+
+- Testing: a sandbox inbox catches everything; nothing reaches real recipients. API: `POST https://sandbox.api.mailtrap.io/api/send/{inbox_id}` with the `Api-Token` header (or bearer token); SMTP credentials come from the inbox's Integration tab. Use it for development and staging, including automated tests that read the inbox through the API.
+- Sending: transactional sending API for production with a separate token from the testing token. Check the current host and stream (transactional versus bulk) in the Mailtrap docs.
+
+## SendGrid (Twilio)
+
+- Send: `POST https://api.sendgrid.com/v3/mail/send` with `personalizations[]`, `from`, `template_id` (`d-...` dynamic template) and `personalizations[].dynamic_template_data`, `custom_args` for your message key, `asm.group_id` for an unsubscribe group. `202 Accepted` on success.
+- Sandbox mode: `"mail_settings": { "sandbox_mode": { "enable": true } }` validates and returns `200 OK` without delivering. The boolean must not be quoted.
+- Signed Event Webhook: ECDSA signature in `X-Twilio-Email-Event-Webhook-Signature`, timestamp in `X-Twilio-Email-Event-Webhook-Timestamp`; verify over timestamp + raw body with the public key from the webhook settings, using the helper library. OAuth 2.0 client credentials can be enabled as well.
+- Events arrive batched as a JSON array: `processed`, `dropped`, `delivered`, `deferred`, `bounce`, `open`, `click`, `spamreport`, `unsubscribe`, `group_unsubscribe`. Each has `sg_event_id`; dedupe on it.
+- Suppressions: bounces, blocks, spam reports and invalid emails each have a `/v3/suppression/{bounces|blocks|spam_reports|invalid_emails}` endpoint; global unsubscribes are managed at `/v3/asm/suppressions/global` and unsubscribe-group suppressions at `/v3/asm/groups/{group_id}/suppressions`.
+- Idempotency: none in the API. Rely on your outbox key.
+
+## Webhook handler shape (any provider)
+
+```ts
+app.post("/webhooks/email", express.raw({ type: "*/*" }), async (req, res) => {
+  let events;
+  try {
+    events = verifyAndParse(req.headers, req.body); // provider-specific; returns an array (SendGrid batches events)
+  } catch {
+    return res.sendStatus(401); // bad signature or credentials: reject, never process
+  }
+  for (const event of events) {
+    const inserted = await db.emailEvents.insertIfAbsent({ id: event.id, provider, raw: JSON.stringify(event) });
+    if (inserted) await queue.add("email-event", { id: event.id });
+  }
+  res.sendStatus(200); // only after every event is stored, so a crash mid-batch gets a retry
+});
+```
+
+Map in the job: hard bounce or complaint → upsert `email_suppressions(address_normalised, reason, event_id, created_at)`; soft bounce → log and count; delivered → mark the outbox row.

package/skills/ui-demo-recording/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ui-demo-recording
+description: Produces polished, repeatable product demo videos and feature walkthroughs of a web app by scripting the story as a Playwright run with recordVideo, seeding fixed demo data and a frozen clock, pacing actions for a human viewer, injecting a visible cursor and click ripples, adding captions or chapter titles, then trimming, scaling and encoding the WebM with FFmpeg into MP4 or GIF. Use when marketing, docs or a release note needs a screen recording of the app, when an existing demo video is out of date after a UI change, or when the same walkthrough must be re-recorded on every release.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node 18+, the @playwright/test or playwright package with a Chromium browser installed, and ffmpeg. The app must run locally or on a staging URL with demo data.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node, npx, ffmpeg"
+  kete-loom/owner: "Kete-org"
+---
+
+# UI demo recording
+
+A demo video is a script, not a screen grab. Write the walkthrough as code so it records identically every time, looks like a calm human is driving, and can be re-run after the next UI change. This skill makes videos for people to watch; for tests that assert behaviour, use the `e2e-testing-playwright` skill.
+
+## 0. Agree the storyboard
+
+Ask the user (stop until you have answers):
+
+1. **Story**: the 3 to 7 steps the viewer should see, and the one outcome to end on.
+2. **Output**: length target, resolution (1920x1080 or 1280x720 for docs, 1080x1920 for vertical), MP4, WebM or GIF, with or without captions.
+3. **Environment**: local or staging URL, a demo account, and confirmation that **no real customer data** appears.
+4. **Branding**: light or dark theme, browser chrome or none (Playwright records the page only, without browser chrome).
+
+Write the storyboard as a numbered list of scenes, each with an action, the on-screen caption and a hold time. Get a yes before recording.
+
+## 1. Make the app deterministic
+
+The recording must look the same on every run.
+
+- **Data**: seed a dedicated demo tenant or database with believable fake names, round numbers and no lorem ipsum. Reset it before each recording.
+- **Time**: freeze the clock so dates and "5 minutes ago" labels are stable (`page.clock.setFixedTime` in Playwright 1.45+; see `references/playwright-recording.md`).
+- **Network noise**: block analytics, chat widgets and cookie banners with `page.route`, or set the consent cookie in advance.
+- **Randomness**: disable onboarding tours, A/B variants and "what's new" pop-ups through feature flags or localStorage before the first navigation.
+- **Login**: sign in once in setup and save `storageState`; never record typing a real password.
+- **Animations**: keep the app's own animations (they look good on video), but wait for them to finish before the next action.
+
+## 2. Write the recording script
+
+Use a plain Playwright library script (or a dedicated Playwright Test project) separate from the test suite. Skeleton in `references/playwright-recording.md`.
+
+1. Create the context with `viewport` equal to the output size and `recordVideo: { dir, size }` set to the same size, plus `deviceScaleFactor: 1`. A mismatch gives blurry or letterboxed video.
+2. Inject the cursor overlay with `context.addInitScript` before the first page loads (`references/cursor-and-captions.md`).
+3. Drive each scene with role-based locators, moving the mouse to the target first (`page.mouse.move` with `steps`) so the viewer sees the pointer travel, then click.
+4. Type with `locator.pressSequentially(text, { delay: 40 to 80 })` so typing is visible; use `fill` for fields the viewer does not need to watch.
+5. Hold after each meaningful change (`page.waitForTimeout(800 to 1500)`). Holds are fine here because this is a recording, not a test; always wait for the visible result first (`expect(locator).toBeVisible()` or `locator.waitFor()`).
+6. Show captions or chapter titles through the overlay, or leave them for post-production (step 4).
+7. Close the context (`await context.close()`): the video file is only finished then. Get the path from `page.video().path()` or `saveAs`.
+
+## 3. Review the raw take
+
+Play it back at full speed and check:
+
+- [ ] Every scene from the storyboard appears in order, nothing extra.
+- [ ] No spinners, flashes of unstyled content, error toasts, scrollbars jumping or debug panels.
+- [ ] No real personal data, internal URLs, API keys or staff names visible.
+- [ ] The cursor is visible and never teleports.
+
+If a scene is flaky, fix the wait in the script; do not cut around it in the edit.
+
+## 4. Post-process with FFmpeg
+
+Recipes in `references/post-processing.md`:
+
+1. Trim the blank first frames and the tail after the last hold.
+2. Convert WebM to H.264 MP4 with `yuv420p` and `+faststart` for the web.
+3. Optionally speed up dull stretches, add a title card or fade, burn in or attach captions (SRT or WebVTT), and add a music bed at low level if the user supplies a licensed track.
+4. For GIF, use the two-pass palette method, at most about 15 fps and 800 px wide, and keep it short.
+5. Probe the output (duration, resolution, size) before handing it over.
+
+## 5. Make it repeatable
+
+- Commit the script, the seed data and the storyboard next to each other (for example `demos/<name>/`).
+- Add an npm script such as `"demo:onboarding": "node demos/onboarding/record.mjs"`.
+- If the user wants it refreshed each release, run it in CI against staging and upload the MP4 as an artifact; a human approves before it replaces the published video.
+
+## Never
+
+- Never record production with real customer accounts or data.
+- Never leave real credentials in the script; read them from the environment for a demo-only account.
+- Never publish a recording without the user watching it first.
+
+## Report back
+
+```
+Demo: <name>   Length: mm:ss   Output: <path> (WxH, fps, MB)
+Script: <path>   Seed: <path>   Run: <command>
+Scenes: 1 ... 2 ... (one line each with start time)
+Checks: data is fake, no secrets on screen, cursor visible
+Known gaps: ...
+```

package/skills/ui-demo-recording/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Record a 60-second demo video of our signup and first project flow for the landing page",
+    "Our product walkthrough video is out of date after the redesign, script it so we can re-record it every release",
+    "Make a Playwright script that records the dashboard demo with a visible cursor and click highlights",
+    "Turn the recorded WebM of our app tour into an MP4 and a small GIF for the release notes",
+    "Capture a screencast of the checkout feature with fake demo data and captions explaining each step"
+  ],
+  "should_not_trigger": [
+    "Write Playwright tests that check the checkout flow still works after each deploy",
+    "Our Playwright suite fails in CI on the login test, find out why",
+    "Cut my interview footage into a three-minute story with B-roll",
+    "Build an animated explainer video in React with spring animations",
+    "Click through the staging app and look for bugs in the settings page"
+  ]
+}

package/skills/ui-demo-recording/references/cursor-and-captions.md

@@ -0,0 +1,48 @@
+# Cursor highlight and caption overlay
+
+Headless Chromium does not draw the OS cursor into the video, so draw one in the page. Pass this function to `context.addInitScript` so it runs before every page's scripts.
+
+```js
+// demos/onboarding/cursor-overlay.mjs
+export function cursorOverlay() {
+  const install = () => {
+    if (document.getElementById('__demo-cursor')) return;
+    const style = document.createElement('style');
+    style.textContent = `
+      #__demo-cursor { position: fixed; top: 0; left: 0; width: 22px; height: 22px; margin: -11px 0 0 -11px;
+        border-radius: 50%; background: rgba(255,255,255,.9); border: 2px solid rgba(0,0,0,.6);
+        box-shadow: 0 1px 4px rgba(0,0,0,.35); pointer-events: none; z-index: 2147483647;
+        transition: transform .08s ease-out; }
+      #__demo-cursor.down { transform: scale(.75); }
+      .__demo-ripple { position: fixed; width: 44px; height: 44px; margin: -22px 0 0 -22px; border-radius: 50%;
+        border: 3px solid rgba(59,130,246,.8); pointer-events: none; z-index: 2147483646;
+        animation: __demo-r .5s ease-out forwards; }
+      @keyframes __demo-r { from { transform: scale(.3); opacity: 1 } to { transform: scale(1.4); opacity: 0 } }
+      #__demo-caption { position: fixed; left: 50%; bottom: 48px; transform: translateX(-50%); max-width: 70%;
+        padding: 12px 20px; border-radius: 10px; background: rgba(17,24,39,.85); color: #fff;
+        font: 600 28px/1.3 system-ui, sans-serif; text-align: center; pointer-events: none;
+        z-index: 2147483647; opacity: 0; transition: opacity .25s; }
+      #__demo-caption.on { opacity: 1; }`;
+    document.head.appendChild(style);
+    const c = document.createElement('div'); c.id = '__demo-cursor';
+    const cap = document.createElement('div'); cap.id = '__demo-caption';
+    document.body.append(c, cap);
+    addEventListener('mousemove', (e) => { c.style.left = e.clientX + 'px'; c.style.top = e.clientY + 'px'; }, true);
+    addEventListener('mousedown', (e) => {
+      c.classList.add('down');
+      const r = document.createElement('div'); r.className = '__demo-ripple';
+      r.style.left = e.clientX + 'px'; r.style.top = e.clientY + 'px';
+      document.body.appendChild(r); setTimeout(() => r.remove(), 600);
+    }, true);
+    addEventListener('mouseup', () => c.classList.remove('down'), true);
+    window.__demoCaption = (t) => { cap.textContent = t; cap.classList.toggle('on', !!t); };
+  };
+  if (document.body) install(); else addEventListener('DOMContentLoaded', install);
+}
+```
+
+Rules:
+- The overlay has `pointer-events: none` so it never intercepts clicks.
+- Keep captions short (one line, under about 50 characters) and on screen for at least 1.5 seconds.
+- If captions must be translatable or editable later, produce an SRT in post-processing instead of burning them into the page.
+- A strict Content-Security-Policy can block injected styles in some apps; if the overlay is missing, run against a demo build that relaxes CSP, or use `bypassCSP: true` on the context.

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