Ship Brand

Turn docs/brand.json (brand-as-data: colors + fonts) into a complete, production-ready brand kit: an expanded palette, a type scale, design tokens, a favicon/app-icon spec, social images, and an OG share image — all derived deterministically from one file so everything is on-brand.

This is the brand-kit member of the /ship-* pack. It pairs with:

• logo-pack (ship-logos) — makes the logo; ship-brand turns it into the full asset set.
• user-guide-builder (ship-guide) and shipping-log (ship-changelog) — read the same

brand.json so docs match the kit.

• screenshot-capture (ship-screenshots) — uses the same tokens for on-brand callouts.

The split is deliberate: the derivation (palette math, contrast, sizes, manifests) is deterministic and done by a script. The image generation is generator-agnostic — the skill writes specs and prompts; you point them at whatever image engine is set up (adapters below).

Workflow

1. Discover what already exists (always first)

Never overwrite blindly. Scan inputs and prior outputs:

node "${CLAUDE_PLUGIN_ROOT}/skills/ship-brand/scripts/scan-assets.mjs"        # or --json

It reports: docs/brand.json (name, color count, fonts), docs/VERSION, any prior kit in docs/brand/, any favicons / app icons / OG images / real web manifests (site.webmanifest, manifest.webmanifest, bare manifest.json — not the kit's own icon-manifest.json) the app already ships, and any reusable logos in docs/brand/logos/ (or public/logos/, etc.). It walks public/, src/app/, and monorepo packages/*/public, then ends with a recommendation:

• No `brand.json` → scaffold one (step 2), don't invent a brand.
• Prior kit exists → re-derive to refresh; only regenerate images that actually changed.
• A logo is present → use Adapter A (resize the square mark into every icon size — the

cleanest, brand-preserving path; see step 5). The scan surfaces this, not just the docs.

• App already ships icons → derive the kit, then fill gaps (missing sizes / social / OG)

rather than duplicating what exists.

2. Ensure brand.json exists (honest about missing input)

If scan-assets.mjs found none, scaffold a starter and stop until it's filled in:

node "${CLAUDE_PLUGIN_ROOT}/skills/ship-brand/scripts/brand-kit.mjs" --init

This writes a starter docs/brand.json (no purple by default) with name, tagline, colors, fonts. Help the user set the real brand color (brand), accent, neutrals, and font names — then re-run. Do not fabricate brand colors. If a logo exists but no brand.json, run logo-pack first or read the colors off the logo with the user.

3. Derive the kit (deterministic, dependency-free)

node "${CLAUDE_PLUGIN_ROOT}/skills/ship-brand/scripts/brand-kit.mjs"          # human report
node "${CLAUDE_PLUGIN_ROOT}/skills/ship-brand/scripts/brand-kit.mjs" --write  # write outputs

--write emits, into docs/brand/:

What the script computes (see [references/derivation.md](references/derivation.md) for the math):

• Palette — each opaque named color → a 50–900 lightness ramp (hue/sat preserved). Alpha

overlays (e.g. grid: rgba(...,.07)) keep their raw var only — no ramp, since a tint ladder of a 7%-opacity scrim is noise.

• Contrast — for every color, the WCAG 2.1 ratio against black and white text, with AA / AAA

verdicts, so you pick text colors with evidence, not by eye.

• Type scale — a modular scale (display→caption) from --base px and --ratio

(default 16 / 1.25; pass --base 18 --ratio 1.2 to change).

• Icon + social manifest — the standard real-world sizes (favicon 16/32/48, .ico,

apple-touch 180, PWA 192/512, maskable 512; avatar 512, X banner 1500×500, LinkedIn 1584×396, OG 1200×630), each tagged with where it's used.

4. Render the brand-kit gallery (self-contained, themeable HTML)

Build a single-file docs/brand/brand-kit.html that shows the kit: palette swatches with their hex + AA/AAA badges, the type scale rendered live, and an icon spec board (a labeled square per required size — the spec, with the real images dropped in once generated). Theme it from tokens.css via :root. Follow [references/html-rules.md](references/html-rules.md): self-contained, no external CSS/JS, themed from brand.json (NEVER purple by default), and never backdrop-filter or SVG feTurbulence (they hang renderers).

5. Generate the images (generator-agnostic — use an adapter)

The kit specifies what to render; you choose the engine. For each entry in icon-manifest.json, generate at the listed pixel size onto a transparent (icons) or branded (social/OG) canvas. Use whichever adapter is available — see [references/generator-adapters.md](references/generator-adapters.md):

• logo-pack output — the cleanest path: take the winning square mark from

docs/brand/logos/ and resize/pad it to each icon size; compose it onto the OG/banner canvas.

• `gemini-imagegen` skill (Nano Banana Pro) — render icons + OG/social art directly.
• `using-local-ideogram4` skill — when the OG/banner needs crisp headline text.
• Ad Lab (optional, only if installed) — resolve its path from $AD_LAB_DIR / PATH / a known

checkout (never a hardcoded drive letter), then node "$AD_LAB_DIR/scripts/generate-image.js" -p "<prompt>" -o docs/brand/icons/<file>. See Adapter D for the discovery snippet.

Save icons to docs/brand/icons/, social to docs/brand/social/. Generate, look at the output, keep the strongest. For OG/banner, the prompt names the brand colors and reserves a clear text zone for the product name + tagline.

6. Wire it up + report

Tell the user exactly what to do with the output:

• Copy docs/brand/icons/* and site.webmanifest to the app's web root (e.g. public/).
• Paste head-snippet.html into the app's <head> (Next.js: app/layout.tsx metadata or

app/head). Adjust paths if assets live under a sub-path.

• Stamp the kit with docs/VERSION so it travels with the release.

Report: the derived palette + contrast summary, the type scale, which images were generated vs. still pending (be honest about gaps), and the wire-up steps. Cross-link ship-logos if the logo needs work and ship-guide so the docs pick up the new tokens.

Worked example (input → output)

Input — docs/brand.json:

{ "name": "MyFieldTime", "tagline": "Run your jobs. Not your inbox.",
  "colors": { "bg": "#0a0a0f", "brand": "#2f7dff", "accent": "#FFDD00", "muted": "#8b9bb4" },
  "fonts": { "display": "Bricolage Grotesque", "body": "Hanken Grotesk" } }

Run — node …/brand-kit.mjs --write. Output (excerpt):

• brand ramp: 50 #ebf2ff · 200 #9ec2ff · 500 #0060ff · 700 #003fa8 · 900 #001d4d.
• Contrast: brand #2f7dff → best text black, 5.5:1, AA (so white nav text on a brand button

needs a darker stop like brand-700 for AA body text). accent #FFDD00 → black text, 15.59:1, AAA. muted #8b9bb4 → black, 7.45:1, AAA — safe for secondary text on light.

• Type scale (16 / 1.25): display 39px · h1 31px · h2 25px · body 16px · caption 10.24px.
• tokens.css with all --brand-50..900, --font-display: "Bricolage Grotesque", --text-*.
• icon-manifest.json listing 8 icons + 4 social/OG sizes, each with a purpose.
• site.webmanifest themed #2f7dff on #0a0a0f; head-snippet.html with the <link>/OG tags.

Then the kit gallery renders those swatches (each with its AA/AAA badge) and an icon spec board, and the images get generated from the logo-pack mark — a complete kit from one JSON file.

Quality bar

• Derived, not eyeballed. Palette ramps and contrast come from the script's math. Every

text-on-color choice cites a real WCAG ratio + AA/AAA verdict — no "looks fine."

• Honest about inputs. Missing brand.json → scaffold and stop, never invent a brand.

Unparseable color values are reported and skipped; alpha overlays keep a raw var but no ramp — both are surfaced in the report, not silently guessed or padded with noise. An unparseable color that still lands in tokens.css is annotated there too (/* unparsed — no ramp/contrast, not validated */), so the token file is as honest as the report and no reader mistakes it for an endorsed token.

• Discovery tells the truth. It distinguishes a shipped web manifest from the kit's own

files: anything under the output dir docs/brand/ (the site.webmanifest and icons/* that --write itself produces) is excluded from the shipped-asset scan, so a second run never re-reports its own output as a pre-existing app asset. It also actually detects a reusable logo (docs/brand/logos/…) so the recommended Adapter A path is found, not merely described.

• Reuse over churn. Discovery runs first; existing icons are extended, not duplicated. A

re-run refreshes tokens and regenerates only what changed.

• Real sizes, real purposes. The icon manifest is the actual production set (favicon → .ico

→ apple-touch → PWA/maskable → OG/social), each labeled with where it's used — not a vague list.

• On-brand, never generic. Tokens, manifest theme color, and HTML all source brand.json.

Never purple unless the brand says so. OG/social art is specific to this product.

• HTML that renders anywhere. Self-contained, themeable via :root, no backdrop-filter,

no feTurbulence.

• Portable. Nothing hardcoded to one app; image engines are adapters, never assumed installed.