Design Tokens

@cpod/tokens provides the complete CyberPod design system with CSS variables, Tailwind preset, and JavaScript/TypeScript exports for building consistent UIs.

Installation

npm install @cpod/tokens
# or
pnpm add @cpod/tokens
# or
yarn add @cpod/tokens

---

Design System Overview

The CyberPod design system includes:

• 🎨 Colors - Light/dark theme, semantic colors, chart colors
• ✍️ Typography - Font families, sizes, and weights
• 📏 Spacing - Consistent spacing scale (4px base)
• 🔵 Border Radius - Standard radius tokens
• 🎭 Shadows - Elevation shadows
• 📐 Breakpoints - Responsive design breakpoints
• 🔄 Animations - Duration, easing, and keyframes

---

Usage Methods

1. CSS Variables (Recommended)

Import CSS files and use variables directly:

/* Import in your global CSS */
@import "@cpod/tokens/css/variables.css";
@import "@cpod/tokens/css/themes.css";

/* Use in your styles */
.button {
  background-color: var(--cpod-primary);
  color: var(--cpod-primary-foreground);
  border-radius: var(--cpod-radius);
  padding: var(--cpod-spacing-3) var(--cpod-spacing-6);
}

2. Tailwind Preset

Use pre-configured Tailwind theme:

// tailwind.config.js
import { cyberpodPreset } from "@cpod/tokens";

export default {
  presets: [cyberpodPreset],
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
};

Then use Tailwind classes with CyberPod tokens:

<button className="bg-primary text-primary-foreground rounded-md px-6 py-3">
  Click me
</button>

3. JavaScript/TypeScript

Import tokens programmatically:

import { colors, spacing, typography } from "@cpod/tokens";

const styles = {
  color: colors.primary,
  fontSize: typography.sizes.md,
  padding: spacing[4],
};

---

Color System

Theme Colors

Light Theme

Token	CSS Variable	Hex	Usage
Primary	--cpod-primary	hsl(222 47% 11%)	Main brand color
Secondary	--cpod-secondary	hsl(210 40% 96%)	Secondary elements
Accent	--cpod-accent	hsl(210 40% 96%)	Accent highlights
Destructive	--cpod-destructive	hsl(0 84% 60%)	Error, delete actions
Muted	--cpod-muted	hsl(210 40% 96%)	Subtle backgrounds

Dark Theme

Token	CSS Variable	Hex	Usage
Primary	--cpod-primary	hsl(210 40% 98%)	Main brand color
Secondary	--cpod-secondary	hsl(217 33% 17%)	Secondary elements
Accent	--cpod-accent	hsl(217 33% 17%)	Accent highlights
Destructive	--cpod-destructive	hsl(0 63% 31%)	Error, delete actions
Muted	--cpod-muted	hsl(217 33% 17%)	Subtle backgrounds

Usage Example

/* CSS */
.card {
  background-color: var(--cpod-card);
  border: 1px solid var(--cpod-border);
  color: var(--cpod-card-foreground);
}

/* Tailwind */
<div className="bg-card border border-border text-card-foreground">
  Card content
</div>

Semantic Colors

All color tokens include foreground variants:

• --cpod-primary-foreground - Text on primary background
• --cpod-secondary-foreground - Text on secondary background
• --cpod-accent-foreground - Text on accent background
• --cpod-destructive-foreground - Text on destructive background

Chart Colors

Special colors for data visualization:

var(--cpod-chart-1)  /* Blue */
var(--cpod-chart-2)  /* Green */
var(--cpod-chart-3)  /* Orange */
var(--cpod-chart-4)  /* Purple */
var(--cpod-chart-5)  /* Red */

---

Typography

Font Families

// CSS
font-family: var(--cpod-font-sans);  /* Inter, system-ui */
font-family: var(--cpod-font-mono);  /* JetBrains Mono, monospace */

// Tailwind
<p className="font-sans">Sans-serif text</p>
<code className="font-mono">Monospace code</code>

Font Sizes

Token	Value	CSS Variable	Usage
xs	12px	--cpod-text-xs	Fine print
sm	14px	--cpod-text-sm	Small text
base	16px	--cpod-text-base	Body text
lg	18px	--cpod-text-lg	Large text
xl	20px	--cpod-text-xl	Headings
2xl	24px	--cpod-text-2xl	Large headings
3xl	30px	--cpod-text-3xl	Display
4xl	36px	--cpod-text-4xl	Hero

Usage Example

// Tailwind
<h1 className="text-4xl font-bold">Hero Title</h1>
<p className="text-base">Body paragraph</p>
<span className="text-sm text-muted-foreground">Helper text</span>

// CSS
h1 {
  font-size: var(--cpod-text-4xl);
  font-weight: 700;
}

---

Spacing

4px base unit scale for consistent spacing.

Token	Value	CSS Variable
0	0px	--cpod-spacing-0
1	4px	--cpod-spacing-1
2	8px	--cpod-spacing-2
3	12px	--cpod-spacing-3
4	16px	--cpod-spacing-4
5	20px	--cpod-spacing-5
6	24px	--cpod-spacing-6
8	32px	--cpod-spacing-8
10	40px	--cpod-spacing-10
12	48px	--cpod-spacing-12
16	64px	--cpod-spacing-16
20	80px	--cpod-spacing-20
24	96px	--cpod-spacing-24

Usage Example

// Tailwind (uses spacing scale automatically)
<div className="p-4 mt-6 mb-8">
  <div className="space-y-3">...</div>
</div>

// CSS
.container {
  padding: var(--cpod-spacing-4);
  margin-top: var(--cpod-spacing-6);
  gap: var(--cpod-spacing-3);
}

---

Border Radius

Token	Value	CSS Variable
none	0px	-
sm	4px	--cpod-radius-sm
md	8px	--cpod-radius
lg	12px	--cpod-radius-lg
xl	16px	--cpod-radius-xl
2xl	24px	--cpod-radius-2xl
full	9999px	-

Usage Example

// Tailwind
<div className="rounded-md">Default radius</div>
<div className="rounded-lg">Large radius</div>
<div className="rounded-full">Circle/pill</div>

// CSS
.button {
  border-radius: var(--cpod-radius);
}

.avatar {
  border-radius: var(--cpod-radius-full);
}

---

Shadows

5 elevation levels for depth hierarchy.

Token	CSS Variable	Usage
sm	--cpod-shadow-sm	Subtle elevation
md	--cpod-shadow-md	Moderate elevation
lg	--cpod-shadow-lg	High elevation
xl	--cpod-shadow-xl	Very high elevation
2xl	--cpod-shadow-2xl	Maximum elevation

Usage Example

// Tailwind
<div className="shadow-md">Card with shadow</div>
<div className="shadow-lg hover:shadow-xl transition-shadow">
  Interactive card
</div>

// CSS
.card {
  box-shadow: var(--cpod-shadow-md);
}

.modal {
  box-shadow: var(--cpod-shadow-2xl);
}

---

Breakpoints

Responsive design breakpoints for different screen sizes.

Breakpoint	Value	CSS	Usage
xs	475px	@media (min-width: 475px)	Small phones
sm	640px	@media (min-width: 640px)	Phones
md	768px	@media (min-width: 768px)	Tablets
lg	1024px	@media (min-width: 1024px)	Laptops
xl	1280px	@media (min-width: 1280px)	Desktops
2xl	1536px	@media (min-width: 1536px)	Large screens

Usage Example

// Tailwind (mobile-first)
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  ...
</div>

<h1 className="text-2xl md:text-3xl lg:text-4xl">
  Responsive heading
</h1>

// CSS
@media (min-width: 768px) {
  .container {
    max-width: 720px;
  }
}

---

Animations

Duration

Token	Value	Usage
fast	150ms	Quick transitions
normal	300ms	Standard transitions
slow	500ms	Smooth transitions

Easing

--cpod-ease-in: cubic-bezier(0.4, 0, 1, 1);
--cpod-ease-out: cubic-bezier(0, 0, 0.2, 1);
--cpod-ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);

Keyframes

Predefined animations like fade-in, slide-in, etc.

Usage Example

// Tailwind
<div className="transition-all duration-300 ease-in-out hover:scale-105">
  Smooth hover effect
</div>

// CSS
.button {
  transition: background-color 300ms var(--cpod-ease-in-out);
}

.button:hover {
  background-color: var(--cpod-primary-hover);
}

---

Customization

Override CSS Variables

Create a custom theme by overriding variables:

:root {
  /* Custom primary color */
  --cpod-primary: hsl(280 100% 70%);
  --cpod-primary-foreground: hsl(0 0% 100%);

  /* Custom radius */
  --cpod-radius: 16px;

  /* Custom font */
  --cpod-font-sans: "Your Font", system-ui, sans-serif;
}

Extend Tailwind Preset

Add custom tokens alongside CyberPod tokens:

// tailwind.config.js
import { cyberpodPreset } from "@cpod/tokens";

export default {
  presets: [cyberpodPreset],
  theme: {
    extend: {
      colors: {
        brand: "#your-color",
      },
      spacing: {
        128: "32rem",
      },
    },
  },
};

---

Complete Integration Example

Next.js with Tailwind

// tailwind.config.ts
import type { Config } from "tailwindcss";
import { cyberpodPreset } from "@cpod/tokens";

const config: Config = {
  presets: [cyberpodPreset],
  content: [
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
};

export default config;

// app/page.tsx
import { Button, Card, CardContent } from "@cpod/react";

export default function Home() {
  return (
    <div className="min-h-screen bg-background px-6 py-12">
      <div className="mx-auto max-w-4xl">
        <h1 className="text-4xl font-bold text-foreground mb-6">
          Welcome to CyberPod
        </h1>

        <div className="grid gap-6 md:grid-cols-2">
          <Card>
            <CardContent className="p-6">
              <h2 className="text-2xl font-semibold mb-3">
                Consistent Design
              </h2>
              <p className="text-muted-foreground mb-4">
                Use design tokens for a unified look across your app.
              </p>
              <Button variant="default">Get Started</Button>
            </CardContent>
          </Card>

          <Card>
            <CardContent className="p-6">
              <h2 className="text-2xl font-semibold mb-3">
                Fully Typed
              </h2>
              <p className="text-muted-foreground mb-4">
                TypeScript support with auto-completion.
              </p>
              <Button variant="outline">Learn More</Button>
            </CardContent>
          </Card>
        </div>
      </div>
    </div>
  );
}

---

TypeScript Types

All tokens are exported with TypeScript types:

import type {
  ColorToken,
  SpacingToken,
  RadiusToken,
  BreakpointToken,
} from "@cpod/tokens";

// Use in your types
type CustomTheme = {
  primary: ColorToken;
  spacing: SpacingToken;
  radius: RadiusToken;
};

---

Best Practices

1. Use Semantic Colors

// ✅ Good - Uses semantic color for status
<Badge variant="success">Active</Badge>
<Badge variant="destructive">Error</Badge>

// ❌ Avoid hardcoded colors
<Badge style={{ background: "#00ff00" }}>Active</Badge>

2. Consistent Spacing

// ✅ Good - Uses spacing scale
<div className="p-4 space-y-3">...</div>

// ❌ Avoid arbitrary values
<div className="p-[17px]">...</div>

3. Responsive Typography

// ✅ Good - Scales with breakpoints
<h1 className="text-2xl md:text-3xl lg:text-4xl">Title</h1>

// ❌ Missing responsive scaling
<h1 className="text-4xl">Title</h1>

4. Dark Mode Support

Always test in both themes:

// ✅ Good - Uses theme-aware colors
<div className="bg-card text-card-foreground">...</div>

// ❌ Fixed color (breaks dark mode)
<div className="bg-white text-black">...</div>

---

Reference

• React Components - Pre-built UI components
• Radix UI - Accessible primitives
• Tailwind CSS - Utility-first CSS