Toolchain

Documentation for BrandBuilder 3.0.1. Official release and exact skill asset.

Every tool below is open source and installable from a standard package manager. The agent's job at the start of a build is to find out what it actually has, say so, and route each asset to the best available producer.

Probing

Run python3 templates/probe.py <kit-dir> and route off what it reports. It prints the capability block, classifies the machine into the core, raster or full tier from 09-portability.md, and writes <kit>/qc/probe.json so the generators and VERIFY.md read measured facts rather than assumptions.

The core tier, Python and its standard library alone, must always succeed. The glyph gate in particular carries its own rasteriser precisely so it never degrades to a skip.

The equivalent by hand, when you want to see it yourself:

for t in inkscape rsvg-convert resvg magick convert potrace oxipng pngquant \
         cwebp avifenc svgo pdffonts qpdf soffice pandoc ffmpeg mmdc \
         oxlint stylelint node npx python3; do
  command -v "$t" >/dev/null 2>&1 && printf '%-14s %s\n' "$t" "$( "$t" --version 2>&1 | head -1 )" \
                                  || printf '%-14s MISSING\n' "$t"
done
python3 - <<'PY'
for m in ("coloraide","fontTools","PIL","playwright","pikepdf"):
    try:
        __import__(m); print(f"{m:12} present")
    except ImportError: print(f"{m:12} MISSING")
PY

State the findings in one short block, then proceed with the fallback chain. Do not narrate each individual miss.

The matrix

Asset on the left, first choice first. Later entries are the fallback chain.

Tools deliberately demoted

GIMP. Its script-fu batch interface is fragile and awkward to drive from an agent, and every job it would do here is done more reliably by ImageMagick or Pillow. GIMP stays on the list as a tool for a human doing interactive touch-up, and it is not an agent target.

ImageMagick for SVG rasterisation. Covered above. It delegates to librsvg and loses fidelity on the way. Call librsvg directly.

Google Fonts at build time. Ordinary generation uses bundled, locally licensed font files and must not fetch fonts over the network. Use the controlled ingestion command before a build when an approved fixed face is missing. See 01-canon.json typography.sourcing.

Contract commands

Run templates/validate_brand.py before any renderer. It rejects incomplete affiliation, inheritance, typography, supplied-input, palette-approval, path, hash, SVG-safety, license, and font metadata. Run templates/analyze_inputs.py only after validation, and run templates/scan_affiliation.py after generation to reject false ownership claims. templates/ingest_font.py is the only network-capable font path and is never called by an ordinary build.

Icon delivery

templates/gen_logo.py calls templates/iconkit.py only after canonical full and reduced SVG masters exist. A raster-capable build must produce the complete web, Android, iOS and iPadOS, macOS, and Windows suites under icons/; a core build produces the self-contained web SVG index and records why binary suites were skipped. verify.py decodes the images, parses native metadata, checks platform matrices and safe areas, inspects ICO and ICNS entries, rejects undeclared files, and proves every legacy favicons/ alias is byte-identical to its authoritative web target.

Native host role matrix

An asset is qualified for the role and host named below, not for every surface that accepts its file format. Check the application's resource declaration and pinned package bytes separately from the generated kit. A Windows executable may embed classic/app.ico while an MSIX package selects target-size assets; an Android details view may resolve an adaptive resource while an older launcher uses a legacy density PNG. Generated assets do not update an installed application until the consumer repins and rebuilds it.

For Windows taskbar roles, BrandBuilder emits transparent outer pixels by default when the approved logo has no square enclosure. An approved square enclosure retains its plate unless a governed application-icon setting explicitly selects an unplated variant. MSIX scale, tile, and Store roles keep their independent plated compositions. Verify the embedded executable or package resource after repinning; a generated kit cannot prove which resource the application shipped.

For egui, treat status text as text even if its message describes an unavailable action. ui.strong(...) can select the active widget stroke color instead of the ordinary text override; do not use it for a dark-surface status without measuring its effective foreground and local background. A genuinely disabled control is exempt from WCAG 2.1 text contrast, but this project additionally requires its label to remain readable at 4.5:1 while its disabled state stays visually distinct. Enabled text requires 4.5:1 and meaningful control or state cues require 3:1 under WCAG 2.1 contrast minimum and non-text contrast. Render enabled, disabled, hover, focus, and light/dark states in the target egui version; token equality alone is insufficient.

Image generation

For ideation only. Use available image generation to show possible logo directions, mood, and visual language for operator discussion. Treat each image as a nonbinding concept, not as production artwork or approved identity source.

When a tool is missing

A build that silently degrades reads as complete when it is not, and that is the failure mode this whole system exists to prevent.

Platform asset and host checks

The generated Android launcher layers and monochrome treatment have a different job from the Play listing image. Use adaptive icon guidance to review launcher roles and Play icon specifications for the store asset. A host integrating the kit still owns content scaling, system bars, and safe insets; Android layout guidance, system bars, and Compose accessibility provide task-specific checks. The kit does not generate a Compose interface adapter. The same source/host distinction applies to Apple app icon configuration, Windows icon construction, and the web manifest.