diff --git a/web/design/tokens/capture.mjs b/web/design/tokens/capture.mjs new file mode 100644 index 00000000..35852e50 --- /dev/null +++ b/web/design/tokens/capture.mjs @@ -0,0 +1,70 @@ +// Capture the visual-system styleguide at 1440 × 900 through the repository's +// zero-dependency Chrome DevTools driver. Read-only import: web/test/browser.mjs +// is not modified. +// +// node web/design/tokens/capture.mjs +// +// Writes PNGs into web/design/tokens/captures/ (gitignored by the root +// `captures/` rule). No server is started; the styleguide is a local file. + +import { mkdir } from "node:fs/promises"; +import { dirname, join } from "node:path"; +import { fileURLToPath, pathToFileURL } from "node:url"; +import { launchChrome } from "../../test/browser.mjs"; + +const here = dirname(fileURLToPath(import.meta.url)); +const outDir = join(here, "captures"); +const styleguide = pathToFileURL(join(here, "styleguide.html")); + +const shots = [ + { id: "foundations", name: "styleguide-01-foundations-1440x900.png" }, + { id: "type", name: "styleguide-02-type-1440x900.png" }, + { id: "space", name: "styleguide-03-space-1440x900.png" }, + { id: "navigation", name: "styleguide-04-rail-1440x900.png" }, + { id: "lists", name: "styleguide-05-lists-1440x900.png" }, + { id: "data", name: "styleguide-06-data-1440x900.png" }, + { id: "overlays", name: "styleguide-07-overlays-1440x900.png" }, + { id: "conversation", name: "styleguide-08-conversation-1440x900.png" }, + { id: "content", name: "styleguide-09-content-1440x900.png" }, +]; + +await mkdir(outDir, { recursive: true }); + +const browser = await launchChrome({ width: 1440, height: 900 }); +try { + for (const shot of shots) { + const page = await browser.openPage(`${styleguide.href}#${shot.id}`, { + width: 1440, + height: 900, + }); + await page.waitForSelector(`#${shot.id}`); + await page.evaluate("document.fonts.ready.then(() => true)"); + if (shot.id === "foundations") { + await page.evaluate("window.scrollTo(0, 0)"); + } else { + await page.evaluate(`(() => { + const node = document.querySelector("#${shot.id}"); + node.scrollIntoView({ block: "start" }); + window.scrollBy(0, -16); + return node.getBoundingClientRect().top; + })()`); + } + await new Promise((resolve) => setTimeout(resolve, 180)); + const path = join(outDir, shot.name); + await page.screenshot(path); + const metrics = await page.evaluate(`(() => { + const node = document.querySelector("#${shot.id}"); + return { + top: Math.round(node.getBoundingClientRect().top), + width: Math.round(node.getBoundingClientRect().width), + pageHeight: document.documentElement.scrollHeight, + }; + })()`); + console.log( + `${shot.name}: viewport 1440x900, section top ${metrics.top}px, width ${metrics.width}px, page ${metrics.pageHeight}px`, + ); + await page.close(); + } +} finally { + await browser.close(); +} diff --git a/web/design/tokens/styleguide.css b/web/design/tokens/styleguide.css new file mode 100644 index 00000000..d8c5d334 --- /dev/null +++ b/web/design/tokens/styleguide.css @@ -0,0 +1,1728 @@ +/* =========================================================================== + Pipelines web — styleguide + --------------------------------------------------------------------------- + The tokens applied to real working shapes. This is a reference stylesheet, + not a replacement for the area files: the selectors below are the components + a migration should converge on. Import tokens.css first. + + Rules demonstrated here: + - one chip component, one control height, one radius family + - grouping by surface contrast, not by nested bordered boxes + - borders only on interactive edges; dividers only inside a surface + - every state also carries a word or glyph, never colour alone + - focus is always a 2px ring with a 2px offset + =========================================================================== */ + +:root { + color-scheme: dark; +} + +* { + box-sizing: border-box; +} + +html { + background: var(--color-bg); +} + +body { + margin: 0; + background: var(--color-bg); + color: var(--color-text); + font: var(--type-body); + -webkit-font-smoothing: antialiased; + text-rendering: optimizeLegibility; +} + +a { + color: var(--color-accent); +} + +.icon-sprite { + position: absolute; + width: 0; + height: 0; + overflow: hidden; +} + +button, +input, +textarea, +select { + font: inherit; + color: inherit; +} + +:where(a, button, input, textarea, select, [tabindex]):focus-visible { + outline: var(--focus-ring-width) solid var(--focus-ring-color); + outline-offset: var(--focus-ring-offset); +} + +/* ---- Guide shell -------------------------------------------------------- */ + +.guide { + display: grid; + grid-template-columns: 216px minmax(0, 1fr); + min-height: 100vh; +} + +.guide-rail { + position: sticky; + top: 0; + align-self: start; + display: flex; + flex-direction: column; + gap: var(--space-l); + height: 100vh; + padding: var(--space-l) var(--space-s); + background: var(--color-surface); + border-right: var(--layout-hairline) solid var(--color-divider); +} + +.guide-brand { + display: flex; + align-items: center; + gap: var(--space-xs); + min-height: 40px; + padding: 0 var(--space-xs); +} + +.guide-mark { + width: var(--icon-inline); + height: var(--icon-inline); + flex: none; + border-radius: var(--radius-s); + background: linear-gradient(135deg, var(--color-accent), var(--color-ok)); + box-shadow: 0 0 0 4px var(--tint-accent-soft); +} + +.guide-brand-text { + display: grid; + gap: 1px; +} + +.guide-brand-name { + font: var(--type-title-small); + letter-spacing: var(--tracking-tight); +} + +.guide-brand-sub { + color: var(--color-muted); + font: var(--type-code-small); +} + +.guide-nav { + display: grid; + gap: 2px; +} + +.guide-nav-label { + margin: 0 0 var(--space-xs); + padding: 0 var(--space-xs); + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.guide-nav a { + display: flex; + align-items: center; + gap: var(--space-xs); + min-height: 36px; + padding: 0 var(--space-s); + border-radius: var(--radius-control); + color: var(--color-muted); + font: var(--type-body-small); + text-decoration: none; + transition: background var(--motion-fast) var(--ease-standard), + color var(--motion-fast) var(--ease-standard); +} + +.guide-nav a:hover { + background: var(--tint-hover); + color: var(--color-text); +} + +.guide-nav a[aria-current="page"] { + background: var(--tint-selected); + color: var(--color-text); + box-shadow: inset 2px 0 0 var(--color-accent); + font-weight: var(--weight-semibold); +} + +.guide-nav-index { + min-width: 22px; + color: var(--color-faint); + font: var(--type-code-small); +} + +.guide-rail-footer { + margin-top: auto; + display: grid; + gap: var(--space-2xs); + padding: 0 var(--space-xs); + color: var(--color-faint); + font: var(--type-code-small); + line-height: 16px; +} + +.guide-main { + min-width: 0; + padding: var(--space-xl) var(--space-2xl) var(--space-4xl); +} + +.guide-header { + max-width: 1120px; + padding-bottom: var(--space-l); + border-bottom: var(--layout-hairline) solid var(--color-divider); +} + +.eyebrow { + margin: 0 0 var(--space-2xs); + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.guide-header h1 { + margin: 0 0 var(--space-xs); + font: var(--type-display); + letter-spacing: -0.02em; +} + +.guide-lead { + max-width: 78ch; + margin: 0; + color: var(--color-muted); + font: var(--type-body-small); + line-height: 1.55; +} + +.guide-meta-row { + display: flex; + flex-wrap: wrap; + gap: var(--space-xs) var(--space-l); + margin-top: var(--space-m); + color: var(--color-faint); + font: var(--type-code-small); +} + +.guide-meta-row strong { + color: var(--color-text); + font-weight: var(--weight-medium); +} + +/* ---- Sections ----------------------------------------------------------- */ + +.guide-section { + max-width: 1120px; + padding-top: var(--space-2xl); + scroll-margin-top: var(--space-m); +} + +.section-head { + display: flex; + align-items: baseline; + justify-content: space-between; + gap: var(--space-m); + margin-bottom: var(--space-m); + padding-bottom: var(--space-xs); + border-bottom: var(--layout-hairline) solid var(--color-divider); +} + +.section-head h2 { + margin: 0; + font: var(--type-title); + letter-spacing: var(--tracking-tight); +} + +.section-index { + color: var(--color-faint); + font: var(--type-code-small); + white-space: nowrap; +} + +.section-note { + max-width: 82ch; + margin: calc(-1 * var(--space-xs)) 0 var(--space-l); + color: var(--color-muted); + font: var(--type-body-small); + line-height: 1.55; +} + +.specimen { + display: grid; + gap: var(--space-s); +} + +.specimen + .specimen { + margin-top: var(--space-l); +} + +.specimen-head { + display: flex; + align-items: baseline; + justify-content: space-between; + gap: var(--space-m); +} + +.specimen-title { + margin: 0; + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.specimen-caption { + color: var(--color-faint); + font: var(--type-code-small); +} + +.stage { + padding: var(--space-m); + background: var(--color-surface); + border-radius: var(--radius-card); +} + +.stage--bare { + padding: 0; + background: transparent; +} + +.stage--row { + display: flex; + flex-wrap: wrap; + align-items: flex-start; + gap: var(--space-m); +} + +/* ---- Swatches ----------------------------------------------------------- */ + +.swatch-group + .swatch-group { + margin-top: var(--space-m); +} + +.swatch-group-label { + margin: 0 0 var(--space-xs); + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.swatch-grid { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(132px, 1fr)); + gap: var(--space-xs); +} + +.swatch { + display: grid; + gap: var(--space-xs); + padding: var(--space-xs); + background: var(--color-surface); + border-radius: var(--radius-control); +} + +.swatch-chip { + height: 42px; + border: var(--layout-hairline) solid var(--color-divider); + border-radius: var(--radius-s); + background: var(--swatch); +} + +.swatch-name { + font: var(--type-code-small); + color: var(--color-text); + overflow-wrap: anywhere; +} + +.swatch-value { + color: var(--color-faint); + font: var(--type-code-small); +} + +/* ---- Type ramp ---------------------------------------------------------- */ + +.type-table { + display: grid; +} + +.type-row { + display: grid; + grid-template-columns: 150px minmax(0, 1fr) 190px; + gap: var(--space-m); + align-items: baseline; + padding: var(--space-s) 0; + border-bottom: var(--layout-hairline) solid var(--color-divider); +} + +.type-row:last-child { + border-bottom: 0; +} + +.type-token { + color: var(--color-accent); + font: var(--type-code-small); + overflow-wrap: anywhere; +} + +.type-spec { + color: var(--color-faint); + font: var(--type-code-small); + text-align: right; +} + +.t-eyebrow { + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; + color: var(--color-muted); +} + +.t-label { + font: var(--type-label); + color: var(--color-text); +} + +.t-meta { + font: var(--type-meta); + color: var(--color-muted); +} + +.t-body-small { + font: var(--type-body-small); +} + +.t-body { + font: var(--type-body); +} + +.t-title-small { + font: var(--type-title-small); +} + +.t-title { + font: var(--type-title); + letter-spacing: var(--tracking-tight); +} + +.t-display { + font: var(--type-display); + letter-spacing: -0.02em; +} + +.t-code { + font: var(--type-code); +} + +/* ---- Spacing scale ------------------------------------------------------ */ + +.space-table { + display: grid; + gap: 0; +} + +.space-row { + display: grid; + grid-template-columns: 180px 1fr 54px; + gap: var(--space-m); + align-items: center; + min-height: 34px; + border-bottom: var(--layout-hairline) solid var(--color-divider); +} + +.space-row:last-child { + border-bottom: 0; +} + +.space-token { + color: var(--color-accent); + font: var(--type-code-small); +} + +.space-track { + display: flex; + align-items: center; + min-height: 14px; +} + +.space-bar { + width: var(--bar); + min-width: 2px; + height: 10px; + border-radius: var(--radius-xs); + background: var(--color-accent); + opacity: 0.72; +} + +.space-value { + color: var(--color-faint); + font: var(--type-code-small); + text-align: right; +} + +/* ---- Radii and elevation ------------------------------------------------ */ + +.radius-grid { + display: flex; + flex-wrap: wrap; + gap: var(--space-l); + align-items: flex-end; +} + +.radius-cell { + display: grid; + gap: var(--space-xs); + justify-items: start; +} + +.radius-box { + width: 76px; + height: 56px; + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius); + background: var(--color-surface-2); +} + +.radius-cell--pill .radius-box { + height: 30px; + border-radius: var(--radius-pill); +} + +.elevation-grid { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: var(--space-m); +} + +.elevation-cell { + display: grid; + gap: var(--space-xs); +} + +.elevation-box { + min-height: 88px; + display: grid; + place-items: center; + padding: var(--space-s); + border-radius: var(--radius-card); + background: var(--color-elevated); + color: var(--color-muted); + font: var(--type-code-small); + box-shadow: var(--elevation); +} + +/* ---- Density comparison ------------------------------------------------- */ + +.specimen + .density-grid { + margin-top: var(--space-l); + padding-top: var(--space-xs); + border-top: var(--layout-hairline) solid var(--color-divider); +} + +.density-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: var(--space-m); +} + +.density-grid .specimen + .specimen { + margin-top: 0; +} + +.density-panel { + display: grid; + gap: var(--space-xs); + padding: var(--space-s); + background: var(--color-surface); + border-radius: var(--radius-card); +} + +.density-head { + display: flex; + align-items: baseline; + justify-content: space-between; + gap: var(--space-xs); + padding: 0 var(--space-2xs); +} + +.density-title { + font: var(--type-label); + color: var(--color-text); +} + +.density-meta { + color: var(--color-faint); + font: var(--type-code-small); +} + +/* ---- Chips -------------------------------------------------------------- */ + +.chip { + display: inline-flex; + align-items: center; + gap: 5px; + min-height: 22px; + padding: 1px 8px; + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-pill); + background: var(--color-surface-2); + color: var(--color-muted); + font: var(--type-label); + white-space: nowrap; + vertical-align: middle; +} + +.chip-glyph { + font: var(--type-code-small); + line-height: 1; +} + +.chip-row { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: var(--space-xs); +} + +.chip--queued { + background: var(--status-queued-wash); + color: var(--status-queued); +} + +.chip--running, +.chip--active { + background: var(--status-running-wash); + color: var(--status-running); +} + +.chip--waiting { + background: var(--status-waiting-wash); + color: var(--status-waiting); +} + +.chip--succeeded { + background: var(--status-succeeded-wash); + color: var(--status-succeeded); +} + +.chip--failed { + background: var(--status-failed-wash); + color: var(--status-failed); +} + +.chip--canceled { + background: var(--status-canceled-wash); + color: var(--status-canceled); +} + +.chip--interrupted { + background: var(--status-interrupted-wash); + color: var(--status-interrupted); +} + +.chip--blocked { + background: var(--status-blocked-wash); + color: var(--status-blocked); +} + +.chip--skipped { + background: var(--status-skipped-wash); + color: var(--status-skipped); +} + +.chip--unknown { + background: var(--status-unknown-wash); + color: var(--status-unknown); +} + +.chip--neutral { + background: var(--color-surface-2); + color: var(--color-muted); +} + +.chip--count { + min-width: 28px; + justify-content: center; + padding: 1px 7px; + color: var(--color-muted); + font: var(--type-code-small); +} + +/* ---- Buttons and fields ------------------------------------------------- */ + +.btn { + display: inline-flex; + align-items: center; + justify-content: center; + gap: 6px; + min-height: var(--density-control-height); + padding: 0 var(--space-s); + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-control); + background: var(--color-surface-2); + color: var(--color-text); + font: var(--type-meta); + white-space: nowrap; + cursor: pointer; + transition: background var(--motion-fast) var(--ease-standard), + border-color var(--motion-fast) var(--ease-standard), + color var(--motion-fast) var(--ease-standard); +} + +.btn:hover { + background: var(--color-elevated); + border-color: var(--color-border-strong); +} + +.btn:active { + background: var(--color-surface); +} + +.btn--primary { + border-color: var(--color-accent); + background: var(--color-accent); + color: var(--color-on-accent); + font-weight: var(--weight-semibold); +} + +.btn--primary:hover { + border-color: var(--color-accent-strong); + background: var(--color-accent-strong); +} + +.btn--primary:active { + border-color: var(--color-accent-pressed); + background: var(--color-accent-pressed); +} + +.btn--danger { + border-color: color-mix(in srgb, var(--color-bad) 58%, var(--color-border)); + background: var(--tint-bad-soft); + color: var(--color-bad); + font-weight: var(--weight-semibold); +} + +.btn--ghost { + border-color: transparent; + background: transparent; + color: var(--color-muted); +} + +.btn--ghost:hover { + border-color: transparent; + background: var(--tint-hover); + color: var(--color-text); +} + +.btn--small { + min-height: var(--density-control-height-small); + padding: 0 10px; + font: var(--type-code-small); +} + +.btn.is-active { + border-color: var(--color-accent); + background: var(--tint-accent-soft); + color: var(--color-accent); +} + +/* ---- Rail --------------------------------------------------------------- */ + +.rail { + width: var(--layout-rail); + min-height: 330px; + display: flex; + flex-direction: column; + gap: 2px; + padding: var(--space-s) var(--space-xs); + background: var(--color-surface); + border-radius: var(--radius-card); +} + +.rail-brand { + display: flex; + align-items: center; + gap: var(--space-xs); + min-height: var(--density-touch-target); + padding: 0 var(--space-s); + margin-bottom: var(--space-s); + font: var(--type-title-small); + letter-spacing: var(--tracking-tight); +} + +.rail-mark { + width: var(--icon-inline); + height: var(--icon-inline); + flex: none; + border-radius: var(--radius-s); + background: linear-gradient(135deg, var(--color-accent), var(--color-ok)); +} + +.rail-item { + display: flex; + align-items: center; + gap: var(--space-s); + min-height: var(--density-touch-target); + padding: 0 var(--space-s); + border: 0; + border-radius: var(--radius-control); + background: transparent; + color: var(--color-muted); + font: var(--type-body); + text-align: left; + text-decoration: none; + cursor: pointer; + transition: background var(--motion-fast) var(--ease-standard), + color var(--motion-fast) var(--ease-standard); +} + +.rail-item:hover, +.rail-item.is-hover { + background: var(--tint-hover); + color: var(--color-text); +} + +.rail-item:active, +.rail-item.is-pressed { + background: var(--tint-pressed); +} + +.rail-item.is-active { + background: var(--tint-selected); + color: var(--color-text); + box-shadow: inset 2px 0 0 var(--color-accent); + font-weight: var(--weight-semibold); +} + +.rail-divider { + height: var(--layout-hairline); + margin: var(--space-s) var(--space-xs); + background: var(--color-divider); +} + +.rail-heading { + margin: 0 0 var(--space-xs); + padding: 0 var(--space-s); + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.rail-footer { + margin-top: auto; + display: flex; + align-items: center; + gap: var(--space-xs); + min-height: var(--density-touch-target); + padding: 0 var(--space-s); + color: var(--color-muted); + font: var(--type-meta); +} + +.rail-state-grid { + display: grid; + grid-template-columns: repeat(3, var(--layout-rail)); + gap: var(--space-m); +} + +.rail-state-cell { + display: grid; + gap: var(--space-xs); +} + +.rail-state-cell .rail { + min-height: 0; + padding: var(--space-2xs); +} + +.rail-state-label { + color: var(--color-faint); + font: var(--type-code-small); + padding-left: var(--space-2xs); +} + +.icon { + width: var(--icon-list); + height: var(--icon-list); + flex: none; +} + +.icon--small { + width: var(--icon-small); + height: var(--icon-small); +} + +.icon--inline { + width: var(--icon-inline); + height: var(--icon-inline); +} + +/* ---- List rows ---------------------------------------------------------- */ + +.row-list { + display: grid; + gap: 2px; +} + +.row { + display: grid; + grid-template-columns: minmax(0, 1fr) auto; + grid-template-areas: + "title chip" + "meta meta"; + gap: var(--density-row-gap) var(--space-xs); + width: 100%; + padding: var(--density-row-pad-block) var(--density-row-pad-inline); + border: var(--layout-hairline) solid transparent; + border-radius: var(--radius-control); + background: transparent; + color: var(--color-text); + text-align: left; + cursor: pointer; + transition: background var(--motion-fast) var(--ease-standard), + border-color var(--motion-fast) var(--ease-standard); +} + +.row:hover, +.row.is-hover { + background: var(--tint-hover); +} + +.row:active, +.row.is-pressed { + background: var(--tint-pressed); +} + +.row.is-selected { + background: var(--tint-selected); + border-color: color-mix(in srgb, var(--color-accent) 38%, var(--color-border)); + box-shadow: inset 2px 0 0 var(--color-accent); +} + +.row:focus-visible { + outline-offset: -2px; +} + +.row-title { + grid-area: title; + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + font: var(--type-body); + font-weight: var(--weight-semibold); +} + +.row > .chip { + grid-area: chip; + align-self: start; +} + +.row-meta { + grid-area: meta; + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + color: var(--color-muted); + font: var(--type-meta); + font-variant-numeric: tabular-nums; +} + +/* ---- Toolbar ------------------------------------------------------------ */ + +.toolbar { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: var(--space-xs); + padding: var(--space-xs) var(--space-s); + background: var(--color-surface); + border-radius: var(--radius-card); +} + +.toolbar .spacer { + flex: 1 1 auto; +} + +.search { + display: flex; + flex: 1 1 300px; + align-items: center; + gap: var(--space-xs); + min-width: 0; + min-height: var(--density-control-height); + padding: 0 10px; + background: var(--color-surface-2); + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-control); +} + +.search:focus-within { + outline: var(--focus-ring-width) solid var(--focus-ring-color); + outline-offset: var(--focus-ring-offset); +} + +.search-icon { + width: var(--icon-status); + height: var(--icon-status); + flex: none; + color: var(--color-muted); +} + +.search input { + flex: 1 1 auto; + min-width: 0; + padding: 6px 0; + border: 0; + outline: 0; + background: transparent; + color: var(--color-text); + font: var(--type-body); +} + +.search input::placeholder { + color: var(--color-muted); + opacity: 1; +} + +.live-badge { + display: inline-flex; + align-items: center; + gap: 6px; + color: var(--status-succeeded); + font: var(--type-label); +} + +.live-dot { + width: 7px; + height: 7px; + flex: none; + border-radius: 50%; + background: currentColor; + box-shadow: 0 0 0 3px var(--status-succeeded-wash); +} + +/* ---- Key/value table ---------------------------------------------------- */ + +.kv { + display: grid; + grid-template-columns: minmax(120px, 180px) minmax(0, 1fr); + gap: var(--space-xs) var(--space-m); + margin: 0; +} + +.kv > div { + display: contents; +} + +.kv dt { + color: var(--color-muted); + font: var(--type-meta); +} + +.kv dd { + margin: 0; + min-width: 0; + overflow-wrap: anywhere; + font: var(--type-body-small); + font-variant-numeric: tabular-nums; +} + +.kv code, +code { + padding: 1px 5px; + border-radius: var(--radius-xs); + background: var(--color-surface-2); + color: var(--color-text); + font: var(--type-code-small); +} + +/* ---- Code block --------------------------------------------------------- */ + +.code-card { + overflow: hidden; + background: var(--color-bg); + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-card); +} + +.code-head { + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--space-s); + padding: 6px 12px; + background: var(--color-surface-2); + border-bottom: var(--layout-hairline) solid var(--color-divider); + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.code-body { + margin: 0; + padding: var(--space-s); + overflow: auto; + color: var(--color-text); + font: var(--type-code); + tab-size: 2; +} + +.code-body code { + padding: 0; + background: transparent; + font: var(--type-code); +} + +.tok-cmd { + color: var(--color-accent); +} + +.tok-arg { + color: var(--color-muted); +} + +.tok-comment { + color: var(--color-faint); +} + +/* ---- Dialog and sheet --------------------------------------------------- */ + +.overlay-demo { + position: relative; + display: flex; + align-items: center; + justify-content: center; + min-height: 310px; + padding: var(--space-l); + overflow: hidden; + background: var(--color-bg); + border-radius: var(--radius-card); +} + +.scrim { + position: absolute; + inset: 0; + background: var(--color-scrim); +} + +.dialog { + position: relative; + display: grid; + gap: var(--space-s); + width: min(var(--layout-dialog), 100%); + padding: var(--space-m); + background: var(--color-elevated); + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-sheet); + box-shadow: var(--elevation-dialog); +} + +.dialog-title { + margin: 0; + font: var(--type-title-small); +} + +.dialog-message { + margin: 0; + color: var(--color-muted); + font: var(--type-body-small); + line-height: 1.5; +} + +.dialog-actions { + display: flex; + justify-content: flex-end; + gap: var(--space-xs); + padding-top: var(--space-2xs); +} + +.overlay-demo--sheet { + align-items: flex-end; + justify-content: center; + padding: 0; +} + +.sheet { + position: relative; + display: flex; + flex-direction: column; + width: min(var(--layout-sheet), 100%); + max-height: 300px; + overflow: hidden; + background: var(--color-elevated); + border: var(--layout-hairline) solid var(--color-border); + border-bottom: 0; + border-radius: var(--radius-sheet) var(--radius-sheet) 0 0; + box-shadow: var(--elevation-sheet); +} + +.sheet-head { + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--space-s); + padding: var(--space-s) var(--space-m); + border-bottom: var(--layout-hairline) solid var(--color-divider); +} + +.sheet-title { + margin: 0; + font: var(--type-title-small); +} + +.sheet-body { + display: grid; + gap: var(--space-xs); + padding: var(--space-s) var(--space-m) var(--space-m); + overflow: auto; +} + +.sheet-row { + display: flex; + align-items: center; + gap: var(--space-s); + padding: var(--space-xs) var(--space-s); + border-radius: var(--radius-control); + background: var(--color-surface-2); +} + +.sheet-row-text { + display: grid; + gap: 1px; + min-width: 0; + flex: 1 1 auto; +} + +.sheet-row-title { + font: var(--type-body-small); + font-weight: var(--weight-semibold); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.sheet-row-meta { + color: var(--color-muted); + font: var(--type-meta); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +/* ---- Chat --------------------------------------------------------------- */ + +.chat-stage { + display: grid; + gap: var(--space-m); + padding: var(--space-m); + background: var(--color-bg); + border-radius: var(--radius-card); +} + +.turn { + display: flex; +} + +.turn--user { + justify-content: flex-end; +} + +.bubble-user { + max-width: min(var(--layout-chat-measure), 82%); + padding: 10px 12px; + background: var(--color-surface-2); + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-card); + color: var(--color-text); + font: var(--type-body); + white-space: pre-wrap; + overflow-wrap: anywhere; +} + +.turn--agent { + display: grid; + gap: var(--space-xs); + max-width: var(--layout-measure); +} + +.agent-name { + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.markdown { + display: grid; + gap: var(--space-xs); + min-width: 0; +} + +.markdown > * { + margin: 0; +} + +.md-paragraph { + font: var(--type-body); + line-height: 1.55; + overflow-wrap: anywhere; +} + +.md-list { + display: grid; + gap: 4px; + margin: 0; + padding-left: 20px; + font: var(--type-body); + line-height: 1.5; +} + +.md-code { + padding: 1px 5px; + border-radius: var(--radius-xs); + background: var(--color-surface-2); + font: var(--type-code-small); +} + +.md-code-block { + overflow: hidden; + background: var(--color-bg); + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-control); +} + +.md-code-label { + padding: 4px 10px; + background: var(--color-surface-2); + border-bottom: var(--layout-hairline) solid var(--color-divider); + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.md-pre { + margin: 0; + padding: 10px; + overflow-x: auto; + font: var(--type-code); +} + +.composer { + display: flex; + align-items: flex-end; + gap: var(--space-xs); + padding: var(--space-xs); + background: var(--color-surface); + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-card); +} + +.composer:focus-within { + outline: var(--focus-ring-width) solid var(--focus-ring-color); + outline-offset: var(--focus-ring-offset); +} + +.icon-button { + display: grid; + place-items: center; + width: var(--density-control-height); + height: var(--density-control-height); + flex: none; + padding: 0; + border: 0; + border-radius: var(--radius-control); + background: transparent; + color: var(--color-muted); + cursor: pointer; +} + +.icon-button:hover { + background: var(--tint-hover); + color: var(--color-text); +} + +.composer-input { + flex: 1 1 auto; + min-width: 0; + max-height: 132px; + resize: none; + padding: 7px 0; + border: 0; + outline: 0; + background: transparent; + color: var(--color-text); + font: var(--type-body); + line-height: 20px; +} + +.composer-input::placeholder { + color: var(--color-muted); + opacity: 1; +} + +.send { + display: grid; + place-items: center; + width: var(--density-control-height); + height: var(--density-control-height); + flex: none; + padding: 0; + border: var(--layout-hairline) solid var(--color-accent); + border-radius: var(--radius-control); + background: var(--color-accent); + color: var(--color-on-accent); + cursor: pointer; +} + +.send:hover { + background: var(--color-accent-strong); + border-color: var(--color-accent-strong); +} + +/* ---- Approval card ------------------------------------------------------ */ + +.approval { + display: grid; + gap: var(--space-s); + padding: var(--space-m); + background: var(--color-surface); + border: var(--layout-hairline) solid var(--color-border); + border-left: 3px solid var(--color-warn); + border-radius: var(--radius-card); +} + +.approval-head { + display: flex; + align-items: flex-start; + gap: var(--space-s); +} + +.approval-shield { + width: 18px; + height: 18px; + flex: none; + color: var(--color-warn); +} + +.approval-titles { + display: grid; + gap: 1px; + min-width: 0; +} + +.approval-headline { + font: var(--type-title-small); +} + +.approval-status { + color: var(--color-muted); + font: var(--type-meta); +} + +.approval-resources { + margin: 0; + max-height: 96px; + overflow: hidden; + padding: 8px 10px; + background: var(--color-bg); + border-radius: var(--radius-control); + color: var(--color-text); + font: var(--type-code); + white-space: pre-wrap; + overflow-wrap: anywhere; +} + +.approval-risk { + display: grid; + gap: 4px; + padding: 8px 10px; + background: var(--tint-warn-soft); + border-radius: var(--radius-control); +} + +.approval-risk-head { + display: flex; + align-items: center; + gap: 5px; + color: var(--color-warn); +} + +.approval-risk-label { + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); +} + +.approval-risk-text { + color: var(--color-text); + font: var(--type-body-small); + line-height: 1.5; +} + +.approval-actions { + display: flex; + flex-wrap: wrap; + gap: var(--space-xs); +} + +/* ---- Artifacts ---------------------------------------------------------- */ + +.artifact-grid { + display: grid; + grid-template-columns: repeat(4, minmax(0, 1fr)); + gap: var(--space-s); +} + +.artifact-tile { + position: relative; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + gap: var(--space-2xs); + min-height: 148px; + padding: var(--space-s); + overflow: hidden; + background: var(--color-surface-2); + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-card); + text-align: center; +} + +.artifact-tile:hover { + border-color: var(--color-border-strong); +} + +.artifact-thumb { + position: absolute; + inset: 0; + background: + radial-gradient( + circle at 68% 27%, + color-mix(in srgb, var(--color-warn) 52%, transparent) 0 9%, + transparent 10% + ), + radial-gradient( + ellipse at 18% 108%, + color-mix(in srgb, var(--color-accent) 34%, transparent) 0 38%, + transparent 39% + ), + radial-gradient( + ellipse at 82% 112%, + color-mix(in srgb, var(--color-ok) 22%, transparent) 0 42%, + transparent 43% + ), + linear-gradient(160deg, var(--color-surface-2), var(--color-elevated-2)); +} + +.artifact-poster { + display: grid; + place-items: center; + width: 56px; + height: 56px; + border-radius: 50%; + background: color-mix(in srgb, var(--color-bg) 76%, transparent); +} + +.artifact-play { + color: var(--color-text); + font-size: var(--icon-inline); + line-height: 1; +} + +.artifact-kind { + color: var(--color-muted); + font: var(--type-eyebrow); + letter-spacing: var(--tracking-eyebrow); + text-transform: uppercase; +} + +.artifact-name { + max-width: 100%; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + font: var(--type-meta); + font-weight: var(--weight-semibold); +} + +.artifact-size { + color: var(--color-faint); + font: var(--type-code-small); +} + +.artifact-actions { + position: absolute; + top: 6px; + right: 6px; + display: flex; + gap: 4px; +} + +.artifact-action { + display: inline-flex; + align-items: center; + min-height: 30px; + padding: 0 8px; + border: var(--layout-hairline) solid var(--color-border); + border-radius: var(--radius-s); + background: color-mix(in srgb, var(--color-bg) 82%, transparent); + color: var(--color-text); + font: var(--type-code-small); + cursor: pointer; +} + +.artifact-action:hover { + border-color: var(--color-border-strong); +} + +/* ---- Empty state -------------------------------------------------------- */ + +.empty-state { + display: grid; + justify-items: start; + gap: var(--space-s); + padding: var(--space-l); + background: var(--color-surface); + border-radius: var(--radius-card); +} + +.empty-state p { + max-width: 52ch; + margin: 0; + color: var(--color-muted); + font: var(--type-body-small); + line-height: 1.55; +} + +.empty-state .btn { + justify-self: start; +} + +/* ---- Closing ------------------------------------------------------------ */ + +.guide-footer { + max-width: 1120px; + margin-top: var(--space-4xl); + padding-top: var(--space-xl); + padding-bottom: var(--space-4xl); + border-top: var(--layout-hairline) solid var(--color-divider); +} + +.guide-footer-grid { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: var(--space-m); + margin-bottom: var(--space-l); +} + +.guide-footer-step { + display: grid; + gap: var(--space-2xs); + padding: var(--space-s); + background: var(--color-surface); + border-radius: var(--radius-card); +} + +.guide-footer-index { + color: var(--color-accent); + font: var(--type-code-small); +} + +.guide-footer-step h3 { + margin: 0; + font: var(--type-title-small); +} + +.guide-footer-step p { + margin: 0; + color: var(--color-muted); + font: var(--type-body-small); + line-height: 1.5; +} + +.guide-footer-files { + display: flex; + flex-wrap: wrap; + gap: var(--space-xs) var(--space-l); + margin: 0; + color: var(--color-faint); + font: var(--type-code-small); +} + +/* ---- Reduced motion ----------------------------------------------------- */ +@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; + } +} + +/* ---- Narrow guide preview ----------------------------------------------- */ + +@media (max-width: 1040px) { + .guide { + grid-template-columns: minmax(0, 1fr); + } + + .guide-rail { + position: static; + height: auto; + border-right: 0; + border-bottom: var(--layout-hairline) solid var(--color-divider); + } + + .guide-nav { + grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); + } + + .guide-main { + padding: var(--space-l) var(--space-m) var(--space-3xl); + } + + .rail-state-grid, + .density-grid, + .artifact-grid { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } +} + +@media (max-width: 680px) { + .type-row, + .space-row { + grid-template-columns: minmax(0, 1fr); + gap: var(--space-2xs); + } + + .type-spec { + text-align: left; + } + + .rail-state-grid, + .density-grid, + .elevation-grid, + .artifact-grid { + grid-template-columns: minmax(0, 1fr); + } + + .guide-footer-grid { + grid-template-columns: minmax(0, 1fr); + } + + .rail-state-cell .rail { + width: 100%; + } +} diff --git a/web/design/tokens/styleguide.html b/web/design/tokens/styleguide.html new file mode 100644 index 00000000..aa731113 --- /dev/null +++ b/web/design/tokens/styleguide.html @@ -0,0 +1,944 @@ + + + + + + Pipelines web — visual system styleguide + + + + + + +
+ + +
+
+

Design deliverable

+

Visual system

+

+ The Pipelines web client keeps the app's dark identity, its mint accent and its + run-status vocabulary. This guide refines the layer model, the spacing and type + scales, and the component shapes so every area reads from one set of roles + instead of repeating its own chip, border and shadow. +

+
+ Contrast body ≥ 4.5:1 · UI edge ≥ 3:1 + Focus 2px ring, 2px offset + Motion 80 / 120 / 180 / 240 ms + Grid 8px with 4px half-steps +
+
+ + +
+
+

Foundations

+ 01 / 09 +
+

+ Colour is assigned by layer, not by file. The page is bg; + a pane or card is surface; a control, row or code body is + surface-2; anything that floats is elevated. + Borders mark interactive edges. Dividers separate content inside one surface. +

+ +
+

Canvas and surface layers

+
+
+ + --color-bg + #0e1513 +
+
+ + --color-surface + #161d1b +
+
+ + --color-surface-2 + #1a211f +
+
+ + --color-elevated + #252c2a +
+
+ + --color-elevated-2 + #2f3634 +
+
+ + --color-scrim + black 58% +
+
+
+ +
+

Text, lines and focus

+
+
+ + --color-text + #dee4e1 +
+
+ + --color-muted + #a9bab5 +
+
+ + --color-faint + #8b9b96 +
+
+ + --color-divider + #2c3a36 +
+
+ + --color-border + #6a7874 +
+
+ + --color-border-strong + #889391 +
+
+ + --color-focus + #a9f0dd +
+
+
+ +
+

Accent and outcome

+
+
+ + --color-accent + #7fd1bb +
+
+ + --color-accent-strong + #a3e4d3 +
+
+ + --color-ok + #6bd39a +
+
+ + --color-warn + #e6c268 +
+
+ + --color-bad + #ef8a8a +
+
+
+
+ + +
+
+

Type

+ 02 / 09 +
+

+ Eight sans roles and two mono roles. A screen title is + title; a section header is title-small; a row name is + body at semibold; meta is meta. Nothing picks a size + directly. +

+ +
+
+ --type-eyebrow + Workspace + 11 / 14 · 600 · 0.06em +
+
+ --type-label + v5 + 11 / 16 · 600 +
+
+ --type-meta + id 24 · v5 · 6 stages + 12 / 16 · 400 +
+
+ --type-body-small + This asks the server to stop the active run. + 13 / 18 · 400 +
+
+ --type-body + Plan and land + 14 / 20 · 400 +
+
+ --type-title-small + Waiting for your decision + 16 / 22 · 600 +
+
+ --type-title + Pipelines + 20 / 26 · 600 +
+
+ --type-display + Visual system + 24 / 30 · 600 +
+
+ --type-code + sha256:9f2c41e8a7 + 12 / 18 · mono +
+
+ --type-code-small + run 458 · 12m + 11 / 16 · mono +
+
+
+ + +
+
+

Space and depth

+ 03 / 09 +
+

+ One 8px grid with 4px half-steps. Padding inside a component is smaller than + the gap between components; the gap between blocks is smaller than the gap + between sections. Radii collapse to five roles, and only floating surfaces + carry a shadow. +

+ +
+
+

Spacing scale

+ 8px grid · 4px half-steps +
+
+
+ --space-3xs + + 2px +
+
+ --space-2xs + + 4px +
+
+ --space-xs + + 8px +
+
+ --space-s + + 12px +
+
+ --space-m + + 16px +
+
+ --space-l + + 24px +
+
+ --space-xl + + 32px +
+
+ --space-2xl + + 40px +
+
+ --space-3xl + + 48px +
+
+ --space-4xl + + 64px +
+
+
+ +
+
+

Radii

+ one family, five roles +
+
+
+ + --radius-xs +
+
+ + --radius-s +
+
+ + --radius-control +
+
+ + --radius-card +
+
+ + --radius-sheet +
+
+ + --radius-pill +
+
+
+ +
+
+

Elevation

+ floating surfaces only +
+
+
+
--elevation-1
+ menu item, sticky edge +
+
+
--elevation-2
+ menu, toast +
+
+
--elevation-3
+ dialog +
+
+
+
+ + + + + +
+
+

Lists and toolbar

+ 05 / 09 +
+

+ A row is one control, not a box around a box. Name, status and meta share one + two-column grid; hover is a wash and selection adds the accent bar. The toolbar + uses the same 36px control height as every other button and field. +

+ +
+
+

Toolbar

+ filter · sort · search · live +
+
+ + + + live +
+
+ +
+
+

Rows

+ default · hover · selected +
+
+
+ + + +
+
+
+ +
+
+

Density

+ light · compact +
+
+
+
+ Light density + row 12px block +
+
+ + + +
+
+
+
+ Compact + row 8px block +
+
+ + + +
+
+
+
+
+ + +
+
+

Key/value and code

+ 06 / 09 +
+

+ Facts use one two-column table with the label in meta and the value + in body-small; hashes, sessions and paths take the mono role. A code + block is a single framed surface with its own header, never a bordered box + inside another bordered box. +

+ +
+
+

Key/value table

+ Summary +
+
+
+
Content hash
sha256:9f2c41e8a7
+
Started
19 Oct 2026 14:20
+
Finished
19 Oct 2026 14:32
+
Duration
12m
+
+
+
+ +
+
+

Monospace code

+ one frame, one label +
+
+
+ Shell + +
+
node serve.mjs --port 8095 --pipelines 127.0.0.1:8080
+# http://127.0.0.1:8095/
+
+PIPELINES_WS_URL=ws://127.0.0.1:8095/connect node test/smoke.mjs
+
+
+
+ + +
+
+

Dialog and sheet

+ 07 / 09 +
+

+ Anything above the page uses elevated, the sheet radius and one + elevation. The scrim carries the separation; the panel does not add a second + border around its content. Actions sit on one row, with the primary last. +

+ +
+
+
+

Confirm dialog

+ Cancel run 458? +
+
+ + +
+
+ +
+
+

Bottom sheet

+ Needs you +
+
+ + +
+
+
+
+ + +
+
+

Conversation

+ 08 / 09 +
+

+ The operator gets a bubble; the agent gets a full-width turn. The transcript is + the page surface, so the agent turn does not need a second card. The composer + shares the control radius and focus ring, and the approval card is the one + place where a warning edge is warranted. +

+ +
+
+
Show me why run 458 needed the decision, and what changed in the last stage.
+
+ +
+ Agent +
+

+ Run 458 waited on the review stage. The landing step then completed and + recorded four artifacts. +

+
    +
  • Review requested a decision on the land stage.
  • +
  • The decision was recorded, then the run finished.
  • +
  • Four files changed in the last stage.
  • +
+
+
bash
+
git diff --stat HEAD~1
+ 4 files changed, 86 insertions(+), 21 deletions(-)
+
+
+
+ +
+ + + +
+ +
+
+ + + Approve bash + Waiting for your response + +
+
docker build -t pipelines:dev .
+
+ + + RISK REVIEW + + This writes an image tagged pipelines:dev on this machine. +
+
+ + + +
+
+
+
+ + +
+
+

Artifacts and empty

+ 09 / 09 +
+

+ A tile is one framed surface; the media fills it and the actions sit over it. + An empty state is a sentence and, when there is a way out, one action — never a + dashed box or an illustration competing with the text. +

+ +
+
+

Artifact tiles

+ image · video · PDF · JSON +
+
+
+ +
+ +
+
+
+ + + land.webm +
+ +
+
+
+ PDF + session.pdf + 1.2 MiB +
+ + +
+
+
+ JSON + report.json + 18.4 KiB +
+ + +
+
+
+
+ +
+
+
+

Empty state

+ sentence plus one way out +
+
+

No runs match the current filters.

+ +
+
+ +
+
+

Run-status chip row

+ web status palette · unchanged +
+
+
+ queued + running + waiting + succeeded + failed + canceled + interrupted + blocked + skipped + active + unknown +
+
+
+
+
+ + +
+
+ + diff --git a/web/design/tokens/tokens.css b/web/design/tokens/tokens.css new file mode 100644 index 00000000..d0e9ecfd --- /dev/null +++ b/web/design/tokens/tokens.css @@ -0,0 +1,262 @@ +/* =========================================================================== + Pipelines web — visual system tokens + --------------------------------------------------------------------------- + The single source of truth for colour roles, spacing, radii, type, elevation, + focus, tints and motion. Every token is named for the job it does, never for + the value it happens to hold. + + This file contains custom properties only. Import it first, then a component + stylesheet (styleguide.css is the worked example). Nothing here paints a + selector on its own. + + Contrast contract (verified against the surfaces below): + --color-text 14.35:1 on --color-bg, 13.29:1 on --color-surface + --color-muted 9.14:1 on --color-bg, 8.47:1 on --color-surface + --color-border 3.71:1 on --color-surface, 3.09:1 on --color-elevated + --color-focus 13.21:1 on --color-surface + Run-status hues are the web's current values, unchanged. + =========================================================================== */ + +:root { + /* ---- Canvas and surface layers ---------------------------------------- */ + /* bg the page behind every pane + surface a pane, card or transcript group + surface-2 an inset control, row or code body + elevated a menu, dialog, sheet or toast above the page + elevated-2 the highest drawn surface: hover on an elevated control */ + --color-bg: #0e1513; + --color-surface: #161d1b; + --color-surface-2: #1a211f; + --color-elevated: #252c2a; + --color-elevated-2: #2f3634; + --color-scrim: rgba(0, 0, 0, 0.58); + + /* ---- Lines and focus --------------------------------------------------- */ + /* divider decorative separation inside one surface (not a control edge) + border the edge of an interactive or focusable component; >=3:1 on + bg, surface, surface-2 and elevated (use border-strong on + elevated-2) + border-strong selected / pressed emphasis; >=3:1 + focus the one focus ring colour, visible on every surface */ + --color-divider: #2c3a36; + --color-border: #6a7874; + --color-border-strong: #889391; + --color-focus: #a9f0dd; + + /* ---- Text -------------------------------------------------------------- */ + --color-text: #dee4e1; + --color-muted: #a9bab5; + --color-faint: #8b9b96; + --color-on-accent: #06231c; + --color-on-bad: #1b0b0b; + --opacity-disabled: 0.5; + + /* ---- Accent ------------------------------------------------------------ */ + --color-accent: #7fd1bb; + --color-accent-strong: #a3e4d3; + --color-accent-pressed: #5fbfa8; + + /* ---- Outcome hues (the app's own: ok / warn / bad) -------------------- */ + --color-ok: #6bd39a; + --color-warn: #e6c268; + --color-bad: #ef8a8a; + + /* ---- Run-status palette (the web's current values, unchanged) ---------- */ + /* These are copied from the current base.css/.chip-* rules. Three values + (succeeded, failed, interrupted) are the web's tuned rendering; the Compose + RunStatusPalette uses slightly different stops. This item does not re-tune + any status hue. */ + --status-queued: #9aa6a2; + --status-running: #7fb2f0; + --status-active: #7fb2f0; + --status-waiting: #8edff5; + --status-succeeded: #6bd39a; + --status-failed: #ef8a8a; + --status-canceled: #889391; + --status-interrupted: #e6c268; + --status-blocked: #f0a35e; + --status-skipped: #a8b8c8; + --status-unknown: #bec9c5; + + /* Status washes tint the chip body; the neutral chip edge does the 3:1 + boundary work, so a wash never has to carry the component alone. */ + --status-queued-wash: rgba(154, 166, 162, 0.10); + --status-running-wash: rgba(127, 178, 240, 0.10); + --status-active-wash: rgba(127, 178, 240, 0.10); + --status-waiting-wash: rgba(142, 223, 245, 0.10); + --status-succeeded-wash: rgba(107, 211, 154, 0.10); + --status-failed-wash: rgba(239, 138, 138, 0.10); + --status-canceled-wash: rgba(136, 147, 145, 0.06); + --status-interrupted-wash: rgba(230, 194, 104, 0.10); + --status-blocked-wash: rgba(240, 163, 94, 0.10); + --status-skipped-wash: rgba(168, 184, 200, 0.10); + --status-unknown-wash: rgba(190, 201, 197, 0.10); + + /* ---- Interaction tints ------------------------------------------------- */ + /* A tint is a transparent wash laid over whatever surface is already there; + it never replaces a surface role. */ + --tint-hover: rgba(222, 228, 225, 0.05); + --tint-pressed: rgba(222, 228, 225, 0.09); + --tint-selected: rgba(127, 209, 187, 0.12); + --tint-selected-strong: rgba(127, 209, 187, 0.20); + --tint-accent-soft: rgba(127, 209, 187, 0.10); + --tint-ok-soft: rgba(107, 211, 154, 0.10); + --tint-warn-soft: rgba(230, 194, 104, 0.10); + --tint-bad-soft: rgba(239, 138, 138, 0.10); + --tint-info-soft: rgba(142, 223, 245, 0.10); + + /* ---- Spacing: 8px grid with 4px half-steps ----------------------------- */ + /* 3xs is the only 2px step, reserved for optical alignment (a glyph against + a label), never for layout. */ + --space-3xs: 2px; + --space-2xs: 4px; + --space-xs: 8px; + --space-s: 12px; + --space-m: 16px; + --space-l: 24px; + --space-xl: 32px; + --space-2xl: 40px; + --space-3xl: 48px; + --space-4xl: 64px; + + /* Role aliases: use these in components, not the t-shirt scale. */ + --space-inline-tight: var(--space-2xs); /* glyph + label */ + --space-inline: var(--space-xs); /* buttons in a toolbar */ + --space-inline-loose: var(--space-s); /* chips in a row */ + --space-stack-tight: var(--space-2xs); /* title + meta */ + --space-stack: var(--space-xs); /* lines inside a block */ + --space-block: var(--space-m); /* block to block */ + --space-section: var(--space-l); /* section to section */ + --space-page: var(--space-xl); /* page / pane padding */ + --space-field-gap: var(--space-xs); /* label to field */ + --space-control-pad-inline: var(--space-s); + --space-control-pad-block: var(--space-2xs); + --space-row-pad-inline: var(--space-s); + --space-panel-pad: var(--space-m); + --space-pane-pad: var(--space-m); + + /* ---- Density ----------------------------------------------------------- */ + /* Density changes padding and control height, never type size, so a compact + list stays readable. Set data-density="compact" on a container. */ + --density-row-pad-block: var(--space-s); + --density-row-pad-inline: var(--space-s); + --density-row-gap: var(--space-2xs); + --density-control-height: 36px; + --density-control-height-small: 30px; + --density-touch-target: 44px; + --density-touch-target-large: 48px; + + /* ---- Radii ------------------------------------------------------------- */ + --radius-xs: 4px; /* inline code */ + --radius-s: 6px; /* tiny marker, count badge */ + --radius-control: 8px; /* button, field, row, menu item */ + --radius-card: 12px; /* pane, card, tile, transcript group */ + --radius-sheet: 16px; /* dialog and sheet */ + --radius-pill: 999px; /* chip, count pill, terminal node */ + + /* ---- Type -------------------------------------------------------------- */ + --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; + --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; + + /* Sizes: 11 / 12 / 13 / 14 / 16 / 20 / 24. Roles, not numbers, at call sites. */ + --type-eyebrow: 600 11px/14px var(--font-sans); + --type-label: 600 11px/16px var(--font-sans); + --type-meta: 400 12px/16px var(--font-sans); + --type-body-small: 400 13px/18px var(--font-sans); + --type-body: 400 14px/20px var(--font-sans); + --type-title-small: 600 16px/22px var(--font-sans); + --type-title: 600 20px/26px var(--font-sans); + --type-display: 600 24px/30px var(--font-sans); + --type-code: 400 12px/18px var(--font-mono); + --type-code-small: 400 11px/16px var(--font-mono); + + --weight-regular: 400; + --weight-medium: 500; + --weight-semibold: 600; + --tracking-eyebrow: 0.06em; + --tracking-tight: -0.01em; + + /* ---- Elevation --------------------------------------------------------- */ + /* Elevation is reserved for things that float above the page: a menu, a + dialog, a sheet, a toast. A pane or card never casts a shadow. */ + --elevation-1: 0 1px 2px rgba(0, 0, 0, 0.32); + --elevation-2: 0 8px 24px rgba(0, 0, 0, 0.42); + --elevation-3: 0 18px 48px rgba(0, 0, 0, 0.52); + --elevation-sheet: 0 -16px 48px rgba(0, 0, 0, 0.55); + --elevation-menu: var(--elevation-2); + --elevation-dialog: var(--elevation-3); + --elevation-toast: var(--elevation-2); + + /* ---- Focus ------------------------------------------------------------- */ + --focus-ring-width: 2px; + --focus-ring-offset: 2px; + --focus-ring-color: var(--color-focus); + --focus-ring: 0 0 0 var(--focus-ring-width) var(--focus-ring-color); + --focus-ring-inset: inset 0 0 0 var(--focus-ring-width) var(--focus-ring-color); + --focus-halo: 0 0 0 var(--focus-ring-width) var(--color-bg), + 0 0 0 calc(var(--focus-ring-width) + var(--focus-ring-offset)) var(--color-focus); + + /* ---- Motion ------------------------------------------------------------ */ + /* fast hover / press feedback + base selection, expansion, focus colour + slow dialog and sheet entry + spin an indeterminate spinner's one rotation */ + --motion-instant: 80ms; + --motion-fast: 120ms; + --motion-base: 180ms; + --motion-slow: 240ms; + --motion-spin: 800ms; + --ease-standard: cubic-bezier(0.2, 0, 0, 1); + --ease-out: cubic-bezier(0, 0, 0, 1); + --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1); + + /* ---- Layout ------------------------------------------------------------ */ + --layout-rail: 200px; + --layout-list-min: 200px; + --layout-list-max: 360px; + --layout-dock: 60px; + --layout-hairline: 1px; + --layout-measure: 72ch; + --layout-chat-measure: 560px; + --layout-dialog: 440px; + --layout-sheet: 560px; + --layout-menu: 240px; + + --icon-status: 14px; + --icon-small: 16px; + --icon-inline: 18px; + --icon-list: 20px; + --icon-rail: 24px; + + --layer-sticky: 10; + --layer-popover: 20; + --layer-dialog: 40; + --layer-toast: 50; + + /* ---- Transitional aliases --------------------------------------------- */ + /* The existing stylesheets use these short names. They map onto the roles + above so a file can be migrated one rule at a time; new CSS should use the + --color-* / --type-* / --space-* roles directly. */ + --bg: var(--color-bg); + --surface: var(--color-surface); + --surface-2: var(--color-surface-2); + --elevated: var(--color-elevated); + --border: var(--color-border); + --border-strong: var(--color-border-strong); + --text: var(--color-text); + --muted: var(--color-muted); + --accent: var(--color-accent); + --ok: var(--color-ok); + --warn: var(--color-warn); + --bad: var(--color-bad); +} + +/* Compact density is a scope, not a second theme: same colours, same type, + tighter row padding and a shorter control. */ +[data-density="compact"] { + --density-row-pad-block: var(--space-xs); + --density-row-pad-inline: var(--space-s); + --density-row-gap: var(--space-3xs); + --density-control-height: 30px; + --density-control-height-small: 24px; +} diff --git a/web/docs/visual-system.md b/web/docs/visual-system.md new file mode 100644 index 00000000..310fb373 --- /dev/null +++ b/web/docs/visual-system.md @@ -0,0 +1,445 @@ +# Pipelines web client — visual system + +Design-only deliverable. It does not change `web/src`, `web/styles.css`, +`web/index.html`, any area stylesheet or any test. The reference implementation is +`web/design/tokens/styleguide.html` + `styleguide.css`, built entirely from +`tokens.css`. + +Sources read for this refinement: + +- `web/base.css`, `lists.css`, `run-detail.css`, `chat.css`, `graph.css`, + `dialogs.css`, `settings.css` — the current palette, chip, radius and shadow + vocabulary. +- `web/design/layout/prototype.html`, `prototype.css`, `web/docs/layout-spec.md` + — the target rail + list/detail shell and its 200px rail. +- `android/.../ui/theme/Color.kt`, `Typography.kt`, `Dimens.kt`, `Theme.kt` — + the app's dark identity, type intent and 4dp-derived spacing. +- `android/.../ui/components/RunStatus.kt` — the app-owned status vocabulary. + +The result keeps the app's dark canvas, mint accent and the web's current +run-status hues. It is a refinement of hierarchy and reuse, not a new brand. + +--- + +## 1. The layer model + +One canvas, four surface steps, one scrim. Every component picks a layer from this +table; no component invents a background. + +| Layer | Token | Used by | Never | +| --- | --- | --- | --- | +| Canvas | `--color-bg` | Page, list/detail pane body, chat transcript, code body, artifact thumb base | A static card that also has a border and a shadow | +| Base surface | `--color-surface` | Left rail, top bar, toolbar, card, detail section, composer shell, approval card, empty state | A row inside another card; use a tint instead | +| Inset surface | `--color-surface-2` | Button/field fill, row fill when needed, chip body, inline code, code header, user bubble, sheet row, artifact tile | A card on top of a card; never `surface-2` on `surface-2` | +| Elevated | `--color-elevated` | Menu, popover, dialog, sheet, toast, tool panel | A normal page card | +| Highest | `--color-elevated-2` | Hover on an elevated control, gradient stop | A page background | +| Scrim | `--color-scrim` | Behind a dialog, sheet or full-screen viewer | A content background | + +Rules: + +1. **One step per nesting level.** Pane (`bg`) → card (`surface`) → control + (`surface-2`). Do not put another `surface` card inside a card; use padding, + a divider or a tint. +2. **A tint is not a layer.** Hover, pressed and selected are transparent washes + (`--tint-*`) laid over the surface that is already there. They never replace a + surface role. +3. **Elevation means floating.** A shadow is reserved for menus, dialogs, sheets, + toasts and the tool panel. A pane or card never casts one. +4. **The transcript is the page.** The agent turn sits directly on `bg`; only the + operator's bubble takes `surface-2`. This removes the current transcript → + agent bubble → tool section → code block stack of four fills. + +### Which surface for each named layer + +| Area | Surface | +| --- | --- | +| App shell / page | `bg` | +| Rail | `surface`, separated from the workspace by a `divider` edge | +| List pane / detail pane | `bg`; the wide split uses a divider, not a card | +| Top bar / connection banner | `surface` + bottom divider; banner states use `surface-2`, `tint-warn-soft`, `tint-bad-soft` | +| List row | transparent on the pane; hover `tint-hover`; selected `tint-selected` + 2px accent inset | +| Toolbar | `surface`; its controls `surface-2` with a `border` | +| Card / detail section | `surface`, no border; sections separated by `space-section` | +| Key/value table | on the card surface; use spacing or a divider, never a per-row box | +| Code block | `bg` body, `surface-2` header, one outer `border` | +| Dialog / sheet / menu | `elevated` + `border` + matching elevation + scrim where modal | +| Chat user bubble | `surface-2` + `border` | +| Chat agent turn | transparent on `bg`; code block is the only framed part | +| Composer | `surface` shell + `border`; the textarea itself is transparent | +| Approval card | `surface` + `border` + 3px warning inset; resources `bg`; risk `tint-warn-soft` | +| Artifact tile | `surface-2` + `border`; media fills the tile; actions overlay it | +| Empty state | `surface` + `space-l` padding; a sentence and at most one action | + +--- + +## 2. Border or background? + +Use **background** to group, **border** to identify a control, **divider** to +separate content inside one surface. + +| Need | Use | Do not use | +| --- | --- | --- | +| A card or section | A `surface` step and spacing | Border + radius + shadow on a static block | +| A button, input, tile, selected row, dialog | `--color-border` (≥3:1 on all surfaces) | `--color-divider`, which is decorative and below 3:1 | +| A separator between rows or sections | `--color-divider` (1px) | A border around each row | +| A selected row | `tint-selected` + 2px inset accent bar + weight | A 1px accent border alone | +| A focused control | The 2px focus ring with a 2px offset | Recolouring the border and calling it focus | +| A destructive confirm | `--color-bad` text/edge + `tint-bad-soft` | A red-filled button for a secondary action | +| A floating panel | `elevated` + `border` + one elevation | A border pretending to be a shadow | + +Rules: + +1. **A border is a control edge, not decoration.** `--color-border` is `#6a7874` + so it stays above 3:1 on `bg`, `surface`, `surface-2` and `elevated`. The old + `#2c3a36` border is now `--color-divider` and is only for non-interactive + separation. +2. **Never border, fill and shadow the same static box.** Pick the grouping + mechanism: a surface step, a divider, or a floating elevation. +3. **No border-only selection.** The selected row also changes weight and adds the + accent bar; the `aria-current`/`aria-selected` state carries the semantics. +4. **No accent border on hover.** Hover is a 5% wash. Accent is reserved for + active, focus and the primary action. Today every `button:hover` turns its + border mint, which makes ordinary hover look selected. +5. **One border around a group.** A code card frames once; the header uses a + divider, not a second border. A dialog frames once; its rows use a surface or + spacing. + +--- + +## 3. Chips and badges + +There is one chip component. + +``` +.chip + glyph (aria-hidden, optional) + the status word + height 22px · padding 1px 8px · radius pill · type-label 11/16 600 + neutral border (3:1) · status wash background · status-colour text +``` + +Status mapping (the web's current status palette, unchanged): + +The values below are copied byte-for-byte from the current `base.css` status +rules. They are the web's tuned rendering of the app's status vocabulary; this +item does not re-tune a single hue. + +| Word | Token | Wash | Glyph | +| --- | --- | --- | --- | +| `queued` | `--status-queued` | `--status-queued-wash` | `◷` | +| `running` | `--status-running` | `--status-running-wash` | `▶` | +| `waiting` | `--status-waiting` | `--status-waiting-wash` | `…` | +| `succeeded` | `--status-succeeded` | `--status-succeeded-wash` | `✓` | +| `failed` | `--status-failed` | `--status-failed-wash` | `✕` | +| `canceled` | `--status-canceled` | `--status-canceled-wash` | `⊘` | +| `interrupted` | `--status-interrupted` | `--status-interrupted-wash` | `‖` | +| `blocked` | `--status-blocked` | `--status-blocked-wash` | `■` | +| `skipped` | `--status-skipped` | `--status-skipped-wash` | `»` | +| `active` | `--status-active` | `--status-active-wash` | `◆` | +| `unknown` | `--status-unknown` | `--status-unknown-wash` | `?` | + +Rules: + +1. **Never colour alone.** Every status chip carries its glyph and its word. The + glyph may be `aria-hidden` because the word is present. +2. **Use the server's vocabulary verbatim.** Status words stay lowercase; the + uppercase role is the eyebrow/overline, never a status label. +3. **One chip, tone modifiers only.** `chip--succeeded`, `chip--failed`, etc. + change colour and wash; they do not change height, radius or type. Delete the + parallel `.outcome-chip`, `.version-chip`, `.graph-type-chip` and + `.verdict-ref` shapes. +4. **A chip is a fact, not an action.** A chip is never a button and never nested + inside another chip. If it opens something, use a row or a link. +5. **Neutral is a tone for a non-status fact.** A version (`v5`) or a file kind + (`PDF`) can use `chip--neutral`; it must not borrow `--status-unknown` and must + not be used for a run state. +6. **Counts are a count chip, not a status chip.** `chip--count` is a neutral + pill with a minimum width, used for `12` or `Filter (2)`. +7. **Badges are attached, not inline.** The attention count is a small filled + bubble (`--color-bad` + `--color-on-bad`) with a number; the live badge is a + dot plus the word `live`. Neither replaces a status chip. +8. **One fact, one chip.** Do not show `failed` twice in a row (chip plus a + coloured diagnostic line); the chip carries the state, the diagnostic carries + the reason. + +--- + +## 4. Spacing inside vs between + +The layout scale is 8px with 4px half-steps. A separate 2px optical step exists +only for aligning a glyph against a label; it is never a layout gap. + +| Inside | Value | +| --- | --- | +| Icon/label gap | 4px | +| Control padding (block × inline) | 4 × 12px | +| Row padding, light (comfortable) | 12 × 12px | +| Row padding, compact | 8 × 12px | +| Card / panel padding | 16px | +| Dialog padding | 16px | +| Sheet padding | 12px vertical, 16px horizontal | +| Code body padding | 12px | +| Chip / count padding | 1 × 8px | + +| Between | Value | +| --- | --- | +| Chips or toolbar controls | 8px | +| Title and meta | 2–4px | +| Lines in a block | 8px | +| Block to block (card sections) | 16px | +| Section to section | 24px | +| Page / pane edge | 32px (24px narrow) | + +Rules: + +1. **One owner per gap.** Use `gap` on the container; do not add a margin to the + last child and a gap on the parent. +2. **Padding inside is smaller than space between.** If a card's padding equals + the gap to the next card, the grouping reads as one block. +3. **No nested padding beyond 24px.** Card 16 + panel 16 + row 12 is 44px of + inset for a 14px label. Remove a layer or reduce to 16 + 8. +4. **List separation is either a gap or a divider, never both.** The refined + lists use a 2px gap and no row border; day headers use a divider. +5. **Density changes geometry only.** Compact changes row block padding 12 → 8 + and control height 36 → 30. Type, line height and touch targets do not shrink. + Touch surfaces (rail, dock, primary row actions) stay 44/48px. + +--- + +## 5. Type roles + +| Role | Size / line | Weight | Use | +| --- | --- | --- | --- | +| `--type-eyebrow` | 11 / 14 | 600 | Overline (`WORKSPACE`, `SECTIONS`, `RISK REVIEW`); tracking 0.06em, uppercase | +| `--type-label` | 11 / 16 | 600 | Chip and badge labels | +| `--type-meta` | 12 / 16 | 400 | Meta lines, key labels, captions, helper text | +| `--type-body-small` | 13 / 18 | 400 | Dialog copy, empty-state copy, dense prose | +| `--type-body` | 14 / 20 | 400 | Default body, row titles (add 600), toolbar labels | +| `--type-title-small` | 16 / 22 | 600 | Card title, dialog/sheet title, approval headline | +| `--type-title` | 20 / 26 | 600 | Screen title (`Pipelines`, `Runs`) | +| `--type-display` | 24 / 30 | 600 | The app's largest title; rare | +| `--type-code` | 12 / 18 | 400 mono | Commands, diffs, code blocks | +| `--type-code-small` | 11 / 16 | 400 mono | Inline code, hashes, timestamps in tables | + +Rules: + +1. **Roles, not sizes.** No `font-size` literal in an area stylesheet. The current + CSS has ten distinct sizes (10, 11, 12, 12.5, 13, 14, 15, 16, 18, 20) plus a + 40px viewer glyph; collapse to the seven sizes above. +2. **Three weights.** 400, 500, 600. Do not introduce 650/700; the app is + semibold-led, not bold-led. +3. **Sentence case for actions and titles.** Uppercase is only the eyebrow / + overline role. Status words stay lowercase. +4. **Tabular numbers** for timestamps, durations, counts and IDs: + `font-variant-numeric: tabular-nums`. +5. **Mono is for data, not emphasis.** Hashes, paths, commands, code and IDs in a + table. A pipeline name or a status word is never mono. +6. **Measure.** Prose is capped at `--layout-measure` (72ch); a chat bubble at + `--layout-chat-measure` (560px). + +--- + +## 6. State, focus and motion + +### Focus + +- One ring: `outline: 2px solid var(--color-focus)` with `outline-offset: 2px`. + `--color-focus` is `#a9f0dd`, 13.2:1 on `surface` and 11:1 on `elevated`. +- Use `:focus-visible`; do not show the ring on a mouse click. +- A filled accent button uses the halo (`--focus-halo`) so the ring sits on the + page, not on the mint fill. +- A composite field (search wrapper, composer shell) uses `:focus-within` and + removes the inner input outline. +- Never `outline: none` without a replacement. Today `.decision-feedback:focus`, + `.template-create-name:focus` and `.rename-input:focus` only recolour the + border; `.timeline-row:focus-visible` explicitly removes the outline. +- An invalid field keeps the focus ring and uses the bad colour for the message + and border, not for the ring. + +### Interaction states + +| State | Treatment | Structural cue | +| --- | --- | --- | +| Hover | `--tint-hover` (5%) | none needed | +| Pressed | `--tint-pressed` (9%) | none needed | +| Selected | `--tint-selected` (12%) | 2px inset accent bar + 600 weight | +| Active / current | `--tint-selected` + accent bar | `aria-current` / `aria-selected` | +| Disabled | `--opacity-disabled` (0.5) | `disabled` / `aria-disabled` | + +Selection is never colour alone: the bar and the weight are the non-colour cue. + +### Motion + +- `--motion-fast` 120ms for hover/press, `--motion-base` 180ms for selection and + expansion, `--motion-slow` 240ms for dialog/sheet entry, `--motion-spin` 800ms + for an indeterminate spinner. +- Standard easing `cubic-bezier(0.2, 0, 0, 1)`. +- Under `prefers-reduced-motion: reduce`, transitions and animations collapse to + an immediate state, scroll behaviour becomes `auto`, and no selected or focus + state is removed. The styleguide implements this globally. + +--- + +## 7. What to remove from today's CSS + +### 7.1 Nested boxes + +Remove the second and third frame in each chain: + +- `base.css` — `.list` / `.detail` (border + radius) wraps `.row` (bottom border) + and `.step` (border + radius), and `.artifact-tile` adds another border and + radius. A run detail is three borders deep. +- `run-detail.css` — `.verdict` and `.field-block` frame content inside + `.stage-pane-sheet`; `.change-hunk` frames a diff inside `.change-viewer`. +- `chat.css` — `.chat-transcript` (border) → `.chat-bubble` (border) → optional + `.chat-tool-section` (border) → `.chat-tool-section-body` (bg). The approval + card is `.chat-approval` (border) → `.chat-approval-resources` (border) → + `.chat-approval-risk` (wash). That is three nested boxes for one decision. +- `dialogs.css` — `.attention-sheet-panel` → `.attention-row` → the inner + `.attention-row-open`; `.decision-sheet-panel` → `.decision-option`. +- `settings.css` — each `.settings-status`, `.settings-warning`, + `.settings-notify-state` and `.settings-card` is its own bordered box inside the + section. + +Replace with: one pane surface, one card surface, spacing, and a divider where a +boundary is genuinely needed. + +### 7.2 Duplicate chip styles + +There are at least six parallel chip shapes: + +| Selector | File | Problem | +| --- | --- | --- | +| `.chip` + `.chip-*` | `base.css` | The canonical shape, 11px pill | +| `.outcome-chip` + `.outcome-*` | `run-detail.css` | Second pill, `currentColor` border | +| `.verdict-ref` | `run-detail.css` | Third pill, 11px | +| `.version-chip` | `lists.css` | Fourth pill, surface fill | +| `.graph-type-chip` | `graph.css` | Fifth pill, 11px | +| `.graph-edge-label` | `graph.css` | Sixth pill-shaped label | +| `.attention-badge` | `dialogs.css` | A badge, correctly distinct; keep but tokenise | + +Delete the five chip duplicates. Keep one `.chip`, one `.chip--count`, and the +attention badge as a badge. The graph edge label is a label, not a status chip: +style it with `type-code-small` and no status tone. + +### 7.3 Inconsistent radii and heights + +- Radii in the current files: 0, 2px, 4px, 6px, 8px, 10px, 12px, 14px, 50%, + 999px. Collapse to `4 / 6 / 8 / 12 / 16 / pill`; use 50% only for a dot or a + circular poster. +- Control heights: about 22px (artifact action), 30px (approval control), 32px + (toolbar/tool), 36px (inputs), 40px (chat send), 44px (rail/strip), 48px (dock). + Standardise on **30px compact**, **36px comfortable**, **44/48px touch**. +- `.chat-send` and `.chat-stop` are 16px glyph buttons with 8px 12px padding while + `.chat-composer-input` is 20px line-height; they do not align. Put both on the + same 36px row. +- `.artifact-action` at 22px is below the 24px minimum for a secondary target; + use 30px or move the actions into a menu. + +### 7.4 Raw colour, alpha and shadow duplication + +- Status hexes are repeated in `base.css` (`.chip-*`), `lists.css` + (`.metric-*`), `run-detail.css` (`.outcome-*`), `dialogs.css` + (`.decision-card`, `.decision-open`) and `graph.css` (`.chip-unknown`). One + `--status-*` token per state. +- Banner and decision hexes `#2c1616`, `#12251b`, `#2a2410`, `#102329` are + one-off colours. Use `tint-bad-soft`, `tint-ok-soft`, `tint-warn-soft` and + `tint-info-soft`. +- Floating shadows have six recipes (`0 10px 30px`, `0 12px 32px`, + `0 16px 40px`, `0 20px 60px`, `0 -12px 40px`, `-12px 0 40px`). Use + `--elevation-2` / `--elevation-3` / `--elevation-sheet`. +- Inline `rgba(...)` tints (`rgba(127, 209, 187, 0.12)`, `rgba(0, 0, 0, 0.45)`) + become `--tint-*` and `--color-scrim`. + +### 7.5 Focus and hover + +- Add a base `:focus-visible` rule; today `base.css` has none, so buttons and + inputs rely on the browser default. +- Remove `outline: none` from `.timeline-row:focus-visible`, + `.decision-feedback:focus`, `.template-create-name:focus` and + `.rename-input:focus`. +- Stop using `border-color: var(--accent)` as the only hover signal on every + button, card, tile and menu item. Hover = tint; accent = active/focus/primary. +- Unify the four focus offsets (`1px`, `-2px`, `-1px`, `2px`) to the token. + +### 7.6 Disabled and opacity + +The files use `opacity: 0.4`, `0.45`, `0.5`, `0.55`, `0.6` and `0.8` for +disabled, unavailable and closed states. Use `--opacity-disabled: 0.5` for a +disabled control; do not fade a whole card to hide it. + +--- + +## 8. The six biggest before/after improvements + +| # | Before | After | +| --- | --- | --- | +| 1 | **Boxes inside boxes.** A run row is a bordered `.row` inside a bordered `.list`; a chat decision is three nested fills/borders; a settings section has a card per block. | One pane surface, one card, spacing and dividers. A row is a control on the pane; only a floating surface has elevation. | +| 2 | **Six chip dialects.** `.chip`, `.outcome-chip`, `.verdict-ref`, `.version-chip`, `.graph-type-chip`, `.graph-edge-label` each set their own height, radius and type. | One `.chip` with tone modifiers, a count chip and one attention badge. Every status carries a glyph and its word. | +| 3 | **Every control invents a height.** 22–48px buttons, fields, tiles and composer actions do not line up across a toolbar. | 30px compact / 36px comfortable / 44–48px touch, one control radius, one icon size. Toolbars and the composer align on one baseline. | +| 4 | **Accent borders on hover.** Every button, tile and card turns mint on hover, making hover look focused and selection look ordinary. | Hover is a 5% wash. Accent is reserved for active, focus and the primary action; selection adds a 2px bar and weight. | +| 5 | **Ten ad-hoc type sizes.** 10, 11, 12, 12.5, 13, 14, 15, 16, 18, 20px with three near-identical section headers. | Seven sizes across eight roles plus two mono roles: 11 / 12 / 13 / 14 / 16 / 20 / 24 with fixed line heights and 400/500/600 weights. | +| 6 | **Focus is a border colour, when it exists at all.** Some inputs remove the outline; a focused timeline row is indistinguishable from hover; `base.css` has no focus rule. | One 2px `#a9f0dd` ring with a 2px offset on every focusable control, `:focus-within` on composite fields, and a halo on filled accent buttons. | + +These six are ordered for migration: each one is independently shippable and each +removes more CSS than it adds once the old selectors are deleted. + +--- + +## 9. Adopt it without a redesign + +1. **Add `tokens.css` first.** It is custom properties only; linking it changes + nothing until a rule consumes a token. The `--bg`, `--surface`, `--border` + aliases at the bottom of the file let the existing stylesheets keep working + while they migrate one rule at a time. +2. **Collapse one area at a time.** Start with `lists.css` (rows, toolbar, + filter menu) because it owns the clearest box-in-box chain. Then + `run-detail.css`, then `chat.css`, then `settings.css`. +3. **Delete duplicate chips in the same change that introduces the unified one.** + Do not leave both `.chip` and `.outcome-chip` shipping. +4. **Move focus to the base layer.** Add the focus rule and remove the + `outline: none` exceptions before touching colour, so keyboard users never + regress. +5. **Keep the app's words and status colours.** This system changes surfaces, + spacing and shape; it does not rename a run state or invent a new outcome hue. + +--- + +## 10. Captures and verification + +Capture command (no server, no build step): + +```sh +node web/design/tokens/capture.mjs +``` + +Captured at **1440 × 900** through the repository's read-only +`web/test/browser.mjs` driver at device scale 1: + +- `web/design/tokens/captures/styleguide-01-foundations-1440x900.png` +- `web/design/tokens/captures/styleguide-02-type-1440x900.png` +- `web/design/tokens/captures/styleguide-03-space-1440x900.png` +- `web/design/tokens/captures/styleguide-04-rail-1440x900.png` +- `web/design/tokens/captures/styleguide-05-lists-1440x900.png` +- `web/design/tokens/captures/styleguide-06-data-1440x900.png` +- `web/design/tokens/captures/styleguide-07-overlays-1440x900.png` +- `web/design/tokens/captures/styleguide-08-conversation-1440x900.png` +- `web/design/tokens/captures/styleguide-09-content-1440x900.png` + +The captures are review evidence and are covered by the repository's root +`captures/` ignore rule, like the layout captures. + +Contrast was checked against the defined surfaces: + +| Pair | Ratio | +| --- | --- | +| `--color-text` / `--color-bg` | 14.35:1 | +| `--color-text` / `--color-surface` | 13.29:1 | +| `--color-muted` / `--color-surface` | 8.47:1 | +| `--color-border` / `--color-surface` | 3.71:1 | +| `--color-border` / `--color-elevated` | 3.09:1 | +| `--color-focus` / `--color-surface` | 13.21:1 | +| lowest status text / its chip wash (canceled) | 4.75:1 | + +No production app stylesheet, view, markup or test was changed. The production +page still renders from the current area stylesheets; this is the target system +and its evidence, not a live restyle.