Storybook Addon

The TailTrace Storybook Addon audits your component styles in real-time, flagging fuzzy matches as potential regressions.

Features

• Automatic Audits - Every story is analyzed on render
• Regression Detection - Fuzzy matches are flagged as warnings
• Token Suggestions - See which tokens to use instead
• Export Specs - Generate design token specifications

Installation

1. Install the addon

   bun add -D @tailtrace/storybook-addon

2. Add to your Storybook config

   .storybook/main.ts

   import type { StorybookConfig } from '@storybook/react-vite';
   
   const config: StorybookConfig = {
     addons: [
       '@storybook/addon-essentials',
       '@tailtrace/storybook-addon',
     ],
   };
   
   export default config;

3. Optionally configure the decorator

   .storybook/preview.ts

   import { withTailtraceAudit } from '@tailtrace/storybook-addon';
   
   export const decorators = [
     withTailtraceAudit({
       deltaEThreshold: 2.3,
     }),
   ];

Usage

Viewing Audits

1. Run Storybook: bun run storybook
2. Navigate to any story
3. Click the “TailTrace” tab in the addons panel
4. See all computed styles with token translations

Understanding Results

The audit table shows:

Column	Description
Element	HTML element and selector
Property	CSS property being audited
Value	Computed CSS value
Token	Matching Tailwind token
Status	Confidence indicator

Regression Warnings

When a style has a fuzzy match, it’s highlighted as a potential regression:

Caution

Regression Detected

background-color: #3b83f6 is close but not exact to blue-500 (#3b82f6).

Difference: ΔE 0.73

This might be unintentional design drift.

Configuration

Decorator Options

withTailtraceAudit({
  // Color matching threshold
  deltaEThreshold: 2.3,

  // Spacing matching threshold (px)
  spacingThreshold: 2,

  // Properties to audit
  properties: [
    'color',
    'background-color',
    'border-color',
    'padding',
    'margin',
    'font-size',
  ],

  // Elements to skip
  skipSelectors: ['.ignore-audit', '[data-no-audit]'],
})

Config File

Create tailtrace.json in your Storybook root:

{
  "colors": {
    "brand-primary": "#3b82f6"
  },
  "deltaEThreshold": 2.3
}

Exporting Specs

Generate a design token specification from your stories:

1. Open the TailTrace panel
2. Click “Export Spec”
3. Choose JSON or CSS custom properties format

Example output:

{
  "usedTokens": {
    "colors": ["blue-500", "slate-900", "white"],
    "spacing": ["p-4", "m-2", "gap-4"],
    "typography": ["text-sm", "font-semibold"]
  },
  "unknownValues": [
    { "property": "color", "value": "#custom123" }
  ]
}

CI Integration

Run TailTrace audits in CI to catch regressions:

# Install dependencies
bun install

# Run Storybook in CI mode with TailTrace
bun run build-storybook
bunx @tailtrace/storybook-addon audit ./storybook-static

The audit command exits with code 1 if fuzzy matches exceed your threshold.

Troubleshooting

Panel Not Showing

1. Verify the addon is in your main.ts config
2. Restart Storybook
3. Check browser console for errors

Styles Not Detected

1. Ensure components render actual DOM elements
2. Check that styles aren’t in Shadow DOM
3. The addon reads getComputedStyle() - inline styles work fine

Performance

For stories with many elements:

1. Use skipSelectors to exclude non-essential elements
2. Limit audited properties
3. Consider auditing only in development, not production builds