• Tools and Packages

    This repository contains several internal tools and packages that support our work. This guide provides an overview of what’s available and when to use each tool.

    Core Content Tools

    Chalk

    Location: packages/chalk/

    Chalk is our content authoring format and build system. It processes .chalk files (Markdown-based) into HTML for preview and export.

    When to use: You’ll use Chalk whenever you’re writing course content, handbook documentation, or any content in the repository.

    Documentation: See the Chalk documentation for complete details on syntax, features, and usage.

    Key commands:

    • pnpm chalk — Start Chalkboard preview server
    • cd packages/chalk && pnpm build — Build content for production

    Chalkboard

    Location: websites/chalkboard.buttonschool.com/

    Chalkboard is the preview tool for viewing Chalk content locally. It provides a web interface for browsing and previewing content as you write.

    When to use: Always use Chalkboard to preview your content changes before committing.

    Key commands:

    • pnpm chalk — Start Chalkboard dev server (from root)

    Workbench

    Location: packages/workbench/

    Workbench is an interactive UI playground for creating educational demos. It lets you build explorable interface demonstrations with configurable props, animations, and layered component views.

    When to use: Use Workbench when creating interactive demos for courses that need to show how UI components work or behave.

    Documentation: See the Workbench documentation for details.

    Key features:

    • Configurable props with controls
    • Playable animations
    • Exploded view for layered components
    • Zoom support for detailed examination

    Blueprint

    Location: packages/blueprint/

    Blueprint is a component library for building layered UI elements that work with Workbench. Components understand zoom levels, explosion states, and interactive variants.

    When to use: Use Blueprint components within Workbench demos to create layered, explorable UI demonstrations.

    Documentation: See the Blueprint documentation for component API and usage.

    Key components:

    • Element — Container for layered compositions
    • Fill — Background fills
    • Shadow — Box shadows
    • Content — Text and typography
    • Layout — Flexbox-based layouts

    Utility Tools

    Course Exporter

    Location: lab/course-exporter/

    A tool for exporting course content as zip files, including both source and built versions.

    When to use: Use when you need to package a course for distribution or backup.

    Key commands:

    • pnpm export aui — Export Advanced UI course
    • pnpm export af — Export Advanced Figma course

    Invoice Downloader

    Location: packages/invoice-downloader/

    An internal Python tool for automatically downloading invoices from various providers (Stripe, Netlify, Veed, etc.).

    When to use: Internal tool for managing invoices and billing.

    Setup: Requires Python environment and service account credentials.

    Dashboard

    Location: packages/dashboard/

    An analytics dashboard built with Observable for viewing revenue, sales, and student feedback data.

    When to use: Internal tool for viewing business metrics and analytics.

    Lab Projects

    These are experimental projects that may or may not become production tools:

    Gather

    Location: lab/gather/

    A project management application prototype focused on role-based design and multi-organization collaboration. Built with Flask (Python) and vanilla HTML/CSS/JS.

    Status: Planning and documentation phase.

    School Planner

    Location: lab/school-planner/

    A course planning tool built with Svelte for organizing and planning course content.

    Key commands:

    • pnpm planner — Start dev server (from root)

    Video Scrubber

    Location: lab/video-scrubber/

    A prototype for video navigation and scrubbing interfaces.

    Quick Command Reference

    Common commands you might use:

    # Content preview
pnpm chalk              # Preview all content
pnpm handbook          # Preview handbook only

# Development
pnpm install           # Install all dependencies
pnpm planner          # Run school planner

# Export
pnpm export <course>   # Export a course as zip

# Individual packages
cd packages/chalk && pnpm dev
cd packages/workbench && pnpm dev

    When to Use Which Tool

    Writing course content?

    • Use Chalk to write .chalk files
    • Use Chalkboard to preview (pnpm chalk)

    Creating interactive demos?

    • Use Workbench to create the demo
    • Use Blueprint components for layered UI elements
    • Preview in Chalkboard

    Working on internal tools?

    • Navigate to the package directory
    • Check the package’s package.json for available scripts
    • Run pnpm dev or pnpm build as needed

    Experimenting with new ideas?

    • Create or work in lab/ directory
    • These projects are experimental and may change

    Future considerations

    Python environment management: This monorepo has multiple Python projects (e.g. lab/gather, packages/invoice-downloader) and may gain more; each has its own dependency needs. For later, we may consider:

    • uv — Fast, per-project virtualenvs and installs; uv run runs in the right env without activating.
    • direnv — Activate the right env when you cd into a project directory, so the active env follows the folder in any shell or editor.

    No change planned right now; documenting for when we revisit.

    Getting Help