@joycostudio/system

A Tailwind v4 CSS variable debugger and design system visualizer. Scans your stylesheets for CSS custom properties and renders an interactive UI to inspect colors, typography, spacing, shadows, and shadcn/ui theme tokens.

Installation

# npm
npm install @joycostudio/system

# pnpm
pnpm add @joycostudio/system

# yarn
yarn add @joycostudio/system

React >=16.8.0 is required as a peer dependency.

Quick Start

import { TailwindV4Debug } from '@joycostudio/system'

export default function DesignSystemPage() {
  return <TailwindV4Debug />
}

The component automatically scans all stylesheets loaded in the DOM and categorizes every CSS custom property it finds.

Usage

TailwindV4Debug Component

The main export. Renders a full-page debug UI with tabbed navigation, search, and visual previews.

import { TailwindV4Debug } from '@joycostudio/system'

// Auto-scan DOM stylesheets
<TailwindV4Debug />

// Pass raw CSS directly
<TailwindV4Debug css={rawCSSString} />

// Custom title
<TailwindV4Debug title="My Design System" />

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | css | string | undefined | Raw CSS content to scan instead of reading from the DOM | | title | string | "Tailwind v4 Debug" | Title displayed in the header |

scanVariables Function

Use this directly if you need programmatic access to the scanned variables without rendering the debug UI.

import { scanVariables } from '@joycostudio/system'

// Scan all DOM stylesheets
const vars = scanVariables()

// Or scan raw CSS
const vars = scanVariables(myCSSString)

console.log(vars.colors)      // CSSVariable[]
console.log(vars.shadcnTheme) // CSSVariable[]
console.log(vars.typography)  // CSSVariable[]
console.log(vars.spacing)     // CSSVariable[]
console.log(vars.radius)      // CSSVariable[]
console.log(vars.shadows)     // CSSVariable[]
console.log(vars.other)       // CSSVariable[]

What It Detects

Variables are automatically categorized based on naming conventions and resolved values:

| Category | Matched patterns | |----------|-----------------| | Colors | --color-* prefixed variables, plus any variable whose resolved value is a color (hex, rgb, hsl, oklch, oklab, etc.) | | shadcn/ui Theme | Standard shadcn/ui tokens: --background, --foreground, --primary, --secondary, --muted, --accent, --destructive, --card, --popover, --border, --input, --ring, --chart-*, --sidebar-*, --radius | | Typography | --text-*, --font-*, --tracking-*, --leading-*, --letter-spacing-*, --line-height-* | | Spacing | --spacing (base multiplier) and --spacing-* | | Radius | --radius and --radius-* | | Shadows | --shadow* | | Other | Everything else |

Debug UI Features

The TailwindV4Debug component provides:

• Tab navigation — Filter by All, Theme, Colors, Typography, Spacing, or Components
• Search — Real-time filtering across variable names and values
• Color swatches — Visual previews grouped by color family with shade scales
• shadcn/ui theme pairs — Background/foreground pairs shown as themed cards
• Typography preview — Text sizes rendered at actual scale, font families with specimen text, and weight samples
• Spacing scale — Visual bar chart of the full spacing scale computed from the base multiplier
• Border radius — Shape previews for each radius token
• Shadow gallery — Box shadow previews rendered on cards
• Component previews — Live-rendered shadcn/ui components (Button, Badge, Input, Card, Tabs, Dialog, Popover) using your theme variables
• Copy to clipboard — Click any variable to copy its name
• Rescan — Re-read stylesheets without reloading the page

Types

type CSSVariable = {
  name: string          // e.g. "--color-blue-500"
  rawValue: string      // Value as written in the stylesheet
  resolvedValue: string // Computed value from getComputedStyle
}

type ColorGroup = {
  family: string        // e.g. "blue"
  variables: CSSVariable[]
}

type ScannedVariables = {
  colors: CSSVariable[]
  shadcnTheme: CSSVariable[]
  typography: CSSVariable[]
  spacing: CSSVariable[]
  radius: CSSVariable[]
  shadows: CSSVariable[]
  other: CSSVariable[]
}

type TailwindDebugProps = {
  css?: string
  title?: string
}

All types are exported from the package entry point.

Version Management

This library uses Changesets for version management.

# Create a changeset
pnpm changeset

# Apply version bumps
pnpm version:package

# Build and publish to npm
pnpm release

License

ISC