@spunto/design-system 0.25.0 → 0.26.0

package/README.md

@@ -470,6 +470,34 @@ it, the navs and footers (they hard-code URLs and a session), the product logos
 and OG cards. The rule: *if it needs to know a product, a URL or a session, it's
 the site; if it only lays out or types, it's the system.*
 
+## Brand — `/brand`
+
+The Spunto logo, behind its own entry: the one sub-export that knows Spunto by
+construction, kept out of the root so a third-party consumer of the primitives
+never ships the company's mark.
+
+```tsx
+import { SpuntoLogo } from "@spunto/design-system/brand"
+
+<SpuntoLogo />                                   // the brand: flame tile, night ink
+<SpuntoLogo variant="mark" tone="night" />       // S + dot only, what survives 16 px
+<SpuntoLogo tone="ink" className="text-primary" /> // no tile, currentColor
+```
+
+The drawing is a 7 × 7 grid — blocks of 10 on a pitch of 14 — and it tells the
+product: the dot is your container, the two brackets are an S with the dot for
+its middle stroke, three blocks on the left are Build, three lights on the right
+are Run, the belt along the bottom is Ship, three squares on top are the
+machines you already own. `tone` picks a declension (`flame`, `build`,
+`ship`, `run`, `night`, `cream`, `pillars`, `ink`); `paint` overrides
+any role on top of it.
+
+The geometry lives as data in `src/brand/logo.ts`, React-free, so the same
+shapes come out as an element (`SpuntoLogo`) and as a file
+(`spuntoLogoSvg()`). `npm run brand:export -- <dir>` writes one `.svg` per
+declension — favicon, per-product tiles — which is how a site gets its static
+copies without ever hand-editing an SVG.
+
 ## Toasts — `SpuntoProvider` + `toast()`
 
 `SpuntoProvider` is the design system's client umbrella provider. Mount it once

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,10 @@
       "types": "./src/components/marketing/index.ts",
       "import": "./src/components/marketing/index.ts"
     },
+    "./brand": {
+      "types": "./src/brand/index.ts",
+      "import": "./src/brand/index.ts"
+    },
     "./fonts": {
       "types": "./src/components/fonts.tsx",
       "import": "./src/components/fonts.tsx"
@@ -62,7 +66,8 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "brand:export": "node scripts/export-logo.ts"
   },
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",

package/src/brand/index.ts

@@ -0,0 +1,31 @@
+// @spunto/design-system/brand — the Spunto logo.
+//
+// Behind its own entry, like every domain sub-export: a `Button` knows nothing
+// about Spunto, and a third-party consumer of the primitives should not carry
+// the company's mark in their bundle. Here it *is* the point: the same drawing
+// for the console, for Spunto Lite, for the showcase, each in its own tone.
+//
+// `SpuntoLogo` is the React element. `spuntoLogoSvg` is the same drawing as a
+// static document — `scripts/export-logo.ts` uses it to write the favicon and
+// the per-product tiles a site serves as files.
+
+export { SpuntoLogo } from "./spunto-logo"
+export type { SpuntoLogoProps } from "./spunto-logo"
+
+export {
+  SPUNTO_LOGO_TONES,
+  SPUNTO_LOGO_VIEWBOX,
+  SPUNTO_LOGO_TILE_RADIUS,
+  spuntoLogoSvg,
+  spuntoLogoShapes,
+  spuntoLogoTile,
+  spuntoLogoFill,
+} from "./logo"
+export type {
+  SpuntoLogoPaint,
+  SpuntoLogoTone,
+  SpuntoLogoVariant,
+  SpuntoLogoRole,
+  SpuntoLogoShape,
+  SpuntoLogoSvgOptions,
+} from "./logo"

package/src/brand/logo.test.tsx

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest"
+import { renderToStaticMarkup } from "react-dom/server"
+
+import { SPUNTO_LOGO_TONES, spuntoLogoShapes, spuntoLogoSvg } from "./logo"
+import { SpuntoLogo } from "./spunto-logo"
+
+// The whole point of `logo.ts` being data is that the element and the file are
+// the same drawing. These pin that: same shapes, same fills, in the same order.
+// (React closes SVG elements with a tag, the file self-closes them — hence `/?>`.)
+const attrs = (svg: string) =>
+  [...svg.matchAll(/<(rect|circle|path)\b([^>]*?)\/?>/g)].map(([, tag, a]) => {
+    const kv = Object.fromEntries([...a.matchAll(/(\w+)="([^"]*)"/g)].map(([, k, v]) => [k, v]))
+    return { tag, ...kv }
+  })
+
+describe("SpuntoLogo", () => {
+  it("draws exactly what spuntoLogoSvg writes, for every tone", () => {
+    for (const tone of Object.keys(SPUNTO_LOGO_TONES) as Array<keyof typeof SPUNTO_LOGO_TONES>) {
+      const paint = SPUNTO_LOGO_TONES[tone]
+      expect(attrs(renderToStaticMarkup(<SpuntoLogo tone={tone} />))).toEqual(attrs(spuntoLogoSvg(paint)))
+      expect(attrs(renderToStaticMarkup(<SpuntoLogo tone={tone} variant="mark" />))).toEqual(
+        attrs(spuntoLogoSvg(paint, { variant: "mark" })),
+      )
+    }
+  })
+
+  it("has no tile and takes currentColor in the ink tone", () => {
+    const svg = renderToStaticMarkup(<SpuntoLogo tone="ink" />)
+    expect(svg).not.toContain('width="128"')
+    expect(svg.match(/fill="currentColor"/g)).toHaveLength(spuntoLogoShapes("glyph").length)
+  })
+
+  it("lets paint override a single role of a tone", () => {
+    const svg = renderToStaticMarkup(<SpuntoLogo tone="flame" paint={{ tile: "#be241f" }} />)
+    expect(svg).toContain('fill="#be241f"')
+    expect(svg).not.toContain('fill="#ec5100"')
+    expect(svg).toContain('fill="#0e0805"')
+  })
+
+  it("is hidden from assistive tech unless it is given a name", () => {
+    expect(renderToStaticMarkup(<SpuntoLogo />)).toContain('aria-hidden="true"')
+    const named = renderToStaticMarkup(<SpuntoLogo title="Spunto — home" />)
+    expect(named).toContain('role="img"')
+    expect(named).toContain("<title>Spunto — home</title>")
+  })
+
+  it("keeps the mark to the S and the dot, and the glyph to the full story", () => {
+    // 2 brackets + 1 dot; then 3 fleet + 3 build + 3 run + 4 ship.
+    expect(spuntoLogoShapes("mark")).toHaveLength(3)
+    expect(spuntoLogoShapes("glyph")).toHaveLength(3 + 3 + 3 + 3 + 4)
+  })
+})

package/src/brand/logo.ts

@@ -0,0 +1,238 @@
+// The Spunto logo, as data.
+//
+// This module is deliberately **pure**: no React, no DOM, no colour maths. It
+// describes the mark once — a list of shapes on a grid, and the named paints
+// that go on them — so that the same drawing can be emitted as a React element
+// (`SpuntoLogo`) and as a static `.svg` file (`spuntoLogoSvg`, used by
+// `scripts/export-logo.ts` to write the favicon and the per-product tiles). One
+// source, two outputs, nothing to keep in sync by eye.
+//
+// ─── The drawing ───────────────────────────────────────────────────────────
+//
+// A 7 × 7 grid: blocks of 10 on a pitch of 14, inset 17 from the edge of a
+// 128 × 128 tile. Everything snaps to it — the bars are blocks fused together,
+// the lights are blocks turned round. That grid is what the logo inherited
+// from its predecessor, and what keeps it in the family of the design system's
+// quasi-square 4 px radius: nothing here is drawn freehand.
+//
+// What it says, read from the centre outwards:
+//
+//   • the dot          — your container. The one thing the platform is about.
+//   • the two brackets — an S (for Spunto) whose middle stroke *is* the dot:
+//                        two L-shapes 180° apart, wrapping the container the
+//                        way the platform wraps a workspace.
+//   • three blocks, left  — Build. Layers stacked; an image being made.
+//   • three lights, right — Run. Round because they're alive: status lights.
+//   • the belt, bottom    — Ship. Square, round, square, round: what leaves
+//                           the build side and comes out running.
+//   • three squares, top  — the fleet. The machines you already own, the
+//                           roof everything else sits under.
+//
+// Each of those is a `role`, so a paint can colour the story (the `pillars`
+// tone lights Build / Ship / Run in their own tokens) or flatten it to one ink.
+
+export const SPUNTO_LOGO_VIEWBOX = 128
+
+/** Corner radius of the tile, in viewBox units — quasi-square, like the system. */
+export const SPUNTO_LOGO_TILE_RADIUS = 14
+
+/** Every part of the drawing that can be painted independently. */
+export type SpuntoLogoRole = "tile" | "core" | "build" | "run" | "ship" | "fleet"
+
+export type SpuntoLogoShape =
+  | { role: SpuntoLogoRole; kind: "rect"; x: number; y: number; w: number; h: number; rx?: number }
+  | { role: SpuntoLogoRole; kind: "circle"; cx: number; cy: number; r: number }
+  | { role: SpuntoLogoRole; kind: "path"; d: string }
+
+/**
+ * `glyph` is the whole story — the S, the container and its three pillars.
+ * `mark` is the S and the container alone, drawn larger: what survives at
+ * 16 px, so it is the favicon and the collapsed-sidebar icon.
+ */
+export type SpuntoLogoVariant = "glyph" | "mark"
+
+const PITCH = 14
+const BLOCK = 10
+const INSET = 17
+const CENTRE = SPUNTO_LOGO_VIEWBOX / 2
+
+/** Grid column/row `i` (0–6) → its top-left coordinate. */
+const at = (i: number) => INSET + PITCH * i
+
+const square = (role: SpuntoLogoRole, col: number, row: number): SpuntoLogoShape => ({
+  role,
+  kind: "rect",
+  x: at(col),
+  y: at(row),
+  w: BLOCK,
+  h: BLOCK,
+})
+
+const light = (role: SpuntoLogoRole, col: number, row: number): SpuntoLogoShape => ({
+  role,
+  kind: "circle",
+  cx: at(col) + BLOCK / 2,
+  cy: at(row) + BLOCK / 2,
+  r: BLOCK / 2,
+})
+
+/* The two brackets and the dot, in both sizes. Coordinates are spelled out
+   rather than computed so the paths read as what they are: an L, its 180°
+   twin, and the space between them. In the glyph the brackets are one block
+   thick, like every other bar on the grid; in the mark they are 14 — the
+   pitch — because at favicon size a 10-unit bar is a single blurred pixel. */
+const CORE = {
+  glyph: [
+    { role: "core", kind: "path", d: "M31 31h52v10H41v42H31z" }, // Γ — top bar, left stem
+    { role: "core", kind: "path", d: "M97 97H45V87h42V45h10z" }, // ⅃ — bottom bar, right stem
+    { role: "core", kind: "circle", cx: CENTRE, cy: CENTRE, r: 13 },
+  ],
+  mark: [
+    { role: "core", kind: "path", d: "M18 18h72v14H32v58H18z" },
+    { role: "core", kind: "path", d: "M110 110H38V96h58V38h14z" },
+    { role: "core", kind: "circle", cx: CENTRE, cy: CENTRE, r: 18 },
+  ],
+} satisfies Record<SpuntoLogoVariant, SpuntoLogoShape[]>
+
+const PILLARS: SpuntoLogoShape[] = [
+  // the fleet, on top
+  square("fleet", 2, 0),
+  square("fleet", 3, 0),
+  square("fleet", 4, 0),
+  // Build — blocks stacked on the left
+  square("build", 0, 2),
+  square("build", 0, 3),
+  square("build", 0, 4),
+  // Run — lights on the right
+  light("run", 6, 2),
+  light("run", 6, 3),
+  light("run", 6, 4),
+  // Ship — the belt along the bottom, build-side square to run-side round
+  square("ship", 1, 6),
+  light("ship", 2, 6),
+  square("ship", 3, 6),
+  light("ship", 4, 6),
+]
+
+/**
+ * The shapes of a variant, tile excluded (the tile is a paint decision, see
+ * `spuntoLogoTile`). Order is paint order.
+ */
+export function spuntoLogoShapes(variant: SpuntoLogoVariant = "glyph"): SpuntoLogoShape[] {
+  return variant === "mark" ? [...CORE.mark] : [...CORE.glyph, ...PILLARS]
+}
+
+/** The tile behind the drawing, when a paint asks for one. */
+export function spuntoLogoTile(): SpuntoLogoShape {
+  return {
+    role: "tile",
+    kind: "rect",
+    x: 0,
+    y: 0,
+    w: SPUNTO_LOGO_VIEWBOX,
+    h: SPUNTO_LOGO_VIEWBOX,
+    rx: SPUNTO_LOGO_TILE_RADIUS,
+  }
+}
+
+// ─── Paint ─────────────────────────────────────────────────────────────────
+
+/**
+ * What colour goes on what. `ink` is the fallback for every drawn role; a
+ * role named explicitly overrides it. No `tile` means a transparent
+ * background — the drawing alone, for a nav bar or a print.
+ */
+export interface SpuntoLogoPaint {
+  tile?: string
+  ink: string
+  core?: string
+  build?: string
+  run?: string
+  ship?: string
+  fleet?: string
+}
+
+/**
+ * The declensions. Each is a design-system token turned into a fixed value:
+ * a logo is an artefact, not a surface, so it does not follow the theme — the
+ * flame tile is the same flame at night. The values are the light-theme
+ * register of `styles.css` (`--flame`, `--build`, `--ship`, `--run`,
+ * `--night`, `--background`) and the sand the marketing pages use for ink on
+ * night, converted out of oklch.
+ *
+ * The idea is one tone per product: Spunto Cloud is the brand and wears
+ * `flame`; a product whose marketing accent is `build` wears `build`; the
+ * design system, whose accent is ink, wears `night`. `pillars` is the same
+ * drawing with its story lit — Build, Ship and Run each in their own token —
+ * for a hero or a social card, not for a 24 px header.
+ */
+export const SPUNTO_LOGO_TONES = {
+  /** The brand: flame tile, night ink. */
+  flame: { tile: "#ec5100", ink: "#0e0805" },
+  /** `--build` tile — amber. */
+  build: { tile: "#f9a733", ink: "#0e0805" },
+  /** `--ship` tile — orange. */
+  ship: { tile: "#fb7c01", ink: "#0e0805" },
+  /** `--run` tile — one step short of flame. */
+  run: { tile: "#f35800", ink: "#0e0805" },
+  /** `--night` tile, sand ink — what the design system itself wears. */
+  night: { tile: "#0e0805", ink: "#e0d3bb" },
+  /** Cream tile, night ink, the container lit in flame — for a light print. */
+  cream: { tile: "#fbf6ee", ink: "#0e0805", core: "#ec5100" },
+  /** Night, with the three pillars in their own tokens (night register). */
+  pillars: {
+    tile: "#0e0805",
+    ink: "#fbf6ee",
+    fleet: "#8b837d",
+    build: "#ffb649",
+    ship: "#ff8b27",
+    run: "#ff6917",
+  },
+} as const satisfies Record<string, SpuntoLogoPaint>
+
+export type SpuntoLogoTone = keyof typeof SPUNTO_LOGO_TONES
+
+/** The colour a role takes under a paint. `tile` returns `undefined` when there is none. */
+export function spuntoLogoFill(paint: SpuntoLogoPaint, role: SpuntoLogoRole): string | undefined {
+  if (role === "tile") return paint.tile
+  return paint[role] ?? paint.ink
+}
+
+// ─── Static SVG ────────────────────────────────────────────────────────────
+
+export interface SpuntoLogoSvgOptions {
+  variant?: SpuntoLogoVariant
+  /** `<title>` for the file; omitted, the SVG carries `aria-hidden`. */
+  title?: string
+}
+
+function shapeToSvg(shape: SpuntoLogoShape, fill: string): string {
+  switch (shape.kind) {
+    case "rect": {
+      const rx = shape.rx ? ` rx="${shape.rx}"` : ""
+      return `<rect x="${shape.x}" y="${shape.y}" width="${shape.w}" height="${shape.h}"${rx} fill="${fill}"/>`
+    }
+    case "circle":
+      return `<circle cx="${shape.cx}" cy="${shape.cy}" r="${shape.r}" fill="${fill}"/>`
+    case "path":
+      return `<path d="${shape.d}" fill="${fill}"/>`
+  }
+}
+
+/**
+ * The logo as a standalone SVG document — what goes on disk as a favicon, an
+ * `<img src>`, an `og:image` source. Same shapes, same paints as the React
+ * component; only the serialisation differs.
+ */
+export function spuntoLogoSvg(paint: SpuntoLogoPaint, options: SpuntoLogoSvgOptions = {}): string {
+  const { variant = "glyph", title } = options
+  const shapes = paint.tile ? [spuntoLogoTile(), ...spuntoLogoShapes(variant)] : spuntoLogoShapes(variant)
+  const body = shapes
+    .map((s) => shapeToSvg(s, spuntoLogoFill(paint, s.role) ?? paint.ink))
+    .map((line) => `  ${line}`)
+    .join("\n")
+  const head = title
+    ? `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${SPUNTO_LOGO_VIEWBOX} ${SPUNTO_LOGO_VIEWBOX}" role="img" aria-labelledby="t">\n  <title id="t">${title}</title>`
+    : `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${SPUNTO_LOGO_VIEWBOX} ${SPUNTO_LOGO_VIEWBOX}" aria-hidden="true">`
+  return `${head}\n${body}\n</svg>\n`
+}

package/src/brand/spunto-logo.tsx

@@ -0,0 +1,90 @@
+import type { SVGProps } from "react"
+
+import { cn } from "../utils"
+import {
+  SPUNTO_LOGO_TONES,
+  SPUNTO_LOGO_VIEWBOX,
+  spuntoLogoFill,
+  spuntoLogoShapes,
+  spuntoLogoTile,
+  type SpuntoLogoPaint,
+  type SpuntoLogoShape,
+  type SpuntoLogoTone,
+  type SpuntoLogoVariant,
+} from "./logo"
+
+/* ─── SpuntoLogo ────────────────────────────────────────────────────────────
+   The logo as a React element. Two axes:
+
+   `variant` — `glyph` (the whole story, from 24 px up) or `mark` (the S and
+   the container alone, for 16 px and collapsed sidebars).
+
+   `tone` — which declension. The seven named ones are fixed paints built
+   from the tokens (see `SPUNTO_LOGO_TONES`); `ink` is the odd one out: no
+   tile, and the drawing takes `currentColor`, so it follows the text colour
+   it sits in — the right choice for a header on a themed surface, where a
+   fixed flame tile would fight the page.
+
+   `paint` overrides any tone field by field. A product whose accent is not a
+   design-system token (the site's marketing `rust`, say) passes its own tile
+   here rather than getting a tone the package would then have to own. */
+
+export interface SpuntoLogoProps extends Omit<SVGProps<SVGSVGElement>, "children" | "viewBox"> {
+  variant?: SpuntoLogoVariant
+  /** @default "flame" */
+  tone?: SpuntoLogoTone | "ink"
+  /** Per-role overrides on top of the tone. */
+  paint?: Partial<SpuntoLogoPaint>
+  /** Width and height, in px. Leave it out to size with `className`. */
+  size?: number
+  /**
+   * Accessible name. Give one when the logo is the only content of a link
+   * ("Spunto — home"); leave it out when a wordmark sits next to it, and the
+   * SVG is hidden from assistive tech.
+   */
+  title?: string
+}
+
+const INK: SpuntoLogoPaint = { ink: "currentColor" }
+
+function Shape({ shape, fill }: { shape: SpuntoLogoShape; fill: string }) {
+  switch (shape.kind) {
+    case "rect":
+      return <rect x={shape.x} y={shape.y} width={shape.w} height={shape.h} rx={shape.rx} fill={fill} />
+    case "circle":
+      return <circle cx={shape.cx} cy={shape.cy} r={shape.r} fill={fill} />
+    case "path":
+      return <path d={shape.d} fill={fill} />
+  }
+}
+
+export function SpuntoLogo({
+  variant = "glyph",
+  tone = "flame",
+  paint: overrides,
+  size,
+  title,
+  className,
+  ...rest
+}: SpuntoLogoProps) {
+  const base: SpuntoLogoPaint = tone === "ink" ? INK : SPUNTO_LOGO_TONES[tone]
+  const paint: SpuntoLogoPaint = { ...base, ...overrides }
+  const shapes = paint.tile ? [spuntoLogoTile(), ...spuntoLogoShapes(variant)] : spuntoLogoShapes(variant)
+
+  return (
+    <svg
+      viewBox={`0 0 ${SPUNTO_LOGO_VIEWBOX} ${SPUNTO_LOGO_VIEWBOX}`}
+      width={size}
+      height={size}
+      className={cn("shrink-0", className)}
+      role={title ? "img" : undefined}
+      aria-hidden={title ? undefined : true}
+      {...rest}
+    >
+      {title && <title>{title}</title>}
+      {shapes.map((shape, i) => (
+        <Shape key={i} shape={shape} fill={spuntoLogoFill(paint, shape.role) ?? paint.ink} />
+      ))}
+    </svg>
+  )
+}