@robr0/design-system 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,9 @@
 # robr0 — Portfolio + Design System
 
 [![CI](https://github.com/robritacca-dotcom/design-system/actions/workflows/ci.yml/badge.svg)](https://github.com/robritacca-dotcom/design-system/actions/workflows/ci.yml)
+<!-- npm-badge:start -->
+[![npm](https://img.shields.io/npm/v/@robr0%2Fdesign-system?logo=npm&color=CB3837)](https://www.npmjs.com/package/@robr0/design-system)
+<!-- npm-badge:end -->
 
 A personal portfolio site built on a custom React design system I designed and engineered from scratch. The DS isn't a side project — it's the backbone every portfolio page is built on, ensuring the work is presented consistently and with the same craft standards I apply professionally.
 
@@ -107,7 +110,7 @@ Full spec in [`design.md`](design.md).
 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:
 
 ```bash
-npm run verify   # lint + library build + story tests + Storybook build + website build
+npm run verify   # lint + library type-check + package build + story tests + Storybook build + website 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.
@@ -120,8 +123,7 @@ CI also guards against documentation drift: generated surfaces (this README's co
 # Storybook (the library's dev sandbox)
 npm run storybook        # http://localhost:6006
 
-# Portfolio + documentation website
-cd website
+# Portfolio + documentation website (npm workspace — install once at the root)
 npm install
-npm run dev              # http://localhost:3000
+npm run dev --workspace website   # http://localhost:3000
 ```

package/components/Breadcrumb/Breadcrumb.css

@@ -74,8 +74,16 @@
    SEPARATOR
    ============================================ */
 
+/*
+   Size via --icon-size, never font-size: .material-symbols-rounded derives
+   the glyph size AND the layout box from that one variable. Setting
+   font-size alone shrank the glyph but left a 24px box around it, so the
+   chevron floated above the text baseline. --icon-size-sm (20px) also
+   matches the 20px line-height of the paragraph-sm labels either side.
+*/
 .ds-breadcrumb__separator {
-  font-size: 18px;
+  --icon-size: var(--icon-size-sm);
+  flex: none;
   color: var(--color-text-tertiary);
   user-select: none;
 }

package/components/Button/Button.d.ts

@@ -1,21 +1,18 @@
 import { default as React } from 'react';
-export interface ButtonProps {
+/** Props owned by Button itself — everything else falls through to the DOM node. */
+type ButtonOwnProps = {
     /** Button text content */
     label?: string;
     /** Icon for left side — Material Symbol name (string) or custom element (ReactNode) */
     iconLeft?: string | React.ReactNode;
     /** Icon for right side — Material Symbol name (string) or custom element (ReactNode) */
     iconRight?: string | React.ReactNode;
-    /** Button priority/variant */
-    priority?: 'primary' | 'secondary' | 'tertiary' | 'destructive';
-    /** Button state */
-    state?: 'default' | 'hover' | 'active' | 'disabled';
+    /** Visual treatment */
+    variant?: 'primary' | 'secondary' | 'tertiary' | 'destructive';
     /** Button size */
     size?: 'default' | 'compact';
-    /** Show text label */
-    text?: boolean;
-    /** Optional click handler */
-    onClick?: () => void;
+    /** Whether the button is disabled */
+    disabled?: boolean;
     /** Optional href — renders as <a> instead of <button> */
     href?: string;
     /** Optional target attribute for links */
@@ -24,16 +21,35 @@ export interface ButtonProps {
     rel?: string;
     /** Marks this link as the current page (adds aria-current="page") */
     ariaCurrent?: boolean;
-    /** Id of an element describing this button — set automatically by Tooltip */
-    'aria-describedby'?: string;
     /** Additional CSS classes */
     className?: string;
-    /** @deprecated Use iconLeft instead */
+    /** @deprecated Use `variant` instead. */
+    priority?: 'primary' | 'secondary' | 'tertiary' | 'destructive';
+    /**
+     * @deprecated Use `disabled` for the disabled state.
+     *
+     * Documentation-only affordance for rendering a *static* interaction state in
+     * Storybook and the showcase site. Real hover/active styling comes from CSS
+     * pseudo-classes and needs no prop — for docs, prefer `className="ds-button--hover"`.
+     */
+    state?: 'default' | 'hover' | 'active' | 'disabled';
+    /** @deprecated Use `iconLeft` instead. */
     icon?: string;
+    /**
+     * @deprecated Will be removed once `label` loses its default in the next major;
+     * an icon-only button will simply omit `label`.
+     */
+    text?: boolean;
+};
+export interface ButtonProps extends ButtonOwnProps, Omit<React.ComponentPropsWithoutRef<'button'>, keyof ButtonOwnProps | 'type'> {
 }
 /**
- * Button component from Figma design system
- * Supports primary and secondary variants with multiple states
- * Icons can be placed on the left and/or right side of the text
+ * Button component from Figma design system.
+ * Supports primary, secondary, tertiary and destructive variants.
+ * Icons can be placed on the left and/or right side of the text.
+ *
+ * Renders a `<button>`, or an `<a>` when `href` is supplied. Forwards a ref to
+ * whichever element it renders, and spreads unrecognised props onto it.
  */
-export declare const Button: ({ label, iconLeft, iconRight, priority, state, size, text, onClick, href, target, rel, ariaCurrent, "aria-describedby": ariaDescribedby, className, icon, }: ButtonProps) => React.JSX.Element;
+export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+export {};

package/components/Button/Button.js

@@ -1,71 +1,79 @@
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
-import "react";
+import React from "react";
 import "./Button.css";
 import "../../fonts/material-symbols.css";
-const Button = ({
-  label = "Button",
-  iconLeft,
-  iconRight,
-  priority = "primary",
-  state = "default",
-  size = "default",
-  text = true,
-  onClick,
-  href,
-  target,
-  rel,
-  ariaCurrent,
-  "aria-describedby": ariaDescribedby,
-  className = "",
-  icon
-  // deprecated, maps to iconLeft for backwards compatibility
-}) => {
-  const baseClass = "ds-button";
-  const variantClass = `${baseClass}--${priority}`;
-  const stateClass = `${baseClass}--${state}`;
-  const sizeClass = `${baseClass}--${size}`;
-  const classes = [baseClass, variantClass, stateClass, sizeClass, className].filter(Boolean).join(" ");
-  const isDisabled = state === "disabled";
-  const iconClass = "material-symbols-rounded";
-  const leftIcon = iconLeft || icon;
-  const renderIcon = (iconProp) => {
-    if (typeof iconProp === "string") {
-      return /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon ${iconClass}`, "aria-hidden": "true", children: iconProp });
+const Button = React.forwardRef(
+  ({
+    label = "Button",
+    iconLeft,
+    iconRight,
+    variant,
+    size = "default",
+    disabled,
+    href,
+    target,
+    rel,
+    ariaCurrent,
+    className = "",
+    priority,
+    state,
+    icon,
+    text = true,
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-button";
+    const resolvedVariant = variant ?? priority ?? "primary";
+    const isDisabled = disabled ?? state === "disabled";
+    const resolvedState = state ?? (isDisabled ? "disabled" : "default");
+    const classes = [
+      baseClass,
+      `${baseClass}--${resolvedVariant}`,
+      `${baseClass}--${resolvedState}`,
+      `${baseClass}--${size}`,
+      className
+    ].filter(Boolean).join(" ");
+    const iconClass = "material-symbols-rounded";
+    const leftIcon = 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 content = /* @__PURE__ */ jsxs(Fragment, { children: [
+      leftIcon && renderIcon(leftIcon),
+      text && /* @__PURE__ */ jsx("span", { className: `${baseClass}__text`, children: label }),
+      iconRight && renderIcon(iconRight)
+    ] });
+    if (href && !isDisabled) {
+      return /* @__PURE__ */ jsx(
+        "a",
+        {
+          ...rest,
+          ref,
+          className: classes,
+          href,
+          target,
+          rel,
+          "aria-current": ariaCurrent ? "page" : void 0,
+          children: content
+        }
+      );
     }
-    return /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon`, "aria-hidden": "true", children: iconProp });
-  };
-  const children = /* @__PURE__ */ jsxs(Fragment, { children: [
-    leftIcon && renderIcon(leftIcon),
-    text && /* @__PURE__ */ jsx("span", { className: `${baseClass}__text`, children: label }),
-    iconRight && renderIcon(iconRight)
-  ] });
-  if (href && !isDisabled) {
     return /* @__PURE__ */ jsx(
-      "a",
+      "button",
       {
+        ...rest,
+        ref,
+        type: "button",
         className: classes,
-        href,
-        target,
-        rel,
-        "aria-current": ariaCurrent ? "page" : void 0,
-        "aria-describedby": ariaDescribedby,
-        onClick,
-        children
+        disabled: isDisabled,
+        children: content
       }
     );
   }
-  return /* @__PURE__ */ jsx(
-    "button",
-    {
-      type: "button",
-      className: classes,
-      onClick,
-      disabled: isDisabled,
-      "aria-describedby": ariaDescribedby,
-      children
-    }
-  );
-};
+);
+Button.displayName = "Button";
 export {
   Button
 };

package/components/Card/Card.d.ts

@@ -1,15 +1,17 @@
 import { default as React } from 'react';
-export interface CardProps {
+/** Props owned by Card itself — everything else falls through to the DOM node. */
+type CardOwnProps = {
     /** Card variant */
     variant?: 'default' | 'case-study';
-    /** Card title displayed below the preview */
+    /**
+     * Card title displayed below the preview.
+     * Note: this shadows the native `title` tooltip attribute, which Card does not expose.
+     */
     title: string;
     /** Preview content rendered inside the card (default variant only) */
     children?: React.ReactNode;
     /** Whether the card is interactive (hoverable) */
     interactive?: boolean;
-    /** Click handler */
-    onClick?: () => void;
     /** Additional CSS classes */
     className?: string;
     /** Navigation href — renders the card as an <a> tag */
@@ -26,5 +28,15 @@ export interface CardProps {
     dek?: string;
     /** Render as a disabled placeholder (no href, dimmed, not interactive) */
     placeholder?: boolean;
+};
+export interface CardProps extends CardOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof CardOwnProps> {
 }
-export declare const Card: ({ variant, title, children, interactive, onClick, className, href, coverSrc, coverAlt, companyLogo, companyName, dek, placeholder, }: CardProps) => React.JSX.Element;
+/**
+ * Card renders a preview tile, or a case-study tile when `variant="case-study"`.
+ *
+ * Renders a `<div>`, or an `<a>` in the case-study variant when `href` is
+ * supplied. Forwards a ref to whichever element it renders and spreads
+ * unrecognised props onto it.
+ */
+export declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement | HTMLAnchorElement>>;
+export {};

package/components/Card/Card.js

@@ -1,90 +1,111 @@
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
-import "react";
+import React from "react";
 import "./Card.css";
 import "../../fonts/material-symbols.css";
-const Card = ({
-  variant = "default",
-  title,
-  children,
-  interactive = false,
-  onClick,
-  className = "",
-  href,
-  coverSrc,
-  coverAlt,
-  companyLogo,
-  companyName,
-  dek,
-  placeholder = false
-}) => {
-  if (variant === "case-study") {
-    const inner = /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-wrap", children: coverSrc ? /* @__PURE__ */ jsx(
-        "img",
+const Card = React.forwardRef(
+  ({
+    variant = "default",
+    title,
+    children,
+    interactive = false,
+    onClick,
+    onKeyDown,
+    className = "",
+    href,
+    coverSrc,
+    coverAlt,
+    companyLogo,
+    companyName,
+    dek,
+    placeholder = false,
+    ...rest
+  }, ref) => {
+    if (variant === "case-study") {
+      const inner = /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-wrap", children: coverSrc ? /* @__PURE__ */ jsx(
+          "img",
+          {
+            src: coverSrc,
+            alt: coverAlt ?? `${title} cover`,
+            className: "ds-card--case-study__cover-image"
+          }
+        ) : /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-placeholder", children: companyLogo && /* @__PURE__ */ jsx(
+          "img",
+          {
+            src: companyLogo,
+            alt: "",
+            className: "ds-card--case-study__cover-placeholder-logo"
+          }
+        ) }) }),
+        /* @__PURE__ */ jsxs("div", { className: "ds-card--case-study__body", children: [
+          (companyLogo || companyName) && /* @__PURE__ */ jsxs("div", { className: "ds-card--case-study__eyebrow", children: [
+            companyLogo && /* @__PURE__ */ jsx("img", { src: companyLogo, alt: "", className: "ds-card--case-study__company-logo" }),
+            companyName && /* @__PURE__ */ jsx("span", { className: "ds-card--case-study__company-name", children: companyName })
+          ] }),
+          /* @__PURE__ */ jsx("h3", { className: "ds-card--case-study__title", children: title }),
+          dek && /* @__PURE__ */ jsx("p", { className: "ds-card--case-study__dek", children: dek })
+        ] })
+      ] });
+      const classes2 = [
+        "ds-card",
+        "ds-card--case-study",
+        placeholder ? "ds-card--case-study--placeholder" : "",
+        className
+      ].filter(Boolean).join(" ");
+      if (placeholder || !href) {
+        return /* @__PURE__ */ jsx(
+          "div",
+          {
+            ...rest,
+            ref,
+            className: classes2,
+            "aria-disabled": "true",
+            children: inner
+          }
+        );
+      }
+      return /* @__PURE__ */ jsx(
+        "a",
         {
-          src: coverSrc,
-          alt: coverAlt ?? `${title} cover`,
-          className: "ds-card--case-study__cover-image"
+          ...rest,
+          ref,
+          href,
+          className: classes2,
+          onClick,
+          children: inner
         }
-      ) : /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-placeholder", children: companyLogo && /* @__PURE__ */ jsx(
-        "img",
-        {
-          src: companyLogo,
-          alt: "",
-          className: "ds-card--case-study__cover-placeholder-logo"
-        }
-      ) }) }),
-      /* @__PURE__ */ jsxs("div", { className: "ds-card--case-study__body", children: [
-        (companyLogo || companyName) && /* @__PURE__ */ jsxs("div", { className: "ds-card--case-study__eyebrow", children: [
-          companyLogo && /* @__PURE__ */ jsx(
-            "img",
-            {
-              src: companyLogo,
-              alt: "",
-              className: "ds-card--case-study__company-logo"
-            }
-          ),
-          companyName && /* @__PURE__ */ jsx("span", { className: "ds-card--case-study__company-name", children: companyName })
-        ] }),
-        /* @__PURE__ */ jsx("h3", { className: "ds-card--case-study__title", children: title }),
-        dek && /* @__PURE__ */ jsx("p", { className: "ds-card--case-study__dek", children: dek })
-      ] })
-    ] });
-    const classes2 = [
-      "ds-card",
-      "ds-card--case-study",
-      placeholder ? "ds-card--case-study--placeholder" : "",
-      className
-    ].filter(Boolean).join(" ");
-    if (placeholder || !href) {
-      return /* @__PURE__ */ jsx("div", { className: classes2, "aria-disabled": "true", children: inner });
+      );
     }
-    return /* @__PURE__ */ jsx("a", { href, className: classes2, children: inner });
+    const baseClass = "ds-card";
+    const classes = [baseClass, interactive ? `${baseClass}--interactive` : "", className].filter(Boolean).join(" ");
+    const handleKeyDown = (e) => {
+      onKeyDown?.(e);
+      if (!interactive) return;
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        onClick?.(e);
+      }
+    };
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...rest,
+        ref,
+        className: classes,
+        onClick: interactive ? onClick : void 0,
+        onKeyDown: handleKeyDown,
+        role: interactive ? "button" : void 0,
+        tabIndex: interactive ? 0 : void 0,
+        "aria-label": interactive ? title : void 0,
+        children: [
+          /* @__PURE__ */ jsx("div", { className: `${baseClass}__preview`, children }),
+          /* @__PURE__ */ jsx("h3", { className: `${baseClass}__title`, children: title })
+        ]
+      }
+    );
   }
-  const baseClass = "ds-card";
-  const interactiveClass = interactive ? `${baseClass}--interactive` : "";
-  const classes = [baseClass, interactiveClass, className].filter(Boolean).join(" ");
-  return /* @__PURE__ */ jsxs(
-    "div",
-    {
-      className: classes,
-      onClick: interactive ? onClick : void 0,
-      onKeyDown: interactive ? (e) => {
-        if (e.key === "Enter" || e.key === " ") {
-          e.preventDefault();
-          onClick?.();
-        }
-      } : void 0,
-      role: interactive ? "button" : void 0,
-      tabIndex: interactive ? 0 : void 0,
-      "aria-label": interactive ? title : void 0,
-      children: [
-        /* @__PURE__ */ jsx("div", { className: `${baseClass}__preview`, children }),
-        /* @__PURE__ */ jsx("h3", { className: `${baseClass}__title`, children: title })
-      ]
-    }
-  );
-};
+);
+Card.displayName = "Card";
 export {
   Card
 };

package/components/Checkbox/Checkbox.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
-export interface CheckboxProps {
+/** Props owned by Checkbox itself — everything else falls through to the wrapper. */
+type CheckboxOwnProps = {
     /** Label text */
     label?: string;
     /** Whether the checkbox is checked */
@@ -10,18 +11,25 @@ export interface CheckboxProps {
     disabled?: boolean;
     /** Component size */
     size?: 'default' | 'compact';
-    /** Callback when toggled */
-    onChange?: (checked: boolean) => void;
+    /** Called with the next checked state when toggled */
+    onCheckedChange?: (checked: boolean) => void;
     /** Additional CSS classes */
     className?: string;
-    /** Accessible label override */
+    /** @deprecated Use `onCheckedChange` instead. */
+    onChange?: (checked: boolean) => void;
+    /** @deprecated Pass the native `aria-label` attribute instead. */
     ariaLabel?: string;
-    /** HTML name attribute */
+    /**
+     * @deprecated No-op. This component renders a `<div role="checkbox">`, not a
+     * native `<input>`, so it cannot participate in native form submission.
+     * Declared only so the attribute is not forwarded to an element that rejects it.
+     */
     name?: string;
-    /** HTML id attribute */
-    id?: string;
+};
+export interface CheckboxProps extends CheckboxOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof CheckboxOwnProps> {
 }
-export interface CheckboxGroupProps {
+export declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLDivElement>>;
+type CheckboxGroupOwnProps = {
     /** Group label */
     label?: string;
     /** Checkbox options */
@@ -36,10 +44,14 @@ export interface CheckboxGroupProps {
     direction?: 'vertical' | 'horizontal';
     /** Component size */
     size?: 'default' | 'compact';
-    /** Callback when selection changes */
-    onChange?: (values: string[]) => void;
+    /** Called with the next selected values */
+    onValuesChange?: (values: string[]) => void;
     /** Additional CSS classes */
     className?: string;
+    /** @deprecated Use `onValuesChange` instead. */
+    onChange?: (values: string[]) => void;
+};
+export interface CheckboxGroupProps extends CheckboxGroupOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof CheckboxGroupOwnProps> {
 }
-export declare const CheckboxGroup: ({ label, items, values, direction, size, onChange, className, }: CheckboxGroupProps) => React.JSX.Element;
-export declare const Checkbox: ({ label, checked, indeterminate, disabled, size, onChange, className, ariaLabel, }: CheckboxProps) => React.JSX.Element;
+export declare const CheckboxGroup: React.ForwardRefExoticComponent<CheckboxGroupProps & React.RefAttributes<HTMLDivElement>>;
+export {};