🎨 Chuk Design System

A universal design token system with multi-format export capabilities. Define your design system once, export to Canva CSS, Remotion TypeScript, python-pptx, standard CSS, and W3C Design Tokens JSON.

✨ Features

• 🎨 Universal Design Tokens: Colors, typography, spacing, and motion
• 📦 Multi-Format Export: Canva, Remotion, PPTX, CSS, W3C JSON
• 🎭 7 Pre-Built Themes: Tech, Finance, Education, Lifestyle, Gaming, Business, Minimal
• 🔒 Type-Safe: Pydantic models with full validation
• ✅ Well-Tested: 89% test coverage with 200+ tests
• 🚀 MCP Server: Claude integration ready
• 📱 Platform-Aware: Safe areas for YouTube, TikTok, Instagram
• 🎬 Video-Optimized: Frame-perfect durations and Remotion springs

🚀 Quick Start

Installation

# Using uv (recommended)
uv pip install -e .

# Or using pip
pip install -e .

Basic Usage

from chuk_design_system.themes import get_theme
from chuk_design_system.exporters import export_to_canva_css

# Get a theme
theme = get_theme("tech")

# Export to Canva CSS
css = export_to_canva_css(theme)
print(css)

🎨 Interactive Showcase

View the design system visually:

# Generate PNG images + open HTML showcase
make showcase

# Open HTML showcase only
make showcase-html

The interactive HTML showcase features click-to-copy color swatches, hover animations for easing curves, live typography samples, and visual gradients.

📚 Design System Structure

Colors

• Palettes: Tailwind-inspired scales (50-950) for 13+ hues
• Semantic Colors: Role-based naming (primary, secondary, success, warning, error)
• Gradients: 6 pre-defined gradients (sunset, ocean, forest, flame, aurora, cosmic)
• Chart Colors: 8-color sequence for data visualization

Typography

• Font Families: Display, Body, Monospace, Decorative
• Multi-Resolution Scales: Web (16px), PPTX (18pt), Video 1080p (40px), Video 4K (80px)
• Text Styles: Hero Title, Title, Heading, Body, Caption
• Font Weights: Thin (100) to Black (900)

Spacing

• 8px Unit System: Canva-compatible (1u = 8px)
• Platform Safe Areas: YouTube Shorts, TikTok, Instagram Story
• Grid Systems: 4, 8, 12 column grids

Motion

• Durations: Video-optimized with frame conversions (30fps, 60fps)
• Easing Curves: Linear, Ease Out, Ease In Out, Smooth, Snappy, Bouncy
• Spring Configs: Remotion-compatible physics
• Transitions: Enter/exit presets (fade, slide, scale)

🎭 Available Themes

📦 Export Formats

Canva CSS

from chuk_design_system.exporters import export_to_canva_css
css = export_to_canva_css(theme)
# Output: --content-primary: #3b82f6;

Remotion TypeScript

from chuk_design_system.exporters import export_to_remotion_ts
ts_code = export_to_remotion_ts(theme)
# Output: export const colorPrimary = "#3b82f6";

python-pptx

from chuk_design_system.exporters.pptx import create_pptx_theme_dict
pptx_theme = create_pptx_theme_dict(theme)

Standard CSS

from chuk_design_system.exporters import export_to_css
css = export_to_css(theme)

W3C Design Tokens JSON

from chuk_design_system.exporters import export_to_w3c_json
json_str = export_to_w3c_json(theme)

🛠️ Development

Setup

make setup

Testing

make test-cov      # Run tests with coverage
make test-watch    # Run tests in watch mode
make test-quick    # Quick test (stop on first failure)

Code Quality

make format        # Format code
make lint          # Run linters
make type-check    # Type checking
make all           # Run all checks

📖 Usage Examples

Export All Themes

from chuk_design_system.themes import THEMES, get_theme
from chuk_design_system.exporters import export_to_canva_css

for theme_name in THEMES.keys():
    theme = get_theme(theme_name)
    css = export_to_canva_css(theme)
    with open(f"exports/{theme_name}.css", "w") as f:
        f.write(css)

Custom Token Access

from chuk_design_system.tokens import ColorTokens, TypographyTokens

colors = ColorTokens()
primary_blue = colors.palette["blue"][500]  # #3b82f6

typography = TypographyTokens()
hero_style = typography.get_text_style("hero_title", "web")

Motion Tokens for Remotion

from chuk_design_system.tokens import MotionTokens

motion = MotionTokens()
spring_config = motion.get_spring_config("smooth")
# {'damping': 22.0, 'stiffness': 150.0, 'mass': 1.0}

frames = motion.get_duration_frames("normal", fps=30)  # 9 frames

🔗 Integration

This design system powers:

• chuk-mcp-remotion: Video generation
• chuk-mcp-pptx: PowerPoint generation
• Canva Apps: Design apps with matching UI

🤖 MCP Server

Use with Claude via Model Context Protocol:

{
  "mcpServers": {
    "chuk-design-system": {
      "command": "python",
      "args": ["-m", "chuk_design_system.server"]
    }
  }
}

📝 Makefile Commands

🧪 Test Coverage

Current coverage: 89% (729 statements, 82 missed)

• tokens/colors.py: 100%
• tokens/typography.py: 100%
• tokens/spacing.py: 100%
• tokens/motion.py: 100%
• exporters/canva.py: 100%
• exporters/remotion.py: 100%
• exporters/pptx.py: 94%

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run make all to verify
5. Submit a pull request

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Inspired by Tailwind CSS color palette
• Canva's design token system
• Remotion's spring physics
• W3C Design Tokens specification