Carbon Design System
Add to your project
DESIGN.md encodes Carbon Design System's visual language for AI coding tools. Add it to your project so Claude Code, Cursor, or any agent that reads files can reference it directly.
Quick start
Fetch /raw/design-systems/carbon/design-md/DESIGN.md and use it as the design foundation for this project.
Overview
Carbon is IBM's open-source design system for digital products and experiences. Now in its fourth major iteration (v11), Carbon provides a comprehensive set of working code, design tools, and guidelines for building consistent IBM product interfaces.
Carbon's design philosophy centers on enabling IBM's diverse product portfolio to achieve visual and behavioral consistency without sacrificing team autonomy. It achieves this through a role-based token system that decouples design decisions from implementation — tokens define what a color or type style does in the UI, while themes define the actual values. A product team can adopt a dark theme or brand customization by changing token values, not component code.
Key characteristics:
- Neutral-first color system: The IBM Design Language gray palette dominates; blue is the single primary action color
- Four built-in themes: White and Gray 10 (light), Gray 90 and Gray 100 (dark) — all designed for the full range of IBM product contexts
- Two-tier token architecture: Primitive palette (
@carbon/colors) → semantic role tokens (@carbon/themes); no three-tier component token layer - Productive/Expressive type split: A unique typographic model that maintains separate styles for dense product interfaces vs. editorial/marketing contexts using the IBM Plex typeface family
- IBM Plex typeface: Carbon's type system is built exclusively on IBM Plex, IBM's open-source typeface
When to reference this system:
- Enterprise SaaS and B2B product interfaces with dense, data-heavy layouts
- Products requiring a proven IBM Design Language implementation
- Teams building in React who want a battle-tested enterprise component library
- Reference for neutral-first color systems with a flat palette (no algorithmic generation)
- Reference for two-tier token architectures (primitive + semantic, no component tier)
When not to use as primary reference:
- Consumer mobile apps (M3 is stronger for iOS/Android-native feel)
- Projects requiring expressive, personalized, or brand-forward color systems
- Non-React web projects (community libs exist but React is the primary supported target)
Sources
| Content Type | Source | Notes |
|---|---|---|
| Guidance | https://carbondesignsystem.com | JavaScript SPA; content accessed via Firecrawl |
| Implementation | https://carbondesignsystem.com/developing/ | React framework docs |
| Color palette | https://github.com/carbon-design-system/carbon/blob/main/packages/colors/src/colors.ts | Raw TypeScript source |
| Theme tokens | https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/white.js | White theme semantic mappings |