Why one shared Color/Active collection instead of separate color collections per component?
If every component had its own color collection, adding a new color family would require changes in 15+ places. The shared
Color/Active collection means one change affects all components. It also ensures perfect color consistency — Brand Blue is literally the same token everywhere, not 15 different tokens that happen to look similar.
Why only 6 tokens in Color/Active instead of more?
We audited every component and found that no component needs more than 6 distinct color roles. Adding more tokens would create "unused slots" in most components, and coupling between the design and development teams about which slot means what. The 6 roles (
color, on-color, container, on-container, outline, focus) are sufficient to describe any interactive component's visual behavior.
Some components seem to use unusual Color/Active tokens. Is that intentional?
Yes. For example, a "basic" button uses
on-container for its text color even though it has no container background. This is intentional — on-container is the right "foreground color against the page surface" role for the brand family. Using it ensures the text color is always readable and on-brand, while remaining consistent with how other types use the same slot.
What does the "neutral" color family look like? Isn't it just gray?
Neutral can have a slight color temperature influenced by the brand. With Brand Palette's
neutral-dark / neutral-light tokens, a brand can shift its neutral toward warm beige or cool blue-gray. This gives the entire design a coherent atmosphere, not just the accent colors.
Why are states (hover, disabled) in Variant Properties but Color and Size in Modes?
States change the component's structure — a disabled button might hide a loading indicator, or a hover state adds an overlay. That structural change is what Variants are for. Color and Size only change token values, not the structure. Modes are the Figma mechanism for changing token values without touching the component's layer structure.
How do I handle typography scaling in Figma without breaking the architecture?
Use Figma Text Styles that reference variables internally. Apply the style to the text node — don't bind a font-size variable directly to the text node, as it would conflict with the style. When the
Button/Size mode changes to "lg", the Button/Label text style (which internally references button-font-size) automatically picks up the larger value.
Can I use this token system without Figma?
Yes. The CSS custom property output from the token generator works independently of Figma. If you're a developer working code-first, you can define your token values directly in CSS/SCSS. The three-tier architecture is a naming and organization convention that's equally valid in pure code.
How does dark mode work in code?
Add
data-cck-theme="dark" to the <html> element (or any ancestor). The CSS selector [data-cck-theme="dark"] overrides all --semantic-* tokens. Since components only reference semantic tokens (never primitives), they automatically adapt. You don't need to change any component classes.
How should I apply disabled states in CSS?
Use the native
:disabled pseudo-class along with structural tokens: .cck-button:disabled { background-color: var(--button-disabled-bg); }. Disabled tokens live in the Structure collection and are the same across all color families — disabled styling is structural, not family-specific.
A child element inside a component isn't responding to color mode changes. Why?
Check whether that element's color is bound to a structural token instead of a
Color/Active token. Structural tokens don't change with color mode — that's by design. For example, the toggle thumb is always white (structural). If you expect it to change, re-evaluate whether it should actually be bound to a family color role.
In Figma, the mode I set isn't applying to a child component. How do I debug?
Walk up the Layers panel. The nearest ancestor with an explicit mode set for that collection wins. If a child component has its own explicit mode set (even at creation time), it will override the parent. To reset it, select the component instance, go to the right panel under "Layer", and set the collection to "(Match parent)".
Why use a 3-tier system? Why not 2 tiers or 4 tiers?
2 tiers (raw → component) don't support simultaneous brand + dark mode switching — you'd end up with a combinatorial explosion of collections. 4 tiers add complexity without additional power — the 3rd tier already decouples everything needed. Three tiers is the minimum necessary for complete independence between brand, theme, component type, and component size.