Creating Reusable Component Libraries with shadcn/ui

// Layer 2: Design system wrapper
// This file lives at packages/ui/components/button.tsx
// It wraps the raw shadcn primitive and exposes your team's prop API.
//
// Import direction:
//   App code → packages/ui/components/button (this file)
//   This file → packages/ui/primitives/button (raw shadcn — never imported by app code)

import * as React from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
import {
  Button as ShadcnButton,
  type ButtonProps as ShadcnButtonProps,
} from '../primitives/button';
import { cn } from '../lib/utils';

// ---------------------------------------------------------------
// Variant definitions using your team's intent-based naming.
// These map onto shadcn's internal variant system below.
// ---------------------------------------------------------------
const buttonVariants = cva('', {
  variants: {
    intent: {
      primary: '',
      secondary: '',
      destructive: '',
      ghost: '',
    },
    size: {
      sm: '',
      md: '',
      lg: '',
    },
  },
  defaultVariants: {
    intent: 'primary',
    size: 'md',
  },
});

// Map your intent API onto shadcn's variant prop.
// This means application code never needs to know shadcn's internal naming.
const intentToShadcnVariant: Record<
  NonNullable<ButtonProps['intent']>,
  ShadcnButtonProps['variant']
> = {
  primary: 'default',
  secondary: 'secondary',
  destructive: 'destructive',
  ghost: 'ghost',
};

// Map your size API onto shadcn's size prop.
const sizeToShadcnSize: Record<
  NonNullable<ButtonProps['size']>,
  ShadcnButtonProps['size']
> = {
  sm: 'sm',
  md: 'default',
  lg: 'lg',
};

// ---------------------------------------------------------------
// ButtonProps intentionally omits shadcn's 'variant' and 'size'
// to prevent consumers from using shadcn's internal API directly.
// Expose your own intent/size props instead.
// ---------------------------------------------------------------
export interface ButtonProps
  extends Omit<ShadcnButtonProps, 'variant' | 'size'>,
    VariantProps<typeof buttonVariants> {
  /** Visual treatment that communicates purpose, not mechanism */
  intent?: 'primary' | 'secondary' | 'destructive' | 'ghost';
  /** Controls vertical padding and font size */
  size?: 'sm' | 'md' | 'lg';
  /** Shows a spinner, announces busy state, and disables interaction */
  loading?: boolean;
  /** Accessible label announced by screen readers during loading.
   *  Defaults to the button's visible text if not provided. */
  loadingText?: string;
}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  (
    {
      intent = 'primary',
      size = 'md',
      loading = false,
      loadingText,
      children,
      className,
      disabled,
      ...props
    },
    ref
  ) => {
    return (
      <ShadcnButton
        ref={ref}
        variant={intentToShadcnVariant[intent]}
        size={sizeToShadcnSize[size]}
        // Disable interaction during loading but keep the element focusable
        // so keyboard users are not surprised by a disappearing focus target.
        disabled={loading || disabled}
        // aria-busy signals to screen readers that the action is in progress.
        // aria-disabled mirrors the disabled state for assistive tech that
        // reads ARIA attributes separately from the HTML disabled attribute.
        aria-busy={loading ? true : undefined}
        aria-disabled={loading || disabled ? true : undefined}
        // aria-label overrides the visible text during loading so screen
        // readers announce the loading state instead of the button label.
        aria-label={
          loading && loadingText ? loadingText : undefined
        }
        className={cn(buttonVariants({ intent, size }), className)}
        {...props}
      >
        {loading && (
          <svg
            className="mr-2 h-4 w-4 animate-spin"
            xmlns="http://www.w3.org/2000/svg"
            fill="none"
            viewBox="0 0 24 24"
            aria-hidden="true"
          >
            <circle
              className="opacity-25"
              cx="12"
              cy="12"
              r="10"
              stroke="currentColor"
              strokeWidth="4"
            />
            <path
              className="opacity-75"
              fill="currentColor"
              d="M4 12a8 8 0 018-8v8H4z"
            />
          </svg>
        )}
        {children}
      </ShadcnButton>
    );
  }
);

Button.displayName = 'Button';

// ---------------------------------------------------------------
// Layer 3 usage example (feature component in application code)
// File: features/checkout/components/submit-button.tsx
// ---------------------------------------------------------------
//
// import { Button } from '@company/ui';            // ✅ Layer 2 wrapper
// NEVER: import { Button } from '@/components/ui/button'; // ❌ Layer 1 bypass
//
// export function SubmitButton({
//   amount,
//   isSubmitting,
// }: {
//   amount: number;
//   isSubmitting: boolean;
// }) {
//   return (
//     <Button
//       intent="primary"
//       size="lg"
//       loading={isSubmitting}
//       loadingText="Processing payment..."
//     >
//       Pay ${amount.toFixed(2)}
//     </Button>
//   );
// }

#!/usr/bin/env bash
# audit-shadcn-imports.sh
# Run this before starting migration to understand the scope of direct shadcn imports.
# Output: a sorted list of components and how many times each is imported directly.

echo "=== Direct shadcn primitive imports ==="
echo "These should all move to @company/ui after migration."
echo ""

# Find all direct imports from the shadcn components/ui directory
grep -rn --include='*.tsx' --include='*.ts' \
  'from ["\x27]@/components/ui/' \
  apps/ features/ \
  | sed "s/.*from ['\"]@\/components\/ui\///" \
  | sed "s/['\"].*/"/" \
  | sort \
  | uniq -c \
  | sort -rn

echo ""
echo "=== Total direct import count ==="
grep -rn --include='*.tsx' --include='*.ts' \
  'from ["\x27]@/components/ui/' \
  apps/ features/ \
  | wc -l

echo ""
echo "=== Files with most direct imports (migration priority) ==="
grep -rln --include='*.tsx' --include='*.ts' \
  'from ["\x27]@/components/ui/' \
  apps/ features/ \
  | xargs -I{} sh -c 'echo "$(grep -c \"from.*@/components/ui/\" {}) {}"' \
  | sort -rn \
  | head -20

/* globals.css
 * Design token system built on shadcn/ui CSS variables.
 * Import this file once in your root layout — never in individual components.
 *
 * Override strategy:
 *   - Dark mode:   .dark class on <html> redefines variables
 *   - Brand:       data-brand attribute on <html> redefines variables
 *   - Section:     data-theme attribute on a container redefines variables for that subtree
 *
 * Components reference variables directly (e.g., bg-primary, text-foreground).
 * They never receive theme information via props.
 */

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    /* === Core palette === */
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;

    /* === Surface hierarchy === */
    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;
    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;

    /* === Interactive states === */
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;

    /* === Feedback === */
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;
    --success: 142 76% 36%;
    --success-foreground: 0 0% 100%;
    --warning: 38 92% 50%;
    --warning-foreground: 0 0% 0%;

    /* === Structure === */
    --border: 214.3 31.8% 91.4%;
    --input: 214.3 31.8% 91.4%;
    --ring: 222.2 84% 4.9%;
    --radius: 0.5rem;

    /* === Typography scale === */
    --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
    --font-mono: 'JetBrains Mono', ui-monospace, monospace;

    /* === Spacing scale === */
    --space-1: 0.25rem;
    --space-2: 0.5rem;
    --space-3: 0.75rem;
    --space-4: 1rem;
    --space-6: 1.5rem;
    --space-8: 2rem;
  }

  /* Dark mode: redefine variables under .dark — no component changes required */
  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;
    --popover: 222.2 84% 4.9%;
    --popover-foreground: 210 40% 98%;
    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 11.2%;
    --secondary: 217.2 32.6% 17.5%;
    --secondary-foreground: 210 40% 98%;
    --muted: 217.2 32.6% 17.5%;
    --muted-foreground: 215 20.2% 65.1%;
    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;
    --destructive: 0 62.8% 30.6%;
    --destructive-foreground: 210 40% 98%;
    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
    --ring: 212.7 26.8% 83.9%;
  }

  /* Brand override: apply data-brand="enterprise" to <html> */
  [data-brand='enterprise'] {
    --primary: 220 70% 50%;
    --primary-foreground: 0 0% 100%;
    --radius: 0.25rem;
    --font-sans: 'DM Sans', ui-sans-serif, system-ui, sans-serif;
  }

  /* Section-level override: apply data-theme="inverted" to any container */
  /* Components inside inherit the redefined variables — no prop changes needed */
  [data-theme='inverted'] {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --border: 217.2 32.6% 17.5%;
  }

  * {
    @apply border-border;
  }

  body {
    @apply bg-background text-foreground font-sans;
  }
}

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "styles/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@company/ui",
    "utils": "@company/ui/lib/utils",
    "ui": "@company/ui/primitives",
    "lib": "@company/ui/lib",
    "hooks": "@company/ui/hooks"
  }
}

// button.a11y.test.tsx
// Accessibility tests for the Button wrapper component.
// Run with: vitest run --grep a11y

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { axe, toHaveNoViolations } from 'jest-axe';
import { Button } from '../components/button';

expect.extend(toHaveNoViolations);

describe('Button — axe automated scan', () => {
  it('has no axe violations in default state', async () => {
    const { container } = render(<Button>Submit</Button>);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it('has no axe violations in loading state', async () => {
    const { container } = render(
      <Button loading loadingText="Submitting form, please wait">
        Submit
      </Button>
    );
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

describe('Button — loading state ARIA', () => {
  it('sets aria-busy when loading', () => {
    render(<Button loading>Submit</Button>);
    const button = screen.getByRole('button');
    expect(button).toHaveAttribute('aria-busy', 'true');
  });

  it('sets aria-disabled when loading', () => {
    render(<Button loading>Submit</Button>);
    const button = screen.getByRole('button');
    expect(button).toHaveAttribute('aria-disabled', 'true');
  });

  it('sets aria-label to loadingText when provided', () => {
    render(
      <Button loading loadingText="Submitting form, please wait">
        Submit
      </Button>
    );
    const button = screen.getByRole('button');
    expect(button).toHaveAttribute(
      'aria-label',
      'Submitting form, please wait'
    );
  });

  it('does not set aria-label when loadingText is not provided', () => {
    render(<Button loading>Submit</Button>);
    const button = screen.getByRole('button');
    expect(button).not.toHaveAttribute('aria-label');
  });
});

describe('Button — keyboard interaction', () => {
  it('maintains focus when loading state changes', async () => {
    const user = userEvent.setup();
    const { rerender } = render(<Button>Submit</Button>);
    const button = screen.getByRole('button');

    await user.tab();
    expect(button).toHaveFocus();

    // Simulate form submission triggering loading state
    rerender(
      <Button loading loadingText="Submitting...">
        Submit
      </Button>
    );

    // Focus must not move when loading state changes
    expect(button).toHaveFocus();
  });

  it('is reachable via keyboard when not loading', async () => {
    const user = userEvent.setup();
    render(<Button>Submit</Button>);
    await user.tab();
    expect(screen.getByRole('button')).toHaveFocus();
  });

  it('is not clickable when loading', async () => {
    const handleClick = vi.fn();
    const user = userEvent.setup();
    render(
      <Button loading onClick={handleClick}>
        Submit
      </Button>
    );
    await user.click(screen.getByRole('button'));
    expect(handleClick).not.toHaveBeenCalled();
  });
});

// ---------------------------------------------------------------
// Dialog focus trapping — verify compound compositions
// ---------------------------------------------------------------
// Note: shadcn/ui exports Dialog parts as separate named imports
// (DialogTrigger, DialogContent, etc.), not compound dot-notation.
// If your Layer 2 Dialog wrapper exposes a compound API (Dialog.Trigger),
// adjust the imports below to match your wrapper's public API.
// ---------------------------------------------------------------
import {
  Dialog,
  DialogTrigger,
  DialogContent,
} from '../components/dialog';

describe('Dialog — focus trapping', () => {
  it('traps focus within the dialog when open', async () => {
    const user = userEvent.setup();
    render(
      <Dialog>
        <DialogTrigger asChild>
          <Button>Open dialog</Button>
        </DialogTrigger>
        <DialogContent>
          <input aria-label="Name" />
          <Button>Cancel</Button>
          <Button intent="destructive">Confirm</Button>
        </DialogContent>
      </Dialog>
    );

    // Open the dialog
    await user.click(screen.getByRole('button', { name: 'Open dialog' }));
    expect(screen.getByRole('dialog')).toBeInTheDocument();

    // Tab through all focusable elements — focus must stay within the dialog
    await user.tab();
    expect(screen.getByLabelText('Name')).toHaveFocus();
    await user.tab();
    expect(screen.getByRole('button', { name: 'Cancel' })).toHaveFocus();
    await user.tab();
    expect(screen.getByRole('button', { name: 'Confirm' })).toHaveFocus();

    // Tab wraps back to the first focusable element inside the dialog
    await user.tab();
    expect(screen.getByLabelText('Name')).toHaveFocus();
  });

  it('returns focus to the trigger when closed', async () => {
    const user = userEvent.setup();
    render(
      <Dialog>
        <DialogTrigger asChild>
          <Button>Open dialog</Button>
        </DialogTrigger>
        <DialogContent>
          <Button>Close</Button>
        </DialogContent>
      </Dialog>
    );

    const trigger = screen.getByRole('button', { name: 'Open dialog' });
    await user.click(trigger);
    await user.keyboard('{Escape}');

    // Focus must return to the element that opened the dialog
    expect(trigger).toHaveFocus();
  });
});

// button.visual.test.ts
// Visual regression tests for the Button wrapper using Playwright.
// Run with: playwright test packages/ui/__tests__/button.visual.test.ts
//
// First run creates baseline screenshots in __screenshots__/.
// Subsequent runs compare against the baseline and fail if pixels changed.
// To update the baseline after an intentional change: playwright test --update-snapshots

import { test, expect } from '@playwright/test';

const STORYBOOK_URL = process.env.STORYBOOK_URL ?? 'http://localhost:6006';

const buttonVariants = [
  { story: 'primary', name: 'Button/Primary' },
  { story: 'secondary', name: 'Button/Secondary' },
  { story: 'destructive', name: 'Button/Destructive' },
  { story: 'ghost', name: 'Button/Ghost' },
  { story: 'loading', name: 'Button/Loading' },
  { story: 'disabled', name: 'Button/Disabled' },
] as const;

for (const { story, name } of buttonVariants) {
  test(`${name} — light mode visual regression`, async ({ page }) => {
    await page.goto(
      `${STORYBOOK_URL}/iframe.html?id=components-button--${story}&viewMode=story`
    );
    await page.waitForLoadState('networkidle');

    const button = page.getByRole('button').first();
    await expect(button).toBeVisible();
    await expect(button).toHaveScreenshot(`button-${story}-light.png`);
  });

  test(`${name} — dark mode visual regression`, async ({ page }) => {
    await page.goto(
      `${STORYBOOK_URL}/iframe.html?id=components-button--${story}&viewMode=story&globals=backgrounds:dark`
    );
    await page.waitForLoadState('networkidle');

    // Apply dark mode via class — matches the CSS variable strategy in globals.css
    await page.evaluate(() =>
      document.documentElement.classList.add('dark')
    );

    const button = page.getByRole('button').first();
    await expect(button).toBeVisible();
    await expect(button).toHaveScreenshot(`button-${story}-dark.png`);
  });

  test(`${name} — hover state visual regression`, async ({ page }) => {
    await page.goto(
      `${STORYBOOK_URL}/iframe.html?id=components-button--${story}&viewMode=story`
    );
    await page.waitForLoadState('networkidle');

    const button = page.getByRole('button').first();
    await button.hover();
    await expect(button).toHaveScreenshot(`button-${story}-hover.png`);
  });
}

{
  "name": "@company/ui",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "exports": {
    ".":  {
      "types": "./index.ts",
      "import": "./index.ts"
    },
    "./styles": "./styles/globals.css",
    "./lib/utils": {
      "types": "./lib/utils.ts",
      "import": "./lib/utils.ts"
    },
    "./hooks/*": {
      "types": "./hooks/*.ts",
      "import": "./hooks/*.ts"
    }
  },
  "files": [
    "components",
    "primitives",
    "lib",
    "styles",
    "hooks",
    "index.ts"
  ],
  "sideEffects": [
    "**/*.css"
  ],
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0",
    "tailwindcss": "^3.4.0 || ^4.0.0"
  },
  "dependencies": {
    "@radix-ui/react-dialog": "^1.1.0",
    "@radix-ui/react-dropdown-menu": "^2.1.0",
    "@radix-ui/react-slot": "^1.1.0",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.1.0",
    "tailwind-merge": "^2.5.0"
  },
  "devDependencies": {
    "@playwright/test": "^1.44.0",
    "@testing-library/jest-dom": "^6.4.0",
    "@testing-library/react": "^15.0.0",
    "@testing-library/user-event": "^14.5.0",
    "jest-axe": "^9.0.0",
    "tsup": "^8.0.0",
    "typescript": "^5.5.0",
    "vitest": "^1.6.0"
  },
  "scripts": {
    "build": "tsup",
    "test": "vitest run",
    "test:a11y": "vitest run --grep a11y",
    "test:visual": "playwright test",
    "test:visual:update": "playwright test --update-snapshots",
    "lint": "eslint . --ext .ts,.tsx",
    "typecheck": "tsc --noEmit"
  }
}

// input.tsx
// Layer 2 wrapper for shadcn Input.
// Demonstrates composition props, escape hatch, and JSDoc documentation patterns.

import * as React from 'react';
import { Input as ShadcnInput } from '../primitives/input';
import { cn } from '../lib/utils';

export interface InputProps
  extends Omit<React.ComponentPropsWithoutRef<typeof ShadcnInput>, 'size'> {
  /**
   * Element rendered inside the input's left edge.
   * Use for icons, currency symbols, or flag components.
   * The input's left padding adjusts automatically when this prop is provided.
   * @example leftElement={<SearchIcon className="h-4 w-4" />}
   */
  leftElement?: React.ReactNode;

  /**
   * Element rendered inside the input's right edge.
   * Use for units, suffix text, or action icons (clear, toggle visibility).
   * @example rightElement={<span className="text-muted-foreground">kg</span>}
   */
  rightElement?: React.ReactNode;

  /**
   * Error message rendered below the input in destructive color.
   * Also sets aria-invalid and aria-describedby on the input for screen readers.
   * Takes priority over helperText when both are provided.
   * @example error="Email address is required"
   */
  error?: string;

  /**
   * Instructional text rendered below the input.
   * Hidden when error is provided.
   * @example helperText="We'll never share your email with anyone."
   */
  helperText?: string;

  /**
   * Controls the input's vertical padding and font size.
   * Use sm for compact forms (data tables, filter bars).
   * Use md (default) for standard forms.
   * Use lg for prominent single-field UIs (search, hero inputs).
   */
  size?: 'sm' | 'md' | 'lg';
}

export const Input = React.forwardRef<HTMLInputElement, InputProps>(
  (
    {
      leftElement,
      rightElement,
      error,
      helperText,
      size = 'md',
      className,
      id,
      ...props
    },
    ref
  ) => {
    // Generate a stable ID for aria-describedby if the consumer did not provide one
    const generatedId = React.useId();
    const inputId = id ?? generatedId;
    const helperId = `${inputId}-helper`;
    const errorId = `${inputId}-error`;

    const sizeClasses = {
      sm: 'h-8 px-2 text-xs',
      md: 'h-10 px-3 text-sm',
      lg: 'h-12 px-4 text-base',
    };

    return (
      <div className="flex flex-col gap-1.5">
        <div className="relative">
          {leftElement && (
            <div
              className="pointer-events-none absolute inset-y-0 left-3 flex items-center text-muted-foreground"
              aria-hidden="true"
            >
              {leftElement}
            </div>
          )}

          <ShadcnInput
            ref={ref}
            id={inputId}
            // aria-invalid signals to screen readers that the field has an error
            aria-invalid={error ? true : undefined}
            // aria-describedby connects the input to its helper/error text
            aria-describedby={
              error ? errorId : helperText ? helperId : undefined
            }
            className={cn(
              sizeClasses[size],
              leftElement && 'pl-9',
              rightElement && 'pr-9',
              error && 'border-destructive focus-visible:ring-destructive',
              className
            )}
            {...props}
          />

          {rightElement && (
            <div
              className="absolute inset-y-0 right-3 flex items-center text-muted-foreground"
              aria-hidden="true"
            >
              {rightElement}
            </div>
          )}
        </div>

        {error && (
          <p
            id={errorId}
            role="alert"
            className="text-xs text-destructive"
          >
            {error}
          </p>
        )}

        {!error && helperText && (
          <p
            id={helperId}
            className="text-xs text-muted-foreground"
          >
            {helperText}
          </p>
        )}
      </div>
    );
  }
);

Input.displayName = 'Input';