@pikku/skills 0.12.32 → 0.12.34

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.

package/skills/pikku-knowledge/SKILL.md

@@ -266,7 +266,7 @@ Two things about the output matter if you are driving it:
   `options` is empty when the answer is free text, and an empty list means offer free
   text — never invent choices to fill it.
 
-`hold` means a profile's own gate is holding the milestone and no seat this loop knows
+`hold` means a profile's own gate is holding the milestone and nothing this loop knows
 about can clear it. It names the hold and the notes it is about; what to do then
 belongs to that profile, not here.
 
@@ -282,7 +282,7 @@ pikku knowledge plan progress <milestone>          # what it still owes, read fr
 pikku knowledge plan defer <milestone> <item> -r "<why>"
 ```
 
-`progress` reconciles the plan against pikku's generated meta — set membership, never anyone's status — and exits non-zero while the first pass is short, or while anything already built contradicts the plan. Unbuilt work in a later pass is reported, not blocked; a function that shipped wide open against a planned permission rule blocks from any pass, because that is a hole rather than a backlog. Writing a plan is its own seat: read `pikku-architect`. Building against one is `pikku-build`.
+`progress` reconciles the plan against pikku's generated meta — set membership, never anyone's status — and exits non-zero while the first pass is short, or while anything already built contradicts the plan. Unbuilt work in a later pass is reported, not blocked; a function that shipped wide open against a planned permission rule blocks from any pass, because that is a hole rather than a backlog. How a plan is written is `pikku-architect`; building against one, and the order plan-then-build, is `pikku-build`.
 
 ### A finished milestone is a tombstone