@mich8060/unified-design-system 0.1.10

package/src/ui/Button/Button.ai.md

@@ -0,0 +1,122 @@
+# Button
+
+Primary action trigger component supporting multiple visual styles, sizes, and icon layouts.
+
+## When to Use
+- Triggering actions (submit, save, delete, navigate)
+- Primary CTA buttons, secondary actions, destructive confirmations
+- Icon-only actions in toolbars or compact UIs
+
+## Props
+
+| Prop | Type | Default | Values | Description |
+|------|------|---------|--------|-------------|
+| `label` | `string` | — | Any text | Button text label |
+| `appearance` | `string` | `"primary"` | `"primary"`, `"soft"`, `"outline"`, `"text"`, `"ghost"`, `"disabled"`, `"destructive"` | Visual style variant |
+| `layout` | `string` | `"label-only"` | `"label-only"`, `"icon-left"`, `"icon-right"`, `"icon-only"`, `"only"` | Content arrangement |
+| `size` | `string` | `"default"` | `"large"`, `"default"`, `"small"`, `"xsmall"` | Button size |
+| `icon` | `string` or `ReactNode` | — | Phosphor icon name (e.g., `"ArrowRight"`, `"Plus"`, `"Trash"`) or JSX | Icon to display |
+| `iconSize` | `number` | — | Any number | Override icon size in px |
+| `className` | `string` | `""` | Any CSS class | Additional CSS classes |
+| `tracking` | `string` or `object` | — | `"event-name"` or `{ event, category, ... }` | Fires a `uds:track` CustomEvent on click with a structured payload |
+| `onClick` | `function` | — | — | Click handler |
+| `disabled` | `boolean` | `false` | — | Disables the button |
+| `aria-label` | `string` | — | — | Accessible label (auto-generated for icon-only) |
+
+## Examples
+
+### Basic buttons
+```jsx
+<Button label="Save" />
+<Button label="Cancel" appearance="outline" />
+<Button label="Delete" appearance="destructive" />
+```
+
+### With icons
+```jsx
+<Button label="Add Item" icon="Plus" layout="icon-left" />
+<Button label="Next" icon="ArrowRight" layout="icon-right" />
+<Button icon="Trash" layout="icon-only" aria-label="Delete item" />
+```
+
+### Size variants
+```jsx
+<Button label="Large" size="large" />
+<Button label="Default" />
+<Button label="Small" size="small" />
+<Button label="XSmall" size="xsmall" />
+```
+
+### All appearances
+```jsx
+<Button label="Primary" appearance="primary" />
+<Button label="Soft" appearance="soft" />
+<Button label="Outline" appearance="outline" />
+<Button label="Text" appearance="text" />
+<Button label="Ghost" appearance="ghost" />
+<Button label="Destructive" appearance="destructive" />
+<Button label="Disabled" appearance="disabled" />
+```
+
+### Action bar pattern
+```jsx
+<Flex gap="8" justifyContent="flex-end">
+  <Button label="Cancel" appearance="outline" onClick={onCancel} />
+  <Button label="Save Changes" icon="FloppyDisk" layout="icon-left" onClick={onSave} />
+</Flex>
+```
+
+### Toolbar with icon-only buttons
+```jsx
+<Flex gap="4">
+  <Button icon="TextB" layout="icon-only" appearance="ghost" aria-label="Bold" />
+  <Button icon="TextItalic" layout="icon-only" appearance="ghost" aria-label="Italic" />
+  <Button icon="TextUnderline" layout="icon-only" appearance="ghost" aria-label="Underline" />
+</Flex>
+```
+
+### Data tracking
+```jsx
+// Simple string event name
+<Button label="Sign Up" tracking="signup-cta" onClick={handleSignUp} />
+
+// Rich payload — all fields are merged into the CustomEvent detail
+<Button
+  label="Add to Cart"
+  icon="ShoppingCart"
+  layout="icon-left"
+  tracking={{ event: "add_to_cart", category: "ecommerce", productId: "widget-123" }}
+  onClick={handleAddToCart}
+/>
+
+// Subscribe in your app root
+useEffect(() => {
+  const handler = (e) => analytics.track(e.detail.event ?? e.detail.action, e.detail);
+  window.addEventListener("uds:track", handler);
+  return () => window.removeEventListener("uds:track", handler);
+}, []);
+```
+
+## Composition
+
+- **In forms**: Place at the bottom of form sections, typically paired with a cancel button
+- **In `Card`**: Use in card footer for card-level actions
+- **In `UDS.PageHeader`**: Pass as `actions` prop for page-level actions
+- **In `Table` rows**: Use `size="xsmall"` or `"small"` with `appearance="ghost"` for inline row actions
+- **In `UDS.Modal` footer**: Primary + secondary action buttons
+
+## Do's and Don'ts
+
+✅ **Do**: Use `appearance="destructive"` for delete/remove actions
+✅ **Do**: Always provide `aria-label` for icon-only buttons
+✅ **Do**: Use `icon` prop with a Phosphor icon name string (e.g., `icon="Plus"`)
+✅ **Do**: Use `layout="icon-left"` for action buttons with context (e.g., "Add User")
+
+❌ **Don't**: Use `appearance="disabled"` for conditional disabling — use the `disabled` prop instead
+❌ **Don't**: Use `appearance="primary"` for every button — reserve for the main page action
+❌ **Don't**: Nest interactive elements inside Button
+
+## Accessibility
+- Icon-only buttons automatically get `aria-label` from the `label` prop or icon name
+- Disabled buttons use native `disabled` attribute
+- Renders as `<button type="button">` by default

package/src/ui/Button/Button.figma.tsx

@@ -0,0 +1,49 @@
+import React from "react"
+import Button from "./Button"
+import figma from "@figma/code-connect"
+
+/**
+ * -- This file was auto-generated by Code Connect --
+ * `props` includes a mapping from Figma properties and variants to
+ * suggested values. You should update this to match the props of your
+ * code component, and update the `example` function to return the
+ * code example you'd like to see in Figma
+ */
+
+figma.connect(
+    Button,
+    "https://www.figma.com/file/LkIyThUA0oVNsDEAyOF7ER/Design-System--Components?node-id=19%3A360",
+    {
+        props: {
+            label: figma.string("Label"),
+            appearance: figma.enum("Appearance", {
+                Primary: "primary",
+                Soft: "soft",
+                Disabled: "disabled",
+                Outline: "outline",
+                "Ghost+": "ghost-",
+                Destructive: "destructive",
+                Ghost: "ghost",
+            }),
+            layout: figma.enum("Layout", {
+                "Label Only": "label-only",
+                "Icon Right": "icon-right",
+                "Icon Left": "icon-left",
+                "Icon Only": "icon-only",
+            }),
+            state: figma.enum("State", {
+                Default: "default",
+                Focus: "focus",
+                Hover: "hover",
+            }),
+            size: figma.enum("Size", {
+                XSmall: "xsmall",
+                Large: "large",
+                Default: "default",
+                Small: "small",
+            }),
+            onDark: figma.boolean("On Dark"),
+        },
+        example: (props) => <Button />,
+    },
+)

package/src/ui/Button/Button.scss

@@ -0,0 +1,188 @@
+@use "../../styles/typography" as *;
+
+.uds-button {
+  all: unset;
+  @include uds-body-16-semibold;
+  align-items: center;
+  background: var(--uds-button-surface-primary-default);
+  border: var(--uds-border-width-1) solid var(--uds-button-border-primary-default);
+  border-radius: var(--uds-radius-4);
+  box-sizing: border-box;
+  color: var(--uds-button-text-default);
+  cursor: pointer;
+  display: inline-flex;
+  justify-content: center;
+  gap: var(--uds-gap-4);
+  height: fit-content;
+  padding-inline: var(--uds-spacing-16);
+  padding-block: var(--uds-spacing-10);
+  text-transform: capitalize;
+  width: fit-content;
+  transition: all var(--uds-animation-duration-200) var(--uds-animation-ease-standard);
+
+  &:hover:not(:disabled) {
+    background: var(--uds-button-surface-primary-hover);
+    border-color: var(--uds-button-border-primary-hover);
+    color: var(--uds-button-text-default);
+  }
+
+  &__icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    line-height: 0;
+
+    svg {
+      width: 20px;
+      height: 20px;
+      flex-shrink: 0;
+    }
+  }
+
+  &__label {
+    display: inline-block;
+    padding: 0 var(--uds-spacing-4);
+    white-space: nowrap;
+  }
+
+  &:focus-visible {
+    outline: solid var(--uds-focus-ring-width) var(--uds-focus-ring-border);
+    outline-offset: var(--uds-focus-ring-offset);
+  }
+
+  &.large {
+    @include uds-body-20-semibold;
+    padding: var(--uds-spacing-12) var(--uds-spacing-18);
+
+    .uds-button__icon svg {
+      width: 24px;
+      height: 24px;
+    }
+  }
+
+  &.small {
+    @include uds-body-14-semibold;
+    padding: var(--uds-spacing-8) var(--uds-spacing-12);
+
+    .uds-button__icon svg {
+      width: 16px;
+      height: 16px;
+    }
+  }
+
+  &.xsmall {
+    @include uds-body-12-semibold;
+    padding: var(--uds-spacing-8) var(--uds-spacing-10);
+
+    .uds-button__icon svg {
+      width: 16px;
+      height: 16px;
+    }
+  }
+
+  &.icon {
+    &-only {
+      padding: var(--uds-spacing-12);
+
+      &.large {
+        padding: var(--uds-spacing-14);
+
+        .uds-button__icon svg {
+          width: 24px;
+          height: 24px;
+        }
+      }
+
+      &.small {
+        padding: var(--uds-spacing-10);
+
+        .uds-button__icon svg {
+          width: 16px;
+          height: 16px;
+        }
+      }
+
+      &.xsmall {
+        padding: var(--uds-spacing-8);
+
+        .uds-button__icon svg {
+          width: 16px;
+          height: 16px;
+        }
+      }
+    }
+  }
+
+  &.soft {
+    background: var(--uds-button-surface-secondary-default);
+    border-color: var(--uds-button-border-secondary-default);
+    color: var(--uds-button-text-secondary);
+
+    &:hover:not(:disabled) {
+      background: var(--uds-button-surface-secondary-hover);
+      border-color: var(--uds-button-border-secondary-hover);
+      color: var(--uds-button-text-secondary);
+    }
+  }
+
+  &.outline {
+    background: var(--uds-color-transparent);
+    border: solid 1px var(--uds-border-primary);
+    color: var(--uds-text-primary);
+
+    &:hover:not(:disabled) {
+      background: var(--uds-color-transparent);
+      border-color: var(--uds-border-brand-primary);
+      color: var(--uds-text-primary);
+    }
+  }
+
+  &.text {
+    background: var(--uds-surface-transparent);
+    color: var(--uds-text-primary);
+    border-color: var(--uds-border-transparent);
+
+    &:hover:not(:disabled) {
+      background: var(--uds-surface-transparent);
+      color: var(--uds-text-brand-primary);
+      border-color: var(--uds-border-transparent);
+    }
+  }
+
+  &.ghost {
+    background: var(--uds-surface-transparent);
+    color: var(--uds-text-brand-primary);
+    border-color: var(--uds-border-transparent);
+
+    &:hover:not(:disabled) {
+      background: var(--uds-surface-transparent);
+      color: var(--uds-text-brand-primary);
+      border-color: var(--uds-border-transparent);
+    }
+  }
+
+  &.destructive {
+    background: var(--uds-button-surface-primary-destructive);
+    color: var(--uds-button-text-default);
+    border-color: var(--uds-button-border-primary-destructive);
+
+    &:hover:not(:disabled) {
+      background: var(--uds-button-surface-primary-destructive);
+      color: var(--uds-button-text-default);
+      border-color: var(--uds-button-border-primary-destructive);
+    }
+  }
+
+  &.disabled {
+    background: var(--uds-button-surface-primary-disabled);
+    color: var(--uds-button-text-disabled);
+    cursor: not-allowed;
+    border-color: var(--uds-button-border-primary-disabled);
+    box-shadow: none;
+    pointer-events: none;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+}

package/src/ui/Button/Button.spec.ts

@@ -0,0 +1,52 @@
+export const BUTTON_LAYOUTS = [
+  "label-only",
+  "icon-left",
+  "icon-right",
+  "icon-only",
+  "only",
+] as const;
+
+export const BUTTON_APPEARANCES = [
+  "primary",
+  "soft",
+  "outline",
+  "text",
+  "ghost",
+  "disabled",
+  "destructive",
+] as const;
+
+export const BUTTON_SIZES = ["large", "default", "small", "xsmall"] as const;
+
+export const BUTTON_DEFAULTS = {
+  appearance: "primary",
+  layout: "label-only",
+  size: "default",
+} as const;
+
+export const BUTTON_CLASS_MAP = {
+  layout: {
+    "label-only": "label-only",
+    "icon-left": "icon-left",
+    "icon-right": "icon-right",
+    "icon-only": "icon-only",
+    only: "only",
+  } as const,
+  appearance: {
+    primary: "primary",
+    soft: "soft",
+    outline: "outline",
+    text: "text",
+    ghost: "ghost",
+    disabled: "disabled",
+    destructive: "destructive",
+  } as const,
+  size: {
+    large: "large",
+    default: "default",
+    small: "small",
+    xsmall: "xsmall",
+  } as const,
+} as const;
+
+export const BUTTON_BASE_CLASS = "uds-button";

package/src/ui/Button/Button.stories.tsx

@@ -0,0 +1,199 @@
+import Button from "./Button";
+import { createStoryArgsFromSpec } from "../_spec/createStoryArgsFromSpec";
+import {
+  BUTTON_APPEARANCES,
+  BUTTON_DEFAULTS,
+  BUTTON_LAYOUTS,
+  BUTTON_SIZES,
+} from "./Button.spec";
+import type { StorySpec } from "../_spec/types";
+
+type ButtonStoryArgs = {
+  label: string;
+  icon?: string;
+  appearance: (typeof BUTTON_APPEARANCES)[number];
+  layout: (typeof BUTTON_LAYOUTS)[number];
+  size: (typeof BUTTON_SIZES)[number];
+  iconSize?: number;
+  disabled?: boolean;
+  tracking?: string | Record<string, unknown>;
+  "aria-label"?: string;
+};
+
+const BUTTON_DEFAULT_ARGS: ButtonStoryArgs = {
+  label: "Button",
+  icon: "Plus",
+  appearance: BUTTON_DEFAULTS.appearance,
+  layout: BUTTON_DEFAULTS.layout,
+  size: BUTTON_DEFAULTS.size,
+};
+
+const BUTTON_STORY_SPEC = {
+  defaults: BUTTON_DEFAULT_ARGS,
+  options: {
+    appearance: BUTTON_APPEARANCES,
+    layout: BUTTON_LAYOUTS,
+    size: BUTTON_SIZES,
+  },
+  stories: {
+    primary: { label: "Primary", appearance: "primary" },
+    soft: { label: "Soft", appearance: "soft" },
+    outline: { label: "Outline", appearance: "outline" },
+    text: { label: "Text", appearance: "text" },
+    ghost: { label: "Ghost", appearance: "ghost" },
+    destructive: { label: "Destructive", appearance: "destructive" },
+    disabled: { label: "Disabled", appearance: "disabled", disabled: true },
+    large: { label: "Large", size: "large" },
+    small: { label: "Small", size: "small" },
+    xsmall: { label: "XSmall", size: "xsmall" },
+    iconLeft: { label: "Add Item", icon: "Plus", layout: "icon-left" },
+    iconRight: { label: "Next", icon: "ArrowRight", layout: "icon-right" },
+    iconOnly: { icon: "Trash", layout: "icon-only", label: "", "aria-label": "Delete item" },
+    customIconSize: {
+      label: "Download",
+      icon: "DownloadSimple",
+      layout: "icon-left",
+      iconSize: 24,
+    },
+    trackingString: {
+      label: "Sign Up",
+      tracking: "signup-cta",
+    },
+    trackingObject: {
+      label: "Add to Cart",
+      icon: "ShoppingCart",
+      layout: "icon-left",
+      tracking: {
+        event: "add_to_cart",
+        category: "ecommerce",
+        productId: "widget-123",
+      },
+    },
+  } as const,
+} satisfies StorySpec<ButtonStoryArgs>;
+
+const fromSpec = createStoryArgsFromSpec<ButtonStoryArgs>(
+  BUTTON_STORY_SPEC.defaults,
+);
+
+export default {
+  title: "Components/Button",
+  component: Button,
+  tags: ["autodocs"],
+  args: BUTTON_STORY_SPEC.defaults,
+  argTypes: {
+    label: {
+      control: "text",
+      description: "Button text label",
+    },
+    tracking: {
+      control: "object",
+      description:
+        'Analytics payload — string or object. Fires a "uds:track" CustomEvent on click.',
+    },
+    icon: {
+      control: "text",
+      description: "Phosphor icon name (e.g. ArrowRight, Plus, Trash)",
+    },
+    iconSize: {
+      control: "number",
+      description: "Override icon size in px",
+    },
+    disabled: {
+      control: "boolean",
+      description: "Disables the button",
+    },
+    onClick: {
+      action: "clicked",
+      description: "Click handler",
+    },
+    appearance: {
+      control: "select",
+      options: [...BUTTON_APPEARANCES],
+      description: "Visual style variant",
+    },
+    layout: {
+      control: "select",
+      options: [...BUTTON_LAYOUTS],
+      description: "Content arrangement",
+    },
+    size: {
+      control: "select",
+      options: [...BUTTON_SIZES],
+      description: "Button size",
+    },
+  },
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export const Default = {
+  args: fromSpec({}),
+};
+
+export const Primary = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.primary),
+};
+
+export const Soft = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.soft),
+};
+
+export const Outline = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.outline),
+};
+
+export const Text = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.text),
+};
+
+export const Ghost = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.ghost),
+};
+
+export const Destructive = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.destructive),
+};
+
+export const Disabled = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.disabled),
+};
+
+export const Large = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.large),
+};
+
+export const Small = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.small),
+};
+
+export const XSmall = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.xsmall),
+};
+
+export const IconLeft = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.iconLeft),
+};
+
+export const IconRight = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.iconRight),
+};
+
+export const IconOnly = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.iconOnly),
+};
+
+export const CustomIconSize = {
+  args: fromSpec(BUTTON_STORY_SPEC.stories.customIconSize),
+};
+
+export const TrackingString = {
+  name: "Tracking (string)",
+  args: fromSpec(BUTTON_STORY_SPEC.stories.trackingString),
+};
+
+export const TrackingObject = {
+  name: "Tracking (object)",
+  args: fromSpec(BUTTON_STORY_SPEC.stories.trackingObject),
+};

package/src/ui/Button/Button.test.tsx

@@ -0,0 +1,85 @@
+import { describe, test, jest } from "@jest/globals";
+import { render, screen, fireEvent } from "@testing-library/react";
+import Button from "./Button";
+import {
+  BUTTON_APPEARANCES,
+  BUTTON_DEFAULTS,
+  BUTTON_LAYOUTS,
+  BUTTON_SIZES,
+} from "./Button.spec";
+
+describe("Button spec sync", () => {
+  test("renders with spec defaults", () => {
+    render(<Button label="Default" />);
+    const button = screen.getByRole("button", { name: "Default" });
+    expect(button).toHaveClass("uds-button");
+    expect(button).not.toHaveClass(BUTTON_DEFAULTS.appearance);
+    expect(button).not.toHaveClass(BUTTON_DEFAULTS.layout);
+    expect(button).not.toHaveClass(BUTTON_DEFAULTS.size);
+  });
+
+  test("supports all appearance options from spec", () => {
+    BUTTON_APPEARANCES.forEach((appearance) => {
+      const { unmount } = render(<Button label={appearance} appearance={appearance} />);
+      const button = screen.getByRole("button", { name: appearance });
+      if (appearance === BUTTON_DEFAULTS.appearance) {
+        expect(button).not.toHaveClass(appearance);
+      } else {
+        expect(button).toHaveClass(appearance);
+      }
+      unmount();
+    });
+  });
+
+  test("supports all size options from spec", () => {
+    BUTTON_SIZES.forEach((size) => {
+      const { unmount } = render(<Button label={size} size={size} />);
+      const button = screen.getByRole("button", { name: size });
+      if (size === BUTTON_DEFAULTS.size) {
+        expect(button).not.toHaveClass(size);
+      } else {
+        expect(button).toHaveClass(size);
+      }
+      unmount();
+    });
+  });
+
+  test("supports all layout options from spec", () => {
+    BUTTON_LAYOUTS.forEach((layout) => {
+      const isIconOnly = layout === "icon-only" || layout === "only";
+      const baseProps = {
+        icon: "Plus",
+        layout,
+      } as const;
+      const props = isIconOnly
+        ? { ...baseProps, "aria-label": "icon-action" }
+        : { ...baseProps, label: layout };
+
+      const { unmount } = render(
+        <Button {...props} />,
+      );
+
+      const button = screen.getByRole("button", {
+        name: isIconOnly ? "icon-action" : layout,
+      });
+
+      if (layout === BUTTON_DEFAULTS.layout) {
+        expect(button).not.toHaveClass(layout);
+      } else {
+        expect(button).toHaveClass(layout);
+      }
+      unmount();
+    });
+  });
+
+  test("tracks click event when tracking prop is provided", () => {
+    const onTrack = jest.fn();
+    window.addEventListener("uds:track", onTrack as EventListener);
+
+    render(<Button label="Track me" tracking="cta-click" />);
+    fireEvent.click(screen.getByRole("button", { name: "Track me" }));
+
+    expect(onTrack).toHaveBeenCalled();
+    window.removeEventListener("uds:track", onTrack as EventListener);
+  });
+});