Color Swatch

Individual color swatch with hex value display, plus grid variants for color scales and semantic color tokens.

Color Scale Grid

Gray

#f9fafb

#e5e7eb

200

#6b7280

500

#374151

700

#111827

900

Semantic Color Grid

Text

text-primary

text-secondary

text-tertiary

Installation

npx visor add color-swatch

This copies two files into your project:

components/ui/color-swatch/color-swatch.tsx — the component
components/ui/color-swatch/color-swatch.module.css — the styles

Usage

import {
  ColorSwatch,
  ColorSwatchGrid,
  SemanticColorItem,
  SemanticColorGrid,
} from '@/components/ui/color-swatch/color-swatch';

{/* Single swatch */}
<ColorSwatch token="--color-blue-500" hex="#3b82f6" name="500" lightText />

{/* Grid of swatches */}
<ColorSwatchGrid
  label="Gray"
  swatches={[
    { token: "--color-gray-50", hex: "#f9fafb", name: "50" },
    { token: "--color-gray-900", hex: "#111827", name: "900", lightText: true },
  ]}
/>

{/* Semantic color group */}
<SemanticColorGrid
  category="Text"
  items={[
    { token: "--text-primary", label: "text-primary" },
    { token: "--text-secondary", label: "text-secondary" },
  ]}
/>

API Reference

ColorSwatchProps

Prop	Type	Default	Description
`token`*	`string`	—	CSS custom property token name (e.g. "--color-blue-500").
`hex`*	`string`	—	Hex value for fallback and display.
`name`*	`string`	—	Label shown beneath the swatch.
`lightText`	`boolean`	`false`	When true, hex text renders white instead of dark.
`className`	`string`	—	Additional CSS class names to merge onto the element.

ColorSwatchGridProps

Prop	Type	Default	Description
`label`*	`string`	—	Scale name shown above the grid.
`swatches`*	`ColorSwatchProps[]`	—	Array of swatch data to render.
`className`	`string`	—	Additional CSS class names to merge onto the element.

SemanticColorGridProps

Prop	Type	Default	Description
`category`	`string`	—	Category name shown above the group
`items`	`SemanticColorItemProps[]`	—	Items in this category
`className`	`string`	—	Additional CSS classes

Color swatches are documentation utilities. Ensure the hex value overlaid on each swatch meets minimum contrast — use lightText={true} for dark swatches and lightText={false} (default) for light swatches.

Color alone should never be the sole means of conveying information — use swatches alongside text labels and token names.