Brand DNA

Brand DNA is an open, evidence-aware brand format and context compiler for humans, design systems and AI agents.

One brand-dna.json can describe the complete brand: strategy, worldview, voice, colours, logo, layout, iconography, photography, people, motion, sound, channels, legal constraints, quality rules and the evidence behind each decision. Since v1.1 the same object also carries a rights-aware inventory of the physical logo, icon, image, illustration, texture, motion, audio and template files. A task profile then selects only the relevant parts and turns them into an exhaustive production brief.

Version 1.2 adds an optional, backward-compatible logo-component contract and a separate portable brand-project.json. A v1.2 logo identifies its reusable signet and wordmark independently, then records the approved combined lockups. Existing v1.0 and v1.1 Brand DNA documents remain valid without this field.

brand-dna.json + icon profile       -> detailed icon prompt
brand-dna.json + linkedin profile   -> detailed writing brief
brand-dna.json + photography profile-> detailed casting/camera/light prompt

The complete reference and interactive prompt lab are published at cueqzapper.github.io/brands.

The reference library contains the real SEEZ draft plus three deliberately fictional brands: a neighbourhood bakery, an outdoor-gear repair workshop and an editorial sound studio. Fictional names, domains, organisations, people, products and evidence are labelled as such and must never be presented as real.

Why another brand format?

Open formats already cover important parts:

• Design Tokens type visual values for tools.
• brand.yml gives Quarto, Python and R a portable logo/colour/type source.
• MRBS describes a broad machine-readable brand system.

Brand DNA focuses on the missing runtime question: what is the smallest exact context an agent needs for this production task? It also treats provenance, confidence and unresolved owner decisions as first-class data.

Quick start

Requires Node.js 20 or newer.

npm install
npm test
node src/cli.mjs validate examples/seez/brand-dna.json
node src/cli.mjs compile examples/seez/brand-dna.json \
  --for icon \
  --brief "Create a 24 px icon for an approved handoff"

Try a different category with a complete fictional dataset:

node src/cli.mjs compile examples/fictional/quiet-current/brand-dna.json \
  --for linkedin \
  --brief "Explain why one piece of room sound stayed in a documentary edit"

Available commands:

brand-dna validate brand-dna.json
brand-dna profiles
brand-dna compile brand-dna.json --for photography --brief "..." --locale de-CH
brand-dna compile brand-dna.json --for linkedin --brief "..." --json
brand-dna export brand-dna.json --format brand-yml
brand-dna export brand-dna.json --format tokens-css

The compiler treats meta.defaultLocale as the source language of the Brand DNA. If --locale is omitted, every packet uses that language automatically. Requested output languages are accepted only when they are declared in meta.locales; otherwise the compiler falls back to the brand default instead of silently creating a mixed-language packet. When source and output language differ, the packet names both and requires a faithful translation of approved terms, facts, numbers and legal wording.

The interactive reference follows the same rule: SEEZ opens in de-CH, while the fictional bakery, repair workshop and sound studio open in English. The language selector only shows locales declared by the active Brand DNA.

Task profiles

The v1.1 distribution includes icon, logo, linkedin, photography, photo-graphic, video, brochure, advertising, website and presentation.

A profile is plain JSON:

{
  "id": "icon",
  "selectors": [
    "/brand/essence",
    "/visual/colors",
    "/visual/shapes",
    "/visual/iconography",
    "/assets/basePath",
    "/assets/icons",
    "/rules/accessibility"
  ],
  "instructions": ["Begin with the semantic job."],
  "productionChecklist": ["Meaning is clear at 16 px."],
  "outputContract": ["Positive prompt", "Negative prompt", "SVG spec"]
}

Selectors are JSON Pointers. Compaction is deterministic and inspectable: a photography packet cannot accidentally receive LinkedIn cadence, while an icon packet cannot silently inherit camera or casting rules.

Physical assets

visual describes the rules; assets points to the files that may actually be used. Each file has a role, media type, alternative text, description, licence, rights statement and lifecycle status. Relative paths resolve against assets.basePath.

{
  "assets": {
    "basePath": "./assets/",
    "logos": [{
      "id": "primary-logo",
      "kind": "logo",
      "path": "logos/primary.svg",
      "mediaType": "image/svg+xml",
      "role": "Primary signature",
      "alt": "Brand name",
      "description": "Approved horizontal signature.",
      "licence": "Brand asset licence",
      "rights": "Use only in approved brand productions.",
      "status": "approved"
    }],
    "icons": [], "photography": [], "illustrations": [], "textures": [],
    "motion": [], "audio": [], "templates": []
  }
}

Profiles select only the relevant collections. An icon prompt receives the approved icon masters and logo reference, a photography prompt receives images and textures, while a complete website packet can receive the whole manifest. The repository examples ship the actual files displayed by GitHub Pages.

Portable Brand Projects

brand-project.schema.json is the open handoff between SEEZWeb, Picorn and other editors. It does not copy brand values. Every token and document binding points back to brand-dna.json with an RFC 6901 JSON Pointer, so a changed colour or logo resolves consistently in the website, business card, label and social templates.

{
  "schemaVersion": "1.1.0",
  "brandDna": {
    "path": "./brand-dna.json",
    "mediaType": "application/vnd.cueqzapper.brand-dna+json",
    "schemaVersion": "1.2.0"
  },
  "tokens": {
    "color.primary": {
      "source": { "document": "brand-dna", "pointer": "/visual/colors/palette/0/hex" },
      "valueType": "color",
      "mode": "live"
    }
  },
  "artifacts": []
}

Brand Project 1.1 adds the needs-driven logo-system and cv kinds while the validator continues to accept 1.0 manifests with their original vocabulary. The standard artifact kinds are website, logo-system, business-card, cv, label, social, icon-set, backgrounds, photography and decorative. Each artifact names its portable document, editor surface, Brand DNA bindings, referenced asset IDs, readiness checks and delivery exports. Paths are package-relative. The strict schema deliberately has no credential, API-key, signed-URL or arbitrary metadata fields; secrets belong in the consuming system's protected runtime.

JavaScript consumers can resolve live values without mutating either file:

import { resolveBrandProjectTokens, resolveArtifactBindings } from "@cueqzapper/brands/project";

const tokens = resolveBrandProjectTokens(project, brandDna);
const bindings = resolveArtifactBindings(project, "business-card-main", brandDna);

See the complete portable-brand-project.json, the TypeScript declarations and the project schema.

Evidence states

Every important decision can be linked to sources and marked as:

• declared: stated by an official source;
• observed: visible in an implemented asset or behaviour;
• inferred: a conservative creative interpretation that still needs review;
• owner-approved: explicitly accepted as binding.

Generated Brand DNA should start as draft. Never infer sensitive attributes such as ethnicity, religion, health, sexual orientation or gender identity from public names, faces, locations or industries. Representation can be explicit, but it must be a deliberate editorial or owner-approved decision.

Compatibility

• The root schema uses JSON Schema Draft 2020-12.
• Brand DNA v1.0 and v1.1 documents remain valid under the v1.2 schema.
• Brand Projects use their own 1.0.0 contract and may reference any supported Brand DNA schema version.
• Colour tokens can carry the DTCG $type: "color" marker.
• brand-dna export --format brand-yml creates a conservative Posit _brand.yml starting point.
• brand-dna export --format tokens-css creates semantic CSS variables.

Repository map

schema/       Brand DNA and portable Brand Project JSON Schemas
profiles/     context selectors and production contracts
src/          pure compiler, project resolver, exports and CLI
types/        public TypeScript declarations
examples/     brand references, assets and a portable project manifest
docs/         GitHub Pages reference and prompt lab
test/         validation and context-isolation tests

Contributing

Proposals are welcome. New fields need a concrete production use case, schema documentation and at least one compiler or validation test. See CONTRIBUTING.md.

Licence

Code and schema are MIT licensed. Example brand data and brand assets may carry their own stated rights; do not assume that an open schema makes a trademark or logo free to reuse.