@carrot/design-colors

Color tokens for the Carrot Design System — neutral scale, status colors, main color scales with auto-generated surface companions, alternative neutrals, and optional palettes.

Installation

/* Core: neutral scale + status colors */
@import "@carrot/design-colors";

/* Add individual color scales as needed (surfaces included automatically) */
@import "@carrot/design-colors/scales/main/blue";
@import "@carrot/design-colors/scales/main/red";

/* Alternative neutral scales */
@import "@carrot/design-colors/scales/neutral/slate";

/* Optional palettes */
@import "@carrot/design-colors/palettes/flatui";

Tokens

Neutral Scale (scales/neutral/scales-neutral.css)

Extended precision neutral scale in @layer kapish.tokens, with fine-grained dark-range stops:

--color-neutral-0 (white) → --color-neutral-1000 (black)

Standard stops: 0, 25, 50, 75, 100, 200, 300, 400, 450, 500, 550, 600, 650, 700, 750, 800, 825, 850, 875, 900, 950, 1000

Status Colors (scales/scales-status.css)

Each status color provides a 50–600 range:

Scale	Token pattern	Example 500
Success	--color-success-{50–600}	#1fae5d
Warning	--color-warning-{50–600}	#e68b33
Danger	--color-danger-{50–600}	#d64546
Info	--color-info-{50–600}	#00b3cc

Main Color Scales (opt-in)

Each provides a 50–900 range as --color-{name}-{stop}:

Import path	Token prefix
scales/main/blue	--color-blue-*
scales/main/brown	--color-brown-*
scales/main/cyan	--color-cyan-*
scales/main/green	--color-green-*
scales/main/indigo	--color-indigo-*
scales/main/orange	--color-orange-*
scales/main/pink	--color-pink-*
scales/main/purple	--color-purple-*
scales/main/red	--color-red-*
scales/main/teal	--color-teal-*
scales/main/yellow	--color-yellow-*

Surface Companions (auto-generated)

Every main color scale automatically includes surface companion tokens — ready-made bg/fg/border combos for common UI patterns. These are generated at build time into .g.css files alongside each scale.

Importing a scale (e.g. scales/main/blue) automatically imports its surface companions.

Token Pattern

--color-{name}-{surface}-{role} where surface is one of subtle, tint, solid, pastel and role is one of bg, fg, border.

Surface Sets

Set	Purpose	bg	fg	border
subtle	Very quiet dark-mode tinted surface	12% of 500 into neutral-900	400	20% of 500 into neutral-750
tint	Noticeable but soft — selected, hover	22% of 500 into neutral-875	300	32% of 500 into neutral-700
solid	Accent IS the surface — buttons, callouts	500	50	600
pastel	Light-mode friendly — soft badges, alerts	50	700	200

The subtle and tint sets use color-mix() to blend the accent color into the neutral scale, producing dark-mode-appropriate tinted surfaces. The solid and pastel sets reference scale stops directly.

Example: All Blue Surface Tokens

/* Subtle — dark-mode badges, faint row tinting */
--color-blue-subtle-bg
--color-blue-subtle-fg
--color-blue-subtle-border

/* Tint — selected cards, hover states */
--color-blue-tint-bg
--color-blue-tint-fg
--color-blue-tint-border

/* Solid — buttons, strong callouts */
--color-blue-solid-bg
--color-blue-solid-fg
--color-blue-solid-border

/* Pastel — light-mode badges, soft alerts */
--color-blue-pastel-bg
--color-blue-pastel-fg
--color-blue-pastel-border

Alternative Neutral Scales (opt-in)

Import path	Description
scales/neutral/slate	Cool neutral (blue bias), 50–900 + 750/850
scales/neutral/zinc	Slightly warm neutral, 50–900
scales/neutral/stone	Soft earthy neutral, 50–900
scales/neutral/sand	Warm sand tones, 50–400
scales/neutral/charcoal	Deep darks only, 700–900

Palettes (opt-in)

Import path	Description
palettes/flatui	Flat UI color palette (original + American + British sets)

Utilities / Generated Classes

None — this package defines tokens only.

Dist Structure

File/Path	Description
index.css	Barrel — neutral scale + status colors
scales/neutral/	Neutral and alternative neutral scales
scales/scales-status.css	Status color tokens
scales/main/scales-main-*.css	Individual main color scales
scales/main/scales-main-*.g.css	Auto-generated surface companion tokens
palettes/	Optional color palettes

Build

npm run build

The build script (scripts/build.mjs) copies src/ to dist/, then for each main color scale generates a .g.css companion with surface tokens and prepends an @import for it into the base scale file. Source files are never modified.

Dependencies

None — this package is self-contained.

---

Usage Guide

Provides the full color token vocabulary for the Carrot Design System — neutrals, status, opt-in named scales, and auto-generated surface companions.

Import

@import "@carrot/design-colors";

Common Patterns

1. Use neutral tokens for surfaces and text

.card {
  background: var(--color-neutral-850);
  border: 1px solid var(--color-neutral-700);
  color: var(--color-neutral-100);
}

2. Use status tokens for feedback states

.alert-success {
  background: var(--color-success-50);
  border-color: var(--color-success-300);
  color: var(--color-success-600);
}

.alert-danger {
  background: var(--color-danger-50);
  border-color: var(--color-danger-300);
  color: var(--color-danger-600);
}

3. Load a named scale for brand colors

@import "@carrot/design-colors";
@import "@carrot/design-colors/scales/main/blue";

.badge-blue {
  background: var(--color-blue-100);
  color: var(--color-blue-700);
}

4. Use the extended neutral range for subtle UI layering

The neutral scale has fine-grained dark stops (800, 825, 850, 875, 900) for precise dark-mode depth:

.page       { background: var(--color-neutral-950); }
.sidebar    { background: var(--color-neutral-900); }
.card       { background: var(--color-neutral-850); }
.card-hover { background: var(--color-neutral-800); }
.modal      { background: var(--color-neutral-750); }

5. Load an alternative neutral for a different brand tone

@import "@carrot/design-colors/scales/neutral/slate";

:root {
  --color-neutral-900: var(--color-slate-900); /* override in theme */
}

6. Access status colors at specific stops

The 50–600 range supports light backgrounds (50–200), borders (300–400), and foreground text (500–600):

.tag-warning {
  background: var(--color-warning-100);
  color: var(--color-warning-600);
  border: 1px solid var(--color-warning-300);
}

7. Use surface companions for dark-mode tinted UI

Surface tokens are auto-generated for every main scale. Import the scale — surfaces come free.

@import "@carrot/design-colors/scales/main/blue";
@import "@carrot/design-colors/scales/main/orange";

Subtle — dark-mode badges, faint row tinting

.badge-blue {
  background: var(--color-blue-subtle-bg);
  color: var(--color-blue-subtle-fg);
  border: 1px solid var(--color-blue-subtle-border);
}

Tint — selected states, active sidebar items

.row--selected {
  background: var(--color-blue-tint-bg);
  color: var(--color-blue-tint-fg);
  border-color: var(--color-blue-tint-border);
}

Solid — buttons, strong callouts

.btn-orange {
  background: var(--color-orange-solid-bg);
  color: var(--color-orange-solid-fg);
  border: 1px solid var(--color-orange-solid-border);
}

Pastel — light-mode alerts, soft badges

.alert-info {
  background: var(--color-blue-pastel-bg);
  color: var(--color-blue-pastel-fg);
  border: 1px solid var(--color-blue-pastel-border);
}

8. Mix surface sets across colours

/* Two badges side by side — blue audience, orange category */
.badge-audience {
  background: var(--color-blue-subtle-bg);
  color: var(--color-blue-subtle-fg);
}

.badge-category {
  background: var(--color-orange-subtle-bg);
  color: var(--color-orange-subtle-fg);
}

Token Reference

Group	Pattern	Range
Neutral	--color-neutral-{n}	0–1000
Success	--color-success-{n}	50–600
Warning	--color-warning-{n}	50–600
Danger	--color-danger-{n}	50–600
Info	--color-info-{n}	50–600
Named scales	--color-{name}-{n}	50–900
Surface bg	--color-{name}-{surface}-bg	per scale
Surface fg	--color-{name}-{surface}-fg	per scale
Surface border	--color-{name}-{surface}-border	per scale

Surfaces: subtle · tint · solid · pastel