@brunosouzas/design-system 0.5.1 → 0.5.3

package/README.md

@@ -146,7 +146,7 @@ Thirteen pieces draw a metro map and its page diagrams, for [stackledger](https:
 - `countBadge` takes `textSize` (6 to 48, default 11): without `height`, the height, width and baseline grow with it.
 - A line's colour comes from the map's data, so `pipe.fill`, `lineBadge.fill` and `zone.fill` also accept `#RRGGBB`. Every other colour is a token path, and a cover spec rejects any hex.
 - `map.bendRadius` (32) is the radius of a bundle's centre line at a 45° or 90° bend; no piece reads it, the map engine draws the arcs (`pipe.d` takes `A`).
-- The `map.*` tokens hold the measures (outline 3, shadow 3.5, line 12, casing 6, badge 20, node 46, ring 3, halo 1.5, licence 10, zone padding 32, bend radius 32…), `surface.*.zoneOpacity` the zone's opacity (0.12, dark 0.22), and `site.*` the page palette, fonts and type scale of brunosouzas.com in light and dark.
+- The `map.*` tokens hold the measures (outline 3, shadow 3.5, line 12, casing 6, badge 20, node 46, ring 3, halo 1.5, licence 10, zone padding 32, bend radius 32…), `surface.*.zoneOpacity` the zone's opacity (0.12, dark 0.22), `surface.*.backdropWater`, `backdropWaterEdge`, `backdropPark` and `backdropCredit` the colours of a city backdrop behind a map and its OpenStreetMap credit (no piece draws it; stackledger does), and `site.*` the page palette, fonts and type scale of brunosouzas.com in light and dark.
 
 ```ts
 import { lineBadge, pipe, stationMarker, toSvg } from "@brunosouzas/design-system";
@@ -168,7 +168,7 @@ Ten pieces draw what the blog's body diagrams need beyond the map pieces: `diagr
 
 ### The cast and the emotes
 
-`mascot({ who, x, y, face, action, scale, look, headTilt, prop })` draws one character standing with the centre of its ground line at `(x, y)`. Each one carries its identity in three layers, so no video has to introduce it: a body shape, a mark always visible, and a prop when its hands are free.
+`mascot({ who, x, y, face, action, scale, look, headTilt, prop, surface })` draws one character standing with the centre of its ground line at `(x, y)`. Each one carries its identity in three layers, so no video has to introduce it: a body shape, a mark always visible, and a prop when its hands are free.
 
 | `who` | Body | Mark | Prop | Colour |
 |---|---|---|---|---|
@@ -184,7 +184,7 @@ Ten pieces draw what the blog's body diagrams need beyond the map pieces: `diagr
 - `action`: `none` (the default: an expression has no hands or feet), `rest`, `wave`, `hold`, `reach`, `up`, `shrug`, `type`. Arms and legs start at the body's sides; hands are mittens.
 - `look` (-1 to 1) moves the gaze, `headTilt` (-30 to 30) turns the agent's head on its neck, `prop: false` hides the prop. Every part is a group named by `data-part` (`body`, `face`, `eyes`, `brows`, `mouth`, `arm-left`, `arm-right`, `legs`, `prop`, `mark`, …), so a scene can animate it.
 
-`emote({ kind, x, y, scale, burst })` draws a reaction beside a head, never over the face. Each kind keeps one meaning in every video, like the colours:
+`emote({ kind, x, y, scale, burst, surface })` draws a reaction beside a head, never over the face. Each kind keeps one meaning in every video, like the colours:
 
 | `kind` | Shape | Meaning |
 |---|---|---|
@@ -199,7 +199,7 @@ Ten pieces draw what the blog's body diagrams need beyond the map pieces: `diagr
 
 In a scene, an emote pops in on the frame the face changes (`emotePop` in `src/brand/cast-motion.ts`, with `leave`, `blinking`, `breathe`, `squashAfter` and `hop`), one at a time, and the body acts through `pose`. A mascot's colour is its identity and never changes with state. The approved motion test is the Studio composition `cast-motion-test` (folder `cast`): `npx remotion render src/index.ts cast-motion-test`. It is a proof of the cast, not an article scene, so `npm run stills` and `npm run render` do not list it.
 
-The cast draws the same on any background; a dark-surface variant is planned (AB#187).
+On a dark page pass `surface: "dark"` (AB#187, 0.5.2): the hard shadows take `surface.dark.shadow`, the ground takes `surface.dark.grid`, and a light rim (`surface.dark.rim`) lines the whole outline, limbs and props included; faces are unchanged. Without `surface`, the cast draws as in 0.5.0.
 
 ### A cover
 

package/dist/src/pieces/cast.d.ts

@@ -1,4 +1,5 @@
 import { type SvgNode } from "./node.ts";
+import { type SurfaceName } from "./ink.ts";
 export declare const MASCOTS: readonly ["dev", "agent", "architect", "devops", "data", "request", "message"];
 export declare const MASCOT_FACES: readonly ["normal", "blink", "happy", "wink", "surprised", "worried", "thinking", "focused"];
 export declare const MASCOT_ACTIONS: readonly ["none", "rest", "wave", "hold", "reach", "up", "shrug", "type"];
@@ -18,6 +19,7 @@ export type MascotParams = {
     look?: number;
     headTilt?: number;
     prop?: boolean;
+    surface?: SurfaceName;
 };
 export type EmoteParams = {
     kind: EmoteKind;
@@ -25,6 +27,7 @@ export type EmoteParams = {
     y: number;
     scale?: number;
     burst?: boolean;
+    surface?: SurfaceName;
 };
 /** One character standing with the centre of its ground line at (x, y). */
 export declare const mascot: import("./piece.ts").Piece<MascotParams>;

package/dist/src/pieces/cast.js

@@ -10,7 +10,9 @@
 // (~/.hermes/spikes/design-system/cast-and-emotes/cast.mts). The frozen fixture
 // test/fixtures/cast-0.5.0.json pins every call's output, so a refactor here
 // must keep every hash.
+import { tokens } from "../../tokens/generated/tokens.js";
 import { drawn, el, g } from "./node.js";
+import { surfaceParam } from "./ink.js";
 import { colour, pos } from "./params.js";
 import { definePiece } from "./piece.js";
 const c = (path) => colour(path);
@@ -20,10 +22,59 @@ export const MASCOT_ACTIONS = ["none", "rest", "wave", "hold", "reach", "up", "s
 export const EMOTE_KINDS = ["idea", "doubt", "problem", "worked", "refused", "pressure", "liked", "waiting"];
 const ink = () => c("color.ink");
 const O = () => ({ stroke: ink(), "stroke-width": 4, "stroke-linejoin": "round" });
-const shade = (d, dx = 8) => el("path", { d, fill: ink(), transform: `translate(${dx} ${dx})` });
+// Every hard shadow is made by `hard`, so the dark drawing finds it by identity, not by its look.
+const SHADOWS = new WeakSet();
+const hard = (n) => (SHADOWS.add(n), n);
+const shade = (d, dx = 8) => hard(el("path", { d, fill: ink(), transform: `translate(${dx} ${dx})` }));
 const solid = (d, fill, dx = 8) => [shade(d, dx), el("path", { d, fill, ...O() })];
 const shine = (d, col) => el("path", { d, fill: "none", stroke: col, "stroke-width": 9, "stroke-linecap": "round" });
 const rr = (x, y, w, h, r) => `M${x + r},${y} H${x + w - r} Q${x + w},${y} ${x + w},${y + r} V${y + h - r} Q${x + w},${y + h} ${x + w - r},${y + h} H${x + r} Q${x},${y + h} ${x},${y + h - r} V${y + r} Q${x},${y} ${x + r},${y} Z`;
+// ---------------------------------------------------------------- dark surface (card 187)
+// On the dark surface (ADR 0003 amendment) the light drawing is rewritten, so the
+// light output stays the frozen 0.5.0 tree: each hard shadow (made by `hard`) takes the surface's
+// shadow colour, the ground takes the surface's grid colour, and a light rim
+// (the drawing in the rim colour, every stroke widened by 2 × 2 × rimWidth) sits
+// behind the whole outline, arms and legs included. The face is unchanged.
+const walk = (n, f) => {
+    const m = f(n);
+    if (!m)
+        return null;
+    const kids = m.children.map((k) => (typeof k === "string" ? k : walk(k, f))).filter((k) => k !== null);
+    return { ...m, children: kids };
+};
+const part = (n) => String(n.attrs["data-part"] ?? "");
+const onDark = (n) => {
+    const d = tokens.surface.dark;
+    return walk(n, (x) => {
+        if (SHADOWS.has(x))
+            return { ...x, attrs: { ...x.attrs, fill: d.shadow } };
+        if (part(x) === "ground")
+            return { ...x, children: x.children.map((k) => (typeof k === "string" ? k : { ...k, attrs: { ...k.attrs, fill: d.grid } })) };
+        return x;
+    });
+};
+const rimOf = (n) => {
+    const d = tokens.surface.dark;
+    return walk(n, (x) => {
+        if (SHADOWS.has(x) || ["ground", "face"].includes(part(x)) || x.attrs.opacity !== undefined)
+            return null;
+        if (x.tag === "g")
+            return x;
+        const sw = x.attrs.stroke !== undefined && x.attrs.stroke !== "none" ? Number(x.attrs["stroke-width"] ?? 4) : 0;
+        const attrs = { ...x.attrs, stroke: d.rim, "stroke-width": sw + 4 * d.rimWidth, "stroke-linejoin": "round" };
+        if (x.attrs.fill !== undefined && x.attrs.fill !== "none")
+            attrs.fill = d.rim;
+        return { ...x, attrs };
+    });
+};
+/** The light drawing redrawn for the dark surface: ground, rim, then the drawing. */
+const darken = (root) => {
+    // The rim is taken from the light tree, where shadows are still known by identity.
+    const isGround = (k) => typeof k === "object" && part(k) === "ground";
+    const rim = rimOf({ ...root, attrs: {}, children: root.children.filter((k) => !isGround(k)) });
+    const dark = onDark(root);
+    return { ...dark, children: [...dark.children.filter(isGround), ...(rim ? [g({ "data-part": "rim" }, ...rim.children)] : []), ...dark.children.filter((k) => !isGround(k))] };
+};
 // ---------------------------------------------------------------- face (macs.ts)
 export const face = (cx, cy, f, col, mouthFill) => {
     const k = 1, dx = 24 * k;
@@ -206,7 +257,7 @@ const drawMascot = (p) => {
         parts = [...parts, g({ "data-part": "head", transform: `rotate(${tilt} ${top[0]} ${top[1]})` }, ...solid(rr(top[0] - 96, 0, 192, 132, 22), c("color.white")), el("path", { d: rr(top[0] - 80, 14, 160, 104, 12), fill: c("illustration.codePanel"), stroke: ink(), "stroke-width": 4 }), faceWrapped)];
     }
     const root = g({ "data-mascot": p.who, transform: `translate(${p.x} ${p.y}) scale(${k}) translate(${-ax} ${-ay})`, stroke: "none" }, g({ "data-part": "ground" }, el("ellipse", { cx: ax, cy: ay, rx: ch.ground, ry: 9, fill: c("cast.ground") })), ...(front ? [] : arms), legs, ...parts, ch.faceInHead ? null : faceWrapped, showProp ? g({ "data-part": "prop" }, ...ch.prop()) : null, ...(front ? arms : []));
-    return drawn([root]);
+    return drawn([p.surface === "dark" ? darken(root) : root]);
 };
 // ---------------------------------------------------------------- emotes (emotes.ts)
 const rays = (cx, cy, r1, r2, n, from = -150, to = -30) => Array.from({ length: n }, (_, i) => {
@@ -215,7 +266,7 @@ const rays = (cx, cy, r1, r2, n, from = -150, to = -30) => Array.from({ length:
     return el("path", { d: `M${r(cx + r1 * Math.cos(a))},${r(cy + r1 * Math.sin(a))} L${r(cx + r2 * Math.cos(a))},${r(cy + r2 * Math.sin(a))}`, stroke: ink(), "stroke-width": 6, "stroke-linecap": "round" });
 });
 const EO = () => ({ stroke: ink(), "stroke-width": 5, "stroke-linejoin": "round", "stroke-linecap": "round" });
-const disc = (cx, cy, r, fill) => [el("circle", { cx: cx + 6, cy: cy + 6, r, fill: ink() }), el("circle", { cx, cy, r, fill, ...EO() })];
+const disc = (cx, cy, r, fill) => [hard(el("circle", { cx: cx + 6, cy: cy + 6, r, fill: ink() })), el("circle", { cx, cy, r, fill, ...EO() })];
 const zed = (x, y, s) => {
     // A Z of height s with its top-left at (x, y - s): ink casing, caller fill.
     const w = s * 0.72, d = `M${x},${y - s} H${x + w} L${x},${y} H${x + w}`;
@@ -230,7 +281,7 @@ const drawEmote = (p) => {
             if (burst)
                 parts.push(el("circle", { cx, cy: cy - 6, r: 62, fill: c("color.transitional"), opacity: 0.35 }), ...rays(cx, cy - 6, 50, 72, 7, -180, 0));
             const bulb = `M${cx - 30},${cy - 10} A34,34 0 1 1 ${cx + 30},${cy - 10} Q${cx + 22},${cy + 6} ${cx + 18},${cy + 22} H${cx - 18} Q${cx - 22},${cy + 6} ${cx - 30},${cy - 10} Z`;
-            parts.push(el("path", { d: bulb, fill: ink(), transform: "translate(6 6)" }), el("path", { d: bulb, fill: c("color.transitional"), ...EO() }), el("path", { d: `M${cx - 16},${cy - 22} Q${cx - 12},${cy - 32} ${cx - 2},${cy - 34}`, fill: "none", stroke: c("color.white"), "stroke-width": 6, "stroke-linecap": "round" }), el("path", { d: `M${cx - 8},${cy + 22} V${cy} L${cx},${cy + 8} L${cx + 8},${cy} V${cy + 22}`, fill: "none", stroke: ink(), "stroke-width": 4, "stroke-linejoin": "round" }), el("rect", { x: cx - 18, y: cy + 22, width: 36, height: 12, rx: 3, fill: c("cast.metal"), ...EO(), "stroke-width": 4 }), el("rect", { x: cx - 14, y: cy + 34, width: 28, height: 10, rx: 5, fill: c("cast.metal"), ...EO(), "stroke-width": 4 }));
+            parts.push(hard(el("path", { d: bulb, fill: ink(), transform: "translate(6 6)" })), el("path", { d: bulb, fill: c("color.transitional"), ...EO() }), el("path", { d: `M${cx - 16},${cy - 22} Q${cx - 12},${cy - 32} ${cx - 2},${cy - 34}`, fill: "none", stroke: c("color.white"), "stroke-width": 6, "stroke-linecap": "round" }), el("path", { d: `M${cx - 8},${cy + 22} V${cy} L${cx},${cy + 8} L${cx + 8},${cy} V${cy + 22}`, fill: "none", stroke: ink(), "stroke-width": 4, "stroke-linejoin": "round" }), el("rect", { x: cx - 18, y: cy + 22, width: 36, height: 12, rx: 3, fill: c("cast.metal"), ...EO(), "stroke-width": 4 }), el("rect", { x: cx - 14, y: cy + 34, width: 28, height: 10, rx: 5, fill: c("cast.metal"), ...EO(), "stroke-width": 4 }));
             break;
         }
         case "doubt":
@@ -239,7 +290,7 @@ const drawEmote = (p) => {
         case "problem":
             if (burst)
                 parts.push(...rays(cx, cy, 48, 70, 5));
-            parts.push(el("path", { d: `M${cx},${cy - 44} L${cx + 46},${cy + 34} H${cx - 46} Z`, fill: ink(), transform: "translate(6 6)" }), el("path", { d: `M${cx},${cy - 44} L${cx + 46},${cy + 34} H${cx - 46} Z`, fill: c("color.failure"), ...EO() }), el("path", { d: `M${cx},${cy - 18} V${cy + 8}`, stroke: ink(), "stroke-width": 9, "stroke-linecap": "round" }), el("circle", { cx, cy: cy + 22, r: 5.5, fill: ink() }));
+            parts.push(hard(el("path", { d: `M${cx},${cy - 44} L${cx + 46},${cy + 34} H${cx - 46} Z`, fill: ink(), transform: "translate(6 6)" })), el("path", { d: `M${cx},${cy - 44} L${cx + 46},${cy + 34} H${cx - 46} Z`, fill: c("color.failure"), ...EO() }), el("path", { d: `M${cx},${cy - 18} V${cy + 8}`, stroke: ink(), "stroke-width": 9, "stroke-linecap": "round" }), el("circle", { cx, cy: cy + 22, r: 5.5, fill: ink() }));
             break;
         case "pressure":
             for (const [dx, dy, k] of [[0, 0, 1], [30, 22, 0.6]])
@@ -261,7 +312,8 @@ const drawEmote = (p) => {
             break;
     }
     const attrs = s === 1 ? { "data-emote": kind, stroke: "none" } : { "data-emote": kind, stroke: "none", transform: `translate(${cx} ${cy}) scale(${s}) translate(${-cx} ${-cy})` };
-    return drawn([g(attrs, ...parts)]);
+    const root = g(attrs, ...parts);
+    return drawn([p.surface === "dark" ? darken(root) : root]);
 };
 const unit = { kind: "number", min: 0, exclusiveMin: true, max: 10 };
 /** One character standing with the centre of its ground line at (x, y). */
@@ -275,6 +327,7 @@ export const mascot = definePiece("mascot", {
     look: { kind: "number", min: -1, max: 1 },
     headTilt: { kind: "number", min: -30, max: 30 },
     prop: { kind: "boolean" },
+    surface: surfaceParam,
 }, drawMascot, ({ who, headTilt }) => (headTilt !== undefined && headTilt !== 0 && who !== "agent" ? [{ path: "headTilt", message: "applies only to the agent" }] : []));
 /** One reaction symbol with a fixed meaning, centred on (x, y), beside a head. */
-export const emote = definePiece("emote", { kind: { kind: "enum", required: true, values: EMOTE_KINDS }, x: pos(), y: pos(), scale: unit, burst: { kind: "boolean" } }, drawEmote);
+export const emote = definePiece("emote", { kind: { kind: "enum", required: true, values: EMOTE_KINDS }, x: pos(), y: pos(), scale: unit, burst: { kind: "boolean" }, surface: surfaceParam }, drawEmote);

package/dist/src/pieces/ink.d.ts

@@ -15,6 +15,10 @@ export declare const limits: (...checks: (Problem | false)[]) => Problem[];
 /** The surface's colours and the ink measures at a scale. */
 export declare const inkOf: ({ surface, inkScale }: Ink) => {
     s: {
+        readonly backdropCredit: "#9AA6D6";
+        readonly backdropPark: "#183F52";
+        readonly backdropWater: "#1E3175";
+        readonly backdropWaterEdge: "#2A3F8A";
         readonly background: "#14215A";
         readonly grid: "#1C2D74";
         readonly muted: "#8F9BD0";
@@ -25,6 +29,10 @@ export declare const inkOf: ({ surface, inkScale }: Ink) => {
         readonly text: "#EEF2FF";
         readonly zoneOpacity: 0.22;
     } | {
+        readonly backdropCredit: "#5A6385";
+        readonly backdropPark: "#D4F2DF";
+        readonly backdropWater: "#C9D8FF";
+        readonly backdropWaterEdge: "#B5C7F5";
         readonly background: "#EEF2FF";
         readonly grid: "#E0E7FB";
         readonly muted: "#5B6694";

package/dist/tokens/generated/tokens.d.ts

@@ -275,6 +275,10 @@ export declare const tokens: {
     };
     readonly surface: {
         readonly dark: {
+            readonly backdropCredit: "#9AA6D6";
+            readonly backdropPark: "#183F52";
+            readonly backdropWater: "#1E3175";
+            readonly backdropWaterEdge: "#2A3F8A";
             readonly background: "#14215A";
             readonly grid: "#1C2D74";
             readonly muted: "#8F9BD0";
@@ -286,6 +290,10 @@ export declare const tokens: {
             readonly zoneOpacity: 0.22;
         };
         readonly light: {
+            readonly backdropCredit: "#5A6385";
+            readonly backdropPark: "#D4F2DF";
+            readonly backdropWater: "#C9D8FF";
+            readonly backdropWaterEdge: "#B5C7F5";
             readonly background: "#EEF2FF";
             readonly grid: "#E0E7FB";
             readonly muted: "#5B6694";

package/dist/tokens/generated/tokens.js

@@ -276,6 +276,10 @@ export const tokens = {
     },
     "surface": {
         "dark": {
+            "backdropCredit": "#9AA6D6",
+            "backdropPark": "#183F52",
+            "backdropWater": "#1E3175",
+            "backdropWaterEdge": "#2A3F8A",
             "background": "#14215A",
             "grid": "#1C2D74",
             "muted": "#8F9BD0",
@@ -287,6 +291,10 @@ export const tokens = {
             "zoneOpacity": 0.22
         },
         "light": {
+            "backdropCredit": "#5A6385",
+            "backdropPark": "#D4F2DF",
+            "backdropWater": "#C9D8FF",
+            "backdropWaterEdge": "#B5C7F5",
             "background": "#EEF2FF",
             "grid": "#E0E7FB",
             "muted": "#5B6694",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosouzas/design-system",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Design tokens and illustration pieces of brunosouzas.com: tokens as CSS, JSON and TypeScript, pieces that draw SVG (and React), and a cover command.",
   "license": "Apache-2.0",
   "repository": {

package/tokens/generated/tokens.css

@@ -176,6 +176,10 @@
   --ds-site-light-text: #444444;
   --ds-site-light-text-dark: #040404;
   --ds-site-light-text-light: #717171;
+  --ds-surface-dark-backdrop-credit: #9AA6D6;
+  --ds-surface-dark-backdrop-park: #183F52;
+  --ds-surface-dark-backdrop-water: #1E3175;
+  --ds-surface-dark-backdrop-water-edge: #2A3F8A;
   --ds-surface-dark-background: #14215A;
   --ds-surface-dark-grid: #1C2D74;
   --ds-surface-dark-muted: #8F9BD0;
@@ -185,6 +189,10 @@
   --ds-surface-dark-shadow: #4C5CB8;
   --ds-surface-dark-text: #EEF2FF;
   --ds-surface-dark-zone-opacity: 0.22;
+  --ds-surface-light-backdrop-credit: #5A6385;
+  --ds-surface-light-backdrop-park: #D4F2DF;
+  --ds-surface-light-backdrop-water: #C9D8FF;
+  --ds-surface-light-backdrop-water-edge: #B5C7F5;
   --ds-surface-light-background: #EEF2FF;
   --ds-surface-light-grid: #E0E7FB;
   --ds-surface-light-muted: #5B6694;

package/tokens/generated/tokens.json

@@ -275,6 +275,10 @@
   },
   "surface": {
     "dark": {
+      "backdropCredit": "#9AA6D6",
+      "backdropPark": "#183F52",
+      "backdropWater": "#1E3175",
+      "backdropWaterEdge": "#2A3F8A",
       "background": "#14215A",
       "grid": "#1C2D74",
       "muted": "#8F9BD0",
@@ -286,6 +290,10 @@
       "zoneOpacity": 0.22
     },
     "light": {
+      "backdropCredit": "#5A6385",
+      "backdropPark": "#D4F2DF",
+      "backdropWater": "#C9D8FF",
+      "backdropWaterEdge": "#B5C7F5",
       "background": "#EEF2FF",
       "grid": "#E0E7FB",
       "muted": "#5B6694",

package/tokens/generated/tokens.ts

@@ -277,6 +277,10 @@ export const tokens = {
   },
   "surface": {
     "dark": {
+      "backdropCredit": "#9AA6D6",
+      "backdropPark": "#183F52",
+      "backdropWater": "#1E3175",
+      "backdropWaterEdge": "#2A3F8A",
       "background": "#14215A",
       "grid": "#1C2D74",
       "muted": "#8F9BD0",
@@ -288,6 +292,10 @@ export const tokens = {
       "zoneOpacity": 0.22
     },
     "light": {
+      "backdropCredit": "#5A6385",
+      "backdropPark": "#D4F2DF",
+      "backdropWater": "#C9D8FF",
+      "backdropWaterEdge": "#B5C7F5",
       "background": "#EEF2FF",
       "grid": "#E0E7FB",
       "muted": "#5B6694",