From afc1ee424d8e64bc860c4958f4f12390d2a88fce Mon Sep 17 00:00:00 2001
From: Talisson Costa <talisson.odcosta@gmail.com>
Date: Tue, 22 Sep 2026 09:11:26 -0300
Subject: [PATCH 1/6] feat(chip): add semantic variants, a solid fill and a
 status dot

The legacy `.chip` is the only thing in the app that can express a status
pill, a solid brand pill or a removable one, which is what keeps its 46 call
sites from moving. This gives Chip the colours they need.

Variants are semantic, so a chip says what it means rather than which colour
it is, and each resolves to bg-surface-*/text-* token utilities. `solid` is
the one filled variant, on --color-surface-action with text-white, because
there is no inverse-text token yet (5.93:1, AA but not AAA). Note the app has
a second, darker solid (bg-primary900, BetaFlag and PlanBasedAccess) that this
deliberately does not cover: which of the two survives is a design decision.

ChipDot is the leading dot on a status chip, in currentColor so it follows the
variant with nothing to wire, and aria-hidden since the label carries meaning.

Shape comes from the Figma tags frame, which we were off: it specifies a 6px
radius on a fixed 24px height, against rounded-sm (4px) and no explicit height
here. The frame's 8px vertical padding is not applied, being an artefact of a
height override that would leave 8px for a 12px label.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 frontend/web/components/base/Chip/Chip.scss   | 25 +++++++++++++
 frontend/web/components/base/Chip/Chip.tsx    | 36 +++++++++++++++++--
 frontend/web/components/base/Chip/ChipDot.tsx |  6 ++++
 frontend/web/components/base/Chip/index.ts    |  1 +
 4 files changed, 65 insertions(+), 3 deletions(-)
 create mode 100644 frontend/web/components/base/Chip/ChipDot.tsx

diff --git a/frontend/web/components/base/Chip/Chip.scss b/frontend/web/components/base/Chip/Chip.scss
index 854427ce3f98..3407d57ff58d 100644
--- a/frontend/web/components/base/Chip/Chip.scss
+++ b/frontend/web/components/base/Chip/Chip.scss
@@ -13,13 +13,38 @@
     border-color: var(--color-border-action);
   }
 
+  // Status colours carry their meaning in the fill, so an outline only adds
+  // noise. Transparent rather than removed, so a status chip is the same
+  // height as a bordered one beside it.
+  &--success,
+  &--warning,
+  &--danger,
+  &--info,
+  &--muted,
+  &--solid {
+    border-color: transparent;
+  }
+
+  // Status dot. currentColor, so it follows the variant with nothing to wire.
+  &__dot {
+    width: 6px;
+    height: 6px;
+    border-radius: var(--radius-full);
+    background: currentColor;
+    flex-shrink: 0;
+  }
+
   // Sizes (default is the base above).
   &--sm {
     padding: 3px 8px;
     font-size: 0.75rem;
   }
 
+  // 24px is fixed in the tags frame, so it is stated rather than left to derive
+  // from the inherited line-height. The frame's 8px vertical padding is an
+  // artefact of a height override on the auto-layout and is not applied.
   &--xs {
+    height: 24px;
     padding: 1px 6px;
     font-size: 0.6875rem;
   }
diff --git a/frontend/web/components/base/Chip/Chip.tsx b/frontend/web/components/base/Chip/Chip.tsx
index 296219372dda..e381e5d9a064 100644
--- a/frontend/web/components/base/Chip/Chip.tsx
+++ b/frontend/web/components/base/Chip/Chip.tsx
@@ -5,7 +5,18 @@ import { colorIconSecondary } from 'common/theme/tokens'
 import './Chip.scss'
 
 export type ChipSize = 'default' | 'sm' | 'xs'
-export type ChipVariant = 'neutral' | 'accent'
+export type ChipVariant =
+  | 'neutral'
+  | 'accent'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'info'
+  | 'muted'
+  | 'solid'
+  // The caller supplies the colour through className. Used by tags, whose
+  // colour is a user's decorative choice rather than a semantic role.
+  | 'none'
 
 export type ChipProps = {
   children: ReactNode
@@ -30,7 +41,24 @@ export type ChipProps = {
 // bg + text come from token utilities; the variant border lives in Chip.scss.
 const VARIANT_UTILITIES: Record<ChipVariant, string> = {
   accent: 'bg-surface-action-subtle text-action',
+
+  danger: 'bg-surface-danger text-danger',
+
+  info: 'bg-surface-info text-info',
+
+  muted: 'bg-surface-muted text-secondary',
+
   neutral: 'bg-surface-subtle text-default',
+  // No utilities: a caller-supplied colour class would otherwise have to beat
+  // these on source order alone, which a reordered stylesheet would break.
+  none: '',
+  // The one filled variant. `text-white` rather than a token because there is
+  // no inverse-text token yet; white on --color-surface-action is 5.93:1, so AA
+  // but not AAA. Note the app has a second, darker solid (`bg-primary900`, used
+  // by BetaFlag and PlanBasedAccess) that this deliberately does not cover.
+  solid: 'bg-surface-action text-white',
+  success: 'bg-surface-success text-success',
+  warning: 'bg-surface-warning text-warning',
 }
 
 // Token-based chip primitive. Uses `ds-chip` rather than the legacy `.chip`
@@ -58,10 +86,12 @@ const Chip = ({
     <span
       ref={ref}
       className={classNames(
-        'ds-chip d-inline-flex align-items-center align-middle gap-1 rounded-sm',
+        // rounded-md is 6px, fixed by the tags frame in Figma. Not a prop:
+        // every chip is the same shape.
+        'ds-chip d-inline-flex align-items-center align-middle gap-1 rounded-md',
         VARIANT_UTILITIES[variant],
+        `ds-chip--${variant}`,
         {
-          'ds-chip--accent': variant === 'accent',
           'ds-chip--clickable': interactive,
           [`ds-chip--${size}`]: size !== 'default',
           'ds-chip--truncate': truncate,
diff --git a/frontend/web/components/base/Chip/ChipDot.tsx b/frontend/web/components/base/Chip/ChipDot.tsx
new file mode 100644
index 000000000000..c00876159cce
--- /dev/null
+++ b/frontend/web/components/base/Chip/ChipDot.tsx
@@ -0,0 +1,6 @@
+import React, { FC } from 'react'
+
+// The leading dot on a status chip. Decorative: the label carries the meaning.
+const ChipDot: FC = () => <span className='ds-chip__dot' aria-hidden='true' />
+
+export default ChipDot
diff --git a/frontend/web/components/base/Chip/index.ts b/frontend/web/components/base/Chip/index.ts
index 7b7ac073a3c4..3667ea1425cc 100644
--- a/frontend/web/components/base/Chip/index.ts
+++ b/frontend/web/components/base/Chip/index.ts
@@ -1,2 +1,3 @@
 export { default } from './Chip'
+export { default as ChipDot } from './ChipDot'
 export type { ChipProps, ChipSize, ChipVariant } from './Chip'

From 8c2cdf95c10e6b45b6dd79bd6a619f5e11bec01a Mon Sep 17 00:00:00 2001
From: Talisson Costa <talisson.odcosta@gmail.com>
Date: Tue, 22 Sep 2026 09:11:35 -0300
Subject: [PATCH 2/6] refactor(experiments): rebuild StatusBadge on the chip
 primitive

It was a bespoke pill with its own stylesheet, duplicating shape, sizing and
a hand-written dark-mode block that Chip already handles. Rebuilt as a
status-to-variant map, deleting 51 lines of SCSS.

This changes the experiment status badges from fully rounded to 6px.
Deliberate: --radius-full came from StatusBadge.scss and had never been
checked against the design system, and nothing in the Figma tags frame is
fully rounded.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../experiments/StatusBadge/StatusBadge.scss  | 51 -------------------
 .../experiments/StatusBadge/StatusBadge.tsx   | 23 +++++----
 2 files changed, 14 insertions(+), 60 deletions(-)
 delete mode 100644 frontend/web/components/experiments/StatusBadge/StatusBadge.scss

diff --git a/frontend/web/components/experiments/StatusBadge/StatusBadge.scss b/frontend/web/components/experiments/StatusBadge/StatusBadge.scss
deleted file mode 100644
index bc8234e2ec38..000000000000
--- a/frontend/web/components/experiments/StatusBadge/StatusBadge.scss
+++ /dev/null
@@ -1,51 +0,0 @@
-.status-badge {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-  padding: 3px 10px;
-  border-radius: var(--radius-full);
-  font-size: var(--font-caption-xs-size);
-  font-weight: var(--font-weight-medium);
-
-  &__dot {
-    width: 6px;
-    height: 6px;
-    border-radius: var(--radius-full);
-  }
-
-  &--created {
-    background: var(--color-surface-info);
-    color: var(--color-text-info);
-
-    .status-badge__dot {
-      background: var(--color-text-info);
-    }
-  }
-
-  &--running {
-    background: var(--color-surface-success);
-    color: var(--color-text-success);
-
-    .status-badge__dot {
-      background: var(--color-text-success);
-    }
-  }
-
-  &--paused {
-    background: var(--color-surface-warning);
-    color: var(--color-text-warning);
-
-    .status-badge__dot {
-      background: var(--color-text-warning);
-    }
-  }
-
-  &--completed {
-    background: var(--color-surface-muted);
-    color: var(--color-text-secondary);
-
-    .status-badge__dot {
-      background: var(--color-text-secondary);
-    }
-  }
-}
diff --git a/frontend/web/components/experiments/StatusBadge/StatusBadge.tsx b/frontend/web/components/experiments/StatusBadge/StatusBadge.tsx
index 10561dfde212..d598ba20448b 100644
--- a/frontend/web/components/experiments/StatusBadge/StatusBadge.tsx
+++ b/frontend/web/components/experiments/StatusBadge/StatusBadge.tsx
@@ -1,19 +1,24 @@
 import { FC } from 'react'
+import Chip, { ChipDot, ChipVariant } from 'components/base/Chip'
 import { ExperimentStatus } from 'common/types/responses'
 import { EXPERIMENT_STATUS_LABELS } from 'components/experiments/constants'
-import './StatusBadge.scss'
+
+const STATUS_VARIANTS: Record<ExperimentStatus, ChipVariant> = {
+  completed: 'muted',
+  created: 'info',
+  paused: 'warning',
+  running: 'success',
+}
 
 type StatusBadgeProps = {
   status: ExperimentStatus
 }
 
-const StatusBadge: FC<StatusBadgeProps> = ({ status }) => {
-  return (
-    <span className={`status-badge status-badge--${status}`}>
-      <span className='status-badge__dot' />
-      {EXPERIMENT_STATUS_LABELS[status]}
-    </span>
-  )
-}
+const StatusBadge: FC<StatusBadgeProps> = ({ status }) => (
+  <Chip variant={STATUS_VARIANTS[status]} size='sm'>
+    <ChipDot />
+    {EXPERIMENT_STATUS_LABELS[status]}
+  </Chip>
+)
 
 export default StatusBadge

From da7447b797281383fc860443a806945de0e2437f Mon Sep 17 00:00:00 2001
From: Talisson Costa <talisson.odcosta@gmail.com>
Date: Tue, 22 Sep 2026 09:11:47 -0300
Subject: [PATCH 3/6] feat(tags): add the tag colour scale

Custom tags derive their fill, border and text from the tag's own hue at
render time, so the contrast ratio is whatever the hue happens to give and
most of the palette fails WCAG AA.

Adds a scale of validated {surface, text} pairs instead, built from the
existing primitive ramps so a ramp change carries through:

  light  surface <hue>-100  text <hue>-800
  dark   surface <hue>-900  text <hue>-100

Two exceptions, both because the ramp offers no step that works. Gold's light
surface is too pale for -800 (2.82), so its text takes -950. Slate's dark
surface at -900 is the page background, so it takes -800.

Splitting them into tag-surface and tag-text lets the generator emit
.bg-tag-<hue> and .text-tag-<hue>, so a tag needs no stylesheet of its own.

The test proves AA once, over the scale, rather than measuring contrast in the
browser. The story shows each pair as a real chip captioned with its measured
ratio, in both themes, so the claim is checkable rather than asserted.

Nothing renders against these yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../theme/__tests__/tagSwatches.test.ts       | 39 +++++++++
 frontend/common/theme/contrast.ts             | 19 +++++
 frontend/common/theme/tokens.json             | 46 +++++++++++
 .../CategoricalPalette.stories.tsx            | 76 ++++++++++++++++-
 frontend/scripts/generate-tokens.mjs          | 30 +++++++
 frontend/web/styles/_token-utilities.scss     | 22 +++++
 frontend/web/styles/_tokens.scss              | 82 +++++++++++++++++++
 7 files changed, 310 insertions(+), 4 deletions(-)
 create mode 100644 frontend/common/theme/__tests__/tagSwatches.test.ts
 create mode 100644 frontend/common/theme/contrast.ts

diff --git a/frontend/common/theme/__tests__/tagSwatches.test.ts b/frontend/common/theme/__tests__/tagSwatches.test.ts
new file mode 100644
index 000000000000..409979a3acb1
--- /dev/null
+++ b/frontend/common/theme/__tests__/tagSwatches.test.ts
@@ -0,0 +1,39 @@
+import tokens from 'common/theme/tokens.json'
+import { AA_NORMAL_TEXT, contrastRatio } from 'common/theme/contrast'
+
+type Entry = { cssVar: string; light: string; dark: string }
+
+const surfaces = tokens.tag.surface as Record<string, Entry>
+const texts = tokens.tag.text as Record<string, Entry>
+const primitives = tokens.primitives as Record<string, string>
+
+const hues = Object.keys(surfaces)
+
+describe('tag swatches', () => {
+  it('defines a surface and a text token for every hue', () => {
+    expect(hues.length).toBeGreaterThan(0)
+    expect(Object.keys(texts)).toEqual(hues)
+  })
+
+  describe.each(hues)('%s', (hue) => {
+    const surface = surfaces[hue]
+    const text = texts[hue]
+
+    it.each(['light', 'dark'] as const)('passes AA in %s mode', (theme) => {
+      expect(contrastRatio(surface[theme], text[theme])).toBeGreaterThanOrEqual(
+        AA_NORMAL_TEXT,
+      )
+    })
+  })
+
+  // Tags are told apart by colour alone, so two swatches rendering alike is
+  // the same defect as failing contrast: #8465 found the picker offering 20
+  // options that resolved to 7 colours.
+  it.each(['light', 'dark'] as const)(
+    'gives every swatch a distinct surface in %s mode',
+    (theme) => {
+      const fills = hues.map((hue) => surfaces[hue][theme].toLowerCase())
+      expect(new Set(fills).size).toBe(fills.length)
+    },
+  )
+})
diff --git a/frontend/common/theme/contrast.ts b/frontend/common/theme/contrast.ts
new file mode 100644
index 000000000000..28c64e120e1f
--- /dev/null
+++ b/frontend/common/theme/contrast.ts
@@ -0,0 +1,19 @@
+// WCAG relative luminance and contrast ratio, per
+// https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+
+export const AA_NORMAL_TEXT = 4.5
+
+export const relativeLuminance = (hex: string): number => {
+  const value = hex.replace('#', '')
+  const [r, g, b] = [0, 2, 4]
+    .map((i) => parseInt(value.substring(i, i + 2), 16) / 255)
+    .map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+export const contrastRatio = (a: string, b: string): number => {
+  const [lighter, darker] = [relativeLuminance(a), relativeLuminance(b)].sort(
+    (x, y) => y - x,
+  )
+  return (lighter + 0.05) / (darker + 0.05)
+}
diff --git a/frontend/common/theme/tokens.json b/frontend/common/theme/tokens.json
index d75701d1ab1f..0d2fa24baa56 100644
--- a/frontend/common/theme/tokens.json
+++ b/frontend/common/theme/tokens.json
@@ -143,6 +143,52 @@
       "info": { "cssVar": "--color-icon-info", "light": "#0aaddf", "dark": "#0aaddf" }
     }
   },
+  "tag": {
+    "surface": {
+      "indigo": { "cssVar": "--color-tag-indigo-surface", "light": "#ddeaff", "dark": "#222a51", "description": "Custom tag fill, indigo. Pairs with --color-tag-indigo-text." },
+      "coral": { "cssVar": "--color-tag-coral-surface", "light": "#ffddd3", "dark": "#4b1e17", "description": "Custom tag fill, coral. Pairs with --color-tag-coral-text." },
+      "gold": { "cssVar": "--color-tag-gold-surface", "light": "#f3edbf", "dark": "#362e00", "description": "Custom tag fill, gold. Pairs with --color-tag-gold-text." },
+      "green": { "cssVar": "--color-tag-green-surface", "light": "#d6f6d0", "dark": "#183612", "description": "Custom tag fill, green. Pairs with --color-tag-green-text." },
+      "orange": { "cssVar": "--color-tag-orange-surface", "light": "#ffdece", "dark": "#4a1f11", "description": "Custom tag fill, orange. Pairs with --color-tag-orange-text." },
+      "blue": { "cssVar": "--color-tag-blue-surface", "light": "#cdefff", "dark": "#0c2f4f", "description": "Custom tag fill, blue. Pairs with --color-tag-blue-text." },
+      "cyan": { "cssVar": "--color-tag-cyan-surface", "light": "#c1f4ff", "dark": "#003449", "description": "Custom tag fill, cyan. Pairs with --color-tag-cyan-text." },
+      "lavender": { "cssVar": "--color-tag-lavender-surface", "light": "#fbe0ff", "dark": "#3b2245", "description": "Custom tag fill, lavender. Pairs with --color-tag-lavender-text." },
+      "teal": { "cssVar": "--color-tag-teal-surface", "light": "#bff9ef", "dark": "#003931", "description": "Custom tag fill, teal. Pairs with --color-tag-teal-text." },
+      "navy": { "cssVar": "--color-tag-navy-surface", "light": "#d7ecff", "dark": "#1e2e49", "description": "Custom tag fill, navy. Pairs with --color-tag-navy-text." },
+      "amber": { "cssVar": "--color-tag-amber-surface", "light": "#ffe5c0", "dark": "#432600", "description": "Custom tag fill, amber. Pairs with --color-tag-amber-text." },
+      "mint": { "cssVar": "--color-tag-mint-surface", "light": "#ccf8da", "dark": "#05381e", "description": "Custom tag fill, mint. Pairs with --color-tag-mint-text." },
+      "silver": { "cssVar": "--color-tag-silver-surface", "light": "#ebebeb", "dark": "#2e2e2e", "description": "Custom tag fill, silver. Pairs with --color-tag-silver-text." },
+      "slate": { "cssVar": "--color-tag-slate-surface", "light": "#dbedff", "dark": "#212f3e", "description": "Custom tag fill, slate. Pairs with --color-tag-slate-text." },
+      "maroon": { "cssVar": "--color-tag-maroon-surface", "light": "#ffddd4", "dark": "#4b1e18", "description": "Custom tag fill, maroon. Pairs with --color-tag-maroon-text." },
+      "plum": { "cssVar": "--color-tag-plum-surface", "light": "#f4d9ff", "dark": "#3b2246", "description": "Custom tag fill, plum. Pairs with --color-tag-plum-text." },
+      "burnt-orange": { "cssVar": "--color-tag-burnt-orange-surface", "light": "#ffdfcb", "dark": "#4a200d", "description": "Custom tag fill, burnt-orange. Pairs with --color-tag-burnt-orange-text." },
+      "salmon": { "cssVar": "--color-tag-salmon-surface", "light": "#ffdcda", "dark": "#4b1d1e", "description": "Custom tag fill, salmon. Pairs with --color-tag-salmon-text." },
+      "lime": { "cssVar": "--color-tag-lime-surface", "light": "#e7f1c4", "dark": "#2b3200", "description": "Custom tag fill, lime. Pairs with --color-tag-lime-text." },
+      "cerise": { "cssVar": "--color-tag-cerise-surface", "light": "#ffdbe2", "dark": "#4a1d26", "description": "Custom tag fill, cerise. Pairs with --color-tag-cerise-text." }
+    },
+    "text": {
+      "indigo": { "cssVar": "--color-tag-indigo-text", "light": "#3948ac", "dark": "#a7baff", "description": "Custom tag label, indigo. Pairs with --color-tag-indigo-surface." },
+      "coral": { "cssVar": "--color-tag-coral-text", "light": "#9a2111", "dark": "#f7a697", "description": "Custom tag label, coral. Pairs with --color-tag-coral-surface." },
+      "gold": { "cssVar": "--color-tag-gold-text", "light": "#695400", "dark": "#cbc072", "description": "Custom tag label, gold. Pairs with --color-tag-gold-surface." },
+      "green": { "cssVar": "--color-tag-green-text", "light": "#076900", "dark": "#9bce91", "description": "Custom tag label, green. Pairs with --color-tag-green-surface." },
+      "orange": { "cssVar": "--color-tag-orange-text", "light": "#992500", "dark": "#f6a78e", "description": "Custom tag label, orange. Pairs with --color-tag-orange-surface." },
+      "blue": { "cssVar": "--color-tag-blue-text", "light": "#0055a9", "dark": "#8bc3fc", "description": "Custom tag label, blue. Pairs with --color-tag-blue-surface." },
+      "cyan": { "cssVar": "--color-tag-cyan-text", "light": "#006191", "dark": "#72cbef", "description": "Custom tag label, cyan. Pairs with --color-tag-cyan-surface." },
+      "lavender": { "cssVar": "--color-tag-lavender-text", "light": "#763090", "dark": "#d7aaea", "description": "Custom tag label, lavender. Pairs with --color-tag-lavender-surface." },
+      "teal": { "cssVar": "--color-tag-teal-text", "light": "#00675b", "dark": "#6bd3c4", "description": "Custom tag label, teal. Pairs with --color-tag-teal-surface." },
+      "navy": { "cssVar": "--color-tag-navy-text", "light": "#445674", "dark": "#aabfe1", "description": "Custom tag label, navy. Pairs with --color-tag-navy-surface." },
+      "amber": { "cssVar": "--color-tag-amber-text", "light": "#8a3d00", "dark": "#e7b374", "description": "Custom tag label, amber. Pairs with --color-tag-amber-surface." },
+      "mint": { "cssVar": "--color-tag-mint-text", "light": "#006b2e", "dark": "#88d1a2", "description": "Custom tag label, mint. Pairs with --color-tag-mint-surface." },
+      "silver": { "cssVar": "--color-tag-silver-text", "light": "#555555", "dark": "#bebebe", "description": "Custom tag label, silver. Pairs with --color-tag-silver-surface." },
+      "slate": { "cssVar": "--color-tag-slate-text", "light": "#485767", "dark": "#aec0d3", "description": "Custom tag label, slate. Pairs with --color-tag-slate-surface." },
+      "maroon": { "cssVar": "--color-tag-maroon-text", "light": "#853c32", "dark": "#f7a598", "description": "Custom tag label, maroon. Pairs with --color-tag-maroon-surface." },
+      "plum": { "cssVar": "--color-tag-plum-text", "light": "#6d3e82", "dark": "#d6aaeb", "description": "Custom tag label, plum. Pairs with --color-tag-plum-surface." },
+      "burnt-orange": { "cssVar": "--color-tag-burnt-orange-text", "light": "#982800", "dark": "#f5a989", "description": "Custom tag label, burnt-orange. Pairs with --color-tag-burnt-orange-surface." },
+      "salmon": { "cssVar": "--color-tag-salmon-text", "light": "#922b32", "dark": "#f8a4a2", "description": "Custom tag label, salmon. Pairs with --color-tag-salmon-surface." },
+      "lime": { "cssVar": "--color-tag-lime-text", "light": "#4f5f00", "dark": "#b7c77c", "description": "Custom tag label, lime. Pairs with --color-tag-lime-surface." },
+      "cerise": { "cssVar": "--color-tag-cerise-text", "light": "#991b41", "dark": "#f6a3af", "description": "Custom tag label, cerise. Pairs with --color-tag-cerise-surface." }
+    }
+  },
   "chart": {
     "1": { "cssVar": "--color-chart-1", "light": "#0aaddf", "dark": "#45bce0", "description": "First series in charts. Blue." },
     "2": { "cssVar": "--color-chart-2", "light": "#ef4d56", "dark": "#f57c78", "description": "Second series. Red." },
diff --git a/frontend/documentation/CategoricalPalette.stories.tsx b/frontend/documentation/CategoricalPalette.stories.tsx
index 2bcfcadc6a99..0df0931465c4 100644
--- a/frontend/documentation/CategoricalPalette.stories.tsx
+++ b/frontend/documentation/CategoricalPalette.stories.tsx
@@ -2,8 +2,11 @@ import React from 'react'
 import type { Meta, StoryObj } from 'storybook'
 
 import './docs.scss'
+import Chip from 'components/base/Chip'
 import DocPage from './components/DocPage'
 import Swatch from './components/Swatch'
+import tokens from 'common/theme/tokens.json'
+import { AA_NORMAL_TEXT, contrastRatio } from 'common/theme/contrast'
 
 // ---------------------------------------------------------------------------
 // Colour data — inlined to avoid importing Constants (which pulls in the
@@ -67,10 +70,10 @@ export const TagColours: StoryObj = {
       title='Tag colours'
       description={
         <>
-          20 decorative colours users pick from when creating tags. Will be
-          defined in <code>_categorical.scss</code> as CSS custom properties (
-          <code>--color-tag-1</code> through <code>--color-tag-20</code>).
-          Currently in <code>constants.ts</code> pending migration. These are
+          The 20 decorative colours users currently pick from when creating a
+          tag, held in <code>constants.ts</code>. Tags derive their fill, border
+          and text from these at render time, which is why most of them fail
+          WCAG AA. #8465 replaces that with the validated scale below. These are
           NOT semantic tokens &mdash; they are categorical identifiers that need
           to be visually distinct from each other.
         </>
@@ -88,6 +91,71 @@ export const TagColours: StoryObj = {
   ),
 }
 
+type TagEntry = { cssVar: string; light: string; dark: string }
+
+const TAG_SURFACES = tokens.tag.surface as Record<string, TagEntry>
+const TAG_TEXTS = tokens.tag.text as Record<string, TagEntry>
+const TAG_HUES = Object.keys(TAG_SURFACES)
+
+export const TagSwatches: StoryObj = {
+  name: 'Tag swatches',
+  parameters: { chromatic: { disableSnapshot: false } },
+  render: () => (
+    <DocPage
+      title='Tag swatches'
+      description={
+        <>
+          The scale a custom tag picks from, replacing the runtime colour maths
+          that made contrast a function of the user&rsquo;s chosen hue. Each hue
+          is a <code>surface</code> and <code>text</code> pair built from the
+          primitive ramps, so a ramp change carries through. Ratios below are
+          for the current theme; every pair clears AA ({AA_NORMAL_TEXT}:1) in
+          both, enforced by <code>tagSwatches.test.ts</code>.
+        </>
+      }
+    >
+      <div className='d-flex flex-wrap gap-3'>
+        {TAG_HUES.map((hue) => (
+          <div
+            className='d-flex flex-column align-items-center gap-1'
+            key={hue}
+          >
+            <Chip className={`border-0 tag-${hue}`} size='xs'>
+              {hue}
+            </Chip>
+            <small className='text-secondary'>
+              {contrastRatio(
+                TAG_SURFACES[hue].light,
+                TAG_TEXTS[hue].light,
+              ).toFixed(2)}
+              :1 light &middot;{' '}
+              {contrastRatio(
+                TAG_SURFACES[hue].dark,
+                TAG_TEXTS[hue].dark,
+              ).toFixed(2)}
+              :1 dark
+            </small>
+          </div>
+        ))}
+      </div>
+      <p className='cat-note'>
+        System tags (Issue, PR, Stale, Unhealthy) are not on this scale. They
+        stay on existing tokens &mdash; <code>bg-surface-default</code>,{' '}
+        <code>border-default</code>, <code>text-default</code> &mdash; plus a
+        coloured icon, so the state is carried by the icon rather than the fill.
+      </p>
+      <div className='d-flex mt-3'>
+        <Chip
+          className='bg-surface-default border-default text-default'
+          size='xs'
+        >
+          System tag
+        </Chip>
+      </div>
+    </DocPage>
+  ),
+}
+
 export const ProjectColours: StoryObj = {
   name: 'Project colours',
   render: () => (
diff --git a/frontend/scripts/generate-tokens.mjs b/frontend/scripts/generate-tokens.mjs
index c36e86cc0e42..0e7afe1cf7fb 100644
--- a/frontend/scripts/generate-tokens.mjs
+++ b/frontend/scripts/generate-tokens.mjs
@@ -138,6 +138,21 @@ function buildScssLines() {
     rootLines.push('')
   }
 
+  // Feature palettes. Themed like the semantic tokens, but scoped to one
+  // feature, so they sit outside `color` where only cross-cutting roles live.
+  if (json.tag) {
+    rootLines.push('  // Tag')
+    for (const [, entries] of sorted(json.tag)) {
+      for (const [, e] of sorted(entries)) {
+        rootLines.push(`  ${e.cssVar}: ${toPrimitiveRef(e.light)};`)
+        if (e.dark && e.dark !== e.light) {
+          darkLines.push(`  ${e.cssVar}: ${toPrimitiveRef(e.dark)};`)
+        }
+      }
+    }
+    rootLines.push('')
+  }
+
   // Chart colour tokens
   if (json[CHART_CATEGORY]) {
     rootLines.push('  // Chart')
@@ -470,6 +485,21 @@ function generateUtilities() {
     lines.push('')
   }
 
+  // Tag swatches. One class per hue rather than a bg/text pair, because the
+  // two are only accessible together: applying a fill without its label colour
+  // is the contrast bug this scale exists to fix.
+  if (json.tag) {
+    lines.push('// Tag swatches')
+    for (const [hue, surface] of sorted(json.tag.surface)) {
+      const text = json.tag.text[hue]
+      if (!text) continue
+      lines.push(
+        `.tag-${hue} { background-color: var(${surface.cssVar}); color: var(${text.cssVar}); }`,
+      )
+    }
+    lines.push('')
+  }
+
   // Radius utilities
   if (json.radius) {
     lines.push('// Radius')
diff --git a/frontend/web/styles/_token-utilities.scss b/frontend/web/styles/_token-utilities.scss
index 488ed0b1c3db..bf6f1cd99a3b 100644
--- a/frontend/web/styles/_token-utilities.scss
+++ b/frontend/web/styles/_token-utilities.scss
@@ -54,6 +54,28 @@
 .icon-success { color: var(--color-icon-success); fill: var(--color-icon-success); }
 .icon-warning { color: var(--color-icon-warning); fill: var(--color-icon-warning); }
 
+// Tag swatches
+.tag-amber { background-color: var(--color-tag-amber-surface); color: var(--color-tag-amber-text); }
+.tag-blue { background-color: var(--color-tag-blue-surface); color: var(--color-tag-blue-text); }
+.tag-burnt-orange { background-color: var(--color-tag-burnt-orange-surface); color: var(--color-tag-burnt-orange-text); }
+.tag-cerise { background-color: var(--color-tag-cerise-surface); color: var(--color-tag-cerise-text); }
+.tag-coral { background-color: var(--color-tag-coral-surface); color: var(--color-tag-coral-text); }
+.tag-cyan { background-color: var(--color-tag-cyan-surface); color: var(--color-tag-cyan-text); }
+.tag-gold { background-color: var(--color-tag-gold-surface); color: var(--color-tag-gold-text); }
+.tag-green { background-color: var(--color-tag-green-surface); color: var(--color-tag-green-text); }
+.tag-indigo { background-color: var(--color-tag-indigo-surface); color: var(--color-tag-indigo-text); }
+.tag-lavender { background-color: var(--color-tag-lavender-surface); color: var(--color-tag-lavender-text); }
+.tag-lime { background-color: var(--color-tag-lime-surface); color: var(--color-tag-lime-text); }
+.tag-maroon { background-color: var(--color-tag-maroon-surface); color: var(--color-tag-maroon-text); }
+.tag-mint { background-color: var(--color-tag-mint-surface); color: var(--color-tag-mint-text); }
+.tag-navy { background-color: var(--color-tag-navy-surface); color: var(--color-tag-navy-text); }
+.tag-orange { background-color: var(--color-tag-orange-surface); color: var(--color-tag-orange-text); }
+.tag-plum { background-color: var(--color-tag-plum-surface); color: var(--color-tag-plum-text); }
+.tag-salmon { background-color: var(--color-tag-salmon-surface); color: var(--color-tag-salmon-text); }
+.tag-silver { background-color: var(--color-tag-silver-surface); color: var(--color-tag-silver-text); }
+.tag-slate { background-color: var(--color-tag-slate-surface); color: var(--color-tag-slate-text); }
+.tag-teal { background-color: var(--color-tag-teal-surface); color: var(--color-tag-teal-text); }
+
 // Radius
 .rounded-2xl { border-radius: var(--radius-2xl); }
 .rounded-full { border-radius: var(--radius-full); }
diff --git a/frontend/web/styles/_tokens.scss b/frontend/web/styles/_tokens.scss
index ce37f7bf5dfa..ef3e721e8c64 100644
--- a/frontend/web/styles/_tokens.scss
+++ b/frontend/web/styles/_tokens.scss
@@ -146,6 +146,48 @@
   --color-icon-success: var(--green-500);
   --color-icon-warning: var(--orange-500);
 
+  // Tag
+  --color-tag-amber-surface: #ffe5c0;
+  --color-tag-blue-surface: #cdefff;
+  --color-tag-burnt-orange-surface: #ffdfcb;
+  --color-tag-cerise-surface: #ffdbe2;
+  --color-tag-coral-surface: #ffddd3;
+  --color-tag-cyan-surface: #c1f4ff;
+  --color-tag-gold-surface: #f3edbf;
+  --color-tag-green-surface: #d6f6d0;
+  --color-tag-indigo-surface: #ddeaff;
+  --color-tag-lavender-surface: #fbe0ff;
+  --color-tag-lime-surface: #e7f1c4;
+  --color-tag-maroon-surface: #ffddd4;
+  --color-tag-mint-surface: #ccf8da;
+  --color-tag-navy-surface: #d7ecff;
+  --color-tag-orange-surface: #ffdece;
+  --color-tag-plum-surface: #f4d9ff;
+  --color-tag-salmon-surface: #ffdcda;
+  --color-tag-silver-surface: #ebebeb;
+  --color-tag-slate-surface: #dbedff;
+  --color-tag-teal-surface: #bff9ef;
+  --color-tag-amber-text: #8a3d00;
+  --color-tag-blue-text: #0055a9;
+  --color-tag-burnt-orange-text: #982800;
+  --color-tag-cerise-text: #991b41;
+  --color-tag-coral-text: #9a2111;
+  --color-tag-cyan-text: #006191;
+  --color-tag-gold-text: #695400;
+  --color-tag-green-text: #076900;
+  --color-tag-indigo-text: #3948ac;
+  --color-tag-lavender-text: #763090;
+  --color-tag-lime-text: #4f5f00;
+  --color-tag-maroon-text: #853c32;
+  --color-tag-mint-text: #006b2e;
+  --color-tag-navy-text: #445674;
+  --color-tag-orange-text: #992500;
+  --color-tag-plum-text: #6d3e82;
+  --color-tag-salmon-text: #922b32;
+  --color-tag-silver-text: #555555;
+  --color-tag-slate-text: #485767;
+  --color-tag-teal-text: #00675b;
+
   // Chart
   --color-chart-1: var(--blue-500);
   --color-chart-2: var(--red-500);
@@ -234,6 +276,46 @@
   --color-icon-default: var(--slate-0);
   --color-icon-disabled: oklch(from var(--slate-0) l c h / 0.32);
   --color-icon-secondary: var(--slate-300);
+  --color-tag-amber-surface: #432600;
+  --color-tag-blue-surface: #0c2f4f;
+  --color-tag-burnt-orange-surface: #4a200d;
+  --color-tag-cerise-surface: #4a1d26;
+  --color-tag-coral-surface: #4b1e17;
+  --color-tag-cyan-surface: #003449;
+  --color-tag-gold-surface: #362e00;
+  --color-tag-green-surface: #183612;
+  --color-tag-indigo-surface: #222a51;
+  --color-tag-lavender-surface: #3b2245;
+  --color-tag-lime-surface: #2b3200;
+  --color-tag-maroon-surface: #4b1e18;
+  --color-tag-mint-surface: #05381e;
+  --color-tag-navy-surface: #1e2e49;
+  --color-tag-orange-surface: #4a1f11;
+  --color-tag-plum-surface: #3b2246;
+  --color-tag-salmon-surface: #4b1d1e;
+  --color-tag-silver-surface: #2e2e2e;
+  --color-tag-slate-surface: #212f3e;
+  --color-tag-teal-surface: #003931;
+  --color-tag-amber-text: #e7b374;
+  --color-tag-blue-text: #8bc3fc;
+  --color-tag-burnt-orange-text: #f5a989;
+  --color-tag-cerise-text: #f6a3af;
+  --color-tag-coral-text: #f7a697;
+  --color-tag-cyan-text: #72cbef;
+  --color-tag-gold-text: #cbc072;
+  --color-tag-green-text: #9bce91;
+  --color-tag-indigo-text: #a7baff;
+  --color-tag-lavender-text: #d7aaea;
+  --color-tag-lime-text: #b7c77c;
+  --color-tag-maroon-text: #f7a598;
+  --color-tag-mint-text: #88d1a2;
+  --color-tag-navy-text: #aabfe1;
+  --color-tag-orange-text: #f6a78e;
+  --color-tag-plum-text: #d6aaeb;
+  --color-tag-salmon-text: #f8a4a2;
+  --color-tag-silver-text: #bebebe;
+  --color-tag-slate-text: #aec0d3;
+  --color-tag-teal-text: #6bd3c4;
   --color-chart-1: var(--blue-400);
   --color-chart-2: var(--red-400);
   --color-chart-3: var(--green-400);

From 7cf94581aa92b962ecbd2c2b976ff65326bc7a37 Mon Sep 17 00:00:00 2001
From: Talisson Costa <talisson.odcosta@gmail.com>
Date: Tue, 22 Sep 2026 09:11:59 -0300
Subject: [PATCH 4/6] feat(icons): add stale and pr-dequeued, and colour
 pr-draft

The design asks for a redrawn Stale, the ionicon being too detailed at 16px,
and a PR dequeued icon. The latter is a live gap rather than a nicety:
GitHubTag.PR_DEQUEUED is already written by the API when GitHub reports a PR
leaving a merge queue, so that tag reaches the UI and renderIcon falls through
to a bare return.

Both follow the frame's spec, 16px at 1.5px stroke, and are drawn at 0.88 of
the box so they carry the same optical weight as the fill-based Octicons
beside them.

pr-draft moves onto --color-icon-secondary. It was the only status icon on
currentColor, so it took the chip's label colour: near-black in light, white
in dark, neither of which the design asks for. Its siblings hardcode GitHub's
brand colours, which are the same in either theme, but the design gives
pr-draft #747B86, a neutral, and a neutral cannot be hardcoded: it has to lift
in dark mode or it sinks into the surface.

Both new icons are registered in the catalogue, which is a hand-maintained
list, so an icon is invisible in Storybook without it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../components/Icons.stories.tsx              |  2 +
 frontend/web/components/icons/Icon.tsx        | 45 ++++++++++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/frontend/documentation/components/Icons.stories.tsx b/frontend/documentation/components/Icons.stories.tsx
index dff1c2ba7125..e35040a5ffb8 100644
--- a/frontend/documentation/components/Icons.stories.tsx
+++ b/frontend/documentation/components/Icons.stories.tsx
@@ -60,6 +60,7 @@ const CATEGORIES: IconCategory[] = [
       'info-outlined',
       'lock',
       'shield',
+      'stale',
       'warning',
     ],
     label: 'Status',
@@ -70,6 +71,7 @@ const CATEGORIES: IconCategory[] = [
       'issue-closed',
       'issue-linked',
       'pr-closed',
+      'pr-dequeued',
       'pr-draft',
       'pr-linked',
       'pr-merged',
diff --git a/frontend/web/components/icons/Icon.tsx b/frontend/web/components/icons/Icon.tsx
index c47b4e0ede1a..a740a0d25dcc 100644
--- a/frontend/web/components/icons/Icon.tsx
+++ b/frontend/web/components/icons/Icon.tsx
@@ -1,4 +1,5 @@
 import { FC } from 'react'
+import { colorIconSecondary, colorIconWarning } from 'common/theme/tokens'
 
 export type IconName =
   | 'arrow-left'
@@ -50,7 +51,9 @@ export type IconName =
   | 'pr-closed'
   | 'pr-draft'
   | 'pr-linked'
+  | 'pr-dequeued'
   | 'pr-merged'
+  | 'stale'
   | 'radio'
   | 'refresh'
   | 'request'
@@ -1272,13 +1275,53 @@ const Icon: FC<IconType> = ({
         </svg>
       )
     }
+    case 'pr-dequeued': {
+      return (
+        <svg
+          width={width || '16'}
+          height={height || width || '16'}
+          viewBox='0 0 16 16'
+          fill='none'
+          stroke='#8957e5'
+          strokeWidth='1.5'
+          strokeLinecap='round'
+          strokeLinejoin='round'
+          xmlns='http://www.w3.org/2000/svg'
+        >
+          <path d='M10.7 3.5a5.3 5.3 0 1 1-5.4 0' />
+          <path d='M8.4 6.2 6.5 8l1.9 1.8' />
+          <circle cx='12.6' cy='3.7' r='1.2' fill='#8957e5' stroke='none' />
+        </svg>
+      )
+    }
+    case 'stale': {
+      return (
+        <svg
+          width={width || '16'}
+          height={height || width || '16'}
+          viewBox='0 0 16 16'
+          fill='none'
+          stroke={fill || colorIconWarning}
+          strokeWidth='1.5'
+          strokeLinecap='round'
+          strokeLinejoin='round'
+          xmlns='http://www.w3.org/2000/svg'
+        >
+          <path d='M10.6 3.6a5.3 5.3 0 1 0 1.9 2.8' />
+          <path d='M7.7 5v3.2l2.1 1.5' />
+          <path d='M11.2 2.8h2l-2 2.3h2' />
+        </svg>
+      )
+    }
     case 'pr-draft': {
       return (
         <svg
           height={height || '16'}
           version='1.1'
           width={width || '16'}
-          fill={fill || 'currentColor'}
+          // A neutral, unlike its hardcoded brand-coloured siblings, so it
+          // has to lift in dark mode.
+          fill={fill || colorIconSecondary}
           className='ml-1'
           xmlns='http://www.w3.org/2000/svg'
         >

From 0913981e4e5301eae67950e5a15e5d51329cfdd4 Mon Sep 17 00:00:00 2001
From: Talisson Costa <talisson.odcosta@gmail.com>
Date: Tue, 22 Sep 2026 09:12:14 -0300
Subject: [PATCH 5/6] fix(tags): carry tag state in an icon, not the fill

Tags rendered the tag's own colour as text on an 8% tint of itself, so the
contrast ratio was whatever the hue happened to give and most of the palette
failed WCAG AA.

System tags (Issue, PR, Stale, Unhealthy) now sit on plain surface with a
neutral border and a coloured icon, so the state is carried by the icon and
the label keeps full contrast. Custom tags take a validated swatch pair from
the scale, keyed on the colour already stored, so no tag changes identity and
nothing needs migrating.

That removes every colour computation, in all four places it had been copied
to, two of which no stylesheet could reach:

  Tag.tsx           fade(.92) / fade(.76) / darken(.1), plus shouldLighten
                    and a #344562 special case, both of which existed only
                    because the fill was the hue
  TagContent.tsx    darken(.1) for the icon, and the same three again as an
                    inline style string
  ToggleChip.tsx    the same three, on Tag's onClick path
  FeatureAction.tsx the same three, in a tooltip string

The two string sites stay strings, being rendered through
dangerouslySetInnerHTML, but they now carry the same classes as the real chip
rather than their own copy of the rules.

renderIcon also now answers to GITLAB, which had never been wired. Harmless
while the fill carried the state; a regression once it does not.

TagType gains GITHUB and GITLAB to match the API enum. The icon switch has
always branched on values the type said could not occur.

escapeHTML's character class is restated as the characters it keeps. Same set,
proven equivalent across U+0000..U+1FFF, but without control characters in the
literal, which the pre-commit lint rejects now the file is touched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 frontend/common/types/responses.ts            |  4 +-
 .../components/ToggleChip.stories.tsx         | 33 ++++----
 frontend/web/components/ToggleChip.scss       | 20 +++++
 frontend/web/components/ToggleChip.tsx        | 53 +++++-------
 .../feature-summary/FeatureAction.tsx         | 19 +++--
 frontend/web/components/tags/Tag.tsx          | 81 +++++++------------
 frontend/web/components/tags/TagContent.tsx   | 74 +++++++++--------
 frontend/web/components/tags/TagValues.tsx    |  1 -
 frontend/web/components/tags/tagSwatch.ts     | 69 ++++++++++++++++
 9 files changed, 202 insertions(+), 152 deletions(-)
 create mode 100644 frontend/web/components/ToggleChip.scss
 create mode 100644 frontend/web/components/tags/tagSwatch.ts

diff --git a/frontend/common/types/responses.ts b/frontend/common/types/responses.ts
index 09acf96940a9..9acafb87ae12 100644
--- a/frontend/common/types/responses.ts
+++ b/frontend/common/types/responses.ts
@@ -572,7 +572,9 @@ export type APIKey = {
   name: string
 }
 
-export type TagType = 'STALE' | 'UNHEALTHY' | 'NONE'
+// Mirrors TagType in api/projects/tags/models.py. GITHUB and GITLAB were
+// missing, though the UI has always branched on them to pick a VCS icon.
+export type TagType = 'NONE' | 'STALE' | 'GITHUB' | 'UNHEALTHY' | 'GITLAB'
 
 export type Tag = {
   id: number
diff --git a/frontend/documentation/components/ToggleChip.stories.tsx b/frontend/documentation/components/ToggleChip.stories.tsx
index b9d153a091aa..ab6c7cacc858 100644
--- a/frontend/documentation/components/ToggleChip.stories.tsx
+++ b/frontend/documentation/components/ToggleChip.stories.tsx
@@ -2,19 +2,19 @@ import React, { useState } from 'react'
 import type { Meta, StoryObj } from 'storybook'
 
 import ToggleChip from 'components/ToggleChip'
-import {
-  colorChart2,
-  colorChart3,
-  colorSurfaceAction,
-} from 'common/theme/tokens'
 
 const meta: Meta<typeof ToggleChip> = {
-  argTypes: {
-    color: { control: 'color' },
-  },
-  args: { active: false, children: 'Feature flag', color: colorSurfaceAction },
+  args: { active: false, children: 'Feature flag' },
   component: ToggleChip,
-  parameters: { layout: 'centered' },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A selectable chip with a leading checkbox. It holds no palette: colour arrives as token utilities in className, so a tag hands it a validated swatch pair rather than a hex to derive from.',
+      },
+    },
+    layout: 'centered',
+  },
   title: 'Components/Data Display/ToggleChip',
 }
 export default meta
@@ -35,16 +35,15 @@ export const Default: Story = {
 }
 
 export const AllStates: Story = {
+  parameters: { chromatic: { disableSnapshot: false } },
   render: () => (
     <div className='d-flex gap-2'>
-      <ToggleChip color={colorSurfaceAction} active>
-        Active
-      </ToggleChip>
-      <ToggleChip color={colorSurfaceAction}>Inactive</ToggleChip>
-      <ToggleChip color={colorChart2} active>
-        Danger
+      <ToggleChip active>Active</ToggleChip>
+      <ToggleChip>Inactive</ToggleChip>
+      <ToggleChip active className='tag-green border-0'>
+        Swatch, active
       </ToggleChip>
-      <ToggleChip color={colorChart3}>Success</ToggleChip>
+      <ToggleChip className='tag-green border-0'>Swatch</ToggleChip>
     </div>
   ),
 }
diff --git a/frontend/web/components/ToggleChip.scss b/frontend/web/components/ToggleChip.scss
new file mode 100644
index 000000000000..8b8d51432155
--- /dev/null
+++ b/frontend/web/components/ToggleChip.scss
@@ -0,0 +1,20 @@
+// The leading checkbox. Its styles used to come from `.chip .icon-check` in
+// _chip.scss, which no longer applies now ToggleChip composes the chip
+// primitive, so they live with the component that owns them.
+.toggle-chip__check {
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-xs);
+
+  // Checked: the tick supplies the colour, so the box gets out of its way.
+  &--active {
+    border-color: transparent;
+  }
+
+  svg {
+    width: 14px;
+    height: 14px;
+  }
+}
diff --git a/frontend/web/components/ToggleChip.tsx b/frontend/web/components/ToggleChip.tsx
index a56708d9e83d..ee9b88c4e9ed 100644
--- a/frontend/web/components/ToggleChip.tsx
+++ b/frontend/web/components/ToggleChip.tsx
@@ -1,10 +1,10 @@
 import React, { FC, ReactNode } from 'react'
 import cx from 'classnames'
 import Icon from './icons/Icon'
-import Utils from 'common/utils/utils'
+import Chip from './base/Chip'
+import './ToggleChip.scss'
 
 type ToggleChipProps = {
-  color?: string
   active?: boolean
   onClick?: () => void
   className?: string
@@ -15,37 +15,26 @@ const ToggleChip: FC<ToggleChipProps> = ({
   active,
   children,
   className,
-  color,
   onClick,
-}) => {
-  const colour = Utils.colour(color)
-  return (
-    <Row
-      style={
-        color
-          ? {
-              backgroundColor: children ? colour.fade(0.92) : colour.fade(0.76),
-              border: `1px solid ${colour.fade(0.76)}`,
-              color: colour.darken(0.1),
-            }
-          : undefined
-      }
-      onClick={onClick}
-      className={cx('chip no-wrap mr-1 mt-0 clickable', className)}
+}) => (
+  <Chip
+    className={cx('no-wrap mr-1 mt-0', className)}
+    onClick={onClick}
+    size='xs'
+    variant='none'
+  >
+    {/* Without a label this is a bare swatch, e.g. the tag colour picker, where
+        the box would be noise: the tick alone marks the selection. */}
+    <span
+      className={cx('d-inline-flex align-items-center justify-content-center', {
+        'toggle-chip__check': !!children,
+        'toggle-chip__check--active': active && !!children,
+      })}
     >
-      <span
-        style={{
-          backgroundColor: active ? 'white' : 'transparent',
-          border:
-            active || !children ? 'none' : `1px solid ${colour.fade(0.76)}`,
-        }}
-        className={cx('icon-check', children ? 'mr-2' : null)}
-      >
-        {active && <Icon name='checkmark-square' fill={color} />}
-      </span>
-      {children}
-    </Row>
-  )
-}
+      {active && <Icon name='checkmark' width={14} />}
+    </span>
+    {children}
+  </Chip>
+)
 
 export default ToggleChip
diff --git a/frontend/web/components/feature-summary/FeatureAction.tsx b/frontend/web/components/feature-summary/FeatureAction.tsx
index 63216aae803d..bce7446c18e5 100644
--- a/frontend/web/components/feature-summary/FeatureAction.tsx
+++ b/frontend/web/components/feature-summary/FeatureAction.tsx
@@ -6,8 +6,8 @@ import Constants from 'common/constants'
 import Permission from 'common/providers/Permission'
 import Icon from 'components/icons/Icon'
 import { Tag } from 'common/types/responses'
-import color from 'color'
 import { getTagColor } from 'components/tags/Tag'
+import { getTagSwatchUtilities } from 'components/tags/tagSwatch'
 import ActionButton from 'components/ActionButton'
 import ActionItem from 'components/shared/ActionItem'
 import { calculateListPosition } from 'common/utils/calculateListPosition'
@@ -171,16 +171,15 @@ const FeatureAction: FC<FeatureActionProps> = ({
                       ? `<span>This feature has been tagged with the permanent tag${
                           protectedTags?.length > 1 ? 's' : ''
                         } ${protectedTags
-                          ?.map((tag) => {
-                            const tagColor = Utils.colour(getTagColor(tag))
-                            return `<strong class='chip chip--xs d-inline-block ms-1' style='background:${color(
-                              tagColor,
-                            ).fade(0.92)};border-color:${tagColor.darken(
-                              0.1,
-                            )};color:${tagColor.darken(0.1)};'>
+                          ?.map(
+                            // dangerouslySetInnerHTML, so not a component.
+                            (tag) =>
+                              `<strong class='ds-chip ds-chip--xs d-inline-flex align-items-center rounded-md ms-1 border-0 ${getTagSwatchUtilities(
+                                getTagColor(tag),
+                              )}'>
                         ${tag.label}
-                      </strong>`
-                          })
+                      </strong>`,
+                          )
                           .join('')}. Please remove the tag${
                           protectedTags?.length > 1 ? 's' : ''
                         } before attempting to delete this flag.</span>`
diff --git a/frontend/web/components/tags/Tag.tsx b/frontend/web/components/tags/Tag.tsx
index 5e8edefbf35b..b1c8b09cc736 100644
--- a/frontend/web/components/tags/Tag.tsx
+++ b/frontend/web/components/tags/Tag.tsx
@@ -2,12 +2,16 @@ import React, { FC } from 'react'
 import cx from 'classnames'
 
 import { Tag as TTag } from 'common/types/responses'
+import Chip from 'components/base/Chip'
 import ToggleChip from 'components/ToggleChip'
 import Utils from 'common/utils/utils'
 import TagContent from './TagContent'
 import Constants from 'common/constants'
-import { getDarkMode } from 'project/darkMode'
-import Color from 'color'
+import {
+  SYSTEM_TAG_UTILITIES,
+  getTagSwatchUtilities,
+  isSystemTag,
+} from './tagSwatch'
 
 type TagType = {
   className?: string
@@ -18,46 +22,13 @@ type TagType = {
   isDot?: boolean
 }
 
-export const getTagColor = (tag: Partial<TTag>, selected?: boolean) => {
-  if (getDarkMode() && tag.color === '#344562') {
-    return '#9DA4AE'
-  }
+export const getTagColor = (tag: Partial<TTag>) => {
   if (tag.type === 'UNHEALTHY') {
     return Constants.featureHealth.unhealthyColor
   }
-  if (selected) {
-    return tag.color
-  }
   return tag.color
 }
 
-export const TagWrapper = ({
-  children,
-  className,
-  disabled,
-  onClick,
-  tag,
-  tagColor,
-}: any) => {
-  return (
-    <div
-      onClick={() => {
-        if (!disabled) {
-          onClick?.(tag as TTag)
-        }
-      }}
-      style={{
-        backgroundColor: `${tagColor.fade(0.92)}`,
-        border: `1px solid ${tagColor.fade(0.76)}`,
-        color: `${tagColor.darken(0.1)}`,
-      }}
-      className={cx('chip', className)}
-    >
-      {children}
-    </div>
-  )
-}
-
 const Tag: FC<TagType> = ({
   className,
   hideNames,
@@ -66,15 +37,12 @@ const Tag: FC<TagType> = ({
   selected,
   tag,
 }) => {
-  const shouldLighten = (color: Color) => getDarkMode() && color.isDark()
-  const tagColor = Utils.colour(getTagColor(tag, selected))
   if (isDot) {
     return (
       <div
         className={'tag--dot'}
-        style={{
-          backgroundColor: `${tagColor.darken(0.1)}`,
-        }}
+        // No text on the dot, so the tag's own colour is safe here.
+        style={{ backgroundColor: getTagColor(tag) }}
       />
     )
   }
@@ -84,8 +52,7 @@ const Tag: FC<TagType> = ({
   if (!hideNames && !!onClick) {
     return (
       <ToggleChip
-        className={className}
-        color={shouldLighten(tagColor) ? tagColor.lighten(0.5) : tagColor}
+        className={cx(getTagSwatchUtilities(getTagColor(tag)), className)}
         active={selected}
         onClick={() => {
           if (!disabled) {
@@ -106,19 +73,27 @@ const Tag: FC<TagType> = ({
     return null
   }
 
+  const isSystem = isSystemTag(tag)
+
   return (
-    <TagWrapper
-      tagColor={shouldLighten(tagColor) ? tagColor.lighten(0.5) : tagColor}
-      className={className}
-      disabled={disabled}
-      hideNames={hideNames}
-      isDot={isDot}
-      onClick={onClick}
-      selected={selected}
-      tag={tag}
+    <Chip
+      className={cx(
+        // Legacy `.chip` carried margin-right; the primitive does not, so tags
+        // keep it here or they butt against whatever follows.
+        'me-1',
+        isSystem
+          ? SYSTEM_TAG_UTILITIES
+          : getTagSwatchUtilities(getTagColor(tag)),
+        // The fill carries the colour, so a border would double the edge.
+        { 'border-0': !isSystem, 'opacity-50': disabled },
+        className,
+      )}
+      onClick={disabled || !onClick ? undefined : () => onClick(tag as TTag)}
+      size='xs'
+      variant='none'
     >
       <TagContent tag={tag} />
-    </TagWrapper>
+    </Chip>
   )
 }
 
diff --git a/frontend/web/components/tags/TagContent.tsx b/frontend/web/components/tags/TagContent.tsx
index e7c5dc289845..b8668048066f 100644
--- a/frontend/web/components/tags/TagContent.tsx
+++ b/frontend/web/components/tags/TagContent.tsx
@@ -1,58 +1,56 @@
 import React, { FC } from 'react'
 import { Tag as TTag } from 'common/types/responses'
 import Format from 'common/utils/format'
-import { IonIcon } from '@ionic/react'
-import { alarmOutline, lockClosed, warning } from 'ionicons/icons'
 import Tooltip from 'components/Tooltip'
-import { getTagColor } from './Tag'
 import OrganisationStore from 'common/stores/organisation-store'
 import Utils from 'common/utils/utils'
 import classNames from 'classnames'
-import Icon from 'components/icons/Icon'
-import Color from 'color'
+import Icon, { IconName } from 'components/icons/Icon'
+import {
+  SYSTEM_TAG_UTILITIES,
+  getTagSwatchUtilities,
+  isSystemTag,
+} from './tagSwatch'
 type TagContent = {
   tag: Partial<TTag>
 }
+// Numeric-entity everything that is not alphanumeric or beyond Latin-1.
+// Stated as the characters it keeps rather than the four ranges it escaped:
+// the same set, without control characters in the literal.
 function escapeHTML(unsafe: string) {
   return unsafe.replace(
-    /[\u0000-\u002F\u003A-\u0040\u005B-\u0060\u007B-\u00FF]/g,
+    /[^0-9A-Za-z\u0100-\uFFFF]/g,
     (c) => `&#${`000${c.charCodeAt(0)}`.slice(-4)};`,
   )
 }
 
+const VCS_ICON_BY_LABEL: Record<string, IconName> = {
+  'Issue Closed': 'issue-closed',
+  'Issue Open': 'issue-linked',
+  'PR Closed': 'pr-closed',
+  'PR Dequeued': 'pr-dequeued',
+  'PR Draft': 'pr-draft',
+  'PR Merged': 'pr-merged',
+  'PR Open': 'pr-linked',
+}
+
 const renderIcon = (
   tagType: string,
-  tagColor: string,
   tagLabel: string,
   isPermanent: boolean,
 ) => {
-  const darkened = tagColor.darken(0.1).string()
   switch (tagType) {
     case 'STALE':
-      return <IonIcon className='ms-1' icon={alarmOutline} color={darkened} />
+      return <Icon name='stale' />
     case 'UNHEALTHY':
-      return <IonIcon className='ms-1' icon={warning} color={darkened} />
+      return <Icon name='warning' width={16} />
     case 'GITHUB':
-      switch (tagLabel) {
-        case 'PR Open':
-          return <Icon name='pr-linked' />
-        case 'PR Merged':
-          return <Icon name='pr-merged' />
-        case 'PR Closed':
-          return <Icon name='pr-closed' />
-        case 'PR Draft':
-          return <Icon name='pr-draft' />
-        case 'Issue Open':
-          return <Icon name='issue-linked' />
-        case 'Issue Closed':
-          return <Icon name='issue-closed' />
-        default:
-          return
-      }
+    case 'GITLAB': {
+      const icon = VCS_ICON_BY_LABEL[tagLabel]
+      return icon ? <Icon name={icon} /> : null
+    }
     default:
-      return isPermanent ? (
-        <IonIcon className='ms-1' icon={lockClosed} color={darkened} />
-      ) : null
+      return isPermanent ? <Icon name='lock' width={16} /> : null
   }
 }
 
@@ -83,17 +81,17 @@ const getTooltip = (tag: TTag | undefined) => {
     tooltip =
       'Features marked with this tag are not monitored for staleness and have deletion protection.'
   }
-  const tagColor = Utils.colour(getTagColor(tag, false))
-
   if (isTruncated) {
+    // Goes through dangerouslySetInnerHTML, so it cannot be a component. Same
+    // classes as the real chip, so there is one set of colour rules.
+    const utilities = isSystemTag(tag)
+      ? SYSTEM_TAG_UTILITIES
+      : `${getTagSwatchUtilities(tag.color)} border-0`
     return `<div>
         <span
-          style='background-color: ${tagColor.fade(0.92)};
-          border: 1px solid ${tagColor.fade(0.76)};
-          color: ${tagColor.darken(0.1)};'
-          class="chip d-inline-block chip--xs me-1${
-            disabled ? ' disabled' : ''
-          }"
+          class="ds-chip ds-chip--xs d-inline-flex align-items-center rounded-md me-1 ${utilities}${
+      disabled ? ' opacity-50' : ''
+    }"
         >
           ${`${escapeHTML(tag.label)}`}
         </span>
@@ -121,7 +119,7 @@ const TagContent: FC<TagContent> = ({ tag }) => {
           })}
         >
           {tagLabel}
-          {renderIcon(tag.type!, Utils.colour(tag.color), tag.label!)}
+          {renderIcon(tag.type!, tag.label!, !!tag.is_permanent)}
         </span>
       }
     >
diff --git a/frontend/web/components/tags/TagValues.tsx b/frontend/web/components/tags/TagValues.tsx
index 66fa495e54f8..53d2d700fbfe 100644
--- a/frontend/web/components/tags/TagValues.tsx
+++ b/frontend/web/components/tags/TagValues.tsx
@@ -49,7 +49,6 @@ const TagValues: FC<TagValuesType> = ({
           value?.includes(tag.id) && (
             <Tag
               key={tag.id}
-              className='chip--xs'
               hideNames={hideNames}
               onClick={onAdd ?? onClick}
               tag={tag}
diff --git a/frontend/web/components/tags/tagSwatch.ts b/frontend/web/components/tags/tagSwatch.ts
new file mode 100644
index 000000000000..f202ee04ffd8
--- /dev/null
+++ b/frontend/web/components/tags/tagSwatch.ts
@@ -0,0 +1,69 @@
+import { Tag as TTag } from 'common/types/responses'
+
+export type TagSwatch =
+  | 'indigo'
+  | 'coral'
+  | 'gold'
+  | 'green'
+  | 'orange'
+  | 'blue'
+  | 'cyan'
+  | 'lavender'
+  | 'teal'
+  | 'navy'
+  | 'amber'
+  | 'mint'
+  | 'silver'
+  | 'slate'
+  | 'maroon'
+  | 'plum'
+  | 'burnt-orange'
+  | 'salmon'
+  | 'lime'
+  | 'cerise'
+
+// Keyed on the colour already stored on the tag, so nothing needs migrating.
+//
+// One swatch per colour the picker offers, so no two tags render alike.
+// Each is derived from that colour's own hue and validated at AA; the
+// values are provisional until the palette work with design settles.
+const SWATCH_BY_COLOUR: Record<string, TagSwatch> = {
+  '#039587': 'teal',
+  '#1492f4': 'blue',
+  '#14c0f4': 'cyan',
+  '#344562': 'navy',
+  '#3cb371': 'mint',
+  '#3d4db6': 'indigo',
+  '#5b2c6f': 'plum',
+  '#5d6d7e': 'slate',
+  '#60bd4e': 'green',
+  '#641e16': 'maroon',
+  '#aac200': 'lime',
+  '#c277e0': 'lavender',
+  '#c6b215': 'gold',
+  '#d35400': 'burnt-orange',
+  '#d3d3d3': 'silver',
+  '#de3163': 'cerise',
+  '#ea5a45': 'coral',
+  '#f08080': 'salmon',
+  '#fe5505': 'orange',
+  '#ffa500': 'amber',
+}
+
+// The API takes any hex (`color` is a bare CharField with no validator), so a
+// tag created outside the picker can hold a colour the scale does not cover.
+const NEUTRAL_UTILITIES = 'bg-surface-subtle text-default'
+
+export const getTagSwatch = (colour?: string | null): TagSwatch | null =>
+  colour ? SWATCH_BY_COLOUR[colour.toLowerCase()] ?? null : null
+
+export const getTagSwatchUtilities = (colour?: string | null): string => {
+  const swatch = getTagSwatch(colour)
+  return swatch ? `tag-${swatch}` : NEUTRAL_UTILITIES
+}
+
+export const isSystemTag = (tag: Partial<TTag>): boolean =>
+  !!tag.type && tag.type !== 'NONE'
+
+export const SYSTEM_TAG_UTILITIES =
+  'bg-surface-default border-default text-default'

From 4bce3e4e74cff5a676bbd73a935ec9cea6c7ef3f Mon Sep 17 00:00:00 2001
From: Talisson Costa <talisson.odcosta@gmail.com>
Date: Tue, 22 Sep 2026 09:12:24 -0300
Subject: [PATCH 6/6] docs(chip): story the variants and how a tag composes
 Chip

Covers the semantic variants and the solid fill, then the two shapes a tag
takes: a system tag on plain surface with a coloured icon, and a custom tag
carrying a swatch pair.

The tag stories live here rather than beside Tag because there is no tag
component to story. Tag reads the store and the flags, and the appearance
decision lives in tagSwatch.ts, which is pure and tested on its own.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../documentation/components/Chip.stories.tsx | 105 +++++++++++++++++-
 1 file changed, 103 insertions(+), 2 deletions(-)

diff --git a/frontend/documentation/components/Chip.stories.tsx b/frontend/documentation/components/Chip.stories.tsx
index c88fe9860935..798a7ad7a484 100644
--- a/frontend/documentation/components/Chip.stories.tsx
+++ b/frontend/documentation/components/Chip.stories.tsx
@@ -1,7 +1,10 @@
 import React from 'react'
 import type { Meta, StoryObj } from 'storybook'
 
-import Chip from 'components/base/Chip'
+import Chip, { ChipDot } from 'components/base/Chip'
+import Icon, { IconName } from 'components/icons/Icon'
+import Constants from 'common/constants'
+import { getTagSwatchUtilities } from 'components/tags/tagSwatch'
 
 const meta: Meta<typeof Chip> = {
   args: { children: 'Production' },
@@ -11,7 +14,7 @@ const meta: Meta<typeof Chip> = {
     docs: {
       description: {
         component:
-          'Canonical token-based chip primitive: a small labelled pill token. Layout via Bootstrap utilities, colour/radius via token utilities, padding/sizes/border/truncation in SCSS. Leading/trailing icons go in as children. Selection lives in ToggleChip and count badges are a separate Badge concern. The legacy `.chip` (old SCSS vars + manual dark-mode block, ~35×) migrates onto this under #6606.',
+          'Canonical token-based chip primitive: a small labelled pill token. Layout via Bootstrap utilities, colour/radius via token utilities, padding/sizes/border/truncation in SCSS. Leading/trailing icons go in as children. `variant` covers neutral, accent, the five status colours and `solid`; `ChipDot` adds the leading dot in `currentColor`. Radius is a fixed 6px from the tags frame, so there is no shape prop. Selection lives in ToggleChip. The legacy `.chip` (old SCSS vars + manual dark-mode block, ~35×) migrates onto this under #6606.',
       },
     },
     layout: 'centered',
@@ -28,6 +31,61 @@ export const Accent: Story = {
   args: { children: '"hello"', variant: 'accent' },
 }
 
+export const Solid: Story = {
+  args: { children: 'Enterprise', variant: 'solid' },
+}
+
+// How Tag composes Chip: a decorative colour a user picked is not a semantic
+// variant, so it arrives as a tag-* swatch class in className. System
+// tags take none of it, and carry their state in the icon instead.
+const SYSTEM_TAGS: { label: string; icon: IconName }[] = [
+  { icon: 'issue-closed', label: 'Issue closed' },
+  { icon: 'issue-linked', label: 'Issue open' },
+  { icon: 'pr-closed', label: 'PR closed' },
+  { icon: 'pr-dequeued', label: 'PR dequeued' },
+  { icon: 'pr-draft', label: 'PR draft' },
+  { icon: 'stale', label: 'Stale' },
+  { icon: 'pr-linked', label: 'PR open' },
+  { icon: 'pr-merged', label: 'PR merged' },
+]
+
+export const AsSystemTag: Story = {
+  name: 'As a system tag',
+  parameters: { chromatic: { disableSnapshot: false } },
+  render: () => (
+    <div className='d-flex flex-wrap gap-2'>
+      {SYSTEM_TAGS.map(({ icon, label }) => (
+        <Chip
+          className='bg-surface-default border-default text-default'
+          key={label}
+          size='xs'
+        >
+          {label}
+          <Icon name={icon} />
+        </Chip>
+      ))}
+    </div>
+  ),
+}
+
+export const AsCustomTag: Story = {
+  name: 'As a custom tag',
+  parameters: { chromatic: { disableSnapshot: false } },
+  render: () => (
+    <div className='d-flex flex-wrap gap-2'>
+      {Constants.tagColors.map((colour: string) => (
+        <Chip
+          className={`border-0 ${getTagSwatchUtilities(colour)}`}
+          key={colour}
+          size='xs'
+        >
+          Custom
+        </Chip>
+      ))}
+    </div>
+  ),
+}
+
 export const Sizes: Story = {
   render: () => (
     <div className='d-flex align-items-center gap-2'>
@@ -38,6 +96,49 @@ export const Sizes: Story = {
   ),
 }
 
+export const StatusVariants: Story = {
+  render: () => (
+    <div className='d-flex align-items-center gap-2'>
+      <Chip variant='info' size='sm'>
+        <ChipDot />
+        Draft
+      </Chip>
+      <Chip variant='success' size='sm'>
+        <ChipDot />
+        Running
+      </Chip>
+      <Chip variant='warning' size='sm'>
+        <ChipDot />
+        Paused
+      </Chip>
+      <Chip variant='danger' size='sm'>
+        <ChipDot />
+        Failed
+      </Chip>
+      <Chip variant='muted' size='sm'>
+        <ChipDot />
+        Completed
+      </Chip>
+    </div>
+  ),
+}
+
+export const Counts: Story = {
+  render: () => (
+    <div className='d-flex align-items-center gap-2'>
+      <Chip variant='accent' size='xs'>
+        5
+      </Chip>
+      <Chip variant='neutral' size='xs'>
+        0
+      </Chip>
+      <Chip variant='neutral' size='xs'>
+        128
+      </Chip>
+    </div>
+  ),
+}
+
 export const Removable: Story = {
   args: { children: 'feature-flag', onRemove: () => undefined },
 }