Spellbook

Spellbook design system used by Tailscale web projects. Not maintained for external use.

Development Setup

Prerequisites

Ensure you have the following tools installed:

• Node.js 22.14.0 (use nvm to manage Node versions)

  nvm use 22.14.0

• Yarn 1.22.19 (package manager)

  npm install -g [email protected]

Getting Started

1. Clone the repository

   git clone https://github.com/tailscale/spellbook.git
   cd spellbook

2. Install dependencies

   yarn install

3. Start Storybook for development

   yarn storybook

   This will start Storybook on http://localhost:6006 (or the next available port)

Available Scripts

• yarn storybook - Start Storybook development server
• yarn build-storybook - Build Storybook for production
• yarn build - Build the component library for production
• yarn test - Run tests with Vitest

Environment Compatibility

This project has been tested and works with:

• Node.js 22.14.0 (recommended for team consistency)

Package Management

This project uses Yarn v1 as the package manager. The yarn.lock file should be committed, and package-lock.json should be ignored/removed if present.

Repo Structure:

spellbook/
├── src/
│   ├── components/
│   │   ├── button/
│   │   │   ├── button.tsx
│   │   │   ├── button.stories.tsx
│   │   ├── ...
│   ├── assets/
│   │   ├── fonts/
│   │   └── images/
│   ├── hooks/
│   ├── utils/
│   ├── tailwind.css
│   └── index.ts    # barrel file for listing official exports of the library

Component Development

Components are located in src/components/ and follow these patterns:

1. OSS-ready structure with proper style mappings
2. Comprehensive TypeScript types and exported constants
3. Accessibility features with proper ARIA attributes
4. Storybook stories for documentation and testing

Example component structure:

src/components/button/
├── button.tsx           # Main component
├── button.stories.tsx   # Storybook stories
├── button.md            # Description markdown (optional)

Styling Guidelines

• Use the .button, .input, and other base CSS classes from src/tailwind.css
• Follow the established design tokens and color system
• Ensure components have rounded corners and consistent spacing
• Support both light and dark themes

Contributing

When adding or modifying components:

1. Ensure TypeScript strict mode compliance
2. Add comprehensive Storybook stories
3. Include proper accessibility attributes
4. Follow the established component patterns
5. Export components from src/index.ts

Troubleshooting

Node.js Version Issues: If you encounter build errors, ensure you're using Node.js 22.14.0:

node --version  # Should output v22.14.0

Package Manager Issues: If dependencies fail to install, try:

rm -rf node_modules yarn.lock
yarn install