Brand Guidelines Engine

A universal skill for producing, reviewing, and advising on brand-compliant materials across any company. This skill turns a brand configuration file into an active quality gate — every deliverable you produce or review passes through brand rules automatically.

How This Skill Works

The skill operates in three modes depending on what the user needs:

Quick Start

Step 0 — Load or Create Brand Configuration

Every task begins here. Check if a brand-config.json exists in the working directory or in the user's uploaded files.

If config exists: Read it and confirm the brand name with the user.

If config does NOT exist: Ask the user for brand information. They may:

• Upload an existing brand guideline document (PDF, DOCX, PPT, image)
• Describe their brand verbally
• Point to a company website

Then generate the config by running:

python3 <skill-path>/scripts/init_brand_config.py --output brand-config.json

Edit the output JSON to fill in the user's brand details. The config structure covers every aspect of brand identity — see references/brand-config-template.md for the full schema and field-by-field guidance.

Minimum viable config (enough to start producing materials):

{
  "brand_name": "Company Name",
  "colors": {
    "primary": [{"name": "Main", "hex": "#000000"}],
    "accent": [{"name": "Accent", "hex": "#FF6600"}]
  },
  "typography": {
    "heading_font": "Poppins",
    "body_font": "Inter"
  }
}

Even a partial config is useful — the skill will work with whatever is provided and flag gaps when they matter for the specific deliverable.

Mode 1: Configure — Building the Brand Config

When the user provides brand source material (a PDF brand book, a website, verbal descriptions), your job is to extract structured brand data into brand-config.json.

Extraction Workflow

1. Read the source material carefully. For PDFs, extract text; for images, describe visual elements; for websites, note colors, fonts, and layout patterns.

2. Map to the config schema. Walk through each section of references/brand-config-template.md and fill what you can find.

3. Infer what's missing. If a brand guide shows a blue header but doesn't list the hex code, eyeball it or ask the user. If tone-of-voice examples exist but no explicit personality traits are listed, derive them from the examples.

4. Ask to fill gaps. Present the user with a summary of what you found vs. what's still missing. Prioritize gaps that affect near-term deliverables.

5. Validate colors. Run scripts/validate_brand.py --config brand-config.json --check colors to ensure contrast ratios meet WCAG AA for all foreground/background combinations.

6. Save and confirm. Write the final brand-config.json and give the user a visual summary: color swatches (as an HTML or SVG artifact), font hierarchy, and key verbal guidelines.

Mode 2: Produce — Creating Brand-Compliant Deliverables

When a user asks you to create any marketing material, follow this workflow:

Step 1 — Identify the Deliverable Type

Read references/deliverable-specs.md to find the matching deliverable type and its specs. Common types:

Step 2 — Apply Brand Rules

For every deliverable, apply these rules from the brand config:

Visual rules (read references/visual-identity.md for details):

• Colors: Use ONLY colors from the brand palette. Primary color dominates (60-30-10 rule: 60% primary/neutral, 30% secondary, 10% accent).
• Typography: Use only approved fonts at approved sizes. Headings in heading font, body in body font. Never mix unapproved fonts.
• Logo: Follow clear-space rules, minimum size, and approved placement positions. Never stretch, rotate, recolor, or add effects to the logo.
• Imagery: Follow the brand's photography/illustration style. Consistent filters, cropping ratios, and subject matter.
• Layout: Respect the brand's grid system and spacing conventions. Consistent margins and padding across materials.

Verbal rules (read references/tone-of-voice.md for details):

• Tone: Match the brand personality. If the brand is "professional yet approachable", every piece of copy should reflect that balance.
• Terminology: Use preferred terms, avoid deprecated ones. Honor the brand's glossary.
• Messaging hierarchy: Lead with the primary message, support with secondary points. Calls-to-action should use approved language.
• Platform adaptation: The same message gets reshaped for each platform's conventions (LinkedIn is professional; Instagram is visual-first; Twitter is concise).

Step 3 — Size and Format the Output

Consult the size table in references/deliverable-specs.md for exact dimensions, DPI, file format, and bleed requirements. Key principles:

• Digital: RGB color mode, 72-150 DPI, pixel dimensions matter
• Print: CMYK color mode, 300 DPI minimum, add bleed (typically 3mm)
• Social: Each platform has its own image sizes — ALWAYS check the latest specs
• Presentations: 16:9 widescreen (33.87cm x 19.05cm) is default; confirm with user

Step 4 — Quality Gate

Before delivering ANY material, run the brand compliance review:

python3 <skill-path>/scripts/validate_brand.py --config brand-config.json --material <output-file>

Also mentally walk through the checklist in references/review-checklist.md:

• Are all colors from the approved palette?
• Are fonts correct (family, weight, size)?
• Is the logo used correctly (size, spacing, variant)?
• Does the copy match the brand voice?
• Are dimensions correct for the intended platform?
• Is there sufficient contrast for readability?
• Are mandatory legal elements present (copyright, disclaimers)?

Mode 3: Review — Auditing Existing Materials

When a user asks you to review or audit materials for brand compliance:

Review Workflow

1. Load the brand config and understand the full brand system.

2. Examine the material. For images, describe what you see (colors, fonts, layout, logo usage). For documents, read the content. For presentations, check each slide.

3. Score against the checklist. Use references/review-checklist.md and score each category (Visual Identity, Typography, Color, Logo, Imagery, Copy, Format).

4. Generate a compliance report with this structure:

   # Brand Compliance Report — [Material Name]
   
   ## Overall Score: X/100
   
   ## Summary
   One-paragraph overview of compliance level.
   
   ## Findings
   
   ### Passes (what's correct)
   - ...
   
   ### Issues (what needs fixing)
   For each issue:
   - **What**: Description of the violation
   - **Where**: Location in the material
   - **Rule**: Which brand guideline it violates
   - **Fix**: Specific recommended correction
   
   ## Recommendations
   Prioritized list of improvements.