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:

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

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

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

• Reference: references/typography-tokens.md

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

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

1. Test color mode switching: Works automatically with media queries
2. Override selectively: Only override for component-specific variations

5. Dark Mode Implementation

Codex provides automatic dark mode support through media queries:

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)
• **De

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: santhoshtr
• Source: santhoshtr/wiki-skills
• License: MIT

Install and usage instructions live in the source repository linked above.