@versini/ui-styles

TailwindCSS configuration and styles for Versini UI Components.

This package provides the core TailwindCSS configuration, custom styles, and design tokens that power all Versini UI components. It includes the TailwindCSS plugin required for proper component styling.

Table of Contents

• Features
• Installation
• Usage
• CLI Tools

Features

• 🎨 Design System: Consistent design tokens and color palette
• 🔧 TailwindCSS Plugin: Ready-to-use plugin for component styles
• 🎭 Theme Support: Built-in light, dark, and system theme support
• 📐 Typography: Optimized typography scales and spacing
• 🌈 Color Tokens: Semantic color tokens for consistent theming
• 🩺 ui-doctor CLI: Detect raw Tailwind color classes and suggest design tokens

Installation

npm install @versini/ui-styles

Usage

TailwindCSS Configuration

Add the UI Styles plugin to your tailwind.config.js:

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@versini/ui-*/**/*.js"
  ],
  plugins: [require("@versini/ui-styles/plugin")]
};

With CSS Import

Import the base styles in your CSS file:

@import "@versini/ui-styles/dist/styles.css";

Complete Setup

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@versini/ui-*/**/*.js"
  ],
  darkMode: "selector", // or 'media' for automatic
  plugins: [require("@versini/ui-styles/plugin")]
};

/* styles.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@import "@versini/ui-styles/dist/styles.css";

CLI Tools

ui-doctor

A CLI tool to detect raw Tailwind CSS color classes (like bg-slate-500, text-red-400) and suggest semantic design tokens from the @versini/ui-styles package.

Usage

# Scan current directory
npx ui-doctor

# Scan a specific directory
npx ui-doctor ./src

# Scan with specific file extensions
npx ui-doctor -e tsx,ts

# Output in JSON format (for CI/CD integration)
npx ui-doctor --json

# Combine options
npx ui-doctor ./src --json -e tsx,ts

Options

| Option | Alias | Description | Default | | --------------------- | ----- | ---------------------------------- | ------------------------------ | | --path <path> | -p | Path to scan | . (current directory) | | --extensions <ext> | -e | Comma-separated file extensions | js,jsx,ts,tsx | | --ignore <patterns> | -i | Comma-separated patterns to ignore | node_modules,dist,build,.git | | --json | | Output in JSON format | false | | --help | -h | Show help message | | | --version | -v | Show version number | |

Example Output

ui-doctor - Scanning for raw Tailwind color classes...

✗ src/components/Button.tsx:15
  <div className="bg-slate-500 text-white">
  Found: bg-slate-500
  Suggestion: Use 'bg-surface-medium'

✗ src/components/Card.tsx:23
  <p className="text-red-400">Error</p>
  Found: text-red-400
  Suggestion: Use 'text-copy-error-light'
  Other options: text-border-danger-medium

──────────────────────────────────────────────────
Summary: 2 violations found in 2 files
Scanned 50 files in 25ms

JSON Output

When using --json, the output is formatted for CI/CD integration:

{
  "filesScanned": 50,
  "totalViolations": 2,
  "duration": 25,
  "violations": [
    {
      "file": "src/components/Button.tsx",
      "issues": [
        {
          "line": 15,
          "column": 12,
          "class": "bg-slate-500",
          "prefix": "bg",
          "color": "slate",
          "shade": "500",
          "suggestions": ["bg-surface-medium"]
        }
      ]
    }
  ]
}

Exit Codes

• 0 - No violations found
• 1 - Violations found or error occurred