@tamsensedev/runner 0.0.0-stage → 0.2.1

package/library/skills/false-positive-check/references/standard-verification.md

@@ -0,0 +1,80 @@
+# Standard Verification
+
+Linear single-pass checklist for straightforward bugs. No task tracking: work through each step sequentially and document findings inline.
+
+## Escalation Checkpoints
+
+Two points in this checklist may trigger escalation to [deep-verification.md](deep-verification.md):
+
+1. **After Step 1 (Data Flow)**: Escalate if 3+ trust boundaries, callbacks/async control flow, or ambiguous validation chain
+2. **After Step 5 (Devil's Advocate)**: Escalate if any question produces genuine uncertainty you cannot resolve
+
+When escalating, hand off all evidence gathered so far: deep verification will continue from where you left off.
+
+## Checklist
+
+### Step 1: Data Flow
+
+Trace data from source to the alleged vulnerability sink.
+
+- Map trust boundaries crossed (internal/trusted vs external/untrusted)
+- Identify all validation and sanitization between source and sink
+- Check API contracts: many APIs have built-in bounds protection that prevents the alleged issue
+- Check for environmental protections (compiler, runtime, OS, framework) that prevent exploitation entirely (not just raise the bar)
+- Apply class-specific checks from [bug-class-verification.md](bug-class-verification.md)
+
+**Key pitfall**: Analyzing the vulnerable code in isolation. Conditional logic upstream may make the vulnerability mathematically unreachable. Trace the full validation chain.
+
+**Escalation check**: If you found 3+ trust boundaries, callbacks or async control flow in the path, or an ambiguous validation chain: escalate to deep verification.
+
+### Step 2: Exploitability
+
+Prove the attacker can trigger the vulnerability.
+
+- **Attacker control**: Prove the attacker controls data reaching the vulnerable operation. Internal storage set by trusted components is not attacker-controlled.
+- **Bounds proof**: For integer/bounds issues, create an explicit algebraic proof using the template in [evidence-templates.md](evidence-templates.md). Verify: IF validation_check_passes THEN bounds_guarantee_holds.
+- **Race feasibility**: For race conditions, prove concurrent access is actually possible. Single-threaded initialization and synchronized contexts cannot have races.
+
+### Step 3: Impact
+
+Determine whether exploitation has real security consequences.
+
+- Distinguish real security impact (RCE, privesc, info disclosure) from operational robustness issues (crash recovery, cleanup failure)
+- Distinguish primary security controls from defense-in-depth. Failure of a defense-in-depth measure is not a vulnerability if primary protections remain intact.
+
+### Step 4: PoC Sketch
+
+Create a pseudocode PoC showing the attack path. Executable and unit test PoCs are optional for standard verification; in review and test steps they run only from a temp directory outside the repository and never against live services (see the ground rules in SKILL.md).
+
+```
+Data Flow: [Source] → [Validation?] → [Transform?] → [Vulnerable Op] → [Impact]
+Attacker controls: [what input, how]
+Trigger: [pseudocode showing the exploit path]
+```
+
+See [evidence-templates.md](evidence-templates.md) for the full PoC template.
+
+### Step 5: Devil's Advocate Spot-Check
+
+Answer these 7 questions. If any produces genuine uncertainty, escalate to deep verification.
+
+**Against the vulnerability:**
+
+1. Am I seeing a vulnerability because the pattern "looks dangerous" rather than because it actually is? (pattern-matching bias)
+2. Am I incorrectly assuming attacker control over trusted data? (trust boundary confusion)
+3. Have I rigorously proven the mathematical condition for vulnerability can occur? (proof rigor)
+4. Am I confusing defense-in-depth failure with a primary security vulnerability? (defense-in-depth confusion)
+5. Am I hallucinating this vulnerability? LLMs are biased toward seeing bugs everywhere: is this actually real or am I pattern-matching on scary-looking code? (LLM self-check)
+
+**For the vulnerability (always ask: false-negative protection):**
+
+6. Am I dismissing a real vulnerability because the exploit seems complex or unlikely?
+7. Am I inventing mitigations or validation logic that I haven't verified in the actual source code? Re-read the code after reaching a conclusion.
+
+**Escalation check**: If any question above produces genuine uncertainty you cannot resolve with the evidence at hand: escalate to deep verification.
+
+### Step 6: Gate Review
+
+Apply all six gates from [gate-reviews.md](gate-reviews.md) and all 13 items from [false-positive-patterns.md](false-positive-patterns.md) to reach a verdict.
+
+Part of the `false-positive-check` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/fp-check (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: read-only rule for proofs of concept, punctuation.

package/library/skills/focused-implementation/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: focused-implementation
+description: Use when implementing a feature, change or fix in the code step, especially one that touches several files: turn the task into checkable goals, build it in small working slices, keep every changed line tied to the task, and record assumptions and side findings for the report instead of asking.
+---
+
+# Focused implementation
+
+The reviewer should be able to read your diff and see the task in every line. Nobody answers questions during the run, so you decide, write the decision down, and keep going.
+
+Start with `project-orientation` if you have not done it in this run. When the spec has several changes, write the plan first with `implementation-plan`.
+
+## 1. Turn the task into goals you can check
+
+Before writing code, write a short list:
+
+```
+Goal: invoices show the VAT amount per line
+Checks:
+- [ ] unit test: 3 lines at 20% VAT give per-line VAT 2.00, 4.00, 0.50
+- [ ] invoice page renders a VAT column (component test or screenshot)
+- [ ] existing invoice tests still pass
+Assumptions:
+- Rounding per line, half up, as in src/money/round.ts (spec does not say)
+```
+
+- Take the acceptance criteria from the spec as they are. Each one becomes at least one check.
+- A vague goal ("make it work", "improve") becomes a concrete check you can run.
+- Where the task or spec is ambiguous, pick the reading that best matches the spec, the existing code and the smallest change. Write it under Assumptions. Do not stop to ask; `task-interview` says which open points deserve a question in the report.
+- If the task as written is impossible or contradicts the code (an API that does not exist, a field that is not stored), do the closest useful thing that stays inside the task, and explain the gap in the report.
+
+## 2. Choose the simplest design that meets the goals
+
+- Prefer the plain, obvious solution: a function call over an event bus, two similar components over a configurable framework for two cases. Three similar lines beat a premature abstraction.
+- No speculative features, options, flags or extension points that the task does not need.
+- Reuse what the project already has (helpers, components, error types, query builders) before writing new ones.
+- For a change that spans many modules or needs a real design decision, ask the `code-architect` agent for one concrete blueprint, then follow it unless you find a reason not to (and say why).
+
+## 3. Build in thin slices
+
+Work in slices that each leave the project working:
+
+1. Implement the smallest complete piece (vertical: from storage to API to UI for one case, rather than all of the storage first).
+2. Test it: write the test first where the project has tests (`test-driven-development`), then run the tests near the change.
+3. Check it builds and type-checks.
+4. Move to the next slice.
+
+Rules:
+- Do not write more than roughly 100 lines without running something.
+- Put the riskiest or least certain piece first, so a dead end shows up early.
+- Never leave the build broken between slices.
+- Commit a slice when it is green if that makes the history clearer (`clean-commits`); one commit at the end is also fine.
+- New behaviour defaults to the safe, conservative option (off, opt-in, read-only) unless the task says otherwise.
+
+## 4. Keep changes surgical
+
+Every changed line should trace back to the task.
+
+- Do not reformat, rename, reorder imports or "modernise" code you are not otherwise changing.
+- Do not delete comments, code or tests you do not fully understand.
+- Match the surrounding style even if you would write it differently.
+- Clean up what your own change made unused (imports, helpers, variables). Leave older dead code alone.
+- When you notice something wrong outside the task, do not fix it. Add it to a "Noticed, not changed" list for the report:
+
+```
+Noticed, not changed:
+- src/utils/format.ts: unused import of `dayjs` (unrelated)
+- Login form shows the raw server error text (separate task)
+```
+
+Exception: if the task cannot be done correctly without touching it (the bug you are fixing lives there), change it and say why.
+
+## 5. Flag these in the report
+
+Do them only when the task needs them, choose the smaller option, and list them in the report so the reviewer looks closely:
+
+- New dependencies, or upgrades of existing ones.
+- Database schema changes or migrations (follow `safe-database-changes`).
+- Changes to authentication, authorisation, sessions, CORS, uploads, rate limits, roles or permissions.
+- New external services or new kinds of stored sensitive data.
+- Changes to a public API, a shared contract, CI config or build config.
+- Deleting files, features or tests.
+- Changes in a repository that the task did not obviously involve.
+
+Never: commit secrets, edit vendored or generated files by hand (regenerate them the way the project does), weaken or delete a failing test to get green, or disable lint rules to silence your own code.
+
+## 6. Finish
+
+1. Tidy your own diff: remove debug output, leftover TODOs you created, commented-out code. For a large change, the `code-simplifier` agent can do a behaviour-preserving pass over the changed files.
+2. Run `verification-before-completion`.
+3. Commit with `clean-commits`.
+4. Write the report: what changed, how it was checked (commands and results), assumptions, flagged items, noticed-not-changed list, anything left open.
+
+## Common mistakes
+
+| Thought | What to do instead |
+|---|---|
+| "While I'm here I'll clean this up" | Note it under "Noticed, not changed". |
+| "I'll test it all at the end" | Test each slice; a bug in slice 1 makes slices 2 to 5 wrong. |
+| "Let me make it configurable, just in case" | Build what the task needs; add options when a second case exists. |
+| "The spec is unclear, I'll wait" | Pick the most reasonable reading, write it under Assumptions, continue. |
+| "This refactor is small enough to include" | Keep refactors out of feature changes unless the task needs them. |
+| "Lint fails on my line, I'll add an ignore comment" | Fix the code; ignore comments only where the project already uses them for the same case, with a reason. |
+
+Sources: addyosmani/agent-skills (MIT, commit aeac41d) incremental-implementation, plus ideas restated from the Karpathy coding guidelines. Changed: rewritten for unattended runs.

package/library/skills/implementation-plan/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: implementation-plan
+description: Use at the start of a code step when the spec or task touches more than one file or more than one repository: turn it into an ordered plan of small tasks with exact files, the interfaces passed between them, the checks that prove each one, and a review focus of the inputs no test covers yet.
+---
+
+# Implementation plan
+
+A plan is the set of decisions an implementer cannot make alone: which files, which names and signatures, which values from the spec, which tests prove each step. Write those down, nothing more. A plan longer than the code it describes has written the code instead.
+
+Start with `project-orientation` if you have not done it in this run. Keep the plan in your working notes; it does not go into the repository unless the project asks for plans there.
+
+## 1. Read the spec as the contract
+
+- The acceptance criteria (AC-1, AC-2 and so on) are the finish line. Each one must end up proven by a test or a check.
+- Out of scope is a hard limit: nothing from it goes into the plan.
+- Decisions, assumptions and the code map are settled: follow them. If the code contradicts one, note it for the report and pick the reading closest to the spec.
+- Values the spec pins (texts, limits, names, status codes) are copied verbatim into a "Constraints" list at the top of the plan.
+
+## 2. Map the files
+
+List every file you will create or change, with one line on its responsibility. Files that change together live together; follow the project's existing layout.
+
+## 3. Order the tasks
+
+Each task is the smallest unit with its own test cycle that a reviewer could accept or reject on its own:
+
+```
+Task 2: CSV export endpoint
+Files: create server/api/boards/[id]/export.get.ts; test test/boardExport.test.ts
+Consumes: canSeeBoard(userId, boardId) from server/utils/boardAccess.ts
+Produces: GET /api/boards/:id/export -> text/csv, header "Title,Status,Owner"
+Proves: AC-1, AC-2
+Steps:
+  1. Test: 3 tasks give 4 lines; no access gives 404 (fails first)
+  2. Implement exportCsv(boardId: number): string and the route
+  3. Run: pnpm test test/boardExport.test.ts -> 2 passed
+```
+
+- Order by dependency: a task uses only what earlier tasks or the existing code provide. Put the riskiest or least certain task as early as its dependencies allow.
+- **Interfaces:** write Consumes and Produces with exact names, parameters, return types and data shapes. This is how the next task learns the names; check that every name used later is produced earlier.
+- **Steps:** each step is one action with a checkable result, and lets you write exactly one reasonable thing. Lines that decide nothing ("handle edge cases", "add validation", "write tests") are gaps: replace them with the case, the rule or the test name.
+- **Tests at the highest seam** that covers the behaviour: an endpoint, a page or a public function, not private helpers. Follow `test-driven-development`.
+
+## 4. Verification
+
+Split it in two:
+
+- **Automated:** the exact commands (tests, type check, lint, build) and what passing looks like. Take them from the spec's test plan and from `project-orientation`.
+- **Manual:** what a person does and sees, naming the page or command. For interface work, the screens to render with `ui-testing` or `design-review`.
+
+Map every acceptance criterion to the task and the check that proves it. A criterion without a check is a gap: add the test.
+
+## 5. Review focus
+
+Write up to five input classes or failure modes the spec implies but no planned test exercises, most likely to bite a person first: an empty list, a very long name, a second click, an expired session, a slow network. The spec's silence on an input is not permission for that input to break the program. For each line, add the test to the task that owns the code, or say in the report why it is left.
+
+## 6. Self-check before coding
+
+1. **Coverage:** every criterion has a task and a check; every task proves a criterion.
+2. **Names:** names and signatures match between Produces and Consumes.
+3. **Scope:** nothing from out of scope, nothing the spec did not ask for.
+4. **Proportion:** the plan is shorter than the code it describes.
+
+Then build it with `focused-implementation`, one task at a time, and finish with `verification-before-completion`. Put the plan's Review Focus and any deviations from the spec in the report.
+
+Sources: adapted from obra/superpowers writing-plans (MIT, commit b739a8a), the plan template and ready-for-development rules of bmad-code-org/BMAD-METHOD (MIT, commit 61e01f8), humanlayer/humanlayer create_plan (Apache-2.0, commit 99abe67) and mattpocock/skills to-spec testing seams (MIT, commit 5beb35b). Changed: condensed into one process for unattended code steps, the plan stays in working notes, execution choices removed.

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`. When you try several directions, number them ("Design option 1", "Design option 2") in the recordings and in the screenshots you attach, each with a purpose that says what it tries.
+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).