managarten/apps/picture/packages/design-tokens/.agent/agent.md

Design Tokens Package Agent

Module Information

Package: @picture/design-tokens Version: 0.1.0 Type: Shared design system tokens Location: /apps/picture/packages/design-tokens

Identity

I am the Design Tokens Agent for the Picture app. I maintain the centralized design system that provides consistent colors, spacing, typography, and theming across all Picture app platforms (web, mobile, landing).

Purpose

This package provides framework-agnostic design tokens that ensure visual consistency across:

• Mobile apps (React Native/Expo) via native theme helpers
• Web apps (SvelteKit) via Tailwind CSS preset
• Landing pages (Astro) via Tailwind CSS preset

The design system supports multiple theme variants (default, sunset, ocean) with both light and dark color modes.

Expertise

Design Token Categories

1. Colors (src/colors.ts)

   • Base color palette (blacks, whites, grays, brand colors)
   • Semantic colors for light/dark modes (background, surface, text, borders)
   • Status colors (success, warning, error, info)
   • Theme-specific colors (indigo/violet, orange/pink, sky/emerald)

2. Spacing (src/spacing.ts)

   • Standardized spacing scale (0px to 128px)
   • Border radius values (sm, md, lg, xl, 2xl, 3xl, full)

3. Typography (src/typography.ts)

   • Font size scale (xs to 8xl)
   • Font weights (regular, medium, semibold, bold)

4. Shadows (src/shadows.ts)

   • Box shadow definitions for web
   • Platform-appropriate shadow styles

5. Themes (src/themes/)

   • Default theme: Indigo/violet color scheme
   • Sunset theme: Orange/pink color scheme
   • Ocean theme: Sky/emerald color scheme
   • Each theme supports light/dark modes

Platform-Specific Exports

Tailwind CSS Preset (tailwind/preset.js)

• Complete Tailwind configuration with design tokens
• Color utilities for dark/light modes
• Spacing, typography, and shadow utilities
• Import in tailwind.config.js to apply tokens

React Native Helpers (native/theme.ts)

• getThemeColors(variant, mode): Get colors for a theme
• createNativeTheme(variant, mode): Create complete theme object
• getThemeVariants(): List available themes
• isValidThemeVariant(variant): Validate theme names

Code Structure

design-tokens/
├── src/
│   ├── index.ts              # Main export (all tokens)
│   ├── colors.ts             # Base & semantic colors
│   ├── spacing.ts            # Spacing & border radius
│   ├── typography.ts         # Font sizes & weights
│   ├── shadows.ts            # Shadow definitions
│   └── themes/
│       ├── index.ts          # Theme registry
│       ├── default.ts        # Indigo/violet theme
│       ├── sunset.ts         # Orange/pink theme
│       └── ocean.ts          # Sky/emerald theme
├── tailwind/
│   └── preset.js             # Tailwind CSS preset
├── native/
│   └── theme.ts              # React Native helpers
└── package.json

Key Patterns

Design Token Usage

Web (Tailwind CSS):

// tailwind.config.js
module.exports = {
  presets: [require('@picture/design-tokens/tailwind/preset')],
  // Use tokens: bg-primary, text-dark-bg, p-4, text-lg
}

Mobile (React Native):

import { createNativeTheme } from '@picture/design-tokens/native';

const theme = createNativeTheme('default', 'dark');
// Access: theme.colors.primary.default, theme.spacing[4], theme.fontSize.lg

Direct Import:

import { semanticColors, spacing, fontSize } from '@picture/design-tokens';

const darkColors = semanticColors.dark;
const padding = spacing[4]; // 16px
const textSize = fontSize.lg; // 18px

Theme Structure

Each theme provides:

• colors: Semantic color mappings for light/dark modes
• shadows: Platform-appropriate shadow styles
• opacity: Standard opacity values (disabled, overlay, hover, pressed)

Color Semantic Naming

• Backgrounds: background, surface, elevated, overlay
• Borders: border, divider
• Inputs: input.background, input.border, input.text, input.placeholder
• Text: text.primary, text.secondary, text.tertiary, text.disabled, text.inverse
• Brand: primary.*, secondary.*
• Status: success, warning, error, info
• UI: skeleton, shimmer, favorite, like, tag

Integration Points

Consumers

This package is consumed by:

• @picture/mobile - React Native mobile app
• @picture/mobile-ui - Mobile UI component library
• @picture/web - SvelteKit web app
• @picture/landing - Astro landing page

Build System

• Build tool: tsup for TypeScript compilation
• Outputs:
  • dist/ - Compiled JS/types for main export
  • native/ - React Native helper with types
  • tailwind/preset.js - Tailwind preset (no build needed)
• Build command: pnpm build
• Dev mode: pnpm dev (watch mode)

Design System Principles

1. Single source of truth: All visual tokens defined once
2. Framework agnostic: Tokens work across web and native
3. Theme support: Multiple color schemes with light/dark modes
4. Semantic naming: Intent-based naming (not color-based)
5. Type safety: Full TypeScript support with exported types

Common Operations

Adding a New Color

1. Add base color to src/colors.ts baseColors object
2. Map to semantic color in semanticColors.dark and semanticColors.light
3. Update Tailwind preset in tailwind/preset.js if needed
4. Run pnpm build to regenerate outputs

Creating a New Theme

1. Create src/themes/mytheme.ts following existing theme structure
2. Export from src/themes/index.ts
3. Add to themes object in src/themes/index.ts
4. Update Tailwind preset if theme-specific utilities needed
5. Run pnpm build

Modifying Spacing Scale

1. Update spacing object in src/spacing.ts
2. Update Tailwind preset theme.extend.spacing
3. Run pnpm build
4. Verify no breaking changes in consuming apps

Type Exports

Key exported types:

• BaseColors, SemanticColors, ColorMode
• Spacing, BorderRadius
• FontSize, FontWeight
• ThemeVariant, ThemeMode, Theme
• NativeTheme (from native helpers)

Notes

• Package is private (not published to npm)
• Peer dependency: tailwindcss >=3.0.0 (optional)
• Build generates both CJS and ESM formats for maximum compatibility
• Colors use hex values for broad platform support
• Shadow values are platform-specific (web uses box-shadow, native uses elevation)