@pikku/skills 0.12.32 → 0.12.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.32",
+  "version": "0.12.33",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-build/SKILL.md

@@ -33,9 +33,10 @@ plus more effort" — it is App plus a deliberate surface checklist, so read the
 base first and follow it in full rather than blending the two into one plan.
 
 The supporting references belong to whichever mode sends you to them:
-`references/multi-app.md` (a second frontend), `references/design.md` (committing
-to a design direction and judging whether the screens realise it — read before
-the first screen is built, not after the last), `references/theming.md`
+`references/multi-app.md` (a second frontend), `references/design.md` (offering
+to mock the screens first, committing to a design direction, and judging whether
+the screens realise it — read before the first screen is built, not after the
+last), `references/theming.md`
 (authoring the theme),
 `references/ship.md` (deploying, and the Fabric-readiness contract).
 

package/skills/pikku-build/references/app.md

@@ -61,6 +61,12 @@ in one message. Then stop; do not interview the user.
   Neutral (fine for an internal tool, but say so out loud); a direction in words;
   a reference (brand guide, screenshots, a site whose register they want); or
   their own design agent/prompt, whose output you take as the direction.
+- **Do they want to see the screens before you build them?** Offer it here, in
+  this same round, as a question and not a gate: one HTML page mocking the main
+  screens, a few minutes, far cheaper to change than built screens. If they say
+  yes, `references/design.md` owns what to make and what it then binds — the
+  approved page becomes source of truth for the screens, and the theme is written
+  before it so what they approve is what ships. If they say no, build.
 - **What language should the app speak, and what language does the team work
   in?** Two answers, not one — see §1a, which is where they go. Ask only if the
   request is not obviously English; a brief written in English about an English
@@ -332,6 +338,10 @@ What a milestone is:
   persona. If you cannot write the gherkin, you cannot build it yet — that is a
   `questions/` note, not a milestone.
 
+If §1's screen mock was made and approved, the milestones are read off it: every
+screen on that page belongs to some milestone, and a screen no milestone builds
+is a hole in this plan. Say which milestone covers which screen.
+
 How to order them:
 
 1. **The spine first.** The one object everything else hangs off, and the screen
@@ -415,16 +425,26 @@ over, and an uncovered function is a half-milestone whether or not the note says
 5. **UI.** Pages in `<app>/src/pages/`, one route file each in `<app>/src/routes/`,
    calling functions through the generated `usePikkuQuery` / `usePikkuMutation`
    hooks from `@project/functions-sdk/pikku/api.gen`. One component per `.tsx`
-   file. Compose the kit from `@/components/<Name>` rather than hand-rolling.
-   Register the screen in `useNavItems()` — that one file feeds both the desktop
-   sidebar and the phone navigation.
+   file. Compose the kit from `@/components/<Name>` rather than hand-rolling
+   controls — and **add to that kit**: the component that draws the thing this
+   product is actually about, and the furniture you would otherwise copy-paste
+   into eight pages. The kit is where you start, not where you stop; an app whose
+   every screen is `Card` + `Stack` + `Text` composed the inventory rather than a
+   design. Register the screen in `useNavItems()` — that one file feeds both the
+   desktop sidebar and the phone navigation.
    **Read `references/design.md` before you write the first screen.** You commit
    to a design direction there and are then accountable to it — it hands you no
-   layouts, because the design is yours to make. Screenshot each screen at 390
-   and 1440 with the seed in place at the END of every milestone, and look at the
-   images — not once at §8, where the only affordable fix is a repaint of eight
-   screens.
-6. **Scenario** (§7), then `status: built`.
+   layouts, because the design is yours to make. What you build here is then
+   judged at step 7, at the end of this milestone rather than once at §8, where
+   the only affordable fix is a repaint of eight screens.
+6. **Scenario** (§7).
+7. **Look at it.** Screenshot every screen this milestone touched, at both
+   widths, with the seed in place, and look at the images. This is a gate, the
+   same as the scenario: a milestone whose screens nobody has seen is not built,
+   it is unproven at the one layer scenarios cannot reach. `references/design.md`
+   carries how to take the shot when no browser tool is wired up, and what to
+   look for. Then `status: built`, and say in the note what you looked at and
+   what it made you change.
 
 Rules that are not optional:
 

package/skills/pikku-build/references/design.md

@@ -30,6 +30,117 @@ and so is the commitment.
 Be ambitious with it. A direction that could describe any SaaS app has not been
 chosen — it has been defaulted to in words instead of in components.
 
+### The looks you will default to
+
+Being ambitious is easier against a list of specific things to not be. Generated
+interfaces cluster hard, and these are the attractors — not because any is ugly,
+but because arriving at one *by default* means no choice was made:
+
+- **Stock Mantine.** The strongest pull, and the hardest to see: a component
+  library's untouched defaults do not look broken, they look finished. Blue
+  accent, `#dee2e6` borders, `md` radius on everything, `Card` + `Stack` + `Text`
+  down every page. An app can be entirely this and never trip a critique, because
+  nothing on any screen is *wrong*.
+- Warm cream ground with a serif display face and a terracotta accent.
+- Near-black with one acid-green or vermilion pop.
+- A purple-to-blue gradient header on white.
+- Inter, or Space Grotesk, as the "safe" typeface.
+- Emoji as section markers; everything centre-aligned; one radius and one shadow
+  stamped on every block, which flattens hierarchy instead of creating it.
+
+If the user asks for one of these, build it — their words win. What is not
+allowed is landing on one because it was nearest to hand.
+
+## Offer to draw the screens before you build them
+
+Before the first milestone, **ask** whether they want to see the screens first.
+One question, in §1's round, not a gate of its own:
+
+> Want me to mock the main screens as a page you can look at before I build
+> anything? It takes a few minutes and it is much cheaper to change a picture
+> than a built screen.
+
+If they decline, build; the direction in words is enough to be accountable to.
+If they accept, this is the cheapest decision in the project — a picture of eight
+screens costs a fraction of eight built screens, and it is the only point where
+"that is not what I meant" is free.
+
+**Author the theme first, then draw the mock from it.** This order is the whole
+point. A beautiful page in hand-rolled CSS sets a bar Mantine then misses, and
+what the user approved is not what ships — they signed off on a picture and
+received an approximation of it. So write `themes/<name>.json` first
+(`references/theming.md`), and let the mock take its every value from that file:
+the palette, `structure.radius`, the spacing scale, the fonts, the component
+`defaultProps`. Approving the mock then approves the theme, and the built screens
+inherit it rather than chase it.
+
+**The mock has two halves, and only one of them is Mantine's.** This is the same
+split the built screen lives under, applied a step earlier so the two agree by
+construction. The PAGE — the shell, the regions, the columns, the rhythm, the
+material behind the content, what overlaps what — is plain HTML and your own
+CSS, arranged however the layout decision demands; that half is free, and it is
+where the design actually happens. The COMPONENTS — anything a person would
+point at and call a control, and that the app will adopt as itself: buttons,
+inputs, selects, tables, badges, menus, modals — are drawn as *Mantine's*, at the
+metrics Mantine actually uses: its control heights, its input shapes, its table
+and menu behaviour. The test is the one the build will apply too: is this thing
+the SHAPE OF THE PAGE, or a COMPONENT someone would point at?
+
+Getting that second half wrong is what makes a mock a lie. A control the mock
+invents is a promise the app cannot keep, and a beautiful hand-rolled input sets
+a bar the real one misses on screen one. If the mock wants something Mantine
+does not do, that is a real finding, and finding it here is the point: change the
+theme so it does, or change the mock, and say which.
+
+**What to make.** One self-contained HTML page holding every screen the app
+needs — not a prototype, not a click-through. Static markup, real content from
+their domain (never lorem), the empty and error states beside the happy path,
+laid out so the whole app is legible by scrolling. Its CSS is custom properties
+on `:root` carrying the theme JSON's values, so a change to either is a change
+to one number in both. Mantine itself will not load here — it is a React library
+and a page like this has no bundler, and on hosts that sandbox the page (a Claude
+Artifact) external stylesheets are blocked outright — so do not try; the mock
+reproduces the theme's values by hand, which is why they have to be written down
+first. Whatever your host offers for showing a page is how you show it: an
+Artifact, a file they open, a preview server. The page is the deliverable; how it
+gets in front of them is not this file's business.
+
+Write it to `knowledge/decisions/design/screens.html` and treat it as **source of
+truth for the screens** once they approve it. That has consequences worth
+stating:
+
+- The milestones are read off it. A screen in the mock that no milestone builds
+  is a gap in the plan, not a spare drawing.
+- A screen the build turns out to need that the mock does not have means the
+  mock was wrong. Update it, and say you did. Do not let the app and the mock
+  drift and then quietly prefer the app.
+- The knowledge graph still owns the domain — objects, roles, rules. The mock
+  owns what the screens look like. When they disagree about a *fact*, knowledge
+  wins; when they disagree about a *layout*, the mock wins.
+
+**Building it is then a transcription, not a translation.** Because the theme
+already exists and the mock was drawn from it, the screen is Mantine components
+arranged the way the mock arranges them — the look arrives with the theme. Two
+rules keep it that way:
+
+- **Layout is yours to write; components are Mantine's.** The page shape — the
+  regions, the columns, the rhythm, what sits beside what — is ordinary markup
+  and your own CSS. Anything a person would point at and call a control comes
+  from Mantine: buttons, inputs, selects, tables, badges, menus. Those carry
+  focus rings, keyboard behaviour and i18n, and hand-rolling one throws all of
+  it away.
+- **A gap goes back to the theme, never into a component override.** If a screen
+  does not match the mock, the fix is a value in `themes/<name>.json`. A stack of
+  one-off `className`s and `!important` fighting Mantine's defaults looks like
+  progress on screen one and is unmaintainable by screen five, and the screens
+  drift apart because nothing central holds them together.
+
+**Checking the built screen against the mock** is a structural comparison, not a
+pixel one: the same regions in the same order, the same hierarchy, the same
+states present, the same tokens used. Do not chase pixel equality — Mantine's
+components have their own metrics and the mock was drawn without them. A built
+screen that reads as the same screen has passed.
+
 ## One screen, designed properly, before the rest exist
 
 Design the first real screen as if it were the only one, and take it further than
@@ -48,6 +159,31 @@ the thing that made it is always yes. Use evidence.
 - **Screenshot every screen and look at the image**, at ~390px and at ~1440px.
   Judging your own UI from source is guessing, and the failures that matter —
   proportion, hierarchy, a wall of identical boxes — are invisible in JSX.
+  **Sort out how you will take that screenshot before you need it**, because an
+  instruction with no working mechanism behind it is one that gets skipped, and
+  this is the one that gets skipped. If a browser-driving tool is wired up, use
+  it. If it is not — or it fails to connect, which happens — the fallback is
+  short enough to write once and keep:
+
+  ```sh
+  CHROME=$(command -v google-chrome || command -v chromium || \
+    command -v chromium-browser || \
+    echo "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")
+  "$CHROME" --headless=new --no-sandbox \
+    --remote-debugging-port=9333 --user-data-dir=/tmp/gc-shots &
+  ```
+
+  Resolve the binary rather than hardcoding the macOS path: the same gate has to
+  work on a Linux box and in CI, and a fallback that only starts on one host is
+  a gate that gets skipped everywhere else. If the host already exposes a CDP
+  endpoint, point the script at that instead and start nothing.
+
+  Then drive it over CDP from a script: `Page.navigate`,
+  `Emulation.setDeviceMetricsOverride` for the two widths,
+  `Page.captureScreenshot`, write the PNG, and open it. Sign in the way a person
+  does — click the dev actor switcher on the login page — rather than reaching
+  for the secret the client uses; the UI path is shorter and it also proves the
+  login screen works. Keep the script; you will run it at every milestone.
 - **Run `impeccable`** (`npx impeccable install`, Node 22.18+) and feed it the
   screenshots. It is external, it does not flatter, and it scores execution
   against interaction heuristics. But it audits how well you executed the design
@@ -69,6 +205,77 @@ questions are fixed:
    had?
 6. Would you show it to the user without apologising for it?
 
+## The kit is a floor, not a ceiling
+
+The scaffold hands you a component kit, and the build instructions tell you to
+compose from it rather than hand-roll. Both are right, and together they have a
+failure mode worth naming: an app whose every screen is `Card` + `Stack` + `Text`
+because those were the pieces in the box. That is not a composed design, it is an
+inventory, and it produces the wall of identical boxes further down this file.
+
+**Composing from the kit means using its primitives, not being limited to its
+list.** A product has objects of its own, and the ones that carry its meaning are
+the ones no generic kit ships:
+
+- the thing the product is *about*, rendered as itself — a funding meter, a
+  streak, a seat map, a run's status over time. If a decision note says the
+  progress toward a goal is the primary object, then a component that draws that
+  progress has to exist, or the note is describing an app you did not build.
+- the repeated furniture that is currently copy-pasted — the page header, the
+  section label, the empty state, the recessed panel a form sits in. Eight inline
+  copies of a heading block will not agree with each other; they will disagree by
+  a few pixels each, and the screens will read as unrelated for reasons nobody
+  can point at.
+
+Both kinds are ordinary components built out of kit primitives and theme values.
+Adding them is not hand-rolling, and they are the difference between an app that
+uses a design system and an app that looks like one.
+
+The tell that you skipped this: your `components/` directory maps one-to-one onto
+your data model and contains nothing that names a *quality* of the product.
+
+## Design is a gate on the milestone, not a phase at the end
+
+The loop that actually runs is plan, build, prove, close. Design advice that
+lives outside that loop does not run — it gets read, agreed with, and skipped,
+because nothing blocks on it. Milestones close on green scenarios, and scenarios
+say nothing about how anything looks.
+
+So put it in the loop. **A milestone is not built until its screens have been
+looked at**, in the same sense that it is not built until its scenario passes:
+
+- Screenshot every screen the milestone touched, at both widths, with the seed
+  in place.
+- Look at the images. Not the JSX.
+- Fix what they show, in this milestone, while it is one screen and not eight.
+- Say in the milestone note what you looked at and what you changed.
+
+A milestone closed without that is closed on a claim, not on evidence. The cost
+of being honest about it now is minutes; the cost at §8 is a repaint of the whole
+app, and by then the wrong register has been inherited by every screen so the
+repaint is a rewrite.
+
+### The seed is part of the gate
+
+A screenshot is only evidence if the screen has something on it. Before the gate
+runs, the dev seed must populate what each screen *is for* — not one row, and not
+an empty state.
+
+This is a real and quiet failure: a list app whose seed has no list, a countdown
+whose seed has no dates, judged for weeks against its own empty state while the
+screen it was built for was never once looked at. The empty state is worth
+designing and is not what the milestone is about.
+
+Seed enough to be judged against: several rows, not three identical ones, and a
+deliberate spread of the cases the screen has to hold — a long title that wraps,
+a missing optional field, a picture and no picture, one item in each state the
+screen can show. Anything derived from *today* — a countdown, "3 days ago", an
+expiry — is seeded as an interval from `now`, never as a fixed date: fixed dates
+are correct on the afternoon they are written and meaningless a month later.
+
+Data left over from a scenario run is not a seed. If the screens are full of
+`Filter coffee grinder mttqdvsx`, you are designing against test debris.
+
 ## Facts, not taste
 
 These are not design opinions and are not open to a different answer.
@@ -125,4 +332,15 @@ first one.
 - Every row carries the same buttons, and the buttons outweigh the content.
 - The palette's meaningful colours are also used decoratively, so they have
   stopped meaning anything.
+- A decision note describes something the screens do not do — the note says
+  progress is the primary object and no screen draws progress, or it says warm
+  and not clinical and the error page is still template blue.
+- The theme JSON is rich and the screens are bare. Tokens are the cheapest half
+  of design and the easiest to mistake for the whole of it: a considered palette
+  and a display font applied to a default layout is a well-dressed default.
+- Every border, divider and disabled control is a cool blue-grey while the
+  accent is not — the surest sign the neutrals were inherited rather than
+  chosen. See `references/theming.md`.
 - It looks like the last app you built.
+- It looks like Mantine. Not *built with* Mantine, which it is and should be —
+  but indistinguishable from a component gallery with the brand hue swapped in.

package/skills/pikku-build/references/theming.md

@@ -53,6 +53,128 @@ Then **write the direction into `knowledge/decisions/design/`** — the words th
 user gave you, what you chose, and what it rules out. The JSON records what the
 theme is; only the note records why.
 
+## The colours the theme has no field for
+
+`brand` is the product's accent. It is not the only colour a screen needs, and
+the missing ones are why "don't hardcode colours per component" gets broken by
+the same agent that wrote it down.
+
+A screen has to say *covered* and *still open*, *fine* and *needs attention* —
+and those are not the accent. Using the accent for them is worse than a stray
+hex: the brand colour stops meaning "this product" and starts meaning "good", so
+it means nothing. But there is no `brand.covered` field, so the value lands
+inline as `#3f7d5c`, once per component, slightly different each time.
+
+Give them a home. A small stylesheet of custom properties, imported once beside
+the Mantine styles, is enough:
+
+```css
+:root:root:root {
+  --app-covered: #3f7d5c;  --app-covered-bg: #e6f1ea;
+  --app-open:    #a8701a;  --app-open-bg:    #fbeedb;
+  --app-sunk:    #fdf7f4;   /* a recessed surface, for forms and asides */
+  --app-hairline: #ecdfd9;  /* NOT var(--mantine-color-gray-2) — see below */
+}
+:root:root[data-mantine-color-scheme='dark'] {
+  --app-covered: #7fc09a;  --app-covered-bg: #1e2f26;
+  --app-open:    #e0ab5c;  --app-open-bg:    #33271a;
+  --app-sunk:    #241b18;
+  --app-hairline: #392b26;
+}
+```
+
+Those values are one app's warm direction, not a palette to copy — derive your
+own from yours.
+
+## Choose the neutrals; do not inherit them
+
+The two details in that snippet that look like typos are the two things most
+likely to make your app look like every other app.
+
+**The hairline is a literal, not `var(--mantine-color-gray-2)`.** Mantine's grey
+ramp is blue-biased — `#f8f9fa`, `#dee2e6`, `#868e96` are all cool — and it is
+what draws card borders, dividers, the shell's edges and every disabled control.
+The theme JSON has `brand` and `structure` and **no neutral field at all**, so
+unless you choose otherwise, every app built from this skill runs its accent on
+somebody else's greys.
+
+If the accent is not itself blue, that mismatch lands on every screen at once:
+warm content ruled off in cold lines, off everywhere and wrong nowhere in
+particular, which is the hardest kind of wrong to find. It survives a careful
+critique because no single screen is broken.
+
+So bias the whole ramp toward the accent — not just the tokens with obvious
+names. Keep Mantine's lightness steps so contrast behaviour and every component
+that picks a step by number are unchanged; move only the hue:
+
+```css
+/* The ramps: hue only. Mantine picks a step by number in either scheme, so
+   these are scheme-independent and belong in the unscoped block. */
+:root:root:root {
+  --mantine-color-gray-0: #faf7f5;  --mantine-color-gray-5: #b8a49d;
+  --mantine-color-gray-1: #f5efec;  --mantine-color-gray-6: #93807a;
+  --mantine-color-gray-2: #efe6e2;  --mantine-color-gray-7: #574a45;
+  --mantine-color-gray-3: #e6dad5;  --mantine-color-gray-8: #3d332f;
+  --mantine-color-gray-4: #d8c8c2;  --mantine-color-gray-9: #2a1f1b;
+  --mantine-color-dark-0: #f3e9e4;  --mantine-color-dark-5: #4a3a34;
+  --mantine-color-dark-1: #cdbdb6;  --mantine-color-dark-6: #392b26;
+  --mantine-color-dark-2: #a8938c;  --mantine-color-dark-7: #241b18;
+  --mantine-color-dark-3: #7a655e;  --mantine-color-dark-8: #1b1512;
+  --mantine-color-dark-4: #5c4a44;  --mantine-color-dark-9: #120d0b;
+}
+
+/* Ground, text and border are a different colour in each scheme, so each one
+   is set in the scheme it belongs to. A scheme-dependent token left in the
+   block above is the classic unreadable-in-dark bug. */
+:root:root:root[data-mantine-color-scheme='light'] {
+  --mantine-color-body: #fdfaf8;
+  --mantine-color-text: #2a1f1b;
+  --mantine-color-default-border: #ecdfd9;
+  --mantine-color-dimmed: #7a625c;      /* keep AA: ~5.4:1 on the body above */
+  --mantine-color-placeholder: #826a64; /* ~4.8:1 */
+}
+:root:root:root[data-mantine-color-scheme='dark'] {
+  --mantine-color-body: #1b1512;
+  --mantine-color-text: #f3e9e4;
+  --mantine-color-default-border: #392b26;
+  --mantine-color-dimmed: #a8938c;      /* ~5.6:1 on the body above */
+  --mantine-color-placeholder: #8c7a74; /* ~4.7:1 */
+}
+```
+
+Check the four text tokens against your own grounds rather than copying these —
+`dimmed` is the most-used text colour in the app and the easiest to drop below
+4.5:1 while making it prettier, and it has to clear the bar on *both* grounds.
+
+**The selector is tripled on purpose.** Mantine's `cssVariablesResolver` injects
+its own `:root` block into `<head>` at runtime, which lands *after* your
+stylesheet and wins on source order at equal specificity. A plain `:root` here is
+silently reverted: the file reads correct, the app renders Mantine's defaults,
+and nothing errors. Repeating the pseudo-class raises specificity without adding
+an element to the selector.
+
+This one costs a whole pass if you meet it without knowing: you diagnose the
+colours correctly, write the right values, reload, and see no change — so you
+assume the diagnosis was wrong. **The only thing that catches it is looking at a
+screenshot and disbelieving the CSS.**
+
+Name them for what they *mean* in this product, never for the colour — `covered`,
+not `green`. The name is the whole value: it survives a change of palette, and it
+is the thing that makes the second use agree with the first. Define both colour
+schemes at once; a token defined only in light is the classic unreadable-in-dark
+bug, and Mantine will happily render it.
+
+The same file is where a couple of other things belong that the theme JSON has no
+field for and every screen otherwise re-invents: the hairline that separates rows
+in a list, the recessed surface a form sits on so it does not carry the same
+weight as the content it adds to, and the one animation the product is allowed
+(behind `prefers-reduced-motion`). Two or three rules, not a framework.
+
+If the app ships template screens you did not write — the error and not-found
+pages usually — read them before you call the palette done. They arrive with the
+scaffold's colours hardcoded, and a stock blue accent on an app whose direction
+says warm is the single loudest contradiction in the build.
+
 **Set the theme once, don't hardcode colours per component.** A screen full of
 inline `color="blue"` and one-off hex values is why apps look templated. Change
 the theme, not the components — and keep it theme-aware for light and dark.