• Repository Structure

    This repository uses a pnpm workspace to manage multiple packages and projects. Understanding the structure will help you navigate the codebase and know where to make changes.

    Top-Level Directories

    content/

    All course materials and internal documentation live here.

    • content/courses/ — Course content organized by course (e.g., advanced-ui/, advanced-figma/)
    • content/handbook/ — Internal documentation and style guides (this handbook)
    • content/workspace/ — Workspace-specific content, proposals, and ideas

    Most content is written in Chalk (.chalk files), which is our content authoring format. See the Chalk documentation for details.

    packages/

    Internal tools and utilities that support our work. These are managed as pnpm workspace packages.

    • packages/chalk/ — The Chalk build system and content processor
    • packages/workbench/ — Interactive UI demo tool for educational content
    • packages/blueprint/ — Layered UI component library for Workbench
    • packages/dashboard/ — Analytics dashboard (Observable-based)
    • packages/invoice-downloader/ — Internal tool for managing invoices
    • packages/aui-preview/ — Preview tool for Advanced UI course

    Each package typically has its own package.json, dependencies, and development scripts. See Tools and Packages for more details.

    websites/

    Source files for our public-facing websites.

    • websites/buttonschool.com/ — Main Button School website
    • websites/chalkboard.buttonschool.com/ — Chalkboard preview tool
    • websites/handbook.buttonschool.com/ — This handbook (public version)
    • websites/uimc.buttonschool.com/ — UI Masterclass website

    Each website has its own build configuration and deployment setup.

    lab/

    Experiments, prototypes, and early-stage work. This is where we try out new ideas before they become full tools or features.

    • lab/gather/ — Project management prototype (Flask/Python)
    • lab/school-planner/ — Course planning tool (Svelte)
    • lab/course-exporter/ — Tool for exporting courses as zip files
    • lab/codepen-archive/ — Archive of CodePen demos and examples
    • lab/video-scrubber/ — Video navigation prototype

    Projects in lab/ may eventually graduate to packages/ if they become production tools, or they may remain experimental.

    Root-Level Files

    Configuration Files

    • package.json — Root package configuration and workspace scripts
    • pnpm-workspace.yaml — Defines the pnpm workspace structure
    • pnpm-lock.yaml — Lock file for dependencies
    • Brewfile — Homebrew packages installed by setup.sh
    • setup.sh — Initial setup script for new team members

    Documentation

    • README.chalk — Repository overview (rendered on GitHub)
    • .gitignore — Git ignore patterns

    Other Files

    Most other files in the root are configuration for build tools, linters, or deployment. If you’re just working on content, you typically don’t need to modify these.

    pnpm Workspace Structure

    This repository uses pnpm workspaces to manage multiple packages. The workspace is defined in pnpm-workspace.yaml and includes:

    • All packages in packages/
    • All websites in websites/
    • All lab projects in lab/

    This means:

    • Dependencies are installed from the root with pnpm install
    • Packages can depend on each other using workspace protocol (workspace:*)
    • Scripts can be run from the root or individual packages
    • Dependencies are hoisted and shared where possible

    When to Use Each Directory

    Use content/ when:

    • Creating or editing course materials
    • Writing handbook documentation
    • Adding new lessons or guides

    Use packages/ when:

    • Working on internal tools
    • Fixing bugs in Chalk, Workbench, or other tools
    • Adding features to existing tools

    Use websites/ when:

    • Making changes to public-facing websites
    • Updating site content or styling
    • Working on deployment configurations

    Use lab/ when:

    • Experimenting with new ideas
    • Building prototypes
    • Testing concepts before they become production tools

    Finding Specific Things

    For a quick reference on where to find specific content, tools, or documentation, see Finding Things.