# Bobby Directory Brand Book

Version 1.0.0. Phase 0 deliverable. Governance 1.0.0, effective 2026-08-23, section 26.

Selected identity: Bracket Index A2, approved by the Owner.

Status: this brand book and the asset suite under `docs/brand/assets/` are documentation and design artefacts only. Nothing in this book has been applied to the running product. The application favicon, metadata, styles, tokens and routes are unchanged.

No em dash character is used anywhere in this document or in any Bobby Directory content.

---

## 1. Brand positioning

### 1.1 What Bobby Directory is

Bobby Directory is a platform for building, operating and publishing structured directories. A directory is a governed collection of records of one declared type, described by typed fields, organised by categories and facets, and reachable through a public website, an API and an MCP endpoint.

The product serves three audiences at once:

1. Directory operators, who create a directory, define its fields, import records, review submissions and publish.
2. Directory visitors, who search, filter and read published records.
3. Developers and agents, who read the same published data through the API and MCP surfaces under the same permissions.

The positioning in one line: structured directories with an API.

The brand promise is legibility. Every record has a declared shape, every field has a declared type, every change has an actor and a timestamp, and every surface reads from the same governed source.

### 1.2 What Bobby Directory is not

- It is not a social network. There is no feed, no follower graph and no engagement mechanic.
- It is not a review platform. Ratings, if ever introduced, are a directory-level option and never the brand's centre.
- It is not a scraper or a data broker. Bobby Directory does not sell record subjects as a product, and it does not present imported data as if it were verified by the platform.
- It is not a general purpose CMS or website builder.
- It is not a marketplace, a payments product or a wallet. Bobby Directory belongs to the wider Bobby family but is a separate product from Bobby Wallet, shares no code, no accounts and no data with it by default, and must never be described as part of it.
- It is not an AI product. AI features may assist import mapping and search, and they are described as assistance, never as authority.

### 1.3 The idea behind the mark

The mark is an open square bracket holding two rounded counters. The bracket is the container, which is the directory. The two counters are records inside it, stacked as rows. The open right side says the container is extensible, that more records fit. The upper counter is ink and the lower counter is accent, which reads as two states of the same record type, for example draft and published.

The device is deliberately technical rather than decorative, because the product is consumed as much by API and MCP clients as by human visitors.

---

## 2. Logo system

### 2.1 Construction

The symbol is drawn on a 64 by 64 unit frame.

| Element | Geometry |
| --- | --- |
| Bracket | Path from 26,12 to 15,12, corner radius 3, down to 15,49, corner radius 3, out to 26,52. Stroke 6 units, round caps, ink colour. |
| Upper counter | Rectangle 32,11.5, 21 wide, 18.5 tall, corner radius 5, ink colour. |
| Lower counter | Rectangle 32,33.5, 21 wide, 18.5 tall, corner radius 5, accent colour. |
| Optical centre | The combined bounding box is 12,9 to 53,55. The mark is centred on that box, not on the stroke path. |

Three geometries exist. They are not interchangeable.

| Geometry | Frame | Use |
| --- | --- | --- |
| Full | 64 units | 48 px and above, all print, all lockups |
| Simplified | 64 units, stroke 7, radius 4, butt caps | 20 px to 48 px, receipts, thermal printing, low ink |
| Micro | 16 units, every edge on an integer boundary | 16 px and 32 px favicons, dense interface rows |

The micro geometry is a redrawn mark, not a scaled copy. Do not scale the full mark to 16 px.

### 2.2 Lockups

| Lockup | Composition | Primary use |
| --- | --- | --- |
| Standalone beeldmerk | Symbol only | App icons, avatars, favicons, dense interface |
| Horizontal | Symbol left, Bobby over DIRECTORY right | Site header, email header, invoices, wide covers |
| Stacked | Symbol above centred Bobby over DIRECTORY | Square and portrait spaces, covers, splash |
| Wordmark, two line | Bobby over DIRECTORY, no symbol | Documents where the symbol appears elsewhere |
| Wordmark, inline | Bobby DIRECTORY on one line | Very short, very wide spaces, footers |

The mixed case lockup, Bobby with uppercase DIRECTORY, is the primary. The uppercase lockup, BOBBY with uppercase DIRECTORY, is a documented alternate. It is permitted only where the mark sits inside dense uppercase interface labels and mixed case would look inconsistent. It is never used on the website header, the app icon, invoices, email headers or social profiles.

### 2.3 Colour variants

| Variant | Ink | Accent | Field |
| --- | --- | --- | --- |
| Full colour, light | `#101828` | `#C2440A` | White or light surface |
| Full colour, dark | `#F2F4F7` | `#FFB066` | Dark ground `#0D1117` |
| One colour black | `#101828` | `#101828` | Light only |
| One colour white | `#FFFFFF` | `#FFFFFF` | Dark or photographic only |
| Grayscale | `#1F2937` | `#5A6472` | Light only, print |
| Pure black | `#000000` | `#000000` | Thermal, fax, single ink print |

Every variant exists with a transparent background, and the two full colour variants also exist with a baked light or dark field for contexts that cannot guarantee the background.

### 2.4 Clear space

Clear space is defined as `x`, where `x` is one quarter of the symbol height in the asset being used.

- Standalone symbol: `x` on all four sides.
- Horizontal and stacked lockups: `x` on all four sides, measured from the outer bounding box of the composition, not from the canvas edge.
- No other logo, wordmark, rule, photograph edge or interface control may enter the clear space.
- The exported SVG lockups already carry roughly `1.4x` of internal padding. When placing the SVG directly, the padding present in the file counts toward clear space.

### 2.5 Minimum sizes

| Asset | Minimum | Geometry to use |
| --- | --- | --- |
| Symbol, screen | 16 px | Micro |
| Symbol, screen | 20 px to 47 px | Simplified |
| Symbol, screen | 48 px and above | Full |
| Symbol, print | 6 mm | Full, or simplified below 8 mm |
| Horizontal lockup, screen | 120 px wide | Full |
| Horizontal lockup, print | 28 mm wide | Full |
| Stacked lockup, screen | 96 px wide | Full |
| Wordmark only, screen | 96 px wide | Full |

### 2.6 Background and contrast rules

- On white and on light surfaces up to `#F4F5F7`, use the full colour light variant.
- On the dark ground `#0D1117` and on dark surfaces up to `#161B22`, use the full colour dark variant. Never place the light accent `#C2440A` on the dark ground, it measures 3.72 to 1 and fails AA.
- On any tint between those two ranges, on photographs, or on an uncontrolled background, use the one colour white or one colour black variant, or place the mark on a solid field of the brand ground.
- On coloured brand-adjacent fields, only the one colour variants are permitted.
- Never place the mark on a background that shares the accent hue family.

Recorded contrast ratios, computed against WCAG 2.1 relative luminance:

| Foreground | Background | Ratio | Verdict |
| --- | --- | --- | --- |
| `#C2440A` | `#FFFFFF` | 5.09 | AA for text, AA large, pass |
| `#C2440A` | `#F4F5F7` | 4.67 | AA for text, pass |
| `#C2440A` | `#0D1117` | 3.72 | Fail for text, prohibited |
| `#101828` | `#FFFFFF` | 17.75 | AAA |
| `#101828` | `#F4F5F7` | 16.27 | AAA |
| `#FFB066` | `#0D1117` | 10.50 | AAA |
| `#FFB066` | `#161B22` | 9.60 | AAA |
| `#F2F4F7` | `#0D1117` | 17.18 | AAA |
| `#FFFFFF` | `#0D1117` | 18.92 | AAA |
| `#1F2937` | `#FFFFFF` | 14.68 | AAA, grayscale ink |
| `#5A6472` | `#FFFFFF` | 6.00 | AA, grayscale accent |
| `#000000` | `#FFFFFF` | 21.00 | AAA, pure monochrome |

### 2.7 Correct usage

- Use the supplied files. Always.
- Choose the geometry that matches the rendered size, not the geometry that is convenient.
- Keep the symbol and the wordmark in their supplied relationship.
- Use the mixed case lockup unless a documented exception applies.
- Give the mark a solid, quiet field.
- Provide alt text on every logo image. Default alt text: `Bobby Directory`. When the logo is a link to the home page, use `Bobby Directory home`. When the logo is decorative and the brand name is already in adjacent text, use an empty alt attribute.

### 2.8 Incorrect usage

Never do any of the following.

1. Recolour the mark outside the approved variants, including brand-adjacent oranges.
2. Apply a gradient, glow, drop shadow, bevel, outline or texture.
3. Rotate, skew, mirror, stretch or condense the mark.
4. Rebuild, retrace or approximate the geometry.
5. Change the gap between the counters, close the bracket, or add a third counter.
6. Set the wordmark in another typeface, or restore the tracking and weight that were changed in round A2.
7. Place the wordmark above the symbol in the horizontal lockup, or beside it in the stacked lockup.
8. Scale the full geometry below its minimum instead of switching to simplified or micro.
9. Place the mark on a busy photograph without a solid field.
10. Use the light accent on the dark ground.
11. Enclose the mark in a shape that is not one of the supplied app icon or avatar fields.
12. Use the uppercase alternate as the primary logo.
13. Combine the mark with another logo without the required clear space and a separating rule.
14. Animate the mark in a way that deforms it. Fade and position moves are permitted, morphs are not.

---

## 3. Colour palette

### 3.1 Core

| Token | Value | Role |
| --- | --- | --- |
| Ink | `#101828` | Primary foreground on light, logo ink |
| Ground light | `#FFFFFF` | Primary light background |
| Surface light | `#F4F5F7` | Cards and raised light surfaces |
| Accent | `#C2440A` | Primary accent on light |
| Ground dark | `#0D1117` | Primary dark background |
| Surface dark | `#161B22` | Cards and raised dark surfaces |
| Foreground dark | `#F2F4F7` | Primary foreground on dark |
| Accent dark | `#FFB066` | Primary accent on dark, dark mode only |

### 3.2 Accent tints

Tints are for fills, chips, borders and charts. They are never used for body text unless the recorded ratio allows it.

| Tint | Value | Ratio on white | Permitted use |
| --- | --- | --- | --- |
| Accent 50 | `#FDF3EC` | 1.09 | Chip and banner fill |
| Accent 100 | `#FADFCB` | 1.27 | Fill, hover fill |
| Accent 200 | `#F3BF9A` | 1.65 | Border, chart series |
| Accent 300 | `#E79761` | 2.33 | Chart series, illustration |
| Accent 400 | `#D66A2A` | 3.53 | Large graphic only, never text |
| Accent 500 | `#C2440A` | 5.09 | Primary accent, text permitted |
| Accent 600 | `#A03707` | 6.90 | Hover and pressed states |
| Accent 700 | `#7C2A05` | 9.59 | Active, focus ring on light |

### 3.3 Neutrals

| Token | Value | Ratio on white |
| --- | --- | --- |
| Neutral 900 | `#101828` | 17.75 |
| Neutral 800 | `#1F2937` | 14.68 |
| Neutral 700 | `#374151` | 10.31 |
| Neutral 600 | `#5A6472` | 6.00 |
| Neutral 500 | `#767F8C` | 4.05 |
| Neutral 300 | `#C3C8D0` | 1.68 |
| Neutral 200 | `#E3E6EA` | 1.25 |
| Neutral 100 | `#F4F5F7` | 1.09 |

Neutral 500 measures 4.05 on white, below 4.5, and is permitted only for large text, borders and disabled states.

### 3.4 Semantic colours

The accent sits close to the warning family, so the warning token is deliberately pushed toward yellow to stay distinguishable from the accent.

| Semantic | Light value | On white | Dark value | On `#0D1117` | Meaning in product |
| --- | --- | --- | --- | --- | --- |
| Success | `#136F3B` | 6.24 | `#5FD08A` | 9.80 | Published, import succeeded |
| Warning | `#8A6100` | 5.54 | `#F5CB5C` | 12.24 | Needs review, quota near limit |
| Danger | `#B42318` | 6.57 | `#FF9C93` | 9.40 | Rejected, destructive action, failed import |
| Info | `#175CD3` | 5.99 | `#84ADFF` | 8.47 | Neutral system notice |
| Draft | `#5A6472` | 6.00 | `#98A2B3` | 7.35 | Unpublished record state |

Colour is never the only signal. Every state carries a text label and, where relevant, an icon.

---

## 4. Typography

### 4.1 Typefaces

| Role | Family | Fallback stack |
| --- | --- | --- |
| Brand and headings | Space Grotesk | `"Space Grotesk", "Inter", "Segoe UI", system-ui, -apple-system, "Helvetica Neue", Arial, sans-serif` |
| Interface and body | Inter | `"Inter", "Segoe UI", system-ui, -apple-system, "Helvetica Neue", Arial, sans-serif` |
| Code, identifiers, field keys | JetBrains Mono | `"JetBrains Mono", "SFMono-Regular", Consolas, "Liberation Mono", monospace` |
| Email | System stack only | `-apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif` |

Email templates never rely on a webfont. Print documents embed the font or use outlines.

### 4.2 Wordmark typography, locked

These values are part of the logo and are not editable.

| Element | Family | Weight | Size relation | Tracking |
| --- | --- | --- | --- | --- |
| Bobby | Space Grotesk | 700 | Base | -0.022 em |
| DIRECTORY | Space Grotesk | 600 | 0.70 of base | 2.3 at 19 px, that is 0.121 em |
| BOBBY, alternate | Space Grotesk | 700 | Base | 0.02 em |

All supplied logo SVG files carry the wordmark as outlines, so no font is required to render them.

### 4.3 Hierarchy

| Level | Family | Size, desktop | Weight | Tracking | Line height |
| --- | --- | --- | --- | --- | --- |
| Display | Space Grotesk | 56 px | 700 | -0.02 em | 1.05 |
| H1 | Space Grotesk | 40 px | 700 | -0.018 em | 1.12 |
| H2 | Space Grotesk | 30 px | 600 | -0.014 em | 1.18 |
| H3 | Space Grotesk | 22 px | 600 | -0.01 em | 1.25 |
| Body large | Inter | 18 px | 400 | 0 | 1.6 |
| Body | Inter | 16 px | 400 | 0 | 1.6 |
| Small | Inter | 14 px | 400 | 0 | 1.55 |
| Label | Inter | 12 px | 600 | 0.06 em, uppercase | 1.4 |
| Code | JetBrains Mono | 14 px | 400 | 0 | 1.55 |

Minimum body size is 16 px on the public site and 14 px in dense console tables. Never set body text below 14 px anywhere.

---

## 5. Tone of voice

### 5.1 Principles

1. Plain. Short sentences. One idea per sentence.
2. Precise. Name the object, the actor and the state.
3. Calm. No urgency theatre, no exclamation marks in product copy.
4. Honest about provenance. Say where data came from and who published it.
5. Second person for the reader, first person plural only for platform commitments.

### 5.2 Preferred vocabulary

| Use | Instead of |
| --- | --- |
| Directory | Site, listing site |
| Record | Entry, item, thing, listing |
| Field | Attribute, property, column |
| Category | Tag group, section |
| Facet | Filter group |
| Import | Upload, ingest, sync |
| Mapping | Matching, translation |
| Published | Live, active |
| Draft | Unpublished, hidden |
| Review | Moderate, approve queue |
| Workspace | Team, organisation, account |
| Member | User, seat |
| Owner | Admin, superuser |
| Capability | Permission flag, right |
| API key | Token, secret key |
| MCP endpoint | AI connection, agent hook |

### 5.3 Prohibited and misleading wording

Never claim, imply or approximate any of the following.

- Verified, validated, certified, accredited, licensed or checked, unless a named verification process actually ran and its result is recorded on the record.
- Official, authoritative or complete for any directory that accepts imported or submitted data.
- Guaranteed, risk free, instant or unlimited.
- Compliant, GDPR compliant, secure by design, bank grade, military grade or enterprise grade as bare adjectives without a named standard and a scope.
- AI powered, intelligent, smart or automatic where a human action is actually required.
- Free forever, or any pricing permanence claim.
- Best, leading, number one, or any superlative that is not attributed to a dated, named source.
- Any suggestion that Bobby Directory is Bobby Wallet, shares accounts with it, or handles payments on its behalf.
- Real names, photographs or contact details of real people in examples, screenshots, demo data or social assets.
- The em dash character.

### 5.4 Naming rules

- The product is written Bobby Directory. Both words capitalised, always together in first mention.
- Never Bobby directory, BobbyDirectory, bobby-directory in prose, or BD as a public abbreviation.
- The domain is written bobbydirectory.com in lowercase.
- The logo lockup is the only place DIRECTORY appears in uppercase on its own.

---

## 6. Platform descriptions and boilerplates

Character counts are for the description text as written.

| Name | Length | Text |
| --- | --- | --- |
| Ultra short | 27 | Structured directories with an API. |
| Short | 96 | Bobby Directory is a platform for building and publishing structured directories with an API. |
| Medium | 236 | Bobby Directory is a platform for building, operating and publishing structured directories. Define typed fields, import records, review submissions and publish. Every published directory is readable through the website, an API and an MCP endpoint. |
| Long | 470 | Bobby Directory is a platform for building, operating and publishing structured directories of almost anything: businesses, professionals, websites, venues, services or animals. Directory operators declare a record type and its typed fields, import or collect records, review submissions and publish. Visitors search and filter the result. Developers and agents read the same published data through an API and an MCP endpoint under the same permissions as the website. |

Boilerplate for press and partner use:

> Bobby Directory is a platform for building, operating and publishing structured directories. Operators declare typed fields, import or collect records, review submissions and publish to a website, an API and an MCP endpoint from one governed source. Bobby Directory is a separate product from Bobby Wallet.

---

## 7. Social media biographies and suggested posts

### 7.1 Biographies

| Platform | Limit | Text | Length |
| --- | --- | --- | --- |
| X | 160 | Structured directories with an API. Declare typed fields, import records, review, publish. Website, API and MCP from one source. bobbydirectory.com | 152 |
| LinkedIn tagline | 120 | Structured directories with an API. Build, review and publish typed records. | 76 |
| LinkedIn about | 2000 | Use the long description in section 6, followed by the boilerplate. | n/a |
| Facebook short | 255 | Bobby Directory is a platform for building and publishing structured directories. Typed fields, review before publish, and one governed source behind the website, the API and the MCP endpoint. | 190 |
| Instagram | 150 | Structured directories with an API. Typed fields. Reviewed records. One source behind site, API and MCP. | 105 |
| YouTube | 1000 | Use the medium description in section 6. | n/a |
| GitHub organisation | 200 | Structured directories with an API. Typed fields, review workflows, and an MCP endpoint over published records. | 111 |

### 7.2 Suggested posts

Each post is written without an em dash, without superlatives and without unverified claims.

1. Launch. `A directory is not a spreadsheet with a theme. It is a record type, typed fields, a review step and a published surface. That is what Bobby Directory gives you.`
2. Import. `Import is the hard part. Bobby Directory checks your file locally first, shows you the proposed field mapping, and asks you to approve it before a single record is created.`
3. API. `Everything a visitor can read on a published directory, an API client can read too, under the same permissions. No second data model.`
4. MCP. `Published directories expose an MCP endpoint, so an agent reads the same governed records a person does. Same permissions, same review state.`
5. Review. `Records do not publish themselves. Draft, review, publish, with an actor and a timestamp on every transition.`
6. Provenance. `If a record came from an import, the record says so. Bobby Directory does not label imported data as verified.`
7. Fields. `Typed fields mean a phone number is a phone number, an opening time is an opening time, and a filter can be built on either without guessing.`
8. Scope. `Directories of businesses, professionals, venues, websites, services or animals. Same engine, different declared record type.`

---

## 8. Email branding rules

### 8.1 Assets and dimensions

| Asset | File | Rendered width | Export width |
| --- | --- | --- | --- |
| Transactional header | `bobby-directory-email-header-light-*.png` | 200 px to 240 px | 600 px and 1200 px |
| Compact header | `bobby-directory-email-compact-light-*.png` | 120 px to 160 px | 200 px and 400 px |
| Dark mode header | `bobby-directory-email-header-dark-*.png` | as above | 600 px and 1200 px |
| Monochrome fallback | `bobby-directory-email-header-mono-*.png` | as above | 600 px and 1200 px |

### 8.2 Rules

1. Email assets are PNG. Never SVG. Several major clients do not render SVG.
2. Always export at 2x the rendered width and set the `width` attribute and the CSS width to the rendered width. Never set only one of them.
3. Set `height="auto"` in CSS and omit a fixed height attribute.
4. Minimum padding around the header logo is 24 px on all sides, 32 px on top of the first content block.
5. Maximum logo width in a 600 px body is 240 px.
6. The header sits on a solid field. Use the light asset on `#FFFFFF` and the dark asset on `#0D1117`. Do not rely on `prefers-color-scheme` alone. Where the client supports it, swap with a dark mode media query and keep the light asset as the default.
7. Transparent PNG logos are not used in email, because clients that force a dark background will place a dark ink mark on a dark field.
8. Alt text is required on every email image. Use `Bobby Directory`. Never leave it empty in email, because blocked images then render as nothing.
9. Set a background colour on the containing table cell that matches the baked field of the image, so a blocked image still shows the correct band.
10. Never place the logo inside a link that has an underline style, and never let a client underline the alt text. Set `text-decoration: none` on the anchor.
11. Footer marks use the compact monochrome asset at no less than 120 px wide.

---

## 9. Invoice and receipt rules

### 9.1 Assets

| Asset | File | Use |
| --- | --- | --- |
| Invoice logo, black | `bobby-directory-invoice-logo-black.svg` | Default on white A4 and Letter |
| Invoice logo, pure black | `bobby-directory-invoice-logo-pure-black.svg` | Single ink and fax |
| Invoice logo, grayscale | `bobby-directory-invoice-logo-grayscale.svg` | Grayscale laser printing |
| Invoice logo, white on dark | `bobby-directory-invoice-logo-white-on-dark.svg` | Dark PDF cover pages only |
| Invoice logo, full colour | `bobby-directory-invoice-logo-full-color.svg` | Colour PDF, screen view |
| Receipt logo | `bobby-directory-receipt-logo-*.svg` | Compact receipts and short PDFs |
| Thermal receipt mark | `bobby-directory-receipt-thermal-mono-w384.png` | 58 mm thermal printers, 384 px |

### 9.2 Rules

1. The default invoice mark is one colour black on white. Colour is optional and must never be required to read the document.
2. Every invoice and receipt must remain fully legible when printed in grayscale or single ink. The grayscale accent `#5A6472` is used instead of the brand accent, measured at 6.00 to 1 on white.
3. Minimum invoice logo width is 28 mm. Minimum receipt logo width is 18 mm.
4. Clear space on documents is one quarter of the symbol height, and no less than 8 mm from the trim edge.
5. Thermal receipts use the pure black mark at 384 px for 58 mm paper and 576 px for 80 mm paper. No grays, no anti-aliased fills, no tints, because thermal heads render mid tones as noise.
6. Do not place the mark over a watermark, a paid stamp or a table rule.
7. The legal entity name, address, registration number and VAT number are set in text, never as part of the logo image.
8. PDF invoices embed the mark as vector. Raster is used only where the renderer cannot embed vector, and then at no less than 600 px tall.
9. Never place a QR code inside the logo clear space.

---

## 10. Asset selection guide

Answer in order.

1. Is the rendered size below 20 px? Use the micro geometry. Below 20 px there is no lockup, only the symbol.
2. Is it between 20 px and 48 px? Use the simplified geometry.
3. Will it print without colour? Use the grayscale variant, or pure black for single ink and thermal.
4. Is the background uncontrolled, photographic or brand adjacent? Use one colour white or one colour black.
5. Is the space wide and short? Use the horizontal lockup. Is it square or portrait? Use the stacked lockup.
6. Is it an email? Use a PNG at 2x, never SVG.
7. Is it a social profile? Use an avatar asset at the platform size, not an app icon.
8. Is it a social cover? Use the named platform file. Do not crop another cover.
9. Does the surface already show the name Bobby Directory in text nearby? The standalone symbol is enough.
10. In every other case, use the full colour horizontal mixed case lockup.

---

## 11. File naming conventions

Pattern:

```
bobby-directory-<component>-<variant>-<field>-<size>.<ext>
```

Rules:

- Lowercase only. Words separated by a single hyphen. No spaces, no underscores, no capitals, no diacritics.
- `<component>` is one of `beeldmerk`, `beeldmerk-simplified`, `beeldmerk-micro`, `horizontal`, `stacked`, `wordmark`, `wordmark-inline`, `app-icon`, `favicon`, `invoice-logo`, `receipt-logo`, `receipt-thermal`, `email-header`, `email-compact`, `avatar`, `embed`, or a social platform name.
- `<variant>` is one of `color-light`, `color-dark`, `black`, `white`, `grayscale`, `pure-black`, `mono`, or a case marker `mixed` or `upper`.
- `<field>` is `on-light` or `on-dark` and appears only when a background is baked into the file.
- `<size>` is a pixel edge for square assets, `h<n>` for a fixed height, or `w<n>` for a fixed width. It is omitted for vector masters.
- Filenames are stable. A corrected asset keeps its filename and gains a new version in the change history, so that public URLs never change.

---

## 12. Future public brand page specification

Route: `/brand`. Public, indexable, no authentication. It is specified here and deliberately not built during Phase 0.

Required sections, in order:

1. Brand introduction. Positioning, what Bobby Directory is and is not, one paragraph each.
2. Logo system. Every lockup and geometry rendered live, with the size at which each applies.
3. Downloads. Per asset and grouped ZIP downloads, with size, dimensions and format shown before the click.
4. Colour swatches. Copyable hex values, tints, semantic colours and the recorded contrast ratio for each pairing.
5. Typography. Live specimens, weights, tracking, fallback stacks.
6. Tone of voice. Preferred vocabulary table and the prohibited wording list.
7. Approved descriptions. Ultra short, short, medium and long, each with a copy button and a character count.
8. Social biographies. Per platform, with the platform limit shown.
9. Email guidance. Rendered examples, width and padding rules, alt text requirements.
10. Invoice and receipt guidance. Grayscale and thermal previews.
11. App icons and favicons. True size previews at 16, 32, 48, 180, 512 and 1024.
12. Avatars. Square and circle previews on light and dark fields.
13. Social covers. Each platform at true aspect with the safe area overlaid.
14. Embed images. Open Graph and preview templates with the rendered card mock.
15. Usage examples. At least six correct placements.
16. Misuse examples. The fourteen prohibitions in section 2.8, each shown and labelled as incorrect.
17. Asset picker. Filter by surface, background, colour mode and size, returning the single correct file.
18. Version and change history. Every published version, its date, its actor and a link to the archived original.

Requirements for the page itself: static rendering, no authentication, no personal data, all download URLs served from the Bobby Directory domain under `/images/`, and a machine readable index at `/brand/index.json` for agents.

---

## 13. Future admin managed brand repository

Route: `/admin/brand`. Specified for a later approved phase. Not built during Phase 0.

The principle: brand files must not live permanently inside application code. Application code references stable public paths. The files behind those paths are managed data, not source.

### 13.1 Asset lifecycle

```text
draft -> in review -> approved -> published
                   \-> rejected
published -> replaced (new version published behind the same path)
published -> rolled back (a previous version is republished)
published -> archived (withdrawn, original retained)
```

Every transition records the actor, the timestamp, the reason and the resulting version number. Transitions are append only. Nothing is deleted.

### 13.2 Stored metadata per asset version

| Field | Purpose |
| --- | --- |
| Asset key | Stable identity, drives the public path |
| Version number | Monotonic per asset key |
| Category | Logo, app icon, favicon, invoice, email, avatar, social, embed |
| Usage description | Where this asset is correct to use |
| State | Draft, in review, approved, published, rejected, archived |
| Original filename | As uploaded |
| Content type | Validated, not trusted from the client |
| Byte size | Recorded at upload |
| Dimensions | Width and height, parsed server side |
| Checksum | SHA-256 of the stored original |
| Alt text | Required, accessible, non empty for non decorative assets |
| Colour mode | Full colour, monochrome, grayscale |
| Background | Transparent, light, dark |
| Minimum size | Enforced guidance for the asset picker |
| Uploaded by, approved by, published by | Distinct actors |
| Timestamps | Uploaded, approved, published, archived |
| Supersedes and superseded by | Version chain |
| Derivative set | Generated sizes and formats, each with its own checksum |

### 13.3 Permissions

- Upload draft: any workspace member with an explicit brand contributor capability.
- Move to review: the same.
- Approve: Owner, or a future explicitly granted Brand Publisher capability.
- Publish, replace, roll back, archive: Owner, or Brand Publisher.
- Publication of an official brand asset is restricted to the Owner or Brand Publisher. No other role, including a general administrator role, may publish.
- Every one of those actions writes an audit event with actor, asset key, version, previous state, new state, timestamp and request identifier.

### 13.4 Storage and stable public URLs

Approved originals and every historical version are stored in platform controlled storage. The application never links to the storage provider directly.

Public delivery uses lowercase, readable, stable paths on the Bobby Directory domain:

```text
/images/bobby-directory-logo-horizontal.svg
/images/bobby-directory-logo-monochrome.svg
/images/bobby-directory-invoice-logo-black.svg
/images/bobby-directory-receipt-logo.png
/images/bobby-directory-email-logo.png
/images/bobby-directory-app-icon-512.png
/images/bobby-directory-favicon-32.png
/images/bobby-directory-social-cover-linkedin.png
/images/bobby-directory-open-graph.png
```

Required properties of the delivery design:

1. The public path maps to an asset key, not to an object path. Publishing a new version repoints the key. The URL does not change.
2. Website templates, email templates, invoices and documentation embed the stable path only. A brand update never requires a code change.
3. The response never reveals the storage provider, bucket name or internal object key. No redirect to a provider domain. The delivery endpoint streams the object.
4. Only assets in the published state are reachable through `/images/`. Draft, in review, rejected and archived assets return 404, not 403, so that the existence of an unpublished asset is not disclosed.
5. Historical originals are immutable. A published version is never overwritten in storage. Rollback republishes an existing immutable version.
6. Publication invalidates the CDN and edge cache for the affected path, and only for that path.
7. Cache headers: published assets are served with a long max age and a revalidation token derived from the version checksum, so a repointed key is picked up promptly while unchanged bytes stay cached.
8. Content type is set from server side validation, never from the upload. `X-Content-Type-Options: nosniff` is always set.
9. Downloads of originals from the admin surface use a content disposition attachment header. Public `/images/` responses are inline.
10. Validation before publication: file type allow list, magic byte check, maximum byte size, maximum dimensions, decode test, and a malware scan.
11. SVG is sanitised before publication. Strip script elements, event handler attributes, external references, foreign objects and embedded entities. Reject any SVG that still contains an external fetch after sanitisation.
12. Raster uploads are normalised: metadata and location data stripped, colour profile flattened, derivatives generated at the documented sizes.
13. Rate limits and audit logging apply to the admin upload and publish endpoints.

None of this exists yet. No storage bucket, no admin route, no delivery endpoint and no live `/images/` asset was created during Phase 0.

---

## 14. Version and change history

| Version | Date | Change | Actor |
| --- | --- | --- | --- |
| 0.1.0 | Phase 0, round 1 | Three brand directions proposed: Bracket Index, Open Registry, Facet | Agent |
| 0.2.0 | Phase 0, round A2 | Bracket Index refined: accent `#C2440A` and `#FFB066`, counters enlarged, DIRECTORY tracking 2.3 and weight 600, mixed case recommended | Agent |
| 1.0.0 | Phase 0, this document | Bracket Index A2 approved. Micro geometry added, monochrome and grayscale variants added, full asset suite exported, brand book written | Owner approved, Agent produced |

---

## 15. Asset index

See `BOBBYDIRECTORY-ASSET-INDEX.md` for the complete file by file index, and `assets/asset-index.json` for the machine readable version.