Contributing

How the monorepo is laid out, how to run it locally, and where new tokens and components go.

Getting started

The repo uses Bun. Install dependencies at the root, then run this docs app — it regenerates the styled system before starting.

bun install
cd apps/docs
bun run dev

Repo layout

  • packages/components — the design system, published as @pockets-ui/components: the Panda theme in src/theme (primitive tokens, semantic tokens, text styles, and component recipes) and the React components, built on React Aria and styled by those recipes. Its generated styled-system (css(), tokens, patterns, recipes) lives in packages/components/styled-system — gitignored, produced by bun run codegen — and ships inside the package as @pockets-ui/components/css, /jsx, /recipes, and friends.
  • packages/utils — @pockets-ui/utils, framework helpers shared by the components.
  • packages/tokens-native — @pockets-ui/tokens-native, the same token tree resolved for React Native.
  • apps/docs — this site, a Panda consumer that extends the theme and generates its own styled-system.

Adding or changing tokens

Primitive scales live in packages/components/src/theme/tokens (colors, spacing, typography, radii, shadows, and friends). Semantic intents — every one with a light and a dark value — live in semantic-tokens.ts, and composite text styles in text-styles.ts, both beside it in src/theme. After editing the theme, run bun run codegen at the root to regenerate the package's styled-system (restarting dev regenerates this app's), and add a page or section under the Tokens section here so the new scale is documented.

Adding a component

Components follow the 3-tier token system: a recipe in packages/components/src/theme/recipes defines component-level tokens that read from semantic intents, and the React implementation lives beside it in packages/components/src. Single-element components use defineRecipe; anything with more than one styled element uses defineSlotRecipe. Register the recipe in the theme (src/theme/index.ts), export the component, and add a demo page under app/components. Running bun component <name> scaffolds all of that for you.

Checks

Run bun test for the theme and component tests, and bunx biome check for lint and formatting before opening a PR.