@tamsensedev/runner 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,144 @@
+---
+name: interface-design
+description: Use when building or changing anything people see in a web or app UI (a screen, page, component, restyle, layout, typography, colour or spacing). Covers following the project's design system, hierarchy, type and spacing scales, colour and depth, states, real content, and looking at the rendered result before finishing.
+---
+
+# Interface design
+
+The goal is an interface that looks decided, not just correct: one thing leads, the type and spacing follow a system, colour means something, every state exists, and the result belongs to this product. Generated UI usually fails by defaulting, not by breaking. This skill is the process for deciding.
+
+## What wins when rules disagree
+
+1. **The task's explicit wording.** If it asks for a new look, a specific colour or a pattern, do that.
+2. **The project's own design sources**: DESIGN.md (or a design section in CLAUDE.md / AGENTS.md), theme and token files, the component library, Storybook, and existing screens that do the same job. These always beat any rule or banned pattern in this library. If the product already has a look, extend it.
+3. **The craft rules and default numbers in this library.** Numbers here are defaults for when the project has none.
+4. **Taste lists** such as `avoiding-generic-ai-design`. They describe defaults to avoid when a choice is free; they never override the project.
+
+The accessibility floor is not taste: if a project token fails contrast or a component has no focus style, use the nearest passing token or add the missing state, and say so in the report. Details live in the `accessibility` skill.
+
+Nobody will answer questions during the run. When something is unclear, decide, write the assumption down, and list it in the final report.
+
+## Step 1: Find what already exists
+
+Before writing UI code, spend a few minutes on:
+
+- Design documents: `DESIGN.md`, `docs/design*`, design notes in CLAUDE.md / AGENTS.md / CONTRIBUTING.
+- Tokens: CSS custom properties, Tailwind config or `@theme`, SCSS variables, a theme object, design-token JSON.
+- Components: the project's `Button`, `Input`, `Dialog`, `Table`, layout shells, icon set, and any headless primitives already installed.
+- The nearest sibling screen that does a similar job. It shows spacing, density, headings, empty states and copy tone in practice.
+- The styling system (Tailwind, CSS modules, plain CSS, CSS-in-JS, a UI kit) and lint rules about styles.
+
+Write a short note for yourself:
+
+```
+Design sources: DESIGN.md, src/styles/tokens.css, components/ui/*
+Look: light, neutral greys, one blue accent, 8px radius, borders not shadows, Inter 14px body
+Sibling screen: /settings/members (same table, same empty state)
+Gaps: no warning colour token, no skeleton component
+```
+
+## Step 2: Extend, or choose a fresh direction
+
+- **Extend (the default).** The product has screens, tokens or a component library. Use them. New surfaces should look like they shipped with the rest. Fill gaps (a missing token, a missing state) in the project's own style and name them in the report.
+- **Fresh direction.** Only when the product has no UI yet, or the task explicitly asks for a new look. Then choose one coherent direction yourself (nobody will pick for you), following [references/new-direction.md](references/new-direction.md), and state the direction in the report.
+
+Never mix: do not bring a new palette, font or radius into one corner of an existing product because it "looks better".
+
+## Step 3: Name the job of the screen
+
+Write three lines before building:
+
+- **Who and when.** "Support lead, many times a day, on a laptop." Not "users".
+- **The verb.** What they must get done here: approve, find the failed deploy, invite a teammate.
+- **The focal element.** The one thing that answers the screen's question. It must win through size, weight, contrast or the space around it; everything else is deliberately demoted.
+
+Dashboards, tables, admin, settings and other screens people work in: also follow `app-screens`. Landing and marketing pages: see the pages section of [references/new-direction.md](references/new-direction.md).
+
+## Step 4: Build with what exists
+
+Controls, in this order:
+
+1. Native HTML that does the job (`<button>`, `<a href>`, `<input>`, `<dialog>`, `<details>`, `<label>`).
+2. The project's component for it.
+3. An accessible headless primitive the project already has (Radix, React Aria, Ark, Headless UI, Reka UI, Bits UI, Angular CDK and similar).
+4. Hand-rolled only as a last resort, and then with the full contract: keyboard (arrows, Enter, Escape), focus trap and return, ARIA roles and states, click outside, scroll lock for overlays.
+
+Styling, in this order: the design system's component or variant, then a shared component you extract on the second real reuse, then semantic tokens, then a one-off utility for a genuine one-off. Bind to semantic tokens (`bg-surface`, `var(--text-muted)`), not literals (`#fff`, `gray-500`, `13px`). Never introduce a second styling system or a new UI library for looks.
+
+## Craft rules
+
+Exact default numbers are in [references/craft-defaults.md](references/craft-defaults.md). Use the project's values first.
+
+**Hierarchy**
+- One focal point per view. Promote it and demote the rest: secondary actions as secondary buttons or text, metadata in a muted tone.
+- Build tiers from size, weight and colour together. A 14px label at 500 in the secondary text colour and a 14px value at 600 in the primary colour separate better than two sizes two pixels apart.
+- If you squint and cannot tell title, body and metadata apart, the hierarchy is too weak.
+
+**Type**
+- A scale, not sizes picked by feel: product UI steps by about 1.2 to 1.25, expressive pages by about 1.333. Four to six sizes on a screen, two or three weights.
+- Sentence case for headings, buttons, labels, tabs and table headers, unless the project already uses another case.
+- Leave letter-spacing at the font's default. Only large display text (about 32px and up) may be tightened slightly, -0.01em to -0.02em. Never change it on body text. Keep the project's values if it already sets them.
+- Reading text 45 to 75 characters per line. `text-wrap: balance` on headings, `pretty` on short paragraphs.
+- Tabular figures (`font-variant-numeric: tabular-nums`) on numbers that update or line up in columns.
+
+**Space and layout**
+- One spacing scale on a 4px base. Tight inside a group, clearly larger between groups, more space above a heading than below it.
+- Group by proximity before adding boxes. Cards are for things that are actually separate objects; never nest cards.
+- Shared edges: text blocks start on two or three left edges per screen, not six. Rows of cards share a bottom edge. Choose the column count from the number of items so nothing is orphaned.
+- Responsive changes are structural (sidebar folds, table becomes a list, columns stack), not just smaller. Nothing scrolls sideways at 320 to 390px.
+
+**Colour**
+- Roles, not swatches: background, surface, raised, border, text (primary, secondary, muted, disabled), accent, focus, success, warning, danger, info.
+- Neutrals carry the structure. The accent goes on primary actions, current selection and meaning, roughly 10% of the screen at most. Colour never decorates.
+- One meaning per colour across the product. Never colour alone: add text, an icon or position.
+- Contrast: text 4.5:1 (placeholders included), large text, icons, control borders and focus indicators 3:1.
+
+**Depth and shape**
+- One depth strategy for the product: borders, tone steps, or soft shadows. A border or a shadow on a surface, not both. Real shadows belong to things that float (menus, popovers, dialogs, toasts).
+- One radius scale. Controls follow their cards. Nested corners are concentric: outer radius = inner radius + padding.
+
+**States**
+- Every control: default, hover, focus-visible, active, disabled (and why it is disabled), loading where it triggers work.
+- Every data block: loading (skeleton at the final size, no layout shift), empty (says why and offers the next action), error (what failed, what to do, a retry), one item, many items, long values. Use `interface-polish` to stress-test with worst-case data.
+
+**Content**
+- Use the task's real content and the product's real words. Never invent metrics, customer names or logos, testimonials, ratings, prices or data. Where content is missing, use clearly neutral placeholders ("Project name", "0 items") or sample data labelled as such, and list them in the report.
+- Copy rules (verbs on buttons, errors, empty states, sentence case) are in [references/writing.md](references/writing.md).
+
+## Step 5: Look at the rendered result
+
+Code review of your own CSS will read your intentions into it. Look at pixels.
+
+1. Start the app as `ui-testing` describes (dev server, seed data, login).
+2. Take screenshots of each changed screen at 1440, 768 and 390px wide, plus the states you built, following the procedure in `design-review`.
+3. Open the images and judge them: does the focal element win, do edges line up, does the phone layout work, is any text clipped or overlapping, does it look like the rest of the product?
+4. Fix the three worst problems, take new screenshots, look again. Three rounds at most.
+
+If the app cannot be started or no browser is available, reason from the code, and say in the report that the rendered check did not run and why.
+
+## Before you finish
+
+- [ ] Squint test: the focal element and the groups read in the right order.
+- [ ] Swap test: with the product name hidden, would this screen look the same as any template? If yes, the free choices were defaulted (see `avoiding-generic-ai-design`).
+- [ ] Every value comes from a token or the project's scale; no new one-off colours, sizes or radii without a reason.
+- [ ] All states above exist and were looked at.
+- [ ] 390px: no sideways scroll, targets at least 44px tall, inputs at least 16px font.
+- [ ] Contrast and visible focus checked on the changed elements.
+- [ ] Copy is real, short and consistent with the rest of the product.
+
+## Common mistakes
+
+- Restyling a product's existing components "to look better" instead of using them.
+- Everything the same size and weight, so nothing leads.
+- An accent colour on every button, tab and icon.
+- Hard-coded colours and spacing next to an existing token set.
+- Only the happy path built: no loading, empty or error state.
+- Declaring it done without ever looking at a screenshot.
+
+## Report
+
+Say briefly: the design sources you followed; whether you extended the existing look or chose a fresh direction (and the direction, if fresh); any tokens or states you had to add; placeholder or sample content that must be replaced; which screens and widths you looked at, and anything you could not check.
+
+Related: `app-screens`, `avoiding-generic-ai-design`, `interface-polish`, `motion-design`, `web-interface-guidelines`, `design-review`, `accessibility`, `ui-testing`.
+
+Sources: adapted from Dammyjay93/interface-design (MIT), pbakaus/impeccable reference files (Apache-2.0, changed: rewritten and condensed, tool and question steps removed), jakubkrehel/make-interfaces-feel-better (MIT), Leonxlnx/taste-skill (MIT).

package/library/skills/interface-design/references/craft-defaults.md

@@ -0,0 +1,130 @@
+# Craft defaults
+
+Read this when the project has no value for something you need (a type size, a spacing step, a radius, a colour role). Every number below is a default. If the project's tokens, DESIGN.md or existing screens say otherwise, they win.
+
+## Type
+
+**Scales.** Pick one ratio and step it from the body size. Round to whole pixels.
+
+| Use | Ratio | Example steps (px) |
+|---|---|---|
+| Dense product UI | 1.2 | 12, 14, 16, 20, 24 |
+| Most product UI | 1.25 | 12, 14, 16, 18, 22, 28 |
+| Marketing and editorial pages | 1.333 | 16, 21, 28, 38, 50, 67 |
+
+Product screens use fixed sizes in rem, not fluid `clamp()` headings. Marketing pages may let display type respond to width, with a cap of about 6rem.
+
+**Roles for product UI** (common clean sets: 12/14/16/24, 12/14/18/24):
+
+| Role | Size | Weight | Line height |
+|---|---|---|---|
+| Page title | 20 to 28px (24 default) | 600 | 1.25 |
+| Section or card title | 16px | 500 to 600 | 1.4 |
+| Body, table cells, nav | 14px (13px in very dense tools) | 400 | 20px at 14px |
+| Reading text (help, articles) | 16px | 400 | 24px at 16px (1.5) |
+| Labels, metadata, axis ticks | 12px | 400 to 500 | 16px |
+| Smallest text anywhere | 11px | 500 | 16px |
+
+- Body line height 1.45 to 1.6; headings 1.1 to 1.3; display 0.95 to 1.1.
+- Measure: 45 to 75 characters for prose (65 to 75 ideal). Tables and dense data may run wider.
+- Weights: at most three per screen. 700 does one job (a title, or money).
+- Letter-spacing: 0 for body and UI text. Display text from about 32px may go to -0.01em or -0.02em. Do not go tighter than -0.03em.
+- Case: sentence case for headings, buttons, labels, tabs, menu items and table headers. Avoid all-caps labels unless the project uses them.
+- Families: one well-tuned sans covers product UI. A second family needs one clear job (monospace for code and IDs, a display face for marketing headlines). Never three.
+- Phones: form inputs at 16px or more, or iOS Safari zooms the page on focus.
+- Light text on dark surfaces: add a little line height (about +0.05) and consider one step more weight.
+
+## Spacing
+
+Base unit 4px. Scale: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96.
+
+| Context | Default |
+|---|---|
+| Icon to label | 6 to 8px |
+| Inside a control (vertical, horizontal) | 6 to 8px, 12 to 16px |
+| Between related fields | 16px |
+| Card padding | 16 to 24px (20 default) |
+| Gap between cards | 16px, the same horizontally and vertically |
+| Between sections of a screen | 32 to 48px |
+| Page gutter, desktop | 24 to 40px |
+| Page gutter, phone | 16 to 20px |
+| Between sections of a marketing page | 96 to 160px |
+
+- Padding is symmetrical unless content needs otherwise. An icon button side may be 2px less than the text side for optical balance.
+- Density is three settings moved together: row height, padding and type size. Do not shrink type and keep the padding.
+
+## Sizes of controls and rows
+
+| Element | Default |
+|---|---|
+| Button and input height, desktop | 32 to 36px (28 in dense toolbars, 40 in long forms) |
+| Button and input height, phone | 44px |
+| Hit area | 44 x 44px on touch, at least 40 x 40 in dense desktop UI (WCAG 2.2 minimum 24 x 24). Extend small controls with padding or a pseudo-element; hit areas never overlap |
+| Table row | 40 to 48px; 32 to 36px dense |
+| List row with avatar and two lines | 56 to 72px |
+| Sidebar width | 224 to 256px; icon rail 48 to 56px |
+| Top bar height | 48 to 56px |
+| Icons | 16px inline and in nav (14 to 20), 1.5px stroke beside regular text, 2px beside semibold |
+
+## Colour
+
+- **Contrast (WCAG AA):** text and placeholders 4.5:1; text 24px and up (or 18.7px bold and up) 3:1; icons, control borders, focus indicators and chart marks that carry meaning 3:1 against what they sit on.
+- **Text tiers:** primary, secondary, muted (all at 4.5:1 or better), and disabled. On white, about #111 / #4b5563 / #6b6b6b is the lightest set that still passes. Two greys that are close (#999 and #aaa) read as one grey used twice.
+- **Accent budget:** one accent hue, used for the primary action, the current selection, focus and data highlights. Roughly 60% dominant neutral, 30% secondary neutral, 10% accent at most. Many good product screens have under 5% coloured pixels.
+- **Status:** success, warning, danger, info as pale tint backgrounds with dark text of the same hue for chips and banners; solid colour only for small marks. Example pairs: success #dcfae5 / #04250e, danger #ffedea / #831c1e, warning #fffbeb / #92400e. Green text on white needs a dark green (about #247b50) to reach 4.5:1.
+- **Neutrals:** a little tint from the brand hue is fine if the project already does it; pure greys are fine too. Sidebars use the page background (or one step off it), not a dark or saturated block beside a light canvas.
+- **Dark mode:** design it, do not invert. Elevation by lightness: base, then about +4 to +8% lightness per raised level. Borders around rgba(255,255,255,0.06 to 0.12). Desaturate status colours slightly. Set `color-scheme: dark`.
+- **New palettes:** define them in OKLCH when the project has no colour space convention; vary lightness, lower chroma near white and black.
+
+## Depth
+
+Choose one strategy per product and hold it:
+
+| Strategy | Suits |
+|---|---|
+| 1px borders, low contrast (about #e5e7eb to #ededed on white, 1.1 to 1.3:1) | Dense tools, tables, admin |
+| Tone steps (surface one step lighter or darker than the page) | Calm apps, dark themes |
+| Soft shadows | Consumer apps with few layers |
+
+- A resting card gets a border or a tone step, or at most a faint shadow (about `0 1px 2px rgb(0 0 0 / 0.06)`). Not a 1px border plus a wide soft shadow.
+- A shadow can stand in for a border: `0 0 0 1px rgb(0 0 0 / 0.06), 0 1px 2px -1px rgb(0 0 0 / 0.06), 0 2px 4px rgb(0 0 0 / 0.04)`; on dark, `0 0 0 1px rgb(255 255 255 / 0.08)`.
+- Floating layers (menus, popovers, dialogs, toasts) get a real shadow with an offset and blur, one level above their parent. Never a zero-offset coloured glow.
+- Keep real borders for dividers, table rules and input outlines.
+
+## Radius
+
+Choose a tight or a soft scale once:
+
+| Scale | Chips | Controls | Cards | Dialogs |
+|---|---|---|---|---|
+| Tight | 4px | 6px | 8px | 12px |
+| Soft | 6px or full | 8 to 10px | 12 to 16px | 16 to 20px |
+
+- Concentric nesting: outer radius = inner radius + padding. When the padding is over about 24px, treat the layers as separate.
+- Pill (fully round) shapes are for chips, toggles and small buttons, not cards.
+- Images in rows: circles for people, 2 to 4px for artwork and logos, the card radius for photos inside cards.
+
+## Motion
+
+Short form; full guidance in `motion-design`.
+
+| Interaction | Duration | Easing |
+|---|---|---|
+| Press feedback | 100 to 160ms | ease-out |
+| Hover, colour change | 100 to 150ms | ease |
+| Tooltip, small popover | 125 to 200ms | ease-out |
+| Dropdown, menu | 150 to 250ms | ease-out |
+| Dialog, drawer | 200 to 300ms (up to 500 for large drawers) | ease-out |
+| Exit | about 75% of the enter | ease-out |
+
+Strong ease-out: `cubic-bezier(0.23, 1, 0.32, 1)`. On-screen movement: `cubic-bezier(0.77, 0, 0.175, 1)`. Never `ease-in` for UI. Respect `prefers-reduced-motion`.
+
+## Browser details people notice
+
+- Focus ring: 2px, offset 2px, in the accent or a high-contrast colour, on `:focus-visible`.
+- Text selection colour from the palette when the project themes it.
+- `-webkit-font-smoothing: antialiased` on the root (macOS) if the project does not already set it.
+- Images: explicit width and height or `aspect-ratio`; a 1px inset outline at `rgb(0 0 0 / 0.1)` on light (`rgb(255 255 255 / 0.1)` on dark) separates photos from same-colour backgrounds.
+- Leave scrollbars native in product UI unless the project already styles them.
+
+Sources: numbers condensed from Dammyjay93/interface-design (MIT), Leonxlnx/taste-skill app-screens reference (MIT), jakubkrehel/make-interfaces-feel-better (MIT), emilkowalski/skills (MIT) and pbakaus/impeccable craft-floor, operate, typeset, colorize and layout references (Apache-2.0, changed: rewritten as defaults under the project's own system).

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

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

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

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

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

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