@tamsensedev/runner 0.10.0 → 0.18.0

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

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

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