@tamsensedev/runner 0.13.0 → 0.19.0

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

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

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

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