:root                   Light theme semantic tokens (default)
[data-theme="dark"]     Dark theme overrides
@media (prefers-color-scheme: dark)  System fallback (no data-theme)
.brand-acme             Brand-specific color overrides only

/* tokens/primitives.css */
:root {
  --blue-600: #2563eb; --gray-900: #111827;
  --gray-50: #f9fafb;  --space-4: 1rem; --radius-md: 0.375rem;
}

/* tokens/semantic.css */
:root {
  --color-interactive-primary:       var(--blue-600);
  --color-interactive-primary-hover: var(--blue-700);
  --color-bg-primary:   #ffffff;
  --color-text-primary: var(--gray-900);
  --color-border:       var(--gray-200);
}

/* tokens/dark.css */
[data-theme="dark"] {
  --color-interactive-primary: var(--blue-500);
  --color-bg-primary:   var(--gray-900);
  --color-text-primary: var(--gray-50);
  --color-border:       var(--gray-700);
}

npm install class-variance-authority clsx tailwind-merge

// components/Button/Button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';
import * as React from 'react';

const button = cva(
  'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[--color-ring] disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        primary:     'bg-[--color-interactive-primary] text-white hover:bg-[--color-interactive-primary-hover]',
        secondary:   'border border-[--color-border] bg-transparent hover:bg-[--color-bg-secondary]',
        ghost:       'hover:bg-[--color-bg-secondary] hover:text-[--color-text-primary]',
        destructive: 'bg-[--color-interactive-destructive] text-white hover:bg-[--color-interactive-destructive-hover]',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-6 text-base',
      },
    },
    defaultVariants: { variant: 'primary', size: 'md' },
  }
);

export type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
  VariantProps<typeof button>;

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, ...props }, ref) => (
    <button ref={ref} className={twMerge(clsx(button({ variant, size }), className))} {...props} />
  )
);
Button.displayName = 'Button';

npx storybook@latest init

// components/Button/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary', 'ghost', 'destructive'] },
    size:    { control: 'radio',  options: ['sm', 'md', 'lg'] },
    disabled: { control: 'boolean' },
  },
};
export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story    = { args: { children: 'Click me', variant: 'primary' } };
export const Secondary: Story  = { args: { children: 'Click me', variant: 'secondary' } };
export const AllVariants: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap' }}>
      {(['primary', 'secondary', 'ghost', 'destructive'] as const).map(v => (
        <Button key={v} variant={v}>{v}</Button>
      ))}
    </div>
  ),
};

// hooks/useTheme.ts
type Theme = 'light' | 'dark' | 'system';

export function useTheme() {
  const [theme, setTheme] = React.useState<Theme>(
    () => (localStorage.getItem('theme') as Theme) ?? 'system'
  );

  React.useEffect(() => {
    const isDark =
      theme === 'dark' ||
      (theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
    document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light');
    localStorage.setItem('theme', theme);
  }, [theme]);

  return { theme, setTheme };
}

/* Zero out motion tokens for users who prefer reduced motion */
@media (prefers-reduced-motion: reduce) {
  :root { --duration-fast: 0ms; --duration-normal: 0ms; --duration-slow: 0ms; }
}

// components/Tabs/Tabs.tsx
import * as React from 'react';

type TabsCtx = { active: string; setActive: (id: string) => void };
const TabsContext = React.createContext<TabsCtx | null>(null);
const useTabs = () => {
  const ctx = React.useContext(TabsContext);
  if (!ctx) throw new Error('Tabs subcomponents must be used inside <Tabs>');
  return ctx;
};

function Tabs({ defaultValue, children }: { defaultValue: string; children: React.ReactNode }) {
  const [active, setActive] = React.useState(defaultValue);
  return <TabsContext.Provider value={{ active, setActive }}><div>{children}</div></TabsContext.Provider>;
}

Tabs.List = ({ children }: { children: React.ReactNode }) =>
  <div role="tablist" style={{ display: 'flex', gap: '0.5rem' }}>{children}</div>;

Tabs.Tab = ({ id, children }: { id: string; children: React.ReactNode }) => {
  const { active, setActive } = useTabs();
  return <button role="tab" aria-selected={active === id} aria-controls={`panel-${id}`} onClick={() => setActive(id)}>{children}</button>;
};

Tabs.Panel = ({ id, children }: { id: string; children: React.ReactNode }) => {
  const { active } = useTabs();
  return active === id ? <div role="tabpanel" id={`panel-${id}`}>{children}</div> : null;
};

export { Tabs };

npm install style-dictionary

{ "color": { "blue": { "500": { "value": "#3b82f6", "type": "color" } } } }

// style-dictionary.config.mjs
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: { transformGroup: 'css', buildPath: 'dist/tokens/',
      files: [{ destination: 'variables.css', format: 'css/variables', options: { selector: ':root', outputReferences: true } }] },
    js:  { transformGroup: 'js',  buildPath: 'dist/tokens/',
      files: [{ destination: 'tokens.mjs', format: 'javascript/es6' }] },
  },
};

npx style-dictionary build --config style-dictionary.config.mjs

npm install --save-dev @changesets/cli && npx changeset init

// package.json - expose tokens as a named export
{
  "exports": {
    ".":         { "import": "./dist/index.js",            "types": "./dist/index.d.ts" },
    "./tokens":  { "import": "./dist/tokens/variables.css" }
  },
  "scripts": { "build": "tsup src/index.ts --format esm --dts", "release": "changeset publish" }
}