npm package: @pivotable/design-system
Description: Cross-platform design tokens for Pivotable iOS and Web applications
Author: Pivotable
Latest version: 0.1.19

# Pivotable Design System

Cross-platform design tokens for Pivotable iOS and Web applications.

## Overview

This package serves as the single source of truth for all design tokens, generating platform-specific outputs:

- **iOS**: Swift constants and extensions
- **Web**: CSS custom properties and TypeScript types

All tokens are defined in JSON format and automatically generate platform outputs via GitHub Actions.

## Installation

### iOS (Swift Package Manager)

Add the package dependency in Xcode:

1. File → Add Package Dependencies
2. Enter the repository URL: `https://github.com/pivotable-ai/design-system`
3. Select the version range (e.g., `from: "0.1.0"`)

Or add to your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/pivotable-ai/design-system", from: "0.1.0")
]
```

Then import in your Swift files:

```swift
import PivotableDesignSystem
```

### Web (npm)

```bash
npm install @pivotable/design-system
```

Import CSS in your `globals.css`:

```css
@import "@pivotable/design-system/build/web/tokens.css";
```

Import TypeScript types:

```typescript
import { tokens, tokenValues } from "@pivotable/design-system/build/web/tokens";
```

## Token Reference

### Colors

#### Adaptive Colors (change per theme)

- `background` - Primary background color
- `foreground` - Primary text color
- `primary` - Primary brand color for CTAs

#### Static Colors (same in both themes)

- `border` - Default border color
- `card` - Card background color
- `badge` - Badge background color

#### Semantic Colors (all static)

- `success` - Success state color (#4ADEB5)
- `error` - Error state color (#E73E3E)
- `warning` - Warning state color (#FFC857)
- `interviewing` - Interviewing status color (#EA580C)
- `accepted` - Accepted status color (#16A34A)

### Spacing

Spacing values use a 4pt base unit. Common values:

- `extraSmall` - 4pt
- `small` - 6pt
- `medium` - 16pt
- `large` - 24pt
- `extraLarge` - 32pt

Component-specific spacing tokens are also available (e.g., `buttonHorizontalPadding`, `cardPadding`, `standardPadding`).

### Typography

Font sizes match iOS Dynamic Type text styles:

- `largeTitle` - 34pt
- `title` - 28pt
- `title2` - 22pt
- `title3` - 20pt
- `headline` - 17pt (semibold)
- `body` - 17pt
- `callout` - 16pt
- `subheadline` - 15pt
- `footnote` - 13pt
- `caption` - 12pt
- `caption2` - 11pt

Font weights: `regular` (400), `medium` (500), `semibold` (600), `bold` (700)

### Radius

- `cornerRadius` - 16pt (standard corner radius for cards and buttons)

## Platform Examples

### iOS Swift

```swift
import SwiftUI
import PivotableDesignSystem

struct MyView: View {
    var body: some View {
        VStack(spacing: PivotSpacing.medium) {
            Text("Hello")
                .foregroundColor(.foreground)
                .padding(PivotSpacing.standardPadding)

            Button("Click me") {
                // Action
            }
            .background(Color.primary)
            .foregroundColor(.background)
            .cornerRadius(PivotRadius.cornerRadius)
        }
        .background(Color.background)
    }
}
```

### Web CSS

```css
.my-component {
  background-color: var(--colorBackground);
  color: var(--colorForeground);
  padding: var(--spacingStandardPadding);
  border-radius: var(--radiusCornerRadius);
}

.primary-button {
  background-color: var(--colorPrimary);
  color: var(--colorBackground);
}
```

### Web TypeScript/React

```typescript
import { tokens, tokenValues } from "@pivotable/design-system/build/web/tokens";

// Use CSS variables
const styles = {
  backgroundColor: tokens.color.background,
  padding: tokens.spacing.standardPadding,
};

// Use actual hex values for calculations
const primaryHex = tokenValues.color.light.primary; // '#153243'
```

## Architecture

### Token Structure

Tokens are organized by category:

```
tokens/src/
├── colors/
│   ├── light.json    # Light theme colors
│   └── dark.json     # Dark theme colors
├── spacing/
│   └── scale.json    # Spacing scale
├── typography/
│   ├── font-families.json
│   ├── font-sizes.json
│   ├── font-weights.json
│   └── line-heights.json
└── radius/
    └── scale.json
```

### Build Process

1. **Style Dictionary** processes token JSON files
2. **Custom transforms** convert tokens to platform-specific formats
3. **Formats** generate Swift, CSS, and TypeScript outputs
4. **GitHub Actions** runs build on every push to main

### Generated Outputs

- **iOS**: `Sources/PivotableDesignSystem/*.swift`
- **Web**: `build/web/tokens.css`, `build/web/tokens.ts`

## Contributing

### Adding New Tokens

1. Edit the appropriate JSON file in `tokens/src/`
2. Follow existing naming conventions (camelCase)
3. Add descriptions for all new tokens
4. Run `npm run validate` to check for issues
5. Submit a pull request

### Modifying Existing Tokens

1. Update the token value in the JSON file
2. Ensure adaptive colors have both light and dark values
3. Run validation to check contrast ratios
4. Update any affected documentation

### Pull Request Process

1. Create a feature branch
2. Make your changes
3. Run `npm run validate` and `npm run build`
4. Ensure all tests pass
5. Submit PR with clear description

## Migration Guide

### From Old Colors.swift

**Old:**

```swift
Color.appPrimary
Color.appBackground
Constants.standardPadding
```

**New:**

```swift
import PivotableDesignSystem

Color.primary
Color.background
PivotSpacing.standardPadding
```

### From Old CSS Variables

**Old:**

```css
var(--primary)
var(--background)
```

**New:**

```css
var(--colorPrimary)
var(--colorBackground)
```

See the [Migration Strategy](#migration-strategy) section for detailed migration steps.

## Troubleshooting

### iOS: "No such module 'PivotableDesignSystem'"

- Ensure the package is added to your project dependencies
- Check that the version in Package.swift matches the available versions
- Clean build folder (Product → Clean Build Folder)

### Web: CSS variables not working

- Ensure `tokens.css` is imported in your `globals.css`
- Check that CSS variables are prefixed with `--` (e.g., `--colorPrimary`)
- Verify the package is installed: `npm list @pivotable/design-system`

### TypeScript: Types not found

- Ensure `tokens.ts` is imported from the correct path
- Check that TypeScript can resolve the module
- Try reinstalling: `npm install @pivotable/design-system`

## Versioning

We use semantic versioning:

- **Minor Version** (0.x.0): New tokens added, non-breaking changes
- **Major Version** (x.0.0): Tokens removed or renamed

### Breaking Changes

Breaking changes are announced in release notes and require team approval. A deprecation period of at least 2 minor versions is provided before removal.

## License

MIT

## Support

For issues, questions, or contributions, please open an issue on GitHub.