@xmp.dev/design-tokens

v1.3.1

Published

4 days ago

Unified design system tokens for all XMP products - supports Tailwind CSS v3 and v4

Downloads

1,363

0High
0Medium
0Low

rybaier

design-tokens design-system tailwind xmp

@xmp.dev/design-tokens

Unified design system tokens for all XMP products. Provides consistent colors, typography, spacing, and component patterns across dashboards, websites, and applications.

🎨 Visual Reference

See all tokens in action! Open VISUAL_REFERENCE.html in your browser (included in this package) for a complete visual showcase with live examples of all colors, shadows, typography, and animations.

Storybook XMP Design System

XMP Design System central hub.

🤖 AI Agent Guide

Working with AI coding assistants? See CLAUDE_STYLE_GUIDE.md for comprehensive style standards and best practices when using Claude, Cursor, or other AI tools on XMP projects.

📦 Installation

npm install @xmp.dev/design-tokens

That's it! No authentication or configuration needed.

🚀 Quick Start

For Tailwind v3 Projects

// tailwind.config.js
const { presets } = require('@xmp.dev/design-tokens');

module.exports = {
  presets: [presets.dark],
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  // Your custom extensions here
};

Use Cases:

XMPX (Always Dark): Uses preset exclusively for all styling
Website (Responsive): Uses preset for dark: classes, default Tailwind for light mode

For Tailwind v4: See dedicated section below and full integration guide

With Tailwind v4

Full setup required for v4 - See Tailwind v4 Integration Guide

Quick preview:

/* app/globals.css */
@import "tailwindcss";
@import "@xmp.dev/design-tokens/css/dark.css";

@theme {
  --color-background: var(--color-background);
  --color-surface: var(--color-background-surface);
  --color-primary: var(--color-text-primary);
  /* ... see full guide for complete mapping */
}

// app/layout.tsx - Apply to body
<body className="bg-background text-primary">

Important: Tailwind v4 uses a different configuration approach. The CSS variables work, but you must map them in a @theme block. See the full integration guide for details.

🎨 Available Tokens

Colors

Backgrounds

background.DEFAULT - Main background
background.surface - Cards, panels
background.elevated - Headers, elevated elements
background.dark - Nested containers

Text

primary - Headings, high emphasis
secondary - Subheadings, important text
tertiary - Body text
muted - Labels, secondary info
disabled - Disabled states

Semantic (Buttons)

success, success.hover
danger, danger.hover
warning, warning.hover
info, info.hover

Status (Badges, Indicators)

status-success
status-error
status-warning
status-info

Usage Examples

React Component with Dark Theme

export function Card({ children }) {
  return (
    <div className="bg-background-surface border border-border rounded-lg p-6 
                    shadow-card hover:shadow-card-hover transition-all">
      <h2 className="text-primary font-bold mb-2">
        Card Title
      </h2>
      <p className="text-tertiary">
        {children}
      </p>
    </div>
  );
}

Badges with Status Colors

export function StatusBadge({ status }) {
  return (
    <span className="px-3 py-1 rounded-full text-sm font-medium
                     bg-green-500/20 text-green-400">
      {status}
    </span>
  );
}

Button with Semantic Colors

export function DangerButton({ onClick, children }) {
  return (
    <button 
      onClick={onClick}
      className="px-4 py-2 bg-danger hover:bg-danger-hover 
                 text-white rounded-md transition-all">
      {children}
    </button>
  );
}

📚 Preset

`dark`

Unified dark theme for all XMP products.

Use for:

Admin dashboards (XMPX - always dark)
Responsive websites (Website - dark mode)
Internal tools
Developer dashboards
Data visualization apps

Features:

Dark backgrounds (#0a0f1a, #1e293b)
White/light text hierarchy
Semantic colors for buttons
Vibrant status indicators
Consistent across all XMP products

How it works:

Always-dark apps: Use preset for all styling
Responsive apps: Use preset for dark: variants, default Tailwind for light mode

🔧 Advanced Usage

Accessing Raw Tokens

const tokens = require('@xmp.dev/design-tokens');

console.log(tokens.colors.themes.dark.background);
// { DEFAULT: '#0a0f1a', surface: '#1e293b', ... }

console.log(tokens.shadows.shadows.dark);
// { sm: '0 1px 3px...', DEFAULT: '0 4px 12px...', ... }

Custom Extensions

const { presets } = require('@xmp.dev/design-tokens');

module.exports = {
  presets: [presets.darkDashboard],
  theme: {
    extend: {
      // Add your custom colors
      colors: {
        brand: '#custom-color',
      },
      // Override specific tokens
      borderRadius: {
        'custom': '2rem',
      },
    },
  },
};

TypeScript Support

import type { Tokens, ThemeColors } from '@xmp.dev/design-tokens';

const tokens: Tokens = require('@xmp.dev/design-tokens').tokens;

📖 Token Reference

Complete Token Files

All tokens are available as JSON:

tokens/colors.json - Color definitions (including role-based and chart tokens)
tokens/shadows.json - Shadow styles (including overlay)
tokens/typography.json - Font families, sizes, weights (including 2xs)
tokens/animation.json - Transition timings (including interactive, overlay, toast)
tokens/spacing.json - Spacing scale, density presets, border radius
tokens/layers.json - Z-index layer system

Design Patterns

See the main repository for documented design patterns:

Badge system (20% opacity backgrounds)
Status indicators
Interactive states
Card layouts
Form inputs

🔄 Migration from Custom Config

Before (XMPX with custom config)

// 91 lines of custom color definitions
export default {
  theme: {
    extend: {
      colors: {
        background: { DEFAULT: '#0a0f1a', ... },
        // ... 60+ more lines
      }
    }
  }
}

After (with package)

const { presets } = require('@xmp.dev/design-tokens');

export default {
  presets: [presets.dark],
  // That's it! 2 lines instead of 91
}

📄 License

MIT

🤝 Contributing

See the main repository for contribution guidelines.

📞 Support

Issues: GitHub Issues
Docs: See /docs in the main repository
Examples: See XMPX frontend for implementation reference

Version: 1.1.0
Last Updated: December 1, 2025
License: MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xmp.dev/design-tokens

🎨 Visual Reference

Storybook XMP Design System

🤖 AI Agent Guide

📦 Installation

🚀 Quick Start

For Tailwind v3 Projects

With Tailwind v4

🎨 Available Tokens

Colors

Backgrounds

Text

Semantic (Buttons)

Status (Badges, Indicators)

Usage Examples

React Component with Dark Theme

Badges with Status Colors

Button with Semantic Colors

📚 Preset

dark

🔧 Advanced Usage

Accessing Raw Tokens

Custom Extensions

TypeScript Support

📖 Token Reference

Complete Token Files

Design Patterns

🔄 Migration from Custom Config

Before (XMPX with custom config)

After (with package)

📄 License

🤝 Contributing

📞 Support

`dark`