The Three-Tier Hierarchy
Every token in CocoKits lives in one of three tiers. The tiers form a strict hierarchy — tokens in a lower tier may only reference tokens in the tier directly above them.
T1
Primitives / Color
Mode: Default
Primitives / Spacing
Mode: Default
Primitives / Typography
Mode: Default
Primitives / Radius
Mode: Default
↓
T2
Brand Palette
Modes: Brand-A, Brand-B, …
Semantic / Color
Modes: Light, Dark
Semantic / Typography
Mode: Default
↓
T3
Color / Active
Modes: neutral, brand, info, success, warning, danger, contrast
Button / Size
Modes: sm, md, lg
Button / Structure
Mode: Default
Toggle / Size & Structure
+ all other components…
The Golden Rule
A token may only reference tokens in the tier directly above it. Component tokens → reference → Semantic tokens → reference → Primitive tokens. No skipping tiers. No circular references. No component token referencing a primitive directly.
A token may only reference tokens in the tier directly above it. Component tokens → reference → Semantic tokens → reference → Primitive tokens. No skipping tiers. No circular references. No component token referencing a primitive directly.
What Each Tier Does
| Tier | Name | Purpose | Example Token | Mode Examples |
|---|---|---|---|---|
| Tier 1 | Primitives | Raw values. No semantic meaning. Never used directly by components. | purple-600: #9333EA |
Default only |
| Tier 2 | Semantic | Named aliases with intent. Brand, light/dark switching lives here. | brand-color: {purple-600} |
Light / Dark, Brand-A / Brand-B |
| Tier 3 | Component | Scoped to a specific component. References Tier 2 for colors, contains raw values only for component-specific dimensions. | button-height: 40px |
sm / md / lg, Default |
Why Not Two Tiers? Why Not Four?
Two tiers (Primitive + Component) would mean components reference colors directly. Switching a brand would require updating every component collection — no shared semantic layer to update.
Four tiers would add indirection with no structural benefit. The three-tier model perfectly matches the three distinct switching needs: brand switching (Tier 1→2, Brand Palette), dark mode (Tier 2, Semantic Color), and component size/color (Tier 3).
The Three Independent Dimensions
The architecture is designed so three things can change independently without affecting each other:
The architecture is designed so three things can change independently without affecting each other:
- Brand — switch Brand Palette mode (Brand-A vs Brand-B)
- Light/Dark — switch Semantic Color mode (Light vs Dark)
- Component Color/Size — switch Color/Active mode or Size collection mode per instance
Figma ↔ Code Mapping
| Figma Concept | Code Equivalent |
|---|---|
| Variable collection | A CSS file or SCSS partial with custom properties |
| Variable mode | [data-attribute] selector or CSS class |
| Variable binding | property: var(--token-name) |
| Mode inheritance (parent → child) | CSS cascade (custom properties inherit) |
| Text style | CSS class with multiple typography properties |
| Color style | CSS custom property value referenced in component CSS |