@brunosouzas/design-system 0.1.1 → 0.2.0

package/README.md

@@ -90,7 +90,7 @@ npm run stills -- publish-subscribe               # 24 phase/final PNGs (six per
 npm run stills -- publish-subscribe --dry-run     # print 24 commands, no effects
 npm run render -- publish-subscribe --dry-run     # print eight commands; real video waits for owner stills approval
 npm run build                                     # compile the package into dist/ (the package test needs it)
-npm run cover -- cover.json --out card.svg        # build a blog cover from its spec
+npm run cover -- cover.json --out card.svg        # build a blog cover (or a banner) from its spec
 npm run pieces:sheet -- --out out/pieces.svg      # every piece once, labelled, for review
 npm run studio                                    # Remotion Studio, for frame-by-frame review
 ```
@@ -151,7 +151,7 @@ const badge = lineBadge({ x: 250, y: 40, text: "SH", fill: "#7B3FE4", surface: "
 
 ### A cover
 
-A cover is a JSON spec kept with its article, outside this repository: drafts are private, and only the pieces are public. `npm run cover -- <spec.json> --out <file.svg>` validates it, reports every problem with its JSON path, and writes an 800x420 SVG; the same spec always gives the same bytes.
+A cover is a JSON spec kept with its article, outside this repository: drafts are private, and only the pieces are public. `npm run cover -- <spec.json> --out <file.svg>` validates it, reports every problem with its JSON path, and writes an 800x420 SVG; the same spec always gives the same bytes. With `"format": "banner"` the same command writes a site banner instead (see below).
 
 ```json
 {
@@ -173,6 +173,15 @@ A cover is a JSON spec kept with its article, outside this repository: drafts ar
 - `custom` (optional) is the cover's one free-form object, a JSON node tree limited to drawing tags and a fixed list of attributes, with no external references. An object that repeats becomes a piece instead.
 - The three published covers that proved the pieces are the test fixtures in `test/fixtures/covers/`.
 
+### Banners
+
+A spec with `"format": "banner"` (the default is `"cover"`) builds a home banner for a site: `banner.width` x `banner.height` (1200x420) with corners rounded at `banner.radius` (20), the measures of brunosouzas.com's published banner. Same pieces, validation and command. Two things differ from a cover:
+
+- the rings go on until they reach the frame's farthest corner (22 rings for a centre at 600, 225 with radius 60), where a cover draws 14;
+- pieces and labels are clipped to the rounded frame too, so nothing pokes past a corner.
+
+The banner is one image that scales down as a whole. Words in it become small on a phone (a 19px label is about 6px at 375px wide), so keep them few or none. `test/fixtures/covers/home-banner.json` is the brunosouzas.com home banner redrawn from the pieces.
+
 ### A new piece
 
 Add it to `src/pieces/library.ts` (or `src/pieces/metro.ts` for a map or diagram piece) with `definePiece(name, schema, draw)`, take its colours and sizes from the tokens (a new colour goes to `tokens/source.json` first), register it in `PIECES`, and give it a sample in `scripts/pieces-sheet.ts`. The catalogue test then checks that it draws with only its required parameters and uses token colours only.

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

@@ -2,6 +2,9 @@ import { type PieceName } from "./library.ts";
 import { type SvgNode } from "./node.ts";
 import { type Problem } from "./params.ts";
 export declare const SAFE_ID: RegExp;
+/** Cover (800x420, the default) or banner (1200x420, rounded corners): spec cover-cli, "Banner output". */
+export declare const FORMATS: readonly ["cover", "banner"];
+export type CoverFormat = (typeof FORMATS)[number];
 export type CoverPiece = {
     piece: PieceName;
 } & Record<string, unknown>;
@@ -14,6 +17,7 @@ export type CoverSpec = {
     id: string;
     title: string;
     description: string;
+    format?: CoverFormat;
     background: string;
     rings: {
         cx: number;
@@ -28,5 +32,7 @@ export declare const backgroundNames: () => string[];
 export declare const comparePaths: (a: string, b: string) => number;
 /** Every problem of a parsed spec, sorted by path; empty when the spec is valid. */
 export declare const validateCoverSpec: (spec: unknown) => Problem[];
-/** The cover's node tree. The spec must be valid (validateCoverSpec returned no problem). */
+/** Rings a banner draws: out to the frame's farthest corner (spec cover-cli, "Banner rings reach the corners"). */
+export declare const bannerRingCount: (cx: number, cy: number, radius?: number) => number;
+/** The cover's (or banner's) node tree. The spec must be valid (validateCoverSpec returned no problem). */
 export declare const coverTree: (spec: CoverSpec) => SvgNode;

package/dist/src/pieces/cover.js

@@ -12,7 +12,9 @@ import { PIECE_NAMES, PIECES, rings } from "./library.js";
 import { el, g } from "./node.js";
 import { COLOUR_TOKENS, checkParams, isColourLiteral, MAX_SIZE, PATH_DATA } from "./params.js";
 export const SAFE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const TOP_LEVEL = ["id", "title", "description", "background", "rings", "pieces", "custom"];
+const TOP_LEVEL = ["id", "title", "description", "format", "background", "rings", "pieces", "custom"];
+/** Cover (800x420, the default) or banner (1200x420, rounded corners): spec cover-cli, "Banner output". */
+export const FORMATS = ["cover", "banner"];
 const CUSTOM_TAGS = ["g", "rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text"];
 // Attributes a free-form object may use (design §6): geometry, paint, text and transform.
 const CUSTOM_ATTRS = new Set([
@@ -154,7 +156,7 @@ export const validateCoverSpec = (spec) => {
     if (!isPlainObject(spec.rings))
         out.push({ path: "rings", message: "missing or not an object (expected cx, cy and an optional radius)" });
     else {
-        const ringProblems = checkParams(rings.schema, spec.rings, "rings").filter((problem) => problem.path !== "rings.color");
+        const ringProblems = checkParams(rings.schema, spec.rings, "rings").filter((problem) => problem.path !== "rings.color" && problem.path !== "rings.count");
         out.push(...ringProblems);
         // The piece takes any finite centre; a cover spec keeps 0.1.0's ±10000, which bounds a banner's ring count.
         for (const axis of ["cx", "cy"]) {
@@ -169,6 +171,11 @@ export const validateCoverSpec = (spec) => {
     }
     if (isPlainObject(spec.rings) && Object.hasOwn(spec.rings, "color"))
         out.push({ path: "rings.color", message: "unknown parameter: the ring colour comes from the background" });
+    if (isPlainObject(spec.rings) && Object.hasOwn(spec.rings, "count"))
+        out.push({ path: "rings.count", message: "unknown parameter: the ring count comes from the format" });
+    if (spec.format !== undefined && (typeof spec.format !== "string" || !FORMATS.includes(spec.format))) {
+        out.push({ path: "format", message: `expected one of ${FORMATS.join(", ")}` });
+    }
     if (!Array.isArray(spec.pieces))
         out.push({ path: "pieces", message: "missing or not an array" });
     else
@@ -254,12 +261,25 @@ const resolveCustom = (node) => {
         attrs.stroke = "none";
     return el(node.tag, attrs, ...(node.children ?? []).map((child) => (typeof child === "string" ? child : resolveCustom(child))));
 };
-/** The cover's node tree. The spec must be valid (validateCoverSpec returned no problem). */
+/** Rings a banner draws: out to the frame's farthest corner (spec cover-cli, "Banner rings reach the corners"). */
+export const bannerRingCount = (cx, cy, radius = tokens.cover.ringRadius) => {
+    const { width, height } = tokens.banner;
+    const far = Math.max(...[[0, 0], [width, 0], [0, height], [width, height]].map(([x, y]) => Math.hypot(x - cx, y - cy)));
+    return Math.max(1, Math.ceil((far - radius) / tokens.cover.ringStep) + 1);
+};
+/** The cover's (or banner's) node tree. The spec must be valid (validateCoverSpec returned no problem). */
 export const coverTree = (spec) => {
-    const { width, height } = tokens.cover;
+    const banner = spec.format === "banner";
+    const { width, height } = banner ? tokens.banner : tokens.cover;
+    // A banner's corners are rounded; a cover keeps today's square frame, attribute for attribute.
+    const corner = banner ? { rx: tokens.banner.radius } : {};
     const pair = tokens.coverBackground[spec.background];
     const drawnPieces = spec.pieces.map(({ piece, ...params }) => PIECES[piece](params));
     const ringPath = `coverBackground.${spec.background}.ring`;
+    const ringCount = banner ? { count: bannerRingCount(spec.rings.cx, spec.rings.cy, spec.rings.radius) } : {};
+    const frame = `url(#${spec.id}-frame)`;
+    const outlined = g({ stroke: tokens.color.ink, "stroke-width": tokens.outline.block, "stroke-linejoin": "round" }, ...drawnPieces.flatMap((d) => d.body), spec.custom ? resolveCustom(spec.custom) : null);
+    const labels = g({ "font-size": tokens.cover.labelSize, "font-weight": tokens.cover.labelWeight, fill: tokens.color.ink, "text-anchor": "middle" }, ...drawnPieces.flatMap((d) => d.text));
     return el("svg", {
         xmlns: "http://www.w3.org/2000/svg",
         width,
@@ -268,5 +288,7 @@ export const coverTree = (spec) => {
         role: "img",
         "aria-labelledby": `${spec.id}-title ${spec.id}-desc`,
         "font-family": tokens.font.sans,
-    }, el("title", { id: `${spec.id}-title` }, spec.title), el("desc", { id: `${spec.id}-desc` }, spec.description), el("defs", {}, el("clipPath", { id: `${spec.id}-frame` }, el("rect", { width, height }))), el("rect", { width, height, fill: pair.fill }), g({ "clip-path": `url(#${spec.id}-frame)` }, ...rings({ ...spec.rings, color: ringPath }).body), g({ stroke: tokens.color.ink, "stroke-width": tokens.outline.block, "stroke-linejoin": "round" }, ...drawnPieces.flatMap((d) => d.body), spec.custom ? resolveCustom(spec.custom) : null), g({ "font-size": tokens.cover.labelSize, "font-weight": tokens.cover.labelWeight, fill: tokens.color.ink, "text-anchor": "middle" }, ...drawnPieces.flatMap((d) => d.text)));
+    }, el("title", { id: `${spec.id}-title` }, spec.title), el("desc", { id: `${spec.id}-desc` }, spec.description), el("defs", {}, el("clipPath", { id: `${spec.id}-frame` }, el("rect", { width, height, ...corner }))), el("rect", { width, height, ...corner, fill: pair.fill }), g({ "clip-path": frame }, ...rings({ ...spec.rings, color: ringPath, ...ringCount }).body), 
+    // On a banner, pieces and labels are clipped too, so nothing pokes past a rounded corner.
+    ...(banner ? [g({ "clip-path": frame }, outlined, labels)] : [outlined, labels]));
 };

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

@@ -5,5 +5,5 @@ export { COLOUR_TOKENS, DATA_COLOUR, MAX_ITEMS, paint, MAX_SIZE, checkParams, co
 export { definePiece, type Piece } from "./piece.ts";
 export * from "./library.ts";
 export { EIP_ICONS, EIP_ICON_NAMES, EIP_ICON_HEIGHT, EIP_ICON_WIDTH, type EipIcon } from "./eip-icons.ts";
-export { SAFE_ID, backgroundNames, comparePaths, coverTree, validateCoverSpec, type CoverPiece, type CoverSpec, type CustomNode } from "./cover.ts";
+export { FORMATS, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, validateCoverSpec, type CoverFormat, type CoverPiece, type CoverSpec, type CustomNode } from "./cover.ts";
 export { tokens, type Tokens } from "../../tokens/generated/tokens.ts";

package/dist/src/pieces/index.js

@@ -10,5 +10,5 @@ export { COLOUR_TOKENS, DATA_COLOUR, MAX_ITEMS, paint, MAX_SIZE, checkParams, co
 export { definePiece } from "./piece.js";
 export * from "./library.js";
 export { EIP_ICONS, EIP_ICON_NAMES, EIP_ICON_HEIGHT, EIP_ICON_WIDTH } from "./eip-icons.js";
-export { SAFE_ID, backgroundNames, comparePaths, coverTree, validateCoverSpec } from "./cover.js";
+export { FORMATS, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, validateCoverSpec } from "./cover.js";
 export { tokens } from "../../tokens/generated/tokens.js";

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

@@ -10,13 +10,16 @@ export type PillParams = {
 /** Pill label centred on (x, y), usually overlapping the top edge of what it names. */
 export declare const pill: import("./piece.ts").Piece<PillParams>;
 export declare const RING_COUNT = 14;
+/** Most rings one call draws: enough for a banner's farthest corner from any centre a cover spec accepts (548). */
+export declare const MAX_RINGS = 1000;
 export type RingsParams = {
     cx: number;
     cy: number;
     radius?: number;
     color?: string;
+    count?: number;
 };
-/** Concentric rings around (cx, cy): 14 rings, step and width from the cover tokens. */
+/** Concentric rings around (cx, cy): `count` rings (14 by default), step and width from the cover tokens. */
 export declare const rings: import("./piece.ts").Piece<RingsParams>;
 export type SheetRow = {
     lead?: "none" | "checkbox" | "checked" | "question";

package/dist/src/pieces/library.js

@@ -23,9 +23,11 @@ export const pill = definePiece("pill", { x: pos(), y: pos(), text: label(), fil
 });
 // ---------- background ----------
 export const RING_COUNT = 14;
-/** Concentric rings around (cx, cy): 14 rings, step and width from the cover tokens. */
-export const rings = definePiece("rings", { cx: pos(), cy: pos(), radius: size(), color: col() }, ({ cx, cy, radius = tokens.cover.ringRadius, color = "color.ring" }) => drawn([
-    g({ fill: "none", stroke: colour(color, "color"), "stroke-width": tokens.cover.ringWidth }, ...Array.from({ length: RING_COUNT }, (_, i) => el("circle", { cx, cy, r: radius + i * tokens.cover.ringStep }))),
+/** Most rings one call draws: enough for a banner's farthest corner from any centre a cover spec accepts (548). */
+export const MAX_RINGS = 1000;
+/** Concentric rings around (cx, cy): `count` rings (14 by default), step and width from the cover tokens. */
+export const rings = definePiece("rings", { cx: pos(), cy: pos(), radius: size(), color: col(), count: count(1, MAX_RINGS) }, ({ cx, cy, radius = tokens.cover.ringRadius, color = "color.ring", count: rings = RING_COUNT }) => drawn([
+    g({ fill: "none", stroke: colour(color, "color"), "stroke-width": tokens.cover.ringWidth }, ...Array.from({ length: rings }, (_, i) => el("circle", { cx, cy, r: radius + i * tokens.cover.ringStep }))),
 ]));
 const rowSchema = {
     lead: { kind: "enum", values: ["none", "checkbox", "checked", "question"] },

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

@@ -1,4 +1,9 @@
 export declare const tokens: {
+    readonly banner: {
+        readonly height: 420;
+        readonly radius: 20;
+        readonly width: 1200;
+    };
     readonly color: {
         readonly backend: "#FF6B6B";
         readonly blocked: "#FF8A3D";

package/dist/tokens/generated/tokens.js

@@ -1,5 +1,10 @@
 // Generated from tokens/source.json by scripts/tokens.ts (npm run tokens). Do not edit by hand.
 export const tokens = {
+    "banner": {
+        "height": 420,
+        "radius": 20,
+        "width": 1200
+    },
     "color": {
         "backend": "#FF6B6B",
         "blocked": "#FF8A3D",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosouzas/design-system",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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

@@ -1,5 +1,8 @@
 /* Generated from tokens/source.json by scripts/tokens.ts (npm run tokens). Do not edit by hand. */
 :root {
+  --ds-banner-height: 420px;
+  --ds-banner-radius: 20px;
+  --ds-banner-width: 1200px;
   --ds-color-backend: #FF6B6B;
   --ds-color-blocked: #FF8A3D;
   --ds-color-caller: #8FB2FF;

package/tokens/generated/tokens.json

@@ -1,4 +1,9 @@
 {
+  "banner": {
+    "height": 420,
+    "radius": 20,
+    "width": 1200
+  },
   "color": {
     "backend": "#FF6B6B",
     "blocked": "#FF8A3D",

package/tokens/generated/tokens.ts

@@ -1,6 +1,11 @@
 // Generated from tokens/source.json by scripts/tokens.ts (npm run tokens). Do not edit by hand.
 
 export const tokens = {
+  "banner": {
+    "height": 420,
+    "radius": 20,
+    "width": 1200
+  },
   "color": {
     "backend": "#FF6B6B",
     "blocked": "#FF8A3D",