@tamsensedev/runner 0.0.0-stage → 0.2.1

package/library/skills/avoiding-generic-ai-design/references/tells.md

@@ -0,0 +1,112 @@
+# The dated registry of AI-look patterns
+
+Read this when scanning a diff or a screenshot for patterns that make an interface read as generated. Last reviewed October 2026.
+
+A pattern here is a default, not a crime. Most began as good ideas on good sites and became tells by being produced everywhere without a reason. That is why the list is dated: every published "use this instead" list becomes the next wave within months, so the replacements below are procedures (derive from the content, the product, the project's system), not specific fonts or colours.
+
+Everything here yields to the project's own design system and to explicit task wording (see the main skill).
+
+## 1. First wave (2023 to 2024)
+
+| Pattern | Instead |
+|---|---|
+| Violet or indigo gradients on heroes, buttons and glows | Flat colour from the product's palette |
+| Gradient-filled headline text | Solid text; emphasis from weight or size |
+| Glass panels: backdrop blur, translucent cards, used as decoration | Opaque surfaces one tone step from the ground |
+| Glowing or gradient "Get started" button | A flat button named for its action |
+| Soft grey drop shadow under every card | A border or tone step; shadows only on floating layers |
+| Three identical feature cards, each with an icon in a rounded square | A composition built from the actual content; different weights for different importance |
+| Emoji as icons or bullets | Words, or one consistent icon set |
+| Centred headline, subtitle, two buttons, screenshot below | A first screen built around the product's most characteristic thing |
+| The same default typeface on every generated page | A face chosen for the product, or the project's own |
+
+## 2. Second wave (2025)
+
+| Pattern | Instead |
+|---|---|
+| Eyebrow: a tiny tracked uppercase label above every heading | Fold the information into the heading, or delete it |
+| Pill badge above the hero headline ("New", "Beta", "Introducing") | Say it in the supporting sentence |
+| One word of a headline in italic serif, colour or underline | One face, one colour; the words carry the emphasis |
+| Bento grid of rounded tiles as the feature section | A section composed for its content |
+| Near-black ground with one neon accent and a glow | A considered dark palette, no glow |
+| Floating rounded pill navigation with blur | A plain bar: name, a few links, one action |
+| Fake dashboard hero made of grey bars and donut charts | A real fragment of the product's interface, or no image |
+| Decorative pulsing status dot ("Available", "Live") | Remove, unless it reports a real status |
+| Fade-and-rise on every section | One authored moment, or none |
+
+## 3. Third wave (2025 to 2026): the fix that became the look
+
+The published remedy for the first two waves was "warm it up and make it editorial". Models adopted it wholesale, and it is now one of the most recognisable generated looks.
+
+| Pattern | Instead |
+|---|---|
+| Warm cream ground (near #F4F1EA) with a terracotta, rust or clay accent (often near #D97757, the Claude interface accent, so on a customer product it reads as a tell) and a high-contrast serif display | A palette from the product's own world |
+| Serif display type as the shortcut to "premium" | A face chosen for the product |
+| Broadsheet cosplay: hairline rules everywhere, zero radius, dense newspaper columns | Structure from space and tone; rules only where a table needs them |
+| Performative labels: "Field notes", "Quietly trusted by", "On our desks" | Plain section names |
+
+## 4. Template chrome that appears whatever the subject
+
+| Pattern | Instead |
+|---|---|
+| Tracked all-caps label above every heading | Sentence case at a readable size, next to what it describes |
+| Meta strings joined with middle dots ("A · B · C") everywhere | Separate fields, or a sentence |
+| Labels built as "WORD, fragment" with a spaced long dash | Plain labels |
+| Tinted near-black (#0B0B0B, #111) standing in for black on every page | The project's ink colour, chosen once |
+| Monospace for small data labels and captions as a "technical" voice | The text face; tabular figures where numbers align; monospace for code and IDs |
+| An arrow glyph appended to every link and button | Plain link text; arrows only where direction means something |
+| Index numbering (01 / 02 / 03, "Step 02") on content that is not a sequence | Order by position or size; a real ordered list when order matters |
+| Agency micro-meta: local time, coordinates, weather, version stamps | Remove |
+| Design-tool chrome as ornament: crosshairs, crop marks, dashed guides, rulers | Remove |
+
+## 5. Structural patterns
+
+| Pattern | Instead |
+|---|---|
+| A full-sentence headline at display size running three or four lines | A title of about five words; the rest goes below |
+| Stock section order: hero, logos, features, testimonial, pricing, call to action | The order of the argument |
+| Every section the same layout family | Different composition per section |
+| Everything centred | Left-aligned by default; centre at most one moment |
+| One medium radius (12 to 16px) on everything regardless of hierarchy | A radius scale chosen once, nested concentrically |
+| Content chopped into identical rounded cards with the same soft shadow | Group by proximity; cards only for separate objects; never nested cards |
+| Nine nearly equal font sizes | Four to six sizes, clearly apart |
+| Invented social proof: logos, quotes, star rows, "10,000+ teams" | Real proof from the task, or none |
+| A grey box, a stretched photo or a CSS shape where a picture belongs | A real image, or a design that needs none |
+| A modal for a task that needs no interruption | Inline or progressive disclosure |
+| Coloured `border-left` or `border-right` stripes thicker than 1px on cards, callouts, alerts | A tint, an icon, or a heading that names the state |
+| Hard offset shadows (`4px 4px 0`) outside a deliberately brutalist product | The product's depth strategy |
+| Sketch-style SVG illustrations and grain filters as decoration | Real illustration, real screenshots, or none |
+| Stripe and grid-line backgrounds with no map, blueprint or canvas under them | A plain surface |
+
+## 6. Generated dashboards
+
+Full detail in `app-screens`; the short list:
+
+| Pattern | Instead |
+|---|---|
+| Dark navy or saturated sidebar beside a light canvas, coloured active pill with a left bar | Sidebar on the page ground; a neutral active pill, or brighter text on dark |
+| "Welcome back, Alex" with a waving hand | A noun title ("Overview", the project's name) |
+| Four KPI cards, each with an icon in a tinted circle and a sparkline | One container split by dividers: label over value, no icon, no sparkline |
+| A green "+12.5%" on every KPI, including changes from zero | Deltas only where useful, with their window in words; grey for zero; "+4 (new)" from zero |
+| KPI values at 36 to 48px bold in the brand colour | 24 to 32px in the text colour |
+| Gradient area chart, smoothed spline, a dot on every point | A 2px straight line, little or no fill, no markers |
+| Rainbow palette, a hue per bar or per chart | One hue per chart; neutrals for the rest |
+| Fat donut with labels on the slices | A thin ring or a sorted bar list, values in a table beside it |
+| Zebra table under uppercase tracked headers, checkbox, avatar, chip and kebab on every row | Rules and alignment, sentence-case grey headers, one status mark, actions only where needed |
+| Left-aligned numbers in proportional digits | Right-aligned tabular figures |
+| Saturated status chips with white text | Pale tint with dark text of the same hue |
+| "No data" illustration in an empty chart | The zero line drawn and one sentence in the frame |
+
+## 7. Copy
+
+Genre verbs and adjectives (unlock, supercharge, seamless, elevate, effortless, cutting-edge, all-in-one); "Not just X, it's Y"; tricolon headlines; "Get started" and "Learn more" where a precise verb exists; long dashes as a habit; lorem ipsum, "Acme", "John Doe", "User 1"; captions that describe the design. See `interface-design` references/writing.md.
+
+## 8. Motion
+
+Identical fade-up on every block; a dozen staggered hero entrances; hover lift on every card; bounce or elastic easing by reflex; infinite loops that mean nothing; reveals that fail and leave a blank band; animation on actions repeated many times a day. See `motion-design`.
+
+## 9. Why removal is not enough
+
+A page with every pattern removed and nothing in their place is an empty page with good manners, and anyone could guess it from the category plus this list. The patterns were filling a gap where a decision should have been. Fill that gap first: the content, the product's own objects and data, the one thing the screen is for, made large.
+
+Sources: adapted from Leonxlnx/taste-skill references/tells.md and app-screens.md (MIT, changed: house-style bans turned into defaults that yield to the project; no inspector statuses), the generated-design traits in the frontend-design skill of anthropics/claude-plugins-official (Apache-2.0, changed: condensed into table rows) and pbakaus/impeccable craft-floor (Apache-2.0, changed: rewritten as table rows).

package/library/skills/clean-commits/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: clean-commits
+description: Use when committing work in the code step: stage only what the task needs, keep secrets and debug leftovers out, write messages in the project's style, and commit on the current branch without pushing, switching branches or rewriting history.
+---
+
+# Clean commits
+
+The code step ends with your work committed on the current branch. TAMsense pushes the branch and opens the pull request; you do neither.
+
+## Hard limits
+
+- Commit on the branch that is checked out. Do not create, switch or delete branches.
+- Do not push, open pull requests, or post anything to the hosting service.
+- Do not rewrite history: no `commit --amend`, `rebase`, `reset` of existing commits, `push --force`, or `filter-branch`. To undo something already committed, add a new commit.
+- Do not skip hooks or signing (`--no-verify`, `-c commit.gpgsign=false`) and do not change git config. If a hook fails, fix what it reports. If the commit cannot be made for an environment reason (a hook needs a service that is not available, no git identity, signing not set up), leave the work staged and explain exactly what failed in the report.
+- Several repositories in the working folder: commit in each one you changed, and only in those.
+
+## Before staging
+
+```
+git status
+git diff
+```
+
+Go through every changed and untracked file:
+
+- **Belongs to the task?** Leave out unrelated edits, formatting churn and files you did not mean to change. Changes that were there before your run are not yours: do not commit them.
+- **Debug leftovers?** Remove `console.log`, `print`, `[DEBUG-` tags, commented-out code, temporary scripts and scratch files.
+- **Secrets?** Never commit `.env` files, keys, tokens, passwords, certificates, credentials in config, or real customer data in fixtures. If a secret is already in a file you changed, do not commit it; report it.
+- **Generated or large files?** Commit build output, coverage reports, caches or binaries only if the project already tracks them. Regenerate generated code the way the project does rather than editing it by hand.
+- **Lock files:** they change only when you deliberately changed dependencies, and only the lock file of the project's package manager.
+
+## Staging
+
+Stage specific paths, not everything:
+
+```
+git add src/billing/tax.ts src/billing/tax.test.ts
+git diff --staged
+```
+
+Read the staged diff once more. `git add -A` or `git add .` is fine only after `git status` shows nothing but your intended changes.
+
+## How many commits
+
+- One commit for the task is fine.
+- Several commits help when the work has separate logical steps (a refactor the feature needs, then the feature; a migration, then the code using it). Each commit should build and pass tests on its own when practical.
+- In a rework, one commit per addressed comment or one commit for the round; both are fine.
+
+## The message
+
+Follow the project's style: look at `git log --oneline -20` and any commit rules in CONTRIBUTING or the commit lint config (Conventional Commits, ticket prefixes, language, capitalisation).
+
+Without a visible convention:
+
+```
+Default VAT country to the shop's country for guest invoices
+
+Customers without a country crashed invoice creation: taxRate() looked
+up undefined in RATES and returned NaN. Use the shop country instead,
+as the spec's rule 4 says.
+```
+
+- Subject: imperative, says what changes, about 50 to 72 characters, no trailing period.
+- Body when the reason is not obvious: why the change is needed, and for bug fixes the root cause.
+- Describe the change, not the process: avoid "as requested", "fix review", "WIP".
+
+## After committing
+
+```
+git status
+git log --oneline -5
+```
+
+`git status` should be clean, or the remaining files should be ones you deliberately left out (explain them in the report). Confirm the commit is on the expected branch.
+
+## Common mistakes
+
+| Mistake | Instead |
+|---|---|
+| `git add -A` with stray files in the tree | Check `git status`, stage paths. |
+| Committing an `.env` or a key "just for testing" | Never; use the project's example env file. |
+| Amending an earlier commit to tidy history | Add a new commit. |
+| Bypassing a failing hook | Fix the reported problem, or report why it cannot pass here. |
+| Pushing "to save the work" | TAMsense pushes; you only commit. |

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

@@ -0,0 +1,107 @@
+---
+name: design-review
+description: Use to judge the visual quality of changed UI, before finishing UI work in a code step or when reviewing a branch. Renders changed screens headless at desktop, tablet and phone widths with empty, loading, error and long-content states, critiques the screenshots, then fixes (code step) or reports with evidence (review step).
+---
+
+# Design review
+
+Correct is not the same as crafted. Generated UI usually renders, aligns and does not clash, yet nothing was decided: no focal point, flat hierarchy, the same card everywhere, missing states. This review finds where the interface defaulted instead of decided, weighs what each problem costs the user, and either fixes it (code step) or reports it with evidence (review step).
+
+It judges pictures, not intentions. Reading your own CSS, you see what you meant; a screenshot shows what is there.
+
+## Two modes
+
+- **Code step** (you built or changed the UI): run this before finishing, fix what it finds, re-render, repeat. Three rounds at most.
+- **Review or test step**: check the branch against its base. Never change product code. Temporary scripts and screenshots go in a temp directory outside the repository. Finish by calling `submit_verdict` once with `passed` and the report.
+
+Nobody answers questions during the run. Where intent is unclear, state your assumption in the report and judge against it.
+
+## Step 1: Scope
+
+- List the UI files changed against the base branch (`git diff --name-only <base>...HEAD`) and map them to the routes, screens or components that render them. The review covers those screens and nothing the branch did not touch.
+- Read the task or PR description for what the change is meant to do.
+
+## Step 2: Reconstruct the design language
+
+Before judging, find what governs these screens (see `interface-design` step 1) and write:
+
+```
+Screens:          /billing, /billing/invoices/:id
+Design sources:   DESIGN.md, src/styles/tokens.css, components/ui
+Decisions found:  sentence case, 8px radius, borders not shadows, one blue accent, 14px body
+Sibling screens:  /settings/members (table, empty state)
+Exceptions:       none documented
+```
+
+You review against the product's own intent, not a generic ideal. A deliberately dense tool is not failing for being dense. A pattern the design system uses is a decision, not a defect, even if `avoiding-generic-ai-design` lists it.
+
+## Step 3: Render
+
+Follow [references/screenshot-procedure.md](references/screenshot-procedure.md):
+
+- Start the app and drive it headless as `ui-testing` describes (its headless check script, outputs in a temp folder). The browser is recorded for the task: name the render after the variant and the question, and mark each state.
+- For each changed screen: 1440, 768 and 390px wide, first screen and full page.
+- Key states: empty, loading, error, long content (worst-case data), plus hover and keyboard focus on the main controls, and dark mode if the product has it.
+- When the change restyles an existing screen, compare with untouched sibling screens and with the base branch's code (`git diff <base>...HEAD` on the styles); do not switch branches in the working tree.
+
+If the app cannot run or no browser is available, review from code, mark every visual finding as inferred, and say in the report that the rendered check did not run and why.
+
+## Step 4: Look
+
+Open every screenshot (the Read tool shows images). First the whole, then details, following [references/critique-passes.md](references/critique-passes.md):
+
+1. **The whole.** One second, then five: what is this screen, what is it for, what do I do? Squint: do two or three masses lead? Cover the product name: could this belong to any product?
+2. **The lenses**, one at a time: hierarchy; typography and colour; surfaces and depth; layout, edges and rhythm; states and polish; content and honesty; phone composition; consistency with the design system and sibling screens.
+3. **Mechanical checks** on the changed code: `web-interface-guidelines`, `interface-polish` rules, contrast of new colour pairs, `accessibility` basics.
+
+## Step 5: Keep only findings with evidence
+
+Every candidate finding needs:
+
+- **Evidence**: the screenshot it shows in (file name, width, state) or a `file:line` contract violation: a documented design decision or token that reaches this screen, and the code that breaks it.
+- **Cost**: why it hurts the user or makes the screen read as generic. If you cannot say why, it is taste: drop it.
+- **One correction**: the specific change, named in the project's own tokens and components ("use `Button variant=secondary`", "gap from `--space-4`, not 13px").
+
+Then try to falsify each one: re-open the source, check whether the difference is deliberate (a documented exception, a sibling screen doing the same), whether it lies outside the changed lines, whether another finding already covers the same root cause. Delete what does not survive.
+
+Do not raise: personal preference where the choice is coherent and well executed; bold choices that match the stated intent; anything the design system ratifies; lint or formatting concerns; pre-existing problems on screens the branch did not touch (mention them once under "Outside scope" at most).
+
+## Step 6: Severity and verdict
+
+- **Blocker**: the screen is broken or misleading for its user, or reads as unfinished: content clipped or overlapping, an action unreachable on a phone, sideways scroll, text below contrast, keyboard focus invisible, a missing loading, empty or error state for data the screen fetches, invented data or proof shown as real, a hand-rolled control without keyboard support where the project has a component, a new look that ignores the established design system.
+- **Should fix**: a real craft gap a design lead would call out while the screen still works: no clear focal point, weak hierarchy, an accent used decoratively, a ragged row, an inconsistent radius or spacing value, missing hover or press feedback, a delta coloured up/down instead of good/bad.
+- **Note**: minor; mention once.
+
+Approval bar: the screen passes when it has no blockers, it uses the project's components and tokens, every data block has its states, and the phone layout works. Craft and taste gaps are reported as should-fix items and never fail a review step on their own.
+
+## Step 7: Act
+
+**Code step.** Fix blockers, then should-fix items, from the decision rather than by nudging values (re-derive the focal point or the spacing, do not patch around it). Re-render the affected screens and look again. Stop after three rounds or when a round finds nothing a stranger would notice. List anything left in the report.
+
+**Review step.** Do not change product code. Call `submit_verdict` once: `passed: false` if any blocker survives, otherwise `passed: true` (should-fix items and notes go in the report without failing the step).
+
+## Report format
+
+```
+Design review: <screens>, <widths and states rendered> (or: rendered check did not run, because ...)
+Design sources: <files>; assumptions: <...>
+
+Blockers
+1. <what is wrong>. Evidence: <screenshot name, width, state> / <file:line>. Cost: <who it hurts and how>. Fix: <one correction in project terms>.
+
+Should fix
+1. ...
+
+Notes
+- ...
+
+What works: <two or three things to keep>
+Not checked: <states or widths that could not be rendered, with the reason>
+Screenshots: <temp directory path>
+```
+
+Prioritize: hierarchy and focal point, then type and colour, then surfaces, layout and rhythm, then states and polish, then content. A short review naming the three things that hold the design back beats forty nitpicks.
+
+Related: `design-critic` agent (an independent second look), `interface-design`, `app-screens`, `avoiding-generic-ai-design`, `interface-polish`, `motion-design`, `web-interface-guidelines`, `ui-testing`, `accessibility`.
+
+Sources: adapted from Dammyjay93/interface-design design-review (MIT, changed: no render widget, verdict via submit_verdict, fixes only in code steps), ibelick/ui-skills improve-ui evidence and falsification rules (MIT, changed: no "ask which findings to plan" step; code steps fix, review steps report), Leonxlnx/taste-skill critique reference (MIT, changed: headless screenshots described in words instead of the bundled inspector) and pbakaus/impeccable audit and critique references (Apache-2.0, changed: rewritten, no detector, storage or ask steps).

package/library/skills/design-review/references/critique-passes.md

@@ -0,0 +1,101 @@
+# Critique passes
+
+Read this when judging screenshots. Make each pass on its own; do not blend them. Write the answers down: a critique you only think through drifts toward approving your own work.
+
+Judge the pictures. If a problem shows in a screenshot, it is real, whatever the code says. Judge against the product's own design language (step 2 of the main skill), not a generic ideal.
+
+## The whole screen first
+
+Open the desktop first screen, then the full page, then the phone.
+
+1. **One second, then five.** Glance and look away: what did you see? There should be one answer (a word, a number, an object). If the answer is "a screen", there is no focal point. Then give it five seconds as a stranger: can you say what this is, who it is for and what to do next?
+2. **Squint.** Blur your attention until text becomes grey bars. The screen should reduce to two or three masses with clear size differences, in the right order. Many similar masses mean everything is medium and nothing leads.
+3. **Cover the name.** Could this screen belong to a competitor or another industry? If swapping the product name and one noun gives an equally valid screen, the free choices were defaulted.
+4. **Edges.** Follow the left edge of every text block down the screen. Count the distinct x positions: two or three, reused on purpose, is composed; six means things were placed one at a time. Check right edges of rows of cards too.
+5. **Space and frame.** Related things close, unrelated far. Gaps between sections clearly larger than gaps inside them. Any hole (empty by accident, beside a short column or under a removed element) rather than a rest (empty by decision)? Equal outer margins? A section using half the width with the other half empty?
+6. **Type.** Is the jump from body to title decisive? More than five or six sizes? Weights doing hierarchy work, or size alone? A heading with one orphan word on its last line? Paragraphs wider than about 75 characters? Text in a grey too light to read?
+7. **Colour.** Name the proportions: what holds most of the surface, what supports, where the accent is. An accent in ten places means nothing; on the one action and one detail it means "here". Is colour carrying meaning (status, selection, data) or decorating?
+8. **Sameness.** Write one word for each block's layout (split, list, table, grid, statement). The same word three times in a row is the template showing, unless the blocks really are peers.
+9. **Phone.** Is the phone layout a composition of its own (navigation folded, its own line breaks, the first screen still one clear thing), or the desktop squeezed? Anything running off the edge, a row scrolling sideways, a tap target smaller than 44px?
+10. **Collisions.** Anything overlapping a heading, a label or a button at any width? Text clipped by its container? A sticky header covering focused content?
+11. **Substance.** Does every block deliver its information completely and at a readable size? Is the primary action a real button on the first screen? Is any content invented (metrics, customers, quotes) or placeholder text left in?
+
+## The lenses
+
+Then one lens at a time, asking each time: was this decided, or defaulted?
+
+- **Hierarchy.** Name the focal element. Does it win through size, weight, contrast or space? Is everything else demoted (secondary actions quieter, metadata muted)? Can you tell primary, secondary and metadata apart without reading?
+- **Typography and colour.** A real scale or near-equal sizes? A text-colour ramp (primary, secondary, muted) or just "text" and "grey text"? Tabular figures on numbers that update or align? One accent with a job?
+- **Surfaces and depth.** One depth strategy (borders, tone steps or shadows), held everywhere? Borders findable but not loud? Nested radii concentric? Shadows only on floating layers?
+- **Layout and rhythm.** Tight inside groups, generous between them? Shared edges? A grid that fits the item count, no orphan cells, no stretched cards with blank bands?
+- **States and polish.** Hover, focus, active, disabled on every control? Loading, empty, error, long content on every data block? Hit areas? Press feedback? Motion short and purposeful?
+- **Content and honesty.** Every visible string read as a user would: do the title, body and numbers tell one coherent story? Do numbers add up and agree where shown twice? Copy in the product's voice, sentence case unless the product does otherwise?
+- **System fit.** Uses the project's components, tokens and patterns? Looks like it shipped with its sibling screens? No hand-rolled control where the project has one?
+
+## Extra questions for app screens
+
+From `app-screens`:
+
+1. Is the screen's one question answered by the biggest thing on it, and is that read first?
+2. Do all blocks share the screen's edges, with no dead strip, orphan cell or stretched card?
+3. Is colour only on data, status and the one primary action?
+4. Do numbers add up, line up digit for digit, and name their baseline?
+5. Is every zero a zero and every missing value a dash?
+6. Does every legend swatch match its mark, with no colliding labels?
+7. On the phone, is navigation folded and does each block still answer its question?
+8. Is the most frequent job one click from the first screen?
+
+## Extra questions for marketing pages
+
+- Does the first screen carry a clear title in the page's `h1`, a sentence saying what this is, and one primary action?
+- Does every section have a heading that names it, and a composition different from its neighbours?
+- Is each screen of the desktop page full (one dominant thing and its content), not a narrow column of small text with dead ground either side?
+- Is every image doing a job (showing the product, proving a claim), with consistent crops? Any grey boxes or fake dashboards?
+- Does the idea carry past the first screen into pricing, FAQ and footer, or do they become stock blocks?
+
+## Cognitive load
+
+Count the failures; two or three mean the screen needs simplifying, four or more is a blocker for a task screen:
+
+- **Single focus**: the main task can be done without competing elements pulling attention.
+- **Chunking**: information comes in groups of about four or fewer.
+- **Grouping**: related items are visibly together.
+- **Visible priority**: it is immediately clear what matters most.
+- **One decision at a time**: the person is not asked to read, decide and navigate at once.
+- **Few choices**: about four or fewer options at a decision point (one primary action, one or two secondary, the rest in a menu).
+- **No memory bridge**: nothing from a previous screen has to be remembered to act here.
+- **Progressive disclosure**: rare detail is revealed when needed, not shown upfront.
+
+## Writing it down
+
+```
+Round n
+Seen in one second: ...
+Focal element: ... (wins / does not win, because ...)
+Layout words by block: header=... / list=... / ...
+Problems (most visible first), each with screenshot and fix:
+1. ...
+2. ...
+3. ...
+```
+
+Name problems the way a designer would to a colleague: "the supporting text starts 24px left of the title's edge", "the empty state is the third bordered box in a row", "on the phone the Save button sits under the fold". "Could be more polished" is not a finding.
+
+## What to fix first
+
+Later items cannot rescue earlier ones:
+
+1. The focal point and hierarchy: make the big thing bigger and the small things fewer.
+2. Layout: shared edges, spacing between and within groups, holes, grid fit.
+3. Typography: scale contrast, line breaks, measure.
+4. Colour: proportions and accent discipline.
+5. States and details: focus, hover, empty, error, small alignments, phone refinements.
+6. Motion, last.
+
+When removing something leaves a gap, close the gap or enlarge what remains; do not refill it with an ornament.
+
+## When to stop
+
+At most three rounds of critique, fix the top three, re-render, critique. Stop early when a round finds nothing a stranger would notice. If problems remain after round three, list them plainly in the report; do not round up.
+
+Sources: adapted from Leonxlnx/taste-skill references/critique.md and app-screens.md (MIT, changed: scoring and caps tied to its inspector removed, product-screen questions added), Dammyjay93/interface-design design-review lenses (MIT) and the cognitive load checklist in pbakaus/impeccable critique reference (Apache-2.0, changed: rewritten).

package/library/skills/design-review/references/screenshot-procedure.md

@@ -0,0 +1,121 @@
+# Rendering screens for a design check
+
+Read this when you need screenshots of changed screens at desktop, tablet and phone widths, and their key states. The output is pictures you open with the Read tool and judge.
+
+## Ground rules
+
+Everything about running the app comes from the `ui-testing` skill and holds here too: headless only, the project's own start command on a free port, no new dependencies or browser downloads (if the project has no Playwright but `TAMSENSE_PLAYWRIGHT` is set, the headless check uses the `playwright-core` and browser the TAMsense runner installed outside the project), outputs only in a new folder under the OS temp directory, nothing written to shared systems, the server stopped at the end by its process id (never kill processes by name: other programs on the computer may be using the same runtime), `git status` clean. In a review step, also change nothing in the repository (no fixtures, seed edits or config): states come from intercepting responses in the browser.
+
+If the project uses Storybook for the changed components, story URLs (`/iframe.html?id=<story-id>`) are often the quickest way to see each state; render them the same way.
+
+In a TAMsense run the browser is recorded for the task too: open contexts through the recorder with a title and a purpose, as [the ui-testing recording reference](../../ui-testing/references/recording.md) shows. For a design check the title names the variant and the purpose names the question, for example "Design option 2" and "Denser table for the invoices list, compared with option 1". Mark each state as you reach it (`mark('Empty state')`, `mark('Error state')`), and add `video: true` when the screen draws on a canvas, shows a map or a video, or embeds another site.
+
+## What to capture
+
+For each changed screen:
+
+| Width | Name |
+|---|---|
+| 1440 | desktop |
+| 768 | tablet |
+| 390 | phone |
+
+At each width: the first screen (what is visible without scrolling) and the full page. For pages taller than about four screens, also capture screen-height slices, because one very tall image is hard to judge.
+
+Then the states the change affects, at desktop and phone at least:
+
+- **Empty**: the endpoint returns no items.
+- **Loading**: the endpoint does not answer while the screenshot is taken.
+- **Error**: the endpoint returns a 500 (and a 403 if permissions matter).
+- **Long content**: the real response with worst-case values swapped in (long names, unbreakable emails, big numbers, missing optional fields; see `interface-polish`).
+- **Interaction**: hover on the primary action, keyboard focus on the first controls (press Tab), an open menu or dialog if the change adds one.
+- **Theme**: dark mode if the product supports it; reduced motion if the change adds motion.
+
+## Using the ui-testing headless check
+
+Use the script in the `ui-testing` skill's `references/headless-check.md`, written to your temp folder, with these settings:
+
+- `CONFIG.widths`: `[1440, 768, 390]`.
+- `CONFIG.paths`: the routes of the changed screens.
+- `CONFIG.title` and `CONFIG.purpose`: the variant and the question this render answers ("Design option 1", "Checking the billing page after the redesign").
+- If the screens need a signed-in user, follow the auth section of `ui-testing` (a storage state saved in the temp folder, passed to `browser.newContext`).
+- If `CHROME_PATH` is set, add `executablePath: process.env.CHROME_PATH` to the launch options.
+- For dark mode, add `colorScheme: 'dark'` to `browser.newContext`; for reduced motion, `reducedMotion: 'reduce'`.
+
+Its own screenshot is the full page in the final state of `steps`. Capture the first screen and the states inside `steps`, and leave the page in its normal state at the end:
+
+```js
+async function steps(page, { path, width, mark }) {
+    const slug = path.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '') || 'home'
+    const shot = async (state) => {
+        await mark(`${state} state`)
+        await page.screenshot({
+            path: join(CONFIG.outDir, `${slug}-${width}-${state}.png`),
+            animations: 'disabled',
+        })
+    }
+
+    await page.evaluate(async () => { await document.fonts.ready })
+    await shot('fold')
+    if (path !== '/billing') return
+
+    await page.getByRole('button', { name: 'Create invoice' }).hover()
+    await shot('hover')
+    await page.keyboard.press('Tab')
+    await page.keyboard.press('Tab')
+    await shot('focus')
+
+    const api = '**/api/invoices**'
+
+    await page.route(api, (route) => route.fulfill({ json: { items: [], total: 0 } }))
+    await page.reload()
+    await page.getByText('No invoices').waitFor()
+    await shot('empty')
+    await page.unroute(api)
+
+    await page.route(api, (route) => route.fulfill({
+        status: 500, contentType: 'application/json', body: '{"error":"Internal error"}',
+    }))
+    await page.reload()
+    await page.getByRole('button', { name: 'Try again' }).waitFor()
+    await shot('error')
+    await page.unroute(api)
+
+    await page.route(api, () => {})
+    await page.reload({ waitUntil: 'domcontentloaded' })
+    await page.locator('[aria-busy="true"]').first().waitFor()
+    await shot('loading')
+    await page.unroute(api)
+
+    await page.route(api, async (route) => {
+        const response = await route.fetch()
+        const json = await response.json()
+        json.items[0].customer = 'Aleksandra Wiśniewska-Kowalczyk Consulting GmbH'
+        json.items[1].email = 'bartholomew.fitzgerald@northwind-industries-holdings.example.com'
+        json.items[2].amount = 12345678.9
+        await route.fulfill({ response, json })
+    })
+    await page.reload()
+    await page.getByText('Aleksandra').waitFor()
+    await shot('long')
+    await page.unroute(api)
+
+    await page.reload()
+}
+```
+
+Adapt the endpoint pattern, the response shape and the readiness checks (`waitFor` on the element that proves each state) to the real screen; find the endpoint in the code or the failed-request list of a first run. The loading route never answers on purpose, so the following `reload` discards it.
+
+If the data is rendered on the server and cannot be intercepted in the browser, use the states the project's stories, fixtures or seed data already provide. In a code step you may add a fixture where the project keeps fixtures; in a review step, list the states you could not render.
+
+## Naming and reporting
+
+Files are named `<screen>-<width>-<state>.png` (for example `billing-390-error.png`) so findings can cite them. Put the temp folder path in the report, describe what each cited screenshot shows, and delete the folder when the step ends unless the task asks to keep artifacts.
+
+When you attach screenshots to the task with `attach_screenshot`, give each a title and a purpose that say what it shows and why: "Design option 1" with "Billing page at 1440, the denser table", not "billing-1440-fold". The replays of the render are attached by themselves.
+
+## When rendering is impossible
+
+If the app needs services that are not available, the build fails, Playwright is not installed (neither in the project nor through `TAMSENSE_PLAYWRIGHT`), or no browser can run: say exactly that in the report, review from the code, and mark every visual finding as inferred rather than seen.
+
+Sources: written for this library on top of the `ui-testing` headless check; the three widths and the screenshot-first critique follow Leonxlnx/taste-skill (MIT) inspect and critique references, described in words instead of shipping its inspector.