Folders

This document defines where files live and why.

Do not add new top-level folders without updating this file.

Root Level

• index.html → Generated docs hub (homepage)
• glossary.html → Generated root page, belonging to no section
• support.html, access-denied.html → Hand-written bare pages, outside the page-transition container

Everything else generated lives in a section folder below, not at the root.

• README.md → Project overview and getting started
• PROJECT_OVERVIEW.md → Project source of truth: what this project is, goals/non-goals, and the engine/instance split
• PROJECT_PROGRESS.md → What has shipped, dated, newest first (CLAUDE.md §21)
• ROADMAP.md → Committed direction, open defects, known debt (CLAUDE.md §21)
• CLAUDE.md → Claude Code development rules (authoritative)
• assets/ → All project assets (CSS, fonts, icons, images, video)
• website/ → Generated website-medium pages: foundations, components, scripts (the design system styleguide)
• brand/ → Brand identity pages: logo, palette, typography, iconography (brand tokens live in assets/css/design-system.css)
• social/ → Generated social channel pages (from cms/social-*.md)
• channels/ → Generated owned-channel pages (from cms/channels-*.md, template: templates/channel-template.md)
• react/ → React adapters for portable components — plain ESM, shipped in the package as dist/react, never loaded by this site
• templates/ → Component and page templates
• cms/ → Documentation markdown source and generator
• tools/ → Generated tool apps. Edit the source pair in cms/apps/, not these files
• examples/ → Generated skeletons, one per page type, linked from docs/page-layouts.html
• _site/ → Build output. Assembled by tools/build-site.js from an allowlist; never edited, never committed
• handovers/ → Session handovers, one per topic (CLAUDE.md §21)
• cms/brands/<brand>/assets/theme.css → Brand theme overrides (one per brand instance)
• cdn/ → Legacy Webflow project code (JS + CSS served via CDN)

The Studio marketing site lives in its own repository since July 2026. See CLAUDE.md §18.

assets/

Single source of truth for all assets. No duplication.

• css/design-system.css → Core design system framework (tokens, utilities, layout primitives)
• css/docs-site.css → Docs-site layout, navigation, page chrome, components
• js/nav.js → Generated site header + sidebar, injected into any page with a #site-nav mount. Never hand-edit
• js/theme-config.js → Generated theme registry (maps brand folder → CSS path + font sources)
• js/theme-loader.js → Dynamic theme loading/unloading module. Dormant since auth was removed
• fonts/ → Web fonts
• icons/ → Favicons and app icons
• images/ → All images, organised by type:
  • logos/ → Site and publication logos
  • og/ → Open Graph social sharing images
  • illustrations/ → Decorative and UI illustrations
  • svg-icons/ → SVG component icons
• video/ → Video assets

website/

The website medium — the design system styleguide preview.

• index.html → Styleguide preview (renders with default tokens)

The design system CSS (assets/css/design-system.css) lives in the assets folder alongside other stylesheets.

brand/

Brand identity pages. Brand tokens live directly in assets/css/design-system.css.

• index.html → Brand book overview, with companion pages for color, logo, typography, iconography, values, etc.

Brand themes

Brand theme overrides live inside each brand's folder: cms/brands/<brand>/assets/theme.css. Each file overrides design system semantic tokens and the neutral colour scale for that brand. Themes are loaded dynamically by theme-loader.js; the registry in assets/js/theme-config.js is generated by docgen from the brand folders.

• cms/brands/brand-template/assets/theme.css → Starter template (copy and customise per brand)

See Setup, Brand Theming for usage.

cdn/

JavaScript and CSS files served to legacy Webflow-era projects via CDN (jsdelivr). Each subfolder represents one project. Leave untouched until Webflow retirement is confirmed (CLAUDE.md §18).

• studio/ → By Default agency website CDN assets (bydefault.studio). See CLAUDE.md §18.
  • js/ → Page-specific scripts (homepage, hero, blog, case study, etc.)
  • css/ → Page-specific styles (hero section)
• fifa-wc26/ → FIFA World Cup 2026 interactive stadium map
  • js/ → Map script
• la-interactive-map/ → LA interactive map
  • js/ → Map script

Additional project folders can be added as needed.

templates/

• component-template.js → JavaScript component template
• component-template.css → CSS component template
• page-template.html → HTML page template

cms/

• Markdown documentation files (source of truth for generated HTML)
• docs.config.js → Project-specific doc settings (sections, nav, fonts, footer), stays when the generator is upgraded
• apps/ → Tool source pairs: <slug>.md frontmatter + <slug>.html body → tools/
• examples/ → Page-type skeletons → examples/
• chrome/ → Shared head/body partials pulled into docs.config.js
• brands/ → Brand-specific markdown documentation (one subfolder per brand)
• generator/ → Documentation site engine
  • template.html → HTML template used for generation
  • generate-docs.js → Generator script (outputs HTML to project root)
  • portable.js → Shared predicate deciding which pages are portable (CLAUDE.md §17)

The generator no longer carries a VERSION file. It ships inside the
@bydefaultstudio/design-system package as dist/docs-kit/, so the package
version is the generator version.

CSS Loading Order

The generated HTML loads CSS in this order:

1. assets/css/design-system.css → Brand tokens, framework tokens, utilities, layout primitives
2. assets/css/docs-site.css → Docs-site layout, navigation, page chrome, components
3. cms/brands/<brand>/assets/theme.css → Brand theme overrides (optional, must load last)

New docs-site CSS goes in assets/css/docs-site.css. New core/foundation CSS goes in assets/css/design-system.css. See CLAUDE.md §17, Layer Discipline for the rules that govern this split.

tools/

Live tool apps — generated output, not source. Each one is built from a pair
in cms/apps/: <slug>.md carries the frontmatter, <slug>.html the body that
goes between the <main> tags. Two files because a tool body must not go through
the markdown pipeline, which rewrites tables, code blocks and inline code. Edit
the pair and re-run docgen; never edit tools/*.html directly.

qr-code.html is the exception and the only hand-written tool left. It carries a
vendored library and its application JS inline, which an app body cannot hold, so
converting it means extracting that JS first.

Each tool also has a guide page (cms/<name>-docs.md → tools/<name>-docs.html)
covering URL schemas, embed parameters and the reasoning a UI cannot carry.

SVG cleaning comes from the @bydefaultstudio/svg-cleaner package (a devDependency): CLI via npx svg-cleaner, browser engine synced to assets/js/vendor/svg-cleaner-core.js on npm install.

Notes

Empty folders are tracked using .gitkeep to preserve structure in the template.

Favicons

Favicons live in assets/icons/.

They are referenced directly in the HTML <head> and are treated as brand assets, not part of the design system.