@tamsensedev/runner 0.10.0 → 0.18.0

package/library/skills/interface-design/references/new-direction.md

@@ -1,62 +1,62 @@
-# Choosing a fresh direction
-
-Read this only when the product has no interface yet, or the task explicitly asks for a new look (a redesign, a new brand, a landing page with no existing site). In every other case, extend what exists.
-
-Nobody will choose between options for you. Work out one direction, check it against the generic default, build it, and state it in the report.
-
-## 1. Ground it in the subject
-
-Write these in your notes before any visual decision:
-
-- **Subject, audience, job.** What the product is, who uses it, and the one thing the screen or page must get them to do. If the task does not say, infer it from the repository (README, package names, routes, seed data) and write the assumption down.
-- **Domain.** Five or more concepts, objects and words from the product's world (not features). A scheduling tool for clinics: rota, shift, cover, on call, ward, handover.
-- **Colour world.** Five or more colours that exist in that world, taken from its materials, places and printed things, not from "warm" or "cool".
-- **The defaults.** Three obvious choices you would make for this kind of interface without thinking (for example: violet gradient hero, three icon cards, Inter on white). You cannot avoid patterns you have not named.
-- **One signature.** A single element that could only belong to this product: a schedule set in the rhythm of a real rota, service health drawn as a route map, the product's own object shown large. If you cannot name one, keep exploring the domain.
-
-## 2. Write a compact plan
-
-```
-Direction: calm clinical tool, dense like a ward board, quiet colour
-Palette:   ground #f7f8f7, surface #ffffff, ink #14211c, muted #56635d, accent #0f766e, danger #b42318
-Type:      one grotesk for everything; 14px body, scale 1.2; tabular figures for times
-Layout:    left rail with labelled nav, full-width rota grid, details in a right panel
-Depth:     1px borders, no resting shadows; radius 6/8
-Signature: the rota grid itself, cover gaps shown as hatched cells
-Rejected:  gradient header -> flat ground; KPI cards with icons -> one divided summary strip
-```
-
-- Palette: a small set of named roles (ground, surface, ink, muted, accent) plus status colours, with contrast checked.
-- Type: one or two families with clear roles. Use a face the project can load the way it loads its other assets; a system stack is acceptable for product UI. If a font needs a new dependency, say so in the report.
-- Layout: a one-sentence concept per screen and the alignment rule (left-aligned by default; centre at most one moment).
-
-## 3. Check the plan against the generic version
-
-Ask: if a similar prompt went to another model, would it land on the same plan? For each part that would (the palette, the hero, the card grid), change it and note what you changed and why. The patterns to check against are in `avoiding-generic-ai-design`.
-
-Then build, following the main skill, and run the render-and-look loop.
-
-## 4. Keep the signature where it means something
-
-Put the signature where it carries meaning and do not stamp it on every element; a style's move repeated everywhere becomes a costume. On a working screen the direction lends type, palette, density and the one signature, while navigation and controls stay the standard ones people already know. A distinctive direction still meets the craft floor: hierarchy, contrast, states, phone layout, keyboard focus, reduced motion.
-
-## Pages (landing, marketing, docs home)
-
-A page is read and scrolled once, so it can carry more voice than an app screen. Rules that hold for pages:
-
-- **The first screen says what this is.** A clear title in the page's one `h1` (a name plus what it does, or a short claim of about five words), one supporting sentence directly under it that says plainly what the thing is, and one primary action as a real button. A stranger should know in five seconds what it is, who it is for and what to do.
-- **Headlines fit in two lines** at every width. About 32 characters is safe at a confident size. Cut words before shrinking type.
-- **Sections follow the argument, not the template.** List the page as claims with their proof, one line per section, and delete sections with no claim. The stock order (hero, logo strip, three features, testimonial, pricing, call to action) is the sign of no argument.
-- **Each section has a heading that names it** and a composition different from its neighbours. The same layout three times in a row is the template showing.
-- **Write the full content.** Every section the task asks for carries its real information (the whole price table, every plan's limits). Thin sections lose to busier pages.
-- **Type does the visible work:** a decisive jump from body to headline (three times or more), five sizes at most, body 16 to 20px in full ink, not grey.
-- **Equal outer margins** at every width, no stretch of blank space taller than half a screen, and the gap between sections clearly larger than any gap inside one.
-- **Imagery:** the project's own screenshots, product photos or footage first; real interface fragments of the product beat drawings of fake dashboards. Do not download images from the internet or invent photos of customers. If there is nothing, let type and colour carry the page rather than grey boxes or stock icons.
-- **Proof is never invented.** No made-up customers, logos, quotes, ratings, user counts or benchmarks. If the task asks for a testimonial section and none are supplied, build it with plainly fictional sample content and list it in the report for replacement.
-- **Motion:** one authored moment (a single entrance or one interactive demo) beats fade-ups on every section. Content must be visible if scripts fail. See `motion-design`.
-
-## Report
-
-State the direction in two or three lines (palette, type, signature), what you rejected as generic, and any sample content or assets to be replaced.
-
-Sources: adapted from Dammyjay93/interface-design (MIT, changed: "does that direction feel right?" and "offer to save" removed, the agent decides and reports), Leonxlnx/taste-skill (MIT, changed: no direction library, no image downloads) and pbakaus/impeccable mode-operate and craft-floor references (Apache-2.0, changed: rewritten, no direction service or user choice).
+# Choosing a fresh direction
+
+Read this only when the product has no interface yet, or the task explicitly asks for a new look (a redesign, a new brand, a landing page with no existing site). In every other case, extend what exists.
+
+Nobody will choose between options for you. Work out one direction, check it against the generic default, build it, and state it in the report.
+
+## 1. Ground it in the subject
+
+Write these in your notes before any visual decision:
+
+- **Subject, audience, job.** What the product is, who uses it, and the one thing the screen or page must get them to do. If the task does not say, infer it from the repository (README, package names, routes, seed data) and write the assumption down.
+- **Domain.** Five or more concepts, objects and words from the product's world (not features). A scheduling tool for clinics: rota, shift, cover, on call, ward, handover.
+- **Colour world.** Five or more colours that exist in that world, taken from its materials, places and printed things, not from "warm" or "cool".
+- **The defaults.** Three obvious choices you would make for this kind of interface without thinking (for example: violet gradient hero, three icon cards, Inter on white). You cannot avoid patterns you have not named.
+- **One signature.** A single element that could only belong to this product: a schedule set in the rhythm of a real rota, service health drawn as a route map, the product's own object shown large. If you cannot name one, keep exploring the domain.
+
+## 2. Write a compact plan
+
+```
+Direction: calm clinical tool, dense like a ward board, quiet colour
+Palette:   ground #f7f8f7, surface #ffffff, ink #14211c, muted #56635d, accent #0f766e, danger #b42318
+Type:      one grotesk for everything; 14px body, scale 1.2; tabular figures for times
+Layout:    left rail with labelled nav, full-width rota grid, details in a right panel
+Depth:     1px borders, no resting shadows; radius 6/8
+Signature: the rota grid itself, cover gaps shown as hatched cells
+Rejected:  gradient header -> flat ground; KPI cards with icons -> one divided summary strip
+```
+
+- Palette: a small set of named roles (ground, surface, ink, muted, accent) plus status colours, with contrast checked.
+- Type: one or two families with clear roles. Use a face the project can load the way it loads its other assets; a system stack is acceptable for product UI. If a font needs a new dependency, say so in the report.
+- Layout: a one-sentence concept per screen and the alignment rule (left-aligned by default; centre at most one moment).
+
+## 3. Check the plan against the generic version
+
+Ask: if a similar prompt went to another model, would it land on the same plan? For each part that would (the palette, the hero, the card grid), change it and note what you changed and why. The patterns to check against are in `avoiding-generic-ai-design`.
+
+Then build, following the main skill, and run the render-and-look loop.
+
+## 4. Keep the signature where it means something
+
+Put the signature where it carries meaning and do not stamp it on every element; a style's move repeated everywhere becomes a costume. On a working screen the direction lends type, palette, density and the one signature, while navigation and controls stay the standard ones people already know. A distinctive direction still meets the craft floor: hierarchy, contrast, states, phone layout, keyboard focus, reduced motion.
+
+## Pages (landing, marketing, docs home)
+
+A page is read and scrolled once, so it can carry more voice than an app screen. Rules that hold for pages:
+
+- **The first screen says what this is.** A clear title in the page's one `h1` (a name plus what it does, or a short claim of about five words), one supporting sentence directly under it that says plainly what the thing is, and one primary action as a real button. A stranger should know in five seconds what it is, who it is for and what to do.
+- **Headlines fit in two lines** at every width. About 32 characters is safe at a confident size. Cut words before shrinking type.
+- **Sections follow the argument, not the template.** List the page as claims with their proof, one line per section, and delete sections with no claim. The stock order (hero, logo strip, three features, testimonial, pricing, call to action) is the sign of no argument.
+- **Each section has a heading that names it** and a composition different from its neighbours. The same layout three times in a row is the template showing.
+- **Write the full content.** Every section the task asks for carries its real information (the whole price table, every plan's limits). Thin sections lose to busier pages.
+- **Type does the visible work:** a decisive jump from body to headline (three times or more), five sizes at most, body 16 to 20px in full ink, not grey.
+- **Equal outer margins** at every width, no stretch of blank space taller than half a screen, and the gap between sections clearly larger than any gap inside one.
+- **Imagery:** the project's own screenshots, product photos or footage first; real interface fragments of the product beat drawings of fake dashboards. Do not download images from the internet or invent photos of customers. If there is nothing, let type and colour carry the page rather than grey boxes or stock icons.
+- **Proof is never invented.** No made-up customers, logos, quotes, ratings, user counts or benchmarks. If the task asks for a testimonial section and none are supplied, build it with plainly fictional sample content and list it in the report for replacement.
+- **Motion:** one authored moment (a single entrance or one interactive demo) beats fade-ups on every section. Content must be visible if scripts fail. See `motion-design`.
+
+## Report
+
+State the direction in two or three lines (palette, type, signature), what you rejected as generic, and any sample content or assets to be replaced.
+
+Sources: adapted from Dammyjay93/interface-design (MIT, changed: "does that direction feel right?" and "offer to save" removed, the agent decides and reports), Leonxlnx/taste-skill (MIT, changed: no direction library, no image downloads) and pbakaus/impeccable mode-operate and craft-floor references (Apache-2.0, changed: rewritten, no direction service or user choice).

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

@@ -1,52 +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).
+# 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

@@ -1,103 +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).
+---
+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).