branding-engine 0.1.0 → 0.2.1

package/README.md

@@ -1,129 +1,484 @@
 # branding-engine
 
-Generate a complete, self-consistent brand kit from one accent color and a
-monogram: a favicon set, a vector mark, wordmark lockups, social cards, a brand
-sheet, and drop-in web tokens. The mark and wordmark are real font outlines
-(pure vector, no raster source); only the social cards and brand sheet render
-live text via a headless browser.
+Generate a consistent brand kit from a compact alphanumeric mark and one accent
+color. Outputs include favicons, vector and raster marks, wordmark lockups,
+brand sheets, social cards, manifests, and CSS tokens.
 
-One monogram, one accent color, every brand surface.
+The mark and wordmark use real font outlines. The common website path requires
+only Node.js; browser rendering is optional.
 
-## Install
+## Example
 
-```sh
+Illustrative input using a non-production sample palette:
+
+```json
+{
+  "name": "Severino Labs",
+  "identity": {
+    "slug": "severino-labs",
+    "color": "#6D5EF7",
+    "deep": "#352A8A",
+    "onColor": "#FFFFFF",
+    "glyph": "SL",
+    "wordmark": "Severino Labs"
+  },
+  "portrait": "./studio.jpg",
+  "cardPalette": {
+    "accent": "#9B8CFF",
+    "textSoft": "#E3DEFF",
+    "textMuted": "#B7AFE8"
+  },
+  "cards": [
+    {
+      "file": "social-card.png",
+      "width": 1200,
+      "height": 630,
+      "photoWidth": 420,
+      "eyebrow": "Severino Labs",
+      "name": "Brand systems, generated.",
+      "tagline": "Marks, wordmarks, sheets, web assets, and social cards from one config.",
+      "meta": "Illustrative branding-engine example",
+      "url": "github.com/jseverino/branding-engine"
+    }
+  ]
+}
+```
+
+Generated mark:
+
+![Severino Labs generated mark](./examples/severino-labs/generated/severino-labs/mark/mark-512.png)
+
+Generated wordmark:
+
+![Severino Labs generated wordmark](./examples/severino-labs/generated/severino-labs/wordmark/wordmark-light.png)
+
+Generated brand sheet:
+
+![Severino Labs generated brand sheet](./examples/severino-labs/generated/severino-labs/sheet/overview.png)
+
+Generated social card:
+
+![Severino Labs generated social card](./examples/severino-labs/generated/cards/social-card.png)
+
+The complete input and committed generated output are in
+[`examples/severino-labs`](./examples/severino-labs/).
+
+## Requirements
+
+- Node.js 18 or newer
+- `sharp`, OpenType.js, and the WOFF2 decoder, installed automatically
+- Optional: `@playwright/test` plus Chromium for brand sheets and social cards
+
+Install:
+
+```bash
 npm install branding-engine
 ```
 
-`sharp` (used everywhere) installs automatically. `@playwright/test` is an
-**optional** dependency: it's only needed for the brand sheet and social cards.
-The mark, wordmark, and icon generation path needs neither Playwright nor Python.
-To enable sheets and cards:
+For a project-local CLI installation:
+
+```bash
+npm install --save-dev branding-engine
+npx branding-engine --help
+```
+
+The package can also be installed globally with
+`npm install --global branding-engine`, though project-local installation keeps
+the version reproducible for collaborators and CI.
+
+For sheets and social cards:
+
+```bash
+npm install --save-dev @playwright/test
+npx playwright install chromium
+```
+
+## Glyph Rules
+
+`glyph` is the compact mark rendered inside the tile.
+
+- Accepts 1-3 ASCII letters or digits
+- Lowercase letters are normalized to uppercase
+- Spaces, punctuation, symbols, and strings longer than three characters fail
+- Layout dynamically adjusts by character count and caps narrow marks by height
+
+Valid:
+
+```text
+A
+AC
+A3X
+7
+R2
+```
+
+Invalid:
 
-```sh
-npm i -D @playwright/test && npx playwright install chromium
+```text
+ABCD
+A C
+A-C
+@
 ```
 
-## Plug into a site (Astro, Eleventy, plain HTML)
+## Quick Start: Add Branding to a Website
 
-The fastest path for a website: scaffold a config, set your color, generate a
-favicon set into `public/`. No headless browser, no python.
+Use `init` and `generate` when a site needs favicons, a manifest, and CSS
+tokens in its public directory.
 
-```sh
-npm i -D branding-engine
-npx branding-engine init        # writes brand.config.json + a `brand` npm script
-# edit accent, glyph, name in brand.config.json, then:
-npm run brand                   # generates into public/, prints the <head> snippet
+```bash
+npm install --save-dev branding-engine
+npx branding-engine init
 ```
 
-`brand.config.json` is flat:
+Edit the generated `brand.config.json`:
 
 ```json
-{ "name": "My Site", "accent": "#2563EB", "glyph": "MS", "wordmark": "My Site" }
+{
+  "name": "My Site",
+  "accent": "#2563EB",
+  "deep": "#173B8F",
+  "onColor": "#FFFFFF",
+  "glyph": "MS"
+}
 ```
 
-`generate` writes these to `public/` at the root paths a static site expects, and
-prints the `<head>` block to paste in (its `theme-color` reflects your accent):
+Then generate the files:
+
+```bash
+npm run brand
+```
+
+Default output:
 
 ```text
-public/favicon.ico  favicon.svg  favicon-32.png  favicon-192.png
-public/apple-touch-icon.png  site.webmanifest  brand-tokens.css
+public/
+├── apple-touch-icon.png
+├── brand-tokens.css
+├── favicon-32.png
+├── favicon-192.png
+├── favicon.ico
+├── favicon.svg
+└── site.webmanifest
 ```
 
-Commit those files; they are deterministic, so re-running `npm run brand` after a
-color change reproduces them exactly. Optional flags: `--public <dir>`,
-`--config <file>`.
+The command also prints the `<head>` links to add to the site.
 
-## CLI
+### Website Config Reference
 
-```sh
-# A one-off kit (mark, wordmark, sheet, web) from an accent + initials
-branding-engine kit acme ff5733 AC "Acme Corp"
+| Field | Required | Description |
+|---|---:|---|
+| `name` | yes | Application name used in `site.webmanifest` |
+| `accent` | yes | Six-digit hex accent, with or without `#` |
+| `glyph` | yes | One to three alphanumeric mark characters |
+| `deep` | no | Dark palette shade; derived from `accent` when omitted |
+| `onColor` | no | Glyph color on the accent; defaults to `#FFFFFF` |
 
-# Just the lean, browser-free pieces (what a website needs)
-branding-engine kit acme ff5733 AC "Acme Corp" --only mark,wordmark,web
+Options:
 
-# A whole brand (primary identity + surfaces + cards) from a config
-branding-engine build --config ./brand --out ./kits
+```bash
+branding-engine generate --config path/to/brand.config.json --public path/to/public
 ```
 
-Flags: `--config <dir|brand.json>`, `--out <dir>`, `--font <file>`,
-`--only mark,wordmark,sheet,web,cards` (`mark` includes the favicon set).
+Generated files are deterministic and intended to be committed with the site.
+
+### Astro
+
+Astro serves files from `public/` at the site root, so the default generator
+paths work without customization:
 
-## Brand config
+```bash
+npm install --save-dev branding-engine
+npx branding-engine init
+npm run brand
+```
+
+In your shared layout, add the generated links and tokens:
+
+```astro
+<html lang="en">
+  <head>
+    <link rel="icon" href="/favicon.ico" sizes="any" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+    <link rel="manifest" href="/site.webmanifest" />
+    <link rel="stylesheet" href="/brand-tokens.css" />
+    <meta name="theme-color" content="#2563EB" />
+  </head>
+  <body><slot /></body>
+</html>
+```
 
-`build` reads a `brand.json` (and an optional sibling `surfaces.json`). Paths
-inside it (`font`, `portrait`) are resolved relative to the config's directory;
-omit `font` to use the bundled Inter.
+To regenerate before every production build, add it to the existing build
+script:
 
-```jsonc
+```json
+{
+  "scripts": {
+    "brand": "branding-engine generate",
+    "build": "npm run brand && astro build"
+  }
+}
+```
+
+### Plain HTML or Static Site
+
+If the repository already publishes a `public/` directory, use the same
+default commands as Astro. If the repository root itself is deployed:
+
+```bash
+npx branding-engine generate --public .
+```
+
+Add the links printed by the command to the page `<head>`, plus the token
+stylesheet:
+
+```html
+<link rel="stylesheet" href="/brand-tokens.css" />
+```
+
+The generated CSS variables can then be used from any stylesheet:
+
+```css
+.button {
+  color: var(--brand-on-accent);
+  background: var(--brand-accent);
+}
+```
+
+## Full Brand Kit
+
+Use `build` for a reusable config-driven kit:
+
+```bash
+branding-engine build --config ./brand --out ./kits
+```
+
+`--config` accepts either a `brand.json` path or a directory containing
+`brand.json`. An optional `surfaces.json` can live beside it.
+
+Minimal `brand.json`:
+
+```json
 {
   "name": "Acme",
-  "wordmarkWeight": 700,            // wordmark text weight (mark uses `weight`, default 800)
   "identity": {
     "slug": "acme",
-    "color": "#1E3A8A",            // accent
-    "deep": "#14245C",            // optional; falls back to a darkened accent
-    "onColor": "#ffffff",         // optional; color on the accent
+    "color": "#1E3A8A",
     "glyph": "AC",
     "wordmark": "Acme Corp"
+  }
+}
+```
+
+Expanded `brand.json`:
+
+```json
+{
+  "name": "Acme",
+  "font": "./AcmeSans.ttf",
+  "weight": 800,
+  "wordmarkWeight": 700,
+  "identity": {
+    "slug": "acme",
+    "color": "#1E3A8A",
+    "deep": "#14245C",
+    "onColor": "#FFFFFF",
+    "glyph": "A3C",
+    "wordmark": "Acme Corp"
+  },
+  "portrait": "./portrait.jpg",
+  "cardPalette": {
+    "accent": "#5B82D6",
+    "textSoft": "#DDE6FB",
+    "textMuted": "#A9C0E8"
   },
-  "cardPalette": { "accent": "#5B82D6", "textSoft": "#DDE6FB", "textMuted": "#A9C0E8" },
-  "cards": [ /* { file, width, height, photoWidth, eyebrow, name, tagline, meta, url } */ ]
+  "cards": [
+    {
+      "file": "social-card.png",
+      "width": 1200,
+      "height": 630,
+      "photoWidth": 420,
+      "eyebrow": "Acme Corp",
+      "name": "Acme",
+      "tagline": "Built for what comes next.",
+      "meta": "Brand systems and engineering",
+      "url": "acme.example"
+    }
+  ]
 }
 ```
 
-`surfaces.json` lists other surfaces that inherit the font and glyph and override
-only color (and optionally wordmark):
+### Full Config Reference
+
+| Field | Required | Description |
+|---|---:|---|
+| `name` | no | Human-readable brand name used in logs and fallbacks |
+| `identity` | yes | Primary brand identity object |
+| `identity.slug` | yes | Output directory name |
+| `identity.color` | yes | Six-digit accent color |
+| `identity.glyph` | yes | One to three alphanumeric mark characters |
+| `identity.wordmark` | no | Text used for wordmark lockups and sheet title |
+| `identity.deep` | no | Curated dark shade |
+| `identity.onColor` | no | Glyph color on accent |
+| `font` | no | Font path relative to `brand.json`; defaults to bundled Inter |
+| `weight` | no | Mark font weight; defaults to `800` |
+| `wordmarkWeight` | no | Wordmark font weight; defaults to `700` |
+| `surfaces` | no | Inline additional surfaces; `surfaces.json` takes precedence |
+| `portrait` | for cards | JPEG path relative to `brand.json` |
+| `cardPalette` | for cards | Card accent and supporting text colors |
+| `cards` | no | Social-card definitions rendered to `<out>/cards/` |
+
+Additional surfaces inherit the primary glyph unless they override it:
 
 ```json
-{ "support": { "color": "#1f4d57", "wordmark": "Acme Support" } }
+{
+  "support": {
+    "color": "#1F4D57",
+    "wordmark": "Acme Support"
+  },
+  "labs": {
+    "color": "#7C3AED",
+    "glyph": "A3",
+    "wordmark": "Acme Labs"
+  }
+}
 ```
 
+## One-Off Kit
+
+Create a kit without a config file:
+
+```bash
+branding-engine kit acme ff5733 AC "Acme Corp"
+```
+
+Three-character example:
+
+```bash
+branding-engine kit prism 635bff P3X "Prism Works" \
+  --only mark,wordmark,web \
+  --out ./kits
+```
+
+Syntax:
+
+```text
+branding-engine kit <slug> <hex> <glyph> ["Wordmark"] [options]
+```
+
+## Stages
+
+Select stages with a comma-separated `--only` value:
+
+```bash
+branding-engine build \
+  --config ./brand.json \
+  --out ./kits \
+  --only mark,wordmark,web
+```
+
+| Stage | Browser needed | Output |
+|---|---:|---|
+| `mark` | no | Favicons, vector mark, PNG marks, transparent variants |
+| `wordmark` | no | Vector and PNG title-case/all-caps lockups |
+| `web` | no | CSS tokens, web manifest, and `<head>` snippet |
+| `sheet` | yes | Brand overview poster, sections, and generated kit README |
+| `cards` | yes | Configured social-card PNGs |
+
+Without `--only`, all stages run.
+
+## Output Layout
+
+Each kit is written under `<out>/<slug>/`:
+
+```text
+<out>/<slug>/
+├── icons/
+├── mark/
+├── sheet/
+├── web/
+└── wordmark/
+```
+
+Social cards are written to `<out>/cards/`.
+
 ## Programmatic API
 
 ```js
-import { buildBrand, buildKit, markSvg, wordmarkSvg } from 'branding-engine';
-
-await buildKit({ slug: 'acme', hex: '#ff5733', glyph: 'AC', wordmark: 'Acme', only: 'mark,wordmark', outDir: 'public/brand' });
-const svg = markSvg({ size: 64, bg: '#ff5733', glyph: 'AC' }); // pure string, no I/O
+import {
+  buildBrand,
+  buildKit,
+  generateSite,
+  markSvg,
+  normalizeGlyph,
+  wordmarkSvg,
+} from 'branding-engine';
+
+await buildKit({
+  slug: 'acme',
+  hex: '#FF5733',
+  glyph: 'a3x',
+  wordmark: 'Acme',
+  only: 'mark,wordmark,web',
+  outDir: 'public/brand',
+});
+
+const glyph = normalizeGlyph('a3x'); // "A3X"
+const mark = markSvg({ size: 64, bg: '#FF5733', glyph });
+const lockup = wordmarkSvg({
+  tileHex: '#FF5733',
+  text: 'Acme',
+  glyph,
+});
 ```
 
-## Output
+Main exports:
+
+- `buildBrand(options)`
+- `buildKit(options)`
+- `initSite(options)`
+- `generateSite(options)`
+- `makeMark(options)`
+- `makeWordmark(options)`
+- `makeSheet(options)`
+- `makeWeb(options)`
+- `makeCards(options)`
+- `markSvg(options)`
+- `wordmarkSvg(options)`
+- `normalizeGlyph(glyph)`
+- `renderCard(browser, options)`
+- `launchBrowser()`
 
-Each kit is `<out>/<slug>/`:
+## Fonts and Glyph Extraction
 
-- `icons/`: `favicon.svg/.ico`, `favicon-32/192.png`, `apple-touch-icon.png`
-- `mark/`: `mark.svg`, `mark-512/1024.png`, transparent light/dark
-- `wordmark/`: `wordmark.svg` + light/dark PNGs, plus all-caps `wordmark-caps.*`
-- `sheet/`: `overview.png` poster + section images, and a `README.md`
-- `web/`: `tokens.css`, `site.webmanifest`, `head.html`
+Bundled Inter caches include uppercase letters and digits for marks, plus
+uppercase, lowercase, digits, and spaces for wordmarks.
 
-Social cards land in `<out>/cards/`.
+Custom fonts and missing characters are extracted entirely in Node with
+OpenType.js and a WebAssembly WOFF2 decoder. No Python, fonttools, native
+binding, or system font utility is required. Supported input formats are TTF,
+OTF, WOFF, and WOFF2.
+
+Extracted caches are written under `.brand-cache/`, or the directory specified
+by `BRAND_CACHE_DIR`. The installed package is never modified. If a variable
+font cannot be instantiated at the requested `weight`, the build exits with the
+font filename and parser error; use a static font file or another supported
+variable font.
+
+## Errors
+
+The CLI exits nonzero with an actionable message for invalid glyphs, invalid
+colors, missing configs, unavailable font glyphs, or missing optional browser
+dependencies.
+
+Example:
+
+```text
+Invalid glyph: "ABCD". Expected 1-3 letters or digits, e.g. A, AC, or A3X.
+```
 
-## Fonts and python
+## License
 
-The bundled Inter ships with prebuilt glyph outlines, so the default font needs
-**no python**. A custom font (or a glyph outside the bundled set) is extracted on
-demand and requires `python3` + `fonttools` (`pip install -r requirements.txt`);
-the extracted cache is written under `.brand-cache/` (or `$BRAND_CACHE_DIR`),
-never into the installed package.
+MIT. The bundled Inter font includes its own notice under
+`assets/fonts/inter/NOTICE.md`.

package/bin/cli.mjs

@@ -3,7 +3,7 @@
 //   branding-engine init                              scaffold a site brand.config + npm script
 //   branding-engine generate [--public <dir>] [--config <file>]   favicons + manifest + tokens -> public/
 //   branding-engine build [--config <dir|brand.json>] [--out <dir>] [--only a,b]
-//   branding-engine kit <slug> <hex> <initials> ["Wordmark"] [--font f] [--out d] [--only a,b]
+//   branding-engine kit <slug> <hex> <glyph> ["Wordmark"] [--font f] [--out d] [--only a,b]
 // Stages for --only: mark, wordmark, sheet, web, cards (mark includes favicons).
 import { buildBrand, buildKit } from '../src/build.mjs';
 import { generateSite, initSite } from '../src/site.mjs';
@@ -29,17 +29,20 @@ const USAGE =
   '  branding-engine init                          scaffold brand.config.json + a `brand` npm script\n' +
   '  branding-engine generate [--public <dir>] [--config <file>]   favicons + manifest + tokens -> public/\n' +
   '  branding-engine build [--config <dir|brand.json>] [--out <dir>] [--only mark,wordmark,sheet,web,cards]\n' +
-  '  branding-engine kit <slug> <hex> <initials> ["Wordmark"] [--font <file>] [--out <dir>] [--only ...]';
+  '  branding-engine kit <slug> <hex> <glyph> ["Wordmark"] [--font <file>] [--out <dir>] [--only ...]\n' +
+  '    <glyph> is 1-3 letters or digits, e.g. A, AC, or A3X.';
 
 const [cmd, ...rest] = process.argv.slice(2);
 const { pos, opt } = parse(rest);
 
 try {
-  if (cmd === 'init') {
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    console.log(USAGE);
+  } else if (cmd === 'init') {
     const { created, headSnippet } = initSite({});
     if (created.length) console.log('Created:\n' + created.map((c) => '  ' + c).join('\n'));
     console.log('\nNext: edit brand.config.json (accent, glyph, name), then run `npm run brand`.');
-    console.log('\nAdd this to your site <head> (or import public/brand-tokens.css for the CSS vars):\n');
+    console.log('\nAdd this to your site <head>:\n');
     console.log(headSnippet + '\n');
   } else if (cmd === 'generate') {
     const { written, publicDir, headSnippet } = await generateSite({ config: opt.config, publicDir: opt.public });
@@ -58,7 +61,7 @@ try {
     await buildKit({ slug, hex, glyph, wordmark, font: opt.font, outDir: opt.out, only: opt.only });
   } else {
     console.error(USAGE);
-    process.exit(cmd ? 1 : 0);
+    process.exit(1);
   }
 } catch (err) {
   console.error(`\n${err.message}`);

package/examples/severino-labs/README.md

@@ -0,0 +1,95 @@
+# Severino Labs example
+
+This illustrative example uses the Severino Labs name with a non-production
+sample palette. It runs the full-kit `build` command from
+[`brand.json`](./brand.json):
+
+```json
+{
+  "name": "Severino Labs",
+  "identity": {
+    "slug": "severino-labs",
+    "color": "#6D5EF7",
+    "deep": "#352A8A",
+    "onColor": "#FFFFFF",
+    "glyph": "SL",
+    "wordmark": "Severino Labs"
+  },
+  "portrait": "./studio.jpg",
+  "cardPalette": {
+    "accent": "#9B8CFF",
+    "textSoft": "#E3DEFF",
+    "textMuted": "#B7AFE8"
+  },
+  "cards": [
+    {
+      "file": "social-card.png",
+      "width": 1200,
+      "height": 630,
+      "photoWidth": 420,
+      "eyebrow": "Severino Labs",
+      "name": "Brand systems, generated.",
+      "tagline": "Marks, wordmarks, sheets, web assets, and social cards from one config.",
+      "meta": "Illustrative branding-engine example",
+      "url": "github.com/jseverino/branding-engine"
+    }
+  ]
+}
+```
+
+Regenerate the committed output from the repository root:
+
+```bash
+node bin/cli.mjs build \
+  --config examples/severino-labs/brand.json \
+  --out examples/severino-labs/generated
+```
+
+## Preview
+
+![Severino Labs generated icon](./generated/severino-labs/mark/mark-512.png)
+
+![Severino Labs generated wordmark](./generated/severino-labs/wordmark/wordmark-light.png)
+
+![Severino Labs generated brand sheet](./generated/severino-labs/sheet/overview.png)
+
+![Severino Labs generated social card](./generated/cards/social-card.png)
+
+## Generated files
+
+```text
+generated/severino-labs/
+├── icons/
+│   ├── apple-touch-icon.png
+│   ├── favicon-32.png
+│   ├── favicon-192.png
+│   ├── favicon.ico
+│   └── favicon.svg
+├── mark/
+│   ├── mark-512.png
+│   ├── mark-1024.png
+│   ├── mark-transparent-dark.png
+│   ├── mark-transparent-light.png
+│   └── mark.svg
+├── sheet/
+│   ├── overview.png
+│   ├── palette.png
+│   ├── sheet-mark.png
+│   └── type-specimen.png
+├── web/
+│   ├── head.html
+│   ├── site.webmanifest
+│   └── tokens.css
+└── wordmark/
+    ├── wordmark-caps-dark.png
+    ├── wordmark-caps-light.png
+    ├── wordmark-caps.svg
+    ├── wordmark-dark.png
+    ├── wordmark-light.png
+    └── wordmark.svg
+
+generated/cards/
+└── social-card.png
+```
+
+These files are generated by `branding-engine`; do not edit them by hand.