--- title: "Folders" subtitle: "File organization and directory structure" description: "Guide defining where files live and why in the project structure." author: "Studio" section: "Docs" layer: "app" subsection: "Dev" order: 2 status: "published" access: "admin" client: "internal" --- 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_BRIEF.md` → Project brief and requirements - `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-book/` → Brand preview page (brand tokens now live in `assets/css/design-system.css`) - `templates/` → Component and page templates - `cms/` → Documentation markdown source and generator - `tools/` → Live tool apps (CPM calculator, SVG cleaner, display ad preview) - `src/` → Source files (pages, JS) - `themes/` → Client theme overrides (one CSS file per client) - `cdn/` → Webflow project code (JS + CSS served via CDN) - `studio/` → By Default agency website. Self-contained marketing site (not a docs site). Shares `assets/css/design-system.css` from the parent for design tokens; everything else lives inside `studio/`. Layer: `app`. See `studio/README.md` for full details and CLAUDE.md §18 for studio-mode rules. - `index.html` → Home page (master feed, Barba level 0) - `about.html`, `contact.html` → Level 1 destination pages - `work/` → Case study pages (level 2) - `articles/` → Article pages (level 2) - `templates/page-template.html` → Studio page template (use this, not root `templates/`) - `assets/css/studio.css` → Studio layout, grid, transitions, components - `assets/css/bd-video.css` → Video component styles - `assets/js/` → `studio.js`, `studio-barba.js`, `studio-contact.js`, `bd-video.js` - `apps-script/` → Google Apps Script utilities ## 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 clientFolder → CSS path + Google Fonts 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-book/ Brand preview page. Brand tokens now live directly in `assets/css/design-system.css`. - `index.html` → Brand preview page (logo, palette, typography, icons) ## themes/ Client theme overrides. Each file overrides design system semantic tokens and the neutral colour scale for a specific client 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 client) Register themes in `assets/js/theme-config.js`. See [Setup — Client Theming](setup.md#client-theming) for usage. ## cdn/ JavaScript and CSS files served to Webflow projects via CDN (jsdelivr). Each subfolder represents a Webflow site. Global scripts shared across sites live in `assets/js/bd/`. - `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. Project overview docs are generated to `projects/` from `cms/projects-*.md`. ## src/ ### src/js/ - JavaScript modules and scripts ### src/pages/ - HTML page files ## 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 - `clients/` → Client-specific markdown documentation (one subfolder per client) - `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/client-name.css` → Client 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](../CLAUDE.md#17-layer-discipline) for the rules that govern this split. ### Studio CSS Loading Order Studio pages load CSS differently from docs pages: 1. `../assets/css/design-system.css` → Shared foundation + core tokens (read-only from studio's perspective) 2. `assets/css/studio.css` → Studio layout grid, components, transitions (loads last, cascade wins) Studio does **not** load `docs-site.css` or client themes. See [CLAUDE.md §18 — Studio Mode](../CLAUDE.md#18-studio-mode). ## 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 `` and are treated as brand assets, not part of the design system.