Skip to content

Commit e81235c

Browse files
bokelleyclaude
bokelley
and
claude
authored
feat(brand-manifest): Add structured tone and standardized logo tags (#945) (#948)
* feat(brand-manifest): Add structured tone guidelines and standardized logo tags Update Brand Manifest schema to support detailed creative guidance: - Tone field now supports both simple string (backward compatible) and structured object with voice, attributes, dos, and donts fields - Added 'usage' field to logo objects for human-readable descriptions - Documented standardized logo tag vocabulary for background compatibility, orientation, and usage context These changes enable creative agents to: - Generate brand-compliant copy programmatically - Select appropriate logo variants for different contexts - Automate brand guideline compliance without human review Closes #945 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(brand-manifest): Correct logo tag semantics in examples Fix inconsistency between logo tags and usage descriptions: - `light-bg` = use on light backgrounds - `dark-bg` = use on dark backgrounds Renamed example files from `logo-dark/logo-light` to `logo-on-light/logo-on-dark` to make the intent clearer. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(brand-manifest): Add structured logo fields (orientation, background, variant) Replace free-form tags with validated enum fields for logo selection: - orientation: square, horizontal, vertical, stacked - background: dark-bg, light-bg, transparent-bg - variant: primary, secondary, icon, wordmark, full-lockup The tags array is retained for additional custom categorization. These structured fields enable reliable filtering by creative agents. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(brand-manifest): Make tone object-only (breaking change) Remove string variant from tone field. Existing string values should migrate to { "voice": "<previous-string>" }. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent e84aafd commit e81235c

3 files changed

Lines changed: 324 additions & 42 deletions

File tree

‎.changeset/brand-manifest-tone-logos.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
"adcontextprotocol": major
3+
---
4+
5+
Add structured tone guidelines and structured logo fields to Brand Manifest schema.
6+
7+
**BREAKING: Tone field changes:**
8+
- Tone is now an object type only (string format removed)
9+
- Structured tone includes `voice`, `attributes`, `dos`, and `donts` fields
10+
- Existing string values should migrate to `{ "voice": "<previous-string>" }`
11+
- Enables creative agents to generate brand-compliant copy programmatically
12+
13+
**Logo object changes:**
14+
- Added `orientation` enum field: `square`, `horizontal`, `vertical`, `stacked`
15+
- Added `background` enum field: `dark-bg`, `light-bg`, `transparent-bg`
16+
- Added `variant` enum field: `primary`, `secondary`, `icon`, `wordmark`, `full-lockup`
17+
- Added `usage` field for human-readable descriptions
18+
- Kept `tags` array for additional custom categorization
19+
20+
These structured fields enable creative agents to reliably filter and select appropriate logo variants.
21+
22+
Closes #945

‎docs/creative/brand-manifest.mdx‎

Lines changed: 209 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -128,16 +128,31 @@ For established brands with defined guidelines, host the manifest on a CDN:
128128
"name": "ACME Corporation",
129129
"logos": [
130130
{
131-
"url": "https://cdn.acmecorp.com/logo-square-dark.png",
132-
"tags": ["dark", "square"],
133-
"width": 512,
134-
"height": 512
131+
"url": "https://cdn.acmecorp.com/logo-on-light.png",
132+
"orientation": "horizontal",
133+
"background": "light-bg",
134+
"variant": "primary",
135+
"usage": "Primary logo for use on light backgrounds",
136+
"width": 1200,
137+
"height": 400
135138
},
136139
{
137-
"url": "https://cdn.acmecorp.com/logo-horizontal-light.png",
138-
"tags": ["light", "horizontal"],
140+
"url": "https://cdn.acmecorp.com/logo-on-dark.png",
141+
"orientation": "horizontal",
142+
"background": "dark-bg",
143+
"variant": "primary",
144+
"usage": "Primary logo for use on dark backgrounds",
139145
"width": 1200,
140146
"height": 400
147+
},
148+
{
149+
"url": "https://cdn.acmecorp.com/icon.png",
150+
"orientation": "square",
151+
"background": "transparent-bg",
152+
"variant": "icon",
153+
"usage": "Icon-only variant for small formats",
154+
"width": 512,
155+
"height": 512
141156
}
142157
],
143158
"colors": {
@@ -151,7 +166,20 @@ For established brands with defined guidelines, host the manifest on a CDN:
151166
"primary": "Helvetica Neue",
152167
"secondary": "Georgia"
153168
},
154-
"tone": "professional and trustworthy",
169+
"tone": {
170+
"voice": "professional and trustworthy",
171+
"attributes": ["confident", "innovative", "approachable"],
172+
"dos": [
173+
"Use clear, direct language",
174+
"Highlight innovation and reliability",
175+
"Address decision-makers directly"
176+
],
177+
"donts": [
178+
"Avoid hyperbole or exaggeration",
179+
"Don't use overly casual language",
180+
"Don't make unsubstantiated claims"
181+
]
182+
},
155183
"tagline": "Innovation You Can Trust",
156184
"product_catalog": {
157185
"feed_url": "https://acmecorp.com/products.rss",
@@ -204,7 +232,7 @@ Some brands don't have dedicated URLs (white-label products, local businesses, B
204232
"primary": "#0071CE",
205233
"secondary": "#FFC220"
206234
},
207-
"tone": "affordable and trustworthy"
235+
"tone": { "voice": "affordable and trustworthy" }
208236
}
209237
```
210238

@@ -248,7 +276,7 @@ The structure of the brand manifest object itself (whether provided inline or ho
248276
| `logos` | Logo[] | Brand logo assets with semantic tags |
249277
| `colors` | Colors | Brand color palette (hex format) |
250278
| `fonts` | Fonts | Brand typography guidelines |
251-
| `tone` | string | Brand voice and messaging tone |
279+
| `tone` | ToneObject | Brand voice and messaging tone guidelines |
252280
| `tagline` | string | Brand tagline or slogan |
253281
| `assets` | Asset[] | Brand asset library with explicit assets and tags |
254282
| `product_catalog` | ProductCatalog | Product catalog information for e-commerce advertisers |
@@ -262,14 +290,140 @@ The structure of the brand manifest object itself (whether provided inline or ho
262290

263291
```typescript
264292
{
265-
url: string; // URL to logo asset
266-
tags?: string[]; // Semantic tags (e.g., "dark", "light", "square", "horizontal")
267-
width?: number; // Logo width in pixels
268-
height?: number; // Logo height in pixels
293+
url: string; // URL to logo asset
294+
orientation?: Orientation; // Aspect ratio: square, horizontal, vertical, stacked
295+
background?: Background; // Compatibility: dark-bg, light-bg, transparent-bg
296+
variant?: Variant; // Type: primary, secondary, icon, wordmark, full-lockup
297+
tags?: string[]; // Additional custom tags
298+
usage?: string; // Human-readable description
299+
width?: number; // Logo width in pixels
300+
height?: number; // Logo height in pixels
269301
}
270302
```
271303

272-
**Common Tags**: `"dark"`, `"light"`, `"square"`, `"horizontal"`, `"vertical"`, `"icon"`, `"wordmark"`, `"lockup"`
304+
#### Logo Fields
305+
306+
**`orientation`** (enum) - Logo aspect ratio:
307+
| Value | Description |
308+
|-------|-------------|
309+
| `square` | Square or circular lockup (~1:1 aspect ratio) |
310+
| `horizontal` | Wide horizontal layout |
311+
| `vertical` | Tall vertical layout |
312+
| `stacked` | Vertically stacked elements |
313+
314+
**`background`** (enum) - Background compatibility:
315+
| Value | Description |
316+
|-------|-------------|
317+
| `dark-bg` | Use on dark backgrounds (logo is light-colored) |
318+
| `light-bg` | Use on light backgrounds (logo is dark-colored) |
319+
| `transparent-bg` | Has transparent background, works on any color |
320+
321+
**`variant`** (enum) - Logo variant type:
322+
| Value | Description |
323+
|-------|-------------|
324+
| `primary` | Main brand logo |
325+
| `secondary` | Alternative version |
326+
| `icon` | Icon/symbol only |
327+
| `wordmark` | Text/wordmark only |
328+
| `full-lockup` | Complete logo with all elements |
329+
330+
**`tags`** (string array) - Additional custom tags for categorization beyond the standard fields.
331+
332+
#### Logo Example
333+
334+
```json
335+
{
336+
"logos": [
337+
{
338+
"url": "https://cdn.brand.com/logo-on-light.png",
339+
"orientation": "horizontal",
340+
"background": "light-bg",
341+
"variant": "primary",
342+
"usage": "Primary logo for use on light backgrounds",
343+
"width": 1200,
344+
"height": 400
345+
},
346+
{
347+
"url": "https://cdn.brand.com/logo-on-dark.png",
348+
"orientation": "horizontal",
349+
"background": "dark-bg",
350+
"variant": "primary",
351+
"usage": "Primary logo for use on dark backgrounds",
352+
"width": 1200,
353+
"height": 400
354+
},
355+
{
356+
"url": "https://cdn.brand.com/icon.png",
357+
"orientation": "square",
358+
"background": "transparent-bg",
359+
"variant": "icon",
360+
"usage": "Icon-only variant for small formats",
361+
"width": 512,
362+
"height": 512
363+
}
364+
]
365+
}
366+
```
367+
368+
### Tone Object
369+
370+
The `tone` field provides structured voice guidelines for creative agents.
371+
372+
```typescript
373+
{
374+
voice?: string; // High-level voice descriptor (the what)
375+
attributes?: string[]; // Personality traits (the character)
376+
dos?: string[]; // Specific guidance for copy generation (the how)
377+
donts?: string[]; // Guardrails to avoid brand violations (the boundaries)
378+
}
379+
```
380+
381+
#### Tone Fields
382+
383+
| Field | Type | Description |
384+
|-------|------|-------------|
385+
| `voice` | string | High-level voice descriptor (e.g., "warm and inviting") |
386+
| `attributes` | string[] | Personality traits that characterize the brand |
387+
| `dos` | string[] | Specific guidance for copy generation |
388+
| `donts` | string[] | Guardrails to avoid brand violations |
389+
390+
#### Tone Example
391+
392+
**Minimal tone** (just voice):
393+
```json
394+
{
395+
"tone": {
396+
"voice": "professional and trustworthy"
397+
}
398+
}
399+
```
400+
401+
**Full tone with guidance**:
402+
```json
403+
{
404+
"tone": {
405+
"voice": "warm and inviting",
406+
"attributes": ["friendly", "optimistic", "conversational", "authentic"],
407+
"dos": [
408+
"Use simple, everyday language",
409+
"Address the reader directly",
410+
"Show empathy and understanding",
411+
"Keep sentences short and punchy"
412+
],
413+
"donts": [
414+
"Avoid corporate jargon",
415+
"Don't be overly formal or stiff",
416+
"Avoid technical terms unless necessary",
417+
"Don't make exaggerated claims"
418+
]
419+
}
420+
}
421+
```
422+
423+
The structured tone format enables creative agents to:
424+
- Generate brand-compliant copy by following specific dos/donts
425+
- Apply consistent voice across different creative formats
426+
- Automate brand guideline compliance without human review
273427

274428
### Colors Object
275429

@@ -358,7 +512,7 @@ Include brand manifest in media buy creation to provide context for creative gen
358512
"brand_manifest": {
359513
"url": "https://acmecorp.com",
360514
"name": "ACME Corporation",
361-
"tone": "professional and innovative"
515+
"tone": { "voice": "professional and innovative" }
362516
},
363517
"packages": [...],
364518
"budget": {...}
@@ -381,14 +535,21 @@ Use brand manifest to inform creative generation:
381535
"logos": [
382536
{
383537
"url": "https://cdn.acmecorp.com/logo-square.png",
384-
"tags": ["square", "dark"]
538+
"orientation": "square",
539+
"background": "transparent-bg",
540+
"variant": "primary",
541+
"usage": "Primary square logo"
385542
}
386543
],
387544
"colors": {
388545
"primary": "#FF6B35",
389546
"secondary": "#004E89"
390547
},
391-
"tone": "professional and trustworthy"
548+
"tone": {
549+
"voice": "professional and trustworthy",
550+
"dos": ["Highlight innovation", "Use clear language"],
551+
"donts": ["Avoid hyperbole"]
552+
}
392553
}
393554
}
394555
```
@@ -413,21 +574,45 @@ Begin with just a URL. Add more fields only when the URL-based inference isn't s
413574
}
414575
```
415576

416-
### 2. Use Semantic Tags for Logos
577+
### 2. Use Structured Fields for Logos
417578

418-
Tags help creative agents select appropriate logo variants:
579+
Use the `orientation`, `background`, and `variant` enum fields for reliable filtering by creative agents:
419580

420581
```json
421582
{
422583
"logos": [
423-
{"url": "...", "tags": ["dark", "square"]}, // For light backgrounds
424-
{"url": "...", "tags": ["light", "square"]}, // For dark backgrounds
425-
{"url": "...", "tags": ["dark", "horizontal"]}, // Wide layouts
426-
{"url": "...", "tags": ["icon"]} // Small placements
584+
{
585+
"url": "...",
586+
"orientation": "horizontal",
587+
"background": "light-bg",
588+
"variant": "primary",
589+
"usage": "Primary logo for light backgrounds"
590+
},
591+
{
592+
"url": "...",
593+
"orientation": "horizontal",
594+
"background": "dark-bg",
595+
"variant": "primary",
596+
"usage": "Primary logo for dark backgrounds"
597+
},
598+
{
599+
"url": "...",
600+
"orientation": "square",
601+
"background": "transparent-bg",
602+
"variant": "icon",
603+
"usage": "Icon for small placements"
604+
}
427605
]
428606
}
429607
```
430608

609+
**Enum fields for filtering:**
610+
- `orientation`: `square`, `horizontal`, `vertical`, `stacked`
611+
- `background`: `dark-bg`, `light-bg`, `transparent-bg`
612+
- `variant`: `primary`, `secondary`, `icon`, `wordmark`, `full-lockup`
613+
614+
Use the `tags` array for additional custom categorization.
615+
431616
### 3. Cache and Reuse Brand Manifests
432617

433618
Brand cards are designed to be cached. Use URL strings for automatic caching:
@@ -632,7 +817,7 @@ For implementations using the legacy `brand_guidelines` field in `build_creative
632817
"fonts": {
633818
"primary": "Helvetica Neue"
634819
},
635-
"tone": "professional"
820+
"tone": { "voice": "professional" }
636821
}
637822
}
638823
```

0 commit comments

Comments
 (0)