fix(tags): make tags and their picker accessible

.gitattributes

@@ -0,0 +1,7 @@
+# Generated from frontend/common/theme/tokens.json by `npm run generate:tokens`,
+# which lint-staged reruns whenever that file changes. Collapsed in diffs and
+# excluded from language stats: read the source, not the output.
+frontend/common/theme/tokens.ts linguist-generated=true
+frontend/web/styles/_tokens.scss linguist-generated=true
+frontend/web/styles/_token-utilities.scss linguist-generated=true
+frontend/documentation/TokenReference.generated.stories.tsx linguist-generated=true

frontend/common/theme/__tests__/tagSwatches.test.ts

@@ -0,0 +1,36 @@
+import tokens from 'common/theme/tokens.json'
+import { AA_NORMAL_TEXT, contrastRatio } from 'common/theme/contrast'
+
+const primitives = tokens.primitives as Record<string, string>
+
+const INK = primitives['content-always-dark']
+
+const swatches = Object.entries(primitives).filter(
+  ([name, hex]) => name.startsWith('content-') && hex !== INK,
+)
+
+const ratio = (hex: string) => contrastRatio(INK, hex)
+
+describe('tag swatches', () => {
+  // Or everything below runs against nothing and still passes.
+  it('finds swatches', () => {
+    expect(swatches.length).toBeGreaterThan(0)
+  })
+
+  // One fill on both themes, so the palette settles the label's contrast. The
+  // fill is 1.18:1 against white, under the 3:1 for non-text, by design: a tag
+  // is read from its label, not its edge.
+  it('clears AA for the label on every fill', () => {
+    const failing = swatches
+      .filter(([, hex]) => ratio(hex) < AA_NORMAL_TEXT)
+      .map(([name, hex]) => `${name} ${ratio(hex).toFixed(2)}:1`)
+    expect(failing).toEqual([])
+  })
+
+  // #8465 found 20 options resolving to 7 colours. Two tags that look alike is
+  // the same defect as failing contrast.
+  it('gives every hue a distinct colour', () => {
+    const seen = new Set(swatches.map(([, hex]) => hex.toLowerCase()))
+    expect(seen.size).toBe(swatches.length)
+  })
+})

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)
+}

frontend/common/theme/tokens.json

@@ -79,7 +79,19 @@
     "orange-800": "#9f5208",
     "orange-900": "#7b4008",
     "orange-950": "#592f07",
-    "slate-1000": "#000000"
+    "slate-1000": "#000000",
+    "content-always-dark": "#080c17",
+    "content-blue": "#c7e6ff",
+    "content-light-blue": "#c9f1fe",
+    "content-light-brown": "#dfc8c6",
+    "content-light-green": "#d6f1d4",
+    "content-light-grey": "#eff0f3",
+    "content-light-mint": "#c7e7e2",
+    "content-light-peach": "#fcd6c7",
+    "content-light-pink": "#ffceda",
+    "content-light-purple": "#dacdde",
+    "content-light-red": "#ffe0df",
+    "content-light-yellow": "#f3edca"
   },
   "color": {
     "surface": {

frontend/common/types/responses.ts

@@ -579,7 +579,8 @@ export type APIKey = {
   name: string
 }
 
-export type TagType = 'STALE' | 'UNHEALTHY' | 'NONE'
+// Mirrors TagType in api/projects/tags/models.py.
+export type TagType = 'NONE' | 'STALE' | 'GITHUB' | 'UNHEALTHY' | 'GITLAB'
 
 export type Tag = {
   id: number

frontend/common/useContainClicks.ts

@@ -0,0 +1,29 @@
+import { RefObject, useEffect } from 'react'
+
+/**
+ * Keeps clicks inside `ref` from reaching the outside-click watchers, so a
+ * subtree portalled elsewhere still counts as part of whatever opened it.
+ *
+ * Without this, an InlineModal holding a portalled menu closes on the very item
+ * you picked, because the menu is not a DOM descendant of the modal. Native
+ * listeners rather than React's onMouseUp, because those sit below document,
+ * which is where useOutsideClick listens.
+ */
+const useContainClicks = (
+  ref: RefObject<HTMLElement | null>,
+  active = true,
+) => {
+  useEffect(() => {
+    const node = ref.current
+    if (!active || !node) return
+    const stop = (e: Event) => e.stopPropagation()
+    node.addEventListener('mouseup', stop)
+    node.addEventListener('touchend', stop)
+    return () => {
+      node.removeEventListener('mouseup', stop)
+      node.removeEventListener('touchend', stop)
+    }
+  }, [ref, active])
+}
+
+export default useContainClicks

frontend/documentation/CategoricalPalette.stories.tsx

@@ -2,40 +2,19 @@ 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
 // full app dependency tree and breaks Storybook's ESM context).
-// Source of truth: common/constants.ts
+// Source of truth: common/constants.ts. The tag scale is not copied here; it
+// comes from tokens.json below, so it cannot drift.
 // ---------------------------------------------------------------------------
 
-const TAG_COLOURS = [
-  { hex: '#3d4db6', name: 'Indigo' },
-  { hex: '#ea5a45', name: 'Coral' },
-  { hex: '#c6b215', name: 'Gold' },
-  { hex: '#60bd4e', name: 'Green' },
-  { hex: '#fe5505', name: 'Orange' },
-  { hex: '#1492f4', name: 'Blue' },
-  { hex: '#14c0f4', name: 'Cyan' },
-  { hex: '#c277e0', name: 'Lavender' },
-  { hex: '#039587', name: 'Teal' },
-  { hex: '#344562', name: 'Navy' },
-  { hex: '#ffa500', name: 'Amber' },
-  { hex: '#3cb371', name: 'Mint' },
-  { hex: '#d3d3d3', name: 'Silver' },
-  { hex: '#5D6D7E', name: 'Slate' },
-  { hex: '#641E16', name: 'Maroon' },
-  { hex: '#5B2C6F', name: 'Plum' },
-  { hex: '#D35400', name: 'Burnt Orange' },
-  { hex: '#F08080', name: 'Salmon' },
-  { hex: '#AAC200', name: 'Lime' },
-  { hex: '#DE3163', name: 'Cerise' },
-]
-
-const DEFAULT_TAG_COLOUR = '#dedede'
-
 const PROJECT_COLOURS = [
   '#906AF6',
   '#FAE392',
@@ -60,30 +39,62 @@ export default meta
 // Stories
 // ---------------------------------------------------------------------------
 
-export const TagColours: StoryObj = {
-  name: 'Tag colours',
+const PRIMITIVES = tokens.primitives as Record<string, string>
+
+// The Content palette, fixed rather than theme-aware: a tag chip carries its
+// own surface, so it does not follow the page. One ink serves all of them.
+const TAG_INK_NAME = 'content-always-dark'
+const TAG_INK = PRIMITIVES[TAG_INK_NAME]
+const TAG_FILLS = Object.entries(PRIMITIVES)
+  .filter(([name]) => name.startsWith('content-') && name !== TAG_INK_NAME)
+  .map(([name, hex]) => [name.replace('content-', ''), hex] as const)
+
+export const TagSwatches: StoryObj = {
+  name: 'Tag swatches',
+  parameters: { chromatic: { disableSnapshot: false } },
   render: () => (
     <DocPage
-      title='Tag colours'
+      title='Tag swatches'
       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
-          NOT semantic tokens &mdash; they are categorical identifiers that need
-          to be visually distinct from each other.
+          The scale a custom tag picks from, replacing the runtime colour maths
+          that made contrast a function of the user&rsquo;s chosen hue. These
+          are the design system&rsquo;s Content colours, fixed in both themes
+          because a chip carries its own surface. Every one clears AA (
+          {AA_NORMAL_TEXT}:1) against the shared ink, enforced by{' '}
+          <code>tagSwatches.test.ts</code>.
         </>
       }
     >
-      <div className='cat-grid'>
-        {TAG_COLOURS.map(({ hex, name }) => (
-          <Swatch key={hex} colour={hex} label={`${name}\n${hex}`} />
+      <div className='d-flex flex-wrap gap-3'>
+        {TAG_FILLS.map(([name, hex]) => (
+          <div
+            className='d-flex flex-column align-items-center gap-1'
+            key={name}
+          >
+            <Chip className={`border-0 tag-${name}`} size='xs'>
+              {name}
+            </Chip>
+            <small className='text-secondary'>
+              {contrastRatio(hex, TAG_INK).toFixed(2)}:1
+            </small>
+          </div>
         ))}
       </div>
       <p className='cat-note'>
-        Default tag colour: <code>{DEFAULT_TAG_COLOUR}</code>
+        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>
   ),
 }

frontend/documentation/components/Chip.stories.tsx

@@ -2,6 +2,9 @@ import React from 'react'
 import type { Meta, StoryObj } from 'storybook'
 
 import Chip from 'components/base/Chip'
+import Icon, { IconName } from 'components/icons/Icon'
+import { contentColours } from 'common/theme/tokens'
+import { getTagSwatchUtilities } from 'components/tags/utils'
 
 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. `none` leaves the colour to the caller, for a decorative colour a user picked rather than a semantic role. `selected` rings the chip. The legacy `.chip` (old SCSS vars + manual dark-mode block, ~35×) migrates onto this under #6606.',
       },
     },
     layout: 'centered',
@@ -28,6 +31,79 @@ export const Accent: Story = {
   args: { children: '"hello"', variant: 'accent' },
 }
 
+// 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'>
+      {Object.values(contentColours).map((colour) => (
+        <Chip
+          className={`border-0 ${getTagSwatchUtilities(colour)}`}
+          key={colour}
+          size='xs'
+        >
+          Custom
+        </Chip>
+      ))}
+    </div>
+  ),
+}
+
+/**
+ * `selected` rings the chip. For a cloud of filter chips the chip is the whole
+ * control, and anything drawn inside it competes with the colour the user
+ * picked. See TagFilter.
+ */
+export const SelectedAsARing: Story = {
+  name: 'Selected',
+  render: () => (
+    <div className='d-flex flex-wrap gap-2 align-items-center'>
+      <Chip className='tag-light-green' selected>
+        onboarding
+      </Chip>
+      <Chip className='tag-light-mint' selected={false}>
+        analytics
+      </Chip>
+      <Chip className='tag-blue' selected={false}>
+        billing
+      </Chip>
+    </div>
+  ),
+}
+
 export const Sizes: Story = {
   render: () => (
     <div className='d-flex align-items-center gap-2'>