Setup

The customisation surface of this site, in one place: where brand colours, fonts, logos and meta tags come from, how a brand theme is put together, and how another product consumes the design system. Work through it when standing up a new instance, or use it to find which file owns a value you need to change.

Brand Colors

Update brand colours in your brand's theme file, cms/brands/<brand>/assets/theme.css. The engine (assets/css/design-system.css) ships neutral values; the theme overrides them.

Never edit brand values into design-system.css directly. The engine file is shared by every brand instance and gets replaced on engine syncs — brand values baked into it are silently lost.

What to change:

, , etc. Your palette colours
, , , etc. Your accent colours

Example:

/* cms/brands/<brand>/assets/theme.css */
:root {
  --off-white: #fff7f1;
  --warm-black: #221f1c;
  --green: #167255;
}

Fonts

Update font families in your brand's theme file, cms/brands/<brand>/assets/theme.css. The engine (assets/css/design-system.css) ships neutral system stacks; the theme overrides them.

What to change:

. Your primary font family
. Your secondary font family (if used)
. Your tertiary brand display font (if used)
. Your monospace font (if used)

Also update:

@font-face declarations in the same theme file if self-hosting (font files go under assets/fonts/)
Font sources in cms/brands/<brand>/brand.json: typekitId for an Adobe Typekit kit, fontPreload for files to preload, googleFontsUrl for Google Fonts. The generator emits the matching head links per brand
Hand-authored pages (tools/*.html, auth/*.html, support.html, access-denied.html, templates/page-template.html) carry their font links hardcoded. If you change the manifest's font sources, update these heads by hand to match

Logo

Replace the logo files in assets/images/logos/bydefault/. There are six variants: three marks (primary, primary-centered, avatar) each with a black and a white version. See Logo for the full file reference.

Project Overview

Fill in PROJECT_OVERVIEW.md with your project details:

Replace all bracketed placeholders [like this] with actual content
Define project goals, audience, and constraints

Meta Tags & SEO

Update SEO meta tags in cms/generator/template.html:

Update <title> template if needed
Add Open Graph tags for social sharing
Update favicon references if using custom favicons

Documentation

The documentation is ready to use, but you may want to:

Review and customize documentation content in the cms/ folder
Update the site name, footer and home page description in cms/docs.config.js
Add or remove documentation pages as needed

Local Development

This project serves on http://localhost:2000/ — pinned in netlify.toml ([dev] port) and .vscode/settings.json, so npm run dev and VS Code Live Server both land on the same number. The port is allocated from the studio-wide registry in CLAUDE.md §6; do not let a server pick its own.

npm run dev

A plain static server is enough for everything except forms. Forms (feedback, access-support) post to /api/submit-form, which is rewritten to a serverless function that writes to Notion — a static server returns 405 for that path. npm run dev runs the functions alongside the site, so use it whenever you are touching a form.

One-time setup for form testing

npm install.
npx netlify login. Browser flow.
npx netlify link. Choose the existing bydefault.design site — this is what pulls the production env vars into your local session.
npx netlify env:list. Confirm NOTION_API_KEY, NOTION_DATABASE_ID_FEEDBACK and NOTION_DATABASE_ID_ACCESS_SUPPORT. See .env.example for the canonical list.

There is no separate dev database. Submitting a form locally writes a real row the team can see, so use obviously-marked test content.

Moving to Cloudflare. Hosting is migrating from Netlify, and npm run dev is still netlify dev until that lands. The port stays 2000 either way. See ROADMAP.md → Platform.

Quick Checklist

Update brand colors in your brand's theme.css (cms/brands/<brand>/assets/)
Update font families in the same theme file
Replace logos in assets/images/logos/bydefault/
Fill in PROJECT_OVERVIEW.md
Update font sources in brand.json (typekitId, fontPreload, googleFontsUrl) and @font-face in the theme file
Set up brand theme (if applicable), see Brand Theming
Review and customize documentation
Run npm run dev to test forms locally on http://localhost:8888

Brand Theming

Brand theming runs on the two-file model: cms/brands/<brand>/brand.json holds the admin settings (name, font sources, footer, favicons) and cms/brands/<brand>/assets/theme.css holds the designer tokens. The full walkthrough, from copying the template folder to going live, is the Brand Setup doc.

How it works

Every page loads a theme as a static link, chosen at build time from the page's own brand:

Root pages load By Default's theme (instance 0) on every page.
Brand pages load their own brand's theme.css, emitted into the page head by the generator.

There is no runtime switching today. theme-loader.js can load and unload a theme dynamically, and a preview switcher was driven by the login — both are dormant since auth was removed, and would be wired back up by whatever gating returns. See ROADMAP.md → Auth.

Stylesheet load order

Theme CSS must always load after all other stylesheets (design-system.css, docs-site.css). This ensures theme overrides win via the CSS cascade, no !important needed. The generator emits this order on every generated page; hand-authored pages carry the same order.

When overriding component styles (not just tokens), match the specificity of the base selector. For example, docs-site.css uses .svg-logo.nav-logo, so the theme should use .svg-logo.nav-logo, not just .

Architecture

File	Purpose
`cms/brands/<brand>/brand.json`	Admin manifest: name, font sources (`typekitId`, `fontPreload`, `googleFontsUrl`), footer, favicons
`cms/brands/<brand>/assets/theme.css`	Designer tokens plus self-hosted `@font-face` declarations
`assets/js/theme-config.js`	Generated registry (built from the manifests by the doc generator). Never hand-edit
`assets/js/theme-loader.js`	Loads/unloads theme CSS and fonts dynamically. Dormant — nothing calls it since auth was removed

Consuming the Design System in Another Product

Standalone products (like the studio site) don't run this repo — they consume the design system as an artefact:

Package (preferred): npm install github:bydefaultstudio/design-system-dist#semver:^4.7.0 ships design-system.css, the icon sprite (icons.svg), the component JS modules (js/ — bar, dialog, copy button, toast, tabs, accordion, dropdown, number input, rating, password toggle, plus the headless bd-audio, bd-cursor and bd-video), and the React adapters (react/, imported as @bydefaultstudio/design-system/react — see React). Pin to a tag and upgrade deliberately; include only the scripts for the components the product uses.
Vendored copy: copying assets/css/design-system.css into the consumer repo also works, but treat the copy as read-only and flag drift rather than editing it.

Either way, the engine CSS ships neutral brand tokens. All brand identity (fonts, palette) belongs in the consumer's own theme.css, loaded after the engine file — never edited into the engine file, or it is silently erased by the next sync.

Next Steps

Start building pages at the repo root and in section folders (see Folder Structure)
Use the templates in templates/ folder for new components
Follow the coding standards in the documentation
Keep documentation updated as you build