@ds-mo/ui 0.3.0 → 0.4.0

package/src/components/ToggleButtonGroup/ToggleButtonGroup.tsx

@@ -1,111 +0,0 @@
-import React from 'react';
-import { cn } from '@/utils/cn';
-import styles from './ToggleButtonGroup.module.css';
-
-export interface ToggleButtonGroupProps {
-  children: React.ReactNode;
-  className?: string;
-}
-
-/**
- * Renders ToggleButton children flush side-by-side with a 1px divider between them.
- * Outer corners keep the button's own border-radius; inner corners are flattened.
- *
- * Individual button chrome (shadow/border) is suppressed — the group container
- * carries the elevation so it wraps the whole control as one visual unit.
- *
- * Divider behaviour by elevation:
- *   elevated / flat / floating — full-height color-border-tertiary line
- *   none (ghost)               — short centred line (icon/text height)
- *
- * Rounded groups: outer edges keep pill padding; inner edges revert to base padding.
- * Pressed state and onPressedChange are managed by the consumer on each ToggleButton.
- */
-export const ToggleButtonGroup = ({ children, className }: ToggleButtonGroupProps) => {
-  const items = React.Children.toArray(children).filter(React.isValidElement);
-  const count = items.length;
-
-  // Read elevation + rounded from first child to drive the group container style.
-  const firstEl   = items[0] as React.ReactElement<Record<string, unknown>> | undefined;
-  const firstProps = firstEl?.props as { elevation?: string; rounded?: boolean } | undefined;
-  const groupElevation = firstProps?.elevation ?? 'elevated';
-  const groupRounded   = !!firstProps?.rounded;
-  const groupElevKey   = groupElevation.charAt(0).toUpperCase() + groupElevation.slice(1);
-
-  return (
-    <div
-      className={cn(
-        styles.group,
-        (styles as Record<string, string>)[`group${groupElevKey}`],
-        groupRounded && styles.groupRounded,
-        className,
-      )}
-      role="group"
-    >
-      {items.map((child, i) => {
-        const el = child as React.ReactElement<Record<string, unknown>>;
-        const p = el.props as {
-          className?: string;
-          elevation?: string;
-          size?: string;
-          rounded?: boolean;
-          pressed?: boolean;
-          icon?: unknown;
-          label?: unknown;
-        };
-
-        const isFirst = i === 0;
-        const isLast  = i === count - 1;
-        const isMid   = !isFirst && !isLast;
-
-        const size       = (p.size ?? 'md') as 'xs' | 'sm' | 'md';
-        const isRounded  = !!p.rounded;
-        const isPressed  = !!p.pressed;
-        const isIconOnly = !!p.icon && !p.label;
-        // Ghost: elevation='none' (no chrome) → short centred divider
-        const isGhost    = (p.elevation ?? 'elevated') === 'none';
-
-        // XS rounded has no extra padding in ToggleButton so needs no correction
-        const sizeKey = size.toUpperCase() as 'XS' | 'SM' | 'MD';
-        const needsRoundedCorrection = isRounded && !isIconOnly && size !== 'xs';
-
-        // Divider injected as a separate element so it's never affected by
-        // the adjacent button's opacity (e.g. disabled state).
-        const dividerClasses = cn(
-          styles.divider,
-          isGhost && styles.dividerGhost,
-          isGhost && size === 'xs' && styles.dividerGhostXS,
-          isGhost && size === 'sm' && styles.dividerGhostSM,
-        );
-
-        return (
-          <React.Fragment key={i}>
-            {i > 0 && <div className={dividerClasses} aria-hidden="true" />}
-            {React.cloneElement(el, {
-              className: cn(
-                p.className,
-                styles.item,
-                isFirst && styles.first,
-                isLast  && styles.last,
-                isMid   && styles.middle,
-
-                // Ghost variant: ::after overlay gets 4px radius treatment
-                isGhost && styles.itemShort,
-
-                // Ghost + pressed: selected state background chip
-                isGhost && isPressed && styles.itemPressed,
-
-                // Rounded: revert inner-edge padding to base (non-pill) value
-                needsRoundedCorrection && isFirst && (styles as Record<string, string>)[`roundedFirst${sizeKey}`],
-                needsRoundedCorrection && isLast  && (styles as Record<string, string>)[`roundedLast${sizeKey}`],
-                needsRoundedCorrection && isMid   && (styles as Record<string, string>)[`roundedMid${sizeKey}`],
-              ),
-            })}
-          </React.Fragment>
-        );
-      })}
-    </div>
-  );
-};
-
-ToggleButtonGroup.displayName = 'ToggleButtonGroup';

package/src/components/ToggleButtonGroup/index.ts

@@ -1,2 +0,0 @@
-export { ToggleButtonGroup } from './ToggleButtonGroup';
-export type { ToggleButtonGroupProps } from './ToggleButtonGroup';

package/src/components/Tooltip/Tooltip.module.css

@@ -1,45 +0,0 @@
-.tooltip {
-  box-sizing: border-box;
-  background-color: var(--color-background-primary);
-  border-radius: var(--dimension-radius-075);
-  box-shadow: var(--effect-elevation-elevated-floating);
-  padding: var(--dimension-space-050);
-  line-height: var(--typography-lineheight-sm);
-  pointer-events: none;
-  backface-visibility: hidden;
-  -webkit-font-smoothing: subpixel-antialiased;
-  animation: tooltipFadeIn var(--effect-motion-short-2) forwards;
-}
-
-.tooltipInner {
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  gap: var(--dimension-space-050);
-}
-
-.keyHint {
-  width: var(--dimension-size-200);
-  height: var(--dimension-size-200);
-  flex-shrink: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  border: var(--dimension-stroke-width-015) solid var(--color-foreground-tertiary);
-  border-bottom-width: var(--dimension-stroke-width-025);
-  border-radius: var(--dimension-radius-025);
-}
-
-.tooltip.closing {
-  animation: tooltipFadeOut var(--effect-motion-short-3) forwards;
-}
-
-@keyframes tooltipFadeIn {
-  from { opacity: 0; }
-  to { opacity: 1; }
-}
-
-@keyframes tooltipFadeOut {
-  from { opacity: 1; }
-  to { opacity: 0; }
-}

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -1,46 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Tooltip } from './Tooltip';
-import { Button } from '../Button';
-
-const meta: Meta<typeof Tooltip> = {
-  title: 'Components/Tooltip',
-  component: Tooltip,
-};
-
-export default meta;
-type Story = StoryObj<typeof Tooltip>;
-
-export const Default: Story = {
-  render: () => (
-    <div style={{ padding: 80, display: 'flex', justifyContent: 'center' }}>
-      <Tooltip label="This is a tooltip">
-        <Button variant="secondary" label="Hover me" />
-      </Tooltip>
-    </div>
-  ),
-};
-
-export const Positions: Story = {
-  render: () => (
-    <div style={{ padding: 100, display: 'flex', gap: 24, justifyContent: 'center' }}>
-      {(['top', 'right', 'bottom', 'left'] as const).map(side => (
-        <Tooltip key={side} label={`Tooltip on ${side}`} side={side}>
-          <Button variant="secondary" label={side} />
-        </Tooltip>
-      ))}
-    </div>
-  ),
-};
-
-export const WithShortcut: Story = {
-  render: () => (
-    <div style={{ padding: 80, display: 'flex', gap: 24, justifyContent: 'center' }}>
-      <Tooltip label="Save" shortcutKey="S">
-        <Button variant="secondary" label="Save" />
-      </Tooltip>
-      <Tooltip label="Undo" shortcutKey="Z" shortcutKeyPosition="start">
-        <Button variant="secondary" label="Undo" />
-      </Tooltip>
-    </div>
-  ),
-};

package/src/components/Tooltip/Tooltip.tsx

@@ -1,260 +0,0 @@
-import React, { useState, useRef, useEffect, useLayoutEffect, useCallback, useId } from 'react';
-import { createPortal } from 'react-dom';
-import { getCssTimeMs } from '@/utils/css-tokens';
-import { Text } from '@/components/Text';
-import styles from './Tooltip.module.css';
-
-const HOVER_DELAY_FALLBACK_MS = 1000;
-const INSTANT_REOPEN_MS = 300;
-const FADE_OUT_DURATION_MS = 200;
-
-let lastTooltipDismissedAt = 0;
-
-export type TooltipSide = 'top' | 'right' | 'bottom' | 'left';
-export type TooltipAlign = 'start' | 'center' | 'end';
-
-export interface TooltipProps {
-  label: string;
-  children: React.ReactElement;
-  delay?: number;
-  side?: TooltipSide;
-  align?: TooltipAlign;
-  sideOffset?: number;
-  alignOffset?: number;
-  shortcutKey?: string;
-  shortcutKeyPosition?: 'start' | 'end';
-  usePortal?: boolean;
-}
-
-export const Tooltip: React.FC<TooltipProps> = ({
-  label,
-  children,
-  delay,
-  side = 'top',
-  align = 'center',
-  sideOffset = 4,
-  alignOffset = 0,
-  shortcutKey,
-  shortcutKeyPosition = 'end',
-  usePortal = true,
-}) => {
-  const hoverDelayMs = getCssTimeMs('--effect-animation-delay-medium-3', HOVER_DELAY_FALLBACK_MS);
-  const resolvedDelay = delay ?? hoverDelayMs;
-  const anchorRef = useRef<HTMLElement | null>(null);
-  const tooltipRef = useRef<HTMLDivElement>(null);
-  const tooltipId = useId();
-
-  const setAnchorRef = useCallback(
-    (el: HTMLElement | null) => {
-      (anchorRef as React.MutableRefObject<HTMLElement | null>).current = el;
-      const childEl = React.Children.only(children) as React.ReactElement<{ ref?: React.Ref<unknown> }>;
-      const childRef = 'ref' in childEl ? childEl.ref : undefined;
-      if (typeof childRef === 'function') childRef(el);
-      else if (childRef && typeof childRef === 'object') (childRef as React.MutableRefObject<unknown>).current = el;
-    },
-    [children]
-  );
-
-  const [open, setOpen] = useState(false);
-  const [isClosing, setIsClosing] = useState(false);
-  const [shouldRender, setShouldRender] = useState(false);
-  const [position, setPosition] = useState<{ x: number; y: number }>({ x: 0, y: 0 });
-  const [tooltipSize, setTooltipSize] = useState<{ width: number; height: number }>({ width: 0, height: 0 });
-  const delayTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const viewportPadding = 4;
-
-  const clearDelayTimer = () => {
-    if (delayTimerRef.current) { clearTimeout(delayTimerRef.current); delayTimerRef.current = null; }
-  };
-
-  const handleOpen = () => {
-    clearDelayTimer();
-    const showImmediately = Date.now() - lastTooltipDismissedAt < INSTANT_REOPEN_MS;
-    if (showImmediately) {
-      setOpen(true); setShouldRender(true); setIsClosing(false); return;
-    }
-    delayTimerRef.current = setTimeout(() => {
-      delayTimerRef.current = null;
-      setOpen(true); setShouldRender(true); setIsClosing(false);
-    }, resolvedDelay);
-  };
-
-  const handleClose = () => {
-    clearDelayTimer();
-    if (closeTimerRef.current) { clearTimeout(closeTimerRef.current); closeTimerRef.current = null; }
-    if (!open && !shouldRender) return;
-    lastTooltipDismissedAt = Date.now();
-    setIsClosing(true);
-    closeTimerRef.current = setTimeout(() => {
-      closeTimerRef.current = null;
-      setShouldRender(false); setOpen(false); setIsClosing(false);
-    }, FADE_OUT_DURATION_MS);
-  };
-
-  useEffect(() => () => { clearDelayTimer(); if (closeTimerRef.current) clearTimeout(closeTimerRef.current); }, []);
-
-  useEffect(() => {
-    if (!shouldRender) return;
-    const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') handleClose();
-    };
-    document.addEventListener('keydown', onKeyDown);
-    return () => document.removeEventListener('keydown', onKeyDown);
-    // handleClose is stable in effect — re-subscribing on each render would churn the listener
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [shouldRender]);
-
-  useLayoutEffect(() => {
-    if (!shouldRender || !tooltipRef.current) return;
-    const updateSize = () => {
-      if (!tooltipRef.current) return;
-      const rect = tooltipRef.current.getBoundingClientRect();
-      const w = rect.width || tooltipRef.current.offsetWidth;
-      const h = rect.height || tooltipRef.current.offsetHeight;
-      if (w > 0 && h > 0) setTooltipSize({ width: w, height: h });
-    };
-    updateSize();
-    requestAnimationFrame(updateSize);
-    if (typeof ResizeObserver !== 'undefined') {
-      const observer = new ResizeObserver(updateSize);
-      observer.observe(tooltipRef.current);
-      return () => observer.disconnect();
-    }
-  }, [shouldRender, label, shortcutKey, shortcutKeyPosition]);
-
-  useLayoutEffect(() => {
-    if (!shouldRender || !anchorRef.current || !tooltipRef.current) return;
-    const calculatePosition = () => {
-      if (!anchorRef.current || !tooltipRef.current) return;
-      const a = anchorRef.current.getBoundingClientRect();
-      const tw = tooltipRef.current.getBoundingClientRect().width || tooltipSize.width || 80;
-      const th = tooltipRef.current.getBoundingClientRect().height || tooltipSize.height || 24;
-      let x = 0, y = 0;
-      switch (side) {
-        case 'top':
-          y = a.top - th - sideOffset;
-          x = align === 'start' ? a.left + alignOffset : align === 'end' ? a.right - tw + alignOffset : a.left + a.width / 2 - tw / 2 + alignOffset;
-          break;
-        case 'bottom':
-          y = a.bottom + sideOffset;
-          x = align === 'start' ? a.left + alignOffset : align === 'end' ? a.right - tw + alignOffset : a.left + a.width / 2 - tw / 2 + alignOffset;
-          break;
-        case 'left':
-          x = a.left - tw - sideOffset;
-          y = align === 'start' ? a.top + alignOffset : align === 'end' ? a.bottom - th + alignOffset : a.top + a.height / 2 - th / 2 + alignOffset;
-          break;
-        case 'right':
-          x = a.right + sideOffset;
-          y = align === 'start' ? a.top + alignOffset : align === 'end' ? a.bottom - th + alignOffset : a.top + a.height / 2 - th / 2 + alignOffset;
-          break;
-      }
-      setPosition({
-        x: Math.min(Math.max(x, viewportPadding), window.innerWidth - tw - viewportPadding),
-        y: Math.min(Math.max(y, viewportPadding), window.innerHeight - th - viewportPadding),
-      });
-    };
-    calculatePosition();
-    requestAnimationFrame(() => requestAnimationFrame(calculatePosition));
-  }, [shouldRender, side, align, sideOffset, alignOffset, tooltipSize.width, tooltipSize.height, label]);
-
-  useEffect(() => {
-    if (!shouldRender) return;
-    const onScrollResize = () => {
-      if (!anchorRef.current || !tooltipRef.current) return;
-      const a = anchorRef.current.getBoundingClientRect();
-      const tw = tooltipSize.width || 80;
-      const th = tooltipSize.height || 24;
-      let x = 0, y = 0;
-      switch (side) {
-        case 'top': y = a.top - th - sideOffset; x = align === 'start' ? a.left + alignOffset : align === 'end' ? a.right - tw + alignOffset : a.left + a.width / 2 - tw / 2 + alignOffset; break;
-        case 'bottom': y = a.bottom + sideOffset; x = align === 'start' ? a.left + alignOffset : align === 'end' ? a.right - tw + alignOffset : a.left + a.width / 2 - tw / 2 + alignOffset; break;
-        case 'left': x = a.left - tw - sideOffset; y = align === 'start' ? a.top + alignOffset : align === 'end' ? a.bottom - th + alignOffset : a.top + a.height / 2 - th / 2 + alignOffset; break;
-        case 'right': x = a.right + sideOffset; y = align === 'start' ? a.top + alignOffset : align === 'end' ? a.bottom - th + alignOffset : a.top + a.height / 2 - th / 2 + alignOffset; break;
-      }
-      setPosition({
-        x: Math.min(Math.max(x, viewportPadding), window.innerWidth - tw - viewportPadding),
-        y: Math.min(Math.max(y, viewportPadding), window.innerHeight - th - viewportPadding),
-      });
-    };
-    window.addEventListener('scroll', onScrollResize, true);
-    window.addEventListener('resize', onScrollResize);
-    return () => { window.removeEventListener('scroll', onScrollResize, true); window.removeEventListener('resize', onScrollResize); };
-  }, [shouldRender, side, align, sideOffset, alignOffset, tooltipSize.width, tooltipSize.height]);
-
-  const keyHint = shortcutKey ? (
-    <div className={styles.keyHint} aria-hidden>
-      <Text variant="text-caption-emphasis" as="span" color="primary">{shortcutKey}</Text>
-    </div>
-  ) : null;
-
-  const tooltipContent = shouldRender ? (
-    <div
-      ref={tooltipRef}
-      id={tooltipId}
-      className={`${styles.tooltip} ${isClosing ? styles.closing : ''}`}
-      style={{
-        position: 'fixed',
-        left: 0,
-        top: 0,
-        transform: `translate(${Math.round(position.x)}px, ${Math.round(position.y)}px)`,
-        willChange: 'transform',
-        zIndex: 10000,
-      }}
-      role="tooltip"
-      onMouseEnter={handleOpen}
-      onMouseLeave={handleClose}
-    >
-      <div className={styles.tooltipInner}>
-        {shortcutKey && shortcutKeyPosition === 'start' && keyHint}
-        <Text variant="text-body-small" as="span" color="primary">{label}</Text>
-        {shortcutKey && shortcutKeyPosition === 'end' && keyHint}
-      </div>
-    </div>
-  ) : null;
-
-  type TriggerProps = {
-    onMouseEnter?: (e: React.MouseEvent) => void;
-    onMouseLeave?: (e: React.MouseEvent) => void;
-    onFocus?: (e: React.FocusEvent) => void;
-    onBlur?: (e: React.FocusEvent) => void;
-    'aria-describedby'?: string;
-  };
-  const trigger = React.Children.only(children);
-  const triggerEl = React.isValidElement<TriggerProps>(trigger) ? trigger : null;
-  const existingDescribedBy = triggerEl?.props['aria-describedby'];
-  const mergedDescribedBy =
-    [existingDescribedBy, shouldRender ? tooltipId : undefined].filter(Boolean).join(' ') ||
-    undefined;
-  const triggerWithRefAndHandlers = triggerEl
-    ? React.cloneElement(triggerEl, {
-        ref: setAnchorRef,
-        'aria-describedby': mergedDescribedBy,
-        onMouseEnter: (e: React.MouseEvent) => {
-          handleOpen();
-          triggerEl.props.onMouseEnter?.(e);
-        },
-        onMouseLeave: (e: React.MouseEvent) => {
-          handleClose();
-          triggerEl.props.onMouseLeave?.(e);
-        },
-        onFocus: (e: React.FocusEvent) => {
-          handleOpen();
-          triggerEl.props.onFocus?.(e);
-        },
-        onBlur: (e: React.FocusEvent) => {
-          handleClose();
-          triggerEl.props.onBlur?.(e);
-        },
-      } as Partial<TriggerProps> & { ref: typeof setAnchorRef })
-    : children;
-
-  return (
-    <>
-      {triggerWithRefAndHandlers}
-      {usePortal ? createPortal(tooltipContent, document.body) : tooltipContent}
-    </>
-  );
-};
-
-Tooltip.displayName = 'Tooltip';

package/src/components/Tooltip/index.ts

@@ -1,2 +0,0 @@
-export { Tooltip } from './Tooltip';
-export type { TooltipProps, TooltipSide, TooltipAlign } from './Tooltip';

package/src/css-modules.d.ts

@@ -1,4 +0,0 @@
-declare module '*.module.css' {
-  const classes: { [key: string]: string };
-  export default classes;
-}

package/src/docs/ColorUsage.mdx

@@ -1,195 +0,0 @@
-import { Meta } from '@storybook/addon-docs/blocks';
-
-<Meta title="Docs/Color Usage" />
-
-# Color Usage Guidelines
-
-## 1. Objective
-
-This document explains how to use color tokens in product code and design implementation.
-
-The key distinction in this repository is:
-
-1. semantic colors are for UI meaning, hierarchy, and component states,
-2. data colors are for charts, graphs, and other visualization marks,
-3. both layers are aliases on top of the reference palette.
-
-If a choice is available between semantic and data tokens, default to semantic for interface chrome and default to data for visualization marks.
-
-## 2. Quick Decision Rule
-
-Use this rule first:
-
-1. use semantic colors when the color communicates UI role,
-2. use data colors when the color differentiates or encodes data,
-3. use reference colors only when working on the token system itself.
-
-Examples:
-
-1. page background, card text, button hover, error banner: **semantic**
-2. bar series, line series, pie slices, heatmap steps: **data**
-3. palette generation or alias maintenance: **reference**
-
-## 3. Semantic Colors
-
-### 3.1 What Semantic Means
-
-Semantic tokens are named by purpose, not by visual appearance. They should be chosen based on what the UI element is doing, not based on whether a blue, red, or grey value looks convenient.
-
-For example:
-
-- `background.primary` means the main surface
-- `foreground.secondary` means lower-emphasis content
-- `background.strong.negative` means a strong negative-intent surface
-- `interaction.hover` means an interaction overlay
-- `foreground.on-strong-background.primary` means primary content placed on a strong colored background
-
-### 3.2 When To Use Semantic Colors
-
-Use semantic tokens for:
-
-1. application and component surfaces,
-2. text and icon hierarchy,
-3. borders and strokes when they convey UI structure,
-4. status styling such as brand, positive, warning, and negative,
-5. hover and pressed overlays,
-6. special product-domain markers that are part of the product language.
-
-Do not use semantic tokens to color arbitrary chart series just because a semantic hue looks nice.
-
-### 3.3 Common Semantic Families
-
-#### Background
-
-Use background tokens for surfaces and fills.
-
-- `background.primary` and `background.secondary` are standard UI surfaces
-- `background.strong.*`, `background.bold.*`, `background.medium.*`, and `background.faint.*` express emphasis and intent
-- `background.translucent`, `background.shade`, and `background.transparent` are utility surface values
-
-Typical mapping:
-
-| Use case | Token |
-|----------|-------|
-| Nested card or panel surface | <code>background.primary</code> |
-| App shell or secondary panel | <code>background.secondary</code> |
-| Bold status banner | <code>background.bold.negative</code> |
-| Subtle info container | <code>background.faint.neutral</code> |
-
-#### Foreground
-
-Use foreground tokens for text, icons, and strokes that follow content hierarchy.
-
-- `foreground.primary` is the highest-emphasis content
-- `foreground.secondary` through `foreground.quaternary` reduce emphasis
-- `foreground.strong.*`, `foreground.bold.*`, `foreground.medium.*`, and `foreground.faint.*` provide colored content roles
-- `foreground.on-strong-background.*` is for content placed on strong colored surfaces
-
-Typical mapping:
-
-| Use case | Token |
-|----------|-------|
-| Main body text | <code>foreground.primary</code> |
-| Helper text or secondary icon | <code>foreground.secondary</code> |
-| Inactive or de-emphasized content | <code>foreground.tertiary</code> |
-| Disabled or very low-emphasis ornament | <code>foreground.quaternary</code> |
-| Text on a bold brand fill | <code>foreground.on-bold-background.primary</code> |
-
-> **Note:** `foreground.tertiary` is only about 3.35:1 in light mode and 3.23:1 in dark mode, so it does not meet AA for standard text sizes. Use it only for genuinely low-emphasis content.
-
-#### Interaction
-
-Use interaction tokens for overlays caused by state changes, not for base surfaces or replacement fills.
-
-- `interaction.hover` and `interaction.pressed` are for standard surfaces
-- `interaction.on-strong-background.hover` and similar are for colored fills
-- Interaction tokens preserve the underlying semantic meaning of the surface they sit on
-
-#### Border & Divider
-
-- `border.primary`, `border.secondary`, and `border.tertiary` are for container edges, field outlines, card strokes
-- `divider.divider` is for internal rules that separate content inside a surface
-- `divider.on-strong-background`, `divider.on-bold-background`, etc. are divider variants for colored fills
-
-> **Divider tokens** are narrower in purpose than border tokens. Use them only when drawing a horizontal or vertical rule inside a surface.
-
-#### Always-Dark
-
-Use `always-dark.*` only when the component must stay dark regardless of surrounding theme. This is a special-case family for fixed dark contexts.
-
-### 3.4 Semantic Tone Selection
-
-When multiple semantic intensities exist, choose the one that matches the amount of emphasis required:
-
-| Tone | Purpose |
-|------|---------|
-| <code>strong</code> | Highest-emphasis fills or content |
-| <code>bold</code> | Strong but less dominant than strong |
-| <code>medium</code> | Mid-emphasis |
-| <code>faint</code> | Low-emphasis tinting or supporting treatment |
-
-When a surface uses a strong semantic background, pair it with the matching `on-background` content token rather than reusing normal foreground tokens.
-
-## 4. Data Colors
-
-### 4.1 When To Use Data Colors
-
-Use data tokens for:
-
-1. chart series colors,
-2. legend keys,
-3. map overlays and plotted markers,
-4. heatmaps and gradients tied to values,
-5. ordered or diverging color ramps.
-
-Do **not** use data tokens for page backgrounds, standard text hierarchy, button states, banners, or form validation.
-
-### 4.2 Common Data Families
-
-| Family | Purpose | Examples |
-|--------|---------|----------|
-| <code>data-misc</code> | Neutral visualization elements | Gridlines, reference lines, axes |
-| <code>data-category</code> | Nominal categories (unordered) | Multi-series bars, pie slices, legend palettes |
-| <code>data-win-loss</code> | Outcome polarity | Pass/fail, win/loss, positive/negative |
-| <code>data-sequence-&#42;</code> | Ordered single-direction values | Intensity ramps, ordered buckets, choropleths |
-| <code>data-diverging-&#42;</code> | Values extending from a midpoint | Above/below target, deviation from baseline |
-
-> **Important:** When using `data-category` colors together, use them in numeric order (1, 2, 3...). This is especially important when categories touch each other (donut charts, stacked bars).
-
-### 4.3 How Semantic And Data Work Together
-
-| Element | Token source |
-|---------|-------------|
-| Chart card background | <code>background.primary</code> (semantic) |
-| Chart title | <code>foreground.primary</code> (semantic) |
-| Axis labels | <code>foreground.secondary</code> (semantic) |
-| Chart bars/lines | <code>data-category.&#42;</code> or <code>data-sequence-&#42;</code> (data) |
-| Alert banner around chart | <code>background.faint.warning</code> (semantic) |
-
-## 5. Accessibility & Pairing
-
-### Preferred Text Pairings
-
-| Background | Safe foreground | Lowest contrast |
-|-----------|----------------|-----------------|
-| <code>background.primary</code> | <code>foreground.primary</code> or <code>.secondary</code> | ~5.74:1 light, ~6.13:1 dark |
-| <code>background.strong.&#42;</code> | <code>foreground.on-strong-background.primary</code> or <code>.secondary</code> | ~6.54:1 light, ~5.28:1 dark |
-| <code>background.bold.&#42;</code> | <code>foreground.on-bold-background.primary</code> or <code>.secondary</code> | ~5.45:1 light, ~4.89:1 dark |
-
-### Tone Pairs
-
-- `background.bold.*` with `foreground.faint.*` — safe, lowest floor ~4.54:1
-- `background.faint.*` with `foreground.bold.*` — safe, same reciprocal rule
-- `background.strong.*` with `foreground.medium.*` — near-AA, not guaranteed for every intent
-
-## 6. Anti-Patterns
-
-Avoid these patterns:
-
-1. choosing a token only because the hue looks visually convenient,
-2. using semantic status colors as a chart palette,
-3. using data colors for ordinary UI text or surfaces,
-4. mixing reference tokens directly into product code,
-5. pairing strong backgrounds with regular foreground tokens instead of `on-background` tokens,
-6. using `divider.*` as a generic border token,
-7. changing token meaning across screens without a strong product reason.