BRAND.md Generator
Create or update BRAND.md at spec version 0.3.0. The format and section
requirements are defined in spec/brand-md.md.
BRAND.md owns identity that should survive a complete visual redesign.
DESIGN.md owns how that identity is applied to a particular surface. Never put
ramps, semantic roles, type scales, spacing, layout, components, or motion in
BRAND.md.
Workflow
1. Resolve existing context
Walk from the working directory to the project root and read every applicable
BRAND.md, root to leaf. Accept a legacy lowercase brand.md only when no
BRAND.md exists in the same directory. Compare exact directory entry names;
two successful path probes may still refer to one file on a case-insensitive file
system. If both spellings are distinct entries, report the conflict and stop. For
a child brand, write only sections that differ from the effective parent.
Ask which architecture applies: branded-house, endorsed, sub-brand, or
independent. Guardrails inherit unless the child is independent; inherited
guardrails may be tightened but not loosened. Accessibility commitments always
inherit and may only be raised.
Discover nearby DESIGN.md paths, skipping generated and dependency directories.
Read and attribute them only when materially updating a brand, checking alignment,
or performing the design handoff. A design belongs to this brand when its brand
frontmatter resolves to this file. Treat location-based attribution as an
inference.
2. Gather evidence
Research only what is missing. Relevant sources may include the product, direct competitors, audience discussions, reviews, and references outside the category. Use enough evidence to understand the category, audience, competitive pattern, and credible whitespace. Do not satisfy a fixed search quota.
Derive what the evidence supports. Ask only unresolved decisions, propose useful defaults, skip inherited or irrelevant sections, and ask in small clusters. Never invent approved claims, verified licenses, or approved colors.
At minimum, resolve:
- the brand, product, audience, category, and relationship to any parent;
- positioning, explicit negations, personality, references, and anti-references;
- voice, messaging, and identity guardrails;
- approved identity colors, typefaces, logo rules, and art direction;
- any established naming, claims, or accessibility commitments.
For each reference, record the trait to borrow and the trait not to copy. Ask about identity primitives, not design-system roles or styling.
3. Generate the brand file
Write specVersion: "0.3.0" and follow the spec. The required shape is:
textStrategy: Overview, Audience, Positioning, Personality, References & Anti-References, Promise, Guardrails Voice: Identity, Tagline & Slogans, Message Pillars, Phrases, Tonal Rules Visual: Core Colors, Typefaces, Art Direction
Optional sections are Manifesto, Vocabulary, Social Bios, Logo & Marks, Photography & Illustration, and the Governance layer with Naming, Claims, and Accessibility Commitments.
Keep identity primitives narrow:
- Core Colors contain 2 to 5 approved colors with exact values, meaning, and mandatory or optional status, never surface roles.
- Typefaces contain families, roles, and fallbacks, not a scale. Mark licensing verified only when it was checked.
- Art Direction names a concrete visual territory, not a list of adjectives.
- Claims distinguish approved, evidenced claims from draft candidates.
Use examples/marginalia/BRAND.md when a
complete example is useful.
4. Hand off to design only when requested
After the user confirms the brand, offer a DESIGN.md for a named surface. If they
accept, read and follow
references/design-md-handoff.md. Otherwise
stop. Never add applied design recommendations to BRAND.md as a substitute.
5. Report possible downstream drift
After a material brand update, report linked or inferred DESIGN.md files that may
need review and describe the potential conflict. Do not edit them unless the user
requests the design handoff. This is a review convention, not an automated check.
Non-negotiable checks
- The output follows the specification and contains no generic filler.
- Positioning is grounded in evidence and includes explicit negations.
- Phrases are ownable; replacing the brand name with a competitor should break them.
- Tonal rules are usable instructions, and guardrails give a practical litmus test.
- No applied tokens, roles, components, or motion appear in
BRAND.md. - No brand-to-design conflict is silently resolved.
