Configuration

TailTrace can be configured via a tailtrace.json file in your project root, or through each tool’s settings.

Configuration File

Create a tailtrace.json file:

{
  "colors": {
    "primary": "#3b82f6",
    "primary-dark": "#1d4ed8",
    "secondary": "#10b981",
    "danger": "#ef4444",
    "warning": "#f59e0b"
  },
  "spacing": {
    "xs": "4px",
    "sm": "8px",
    "md": "16px",
    "lg": "24px",
    "xl": "32px"
  },
  "fontSize": {
    "xs": "12px",
    "sm": "14px",
    "base": "16px",
    "lg": "18px",
    "xl": "20px"
  },
  "borderRadius": {
    "sm": "4px",
    "md": "8px",
    "lg": "12px",
    "full": "9999px"
  },
  "deltaEThreshold": 2.3,
  "spacingThreshold": 2
}

Configuration Options

colors

A map of token names to hex color values. TailTrace uses CIEDE2000 Delta-E for perceptual matching.

{
  "colors": {
    "brand-blue": "#3b82f6",
    "brand-green": "#10b981"
  }
}

spacing

A map of token names to spacing values. Supports px, rem, and em units.

{
  "spacing": {
    "1": "4px",
    "2": "8px",
    "4": "16px"
  }
}

Tip

If you’re using Tailwind’s default spacing scale, you don’t need to configure this - TailTrace uses Tailwind defaults automatically.

deltaEThreshold

The maximum Delta-E difference for a color to be considered a “fuzzy” match. Default is 2.3 (the just-noticeable difference for human vision).

Value	Meaning
0	Exact matches only
1.0	Very strict
2.3	Default (JND threshold)
5.0	Lenient

spacingThreshold

The maximum pixel difference for spacing to be considered a “fuzzy” match. Default is 2.

Import from Tailwind Config

TailTrace can automatically read your tailwind.config.js:

{
  "extends": "./tailwind.config.js"
}

This extracts your theme colors, spacing, and typography settings.

Per-Tool Configuration

Chrome Extension

Configure via the popup settings panel. Settings are stored in chrome.storage.local.

VS Code Extension

Use VS Code settings:

{
  "tailtrace.configPath": "./tailtrace.json",
  "tailtrace.deltaEThreshold": 2.3
}

Storybook Addon

Pass config to the decorator:

.storybook/preview.ts

import { withTailtraceAudit } from '@tailtrace/storybook-addon';

export const decorators = [
  withTailtraceAudit({
    deltaEThreshold: 2.3,
  }),
];

Cloud Sync (Pro)

With TailTrace Pro, you can sync configurations across your team:

1. Create a workspace at tailtrace.dev
2. Add your config via the dashboard
3. Team members fetch config automatically via API

{
  "cloud": {
    "workspaceId": "ws_abc123",
    "configId": "cfg_xyz789"
  }
}