acuvo-code 0.2.0

package/skills/typography.md

@@ -0,0 +1,135 @@
+---
+name: typography
+description: Type scale, pairing, measure and rhythm — the largest single lever on whether a page reads as designed
+when: Any page with words on it, which is every page. Read before choosing fonts or sizes.
+---
+
+# Typography
+
+Most generated pages fail here before they fail anywhere else. The colours are
+fine, the layout is fine, and it still looks like a template — because every
+heading is bold, every size is a round number, and the body text runs the full
+width of a monitor.
+
+## ⭐ The four decisions, in the order they matter
+
+1. **Measure** — how wide a line of body text is.
+2. **Scale** — the ratio between sizes.
+3. **Weight contrast** — how far apart the heaviest and lightest are.
+4. **Which fonts** — genuinely last. A well-set page in one system font beats a
+   badly-set page in two beautiful ones.
+
+## 1. Measure: 60–75 characters, always
+
+```css
+.prose { max-width: 68ch; }
+```
+
+`ch` is the width of a "0", so `68ch` is roughly 68 characters *at that font
+size* — it stays correct when the size changes, which a `max-width: 720px` does
+not.
+
+⚠️ **This is the most common single defect in generated pages.** Body text
+spanning 1400px is unreadable, and it is unreadable in a way people feel
+without being able to name. Headings may run wider (they are short); body,
+never.
+
+## 2. A scale, not arbitrary sizes
+
+Pick a ratio and multiply. Do not choose sizes by feel — that is what produces
+`18px` next to `19px`, a difference nobody can see doing work nobody notices.
+
+| use | ratio 1.25 (calm, editorial) | ratio 1.333 (louder, marketing) |
+|---|---|---|
+| small print | 0.8rem | 0.75rem |
+| body | 1rem | 1rem |
+| lead / large body | 1.25rem | 1.333rem |
+| h3 | 1.563rem | 1.777rem |
+| h2 | 1.953rem | 2.369rem |
+| h1 | 2.441rem | 3.157rem |
+
+The vendored system already ships a scale — **use those tokens rather than
+re-deriving one.** Two scales in one page is worse than either alone.
+
+⭐ **Hero headings break the scale on purpose.** A landing page hero often wants
+`clamp(2.5rem, 6vw, 5rem)` — bigger than the scale's top step. That is a
+deliberate exception at one place, not permission to freestyle everywhere.
+
+## 3. Weight and contrast
+
+- Body **400**. Headings **600–700**. That is the whole system for most pages.
+- ⚠️ **Do not bold everything.** When four things are bold, nothing is
+  emphasised. Emphasis is a ratio, not a property.
+- **Contrast size before you contrast weight.** A 2.4rem/600 heading over
+  1rem/400 body has far more presence than 1.2rem/800 over 1rem/700.
+- Below 500, avoid pairing a light weight with small sizes — it fails contrast
+  checks and looks broken on Windows.
+
+## 4. Choosing fonts
+
+Google Fonts is the **only** external font host that loads under our CSP
+(see `acuvo-design-system`). Anything else fails silently and the page falls
+back to Times New Roman, which is the single most recognisable "the AI failed"
+signal there is.
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">
+```
+
+⚠️ **Load only the weights used.** Every extra weight is a real download. Three
+is usually right; five is almost never.
+
+**Pairings that reliably work:**
+
+| feel | display / headings | body |
+|---|---|---|
+| modern product, SaaS | Inter 600–700 | Inter 400 |
+| editorial, premium | Fraunces / Playfair Display | Inter / Source Sans 3 |
+| technical, developer | Space Grotesk | IBM Plex Sans |
+| warm, human, local trade | Bricolage Grotesque | Karla |
+| luxury, restrained | Cormorant Garamond | Jost |
+
+⭐ **One family, two weights, is a legitimate and often superior answer.** Inter
+600 over Inter 400 with a real size scale looks intentional. Two display faces
+fighting each other looks like a template.
+
+⚠️ Never pair two serifs, or two geometric sans. If they are similar enough to
+be confused, the pairing reads as a mistake rather than a choice.
+
+## 5. Rhythm — the part that gets skipped
+
+- **Line height scales inversely with size.** Body `1.5–1.7`. Headings
+  `1.05–1.25`. A 3rem heading at `line-height: 1.5` has a canyon through it.
+- **Letter-spacing likewise.** Large display type wants slightly negative
+  (`-0.02em` to `-0.03em`); small caps and overlines want positive
+  (`0.08em`–`0.12em`). Body wants none.
+- **Space belongs above a heading, not below it.** A heading should sit close to
+  the text it introduces and far from the text it follows — that is what makes
+  a page scannable. `margin-block: 2.5em 0.6em`.
+
+```css
+h2 { font-size: 1.953rem; line-height: 1.15; letter-spacing: -0.02em; margin-block: 2.5em 0.6em; }
+p  { font-size: 1rem; line-height: 1.65; max-width: 68ch; }
+.overline { font-size: 0.75rem; letter-spacing: 0.12em; text-transform: uppercase; }
+```
+
+## 6. Details that separate careful from careless
+
+- Use real punctuation: `"` `"` `'` `—` `…`, not `"` and `--`.
+- `text-wrap: balance` on headings, `text-wrap: pretty` on paragraphs. Two
+  lines, no orphans, free.
+- Numbers in tables: `font-variant-numeric: tabular-nums`, or columns jitter.
+- ⚠️ Never centre a paragraph longer than two lines. Centred ragged-left text
+  is hard to read because the eye loses the line start.
+- `font-size` on `<html>` stays at the browser default. Setting `62.5%` or a px
+  value overrides someone's accessibility setting.
+
+## Before calling it done
+
+- Body text is capped near `68ch`. Nothing runs the full viewport.
+- Every size comes from the scale (one deliberate hero exception allowed).
+- At most three weights are loaded, and all of them are used.
+- Headings have tighter line-height than body, and more space above than below.
+- The page still reads correctly at 320px and at 200% browser zoom.

package/skills/verify-your-own-work.md

@@ -0,0 +1,62 @@
+---
+name: verify-your-own-work
+description: How to prove a change works — mutation testing, and why "it builds" proves nothing
+when: After writing code, adding a test, or before reporting something as done
+---
+
+# Proving it works
+
+## "It builds" is not evidence
+
+A clean build proves the code parses. It does not prove the feature is reachable,
+that the test would catch a regression, or that a human can get to it.
+
+The three claims, from weakest to strongest:
+1. *It compiles.* — almost worthless.
+2. *The tests pass.* — worth something, IF the tests can fail.
+3. *I ran the real path end to end and observed the result.* — this is evidence.
+
+## ⚠️⚠️ Mutation-test every guard you write
+
+A test that cannot fail is worse than no test: it costs the same to maintain and
+it actively certifies broken code.
+
+**After writing a check, break the thing it guards and confirm the test goes
+RED. Then restore and confirm GREEN.**
+
+```
+1. write the guard         → green
+2. break the code it guards → MUST go red   ← if it stays green, the test is fake
+3. restore                  → green again
+```
+
+Real examples of tests that passed while guarding nothing:
+- a regex missing anchors, so `abc<valid>def` passed
+- `toContain('<Widget')`, satisfied by `<WidgetX` — the component was renamed and
+  the test never noticed
+- a check whose verdict depended on the OS path separator: it passed on CI and
+  failed only on the developer's machine
+
+## Only the end-to-end run proves reach
+
+The most expensive recurring defect is **built but unreachable**: the function
+exists, the tests pass, and nothing can actually invoke it. A registered tool
+that never fires, a page with no link to it, an export with no importer.
+
+So before "done": run the real path. Open the page. Call the endpoint. Check the
+row landed in the database.
+
+## Say what you did not check
+
+If you tested three of five cases, say which two you did not. An honest partial
+result is useful; an implied "all good" that turns out to be a third is not.
+
+## When a check fails, doubt the check first
+
+A failing test means one of two things and they are not equally likely:
+1. the code is broken
+2. **the check is wrong**
+
+Read the failure literally and verify each link in its chain before "fixing" the
+code. Changing correct code to satisfy a broken test is a real and common way to
+make software worse while feeling productive.

package/skills/web-app-quality.md

@@ -0,0 +1,62 @@
+---
+name: web-app-quality
+description: What makes a generated app actually work — state, persistence, accessibility, edge cases
+when: Building an interactive app, tool or anything with user input
+---
+
+# Making the app actually work
+
+## Persist by default
+
+An app that forgets everything on refresh feels broken even when it is
+functionally correct. Persist user state to `localStorage` under one namespaced
+key, and read it back on load.
+
+```js
+const KEY = 'myapp:v1';
+const load = () => { try { return JSON.parse(localStorage.getItem(KEY)) ?? null; } catch { return null; } };
+const save = (s) => { try { localStorage.setItem(KEY, JSON.stringify(s)); } catch {} };
+```
+
+⚠️ Always `try/catch`. `localStorage` throws in private mode and when full, and
+an uncaught throw during load blanks the whole app.
+
+⚠️ Version the key (`:v1`). Shipping a new shape against an old stored object is
+how an app crashes only for returning users — the ones who liked it.
+
+## Input, and the cases that break it
+
+Handle every one of these before saying done:
+
+- **Empty submit** — do nothing, or say what is required. Never add a blank row.
+- **Whitespace only** — `.trim()` before validating.
+- **Duplicate** — decide: reject, merge, or allow. Do not crash.
+- **Very long input** — clamp or wrap. One 500-character word must not break layout.
+- **Numbers** — reject `NaN`. `Number('')` is `0`, which silently accepts empty.
+- **Zero and negative** — a quantity of 0 is different from no quantity.
+
+## Keyboard and accessibility
+
+- Every interactive thing is a `<button>` or `<a>`, never a `<div onclick>`.
+- `Enter` submits the form the user is in; `Escape` closes what just opened.
+- Visible focus rings. Do not `outline: none` without a replacement.
+- Labels tied to inputs (`<label for>`), and `aria-label` on icon-only buttons.
+- Colour is never the only signal — pair it with text or an icon.
+
+## Destructive actions
+
+Deleting needs either a confirm or an undo. Undo is better: it keeps the app
+fast and forgiving. A confirm dialog on every delete trains people to click
+through it.
+
+## Numbers and dates
+
+- Format money with `Intl.NumberFormat`, never `toFixed(2)` plus a `$`.
+- Dates with `Intl.DateTimeFormat` — never build a date string by hand.
+- Show relative time ("2 minutes ago") for recent things, absolute for old.
+
+## Before calling it done
+
+Run through it as a user: add something, refresh, edit it, delete it, undo,
+submit an empty form, paste a wall of text, use only the keyboard. Every one of
+those is a bug people actually hit.

package/skills/working-in-the-background.md

@@ -0,0 +1,64 @@
+---
+name: working-in-the-background
+description: Servers, watchers and long builds without blocking — start_process and wait_for_output
+when: Whenever a command does not exit on its own — a server, a watcher, a long build, anything you need running WHILE you work
+---
+
+# Working In The Background
+
+## ⚠️⚠️ `run_command` is for commands that FINISH
+
+A dev server never finishes. Starting one with `run_command` blocks until the
+timeout and then reports a failure for something that was working perfectly.
+
+**Use `start_process` for anything that keeps running:** a dev server, a
+watcher, a build in watch mode, a queue worker.
+
+## ⭐⭐ The sequence that works every time
+
+1. **`start_process`** — launch it. You get an `id` back.
+2. **`wait_for_output`** — block until the line that means READY appears
+   (`Ready in`, `Listening on`, `compiled successfully`).
+3. **`check_process`** — read what it printed, confirm it is still alive, and —
+   if it announced a port — confirm it is **actually answering HTTP**.
+4. Do your work.
+5. **`stop_process`** — stops it and everything it started, returns final output.
+
+⭐ **`wait_for_output` instead of guessing.** Sleeping "about thirty seconds"
+is wrong in both directions: too short and you test a server that has not
+started, too long and you waste half a minute on every run. Wait for the line.
+
+## ⚠️⚠️ Waiting for ONLY the success line will hang on a crash
+
+If the process dies during startup, the ready line never comes and you sit
+there until the timeout learning nothing.
+
+⭐ **Wait for a pattern that also matches failure** — `Ready in`, but also
+`Error`, `EADDRINUSE`, `Cannot find module`. Then read the output and find out
+which happened. **Silence is not success**, and a wait that can only end one way
+turns a five-second crash into a two-minute mystery.
+
+## ⭐ A port answering is the only proof it started
+
+`check_process` tells you whether the port actually responds. Use that, not the
+log line — a framework can print "Ready" and still fail the first request. If
+you are about to test a page, confirm the port answers first, or you will spend
+the next three steps debugging your test instead of the app.
+
+## ⚠️ Long logs: `summarize_log`, not the whole thing
+
+A watch-mode build produces thousands of lines. `summarize_log` folds it to the
+errors and warnings first, then the tail, then **an exact count of what was left
+out** — so you know whether you are seeing everything.
+
+Reading a 4,000-line log in full costs a large part of your context and usually
+tells you one thing you could have had from the summary.
+
+## ⭐ Clean up
+
+**Stop what you started.** A dev server left running holds its port, and the
+next run fails with `EADDRINUSE` — which reads like a broken app and is not.
+If a port is busy, check whether YOU left something on it before concluding
+anything about the code.
+
+Related skills: `debugging`, `verify-your-own-work`.