diff --git a/.agents/agents/component-builder.md b/.agents/agents/component-builder.md index 9e7af8a..bb2d17f 100644 --- a/.agents/agents/component-builder.md +++ b/.agents/agents/component-builder.md @@ -28,9 +28,11 @@ You may not edit `tokens.css`, `verify.mjs`, `astro.config.mjs`, or - No raw hex, no px font sizes, no ad-hoc breakpoints. Tokens only. - **Never reshape CSS to slip past `check-tokens.mjs`** — e.g. the `font:` - shorthand to hide a px size it would catch as `font-size:`. If the token you - need does not exist, report the gap and stop; you may not add it yourself. See - `.agents/rules/gates.md`. + shorthand to hide a px size it would catch as `font-size:` — and never point a + legacy value at the nearest token that happens to exist. Both are silent + redesigns. Keep the true value and mark it + `/* token-gap: ; owner design-system-keeper */`, which waives the + finding and queues it. You may not add tokens. See `.agents/rules/gates.md`. - No `client:*` unless genuinely interactive, with written justification. - Every ARIA attribute from the markup you replace survives. `verify.mjs` asserts several by name. diff --git a/.agents/rules/gates.md b/.agents/rules/gates.md index 233f262..1c8c957 100644 --- a/.agents/rules/gates.md +++ b/.agents/rules/gates.md @@ -66,16 +66,34 @@ worse than failing, because failure is visible and this is not. `font:` shorthand passes it. Task 07 did exactly that, in **two** components, with a comment saying so. Both hardcoded values survived into a "green" branch. -When a token you need does not exist: +### Do not substitute a near-miss token either -1. Stop. Do not invent a value, and do not reshape the syntax to hide one. -2. Write the gap in your task report: the selector, the legacy value(s) it comes - from, and which file owns the token. -3. If your task cannot proceed without it, say so and stop. A blocked task is a - finding. A silently-passing one is a defect that ships. +The second way to break this is subtler, and both tasks 10 and 11 did it: keep +the gate happy by pointing a legacy value at the closest token that already +exists. `#e5eeeb` became `var(--paper)`. Diff-**added** green became +`var(--accent)` — purple. `12px` and `14px` both became `var(--step-1)`, 15px. -`tokens.css` has a single owner (`design-system-keeper`) precisely so that "add -a token" is a decision, not a side effect. +That is a silent redesign, and it is _worse_ than leaving the raw value in, +because a raw hex is at least honest about being unresolved. + +### What to do instead: mark the gap + +`tokens.css` has one owner (`design-system-keeper`) so that "add a token" is a +decision, not a side effect. You may not add one. You **can** keep the true +value and stay green — mark it: + +```css +/* token-gap: no --step-* covers 12px; owner design-system-keeper */ +font-size: 12px; +``` + +The marker waives that one finding. It needs a real reason after the colon; a +bare `token-gap:` is rejected. Every marked value is listed on each run, so the +debt stays visible rather than disappearing. + +Write it in your task report as well: selector, legacy value, owning file. +Marking a gap is not resolving it — it keeps the site truthful until whoever +owns the token layer decides. ## Parallelism diff --git a/.agents/scripts/check-tokens.mjs b/.agents/scripts/check-tokens.mjs index efc78f7..fea3e29 100755 --- a/.agents/scripts/check-tokens.mjs +++ b/.agents/scripts/check-tokens.mjs @@ -3,6 +3,23 @@ // the token layer. A rule nobody checks is a suggestion — wire this into // `pnpm run verify`. // +// ESCAPE HATCH — `token-gap:`. Some legacy values have no token yet, and only +// `design-system-keeper` may add one. Without an escape, an agent told both +// "keep the site identical" and "get the gate green" has to break one of them, +// and tasks 10 and 11 both broke the first: `#e5eeeb` became `var(--paper)`, +// diff-added green became `var(--accent)` purple. Substituting a near-miss +// token is a silent redesign; it is worse than a raw value, because the raw +// value is at least honest about what it is. +// +// So: mark the line, keep the true value, stay green. +// +// /* token-gap: no --step-* covers 12px; owner design-system-keeper */ +// font-size: 12px; +// +// Marked values are counted and listed on every run — they are a visible debt +// queue, not a way to make the finding disappear. The marker needs a reason; +// a bare `token-gap:` does not count. +// // Usage: node .agents/scripts/check-tokens.mjs [srcDir] import { readdirSync, readFileSync, statSync } from 'node:fs'; @@ -24,35 +41,62 @@ const targets = ARGS.length : walk('src'); const findings = []; +const gaps = []; + +// A finding is waived when its own line, or the line above it, carries a +// `token-gap:` marker with a reason after the colon. +const MARKER = /token-gap:([^\n]*)/; +// The reason is what is left after the marker once the comment terminator and +// punctuation are stripped. `/* token-gap: */` is not a reason. +const reason = (line) => { + const found = MARKER.exec(line ?? ''); + if (!found) return null; + const text = found[1] + .replace(/\*\/\s*$/, '') + .replace(/[\s*/]+$/, '') + .trim(); + return /[a-z0-9]/i.test(text) ? [null, text] : null; +}; +const waiver = (lines, index) => + reason(lines[index]) || (index > 0 ? reason(lines[index - 1]) : null); for (const path of targets) { if (!['.astro', '.css'].includes(extname(path))) continue; if (TOKEN_FILES.some((allowed) => path.endsWith(allowed))) continue; - readFileSync(path, 'utf8') - .split('\n') - .forEach((line, index) => { - const at = `${path}:${index + 1}`; + const lines = readFileSync(path, 'utf8').split('\n'); + lines.forEach((line, index) => { + const at = `${path}:${index + 1}`; + const waived = waiver(lines, index); + const record = (finding) => { + if (waived) gaps.push(`${at}: ${finding.slice(at.length + 2)} [${waived[1]}]`); + else findings.push(finding); + }; - // Raw hex — the drifted-palette failure mode this whole layer exists to stop. - const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g); - if (hex) findings.push(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`); + // Raw hex — the drifted-palette failure mode this whole layer exists to stop. + const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g); + if (hex) record(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`); - // rgb()/hsl() literals are the same problem wearing a different hat. - if (/\b(rgba?|hsla?)\(\s*\d/.test(line)) - findings.push(`${at}: raw colour function — use a token`); + // rgb()/hsl() literals are the same problem wearing a different hat. + if (/\b(rgba?|hsla?)\(\s*\d/.test(line)) record(`${at}: raw colour function — use a token`); - // Hard-coded font sizes bypass the type scale. - const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/); - if (fontSize) findings.push(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`); + // Hard-coded font sizes bypass the type scale. + const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/); + if (fontSize) record(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`); - // Ad-hoc breakpoints are how sixteen of them accumulated last time. - const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/); - if (media && !ALLOWED_BREAKPOINTS.includes(media[1])) - findings.push( - `${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`, - ); - }); + // Ad-hoc breakpoints are how sixteen of them accumulated last time. + const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/); + if (media && !ALLOWED_BREAKPOINTS.includes(media[1])) + record( + `${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`, + ); + }); +} + +if (gaps.length) { + console.log(`token check: ${gaps.length} marked token-gap(s) awaiting design-system-keeper:\n`); + gaps.forEach((gap) => console.log(` ${gap}`)); + console.log(''); } if (findings.length) { diff --git a/src/components/blocks/ChapterHero.astro b/src/components/blocks/ChapterHero.astro new file mode 100644 index 0000000..2a8eb7f --- /dev/null +++ b/src/components/blocks/ChapterHero.astro @@ -0,0 +1,82 @@ +--- +// ChapterHero — eyebrow + display headline + intro paragraph. The shared +// opener for /models/, /agents/, /skills/, /summary/. The optional `foot` +// slot holds the rules case-study's two-column hero-foot. +// +// The eyebrow reuses the existing `Eyebrow` primitive but defaults to the +// `red` tone, which matches the chapter surfaces (not the guide surface). +// The h1 em treatment (Georgia italic, red) is the chapter-page signature. + +import Eyebrow from '../primitives/Eyebrow.astro'; + +interface Props { + /** Short uppercase label, same treatment as Eyebrow. Defaults to red, + * matching chapters.css `.eyebrow`. */ + eyebrow: string; + /** Colour tone for the eyebrow. */ + tone?: 'accent' | 'red'; +} + +const { eyebrow, tone = 'red' } = Astro.props; +--- + +
+ +

+
+ +
+ + diff --git a/src/components/blocks/ComparisonTable.astro b/src/components/blocks/ComparisonTable.astro new file mode 100644 index 0000000..a3eda3c --- /dev/null +++ b/src/components/blocks/ComparisonTable.astro @@ -0,0 +1,81 @@ +--- +// ComparisonTable — horizontal-scroll wrapper for wide comparison tables. +// Used by /models/ and /rules/ pages where tables become unreadable on a +// phone without horizontal scroll. +// +// The pattern from chapters.css and full-guide/audit.css: +//
+// ...
+//
+// with `.table-wrap { overflow-x: auto }`. +// +// Callers pass the table via the default slot; the wrapper class adds the +// scroll behaviour and hairline border so the wrapper itself looks +// intentional, not like an overflow leak. + +interface Props { + /** Minimum width on the inner table. Forces horizontal scroll below this + * width rather than squashing columns into illegibility. */ + minWidth?: string; +} + +const { minWidth = '640px' } = Astro.props; +--- + +
+
+ +
+
+ + diff --git a/src/components/blocks/SectionGrid.astro b/src/components/blocks/SectionGrid.astro new file mode 100644 index 0000000..e670172 --- /dev/null +++ b/src/components/blocks/SectionGrid.astro @@ -0,0 +1,82 @@ +--- +// SectionGrid — the gap:1px hairline-separated card grid. Used by /models/' +// LOW/MEDIUM/HIGH cards and /agents/' FRAME/HAND OFF/PROVE cards. +// +// The separator technique is deliberate house style: `gap:1px` over a +// coloured parent background fakes borders without `border` shorthand. The +// child fills its background to cover the parent's 1px seam. +// +// Each direct child is expected to be a card — the markup pattern from +// chapters.css: +//
LABEL

Title

Body

+// The component styles `> .card` and its internals so callers don't repeat. + +interface Props { + /** Number of columns at the widest breakpoint. */ + columns?: number; +} + +const { columns = 3 } = Astro.props; +--- + +
+ +
+ + diff --git a/src/components/blocks/SiteFooter.astro b/src/components/blocks/SiteFooter.astro new file mode 100644 index 0000000..4c258b2 --- /dev/null +++ b/src/components/blocks/SiteFooter.astro @@ -0,0 +1,63 @@ +--- +// SiteFooter — the bottom of every chapter page. Holds the inline-nav links +// (chapter-to-chapter or to the field guide) plus the small footer text. +// +// The chapter pages use a "pill" link style: 1px ink border, ink text, +// inverts on hover. Padding and gap are inherited from chapters.css +// `.links`. The block element is the lower bound of the page main — no +// margin/padding magic, just the rule above the first link. +// +// Footer text (the muted paragraph) goes into the default slot. + +interface Props { + /** Optional accessible label for the inline-nav region. */ + navLabel?: string; +} + +const { navLabel = 'Chapter navigation' } = Astro.props; +--- + +
+ +
+ +
+
+ + diff --git a/src/components/blocks/TopBar.astro b/src/components/blocks/TopBar.astro new file mode 100644 index 0000000..70372c3 --- /dev/null +++ b/src/components/blocks/TopBar.astro @@ -0,0 +1,64 @@ +--- +// TopBar — the three-cell topbar shared by /models/, /agents/, /skills/, +// /summary/. Each slot is independent; the layout is a flex row with +// `justify-content: space-between`. +// +// The chapter pages use: +// ← ROUTE MAP | 01 / MODELS | field guide ↗ +// +// The brief's watch-for: callers that mark a link as the current page +// should set `aria-current="page"` on that link. The component does not +// impose it — slot content is preserved verbatim. This is the only +// indication of location for assistive tech on these pages, so losing +// it would be a real regression. + +interface Props { + /** Optional HTML id for the topbar. */ + id?: string; +} + +const { id } = Astro.props; +--- + +
+
+
+
+
+ + diff --git a/src/layouts/ChapterLayout.astro b/src/layouts/ChapterLayout.astro new file mode 100644 index 0000000..03c72b9 --- /dev/null +++ b/src/layouts/ChapterLayout.astro @@ -0,0 +1,41 @@ +--- +// ChapterLayout — the shared chapter-page shell. TopBar at the top, a +// `
` slot for page content, SiteFooter at the bottom. +// +// Pages include this instead of BaseLayout for the four chapter routes +// (/models/, /agents/, /skills/, /summary/). /rules/ uses a different shell +// (task 14). /full-guide/ has its own. +// +// The chapters.css stylesheet is the shared layer. It carries the +// chapter-palette tokens, the hero/grid/practice legacy classes, and the +// responsive contract that audit-ui.mjs asserts. + +import BaseLayout from './BaseLayout.astro'; +import TopBar from '../components/blocks/TopBar.astro'; +import SiteFooter from '../components/blocks/SiteFooter.astro'; +import chaptersStylesheet from '../../chapters.css?url'; + +interface Props { + title: string; + description: string; + lang?: string; +} + +const { title, description, lang = 'en' } = Astro.props; +--- + + + + + + + + +
+ +
+ + + + + diff --git a/src/pages/summary.astro b/src/pages/summary.astro index e15be22..02615c6 100644 --- a/src/pages/summary.astro +++ b/src/pages/summary.astro @@ -1,63 +1,59 @@ --- -import BaseLayout from '../layouts/BaseLayout.astro'; -import chaptersStylesheet from '../../chapters.css?url'; +import ChapterLayout from '../layouts/ChapterLayout.astro'; +import ChapterHero from '../components/blocks/ChapterHero.astro'; +import SectionGrid from '../components/blocks/SectionGrid.astro'; const base = import.meta.env.BASE_URL; const introduction = 'This guide turns AI work into a shape: frame the problem, choose the model and agent, isolate changes, teach repeatable decisions, and verify the result.'; --- - - -
-
- ← AI FOR DUMMIES - 00 / ROUTE MAP - review desk ↗ -
-
-

Start here

-

Ship the
system.

-

{introduction}

-
-
- - - - -
- 05

Practice

Compare prompts and skill-enabled runs.

Open lab → -
-
- 06

Review desk

Browse original files and improved drafts.

Open desk → -
-
- -
- Each chapter stands alone; the order follows a real task becoming a reliable change. -
-
- + + ← AI FOR DUMMIES + 00 / ROUTE MAP + review desk ↗ + + + Ship the
system. +

{introduction}

+ + + + + + + +
+ 05

Practice

Compare prompts and skill-enabled runs.

Open lab → +
+
+ 06

Review desk

Browse original files and improved drafts.

Open desk → +
+ + + Full field guide + Operations guide + + Each chapter stands alone; the order follows a real task becoming a reliable change. + +