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:

<!-- 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:

.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:

<!-- 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:

.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:

.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:

.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:

.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:

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

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

Icon transitions:

.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):

@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:

/* 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:

.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.