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)
• *.html → Generated documentation pages (flat at 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 → Progress tracker for ongoing work
• CLAUDE.md → Claude Code development rules (authoritative)
• assets/ → All project assets (CSS, fonts, icons, images, video)
• design-system/ → Design system framework (shared across projects)
• brand/ → Brand identity pages: logo, palette, typography, iconography (brand tokens live in assets/css/design-system.css)
• touchpoints/ → Generated touchpoint guideline pages (from cms/touchpoints-*.md)
• templates/ → Component and page templates
• cms/ → Documentation markdown source and generator
• tools/ → Live tool apps (CPM calculator, SVG cleaner, display ad preview)
• themes/ → Brand theme overrides (one CSS file per brand)
• 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, auth UI
• js/auth.js → Authentication module (Netlify Identity)
• js/auth-config.js → Auth role hierarchy and settings
• js/theme-config.js → Theme registry (maps brandFolder → CSS path + optional font URL)
• js/theme-loader.js → Dynamic theme loading/unloading module
• 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

design-system/

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.

themes/

Brand theme overrides. Each file overrides design system semantic tokens and the neutral colour scale for a specific brand brand. Themes are loaded dynamically by theme-loader.js based on the user's auth identity.

• theme-template.css → Starter template (copy and customise per brand)

Register themes in assets/js/theme-config.js. 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 (fonts, footer, description), stays when generator is upgraded
• brands/ → Brand-specific markdown documentation (one subfolder per brand)
• generator/ → Documentation site engine (replaceable, drop in a new version to upgrade)
  • template.html → HTML template used for generation
  • generate-docs.js → Generator script (outputs HTML to project root)
  • VERSION → Current engine 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, auth UI
3. themes/brand-name.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. Each tool is a standalone HTML page.

• cpm-calculator.html → CPM & Spend Calculator
• svg-cleaner.html → Browser-based SVG cleaner UI
• display-ad-preview.html → Celtra ad preview sandbox

The SVG cleaner CLI script lives at assets/js/svg-clean.js.

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.