🎨 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
| Theme | Primary Color | Use Case |
|---|---|---|
| Tech | Blue (#3b82f6) | Technology, SaaS products |
| Finance | Green (#22c55e) | Financial services, dashboards |
| Education | Purple (#a855f7) | Learning platforms, courses |
| Lifestyle | Pink (#db2777) | Fashion, beauty, wellness |
| Gaming | Green (#10b981) | Gaming platforms, esports |
| Business | Blue (#3b82f6) | Corporate, professional services |
| Minimal | Zinc (#71717a) | Minimalist designs, portfolios |
📦 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
| Command | Description |
|---|---|
make help | Show all available commands |
make test-cov | Run tests with coverage report |
make format | Format code with black + ruff |
make showcase | Generate visual showcases |
make all | Run all checks |
🧪 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:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Run
make allto verify - 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