1 — Multi-Brand Support
Problem: The same component library needs to support two brands — Brand-A (purple) and Brand-B (teal). Without tokens, every color must be duplicated and versioned separately.
Solution: The Brand Palette collection has modes
Brand-A and Brand-B. Switching the mode changes every brand-derived color instantly. Semantic and component tokens are unchanged. Zero duplication.2 — Dark Mode
Problem: Dark mode requires completely different color values for most UI elements. Maintaining a dark variant of every component stylesheet is error-prone and doubles the maintenance burden.
Solution: The Semantic Color collection has
Light and Dark modes. In code, switching [data-cck-theme="dark"] on the root element swaps all token values. Components never change — only the token values at the root.3 — Combinatorial Variant Explosion
Problem: A button has 4 types × 7 colors × 3 sizes × 5 states = 420 Figma variants. This makes the component file enormous, slow, and nearly impossible to maintain.
Solution: Only Type and State are Figma variant properties (because they can have different node structures). Color and Size are controlled via variable mode overrides per instance. Result: 4 × 5 = 20 variants — a 95% reduction.
4 — Color × Type Independence
Problem: When adding a new color family, every component's color handling needs to be updated. When adding a new component type, new color mappings must be written for every color family — creating an O(n×m) maintenance problem.
Solution: The shared
Color / Active collection bridges semantic colors to components. Color classes set --cck-color, --cck-on-color, etc. Type classes read those variables. Adding a new color = one color class. Adding a new type = one type class. The two dimensions are completely independent.5 — Design–Code Drift
Problem: Figma files and CSS files evolve independently. Six months in, the "brand purple" in Figma is slightly different from the one in the codebase. No one knows which is correct. QA is painful.
Solution: Token values are defined in one place (JSON token definitions) and generated into both Figma variable JSON and CSS custom properties. Figma and code always reference the same source. The token generator enforces sync on every build.
6 — Typography Scaling in Figma
Problem: In Figma, you can't apply a text style AND bind a font-size variable to the same text node — the style overrides the variable. This means typography either can't use variables, or can't use named styles. Both options are bad.
Solution: Bind the variable inside the style definition. The text style
Button / Label has its font-size property bound to the button-font-size variable. Designers use the style; the variable drives the value. When the size mode changes, the style updates automatically.
These aren't theoretical problems. Every one was encountered during the initial build of CocoKits and required a specific architectural decision to resolve. The three-tier architecture is the outcome of solving all six simultaneously.