Architecture

Bitsy keeps public-facing surfaces easy to scan. README.md and these docs explain the foundation, while architecture notes, ADRs, and status docs stay versioned under internal/ for contributors. The main package area is packages/foundation and Bits have their own packages/bits area, while the public package name stays @bitsyui/core for compatibility.

Workspace structure

The top-level map should orient contributors before they read package-specific detail.

.
|-- AGENTS.md
|-- CONTRIBUTING.md
|-- README.md
|-- apps
|   |-- docs
|   `-- storybook
|-- internal
|   |-- architecture
|   |-- adr
|   |-- foundation
|   `-- status
|-- packages
|   |-- bits
|   |-- cli
|   `-- foundation

Workspace roles at a glance

These are the repo areas a contributor actually needs to keep straight.

Public front door

`README.md`

The fast repo overview for package roles, local workflow, and the top-level map.

Foundation

`packages/foundation`

The repo home for tokens, theme, reset, base defaults, and the primary import path.

Bits

`packages/bits`

Per-Bit folders that keep web implementation, bit.md, and bitsy-guide.md together.

Setup

`packages/cli`

The narrow setup companion that generates a starter stylesheet for the foundation.

Public docs

`apps/docs`

Setup, tokens, themes, examples, and this repo guide for people evaluating or adopting Bitsy.

Validation

`apps/storybook`

The validation and example surface for the foundation and implemented Bits.

Contributor memory

`internal/`

Architecture guidance, ADRs, status docs, and validation notes that should stay discoverable without dominating the root.

What belongs in Foundation and Bits

Keeping the two layers distinct is what lets the Bit layer stay small and scan-friendly.

Foundation scope

What belongs in Foundation

Semantic tokens.
Light and dark theme values.
Browser reset and base element defaults.
A very small optional utility layer.

Bit scope

What belongs in Bits

One folder per implemented Bit.
The current web implementation for that Bit.
The Bit definition in bit.md.
The Bitsy Guide in bitsy-guide.md.

You do not need to jump between implementation folders and a separate docs tree to understand a Bit.

Out of scope

What stays out of Foundation

Framework adapters and component libraries.
Page shells and hidden layout systems.
Large prose or typography frameworks.
Showcase-first docs architecture.

Current implemented Bits

Button and Text Field live under packages/bits. Their portable semantics live in each Bit folder's bit.md and bitsy-guide.md, while their current web implementation still ships to consumers through @bitsyui/core. Each has one example page: Button and Text Field.