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:

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

Then import in your Swift files:

import PivotableDesignSystem

Web (npm)

npm install @pivotable/design-system

Import CSS in your globals.css:

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

Import TypeScript types:

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

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

.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

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:

Color.appPrimary
Color.appBackground
Constants.standardPadding

New:

import PivotableDesignSystem

Color.primary
Color.background
PivotSpacing.standardPadding

From Old CSS Variables

Old:

var(--primary)
var(--background)

New:

var(--colorPrimary)
var(--colorBackground)

See the 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.