13.1 CSS Custom Property Architecture
The token generator exports three layers of CSS custom properties, applied at different scopes:
CSS — :root (Tier 1 + Tier 2 defaults)
:root {
/* Tier 1 — Primitives */
--purple-600: #9333ea;
--gray-50: #f9fafb;
--spacing-4: 4px;
--font-size-sm: 14px;
/* Tier 2 — Semantic (Light mode default) */
--brand-color: var(--purple-600);
--brand-on-color: #ffffff;
--brand-container: var(--purple-100);
--brand-on-container: var(--purple-800);
--brand-outline: var(--purple-600);
--brand-focus: rgba(147, 51, 234, 0.4);
--surface-default: #ffffff;
--on-surface: var(--gray-900);
--disabled-surface: var(--gray-100);
}
CSS — Dark mode override
[data-cck-theme="dark"] {
/* Override Tier 2 semantic tokens for dark theme */
--brand-color: var(--purple-400); /* lighter for dark bg */
--brand-on-color: var(--purple-900);
--brand-container: var(--purple-900);
--brand-on-container: var(--purple-200);
--surface-default: var(--gray-900);
--on-surface: var(--gray-50);
--disabled-surface: var(--gray-800);
}13.2 Class Naming Convention
Format: .cck-{component}__{prop}--{value}
| Segment | Meaning | Example |
|---|---|---|
cck- | Namespace prefix (CocoKits) | cck- |
{component} | Component name, lowercase, hyphenated | button, form-field |
__{prop} | BEM element — the property being modified | __color, __type, __size |
--{value} | BEM modifier — the value | --brand, --primary, --lg |
HTML usage examples
<!-- Brand primary large button -->
<button class="cck-button
cck-button__color--brand
cck-button__type--primary
cck-button__size--lg">
Save
</button>
<!-- Danger outline medium button -->
<button class="cck-button
cck-button__color--danger
cck-button__type--outline
cck-button__size--md">
Delete
</button>13.3 Token Generator Outputs
| Output Format | Use Case |
|---|---|
SCSS variables ($brand-color: …) | Sass/SCSS components that reference tokens by name |
CSS custom properties (--brand-color: …) | Global CSS file loaded once; all tokens available in browser |
| CSS mixins | Component stylesheets include size and structural mixins per component |
| TypeScript dictionary | Type-safe token access in JS/TS code; animation keyframes, dynamic styles |
13.4 Adding a New Color Family
1
Add base colors to Brand Palette
In each brand mode (Brand-A, Brand-B, …), add a
In each brand mode (Brand-A, Brand-B, …), add a
my-family-base and related tokens pointing to primitives.
2
Add 6 role tokens to Semantic / Color
In both Light and Dark modes, add
In both Light and Dark modes, add
my-family-color, my-family-on-color, my-family-container, my-family-on-container, my-family-outline, my-family-focus.
3
Add a new mode to Color / Active
Name it
Name it
my-family. Set each of the 6 tokens to point to the corresponding my-family-* semantic token.
4
Add one CSS class per component
.cck-button__color--my-family { --cck-color: var(--my-family-color); /* ...all 6 */ }
No other code changes needed — all existing type classes automatically work.
13.5 Adding a New Component
1
Create
Add sm/md/lg modes. Define all dimension and typography tokens.
{Component}/Size collection in FigmaAdd sm/md/lg modes. Define all dimension and typography tokens.
2
Create
Add tokens for fixed colors (disabled states, structural elements). Reference Semantic/Color globals.
{Component}/Structure collectionAdd tokens for fixed colors (disabled states, structural elements). Reference Semantic/Color globals.
3
Wire family colors to Color / Active
Inside the component, bind color-family fills directly to
Inside the component, bind color-family fills directly to
Color/Active → color, container, etc. Do not create new tokens.
4
Write CSS color + type classes
Follow the
Follow the
.cck-{comp}__color--{family} and .cck-{comp}__type--{type} pattern. Each color class sets the 6 --cck-* variables. Each type class reads them.