Usage
DataColor is the narrow exception to palette-only paint in @prepared911/ui. It carries a valid CSS color string from vendor or GIS data through toDataColor, then into fill or stroke on Shape or Swatch only. It is not a token, not ChartColor, and not a general escape hatch for product-owned UI.
ChartColor on charts and Swatch.Box background, Text foreground, Icon foreground, and similar token enums do not accept DataColor at the type level (packages/ui/src/components/data-color/scope.type-test.ts).| Situation | Use |
|---|---|
| Product status, alert, or emphasis | Foreground, Background, StatusDot, Badge, or other token props |
| Chart series you control | ChartColor on Swatch or chart slices |
| Color string from GIS or vendor API you cannot remap | toDataColor, then fill or stroke on Shape or Swatch |
| One-off designer pick in app code | Request a token or use an existing palette enum; not DataColor |
rgb/hsl/hwb/lab/lch/oklab/oklch/color(), named colors, transparent, and similar).undefined (does not throw). Call sites should omit paint or fall back to none.var(, url(, currentcolor, CSS-wide keywords, injection-like characters, and the full list in ADR 0034.DataColor is a branded subtype of string, so any prop typed as plain string still accepts it at compile time. The real guarantee is narrower:
Box background, Text/Icon foreground, and other token paint enums) reject DataColor in type tests.Shape and Swatch read DataColor on fill and stroke and paint it (mechanical scope: packages/ui/tests/data-color-scope.test.ts).fill/stroke still accept palette tokens and ChartColor for product-owned colors.DataColor through unrelated string props expecting components to paint it; only vector marks implement the runtime path.
Calling toDataColor (from @prepared911/ui, @prepared911/ui/primitives or @prepared911/ui/data-color) or casting with as DataColor triggers design-system/to-data-color-call at warning severity in product trees. It shows in pnpm check output; pnpm lint:design-system covers the legacy trees. The rule is informational: explain in the pull request why the color is third-party data you cannot map.