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

- **Type:** Skill
- **Install:** `agentstack add skill-santhoshtr-wiki-skills-codex-design-tokens`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [santhoshtr](https://agentstack.voostack.com/s/santhoshtr)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [santhoshtr](https://github.com/santhoshtr)
- **Source:** https://github.com/santhoshtr/wiki-skills/tree/master/skills/codex-design-tokens

## Install

```sh
agentstack add skill-santhoshtr-wiki-skills-codex-design-tokens
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```

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

```

**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)
- **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](https://github.com/santhoshtr)
- **Source:** [santhoshtr/wiki-skills](https://github.com/santhoshtr/wiki-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-santhoshtr-wiki-skills-codex-design-tokens
- Seller: https://agentstack.voostack.com/s/santhoshtr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.