# Codex Design Tokens

> Build web UIs using Wikimedia Codex design tokens (CSS custom properties) for consistent styling. Supports custom components, themed applications, design-to-code conversion, MediaWiki integration, and standalone web apps with automatic light/dark mode.

- Skill: `santhoshtr/codex-design-tokens` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add santhoshtr/codex-design-tokens`
- Raw SKILL.md: https://api.skillmd.com/api/skills/santhoshtr/codex-design-tokens/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: santhoshtr (https://skillmd.com/u/santhoshtr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/santhoshtr/codex-design-tokens

---


# Wikimedia Codex Design Tokens

Design tokens are the smallest units that store visual styles and design decisions. The Wikimedia Codex design system provides 380+ tokens in CSS custom property format, enabling consistent UI development across applications. This skill helps developers use these tokens to build accessible, themeable web interfaces.

## When to Use This Skill

Use this skill when developers request help with:

- Building custom UI components using Codex design tokens
- Implementing Wikimedia visual style in web applications
- Converting design mockups to token-based CSS code
- Creating MediaWiki skins, extensions, or gadgets
- Building standalone web apps with Wikimedia theming
- Ensuring visual consistency and accessibility
- Supporting automatic dark mode switching
- Styling forms, buttons, cards, and other interactive elements

## Quick Start

### Installation

The simplest approach uses CDN links:

```html
<!-- Light mode tokens (always loaded) -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@wikimedia/codex-design-tokens/theme-wikimedia-ui.css"
/>

<!-- Dark mode tokens (loaded when prefers-color-scheme: dark) -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@wikimedia/codex-design-tokens/theme-wikimedia-ui-mode-dark.css"
  media="( prefers-color-scheme: dark )"
/>
```

### Using Tokens

Once imported, use tokens as CSS custom properties:

```css
.my-component {
  background-color: var(--background-color-base);
  color: var(--color-base);
  padding: 1rem;
  border: 1px solid var(--border-color-subtle);
}
```

## Core Workflows

### 1. Token Discovery Workflow

When implementing a design, find the right token:

1. **Identify the design property**: color, spacing, typography, border, shadow, etc.
2. **Determine the purpose**: base/default, interactive, state, status
3. **Select semantic token**: use the semantic name that matches intent, not raw values
4. **Apply the token**: use `var(--token-name)` in CSS

**Example**: Styling a primary button

- Purpose: Primary action → use `--color-progressive` (blue semantic color)
- Text color: white on blue → use `--color-inverted`
- Hover state: darker blue → use `--color-progressive--hover`
- Reference file: `references/color-tokens.md` and `references/component-patterns.md`

### 2. Building Components with Tokens

Follow this process for any component:

1. **Start with a template**: Use minimal starter from `assets/templates/basic-page.html`
2. **Apply base styles**: Use primary tokens for default appearance
3. **Add interactive states**: Implement hover, focus, active, disabled
4. **Verify contrast**: Codex tokens ensure WCAG compliance
5. **Test modes**: Open in light and dark environments to verify token switching
6. **Test accessibility**: Use keyboard navigation, screen reader compatibility

### 3. Design-to-Code Conversion

When given a design specification:

1. **Color mapping**: Identify each color in design → map to semantic token

   - Blues → `--color-progressive` family
   - Reds → `--color-destructive` family
   - Grays → `--color-base`, `--color-subtle` families
   - Reference: `references/color-tokens.md`

2. **Spacing mapping**: Measure visual spacing → map to token scale

   - Standard spacing uses consistent increments
   - Use semantic tokens rather than hardcoded values
   - Reference: `references/tokens-complete.md`

3. **Typography mapping**: Font size and style → map to typography tokens

   - Reference: `references/typography-tokens.md`

4. **State handling**: Map all interactive states to token variants

   - Base state: `--token-name`
   - Hover: `--token-name--hover`
   - Active: `--token-name--active`
   - Focus: `--token-name--focus`

5. **Build component**: Implement with mapped tokens

### 4. Theme Application

For theming entire applications:

1. **Import tokens at root**: Load both light and dark token files
2. **Apply to layout containers**: Use base tokens on major sections
3. **Use token categories consistently**:
   - Interactive elements use `--color-progressive`
   - Destructive actions use `--color-destructive`
   - Text uses `--color-base`, `--color-subtle`
4. **Test color mode switching**: Works automatically with media queries
5. **Override selectively**: Only override for component-specific variations

### 5. Dark Mode Implementation

Codex provides automatic dark mode support through media queries:

```html
<!-- Light mode (always loaded) -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@wikimedia/codex-design-tokens/theme-wikimedia-ui.css"
/>

<!-- Dark mode (conditional) -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@wikimedia/codex-design-tokens/theme-wikimedia-ui-mode-dark.css"
  media="( prefers-color-scheme: dark )"
/>
```

**How it works**:

- Light mode tokens load by default
- When OS/browser is in dark mode, dark mode tokens override
- No JavaScript needed
- Tokens automatically switch based on user preference

**Testing**:

- Chrome DevTools → Rendering tab → Emulate CSS media feature `prefers-color-scheme`
- Firefox: about:config → `ui.systemUsesDarkTheme` set to 0 (light) or 1 (dark)

**Fixed tokens**: Some tokens stay the same in both modes:

- `--color-inverted-fixed` (always white)
- `--background-color-base-fixed` (always white)
- Use these for elements that should never change

### 6. MediaWiki Integration

For MediaWiki skins and extensions:

1. **In ResourceLoader**: Load tokens as modules
2. **In Less files**: Reference token values directly
3. **In extensions**: Include tokens in your extension's resources
4. **See**: `references/dark-mode-guide.md` for detailed MediaWiki integration

### 7. Layout & Stacking with Z-Index

Use semantic z-index tokens for predictable element layering:

**Basic stacking hierarchy** (lowest to highest):

- `--z-index-base` (0): Default layer for content
- `--z-index-above-content` (1): Elements above content
- `--z-index-toolbar` (2): Toolbars and sticky navigation
- `--z-index-dropdown` (50): Dropdown menus
- `--z-index-sticky` (100): Sticky headers/footers
- `--z-index-fixed` (200): Fixed position elements
- `--z-index-overlay` (450): Modal overlays and dialogs
- `--z-index-popover` (700): Popovers
- `--z-index-tooltip` (800): Tooltips
- `--z-index-toast-notification` (900): Toast notifications
- `--z-index-top` (9999): Absolutely top layer

**Example usage**:

```css
.dropdown-menu {
  position: absolute;
  z-index: var(--z-index-dropdown);
}

.modal-overlay {
  position: fixed;
  z-index: var(--z-index-overlay-backdrop);
}

.modal-dialog {
  position: fixed;
  z-index: var(--z-index-overlay);
}

.tooltip {
  position: absolute;
  z-index: var(--z-index-tooltip);
}
```

**Component-internal stacking**: Use `--z-index-stacking-0` through `--z-index-stacking-3` for layering elements within a single component.

### 8. Spacing System

Use consistent spacing tokens for margins, padding, and gaps:

**Standard spacing scale** (use these for most layouts):

- `--spacing-50` (8px): Tight spacing
- `--spacing-75` (12px): Compact spacing
- `--spacing-100` (16px): Default spacing
- `--spacing-150` (24px): Medium spacing
- `--spacing-200` (32px): Large spacing
- `--spacing-300` (48px): Extra large spacing

**Example usage**:

```css
.card {
  padding: var(--spacing-100);
  margin-bottom: var(--spacing-150);
  gap: var(--spacing-75);
}

.section {
  padding: var(--spacing-200) var(--spacing-100);
  margin-top: var(--spacing-300);
}
```

**Size tokens for dimensions**: Use `--size-*` tokens for widths, heights, and other dimensions:

```css
.icon {
  width: var(--size-100);   /* 1rem = 16px */
  height: var(--size-100);
}

.button {
  min-height: var(--size-200);  /* 2rem = 32px */
  padding: 0 var(--spacing-100);
}
```

### 9. Animation & Transitions

Use token-based animations for consistency:

**Basic transitions**:

```css
.button {
  transition-property: var(--transition-property-base);
  transition-duration: var(--transition-duration-base);
  transition-timing-function: var(--transition-timing-function-user);
}

.button:hover {
  background-color: var(--background-color-progressive--hover);
}
```

**Fade effects**:

```css
.modal {
  transition-property: var(--transition-property-fade);
  transition-duration: var(--transition-duration-medium);
  opacity: 0;
}

.modal.is-visible {
  opacity: var(--opacity-base);
}
```

**Icon transitions**:

```css
.icon {
  transition-property: var(--transition-property-icon);
  transition-duration: var(--transition-duration-base);
  color: var(--color-base);
}

.icon:hover {
  color: var(--color-progressive);
}
```

**Loading spinners** (use animation tokens):

```css
@keyframes spin {
  from {
    transform: var(--transform-progress-indicator-spinner-start);
  }
  to {
    transform: var(--transform-progress-indicator-spinner-end);
  }
}

.spinner {
  animation-name: spin;
  animation-duration: var(--animation-duration-fast);
  animation-timing-function: var(--animation-timing-function-base);
  animation-iteration-count: var(--animation-iteration-count-base);
}
```

## Token Categories Reference

### Colors (~90 tokens)

Semantic text colors for all UI states:

- **Base colors**: `--color-base`, `--color-emphasized`, `--color-subtle`, `--color-disabled`
- **Interactive colors**: `--color-progressive` (blue), `--color-destructive` (red)
- **State variants**: `--hover`, `--active`, `--focus` suffixes for each
- **Special colors**: `--color-inverted` (white), `--color-visited` (links)
- **Icon colors**: `--color-icon-error`, `--color-icon-success`, etc.

→ See `references/color-tokens.md` for complete list with use cases

### Background Colors (~45 tokens)

Colors for container backgrounds, buttons, and surfaces:

- **Base backgrounds**: `--background-color-base`, `--background-color-neutral`
- **Interactive backgrounds**: with hover/active/focus variants
- **Status backgrounds**: error, warning, success, notice (red, orange, green, gray)
- **Special backgrounds**: transparent, inverted, backdrop, content states

→ See `references/color-tokens.md` for complete list

### Border Colors (~35 tokens)

Colors for borders, dividers, and outlines:

- **Base borders**: `--border-color-base`, `--border-color-emphasized`, `--border-color-subtle`
- **Interactive borders**: progressive and destructive with state variants
- **Input borders**: `--border-color-input-*` for form elements
- **Special borders**: transparent, inverted, focus outlines

→ See `references/tokens-complete.md`

### Typography (~30 tokens)

Font sizing, line-height, family, and weight:

- **Font sizes**: `--font-size-x-small` (0.75rem) to `--font-size-xxx-large` (1.75rem)
- **Line heights**: matching scale (`--line-height-x-small` to `--line-height-xxx-large`)
- **Font families**: `--font-family-system-sans`, `--font-family-serif`, `--font-family-monospace`
- **Font weights**: `--font-weight-hairline` (100) to `--font-weight-bold` (700)
- **Content**: `--line-height-content` for user-generated content

→ See `references/typography-tokens.md`

### Spacing & Sizing (~55 tokens)

Comprehensive sizing and spacing scale for consistent layouts:

- **Size scale**: `--size-0` to `--size-5600` (0 to 56rem), plus absolute pixel values
- **Spacing scale**: `--spacing-0` to `--spacing-400` (0 to 64px) for margins and padding
- **Viewport sizes**: `--size-viewport-width-full`, `--size-viewport-height-full`
- **Percentage sizes**: `--size-third` (33.33%), `--size-half` (50%), `--size-full` (100%), `--size-double` (200%)
- **Content sizes**: `--size-content-min`, `--size-content-fit`, `--size-content-max`
- **Min sizes**: Interactive targets (`--min-size-interactive-pointer`, `--min-size-interactive-touch`), icons, inputs
- **Max widths**: Breakpoints for mobile, tablet, desktop, desktop-wide

→ See `references/tokens-complete.md`

### Layout & Stacking (~15 tokens)

Z-index tokens for managing element layering:

- **Layout z-index**: `--z-index-bottom` (-100) to `--z-index-top` (9999)
- **Semantic layers**: `--z-index-dropdown` (50), `--z-index-overlay` (450), `--z-index-tooltip` (800), `--z-index-toast-notification` (900)
- **Stacking context**: `--z-index-stacking-0` to `--z-index-stacking-3` for component-internal layering

Use semantic z-index tokens instead of hardcoded values for predictable stacking behavior.

### Border Tokens (~25 tokens)

Comprehensive border properties beyond just colors:

- **Border widths**: `--border-width-base` (1px), `--border-width-thick` (2px)
- **Border styles**: `--border-style-base` (solid), `--border-style-dashed`
- **Border radius**: `--border-radius-base` (2px), `--border-radius-sharp` (0), `--border-radius-pill` (9999px), `--border-radius-circle` (50%)
- **Composite borders**: `--border-base`, `--border-subtle`, `--border-progressive`, `--border-destructive` (combines width, style, color)

→ See `references/tokens-complete.md`

### Box Shadows (~20 tokens)

Comprehensive shadow system with directional variants:

- **Shadow sizes**: `--box-shadow-small`, `--box-shadow-medium`, `--box-shadow-large`
- **Directional shadows**: `--box-shadow-outset-small-top`, `--box-shadow-outset-small-bottom`, `--box-shadow-outset-small-start`
- **Inset shadows**: `--box-shadow-inset-small`, `--box-shadow-inset-medium`, `--box-shadow-inset-medium-vertical`
- **Shadow colors**: Base, progressive, destructive, inverted with state variants
- **Around/below**: `--box-shadow-outset-medium-around`, `--box-shadow-outset-large-below`

→ See `references/tokens-complete.md`

### Animation & Transitions (~15 tokens)

Timing and animation properties:

- **Transition duration**: `--transition-duration-base` (100ms), `--transition-duration-medium` (250ms)
- **Transition properties**: `--transition-property-base`, `--transition-property-fade`, `--transition-property-icon`
- **Timing functions**: `--transition-timing-function-system` (ease), `--transition-timing-function-user` (ease-out)
- **Animation duration**: `--animation-duration-fast` (1000ms) to `--animation-duration-slow` (2000ms)
- **Animation delays**: `--animation-delay-none`, `--animation-delay-medium`, `--animation-delay-slow`
- **Animation functions**: `--animation-timing-function-base`, `--animation-timing-function-bouncing`

Use these for smooth, consistent animations across the interface.

### Opacity (~8 tokens)

Opacity levels for various UI elements:

- **General opacity**: `--opacity-base` (1), `--opacity-medium` (0.65), `--opacity-low` (0.3), `--opacity-transparent` (0)
- **Icon opacity**: `--opacity-icon-base`, `--opacity-icon-base--hover`, `--opacity-icon-base--selected`, `--opacity-icon-base--disabled`

### Cursor States (~12 tokens)

Cursor types for different interactions:

- **Base cursors**: `--cursor-base`, `--cursor-base--hover` (pointer), `--cursor-base--disabled`
- **Interaction cursors**: `--cursor-grab`, `--cursor-grabbing`, `--cursor-move`, `--cursor-text`
- **Utility cursors**: `--cursor-help`, `--cursor-not-allowed`, `--cursor-zoom-in`, `--cursor-zoom-out`
- **Resize cursors**: `--cursor-resize-nesw`, `--cursor-resize-nwse`

### Visual Effects

- **Filters**: Icon invert filter
- **Mix blend modes**: Normal and multiply
- **Transforms**: Checkbox tick rotation, progress indicator spinner
- **Text decoration**: None, underline, line-through
- **Text overflow**: Clip, ellipsis

→ See `references/tokens-complete.md`

## Best Practices

### 1. Always Use Semantic Tokens

✓ **Good**: `color: var(--color-progressive);` (semantic, auto dark mode)
✗ **Bad**: `color: #36c;` (hardcoded, breaks dark mode)

Semantic tokens describe purpose (progressive action, destructive action) not color values.

### 2. Use the Spacing Scale Consistently

✓ **Good**: `padding: var(--spacing-100);` (consistent, maintainable)
✗ **Bad**: `padding: 15px;` (arbitrary value breaks design system)

Use spacing tokens (`--spacing-*`) for margins, padding, and gaps. Use size tokens (`--size-*`) for widths and heights.

### 3. Use Z-Index Tokens for Layering

✓ **Good**: `z-index: var(--z-index-dropdown);` (predictable stacking)
✗ **Bad**: `z-index: 999;` (arbitrary value, can cause stacking conflicts)

The z-index system ensures all overlays, dropdowns, and modals stack correctly.

### 4. Use CSS calc() for Token Math

When combining tokens:

```css
/* Scale a token value */
width: calc(var(--font-size-medium) * 2);
padding: calc(var(--spacing-100) * 0.5);
```

### 5. Design for Both Light and Dark Modes

Test every component in both modes:

- Use browser dev tools to toggle `prefers-color-scheme`
- Verify contrast ratios remain acceptable
- Check that secondary colors work in both modes

### 6. Follow the Token Hierarchy

- **Progressive**: Primary actions, main CTA (blue)
- **Destructive**: Dangerous actions, delete buttons (red)
- **Neutral**: Secondary actions, default state (gray)
- **Status colors**: Error (red), Warning (orange), Success (green), Notice (gray)

### 7. Leverage State Tokens

Always style all interactive states:

```css
.button {
  background-color: var(--background-color-progressive);
  color: var(--color-inverted);
}

.button:hover {
  background-color: var(--background-color-progressive--hover);
}

.button:active {
  background-color: var(--background-color-progressive--active);
}

.button:focus {
  outline: 2px solid var(--outline-color-progressive--focus);
}

.button:disabled {
  background-color: var(--background-color-disabled);
  color: var(--color-disabled);
}
```

### 8. Use Border Radius Tokens

✓ **Good**: `border-radius: var(--border-radius-base);` (2px, consistent)
✗ **Bad**: `border-radius: 3px;` (doesn't match design system)

Use `--border-radius-pill` for fully rounded buttons, `--border-radius-circle` for circular avatars.

### 9. Use Composite Border Tokens

✓ **Good**: `border: var(--border-base);` (combines width, style, color)
✗ **Bad**: `border: 1px solid #a2a9b1;` (hardcoded, not maintainable)

Composite tokens like `--border-base`, `--border-progressive`, `--border-subtle` combine multiple properties.

### 10. Accessibility First

Tokens are designed to meet WCAG accessibility standards:

- Contrast ratios are pre-verified
- Color combinations are tested
- Using tokens correctly ensures accessibility
- Never override with hardcoded values for contrast-sensitive elements

## Common Patterns

### Button Variants

**Primary (Progressive)**: Main call-to-action

- Background: `--background-color-progressive`
- Hover: `--background-color-progressive--hover`
- Text: `--color-inverted`

**Secondary (Neutral)**: Regular actions

- Background: `--background-color-interactive`
- Hover: `--background-color-interactive--hover`
- Text: `--color-base`

**Destructive**: Delete or dangerous actions

- Background: `--background-color-destructive`
- Hover: `--background-color-destructive--hover`
- Text: `--color-inverted`

→ See `assets/templates/button-examples.html` for complete code

### Form Elements

**Text Inputs**:

- Background: `--background-color-interactive-subtle`
- Border: `--border-color-input-*` with state variants
- Text: `--color-base`

**Checkboxes/Radios**:

- Border: `--border-color-input-binary`
- Checked background: `--background-color-input-binary--checked`

**Validation**:

- Error: use `--border-color-error`, `--color-error`
- Success: use `--color-success`, `--background-color-success-subtle`

→ See `assets/templates/form-examples.html` for complete code

### Interactive States

All interactive elements need:

1. **Default**: Base token
2. **Hover**: `--token--hover` variant
3. **Active**: `--token--active` variant
4. **Focus**: `--outline-color-*--focus` or focus-visible
5. **Disabled**: `--background-color-disabled`, `--color-disabled`

→ See `assets/templates/interactive-states.html` for examples

## Using This Skill

When a developer requests Codex token help:

1. **Understand the need**: Identify the use case (component, theme, conversion, MediaWiki)
2. **Apply appropriate workflow**: Guide through the relevant workflow above
3. **Reference documentation**: Load relevant reference file as needed
4. **Provide working code**: Use templates from assets/ as starting points
5. **Test both modes**: Remind to test light and dark mode
6. **Verify accessibility**: Ensure tokens used maintain WCAG compliance

## Reference Files

Detailed information available in reference documents:

- `references/tokens-complete.md` - All 180+ tokens organized by category with descriptions
- `references/color-tokens.md` - Complete color system: base, interactive, status, backgrounds, borders
- `references/typography-tokens.md` - Font size and line-height scales with pairing recommendations
- `references/component-patterns.md` - Common UI patterns with complete code examples
- `references/dark-mode-guide.md` - Dark mode implementation, testing, and MediaWiki integration

Load these files when needed for detailed information.

## Template Files

Working HTML examples available in templates:

- `assets/templates/basic-page.html` - Minimal starter page with tokens imported
- `assets/templates/button-examples.html` - Button variants (progressive, destructive, neutral, disabled)
- `assets/templates/form-examples.html` - Form elements (inputs, checkboxes, radios, validation)
- `assets/templates/interactive-states.html` - All interactive states (hover, active, focus, disabled)

Use templates as starting points for code generation.

## Troubleshooting

### Token not working / showing as fallback color

- Verify token stylesheets are imported before custom CSS
- Check token name spelling (all lowercase with hyphens)
- Ensure media query for dark mode is correct

### Dark mode not switching

- Verify both stylesheet links are included
- Check media query syntax: `media="( prefers-color-scheme: dark )"`
- Test with browser dev tools or OS dark mode setting
- Ensure no hardcoded colors override tokens

### Color contrast issues

- Codex tokens meet WCAG standards by design
- If issues occur, likely due to hardcoded colors instead of tokens
- Always use semantic tokens for contrast-sensitive elements

### Spacing/sizing looks wrong

- Verify you're using appropriate token scale (font-size, line-height pairs)
- Check for conflicting margin/padding that overrides token values
- Use `!important` temporarily to debug, then refactor properly

## Best Learning Path

1. **Start simple**: Use `assets/templates/basic-page.html` to get familiar
2. **Build a component**: Follow workflow in section 2 to build a button or card
3. **Explore colors**: Read `references/color-tokens.md` to understand semantic system
4. **Review patterns**: Check `references/component-patterns.md` for common solutions
5. **Test modes**: Implement dark mode support and test switching
6. **Build more**: Create forms, complex layouts, and interactive components

## Key Concepts

**Semantic tokens**: Token names describe purpose (progressive, destructive) not values
**State pattern**: Each semantic token has variants for hover, active, focus states
**Fixed tokens**: Some tokens don't change in dark mode (inverted-fixed, base-fixed)
**Progressive disclosure**: Import token file, CSS variables are ready to use
**Accessibility built-in**: Using tokens correctly ensures WCAG compliance

## Resources

- **Official Codex Documentation**: https://doc.wikimedia.org/codex/latest/
- **Design Tokens Overview**: https://doc.wikimedia.org/codex/latest/design-tokens/overview.html
- **CDN Source**: https://cdn.jsdelivr.net/npm/@wikimedia/codex-design-tokens/
- **MediaWiki Integration**: https://www.mediawiki.org/wiki/Codex

---

**Note**: This skill is version-agnostic and works with any current or future version of Codex design tokens via CDN. Always verify token availability in the official documentation if using an older or newer version.