@bitrise/bitkit-v2

Bitrise Design System Components built with Chakra UI v3.

Browse the component library in Storybook (Google auth required)

Using with AI assistants (Claude Code, Cursor, Codex, etc.)

If you're prototyping or vibe-coding with an AI assistant, do this before writing any Bitkit code:

1. Configure the hosted Storybook MCP so the AI can query live component props, examples, and tokens instead of guessing. Add to your project's .mcp.json:

{
  "mcpServers": {
    "bitkit-storybook-mcp": {
      "url": "https://storybook.services.bitrise.dev/projects/bitkit-v2/production/mcp",
      "type": "http"
    }
  }
}

2. Reference Bitkit's AGENTS.md so the AI picks up component naming, the state prop pattern, semantic token rules, and other library conventions. Add to your project's own AGENTS.md (or CLAUDE.md):

@./node_modules/@bitrise/bitkit-v2/AGENTS.md

The hosted Storybook itself is browsable at https://storybook.services.bitrise.dev/projects/bitkit-v2/production/ (Google auth required).

Features

• Custom Design System: Complete Bitrise brand implementation
• Built with Chakra UI v3: Latest Chakra UI features and performance
• TypeScript: Full TypeScript support with auto-generated types
• Self-hosted Fonts: Figtree and Source Code Pro bundled via BitkitProvider
• Pinned Peer Dependencies: Bitkit declares Chakra, Emotion and the Chakra CLI as pinned peers so your tree stays deduped

Installation

# Runtime peers — required for Bitkit to render
npm install @bitrise/bitkit-v2 @chakra-ui/[email protected] @emotion/[email protected]

# Build-time peer — required so the bundled postinstall hook can generate bitkit-specific theme typings
npm install --save-dev @chakra-ui/[email protected]

Chakra UI and Emotion are declared as peer dependencies so the host app owns the single copy of Chakra in the tree. Install them at the exact versions Bitkit pins — any other version (including patch bumps like 3.37.1) triggers a peer mismatch warning, and a different minor/major may also cause runtime API incompatibility against Bitkit's compiled output. Duplicate Chakra installs only show up if some other transitive dependency drags in a different Chakra version on top of the drift, but when they do they silently break BitkitProvider's theme context, which is exactly the failure mode pinned peers protect against.

@chakra-ui/cli is a peer too — Bitkit's postinstall hook uses it to generate Chakra theme typings into your project's node_modules. Install it as a devDependency in the host app so the hook can find it.

Production-only installs (npm ci --omit=dev, pnpm install --prod, etc.): because @chakra-ui/cli is conventionally installed in the host's devDependencies, it will be skipped — your package manager may emit an unmet-peer warning or, with strict peer enforcement (e.g. pnpm's strict-peer-dependencies=true), fail the install. The bundled postinstall hook itself detects the missing CLI, prints a notice and exits cleanly. Theme typings are a development-time concern, so production environments don't need the CLI; if your prod install is configured for strict peers, either set strict-peer-dependencies=false for the deploy step, allow-list @chakra-ui/cli as a missing peer, or install the CLI as a regular dependency instead of a devDependency.

Requirements

• React 18+ (peer dependency)
• React DOM 18+ (peer dependency)
• @chakra-ui/react 3.37.0 (peer dependency, pinned)
• @emotion/react 11.14.0 (peer dependency, pinned)
• @chakra-ui/cli 3.37.0 (peer dependency, pinned — used by the bundled postinstall typegen hook; install as a devDependency in the host app)

Theme typings

Bitkit ships a Chakra UI v3 theme with custom recipes, semantic tokens, and design tokens. For TypeScript autocompletion to recognize bitkit-specific values (e.g. <BitkitButton variant="ai-primary">, colors.purple.60), Chakra's typegen must run in your project's node_modules after install.

This happens automatically via a postinstall hook bundled with the package, as long as @chakra-ui/cli is installed in the host app (it's declared as a peer dependency for this reason).

If the postinstall is skipped (e.g. @chakra-ui/cli is not installed, you ran npm install --ignore-scripts, or a CI runner blocks lifecycle scripts), regenerate the typings manually:

npx chakra typegen node_modules/@bitrise/bitkit-v2/dist/theme/index.js

You can verify it worked by checking that <BitkitButton variant="ai-primary" /> type-checks in your editor while <BitkitButton variant="solid" /> errors.

Quick Start

import { BitkitProvider, BitkitButton } from '@bitrise/bitkit-v2';

function App() {
  return (
    <BitkitProvider>
      <BitkitButton variant="primary">Hello Bitrise!</BitkitButton>
    </BitkitProvider>
  );
}

Development

Requirements

• Node.js 24.x+ (see .tool-versions for the exact version used in development)

Commands

# Install dependencies
npm install

# Start Storybook
npm run storybook

# Build the library
npm run build

# Generate theme types
npm run theme:generate-types

Export SVG icons from Figma

First you should create a Figma Personal Access Token to acces to the Bitkit Foundations file: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens

FIGMA_TOKEN=<your-personal-access-token> npm run generate:icons

Manual Icon Overrides

A few icons are hand-maintained instead of coming from Figma (e.g. the drag handle, the animated spinners). A manual icon always uses both markers together:

1. *.manual.svg — name the source icon-<name>-<size>.manual.svg. On every run the generator deletes any Figma-exported icon-<name>-<size>.svg with a .manual.svg sibling, so figma-export can never overwrite it. Draw monochrome icons with #2B0E3F (svgr rewrites it to currentColor).
2. // @generate:skip in the first lines of the .tsx — so the generator never regenerates the component. It's still exported as long as the .manual.svg exists in lib/svgs/.

// @generate:skip
// Manually maintained icon.

import { Icon, type IconProps } from '@chakra-ui/react/icon';
// ... import the *.manual.svg and render it

Current manual icons: IconDragHandle and the IconSpinner* icons (the spinners also default color to a semantic icon/* token). Everything else comes from Figma — leave it to the generator.

License

MIT

Contributing

Please see our contributing guidelines.