@robr0/design-system 0.2.0 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ The **live site** is the portfolio built on the design system. **Storybook** is
 | Part | Description |
 |---|---|
 | **Portfolio website** (`/website`) | Next.js app with case studies, work history, writing, and about pages — all built exclusively with the design system components below. **[Live site →](https://robertritacca.com/)** |
-| **Design system** (`/src`) | <!-- component-count -->56<!-- /component-count --> React components, a three-tier token architecture, dark mode, and a full documentation site. Built to production standards. **[Storybook →](https://design-system-iota-one.vercel.app/?path=/docs/robr0-ds--docs)** |
+| **Design system** (`/src`) | <!-- component-count -->61<!-- /component-count --> React components, a three-tier token architecture, dark mode, and a full documentation site. Built to production standards. **[Storybook →](https://design-system-iota-one.vercel.app/?path=/docs/robr0-ds--docs)** |
 
 ---
 
@@ -27,17 +27,19 @@ The **live site** is the portfolio built on the design system. **Storybook** is
 ### Components
 
 <!-- component-list:start -->
-Accordion · Alert · Alert dialog · App layout · App sidebar · Avatar · Badge · Breadcrumb · Button · Button group · Card · Carousel · Chart · Checkbox · Chip · Circular button · Code block · Combobox · Command palette · Contact card · Contribution graph · Date input · Date picker · Dialog · Divider · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Figure · File input · Input · Instructions · Link list · Nav · Pagination · Popover · Progress bar · Quote · Radio button · Section title · Segmented control · Selection card · Skeleton · Slider · Spinner · Stat · Table · Tabs · Textarea · Timeline · Toast · Toggle group · Toggle switch · Tooltip
+Accordion · Alert · Alert dialog · App layout · App sidebar · Avatar · Badge · Breadcrumb · Button · Button group · Card · Carousel · Chart · Checkbox · Chip · Circular button · Code block · Colour picker · Combobox · Command palette · Contact card · Context menu · Contribution graph · Date input · Date picker · Dialog · Divider · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Field · Figure · File input · Input · Instructions · Kbd · Link list · Navigation · Pagination · Popover · Progress bar · Quote · Radio button · Section title · Segmented control · Selection card · Skeleton · Slider · Spinner · Stat · Swatch · Table · Tabs · Textarea · Timeline · Toast · Toggle group · Toggle switch · Tooltip
 <!-- component-list:end -->
 
 ### Using the package
 
-The design system is published as [`@robr0/design-system`](https://www.npmjs.com/package/@robr0/design-system) (React 19+ is a peer dependency):
+The design system is published as [`@robr0/design-system`](https://www.npmjs.com/package/@robr0/design-system) (React 19+ is a peer dependency) — the **[full setup guide](https://www.robertritacca.com/docs/get-started)** covers install, dark mode, fonts, and re-theming:
 
 ```bash
 npm install @robr0/design-system
 ```
 
+The package is ESM-only and resolved via `exports` subpaths: use a bundler that handles CSS and font imports from `node_modules` (Vite, Next.js, webpack), and set TypeScript's `moduleResolution` to `"bundler"` (or `"nodenext"`).
+
 Import the token stylesheet once (it carries the primitives, semantic tokens, and both themes), then use components:
 
 ```tsx
@@ -51,7 +53,7 @@ Deep imports work too (`@robr0/design-system/components/Button/Button`). Chart c
 import { BarChart, LineChart } from '@robr0/design-system/charts';
 ```
 
-**Theming and customization** happen through CSS variables — no configuration API:
+**Theming and customization** happen through CSS variables — no configuration API. Components are provider-free, with one exception: wrap your tree in `ToastProvider` if (and only if) you use the toast queue via `useToast`.
 
 - **Dark mode**: set `data-theme="dark"` on the root element (light is the default).
 - **Font**: the whole type scale chains to one token. Load any font you like and override it:
@@ -107,10 +109,10 @@ Full spec in [`design.md`](design.md).
 
 ## Quality & CI
 
-Every push and pull request runs a GitHub Actions pipeline ([`ci.yml`](.github/workflows/ci.yml)) with four jobs: **lint + library build**, **story tests** (every Storybook story rendered in headless Chromium via Vitest), **Storybook build**, and **website build**. The same checklist runs locally with one command:
+Every push and pull request runs a GitHub Actions pipeline ([`ci.yml`](.github/workflows/ci.yml)) with four jobs: **lint + library build**, **story tests** (every Storybook story rendered in headless Chromium via Vitest), **Storybook build**, and **website lint + build**. The same checklist runs locally with one command:
 
 ```bash
-npm run verify   # lint + library type-check + package build + story tests + Storybook build + website build
+npm run verify   # lint + library type-check + package build + story tests + Storybook build + website lint + build
 ```
 
 CI also guards against documentation drift: generated surfaces (this README's component count and list, the website's skills pages, the published CLAUDE.md/design.md blueprints) are rebuilt from their source registries on every build, and CI fails if the committed copies are stale. The numbers on the site are never hand-written.

package/components/Accordion/Accordion.js

@@ -59,7 +59,6 @@ const Accordion = ({
             "div",
             {
               id: `${baseClass}-panel-${item.id}`,
-              role: "region",
               "aria-labelledby": `${baseClass}-header-${item.id}`,
               className: `${baseClass}__panel`,
               children: /* @__PURE__ */ jsx("div", { className: `${baseClass}__content`, children: item.content })

package/components/Avatar/Avatar.js

@@ -46,6 +46,7 @@ const Avatar = ({
       "span",
       {
         className: `${baseClass}__status ${baseClass}__status--${status}`,
+        role: "img",
         "aria-label": status
       }
     )

package/components/Breadcrumb/Breadcrumb.d.ts

@@ -11,9 +11,15 @@ export interface BreadcrumbProps {
     maxItems?: number;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * Accessible name for the nav landmark. Override when more than one
+     * Breadcrumb can appear on a page — identically-named landmarks are
+     * indistinguishable to assistive technology.
+     */
+    ariaLabel?: string;
 }
 /**
  * Breadcrumb shows the user's location within a page hierarchy.
  * Supports automatic collapsing of middle items when the list exceeds maxItems.
  */
-export declare const Breadcrumb: ({ items, maxItems, className, }: BreadcrumbProps) => import("react").JSX.Element;
+export declare const Breadcrumb: ({ items, maxItems, className, ariaLabel, }: BreadcrumbProps) => import("react").JSX.Element;

package/components/Breadcrumb/Breadcrumb.js

@@ -4,7 +4,8 @@ import "../../fonts/material-symbols.css";
 const Breadcrumb = ({
   items,
   maxItems,
-  className = ""
+  className = "",
+  ariaLabel
 }) => {
   const baseClass = "ds-breadcrumb";
   const classes = [baseClass, className].filter(Boolean).join(" ");
@@ -20,7 +21,7 @@ const Breadcrumb = ({
   } else {
     visibleItems = [...items];
   }
-  return /* @__PURE__ */ jsx("nav", { className: classes, "aria-label": "Breadcrumb", children: /* @__PURE__ */ jsx("ol", { className: `${baseClass}__list`, children: visibleItems.map((item, index) => {
+  return /* @__PURE__ */ jsx("nav", { className: classes, "aria-label": ariaLabel || "Breadcrumb", children: /* @__PURE__ */ jsx("ol", { className: `${baseClass}__list`, children: visibleItems.map((item, index) => {
     const isLast = index === visibleItems.length - 1;
     if (item === "ellipsis") {
       return /* @__PURE__ */ jsxs("li", { className: `${baseClass}__item`, "aria-hidden": "true", children: [

package/components/Button/Button.css

@@ -371,6 +371,24 @@
   color: var(--color-status-error-bg);
 }
 
+/* ============================================
+   LOADING
+   Keeps the variant's full-colour appearance (no disabled dim);
+   the spinner occupies the left icon slot and inherits its colour.
+   ============================================ */
+
+.ds-button--loading {
+  cursor: progress;
+  pointer-events: none;
+}
+
+/* The generic icon-slot svg sizing must not distort the spinner —
+   it sizes itself from the Spinner size prop */
+.ds-button .ds-button__icon .ds-spinner__circle {
+  width: 100%;
+  height: 100%;
+}
+
 /* ============================================
    FOCUS
    ============================================ */

package/components/Button/Button.d.ts

@@ -13,6 +13,12 @@ type ButtonOwnProps = {
     size?: 'default' | 'compact';
     /** Whether the button is disabled */
     disabled?: boolean;
+    /**
+     * Shows a spinner in the left icon slot and blocks interaction while an
+     * async action runs. Keeps the variant's full-colour appearance (unlike
+     * `disabled`) and sets `aria-busy` on the rendered element.
+     */
+    loading?: boolean;
     /** Optional href — renders as <a> instead of <button> */
     href?: string;
     /** Optional target attribute for links */

package/components/Button/Button.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import React from "react";
+import { Spinner } from "../Spinner/Spinner.js";
 import "./Button.css";
 import "../../fonts/material-symbols.css";
 const Button = React.forwardRef(
@@ -10,6 +11,7 @@ const Button = React.forwardRef(
     variant,
     size = "default",
     disabled,
+    loading,
     href,
     target,
     rel,
@@ -25,27 +27,32 @@ const Button = React.forwardRef(
     const resolvedVariant = variant ?? priority ?? "primary";
     const isDisabled = disabled ?? state === "disabled";
     const resolvedState = state ?? (isDisabled ? "disabled" : "default");
+    const isLoading = Boolean(loading);
     const classes = [
       baseClass,
       `${baseClass}--${resolvedVariant}`,
       `${baseClass}--${resolvedState}`,
       `${baseClass}--${size}`,
+      isLoading && `${baseClass}--loading`,
       className
     ].filter(Boolean).join(" ");
     const iconClass = "material-symbols-rounded";
-    const leftIcon = iconLeft || icon;
+    const spinnerSize = size === "compact" ? "sm" : "md";
+    const leftIcon = isLoading ? /* @__PURE__ */ jsx(Spinner, { size: spinnerSize, variant: "inherit" }) : iconLeft || icon;
     const renderIcon = (iconProp) => {
       if (typeof iconProp === "string") {
         return /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon ${iconClass}`, "aria-hidden": "true", children: iconProp });
       }
       return /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon`, "aria-hidden": "true", children: iconProp });
     };
+    const needsAccessibleName = !text || !label;
+    const fallbackAriaLabel = needsAccessibleName && label && !rest["aria-label"] ? label : void 0;
     const content = /* @__PURE__ */ jsxs(Fragment, { children: [
       leftIcon && renderIcon(leftIcon),
       text && /* @__PURE__ */ jsx("span", { className: `${baseClass}__text`, children: label }),
       iconRight && renderIcon(iconRight)
     ] });
-    if (href && !isDisabled) {
+    if (href && !isDisabled && !isLoading) {
       return /* @__PURE__ */ jsx(
         "a",
         {
@@ -56,6 +63,7 @@ const Button = React.forwardRef(
           target,
           rel,
           "aria-current": ariaCurrent ? "page" : void 0,
+          "aria-label": fallbackAriaLabel ?? rest["aria-label"],
           children: content
         }
       );
@@ -67,7 +75,9 @@ const Button = React.forwardRef(
         ref,
         type: "button",
         className: classes,
-        disabled: isDisabled,
+        disabled: isDisabled || isLoading,
+        "aria-busy": isLoading || void 0,
+        "aria-label": fallbackAriaLabel ?? rest["aria-label"],
         children: content
       }
     );

package/components/Card/Card.css

@@ -25,6 +25,8 @@
 
   /* Interaction */
   transition: transform var(--motion-duration-slow) var(--motion-ease-standard), box-shadow var(--motion-duration-slow) var(--motion-ease-standard);
+  /* ds-allow(color): transparent resting state of the sanctioned Card
+     hover-lift shadow (see design.md — Do's and Don'ts). */
   box-shadow: 0 0 0 rgba(0, 0, 0, 0);
 }
 
@@ -34,6 +36,8 @@
 
 .ds-card--interactive:hover {
   transform: translateY(-4px);
+  /* ds-allow(color): the sanctioned Card hover-lift shadow — deliberately
+     heavier than --shadow-floating (see design.md — Do's and Don'ts). */
   box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
 }
 
@@ -80,6 +84,8 @@
 
 .ds-card--case-study:hover {
   transform: translateY(-4px);
+  /* ds-allow(color): same sanctioned hover-lift shadow as the interactive
+     variant. */
   box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
 }
 

package/components/CircularButton/CircularButton.css

@@ -196,6 +196,17 @@
   background-color: var(--color-action-passive-bg-active);
 }
 
+/* ============================================
+   LOADING
+   Keeps the variant's full-colour appearance (no disabled dim);
+   the spinner replaces the icon and inherits its colour.
+   ============================================ */
+
+.ds-circular-button--loading {
+  cursor: progress;
+  pointer-events: none;
+}
+
 /* ============================================
    FOCUS
    ============================================ */

package/components/CircularButton/CircularButton.d.ts

@@ -7,6 +7,12 @@ export interface CircularButtonProps {
     state?: 'default' | 'hover' | 'active' | 'disabled';
     /** Button size */
     size?: 'default' | 'compact';
+    /**
+     * Shows a spinner in place of the icon and blocks interaction while an
+     * async action runs. Keeps the variant's full-colour appearance (unlike
+     * the disabled state) and sets `aria-busy` on the rendered element.
+     */
+    loading?: boolean;
     /** Accessible label */
     ariaLabel: string;
     /** Optional click handler */
@@ -27,4 +33,4 @@ export interface CircularButtonProps {
  * A round button containing a single icon, available in
  * primary and secondary variants with default and compact sizes.
  */
-export declare const CircularButton: ({ icon, priority, state, size, ariaLabel, onClick, href, target, rel, "aria-describedby": ariaDescribedby, className, }: CircularButtonProps) => import("react").JSX.Element;
+export declare const CircularButton: ({ icon, priority, state, size, loading, ariaLabel, onClick, href, target, rel, "aria-describedby": ariaDescribedby, className, }: CircularButtonProps) => import("react").JSX.Element;

package/components/CircularButton/CircularButton.js

@@ -1,4 +1,5 @@
 import { jsx } from "react/jsx-runtime";
+import { Spinner } from "../Spinner/Spinner.js";
 import "./CircularButton.css";
 import "../../fonts/material-symbols.css";
 const CircularButton = ({
@@ -6,6 +7,7 @@ const CircularButton = ({
   priority = "primary",
   state = "default",
   size = "default",
+  loading,
   ariaLabel,
   onClick,
   href,
@@ -18,10 +20,18 @@ const CircularButton = ({
   const variantClass = `${baseClass}--${priority}`;
   const stateClass = `${baseClass}--${state}`;
   const sizeClass = `${baseClass}--${size}`;
-  const classes = [baseClass, variantClass, stateClass, sizeClass, className].filter(Boolean).join(" ");
+  const isLoading = Boolean(loading);
+  const classes = [
+    baseClass,
+    variantClass,
+    stateClass,
+    sizeClass,
+    isLoading && `${baseClass}--loading`,
+    className
+  ].filter(Boolean).join(" ");
   const isDisabled = state === "disabled";
-  const children = /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon material-symbols-rounded`, "aria-hidden": "true", children: icon });
-  if (href && !isDisabled) {
+  const children = isLoading ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon`, "aria-hidden": "true", children: /* @__PURE__ */ jsx(Spinner, { size: size === "compact" ? "sm" : "md", variant: "inherit" }) }) : /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon material-symbols-rounded`, "aria-hidden": "true", children: icon });
+  if (href && !isDisabled && !isLoading) {
     return /* @__PURE__ */ jsx(
       "a",
       {
@@ -42,7 +52,8 @@ const CircularButton = ({
       type: "button",
       className: classes,
       onClick,
-      disabled: isDisabled,
+      disabled: isDisabled || isLoading,
+      "aria-busy": isLoading || void 0,
       "aria-label": ariaLabel,
       "aria-describedby": ariaDescribedby,
       children

package/components/CodeBlock/CodeBlock.js

@@ -77,7 +77,16 @@ const CodeBlock = ({
         }
       )
     ] }),
-    /* @__PURE__ */ jsx("div", { id: panelId, className: `${baseClass}__panel`, "aria-hidden": collapsed || void 0, children: /* @__PURE__ */ jsx("div", { className: `${baseClass}__panel-inner`, children: /* @__PURE__ */ jsx("pre", { className: `${baseClass}__pre`, children: /* @__PURE__ */ jsx("code", { className: `${baseClass}__code`, children: code }) }) }) })
+    /* @__PURE__ */ jsx("div", { id: panelId, className: `${baseClass}__panel`, "aria-hidden": collapsed || void 0, children: /* @__PURE__ */ jsx("div", { className: `${baseClass}__panel-inner`, children: /* @__PURE__ */ jsx(
+      "pre",
+      {
+        className: `${baseClass}__pre`,
+        tabIndex: collapsed ? -1 : 0,
+        role: "region",
+        "aria-label": filename ? `Code: ${filename}` : language ? `Code: ${language}` : "Code",
+        children: /* @__PURE__ */ jsx("code", { className: `${baseClass}__code`, children: code })
+      }
+    ) }) })
   ] });
 };
 export {

package/components/ColorPicker/ColorPicker.css

@@ -0,0 +1,278 @@
+/* ============================================
+   COLORPICKER COMPONENT
+   Swatch trigger + saturation/hue/alpha panel
+
+   Colour-mixing constants: the white/black
+   gradient overlays and the hue spectrum are
+   colour-space physics, not theme decisions —
+   they are written as hsl() literals because no
+   semantic token can represent them. Everything
+   themeable uses tokens as usual.
+
+   ds-allow-file(color): colour-space physics —
+   the gradients and spectrum cannot be theme
+   tokens.
+   ============================================ */
+
+/* Base */
+
+.ds-colorpicker {
+  position: relative;
+  /* Field owns no layout — the root class stacks label, trigger and helper */
+  display: inline-flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--gap-sm);
+}
+
+/* Trigger */
+
+.ds-colorpicker__trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--gap-sm);
+  padding: var(--padding-xxs);
+  border: var(--border-xs) solid var(--color-input-border-primary);
+  border-radius: var(--radius-md);
+  background-color: transparent;
+  cursor: pointer;
+  transition: border-color var(--motion-duration-base) var(--motion-ease-standard);
+}
+
+.ds-colorpicker__trigger:hover:not(:disabled) {
+  border-color: var(--color-input-border-hover);
+}
+
+.ds-colorpicker__trigger:focus-visible {
+  outline: none;
+  border-color: var(--color-input-border-selected);
+}
+
+.ds-colorpicker--open .ds-colorpicker__trigger {
+  border-color: var(--color-input-border-selected);
+}
+
+.ds-colorpicker__trigger-swatch {
+  width: 24px;
+  height: 24px;
+  border-radius: var(--radius-sm);
+  /* Checkerboard shows through translucent colours */
+  background-color: var(--color-bg-page-primary);
+  background-image:
+    linear-gradient(var(--ds-cp-color), var(--ds-cp-color)),
+    repeating-conic-gradient(var(--color-bg-container-tertiary) 0% 25%, transparent 0% 50%);
+  background-size: 100% 100%, 8px 8px;
+  box-shadow: inset 0 0 0 var(--border-xs) var(--color-bg-container-border);
+  flex-shrink: 0;
+}
+
+.ds-colorpicker__trigger-text {
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  line-height: var(--font-paragraph-sm-line-height);
+  color: var(--color-text-primary);
+  font-variant-numeric: tabular-nums;
+  padding-right: var(--padding-xxs);
+}
+
+/* Sizes */
+
+.ds-colorpicker--compact .ds-colorpicker__trigger-swatch {
+  width: 20px;
+  height: 20px;
+}
+
+/* Panel */
+
+.ds-colorpicker__panel {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  margin-top: var(--gap-xxs);
+  width: 240px;
+  padding: var(--padding-sm-md);
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap-sm-md);
+  background-color: var(--color-bg-page-primary);
+  border: var(--border-xs) solid var(--color-input-border-primary);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-floating);
+  z-index: 10;
+}
+
+/* Saturation / brightness area */
+
+.ds-colorpicker__saturation {
+  position: relative;
+  height: 150px;
+  border-radius: var(--radius-sm);
+  cursor: crosshair;
+  touch-action: none;
+  background:
+    linear-gradient(to top, hsl(0 0% 0%), transparent),
+    linear-gradient(to right, hsl(0 0% 100%), transparent),
+    hsl(var(--ds-cp-hue) 100% 50%);
+}
+
+.ds-colorpicker__saturation:focus-visible {
+  outline: var(--border-md) solid var(--color-input-border-selected);
+  outline-offset: var(--border-md);
+}
+
+.ds-colorpicker__handle {
+  position: absolute;
+  left: var(--ds-cp-x);
+  top: var(--ds-cp-y);
+  transform: translate(-50%, -50%);
+  width: 14px;
+  height: 14px;
+  border-radius: var(--radius-full);
+  border: var(--border-md) solid hsl(0 0% 100%);
+  box-shadow: var(--shadow-floating);
+  pointer-events: none;
+}
+
+/* Sliders + preview */
+
+.ds-colorpicker__controls {
+  display: flex;
+  align-items: center;
+  gap: var(--gap-sm-md);
+}
+
+.ds-colorpicker__sliders {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap-sm);
+  min-width: 0;
+}
+
+.ds-colorpicker__hue,
+.ds-colorpicker__alpha {
+  appearance: none;
+  -webkit-appearance: none;
+  width: 100%;
+  height: 12px;
+  border-radius: var(--radius-full);
+  outline: none;
+  cursor: pointer;
+}
+
+.ds-colorpicker__hue {
+  background: linear-gradient(
+    to right,
+    hsl(0 100% 50%),
+    hsl(60 100% 50%),
+    hsl(120 100% 50%),
+    hsl(180 100% 50%),
+    hsl(240 100% 50%),
+    hsl(300 100% 50%),
+    hsl(360 100% 50%)
+  );
+}
+
+.ds-colorpicker__alpha {
+  background-color: var(--color-bg-page-primary);
+  background-image:
+    linear-gradient(to right, transparent, var(--ds-cp-solid)),
+    repeating-conic-gradient(var(--color-bg-container-tertiary) 0% 25%, transparent 0% 50%);
+  background-size: 100% 100%, 8px 8px;
+}
+
+.ds-colorpicker__hue::-webkit-slider-thumb,
+.ds-colorpicker__alpha::-webkit-slider-thumb {
+  appearance: none;
+  -webkit-appearance: none;
+  width: 16px;
+  height: 16px;
+  border-radius: var(--radius-full);
+  background: hsl(0 0% 100%);
+  border: var(--border-xs) solid var(--color-bg-container-border);
+  box-shadow: var(--shadow-floating);
+}
+
+.ds-colorpicker__hue::-moz-range-thumb,
+.ds-colorpicker__alpha::-moz-range-thumb {
+  width: 16px;
+  height: 16px;
+  border-radius: var(--radius-full);
+  background: hsl(0 0% 100%);
+  border: var(--border-xs) solid var(--color-bg-container-border);
+  box-shadow: var(--shadow-floating);
+}
+
+.ds-colorpicker__hue:focus-visible,
+.ds-colorpicker__alpha:focus-visible {
+  outline: var(--border-md) solid var(--color-input-border-selected);
+  outline-offset: var(--border-md);
+}
+
+.ds-colorpicker__preview {
+  width: 32px;
+  height: 32px;
+  border-radius: var(--radius-sm);
+  background-color: var(--color-bg-page-primary);
+  background-image:
+    linear-gradient(var(--ds-cp-color), var(--ds-cp-color)),
+    repeating-conic-gradient(var(--color-bg-container-tertiary) 0% 25%, transparent 0% 50%);
+  background-size: 100% 100%, 8px 8px;
+  box-shadow: inset 0 0 0 var(--border-xs) var(--color-bg-container-border);
+  flex-shrink: 0;
+}
+
+/* Hex + alpha inputs */
+
+.ds-colorpicker__inputs {
+  display: flex;
+  align-items: center;
+  gap: var(--gap-sm);
+  padding: var(--padding-xxs) var(--padding-sm);
+  border: var(--border-xs) solid var(--color-input-border-primary);
+  border-radius: var(--radius-md);
+  transition: border-color var(--motion-duration-base) var(--motion-ease-standard);
+}
+
+.ds-colorpicker__inputs:focus-within {
+  border-color: var(--color-input-border-selected);
+}
+
+.ds-colorpicker__hash {
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  color: var(--color-text-tertiary);
+}
+
+.ds-colorpicker__hex-field {
+  flex: 1;
+  min-width: 0;
+  border: none;
+  background: transparent;
+  outline: none;
+  padding: 0;
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  line-height: var(--font-paragraph-sm-line-height);
+  color: var(--color-text-primary);
+  text-transform: uppercase;
+  font-variant-numeric: tabular-nums;
+}
+
+.ds-colorpicker__alpha-value {
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  color: var(--color-text-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+/* States */
+
+.ds-colorpicker--disabled .ds-colorpicker__trigger {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.ds-colorpicker--error .ds-colorpicker__trigger {
+  border-color: var(--color-status-error-border);
+}

package/components/ColorPicker/ColorPicker.d.ts

@@ -0,0 +1,50 @@
+import { default as React } from 'react';
+/** Props owned by ColorPicker itself — everything else falls through to the trigger <button>. */
+type ColorPickerOwnProps = {
+    /** Field label text */
+    label?: string;
+    /** Current colour as a hex string — 3, 6 or 8 digit, with or without `#` */
+    value?: string;
+    /** Initial colour for uncontrolled use */
+    defaultValue?: string;
+    /**
+     * Convenience callback receiving the colour as an uppercase hex string
+     * (`#RRGGBB`, or `#RRGGBBAA` when `showAlpha` and alpha < 100%). Fires
+     * live while dragging.
+     */
+    onValueChange?: (value: string) => void;
+    /** Show the current hex value as text inside the trigger */
+    showText?: boolean;
+    /** Add an alpha (opacity) slider and emit 8-digit hex when alpha < 100% */
+    showAlpha?: boolean;
+    /** Component size */
+    size?: 'default' | 'compact';
+    /** Whether the picker is disabled */
+    disabled?: boolean;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Error state */
+    error?: boolean;
+    /** Helper or error message */
+    helperText?: string;
+    /**
+     * When set, a hidden `<input type="hidden">` carries the current hex value
+     * under this name so the picker participates in native form submission.
+     */
+    name?: string;
+    /** Additional CSS classes — applied to the wrapper, not the trigger */
+    className?: string;
+};
+export interface ColorPickerProps extends ColorPickerOwnProps, Omit<React.ComponentPropsWithoutRef<'button'>, keyof ColorPickerOwnProps | 'type'> {
+}
+/**
+ * Colour picker: a swatch trigger that opens a panel with a
+ * saturation/brightness area, hue slider, optional alpha slider and a hex
+ * field. Works controlled (`value` + `onValueChange`) or uncontrolled
+ * (`defaultValue`).
+ *
+ * Forwards a ref to the trigger `<button>` and spreads unrecognised props
+ * onto it.
+ */
+export declare const ColorPicker: React.ForwardRefExoticComponent<ColorPickerProps & React.RefAttributes<HTMLButtonElement>>;
+export {};