A project's visual identity is declared once and generated: the contract and the generator are the protocol's, the identity is the project's
Accepted
Context
SpecDossier and Signatio each carried a logo generator beside their assets (tools/*-brand, Rust), a contract compiled into it, and a drift script (scripts/brand.nu). The two copies had already diverged before either shipped — Signatio's lockup measured `gap` to the word's origin with no left pad, SpecDossier's `gap_ratio` to the word's ink, with a pair kern Signatio's lacked — and ontoref itself had hand-drawn logos and a hand-written branding index. Every project that wanted the same management would have copied the tool a third time.
On 2026-09-27 (SOW wo-visual-identity-capability-v2, 14/14 contracts witnessed, receipt signed) the capability became the protocol's: code/ontology/schemas/branding.ncl (BrandingSettings, Style, Brand), the ontoref-brand generator installed beside the CLI, `ontoref visual …` / `ontoref logo`, the visual-identity mode, two qa howtos and migration 0107. Measured: one generator, knowing no mark's geometry, regenerated both committed sets byte for byte (32/32) and SpecDossier's image anchors; the three conventions that differed became declarable layout fields (lockup.pad_start, wordmark.frame, mark.frame) instead of being absorbed. ontoref's own mark — a polyhedron with strokes, clips, gradients and looping motion — could not be expressed as flat parts, which is why a mark has two kinds.
Decision
A PROJECT'S VISUAL IDENTITY IS DECLARED ONCE AND GENERATED. `branding` in .ontoref/config.ncl says where it lives. The project holds only its identity — brand.ncl, visual/style.ncl and the fonts they name — and every SVG, the branding index and the image anchors are generated from it by the protocol's ontoref-brand under the shipped contract, imported where it is installed and never compiled into the tool (adr-108). `ontoref visual check` is the witness of that generated tree (adr-070): it regenerates into scratch and fails on any output, index or anchor out of step. A mark is 'Parts — path data the project derives in its own Nickel, where the relations only that mark has are checked — or 'Authored — its SVG is the authority, composed around and never redrawn. Validators enforce shape, the legibility thresholds the project declares, and drift; they never choose. Concept, palette, face and image registers are the principal's (Human steps of the visual-identity mode). Opt-in: a project that declares no `branding` is not bound.
Constraints
- Hard ontoref-brand applies the installed branding.ncl; its sources embed no copy of the contract.
- Hard `ontoref visual check` passes a clean generation and fails, naming the file, on an edited output, a stale file and a drifted anchor; a project without `branding` passes.
- Hard In the visual-identity mode, choose-concept, choose-palette, choose-face and choose-registers are Human steps.
Alternatives considered
- Per-project generators over a shared library — rejected: Each project still builds, versions and updates a tool; the drift observed between the two existing generators is the cost of that shape.
- One generic mark model (rich parts: strokes, clips, gradients, looping motion) — rejected: A contract sized by its most complex case, drawn from a single mark; the 'Authored kind keeps the common case small and lets a complex mark stay its SVG.
- A contract that absorbs each generator's conventions silently — rejected: Two generators that 'do the same' differed in layout conventions; absorbing them makes a byte change of a committed set a hidden policy. They are declared fields (pad_start, frame) that a project states and a reader can see.
Anti-patterns
- A generator beside the assets — A project copies the generator, the contract or a drift script into its own tree, and the copies drift from the protocol's and from each other.
- Taste by validator — A check refuses a palette, a face or a concept for being unlike the one someone prefers, instead of for failing a threshold the project declared.
- Redrawing an authored mark — A mark whose nature is not flat paths is approximated into parts to fit the generator, and the approximation replaces the authority.
Perspectives