@opendata-ai/openchart-core 6.28.5 → 7.0.0

package/src/styles/dark.css

@@ -3,18 +3,35 @@
  * --------------------------------------------------------------------------- */
 
 .oc-dark {
-  --oc-bg: #1a1a2e;
-  --oc-text: #e0e0e0;
-  --oc-text-secondary: #b0b0b0;
-  --oc-text-muted: #808080;
-  --oc-gridline: #333355;
-  --oc-axis: #999999;
-  --oc-border: #444466;
+  /* Surfaces (zinc-based achromatic ramp) */
+  --oc-bg: #09090b;
+  --oc-card: #111113;
+  --oc-secondary: #27272a;
+
+  /* Text levels — see tokens.css for the cross-mode naming rationale */
+  --oc-text: #f7f8f8;
+  --oc-text-secondary: #d0d6e0;
+  --oc-text-muted: #a1a1aa;
+  --oc-text-subtle: #71717a;
+  --oc-text-faint: #52525b;
+
+  /* Lines */
+  --oc-gridline: rgba(255, 255, 255, 0.05);
+  --oc-axis: rgba(255, 255, 255, 0.1);
+  --oc-border: rgba(255, 255, 255, 0.1);
+
+  /* Brand and semantic — accent stays cyan (no darkening on dark bg) */
+  --oc-accent: #06b6d4;
+  --oc-accent-strong: #06b6d4;
+  --oc-positive: #34d399;
+  --oc-negative: #fb7185;
   --oc-focus: #60a5fa;
+
+  /* Interactive states */
   --oc-hover-bg: rgba(255, 255, 255, 0.05);
-  --oc-tooltip-bg: rgba(30, 30, 50, 0.85);
+  --oc-tooltip-bg: rgba(17, 17, 19, 0.92);
   --oc-tooltip-border: rgba(255, 255, 255, 0.08);
   --oc-tooltip-shadow: 0 2px 8px rgba(0, 0, 0, 0.3), 0 0 1px rgba(0, 0, 0, 0.4);
-  --oc-tooltip-text: #e0e0e0;
-  --oc-legend-text: #b0b0b0;
+  --oc-tooltip-text: #f7f8f8;
+  --oc-legend-text: #d0d6e0;
 }

package/src/styles/tokens.css

@@ -11,7 +11,8 @@
 .oc-sankey-root,
 .oc-tilemap-root,
 .oc-barlist-root {
-  --oc-font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  --oc-font-family:
+    "Inter Variable", Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
   --oc-font-mono: "JetBrains Mono", "Fira Code", "Cascadia Code", monospace;
 
   /* Animation easing presets via CSS linear() */
@@ -70,27 +71,69 @@
   --oc-animation-duration: 500ms;
   --oc-animation-stagger: 80ms;
   --oc-annotation-delay: 200ms;
-  --oc-title-size: 22px;
-  --oc-title-weight: 700;
-  --oc-title-tracking: -0.02em;
+
+  /* Typography scale (editorial design system) */
+  --oc-title-size: 26px;
+  --oc-title-weight: 590;
+  --oc-title-tracking: -0.022em;
   --oc-subtitle-size: 14px;
   --oc-subtitle-weight: 400;
-  --oc-source-size: 12px;
+  --oc-source-size: 11px;
   --oc-source-weight: 400;
   --oc-body-size: 13px;
+  --oc-eyebrow-size: 11px;
+  --oc-eyebrow-weight: 510;
+  --oc-eyebrow-tracking: 0.08em;
+
+  /* Surfaces (light mode defaults) */
   --oc-bg: #ffffff;
-  --oc-text: #1d1d1d;
-  --oc-text-secondary: #5c5c5c;
-  --oc-text-muted: #999999;
-  --oc-gridline: #e8e8e8;
-  --oc-axis: #888888;
-  --oc-border: #e2e2e2;
-  --oc-border-radius: 4px;
+  --oc-card: #ffffff;
+  --oc-secondary: #f4f4f5; /* zinc-100, raised surface */
+
+  /*
+   * Text levels. Names invert across modes: in light mode "muted" sits at
+   * a lighter zinc step than "subtle" because both are picked relative to
+   * the active background, not from a fixed lightness ladder. The intent
+   * is "muted = first step away from primary text"; "subtle = next step
+   * down"; etc.
+   *
+   *   Light mode: text=zinc-950, secondary=zinc-700, muted=zinc-500,
+   *               subtle=zinc-400, faint=zinc-300
+   *   Dark mode (dark.css): inverts the surface tokens but keeps the same
+   *               muted -> subtle -> faint progression away from primary.
+   */
+  --oc-text: #09090b;
+  --oc-text-secondary: #3f3f46;
+  --oc-text-muted: #71717a;
+  --oc-text-subtle: #a1a1aa;
+  --oc-text-faint: #d4d4d8;
+
+  /* Lines */
+  --oc-gridline: rgba(0, 0, 0, 0.06);
+  --oc-axis: rgba(0, 0, 0, 0.1);
+  --oc-border: rgba(0, 0, 0, 0.08);
+  --oc-border-radius: 2px;
+
+  /* Brand and semantic */
+  --oc-accent: #06b6d4;
+  --oc-accent-strong: #0891b2; /* darker cyan for line strokes on light bg */
+  --oc-positive: #10b981;
+  --oc-negative: #e11d48;
   --oc-focus: #3b82f6;
+
+  /* Spacing scale (4px base) */
+  --oc-space-1: 4px;
+  --oc-space-2: 8px;
+  --oc-space-3: 12px;
+  --oc-space-4: 16px;
+  --oc-space-6: 24px;
+  --oc-space-8: 32px;
+
+  /* Interactive states */
   --oc-hover-bg: rgba(0, 0, 0, 0.025);
   --oc-tooltip-bg: rgba(255, 255, 255, 0.88);
   --oc-tooltip-border: rgba(0, 0, 0, 0.08);
   --oc-tooltip-shadow: 0 2px 8px rgba(0, 0, 0, 0.08), 0 0 1px rgba(0, 0, 0, 0.12);
-  --oc-tooltip-text: #1d1d1d;
-  --oc-legend-text: #555555;
+  --oc-tooltip-text: #09090b;
+  --oc-legend-text: #3f3f46;
 }

package/src/styles/tooltip.css

@@ -1,5 +1,8 @@
 /* ---------------------------------------------------------------------------
  * Tooltip
+ * Editorial card matching the new design system: zinc surface, cyan accent,
+ * Inter Variable, mono numerics. Sized for a slice tooltip that lists every
+ * series at the snapped x.
  * --------------------------------------------------------------------------- */
 
 .oc-tooltip {
@@ -8,23 +11,26 @@
   pointer-events: none;
   z-index: 1000;
   background: var(--oc-tooltip-bg);
-  backdrop-filter: blur(12px);
+  backdrop-filter: blur(14px);
   border: 1px solid var(--oc-tooltip-border);
-  border-radius: 8px;
+  border-radius: var(--oc-border-radius, 4px);
   box-shadow: var(--oc-tooltip-shadow);
   color: var(--oc-tooltip-text);
   font-family: var(--oc-font-family);
   font-size: 12px;
   padding: 0;
-  max-width: 260px;
-  min-width: 140px;
+  max-width: 280px;
+  min-width: 160px;
   line-height: 1.4;
   animation: oc-tooltip-in 120ms ease-out;
+  transition:
+    left 100ms ease-in-out,
+    top 100ms ease-in-out;
 
   & .oc-tooltip-header {
     display: flex;
     align-items: center;
-    gap: 6px;
+    gap: 8px;
     padding: 8px 12px 6px;
   }
 
@@ -36,53 +42,91 @@
   }
 
   & .oc-tooltip-title {
-    font-weight: 600;
-    font-size: 12px;
-    letter-spacing: -0.01em;
-    color: var(--oc-tooltip-text);
+    font-weight: 590;
+    font-size: 11px;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: var(--oc-text-muted);
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
   }
 
   & .oc-tooltip-body {
-    padding: 4px 12px 8px;
+    padding: 6px 12px 10px;
     border-top: 1px solid var(--oc-tooltip-border);
   }
 
-  /* Only add separator when header is present */
-  & .oc-tooltip-header + .oc-tooltip-body {
-    padding-top: 6px;
-  }
-
   /* No separator when body is the only child */
   & .oc-tooltip-body:first-child {
     border-top: none;
-    padding-top: 8px;
+    padding-top: 10px;
   }
 
   & .oc-tooltip-row {
     display: flex;
     align-items: baseline;
     justify-content: space-between;
-    gap: 12px;
-    padding: 1px 0;
+    gap: 16px;
+    padding: 2px 0;
+  }
+
+  & .oc-tooltip-row-swatch {
+    display: inline-block;
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    margin-right: 6px;
+    flex-shrink: 0;
+    transform: translateY(-1px);
   }
 
   & .oc-tooltip-label {
-    color: var(--oc-text-muted);
-    font-size: 11px;
+    color: var(--oc-text-secondary);
+    font-size: 12px;
+    font-weight: 400;
     white-space: nowrap;
     flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
   }
 
   & .oc-tooltip-value {
-    font-weight: 500;
-    font-size: 11px;
+    font-weight: 510;
+    font-size: 12px;
     font-variant-numeric: tabular-nums;
+    color: var(--oc-tooltip-text);
     text-align: right;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
   }
 }
+
+/* ---------------------------------------------------------------------------
+ * Crosshair guideline + per-series snap dots (line/area charts)
+ * Animate the snap between adjacent points so the indicator slides instead
+ * of jumping. ~50ms ease-in-out keeps the motion crisp without lagging.
+ * --------------------------------------------------------------------------- */
+
+.oc-crosshair {
+  pointer-events: none;
+  transition:
+    x1 50ms ease-in-out,
+    x2 50ms ease-in-out;
+}
+
+.oc-snap-dots circle {
+  pointer-events: none;
+  transition:
+    cx 50ms ease-in-out,
+    cy 50ms ease-in-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .oc-tooltip,
+  .oc-crosshair,
+  .oc-snap-dots circle {
+    transition: none;
+  }
+}

package/src/theme/__tests__/dark-mode.test.ts

@@ -1,14 +1,15 @@
+import { hsl } from 'd3-color';
 import { describe, expect, it } from 'vitest';
 import { contrastRatio } from '../../colors/contrast';
-import { adaptColorForDarkMode, adaptTheme } from '../dark-mode';
+import { adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme } from '../dark-mode';
 import { resolveTheme } from '../resolve';
 
 describe('adaptColorForDarkMode', () => {
   const lightBg = '#ffffff';
-  const darkBg = '#1a1a2e';
+  const darkBg = '#09090b';
 
   it('adapted color has similar contrast on dark bg as original on light bg', () => {
-    const original = '#1b7fa3'; // teal from palette
+    const original = '#06b6d4'; // cyan, primary accent
     const adapted = adaptColorForDarkMode(original, lightBg, darkBg);
 
     const originalRatio = contrastRatio(original, lightBg);
@@ -19,6 +20,11 @@ describe('adaptColorForDarkMode', () => {
     expect(Math.abs(adaptedRatio - originalRatio)).toBeLessThan(tolerance);
   });
 
+  it('returns unchanged input for unparseable colors (e.g. raw oklch)', () => {
+    const result = adaptColorForDarkMode('oklch(70% 0.15 200)', lightBg, darkBg);
+    expect(result).toBe('oklch(70% 0.15 200)');
+  });
+
   it('returns a valid hex color', () => {
     const result = adaptColorForDarkMode('#e15759', lightBg, darkBg);
     expect(result).toMatch(/^#[0-9a-f]{6}$/i);
@@ -30,6 +36,44 @@ describe('adaptColorForDarkMode', () => {
   });
 });
 
+describe('adaptForLightLineStroke', () => {
+  it('darkens a saturated cyan by ~12% lightness', () => {
+    const original = '#06b6d4';
+    const darkened = adaptForLightLineStroke(original);
+    expect(darkened).not.toBe(original);
+    const c = hsl(darkened);
+    const o = hsl(original);
+    expect(c).not.toBeNull();
+    expect(c!.l).toBeCloseTo(o.l - 0.12, 2);
+  });
+
+  it('passes saturated red and blue through with reduced lightness', () => {
+    for (const color of ['#ef4444', '#3b82f6']) {
+      const out = adaptForLightLineStroke(color);
+      const before = hsl(color);
+      const after = hsl(out);
+      expect(after!.l).toBeLessThan(before.l);
+    }
+  });
+
+  it('passes pure gray through unchanged (saturation below threshold)', () => {
+    // zinc-400 has near-zero saturation; reducing lightness on a gray would
+    // shift it toward black, which isn't desired for achromatic palettes.
+    expect(adaptForLightLineStroke('#a1a1aa')).toBe('#a1a1aa');
+  });
+
+  it('passes already-dark colors through unchanged (l <= 0.4)', () => {
+    // Indigo-900 sits at l ≈ 0.30 — already meets contrast on white.
+    const dark = '#312e81';
+    expect(adaptForLightLineStroke(dark)).toBe(dark);
+  });
+
+  it('passes invalid input through unchanged', () => {
+    expect(adaptForLightLineStroke('not-a-color')).toBe('not-a-color');
+    expect(adaptForLightLineStroke('')).toBe('');
+  });
+});
+
 describe('adaptTheme', () => {
   it('sets isDark to true', () => {
     const light = resolveTheme();
@@ -40,7 +84,7 @@ describe('adaptTheme', () => {
   it('swaps to dark background', () => {
     const light = resolveTheme();
     const dark = adaptTheme(light);
-    expect(dark.colors.background).toBe('#1a1a2e');
+    expect(dark.colors.background).toBe('#09090b');
   });
 
   it('updates text color for dark mode', () => {
@@ -52,12 +96,13 @@ describe('adaptTheme', () => {
     expect(ratio).toBeGreaterThan(4);
   });
 
-  it('adapts categorical palette colors', () => {
+  it('preserves categorical palette across modes', () => {
     const light = resolveTheme();
     const dark = adaptTheme(light);
-    // Colors should be different (adjusted for dark bg)
-    expect(dark.colors.categorical).not.toEqual(light.colors.categorical);
-    expect(dark.colors.categorical).toHaveLength(light.colors.categorical.length);
+    // Design-system tokens are mode-agnostic: the same vibrant cyan-led
+    // palette renders in both modes. Contrast-equivalence adaptation
+    // dulls cyan into teal, which is not what the spec calls for.
+    expect(dark.colors.categorical).toEqual(light.colors.categorical);
   });
 
   it('updates chrome text colors', () => {

package/src/theme/__tests__/defaults.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { contrastRatio } from '../../colors/contrast';
+import { ACHROMATIC_RAMP } from '../../colors/palettes';
+import { adaptColorForDarkMode } from '../dark-mode';
 import { DEFAULT_THEME } from '../defaults';
 
 describe('DEFAULT_THEME', () => {
@@ -11,33 +13,57 @@ describe('DEFAULT_THEME', () => {
     expect(DEFAULT_THEME.chrome).toBeDefined();
   });
 
-  it('uses Inter as primary font', () => {
-    expect(DEFAULT_THEME.fonts.family).toContain('Inter');
+  it('uses Inter Variable as primary font', () => {
+    expect(DEFAULT_THEME.fonts.family).toContain('Inter Variable');
   });
 
-  it('title is 22px bold', () => {
-    expect(DEFAULT_THEME.chrome.title.fontSize).toBe(22);
-    expect(DEFAULT_THEME.chrome.title.fontWeight).toBe(700);
+  it('title is 26px demi (590 weight)', () => {
+    expect(DEFAULT_THEME.chrome.title.fontSize).toBe(26);
+    expect(DEFAULT_THEME.chrome.title.fontWeight).toBe(590);
   });
 
-  it('subtitle is 15px normal weight', () => {
-    expect(DEFAULT_THEME.chrome.subtitle.fontSize).toBe(15);
+  it('subtitle is 14px normal weight', () => {
+    expect(DEFAULT_THEME.chrome.subtitle.fontSize).toBe(14);
     expect(DEFAULT_THEME.chrome.subtitle.fontWeight).toBe(400);
   });
 
-  it('source is 12px normal weight', () => {
-    expect(DEFAULT_THEME.chrome.source.fontSize).toBe(12);
+  it('source is 11px normal weight', () => {
+    expect(DEFAULT_THEME.chrome.source.fontSize).toBe(11);
     expect(DEFAULT_THEME.chrome.source.fontWeight).toBe(400);
   });
 
-  it('categorical palette has sufficient contrast on white background', () => {
-    const bg = DEFAULT_THEME.colors.background;
-    for (const color of DEFAULT_THEME.colors.categorical) {
-      const ratio = contrastRatio(color, bg);
-      // AA for large text is 3:1. Some editorial palette colors may not
-      // hit 4.5:1 on pure white, but they should all clear 3:1.
-      expect(ratio).toBeGreaterThanOrEqual(3);
-    }
+  it('borderRadius is 2px (square aesthetic)', () => {
+    expect(DEFAULT_THEME.borderRadius).toBe(2);
+  });
+
+  it('font weights include 510 (medium) and 590 (demi)', () => {
+    expect(DEFAULT_THEME.fonts.weights.medium).toBe(510);
+    expect(DEFAULT_THEME.fonts.weights.semibold).toBe(590);
+  });
+
+  it('categorical palette is non-empty and primary accent is cyan', () => {
+    // Palette is a designed OKLCH multi-hue ramp tuned for dark surfaces
+    // (L~=0.70). It does not guarantee WCAG-AA-large-text contrast on
+    // pure white; light-mode line strokes route through the strong
+    // accent token (`adaptForLightLineStroke`) instead. Per-token
+    // accessibility is enforced via dedicated contrast helpers, not
+    // here.
+    expect(DEFAULT_THEME.colors.categorical.length).toBeGreaterThanOrEqual(5);
+    expect(DEFAULT_THEME.colors.categorical[0]).toBe('#06b6d4');
+  });
+
+  it('dark canvas surface tokens are part of the achromatic ramp', () => {
+    expect(ACHROMATIC_RAMP.bg).toBe('#09090b');
+    expect(ACHROMATIC_RAMP.fg).toBe('#f7f8f8');
+  });
+
+  it('dark-mode adapter preserves contrast monotonicity for cyan accent', () => {
+    // The cyan accent on white has a low ratio (~2.4); the adapter's
+    // job is to produce a similar ratio against the dark canvas, not
+    // to raise it. Just confirm the adapter returns something.
+    const adapted = adaptColorForDarkMode('#06b6d4', '#ffffff', ACHROMATIC_RAMP.bg);
+    expect(adapted).toMatch(/^#[0-9a-f]{6}$/i);
+    expect(contrastRatio(adapted, ACHROMATIC_RAMP.bg)).toBeGreaterThan(1.5);
   });
 
   it('has sequential and diverging palette entries', () => {

package/src/theme/dark-mode.ts

@@ -7,16 +7,17 @@
 
 import { hsl, rgb } from 'd3-color';
 import { contrastRatio } from '../colors/contrast';
+import { ACHROMATIC_RAMP } from '../colors/palettes';
 import type { ResolvedTheme } from '../types/theme';
 
 // ---------------------------------------------------------------------------
 // Dark mode background
 // ---------------------------------------------------------------------------
 
-/** Default dark mode background color. */
-const DARK_BG = '#1a1a2e';
+/** Default dark mode background color (zinc-based canvas). */
+const DARK_BG = ACHROMATIC_RAMP.bg;
 /** Default dark mode text color. */
-const DARK_TEXT = '#e0e0e0';
+const DARK_TEXT = ACHROMATIC_RAMP.fg;
 
 // ---------------------------------------------------------------------------
 // Color adaptation
@@ -30,6 +31,17 @@ const DARK_TEXT = '#e0e0e0';
  * had against lightBg.
  */
 export function adaptColorForDarkMode(color: string, lightBg: string, darkBg: string): string {
+  // Adapter only handles hex/rgb-style inputs. Raw oklch() and other
+  // CSS Color 4 strings parse unreliably through d3-color in happy-dom,
+  // so guard early instead of silently falling back to a default.
+  if (rgb(color) == null) {
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn(
+        `[openchart] adaptColorForDarkMode: unparseable color "${color}", returning unchanged. Use precomputed sRGB hex.`,
+      );
+    }
+    return color;
+  }
   const originalRatio = contrastRatio(color, lightBg);
   const c = hsl(color);
   if (c == null || Number.isNaN(c.h)) {
@@ -101,13 +113,17 @@ export function adaptTheme(theme: ResolvedTheme): ResolvedTheme {
   // instead of overwriting with library defaults.
   const darkBg = alreadyDark ? inputBg : DARK_BG;
   const darkText = alreadyDark ? theme.colors.text : DARK_TEXT;
-  const darkGridline = alreadyDark ? theme.colors.gridline : '#333344';
-  const darkAxis = alreadyDark ? theme.colors.axis : '#888899';
-
-  // Only adapt categorical colors when switching from light to dark
-  const categorical = alreadyDark
-    ? theme.colors.categorical
-    : theme.colors.categorical.map((c) => adaptColorForDarkMode(c, inputBg, darkBg));
+  const darkGridline = alreadyDark ? theme.colors.gridline : 'rgba(255,255,255,0.05)';
+  // axis is also tick-label fill — needs WCAG AA contrast on dark bg.
+  // Zinc-400 (`#a1a1aa`) hits ~6:1 against #09090b.
+  const darkAxis = alreadyDark ? theme.colors.axis : '#a1a1aa';
+  const darkMuted = ACHROMATIC_RAMP.fgMuted;
+
+  // Categorical palette is pinned to design-system tokens. The same vibrant
+  // hex values render in both light and dark modes — adapting them via
+  // contrast-equivalence dulls them on dark backgrounds (cyan -> teal),
+  // which is the opposite of what the design system calls for.
+  const categorical = theme.colors.categorical;
 
   return {
     ...theme,
@@ -118,16 +134,60 @@ export function adaptTheme(theme: ResolvedTheme): ResolvedTheme {
       text: darkText,
       gridline: darkGridline,
       axis: darkAxis,
-      annotationFill: 'rgba(255,255,255,0.08)',
-      annotationText: '#bbbbcc',
+      annotationFill: 'rgba(255,255,255,0.06)',
+      annotationText: darkMuted,
       categorical,
+      // Sparkline trend colors tuned for dark surfaces: teal-leaning green
+      // and coral red read better than the saturated light-mode tokens.
+      // Any non-default value is treated as a user override and preserved.
+      positive: theme.colors.positive !== '#16a34a' ? theme.colors.positive : '#34d399',
+      negative: theme.colors.negative !== '#dc2626' ? theme.colors.negative : '#f87171',
     },
     chrome: {
+      // Eyebrow keeps its accent tint (cyan in both modes); the other
+      // chrome elements desaturate to a muted gray on the dark canvas.
+      eyebrow: theme.chrome.eyebrow,
       title: { ...theme.chrome.title, color: darkText },
-      subtitle: { ...theme.chrome.subtitle, color: '#aaaaaa' },
-      source: { ...theme.chrome.source, color: '#888888' },
-      byline: { ...theme.chrome.byline, color: '#888888' },
-      footer: { ...theme.chrome.footer, color: '#888888' },
+      subtitle: { ...theme.chrome.subtitle, color: darkMuted },
+      source: { ...theme.chrome.source, color: darkMuted },
+      byline: { ...theme.chrome.byline, color: darkMuted },
+      footer: { ...theme.chrome.footer, color: darkMuted },
     },
   };
 }
+
+// ---------------------------------------------------------------------------
+// Light mode line stroke darkening
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a darker variant of a color for use as a foreground stroke on
+ * light backgrounds, where mid-lightness palette colors (e.g. cyan-500
+ * `#06b6d4`) lack contrast against white. Drops HSL lightness by ~12%
+ * absolute (clamped to >= 0) while preserving hue and saturation, which
+ * reproduces the cyan-500 → cyan-600 step the cyan accent originally
+ * needed and works for any other palette accent the user picks.
+ *
+ * Returns the input unchanged when:
+ *   - the color is already dark enough (L <= ~0.40) — further darkening
+ *     just muddies the stroke without adding contrast
+ *   - the color isn't parseable
+ *   - the color is achromatic (NaN hue) — HSL lightness on grays drifts
+ *     toward black instead of staying neutral
+ *
+ * Exposed via the `--oc-accent-strong` CSS token.
+ */
+export function adaptForLightLineStroke(color: string): string {
+  if (rgb(color) == null) return color;
+  const c = hsl(color);
+  if (c == null) return color;
+  // Achromatic check: NaN hue OR low saturation. d3-color reports a valid
+  // hue for grays whose RGB channels aren't perfectly equal (e.g. zinc
+  // `#a1a1aa` has s≈0.05), so saturation is the more reliable signal.
+  // Threshold 0.10 catches near-grays without tripping on real palette
+  // colors (palette saturation is ≥ ~0.5).
+  if (Number.isNaN(c.h) || c.s < 0.1) return color;
+  if (c.l <= 0.4) return color;
+  c.l = Math.max(0, c.l - 0.12);
+  return c.formatHex();
+}