@tamsensedev/runner 0.0.0-stage → 0.1.0

package/library/skills/accessibility/references/wcag-checks.md

@@ -0,0 +1,168 @@
+# WCAG 2.2 checks, patterns and scripts
+
+Read this when you need the exact criterion for a finding, a correct markup pattern for a fix, a contrast calculation, or the keyboard pass for the headless check.
+
+## Level A and AA criteria that matter most for web apps
+
+| Criterion | Level | What to check |
+|---|---|---|
+| 1.1.1 Non-text Content | A | Alt text on meaningful images, names on icon buttons, `alt=""` on decorative images |
+| 1.2.2 Captions (Prerecorded) | A | Videos with speech have captions |
+| 1.3.1 Info and Relationships | A | Headings, lists, tables, labels and groups exist in markup, not only in styling |
+| 1.3.2 Meaningful Sequence | A | DOM order matches reading order (CSS `order` and grid placement can break it) |
+| 1.3.5 Identify Input Purpose | AA | `autocomplete` on fields about the user |
+| 1.4.1 Use of Color | A | Colour is not the only way information is shown |
+| 1.4.3 Contrast (Minimum) | AA | 4.5:1 text, 3:1 large text (24 px, or 18.66 px bold) |
+| 1.4.4 Resize Text | AA | Usable at 200% zoom |
+| 1.4.10 Reflow | AA | No two-dimensional scrolling at 320 CSS px wide (except maps, tables, editors) |
+| 1.4.11 Non-text Contrast | AA | 3:1 for control boundaries, focus indicators, meaningful icons and graphics |
+| 1.4.12 Text Spacing | AA | No clipped text when line and letter spacing increase (avoid fixed heights on text boxes) |
+| 1.4.13 Content on Hover or Focus | AA | Tooltips and popovers can be dismissed (Escape), hovered and stay until dismissed |
+| 2.1.1 Keyboard | A | Every function works with the keyboard |
+| 2.1.2 No Keyboard Trap | A | Focus can always move away |
+| 2.1.4 Character Key Shortcuts | A | Single-key shortcuts can be turned off or only work when a component has focus |
+| 2.2.1 Timing Adjustable | A | Time limits can be extended |
+| 2.2.2 Pause, Stop, Hide | A | Moving or auto-updating content can be paused |
+| 2.3.1 Three Flashes | A | Nothing flashes more than three times per second |
+| 2.4.1 Bypass Blocks | A | Skip link or landmarks |
+| 2.4.2 Page Titled | A | Descriptive, unique titles per route |
+| 2.4.3 Focus Order | A | Order preserves meaning; dialogs and route changes manage focus |
+| 2.4.4 Link Purpose (In Context) | A | Link text says where it goes |
+| 2.4.6 Headings and Labels | AA | Headings and labels describe their content |
+| 2.4.7 Focus Visible | AA | A visible focus indicator |
+| 2.4.11 Focus Not Obscured (Minimum) | AA | Focused element not fully hidden by sticky or overlay content |
+| 2.5.1 Pointer Gestures | A | Multi-finger or path gestures have a single-pointer alternative |
+| 2.5.2 Pointer Cancellation | A | Actions fire on release, not on press |
+| 2.5.3 Label in Name | A | Accessible name contains the visible label |
+| 2.5.7 Dragging Movements | AA | Dragging has a single-pointer alternative |
+| 2.5.8 Target Size (Minimum) | AA | 24 by 24 CSS px, or enough spacing |
+| 3.1.1 Language of Page | A | `<html lang>` |
+| 3.1.2 Language of Parts | AA | `lang` on passages in another language |
+| 3.2.1 On Focus / 3.2.2 On Input | A | Focusing or changing a field does not navigate or submit unexpectedly |
+| 3.2.3 Consistent Navigation | AA | Navigation in the same order across pages |
+| 3.2.6 Consistent Help | A | Help links or contact options in the same place across pages |
+| 3.3.1 Error Identification | A | Errors described in text and tied to the field |
+| 3.3.2 Labels or Instructions | A | Labels and format hints |
+| 3.3.3 Error Suggestion | AA | Say how to fix it when known |
+| 3.3.4 Error Prevention (Legal, Financial, Data) | AA | Review, confirm or undo for important submissions |
+| 3.3.7 Redundant Entry | A | Do not ask again for data entered earlier in the same process |
+| 3.3.8 Accessible Authentication (Minimum) | AA | No memory or puzzle test without an alternative; allow paste and password managers |
+| 4.1.2 Name, Role, Value | A | Custom controls expose name, role and state |
+| 4.1.3 Status Messages | AA | Status updates announced without moving focus |
+
+Criteria 2.4.12, 2.4.13 and 3.3.9 are AAA and new in 2.2; 4.1.1 Parsing was removed in 2.2, so do not report it.
+
+## Patterns
+
+**Visually hidden text** (for screen readers only):
+
+```css
+.visually-hidden {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+  overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;
+}
+```
+
+Use the project's existing utility if it has one (`sr-only`, `visually-hidden`, a component).
+
+**Dialog:** prefer native `<dialog>` opened with `showModal()`, which makes the rest of the page inert and closes on Escape. Give it a name (`aria-labelledby` pointing at its heading), move focus inside on open, and return focus to the trigger on close. A custom dialog needs `role="dialog"`, `aria-modal="true"`, a focus trap, Escape handling and an inert or `aria-hidden` background.
+
+**Skip link:**
+
+```html
+<a class="skip-link" href="#main">Skip to main content</a>
+<main id="main" tabindex="-1">...</main>
+```
+
+with CSS that keeps it off-screen until it receives focus.
+
+**Error summary on submit:** a heading like "2 problems need fixing" with links to each invalid field, focused after a failed submit; each field keeps its own inline error with `aria-describedby`.
+
+**Tabs:** `role="tablist"` containing `role="tab"` elements with `aria-selected` and `aria-controls`; panels with `role="tabpanel"` and `aria-labelledby`. Only the active tab has `tabindex="0"`; arrow keys move between tabs.
+
+**Disclosure and menus:** a button with `aria-expanded` that toggles the controlled region. Do not use `role="menu"` for site navigation; it promises application-style keyboard behaviour.
+
+**Live region:** render the container empty on page load, then change its text:
+
+```html
+<div role="status" class="visually-hidden" id="announcer"></div>
+```
+
+Clearing it before writing the same message again makes screen readers repeat it.
+
+**Reduced motion:**
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+Or scope it to the animations the change adds, if the project handles motion per component.
+
+## Contrast from design tokens
+
+When colours come from tokens or CSS variables, compute the ratio instead of guessing. Run with `node -e` or in a temp file:
+
+```js
+function luminance(hex) {
+  const value = hex.replace('#', '')
+  const full = value.length === 3 ? value.split('').map(c => c + c).join('') : value
+  const [r, g, b] = [0, 2, 4].map(i => parseInt(full.slice(i, i + 2), 16) / 255)
+    .map(c => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+function contrast(foreground, background) {
+  const [light, dark] = [luminance(foreground), luminance(background)].sort((a, b) => b - a)
+  return (light + 0.05) / (dark + 0.05)
+}
+console.log(contrast('#6b7280', '#ffffff').toFixed(2))
+```
+
+Semi-transparent colours must be blended with their real background first. For dark mode, check both themes.
+
+## Keyboard pass in a headless browser
+
+Use as the `steps` function of the `ui-testing` headless check. It records the first stops of the Tab order, whether each one shows a focus style, and whether Escape closes an open dialog. The focus-style test is a heuristic (it looks for an outline or box shadow); confirm doubtful cases on a screenshot.
+
+```js
+async function steps(page) {
+    const stops = []
+    for (let i = 0; i < 25; i++) {
+        await page.keyboard.press('Tab')
+        const stop = await page.evaluate(() => {
+            const el = document.activeElement
+            if (!el || el === document.body) return null
+            const style = getComputedStyle(el)
+            const hasOutline = style.outlineStyle !== 'none' && parseFloat(style.outlineWidth) > 0
+            const hasShadow = style.boxShadow && style.boxShadow !== 'none'
+            const label = el.getAttribute('aria-label') || el.innerText || el.getAttribute('title') || el.getAttribute('name') || ''
+            return {
+                element: el.tagName.toLowerCase() + (el.getAttribute('role') ? `[role=${el.getAttribute('role')}]` : ''),
+                name: label.trim().replace(/\s+/g, ' ').slice(0, 60),
+                visibleFocus: Boolean(hasOutline || hasShadow),
+                inViewport: (() => { const r = el.getBoundingClientRect(); return r.bottom > 0 && r.top < innerHeight })(),
+            }
+        })
+        if (!stop) break
+        stops.push(stop)
+    }
+    let escapeClosesDialog = null
+    const dialog = page.locator('dialog[open], [role="dialog"]').first()
+    if (await dialog.isVisible().catch(() => false)) {
+        await dialog.locator('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])').first().focus().catch(() => {})
+        await page.keyboard.press('Escape')
+        escapeClosesDialog = !(await dialog.isVisible().catch(() => false))
+    }
+    return { stops, escapeClosesDialog }
+}
+```
+
+Read the result: stops with an empty `name` are unnamed controls; `visibleFocus: false` needs a screenshot check; the order should follow the visual layout; stops that repeat in a loop inside one component suggest a trap. To test a dialog, open it in `steps` first (click its trigger), then run the same loop and check focus stays inside it and returns to the trigger after Escape.
+
+Adapted from addyosmani/web-quality-skills `skills/accessibility/references/WCAG.md` and `A11Y-PATTERNS.md` (MIT, commit afa8da942115f2961fdbfa80807ea0b232ff6c00, Copyright (c) 2026 Addy Osmani). Changed: limited to A and AA criteria relevant to web apps with "what to check" notes, patterns condensed, contrast and keyboard-pass scripts added.

package/library/skills/addressing-review-feedback/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: addressing-review-feedback
+description: Use when a code step is a rework with review comments to address: check each comment against the current code before acting, fix every valid one, explain with evidence any you do not apply, keep the reviewer's own commits, and report the outcome per comment.
+---
+
+# Addressing review feedback
+
+A rework run gets the reviewer's comments and a branch that already has the earlier work, and maybe commits from the reviewer. Nobody will answer questions, and you cannot reply on GitHub. Your answer to the reviewer is the code plus the report.
+
+Review feedback is a set of technical claims to check, not orders to apply blindly and not opinions to argue with. Verify, then act.
+
+## 1. Get the current state
+
+In each repository:
+
+```
+git log --oneline origin/<base>..HEAD
+git diff --stat origin/<base>...HEAD
+git status
+```
+
+- The current branch is the source of truth. Line numbers in the comments may refer to an older version; find the code by content, not by number.
+- Identify commits that are not from the earlier agent run (different author, or messages like "review fixes"). These are the reviewer's own changes. Keep them: do not revert, rewrite or "clean up" them unless a comment explicitly asks for that.
+- Never rewrite history: no rebase, amend, reset or force push. Add new commits on top.
+
+## 2. List every comment
+
+Read all comments before changing anything. Items can depend on each other, and a later comment can change how you read an earlier one.
+
+Number them and restate each as a concrete technical requirement:
+
+```
+C1 "this will blow up for guests" -> getCart() must handle a null user (src/cart.ts, getCart)
+C2 "use the existing money helper" -> replace manual rounding with formatMoney() in Invoice.vue
+C3 "add a test for the empty state" -> component test: no items shows the empty message
+```
+
+A comment that holds several requests becomes several items.
+
+## 3. Verify each item against the code
+
+For each item, before editing:
+
+- Is the claim true in the current code? Reproduce it if it is a bug (a test, a quick run). It may already be fixed by a reviewer commit.
+- Would the suggested change break something else? Search for other callers, run the related tests.
+- Is there a reason the code is the way it is (a comment, a test, the spec, a platform constraint)?
+- Does the suggestion fit this codebase and its conventions?
+- For "do it properly" or "add X" requests, check whether X is used: search the code. Building an unused feature is not a fix.
+
+If a comment is unclear, choose the reading that best matches the reviewer's evident intent, the spec and the code. Write the reading you chose in the report. Do not stop and do not skip it.
+
+## 4. Decide and act
+
+Each item ends in one of these states:
+
+| State | When |
+|---|---|
+| Fixed | The comment is valid; you changed the code and checked it. |
+| Already done | The current code already does it (say where, for example a reviewer commit). |
+| Fixed differently | The concern is valid but the suggested change is wrong here; you solved the concern another way. |
+| Not changed | The comment is wrong for this code, conflicts with the spec, or would break something. Give the evidence. |
+| Partly done | You could do only part of it (needs credentials, out of scope of the task). Say what is left. |
+
+Default to fixing. Use "Not changed" only with concrete evidence (file:line, test output, a spec quote), never because the change is inconvenient. When the reviewer and the spec disagree, follow the reviewer if the change is safe and within the task, and note the conflict.
+
+Order of work:
+1. Blocking items: broken behaviour, security, data loss.
+2. Simple items: naming, imports, small corrections.
+3. Larger items: logic changes, refactors.
+
+Work one item at a time and run the related tests after each. Use `systematic-debugging` for bug reports and `test-driven-development` when a comment asks for new behaviour or reports a bug that a test could catch.
+
+Stay within the comments and what they directly imply. A rework is not the time for unrelated improvements; list those under "Noticed, not changed".
+
+## 5. Verify everything and commit
+
+Run `verification-before-completion` across the whole branch, not only the lines you touched: a fix for one comment can break another part. Commit with `clean-commits`; one commit per comment or one commit for the whole round both work, as long as messages say what was addressed.
+
+## 6. Report per comment
+
+Plain technical statements. No thanks, no "great catch", no "you're absolutely right": the reader wants to know what changed.
+
+```
+Review comments
+C1 Fixed: getCart() returns an empty cart for guests (src/cart.ts:31), test "guest gets empty cart" added, failed before.
+C2 Fixed: Invoice.vue uses formatMoney() for totals and line prices.
+C3 Fixed: test "shows the empty message when there are no items" in Invoice.test.ts.
+C4 Not changed: the comment suggests removing the legacy date parser, but importInvoices() still calls it for CSV files (src/import/csv.ts:88); removing it breaks 4 tests in csv.test.ts.
+C5 Already done: reviewer commit 3f2a1c0 renamed the prop.
+C6 Unclear, read as "show the VAT column only for business customers" (matches spec rule 2): done in InvoiceTable.vue.
+
+Checks
+- pnpm test -- --run: 220 passed, 0 failed
+- pnpm typecheck: exit 0
+```
+
+## Common mistakes
+
+| Mistake | Instead |
+|---|---|
+| Applying every suggestion without checking it | Verify against the code first; reviewers can be wrong or work from an old version. |
+| Skipping a comment silently | Every comment appears in the report with a state. |
+| Arguing without evidence | Show the file:line, the test or the spec line. |
+| Reverting or rewriting the reviewer's commits | Keep them; build on top. |
+| Fixing items in a batch and testing once at the end | One item, then its tests. |
+| Fixing only the commented lines | Look for the same problem elsewhere in your change and fix it there too. |
+| Asking questions in the report and waiting | Decide, state the reading you chose, and finish. |
+
+Sources: obra/superpowers (MIT, commit bb92a77) receiving-code-review. Changed: rewritten for unattended reworks, every question path removed.

package/library/skills/app-screens/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: app-screens
+description: Use when building or changing screens people work in: dashboards, admin and back office, analytics and reports, tables and lists with filters, inboxes and queues, forms, settings and billing, detail pages. Covers answering the screen's one question first, KPIs, charts, tables, forms, empty, loading and error states, and the phone layout.
+---
+
+# App screens
+
+An app screen is worked in, not read once. The generated version is the average of every dashboard template: a tinted sidebar, "Welcome back" with a wave, four KPI cards with icons and green deltas, a gradient area chart, a zebra table. Nothing in it is wrong and none of it was decided. Good product screens are quieter and fuller at the same time: colour on data instead of chrome, numbers set as type instead of tiles, and the product's real objects answering a real question.
+
+Follow `interface-design` for the general process. This skill adds what is specific to working screens. Defaults here come from measurements of real product screens; the project's own components, tokens and existing screens always win over them. If a sibling screen already has a table, filters or KPIs, reuse those patterns exactly.
+
+## The run
+
+Do these in order. The first three decide whether the screen is any good.
+
+### 1. Inventory the data and the jobs
+
+Write eight to twelve lines in your notes:
+
+- **Objects** the screen shows (invoices, deployments, members) and their fields, with units.
+- **Realistic magnitudes**: how many objects, typical and extreme values, and how small a new account really is.
+- **People**: who opens it, how often (a glance a day or an eight-hour session), on what device.
+- **Jobs**: what they do next from here (approve, reply, pay, redeploy), and which job is most frequent.
+- **The product's own things**: its name, the workspace or account scope, its people and recognisable objects (product photos, avatars, cover art).
+
+Use the real data source. When you need sample data (a new screen with no backend yet, a story, a test fixture), make it believable and consistent: totals computed from the rows, dates in order, a unit on every figure, small numbers for small accounts. Never "Acme", "John Doe", "User 1", lorem ipsum or vanity totals. List sample data in the report.
+
+### 2. Name the screen's one question
+
+Every screen answers one question first: "Did today's orders ship?", "Which deploy broke?", "Who is waiting for a reply?". Write it in one line. It decides:
+
+- **What is biggest.** The largest block, and the largest figure, answer that question.
+- **What comes first** in reading order.
+- **What is left out.** A block that answers no question is deleted. A few numbers may need no chart at all.
+
+Then name the screen's **one finding**: the fact in the current data that most needs attention ("3 invoices overdue, the oldest by 41 days"). Put it where it is read first (the line under the title, or the subline of the main figure), next to the action it drives.
+
+List the remaining blocks as answers to the next questions, one line each. This replaces the stock order of KPI row, big chart, two small charts, table.
+
+Three more checks:
+
+- **Everything the task names shows on the first screen** at 1440 x 900: each block's header and first rows or figure. Cap overview lists at 4 to 6 rows with "View all".
+- **The most frequent job is one click away**: a primary button in the title row, an action on the row that needs it, "View logs" on the failed item. A screen with no control for its main job reads as a report.
+- **Show the evidence beside the answer.** "Error rate 0.28%, peaked at 3.9% after deploy a3f09c1" is trusted more than the number alone.
+
+### 3. Build the shell, then the data, then the states
+
+1. **Shell first, empty**: navigation, title row, canvas with gutters. Use the project's layout components. Check it at 1440 and 390 before data goes in. Do the grid arithmetic so cards land on the canvas edges.
+2. **Data**: render every block from the data. Format every figure (separators, fixed decimals per metric, a sign on every change, units as a smaller muted suffix, tabular figures, numbers right-aligned in columns). Use the product's words for labels ("Waiting on customer", not "Status 2").
+3. **States**: for every block, its loading, empty, zero and error state; for every row and control, hover, selected, focus and disabled. Look at each in the browser.
+
+### 4. Check the screenshots
+
+Take screenshots at 1440, 768 and 390 (procedure in `design-review`) and answer in writing:
+
+1. Is the screen's question answered by the biggest thing on it, and is that read first?
+2. Does every block share the screen's edges? Any dead strip, a card stopping short, an orphan cell, a card stretched with a blank band at its foot?
+3. Is colour only on data, status and the one primary action?
+4. Do the numbers add up and line up digit for digit? Does every fact shown twice agree? Does every relative figure name its baseline ("vs last week")?
+5. Does every zero look like a zero and every missing value like a dash?
+6. Does every legend swatch match its mark? Do any labels collide?
+7. On the phone, is the navigation folded away, and does each block still answer its question?
+
+Fix the worst three, look again. Three rounds at most.
+
+## Defaults at a glance
+
+Details and numbers: [references/shell-kpis-charts.md](references/shell-kpis-charts.md) (navigation, title row, KPIs, deltas, charts), [references/tables-forms-settings.md](references/tables-forms-settings.md) (tables, lists, forms, settings, buttons) and [references/states-density-phone.md](references/states-density-phone.md) (empty, zero, loading, error, density, phone and tablet).
+
+- **Shell.** Labelled sidebar about 224 to 240px on the page background (not a dark or saturated block), active item as a neutral pill or brighter text. Product name and scope (workspace, project) at the top. A top bar only when it holds something real (search, switcher, object name).
+- **Title.** One `h1` per screen, a noun ("Invoices", the project's name), 20 to 28px. An optional one-line muted sentence about the data. Actions on the right only when real. One filled primary button per screen.
+- **KPIs.** Type, not tiles: one container split by 1px dividers, label over value, value 24 to 32px, no icons, no sparklines. Deltas optional, small, with the window in words; colour says good or bad (a rise in errors is bad), not up or down; zero change is grey.
+- **Charts.** One question, one series, one hue. Straight 2px lines, 3 to 5 faint horizontal gridlines, no y-axis line, round ticks above the maximum, flat x labels. No legend for a single series. Annotate the event that matters.
+- **Tables.** Sentence-case muted headers, no fill band, no zebra stripes, 1px row rules or none, numbers right-aligned in tabular figures, identity column widest, one status mark per row, row actions only where rows need them.
+- **Forms.** Label above the field, no placeholder-as-label, 16px between fields, one control height per context, errors inline, disabled controls say why.
+- **States.** Zero printed as zero, missing as a muted dash, empty blocks keep their frame and header with one sentence and an action, loading as a skeleton at final size, errors inside the failed block with a retry.
+- **Phone.** Navigation folds to a top bar with a menu or a bottom bar; tables become two-line lists below about 640px; at most one row of controls above a chart; the page never scrolls sideways.
+- **Motion.** Feedback only: press, hover, focus, a menu or sheet opening, a row arriving. Nothing performs an entrance on load.
+
+## Common mistakes
+
+- A grid chosen before the data: four KPI tiles in a three-column grid, a lone card beside 800px of nothing.
+- Colour on chrome (tinted nav rows, coloured tab pills, brand fill on every button) and none on the data.
+- The biggest number on the screen is not the answer to its question.
+- A KPI and a table on the same screen that disagree, or totals that do not add up.
+- A green "+100%" grown from zero; red on every negative number.
+- A full-screen error banner when one block failed.
+- Only the full-data state built.
+
+## Done when
+
+The one question and the one finding are written down and visible on the first screen; the main job is one click away; every block has its states; numbers reconcile; screenshots at three widths pass the seven questions. Report the screen's question, any sample data to replace, and anything not checked.
+
+Related: `interface-design`, `avoiding-generic-ai-design`, `interface-polish`, `design-review`, `accessibility`.
+
+Sources: adapted from Leonxlnx/taste-skill references/app-screens.md (MIT, changed: condensed; no direction library, scripts, chart helpers or house bans; project system takes precedence) and pbakaus/impeccable operate reference (Apache-2.0, changed: rewritten).

package/library/skills/app-screens/references/shell-kpis-charts.md

@@ -0,0 +1,108 @@
+# Shell, title row, KPIs and charts
+
+Read this when building navigation, a page header, headline numbers or a chart on an app screen. Numbers are measured from real product screens (desktop, 1440 to 1512px wide) and are defaults: the project's existing shell and components win.
+
+## Shell
+
+Five shapes cover almost every product:
+
+| Shell | What it is | Suits |
+|---|---|---|
+| Open plane | Labelled sidebar on the page background, separated by nothing or one 1px line; no top bar | Most tools |
+| Tinted frame, white sheet | Sidebar and top bar share one light tint (#f6f6f6 to #f9fbfc); the page sits on a white sheet inset about 8px, radius 10 to 16, a 1px edge, no shadow | B2B analytics, developer platforms |
+| Ruled T-frame | 210 to 240px sidebar and 64px top bar on one background, divided by 1px rules | Dark products, monitoring |
+| Icon rail | Unlabelled 48 to 56px rail, 16 to 18px icons, tooltip and accessible name on each | Five destinations or fewer, research views needing width |
+| No sidebar | 46 to 48px top bar over a centred 1088 to 1208px column | Reports, viewers, few destinations |
+
+**Sidebar**
+
+- Width 224 to 256px. Rows: 32px hit area on a 34px pitch (roomy: 40px on 44). Icons 16px outline at about 1.5px stroke, label 14px regular, 8 to 10px after the icon.
+- Active item: a neutral grey pill (radius about 8, inset 8px, fill about #ececec) with the label unchanged; on dark, the label brightens. A coloured left bar is rare in good products.
+- Groups: sentence-case muted labels at 12 to 13px with 24px or more above, never uppercase by default; or hairlines between groups.
+- Top: product mark and name, then the scope switcher (workspace, team, project). Bottom: settings, help, the user.
+- Counts only on queues that need action, with a clear noun ("Requests 5").
+- Nav items go to other screens, never to anchors in one long page.
+
+**Top bar**: 48px on light chrome, 64px with a rule. It holds something real: search (about 32 to 36px tall, with a shortcut hint), the switcher, or the object's name. A top bar left mostly empty is wasted.
+
+**Right rail**: a fixed column (about 320 to 384px, `1fr 384px` with a 24px gap) only for a stable secondary stream: details of the selected object, recent items.
+
+**Floating buttons**: only for the screen's one primary action, and only when they cover nothing at any width.
+
+## Canvas and title row
+
+- Fluid canvas with 24 to 40px side padding, or a centred 1100 to 1250px column for data pages. Narrower than about 900px wastes the width.
+- Title 20 to 36px from the canvas top on tools.
+- **One gutter**: the same gap horizontally and vertically (16px default). Mixed 12/16/20/24 gaps on one screen look accidental.
+- **One left edge, one right edge** from the header to the last row. Write the arithmetic down: 3 x 368 + 2 x 16 = 1136.
+- **A grid that fits the data**: choose the column count from the number of items; a lone card spans; a table of five columns or fewer pairs with another block instead of stretching to 1300px.
+- **Cards in a row share a bottom edge.** Balance by content (same number of rows in both lists); otherwise let a card keep its own height (`align-items: start`) rather than stretching with a blank band. Only an action or a total may be pinned to a stretched card's foot.
+
+**Title**
+
+- One `h1` per screen. A noun: "Analytics", "Invoices", the project or object name. A greeting only on personal homes, never with an emoji.
+- 20 to 28px at 600 (24 default). In dense tools a breadcrumb whose last item is the `h1` at 16px is fine.
+- Optional second line: one 14px muted sentence about the data (the period, the scope, the finding), never instructions about the interface.
+- Right side: real actions only, or a freshness stamp ("Updated 09:14" with a refresh button).
+- One filled primary button per screen; often near-black or the brand colour. Secondary: outlined; tertiary: text.
+
+**Tabs, filters and date range**
+
+- Date range at page level or per card, never both. A card's own period sits right-aligned in its header in a muted tone.
+- Underline tabs on a full-width 1px rule, indicator 2px, as wide as the label.
+- Segmented controls are as wide as their options; full width only below about 480px.
+- Control height in title and filter rows 32 to 36px. Scope on the left (date, then filters), utilities on the right. About 24px from the filter row to the first card.
+
+## KPIs
+
+- **Type, not tiles.** Default: one container split by 1px dividers into equal columns, label above value. Or put each headline number in the card that explains it.
+- Count matches the grid: four KPIs, four columns. One to six per row.
+- Value 24 to 32px (median about 26), label 12 to 14px muted, sentence case. Value about 1.7 times the label. Weight 400 to 600; bold for money only.
+- **The answer figure leads**: when one figure answers the screen's question (a balance, the month's revenue), it is 30 to 36px and at least 1.3 times its siblings. No other figure on the screen is larger.
+- No icon in a coloured circle, no sparkline, no tinted tile. An info icon beside the label is fine. Units as a smaller muted suffix ("5 min", "24 / 30").
+- One figure, one place: do not repeat a KPI in a legend beside it or as a panel title below.
+- KPIs can double as tabs for a chart; then the selected one gets a 2px rule or the active fill, and the others keep their values in the text colour (a grey value reads as disabled).
+
+**Deltas**
+
+- Optional. 12 to 14px, never larger than the label; text, a small glyph, or a pale pill.
+- The window in words: "vs previous 30 days".
+- **Colour says good or bad, not up or down.** Latency, errors, cost and churn are better when they fall. A change in the bad direction gets the danger colour; a good change gets the success colour or stays muted.
+- Zero or undefined change is grey. From a zero baseline write "+4 (new)", not "+100%" or ">999%". Nothing to compare: a muted dash.
+
+## Charts
+
+**Which chart for which question**
+
+| Question | Form |
+|---|---|
+| Is it moving over time? | One line; an area only with a fill of 15% or less |
+| How much per period? | Columns with square corners (at most a 4px top radius) |
+| How is it distributed? | Histogram with equal bins |
+| Who ranks? | Sorted horizontal bar list |
+| What share? | A thin ring or a 100% stacked bar, five parts at most |
+| How far to a target? | A progress bar with both ends labelled, fill at the true ratio |
+| How much of a budget is used? | A track as long as the budget, spent part filled, committed part lighter, overrun in the danger colour |
+| Has it drifted from target? | One row per part: current value as a bar with a 1px tick at the target |
+| Where? | A map with a list beside it; the list carries the magnitudes |
+
+A few numbers need no chart. Link to the analytics screen instead.
+
+**Rules**
+
+- One series per chart is normal; three at most. Switch metrics with a control rather than overlaying lines.
+- Plot height 120 to 260px (about 200 default); aspect about 2:1 to 5:1. A series flat except for one event gets at most two-thirds of the width.
+- Gridlines: 3 to 5, horizontal, 1px, faint (about #e5e5e5 on light, #2b2b2b on dark). No y-axis line; the baseline is the one stronger line. Dashed lines only in chart grids and reference lines.
+- Y ticks: 4 to 7, round even steps, top tick above the maximum, integers for counts, zero as the baseline for bars. Never a chart without a scale.
+- Axis text no larger than the data (11 to 12px muted). X labels: 4 to 8, flat, never rotated, on one regular step. Time goes on a time scale.
+- Lines 2px straight segments, no point markers except on hover. Fill none or a flat 10 to 15% tint.
+- **Colour**: one hue per chart, on the main data element (today, the current period, the bar that breaks). One subject keeps one hue across the screen. Four hues at most on a screen. Status colours only for status.
+- **Legends**: none for a single series. Otherwise five items at most, in the card header, each swatch drawn like its mark.
+- **Rings**: thin (3 to 8px stroke), no labels on slices, total in the centre or beside it, values in a table next to it.
+- **Tooltips**: plain text or a plain box, label and value on one line.
+- **Annotate the event that matters**: a spike or step more than about three times the usual change gets a 1px marker and a short label naming its cause. Reference lines (budget, SLO) are 1px dashed with the label at the end. Labels never collide with lines or each other.
+- **Forecasts** are dashed after today, with the end value labelled.
+- **Short and empty histories are drawn honestly**: the zero line, missing bars for empty periods, no padded range, no "No data" illustration.
+- Use the project's chart library and set these options on it; never ship the library's defaults (gradients, rainbow palettes, smoothing, legends for one series) unchanged.
+
+Sources: adapted from Leonxlnx/taste-skill references/app-screens.md sections 3 to 6 (MIT, changed: condensed, chart helper and inspector references removed, defaults placed under the project's system).

package/library/skills/app-screens/references/states-density-phone.md

@@ -0,0 +1,54 @@
+# States, density and the phone
+
+Read this when building the empty, zero, loading and error states of an app screen, deciding density, or laying the screen out for tablets and phones. Reuse the project's existing empty-state, skeleton and error components first.
+
+## Empty, zero, loading and error
+
+- **A real zero is printed** in the normal style: "0", "$0.00", "0%". It may be muted when the line beside it becomes the next step.
+- **Missing or not applicable is a muted dash**, at text size. A dash at headline size reads as loading.
+- **Counts follow the view.** Counts in tabs, KPIs and "12 open" are computed from the current filter and recomputed on every switch.
+- **An empty block keeps its frame and header** and adds one sentence spanning the block (in a grid, `grid-column: 1 / -1`) with the next action: "No invoices match these filters. Clear filters." Distinguish first use, no results from filters, no permission, and failure: each has its own sentence.
+- **First run** (the whole screen empty): keep the frame and title; put the first action where the data will appear; show setup progress at its true percentage if there are steps.
+- **An empty chart is drawn**: the zero line and the axis, not an illustration.
+- **An empty side card can show reference data** instead of a blank box (last week's values under "Nothing yet today").
+- **Loading**: the final layout with each value replaced by a flat muted bar at its real size (a 24px figure gets a 24px bar, rows keep their pitch). Labels and headers appear at once. No layout shift when data lands. A refresh of data already on screen keeps the old values and updates the freshness stamp. Spinners only inside the control that triggered the work.
+- **Error**: inside the block that failed, never a full-screen banner when one block failed. One sentence saying what failed and when data was last good ("Couldn't load deployments. Last updated 09:14."), and a Retry button. The danger colour on a small icon or a pale pill, not on the whole block.
+- **Stale or static data**: a freshness stamp with a refresh button; a snapshot that cannot refresh says so in one quiet notice.
+- **Limits and usage**: a bar at the true ratio with both ends labelled ("12.7k of 20k").
+- **Permissions**: read-only and no-access states say why and who can change it; rows keep their layout when actions are hidden.
+- **Red is a signal, not a texture**: one red mark per object at most, on the overdue or failing fact.
+
+## Density
+
+Choose by how the screen is used, then move three settings together: row height, padding and type size.
+
+| Density | Typical screen | Body | Rows | Card padding |
+|---|---|---|---|---|
+| Sparse (6 to 25 data points) | Home, settings, one object | 14 to 16px | 56 to 72px | 20 to 24px |
+| Medium (25 to 50) | Analytics overview, list screen | 14px | 44 to 56px | 16 to 24px |
+| Dense (100 and more) | Monitoring, trading, research, long sessions | 13px | 32 to 42px | 16px, with generous gutters between bands |
+
+- Placed space reads as calm; leftover space reads as unfinished. Emptiness from a fixed grid and repeated gaps looks deliberate; emptiness from a grid that does not fit the data looks broken.
+- Design for the data a new account has as well as a busy one: size blocks to the question, not to hoped-for data.
+
+## The phone
+
+- **Navigation folds**: the sidebar becomes a 48 to 56px top bar with the screen name, a menu button opening a full-screen sheet (nav, switcher, account) and at most one action; or a bottom bar of four or five destinations with short labels. A sidebar that still takes more than about 30% of the width is broken.
+- **Margins** 16 to 20px; touch targets at least 44px; data and labels 14px; sublines no smaller than 12px; inputs 16px.
+- **The title stays** at 20 to 24px. Header actions move into a menu, except the one primary.
+- **Filters** collapse into one row of chips or a Filters sheet; tabs scroll sideways inside their own row, never the page. The first list row starts in the top 60% of the screen.
+- **KPIs** become a two-column grid (an even count, or let the last cell span) or a list with label left and value right. Never four squeezed columns.
+- **At most one row of controls above a chart.** Charts go full width, 160 to 200px tall, 3 or 4 x labels, legend as dots above. Y ticks keep their own lane; a tick label never sits on the line.
+- **Tables become two-line lists below about 640px**: identity and key number on line one, the other fields muted on line two, the one action on the right. Fields move to line two; they are never dropped. A table that must stay a table scrolls inside its own frame with the first column fixed.
+- **Row actions** are text actions or one compact trailing button; one filled bulk action for the list.
+- **When a strip collapses**, drop the item least relevant to the screen's main job, not the last in source order.
+- **Blocks that carry an action move up**: a right rail with "Reorder" becomes a summary row above the list ("5 items low, Review").
+- **Several panes** (list and detail, inbox): one at a time; choosing a row pushes the detail, back returns to the list at its scroll position.
+- **Settings**: the label column stacks above its panel.
+- **Builders and editors**: show the work read-only, with tools in a bottom sheet if editing stays.
+
+## The tablet (about 641 to 1100px)
+
+Its own band, not a stretched phone or a squeezed desktop: the sidebar folds to a top bar or rail, tables keep four or five columns with secondary fields as sublines, two panels stack once either would be under about 340px, and the identity column is never the one truncated.
+
+Sources: adapted from Leonxlnx/taste-skill references/app-screens.md sections 10 to 12 (MIT, changed: condensed; inspector checks removed) and pbakaus/impeccable operate and harden references (Apache-2.0, changed: rewritten).