Ux Tokens

---
name: ux-tokens
description: >
  Definition, documentation, and application of design tokens for Vue 3 + shadcn-vue.
  Use when configuring a new project, extracting tokens from Figma, or ensuring
  token consistency across Vue components.
---

# Skill: Design Tokens — Vue 3 + shadcn-vue

## Default structure (globals.css generated by shadcn-vue init)

```css
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;
    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;
    --border: 214.3 31.8% 91.4%;
    --input: 214.3 31.8% 91.4%;
    --ring: 222.2 84% 4.9%;
    --radius: 0.5rem;
  }
  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark variants */
  }
}
```

## Additional semantic tokens (add when needed)

```css
:root {
  --success: 142 76% 36%;
  --success-foreground: 0 0% 100%;
  --warning: 38 92% 50%;
  --warning-foreground: 26 83% 14%;
  --info: 199 89% 48%;
  --info-foreground: 0 0% 100%;
}
```

## tailwind.config.ts — extend with custom tokens

```typescript
import type { Config } from 'tailwindcss'

export default {
  darkMode: 'class', // shadcn-vue uses class strategy
  content: ['./src/**/*.{vue,ts}', './components/**/*.{vue,ts}'],
  theme: {
    extend: {
      colors: {
        // shadcn-vue tokens — do not duplicate, use via CSS vars
        // Additional project tokens:
        success: 'hsl(var(--success))',
        'success-foreground': 'hsl(var(--success-foreground))',
        warning: 'hsl(var(--warning))',
        'warning-foreground': 'hsl(var(--warning-foreground))',
      },
      borderRadius: {
        // shadcn-vue uses --radius
        lg: 'var(--radius)',
        md: 'calc(var(--radius) - 2px)',
        sm: 'calc(var(--radius) - 4px)',
      },
    },
  },
} satisfies Config
```

## Usage in Vue components

```vue
<!-- Via Tailwind (preferred) -->
<div class="bg-background text-foreground border border-border rounded-lg" />
<Button class="bg-primary text-primary-foreground" />
<p class="text-muted-foreground text-sm" />

<!-- Via CSS variable (when Tailwind has no utility) -->
<div :style="{ color: 'hsl(var(--muted-foreground))' }" />

<!-- Local scope (override token in a component) -->
<div :style="{ '--primary': '262 83% 58%' }">
  <Button>Button with custom primary</Button>
</div>
```

## Spacing scale (base 4px — maintain consistency)

| Token | px | Tailwind | Typical usage |
|---|---|---|---|
| `space-0.5` | 2 | `gap-0.5` | Micro adjustments |
| `space-1` | 4 | `gap-1` | Icon + label |
| `space-2` | 8 | `gap-2` | Internal gap |
| `space-3` | 12 | `gap-3` | Badge padding |
| `space-4` | 16 | `gap-4 p-4` | Default padding |
| `space-6` | 24 | `gap-6` | Gap between card sections |
| `space-8` | 32 | `gap-8 p-8` | Card padding |
| `space-12` | 48 | `gap-12` | Gap between sections |

## Consistency checklist

- [ ] No hardcoded hex values outside of tokens (`#2563EB` → `hsl(var(--primary))`)
- [ ] Spacing follows 4px scale
- [ ] Dark mode tested with `class="dark"` on html root
- [ ] Semantic tokens used correctly (success, warning, destructive)
- [ ] `--radius` consistent across all components