Setup

This template provides a solid foundation for new projects. Follow these steps to customize it for your project.

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 cms/ folder
Update the index page description in cms/generator/generate-docs.js
Add or remove documentation pages as needed

Local Development (Netlify Functions)

Forms (feedback, access-support) post to /api/submit-form, which is rewritten in netlify.toml to a Netlify Function that writes to Notion. To exercise that path locally, run Netlify Dev instead of a static server. It runs the Functions in netlify/functions/ and proxies them through /api/*.

VSCode Live Server (port 5501) is static-only, so any POST to /api/* returns 405. Use port 8888 (Netlify Dev) for any form testing.

One-time setup

npm install. Installs netlify-cli (~200 MB; first install takes 30–90 s).
npx netlify login. Browser flow.
npx netlify link. Choose the existing bydefault.design site. This is what lets netlify dev pull production env vars into your local session.
npx netlify env:list. Confirm the three keys: NOTION_API_KEY, NOTION_DATABASE_ID_FEEDBACK, NOTION_DATABASE_ID_ACCESS_SUPPORT. See .env.example for the canonical list.

Each session

npm run dev

Opens http://localhost:8888 with Functions live. Netlify Dev loads the Local development (Netlify CLI) context for env vars, so NOTION_API_KEY and the four NOTION_DATABASE_ID_* keys must be populated in that context on the Netlify dashboard. Submitting any form writes a real row to the production Notion database. There is no separate dev database, so test submissions are visible to the team.

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

The theme system uses the auth module to decide which brand a visitor sees:

Team members see the By Default brand (instance 0, loaded as a static link on every root page)
Brand users see their brand automatically (matched via brandFolder in Netlify Identity app_metadata; the value must match the brand's folder key)
Admins get a Theme Preview section in the header dropdown to preview any brand. The preview persists across navigation (via sessionStorage) and resets when the tab closes; selecting "By Default" clears it

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
`assets/js/auth.js`	Calls `initThemeForUser()` after auth resolves

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:^1.1.0 ships design-system.css plus the icon sprite (icons.svg). Pin to a tag and upgrade deliberately.
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