Platform Strategy

By Default BrandOS is an interactive brand infrastructure platform. It gives clients, partners, and the internal team a shared environment to build, access, and optimise the brand systems that power effective interactive advertising.

Where traditional brand portals are static — guidelines in a PDF, logos in a folder — BrandOS is operational. It holds design tokens, brand frameworks, advertising tools, and client-specific environments in one place, structured so that every project begins from the same high-quality foundation and every output is measurably on-brand.

In one sentence: BrandOS is where By Default's interactive advertising methodology becomes something clients can build with, not just look at.

What It Is Not

BrandOS is not a design system documentation site. It is not a file library. It is not a static brand guidelines PDF. The design system lives inside it as infrastructure — not as its purpose.

If a decision can be made by reading a token, the platform is doing its job. If a decision requires a meeting, the platform is not yet doing its job.

How the codebase is layered

The repository is split into four layers so the design system can be lifted into other products without dragging this docs site along with it:

• foundation — design tokens, layout primitives, type and colour utilities. The unopinionated base every product needs.
• core — reusable components (button, card, dropdown, …) and brand identity docs. The branded-but-functionally-generic layer.
• docs-site — components that only exist to power this BrandOS site (asset-card, book-cover, dont-card, sticky-bar, copy-button). Not portable.
• app — BrandOS-specific tools and project content (CPM calculator, ad preview, world clock, project case studies, internal setup docs). Not portable.

Foundation and core ship together when the system is packaged for a new product. Docs-site and app stay with BrandOS itself. The full ruleset, including the "where to put new things" decision tree, lives in CLAUDE.md §17 (Layer Discipline).

Audience

BrandOS serves three distinct audiences. Copy, navigation, and content decisions must specify which audience they serve before they are written.

Team — designers, developers, and strategists at By Default. They use the system as the foundation for every project. The system exists to make quality non-negotiable and delivery faster.

Partners — media owners, production houses, tech vendors, ad platforms. They access BrandOS to understand brand constraints and retrieve specifications before and during production. The system exists to eliminate briefing overhead.

Clients — brand and marketing leads at client organisations. They access BrandOS to understand their brand system, use the studio's tools, and — over time — build and govern their own Brand OS. The system exists to give them infrastructure, not just outputs.

Platform Architecture

The repository is structured across several interconnected modules:

The design system CSS (assets/css/design-system.css) is the single source of truth for all tokens. Brand tokens are defined in the "Brand Tokens" section of design-system.css and each client theme can override them via theme.css.

UX Copy

Voice

BrandOS copy sits at the intersection of creative precision and strategic clarity. Every word should hold both.

• Direct without blunt — no filler, no throat-clearing. Every sentence earns its place.
• Expert without exclusive — assumes an intelligent reader, not a developer. Complex ideas expressed simply.
• Warm without casual — there is a relationship here. The platform should feel built for the specific person reading it.
• Action-oriented — the platform exists to enable doing, not reading. Copy should point toward the next move.

Seven Principles

1. Name what it is, not what it does.
"Your brand system" is more powerful than "Click here to access your brand guidelines."

2. Write for the moment, not the manual.
UX copy is contextual. The user is in the middle of doing something. Help them with the next step — don't explain the platform.

3. Use "your" deliberately.
For clients: "your brand system," "your tokens," "your frameworks" builds ownership. For the team: "the system," "our methodology" reinforces shared standards.

4. Avoid qualifier creep.
Remove "simply," "easily," "just," "quickly." If it's simple, show it. If it's not simple, don't lie.

5. Headlines are arguments, not labels.
"Design Tokens" is a label. "Every decision starts here" is an argument. The platform makes its case.

6. Active voice, present tense.
"Your brand tokens are live." Not "Brand tokens have been published."

7. Error copy is a trust moment.
Be specific about what happened. Be honest about what to do. Never blame the user.

Tone by Context

Copy by Scenario

Navigation labels — labels should express intent, not describe content.

Empty states — tell the user what will be here and how to make it appear. Never "Nothing here" or "No items found."

"No frameworks yet. Add your first framework to start building your brand OS."

Tool interfaces — use the exact noun the user would use with a colleague. No instructional preamble.

"CPM (cost per mille)" — not "Input your CPM value below"

Error states — specific, honest, forward-pointing.

"You don't have access to this environment. Contact [name] to request access." — not "Access denied."

Documentation — treat the reader as a senior practitioner. No "simply," no "just." Structure every section: what it is → when to use it → how to use it → what not to do.

Copy Update Process

When updating UX copy, follow this sequence:

1. Identify the scenario — which audience, which moment, what are they trying to do?
2. Write three versions — different frames, not minor word swaps
3. Test against the seven principles — remove qualifiers, check active voice, confirm it makes an argument
4. Check audience fit — correct technical level, correct use of "your" vs "the"
5. Edit the Markdown source — never edit generated HTML directly
6. Run the doc generator after any cms/*.md change: cd cms/generator && npm run docgen
7. Review in context — read the copy in the browser, in the actual interface
8. Document the change in PROJECT_PROGRESS.md — what changed, why, and the date

Do not:

• Update navigation labels without checking section headers and body copy for consistency
• Add warmth through filler words — write tighter instead
• Write copy that explains the platform — if extensive explanation is needed, the UX needs fixing
• Let error states ship without intentional copy

Outcome Signals

These are the signals that indicate BrandOS is working.

Team signals

• Token and spec questions trend toward zero — the system answers them
• Every project starts from the system, not from a blank file
• New patterns are added to the system, not invented per-project and abandoned
• The doc generator runs after every docs change

Partner signals

• Briefing clarification emails decrease per engagement
• Off-brand partner outputs requiring revision decrease
• Partners describe By Default as "straightforward to work with"

Client signals

• Clients access their brand environment without prompting
• "Is this on-brand?" queries decrease — clients answer this themselves using the system
• Clients reference BrandOS frameworks in their own brand decisions
• Retention rate is higher for accounts with active platform access

Platform health signals

• No broken links in the generated docs site
• All pages pass WCAG 2.1 AA on an ongoing basis
• Lighthouse 90+ maintained — not just at launch
• Docs reviewed within 90 days — stale documentation is worse than none
• Token sync between Webflow variables and BrandOS tokens: always zero divergence

Related Docs

• cms/color.md — colour token reference
• cms/typography.md — typography token reference
• cms/spacing.md — spacing token reference
• cms/layout.md — page layout hierarchy
• cms/button.md — button component usage
• cms/seo-best-practices.md — SEO meta requirements
• PROJECT_BRIEF.md — project intent and constraints
• PROJECT_PROGRESS.md — change log and task tracker