@robr0/design-system 0.2.0 → 0.3.0

package/components/Kbd/Kbd.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+/** Props owned by Kbd itself — everything else falls through to the <kbd> element. */
+type KbdOwnProps = {
+    /** Key size */
+    size?: 'default' | 'compact';
+    /** Additional CSS classes */
+    className?: string;
+    /** The key legend — e.g. ⌘, K, Esc, Shift */
+    children?: React.ReactNode;
+};
+export interface KbdProps extends KbdOwnProps, Omit<React.ComponentPropsWithoutRef<'kbd'>, keyof KbdOwnProps> {
+}
+/**
+ * Kbd renders a single keyboard key as a keycap, for shortcut hints in
+ * menus and docs prose. Compose several for a chord: `<Kbd>⌘</Kbd><Kbd>K</Kbd>`.
+ * Purely presentational — safe to render from a Server Component.
+ */
+export declare const Kbd: React.ForwardRefExoticComponent<KbdProps & React.RefAttributes<HTMLElement>>;
+export {};

package/components/Kbd/Kbd.js

@@ -0,0 +1,14 @@
+import { jsx } from "react/jsx-runtime";
+import React from "react";
+import "./Kbd.css";
+const Kbd = React.forwardRef(
+  ({ size = "default", className = "", children, ...rest }, ref) => {
+    const baseClass = "ds-kbd";
+    const classes = [baseClass, `${baseClass}--${size}`, className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx("kbd", { ...rest, ref, className: classes, children });
+  }
+);
+Kbd.displayName = "Kbd";
+export {
+  Kbd
+};

package/components/Popover/Popover.d.ts

@@ -19,10 +19,4 @@ export interface PopoverProps {
     /** Additional CSS classes for the popover panel */
     className?: string;
 }
-/**
- * Popover component for contextual overlays.
- * Wraps a trigger element and displays content in a
- * positioned panel. Supports click and hover triggers
- * with automatic outside-click dismissal.
- */
 export declare const Popover: ({ children, content, size, position, trigger, open: controlledOpen, onOpenChange, ariaLabel, className, }: PopoverProps) => React.JSX.Element;

package/components/Popover/Popover.js

@@ -1,6 +1,8 @@
 import { jsxs, jsx } from "react/jsx-runtime";
-import { useState, useRef, useCallback, useEffect } from "react";
+import React, { useState, useRef, useCallback, useEffect } from "react";
 import "./Popover.css";
+const INTERACTIVE_TAGS = /* @__PURE__ */ new Set(["button", "a", "input", "select", "textarea", "summary"]);
+const canCarryPopoverSemantics = (el) => typeof el.type === "string" ? INTERACTIVE_TAGS.has(el.type) : true;
 const Popover = ({
   children,
   content,
@@ -73,26 +75,30 @@ const Popover = ({
       onMouseEnter: handleMouseEnter,
       onMouseLeave: handleMouseLeave,
       children: [
-        /* @__PURE__ */ jsx(
-          "div",
+        /* @__PURE__ */ jsx("div", { className: `${baseClass}__trigger`, onClick: handleClick, children: React.isValidElement(children) && canCarryPopoverSemantics(children) ? React.cloneElement(children, {
+          "aria-expanded": isOpen,
+          "aria-haspopup": "dialog",
+          ...ariaLabel ? { "aria-label": ariaLabel } : {}
+        }) : trigger === "click" ? /* @__PURE__ */ jsx(
+          "button",
           {
-            className: `${baseClass}__trigger`,
-            onClick: handleClick,
-            role: trigger === "click" ? "button" : void 0,
-            tabIndex: trigger === "click" ? 0 : void 0,
+            type: "button",
             "aria-expanded": isOpen,
-            "aria-label": ariaLabel,
             "aria-haspopup": "dialog",
-            onKeyDown: (e) => {
-              if (trigger === "click" && (e.key === "Enter" || e.key === " ")) {
-                e.preventDefault();
-                setOpen(!isOpen);
-              }
-            },
+            "aria-label": ariaLabel,
             children
           }
-        ),
-        /* @__PURE__ */ jsx("div", { className: panelClasses, role: "dialog", "aria-hidden": !isOpen, children: content })
+        ) : children }),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: panelClasses,
+            role: "dialog",
+            "aria-label": ariaLabel || "Popover",
+            "aria-hidden": !isOpen,
+            children: content
+          }
+        )
       ]
     }
   );

package/components/ProgressBar/ProgressBar.js

@@ -14,7 +14,7 @@ const ProgressBar = ({
     `${baseClass}--${size}`,
     className
   ].filter(Boolean).join(" ");
-  return /* @__PURE__ */ jsxs("div", { className: classes, role: "progressbar", "aria-valuenow": clamped, "aria-valuemin": 0, "aria-valuemax": 100, "aria-label": ariaLabel, children: [
+  return /* @__PURE__ */ jsxs("div", { className: classes, role: "progressbar", "aria-valuenow": clamped, "aria-valuemin": 0, "aria-valuemax": 100, "aria-label": ariaLabel || "Progress", children: [
     /* @__PURE__ */ jsx("div", { className: `${baseClass}__track`, children: /* @__PURE__ */ jsx("div", { className: `${baseClass}__fill`, style: { width: `${clamped}%` } }) }),
     showLabel && /* @__PURE__ */ jsxs("span", { className: `${baseClass}__label`, children: [
       clamped,

package/components/SelectionCard/SelectionCard.css

@@ -232,8 +232,12 @@
 .ds-selection-card__toggle-icon {
   /* Intentionally off the --icon-size-* scale — same reason as ToggleSwitch:
      this glyph lives inside the 20x20 toggle thumb, and the smallest scale
-     step (20px) would fill it completely. */
-  font-size: 14px;
+     step (20px) would fill it completely. Sized via --icon-size, not
+     font-size, so the icon's box shrinks with the glyph (see ToggleSwitch).
+
+     ds-allow(icon-size): 14px glyph inside the 20px thumb — the smallest
+     scale step would fill it edge to edge. */
+  --icon-size: 14px;
   color: var(--color-action-primary-bg);
 }
 

package/components/Skeleton/Skeleton.css

@@ -22,6 +22,8 @@
     var(--color-bg-container-primary) 50%,
     transparent 100%
   );
+  /* ds-allow(motion): the shimmer needs a symmetric in-out curve and no
+     --motion-ease-* token provides one — the duration is tokenized. */
   animation: ds-skeleton-shimmer var(--motion-duration-loop-shimmer) ease-in-out infinite;
 }
 

package/components/Spinner/Spinner.css

@@ -59,6 +59,17 @@
   stroke: var(--color-text-secondary);
 }
 
+/* Inherit — both circles draw in currentColor so the spinner matches the
+   text/icon colour of whatever control contains it (e.g. a loading Button) */
+.ds-spinner--inherit .ds-spinner__track {
+  stroke: currentColor;
+  opacity: 0.25;
+}
+
+.ds-spinner--inherit .ds-spinner__arc {
+  stroke: currentColor;
+}
+
 /* ============================================
    ANIMATION
    ============================================ */

package/components/Spinner/Spinner.d.ts

@@ -1,8 +1,8 @@
 export interface SpinnerProps {
     /** Size of the spinner */
     size?: 'sm' | 'md' | 'lg';
-    /** Visual variant */
-    variant?: 'primary' | 'neutral';
+    /** Visual variant — `inherit` draws the spinner in `currentColor`, for use inside coloured controls */
+    variant?: 'primary' | 'neutral' | 'inherit';
     /** Accessible label */
     label?: string;
     /** Additional CSS classes */

package/components/Swatch/Swatch.css

@@ -0,0 +1,52 @@
+/* ============================================
+   SWATCH COMPONENT
+   Clickable colour tile for palettes and pickers
+   ============================================ */
+
+/* Base */
+
+.ds-swatch {
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-full);
+  background-color: var(--ds-swatch-color);
+  /* A hairline inset keeps very light colours visible on the white floor */
+  box-shadow: inset 0 0 0 var(--border-xs) var(--color-bg-container-border);
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: box-shadow var(--motion-duration-base) var(--motion-ease-standard);
+}
+
+/* Sizes */
+
+.ds-swatch--compact {
+  width: 20px;
+  height: 20px;
+}
+
+/* Shapes */
+
+.ds-swatch--square {
+  border-radius: var(--radius-sm);
+}
+
+/* States */
+
+.ds-swatch--selected {
+  box-shadow:
+    inset 0 0 0 var(--border-xs) var(--color-bg-container-border),
+    0 0 0 var(--border-md) var(--color-bg-page-primary),
+    0 0 0 calc(var(--border-md) * 2) var(--color-text-primary);
+}
+
+.ds-swatch:focus-visible {
+  outline: var(--border-md) solid var(--color-input-border-selected);
+  outline-offset: var(--border-md);
+}
+
+.ds-swatch--disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}

package/components/Swatch/Swatch.d.ts

@@ -0,0 +1,34 @@
+import { default as React } from 'react';
+/** Props owned by Swatch itself — everything else falls through to the <button>. */
+type SwatchOwnProps = {
+    /** The colour this swatch shows — any valid CSS colour, typically a hex value */
+    value: string;
+    /**
+     * Accessible name for the swatch. Defaults to the colour value, which is
+     * meaningful but terse — prefer a human name ("Teal 07") when you have one.
+     */
+    label?: string;
+    /** Selected state — renders the selection ring and sets aria-pressed */
+    selected?: boolean;
+    /** Swatch size */
+    size?: 'default' | 'compact';
+    /** Corner treatment — circle matches the site's preset grids; square suits picker triggers */
+    shape?: 'circle' | 'square';
+    /** Whether the swatch is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface SwatchProps extends SwatchOwnProps, Omit<React.ComponentPropsWithoutRef<'button'>, keyof SwatchOwnProps | 'type'> {
+}
+/**
+ * A clickable colour tile — the building block for preset palettes and
+ * picker triggers. Renders a `<button>` whose background is the `value`
+ * colour; `selected` draws the theme-aware selection ring.
+ *
+ * Purely presentational (no hooks), so it can be rendered from a Server
+ * Component; interactivity arrives through the native `onClick` you pass.
+ * Forwards a ref to the `<button>` and spreads unrecognised props onto it.
+ */
+export declare const Swatch: React.ForwardRefExoticComponent<SwatchProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/components/Swatch/Swatch.js

@@ -0,0 +1,44 @@
+import { jsx } from "react/jsx-runtime";
+import React from "react";
+import "./Swatch.css";
+const Swatch = React.forwardRef(
+  ({
+    value,
+    label,
+    selected = false,
+    size = "default",
+    shape = "circle",
+    disabled = false,
+    className = "",
+    style,
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-swatch";
+    const classes = [
+      baseClass,
+      size === "compact" ? `${baseClass}--compact` : "",
+      shape === "square" ? `${baseClass}--square` : "",
+      selected ? `${baseClass}--selected` : "",
+      disabled ? `${baseClass}--disabled` : "",
+      className
+    ].filter(Boolean).join(" ");
+    const swatchStyle = { ...style, "--ds-swatch-color": value };
+    return /* @__PURE__ */ jsx(
+      "button",
+      {
+        ...rest,
+        ref,
+        type: "button",
+        className: classes,
+        style: swatchStyle,
+        disabled,
+        "aria-pressed": selected,
+        "aria-label": rest["aria-label"] ?? label ?? value
+      }
+    );
+  }
+);
+Swatch.displayName = "Swatch";
+export {
+  Swatch
+};

package/components/Table/Table.css

@@ -184,3 +184,22 @@
   line-height: var(--font-paragraph-sm-line-height);
   letter-spacing: var(--font-paragraph-sm-letter-spacing);
 }
+
+/* ============================================
+   SCREEN-READER-ONLY
+   Fallback text for header cells with no visible
+   label (checkbox / actions columns) — an empty
+   <th> is unannounced.
+   ============================================ */
+
+.ds-table__sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/components/Table/Table.js

@@ -38,7 +38,7 @@ const Table = React.forwardRef(
             width: col.width,
             textAlign: col.align || "left"
           },
-          children: col.header
+          children: col.header || /* @__PURE__ */ jsx("span", { className: `${baseClass}__sr-only`, children: col.key })
         },
         col.key
       )) }) }),

package/components/Textarea/Textarea.css

@@ -14,19 +14,6 @@
    LABEL
    ============================================ */
 
-.ds-textarea__label {
-  font-family: var(--font-paragraph-em-family);
-  font-size: var(--font-paragraph-em-size);
-  font-weight: var(--font-paragraph-em-weight);
-  line-height: var(--font-paragraph-em-line-height);
-  letter-spacing: var(--font-paragraph-em-letter-spacing);
-  color: var(--color-text-primary);
-}
-
-.ds-textarea__required {
-  color: var(--color-core-accent-coral);
-}
-
 /* ============================================
    FIELD
    ============================================ */
@@ -69,24 +56,6 @@
    FOOTER (helper + counter)
    ============================================ */
 
-.ds-textarea__footer {
-  display: flex;
-  align-items: flex-start;
-  justify-content: space-between;
-  gap: var(--gap-sm);
-}
-
-.ds-textarea__helper {
-  font-family: var(--font-paragraph-sm-family);
-  font-size: var(--font-paragraph-sm-size);
-  font-weight: var(--font-paragraph-sm-weight);
-  line-height: var(--font-paragraph-sm-line-height);
-  letter-spacing: var(--font-paragraph-sm-letter-spacing);
-  color: var(--color-text-tertiary);
-  margin: 0;
-  flex: 1;
-}
-
 .ds-textarea__counter {
   font-family: var(--font-paragraph-sm-family);
   font-size: var(--font-paragraph-sm-size);
@@ -108,10 +77,6 @@
   border-color: var(--color-status-error-border);
 }
 
-.ds-textarea--error .ds-textarea__helper {
-  color: var(--color-status-error-border);
-}
-
 .ds-textarea--error .ds-textarea__counter {
   color: var(--color-status-error-border);
 }
@@ -120,10 +85,6 @@
    DISABLED STATE
    ============================================ */
 
-.ds-textarea--disabled .ds-textarea__label {
-  color: var(--color-input-text-disabled);
-}
-
 .ds-textarea--disabled .ds-textarea__field {
   background-color: var(--color-input-bg-disabled);
   border-color: var(--color-input-border-disabled);
@@ -146,7 +107,3 @@
   letter-spacing: var(--font-paragraph-sm-letter-spacing);
 }
 
-.ds-textarea--compact .ds-textarea__label {
-  font-size: var(--font-paragraph-sm-size);
-  line-height: var(--font-paragraph-sm-line-height);
-}

package/components/Textarea/Textarea.js

@@ -1,5 +1,6 @@
-import { jsxs, jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import React from "react";
+import { Field } from "../Field/Field.js";
 import "./Textarea.css";
 const Textarea = React.forwardRef(
   ({
@@ -37,44 +38,45 @@ const Textarea = React.forwardRef(
     };
     const inputId = id || name || label?.toLowerCase().replace(/\s+/g, "-");
     const charCount = value?.length || 0;
-    return /* @__PURE__ */ jsxs("div", { className: classes, children: [
-      label && /* @__PURE__ */ jsxs("label", { className: `${baseClass}__label`, htmlFor: inputId, children: [
+    return /* @__PURE__ */ jsx(
+      Field,
+      {
+        className: classes,
         label,
-        required && /* @__PURE__ */ jsxs("span", { className: `${baseClass}__required`, "aria-hidden": "true", children: [
-          " ",
-          "*"
-        ] })
-      ] }),
-      /* @__PURE__ */ jsx(
-        "textarea",
-        {
-          ...rest,
-          ref,
-          className: `${baseClass}__field`,
-          id: inputId,
-          name,
-          value,
-          placeholder,
-          rows,
-          disabled,
-          required,
-          maxLength,
-          "aria-label": ariaLabel || rest["aria-label"] || label,
-          "aria-invalid": error,
-          "aria-describedby": helperText ? `${inputId}-helper` : rest["aria-describedby"],
-          onChange: handleChange,
-          style: { resize, ...style }
-        }
-      ),
-      /* @__PURE__ */ jsxs("div", { className: `${baseClass}__footer`, children: [
-        helperText && /* @__PURE__ */ jsx("p", { className: `${baseClass}__helper`, id: `${inputId}-helper`, children: helperText }),
-        maxLength && /* @__PURE__ */ jsxs("span", { className: `${baseClass}__counter`, "aria-live": "polite", "aria-atomic": "true", children: [
+        helperText,
+        error,
+        required,
+        disabled,
+        size,
+        id: inputId,
+        aside: maxLength ? /* @__PURE__ */ jsxs("span", { className: `${baseClass}__counter`, "aria-live": "polite", "aria-atomic": "true", children: [
           charCount,
           "/",
           maxLength
-        ] })
-      ] })
-    ] });
+        ] }) : void 0,
+        children: /* @__PURE__ */ jsx(
+          "textarea",
+          {
+            ...rest,
+            ref,
+            className: `${baseClass}__field`,
+            id: inputId,
+            name,
+            value,
+            placeholder,
+            rows,
+            disabled,
+            required,
+            maxLength,
+            "aria-label": ariaLabel || rest["aria-label"] || label,
+            "aria-invalid": error,
+            "aria-describedby": helperText ? `${inputId}-helper` : rest["aria-describedby"],
+            onChange: handleChange,
+            style: { resize, ...style }
+          }
+        )
+      }
+    );
   }
 );
 Textarea.displayName = "Textarea";

package/components/ToggleSwitch/ToggleSwitch.css

@@ -59,7 +59,10 @@
      Set via --icon-size (not font-size): .material-symbols-rounded derives
      font-size, width, and height from it together. Overriding font-size
      alone leaves the box at the 24px default, so the glyph hangs off-centre
-     inside the thumb. */
+     inside the thumb.
+
+     ds-allow(icon-size): 14px glyph inside the 20px thumb — the smallest
+     scale step would fill it edge to edge. */
   --icon-size: 14px;
   color: var(--color-action-primary-bg);
 }
@@ -123,7 +126,9 @@
 
 .ds-toggle-switch--compact .ds-toggle-switch__thumb-icon {
   /* Off-scale for the same reason as the default size — the compact thumb
-     is only 16x16. */
+     is only 16x16.
+
+     ds-allow(icon-size): 12px glyph inside the 16px compact thumb. */
   --icon-size: 12px;
 }
 

package/components/registry.d.ts

@@ -1,19 +1,56 @@
 /**
- * COMPONENT REGISTRY — the single source of truth for the public
- * component count.
+ * COMPONENT REGISTRY — the single source of truth for the public component
+ * list, count, and per-component metadata.
+ *
+ * The data lives in registry.json. Each entry in `components` carries:
+ *
+ *   name        the folder under src/components (also the exported name)
+ *   label       the display name — "Navigation" for the Nav folder
+ *   slug        the website route segment — stored, not derived, so the
+ *               Nav → navigation exception is plain data rather than a
+ *               special case duplicated across validators
+ *   description one line, used for the page title, the sidebar search index,
+ *               and anywhere the component is summarised
+ *   category    one of `componentCategories`
+ *   client      whether the component declares 'use client' — i.e. whether it
+ *               uses hooks or defines handlers. Presentational components are
+ *               deliberately false so consumers can render them from a React
+ *               Server Component.
  *
- * The data lives in registry.json: `components` is the official list of
- * public components (one entry per folder in src/components), and
  * `docOnlyHelpers` names the internal documentation helpers that are
  * deliberately excluded from the public count.
  *
- * scripts/validate-component-registry.mjs compares the registry against
- * the filesystem on every build (library, Storybook, and website), so
- * the registry cannot silently drift from reality.
+ * scripts/validate-component-registry.mjs compares the registry against the
+ * filesystem on every build (library, Storybook, and website), so it cannot
+ * silently drift from reality.
+ *
+ * Anywhere a component count is displayed — the Storybook overview, the
+ * website mega-nav, case studies — import COMPONENT_COUNT from here. Never
+ * hardcode the number.
+ */
+export interface ComponentMeta {
+    /** Folder under src/components, and the exported component name */
+    name: string;
+    /** Display name — may differ from `name` (Nav → "Navigation") */
+    label: string;
+    /** Website route segment under /components */
+    slug: string;
+    /** One-line summary, used for page titles and search */
+    description: string;
+    /** Grouping — one of `componentCategories` */
+    category: string;
+    /** Whether the component declares 'use client' */
+    client: boolean;
+}
+/** Full metadata for every public component, alphabetical by name. */
+export declare const componentMetadata: readonly ComponentMeta[];
+/** The categories a component may belong to. */
+export declare const componentCategories: readonly string[];
+/**
+ * The official public component list, names only.
  *
- * Anywhere a component count is displayed — the Storybook overview,
- * the website mega-nav, case studies — import COMPONENT_COUNT from
- * here. Never hardcode the number.
+ * Unchanged in shape from before the metadata migration, so every existing
+ * consumer keeps working without an edit.
  */
 export declare const componentRegistry: readonly string[];
 /** The official public component count. */

package/components/registry.js

@@ -1,7 +1,11 @@
 import registry from "./registry.json.js";
-const componentRegistry = registry.components;
+const componentMetadata = registry.components;
+const componentCategories = registry.categories;
+const componentRegistry = registry.components.map((c) => c.name);
 const COMPONENT_COUNT = registry.components.length;
 export {
   COMPONENT_COUNT,
+  componentCategories,
+  componentMetadata,
   componentRegistry
 };