@gv-tech/design-system 2.1.1 → 2.2.0

package/dist/pages/components/ThemeToggleDocs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ThemeToggleDocs.d.ts","sourceRoot":"","sources":["../../../src/pages/components/ThemeToggleDocs.tsx"],"names":[],"mappings":"AAKA,wBAAgB,eAAe,4CAoH9B"}
+{"version":3,"file":"ThemeToggleDocs.d.ts","sourceRoot":"","sources":["../../../src/pages/components/ThemeToggleDocs.tsx"],"names":[],"mappings":"AAKA,wBAAgB,eAAe,4CA+I9B"}

package/dist/registry/alert-dialog.test.json

@@ -6,7 +6,7 @@
   "files": [
     {
       "path": "ui/alert-dialog.test.tsx",
-      "content": "import { render, screen, waitFor } from '@testing-library/react';\nimport userEvent from '@testing-library/user-event';\nimport { describe, expect, it } from 'vitest';\nimport {\n  AlertDialog,\n  AlertDialogAction,\n  AlertDialogCancel,\n  AlertDialogContent,\n  AlertDialogDescription,\n  AlertDialogFooter,\n  AlertDialogHeader,\n  AlertDialogTitle,\n  AlertDialogTrigger,\n} from './alert-dialog';\n\ndescribe('AlertDialog', () => {\n  it('renders correctly', async () => {\n    render(\n      <AlertDialog>\n        <AlertDialogTrigger>Open</AlertDialogTrigger>\n        <AlertDialogContent>\n          <AlertDialogHeader>\n            <AlertDialogTitle>Are you sure?</AlertDialogTitle>\n            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>\n          </AlertDialogHeader>\n          <AlertDialogFooter>\n            <AlertDialogCancel>Cancel</AlertDialogCancel>\n            <AlertDialogAction>Continue</AlertDialogAction>\n          </AlertDialogFooter>\n        </AlertDialogContent>\n      </AlertDialog>,\n    );\n\n    expect(screen.getByText('Open')).toBeInTheDocument();\n    expect(screen.queryByText('Are you sure?')).not.toBeInTheDocument();\n\n    await userEvent.click(screen.getByText('Open'));\n\n    await waitFor(() => {\n      expect(screen.getByRole('alertdialog')).toBeInTheDocument();\n      expect(screen.getByText('Are you sure?')).toBeInTheDocument();\n      expect(screen.getByText('This action cannot be undone.')).toBeInTheDocument();\n    });\n  });\n\n  it('closes when cancel is clicked', async () => {\n    render(\n      <AlertDialog>\n        <AlertDialogTrigger>Open</AlertDialogTrigger>\n        <AlertDialogContent>\n          <AlertDialogHeader>\n            <AlertDialogTitle>Are you sure?</AlertDialogTitle>\n          </AlertDialogHeader>\n          <AlertDialogFooter>\n            <AlertDialogCancel>Cancel</AlertDialogCancel>\n          </AlertDialogFooter>\n        </AlertDialogContent>\n      </AlertDialog>,\n    );\n\n    await userEvent.click(screen.getByText('Open'));\n    await waitFor(() => expect(screen.getByRole('alertdialog')).toBeInTheDocument());\n\n    await userEvent.click(screen.getByText('Cancel'));\n    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());\n  });\n\n  it('closes when action is clicked', async () => {\n    render(\n      <AlertDialog>\n        <AlertDialogTrigger>Open</AlertDialogTrigger>\n        <AlertDialogContent>\n          <AlertDialogHeader>\n            <AlertDialogTitle>Are you sure?</AlertDialogTitle>\n          </AlertDialogHeader>\n          <AlertDialogFooter>\n            <AlertDialogAction>Continue</AlertDialogAction>\n          </AlertDialogFooter>\n        </AlertDialogContent>\n      </AlertDialog>,\n    );\n\n    await userEvent.click(screen.getByText('Open'));\n    await waitFor(() => expect(screen.getByRole('alertdialog')).toBeInTheDocument());\n\n    await userEvent.click(screen.getByText('Continue'));\n    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());\n  });\n});\n",
+      "content": "import { render, screen, waitFor } from '@testing-library/react';\nimport userEvent from '@testing-library/user-event';\nimport { describe, expect, it } from 'vitest';\nimport {\n  AlertDialog,\n  AlertDialogAction,\n  AlertDialogCancel,\n  AlertDialogContent,\n  AlertDialogDescription,\n  AlertDialogFooter,\n  AlertDialogHeader,\n  AlertDialogTitle,\n  AlertDialogTrigger,\n} from './alert-dialog';\n\ndescribe('AlertDialog', () => {\n  it('renders correctly', async () => {\n    render(\n      <AlertDialog>\n        <AlertDialogTrigger>Open</AlertDialogTrigger>\n        <AlertDialogContent>\n          <AlertDialogHeader>\n            <AlertDialogTitle>Are you sure?</AlertDialogTitle>\n            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>\n          </AlertDialogHeader>\n          <AlertDialogFooter>\n            <AlertDialogCancel>Cancel</AlertDialogCancel>\n            <AlertDialogAction>Continue</AlertDialogAction>\n          </AlertDialogFooter>\n        </AlertDialogContent>\n      </AlertDialog>,\n    );\n\n    expect(screen.getByText('Open')).toBeInTheDocument();\n    expect(screen.queryByText('Are you sure?')).not.toBeInTheDocument();\n\n    await userEvent.click(screen.getByText('Open'));\n\n    await waitFor(() => {\n      expect(screen.getByRole('alertdialog')).toBeInTheDocument();\n      expect(screen.getByText('Are you sure?')).toBeInTheDocument();\n      expect(screen.getByText('This action cannot be undone.')).toBeInTheDocument();\n    });\n  });\n\n  it('closes when cancel is clicked', async () => {\n    render(\n      <AlertDialog>\n        <AlertDialogTrigger>Open</AlertDialogTrigger>\n        <AlertDialogContent>\n          <AlertDialogHeader>\n            <AlertDialogTitle>Are you sure?</AlertDialogTitle>\n            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>\n          </AlertDialogHeader>\n          <AlertDialogFooter>\n            <AlertDialogCancel>Cancel</AlertDialogCancel>\n          </AlertDialogFooter>\n        </AlertDialogContent>\n      </AlertDialog>,\n    );\n\n    await userEvent.click(screen.getByText('Open'));\n    await waitFor(() => expect(screen.getByRole('alertdialog')).toBeInTheDocument());\n\n    await userEvent.click(screen.getByText('Cancel'));\n    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());\n  });\n\n  it('closes when action is clicked', async () => {\n    render(\n      <AlertDialog>\n        <AlertDialogTrigger>Open</AlertDialogTrigger>\n        <AlertDialogContent>\n          <AlertDialogHeader>\n            <AlertDialogTitle>Are you sure?</AlertDialogTitle>\n            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>\n          </AlertDialogHeader>\n          <AlertDialogFooter>\n            <AlertDialogAction>Continue</AlertDialogAction>\n          </AlertDialogFooter>\n        </AlertDialogContent>\n      </AlertDialog>,\n    );\n\n    await userEvent.click(screen.getByText('Open'));\n    await waitFor(() => expect(screen.getByRole('alertdialog')).toBeInTheDocument());\n\n    await userEvent.click(screen.getByText('Continue'));\n    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());\n  });\n});\n",
       "type": "registry:ui"
     }
   ]

package/dist/registry/index.json

@@ -587,6 +587,13 @@
     ],
     "type": "registry:ui"
   },
+  {
+    "name": "theme-toggle.test",
+    "files": [
+      "ui/theme-toggle.test.tsx"
+    ],
+    "type": "registry:ui"
+  },
   {
     "name": "theme-toggle",
     "files": [

package/dist/registry/theme-toggle.json

@@ -6,7 +6,7 @@
   "files": [
     {
       "path": "ui/theme-toggle.tsx",
-      "content": "import { Button } from '@/components/ui/button';\nimport {\n  DropdownMenu,\n  DropdownMenuContent,\n  DropdownMenuItem,\n  DropdownMenuTrigger,\n} from '@/components/ui/dropdown-menu';\nimport { cn } from '@/lib/utils';\nimport { Moon, Sun, SunMoon } from 'lucide-react';\nimport { useTheme } from 'next-themes';\n\nexport interface ThemeToggleProps {\n  /**\n   * The mode of the theme toggle. 'binary' allows toggling between light and dark. 'ternary' allows choosing between\n   * light, dark, and system.\n   *\n   * @default 'binary'\n   */\n  variant?: 'binary' | 'ternary';\n  /** Optional callback when the theme changes. */\n  onThemeChange?: (theme: string) => void;\n  /** Optional current theme value for external control. */\n  customTheme?: string;\n  /** Optional className for the button. */\n  className?: string;\n}\n\nexport function ThemeToggle({ variant = 'binary', onThemeChange, customTheme, className }: ThemeToggleProps) {\n  const { theme: nextTheme, setTheme: setNextTheme, resolvedTheme } = useTheme();\n\n  // Use customTheme if provided, otherwise fallback to next-themes\n  const currentTheme = customTheme ?? nextTheme;\n\n  // Determine the effective theme for icon rendering\n  const effectiveTheme = customTheme ? customTheme : resolvedTheme;\n  const isDark = effectiveTheme === 'dark';\n  const isSystem = currentTheme === 'system';\n\n  const handleThemeChange = (newTheme: string) => {\n    if (onThemeChange) {\n      onThemeChange(newTheme);\n    } else {\n      setNextTheme(newTheme);\n    }\n  };\n\n  const IconToggle = () => (\n    <>\n      <Sun\n        className={cn(\n          'h-[1.2rem] w-[1.2rem] transition-all',\n          !isSystem && !isDark ? 'rotate-0 scale-100' : '-rotate-90 scale-0',\n        )}\n      />\n      <Moon\n        className={cn(\n          'absolute h-[1.2rem] w-[1.2rem] transition-all',\n          !isSystem && isDark ? 'rotate-0 scale-100' : 'rotate-90 scale-0',\n        )}\n      />\n      <SunMoon\n        className={cn(\n          'absolute h-[1.2rem] w-[1.2rem] transition-all',\n          isSystem ? 'rotate-0 scale-100' : 'rotate-90 scale-0',\n        )}\n      />\n      <span className=\"sr-only\">Toggle theme</span>\n    </>\n  );\n\n  if (variant === 'ternary') {\n    return (\n      <DropdownMenu>\n        <DropdownMenuTrigger asChild>\n          <Button variant=\"ghost\" size=\"icon\" className={cn('relative h-9 w-9', className)}>\n            <IconToggle />\n          </Button>\n        </DropdownMenuTrigger>\n        <DropdownMenuContent align=\"end\">\n          <DropdownMenuItem onClick={() => handleThemeChange('light')}>\n            <Sun className=\"mr-2 h-4 w-4\" />\n            <span>Light</span>\n          </DropdownMenuItem>\n          <DropdownMenuItem onClick={() => handleThemeChange('dark')}>\n            <Moon className=\"mr-2 h-4 w-4\" />\n            <span>Dark</span>\n          </DropdownMenuItem>\n          <DropdownMenuItem onClick={() => handleThemeChange('system')}>\n            <SunMoon className=\"mr-2 h-4 w-4\" />\n            <span>System</span>\n          </DropdownMenuItem>\n        </DropdownMenuContent>\n      </DropdownMenu>\n    );\n  }\n\n  return (\n    <Button\n      variant=\"ghost\"\n      size=\"icon\"\n      className={cn('relative h-9 w-9', className)}\n      onClick={() => handleThemeChange(currentTheme === 'dark' ? 'light' : 'dark')}\n      aria-label=\"Toggle theme\"\n    >\n      <IconToggle />\n    </Button>\n  );\n}\n",
+      "content": "import { Button } from '@/components/ui/button';\nimport {\n  DropdownMenu,\n  DropdownMenuContent,\n  DropdownMenuItem,\n  DropdownMenuTrigger,\n} from '@/components/ui/dropdown-menu';\nimport { useTheme } from '@/hooks/use-theme';\nimport { cn } from '@/lib/utils';\nimport { Moon, Sun, SunMoon } from 'lucide-react';\n\nexport interface ThemeToggleProps {\n  /**\n   * The mode of the theme toggle. 'binary' allows toggling between light and dark. 'ternary' allows choosing between\n   * light, dark, and system.\n   *\n   * @default 'binary'\n   */\n  variant?: 'binary' | 'ternary';\n  /** Optional callback when the theme changes. */\n  onThemeChange?: (theme: string) => void;\n  /** Optional current theme value for external control. */\n  customTheme?: string;\n  /** Optional className for the button. */\n  className?: string;\n}\n\nexport function ThemeToggle({ variant = 'binary', onThemeChange, customTheme, className }: ThemeToggleProps) {\n  const { theme: nextTheme, setTheme: setNextTheme, resolvedTheme } = useTheme();\n\n  // Use customTheme if provided, otherwise fallback to next-themes\n  const currentTheme = customTheme ?? nextTheme;\n\n  // Determine the effective theme for icon rendering\n  const effectiveTheme = customTheme ? customTheme : resolvedTheme;\n  const isDark = effectiveTheme === 'dark';\n  const isSystem = currentTheme === 'system';\n\n  const handleThemeChange = (newTheme: string) => {\n    if (onThemeChange) {\n      onThemeChange(newTheme);\n    } else {\n      setNextTheme(newTheme);\n    }\n  };\n\n  const IconToggle = () => (\n    <>\n      <Sun\n        className={cn(\n          'h-[1.2rem] w-[1.2rem] transition-all',\n          !isSystem && !isDark ? 'rotate-0 scale-100' : '-rotate-90 scale-0',\n        )}\n      />\n      <Moon\n        className={cn(\n          'absolute h-[1.2rem] w-[1.2rem] transition-all',\n          !isSystem && isDark ? 'rotate-0 scale-100' : 'rotate-90 scale-0',\n        )}\n      />\n      <SunMoon\n        className={cn(\n          'absolute h-[1.2rem] w-[1.2rem] transition-all',\n          isSystem ? 'rotate-0 scale-100' : 'rotate-90 scale-0',\n        )}\n      />\n      <span className=\"sr-only\">Toggle theme</span>\n    </>\n  );\n\n  if (variant === 'ternary') {\n    return (\n      <DropdownMenu>\n        <DropdownMenuTrigger asChild>\n          <Button variant=\"ghost\" size=\"icon\" className={cn('relative h-9 w-9', className)}>\n            <IconToggle />\n          </Button>\n        </DropdownMenuTrigger>\n        <DropdownMenuContent align=\"end\">\n          <DropdownMenuItem onClick={() => handleThemeChange('light')}>\n            <Sun className=\"mr-2 h-4 w-4\" />\n            <span>Light</span>\n          </DropdownMenuItem>\n          <DropdownMenuItem onClick={() => handleThemeChange('dark')}>\n            <Moon className=\"mr-2 h-4 w-4\" />\n            <span>Dark</span>\n          </DropdownMenuItem>\n          <DropdownMenuItem onClick={() => handleThemeChange('system')}>\n            <SunMoon className=\"mr-2 h-4 w-4\" />\n            <span>System</span>\n          </DropdownMenuItem>\n        </DropdownMenuContent>\n      </DropdownMenu>\n    );\n  }\n\n  return (\n    <Button\n      variant=\"ghost\"\n      size=\"icon\"\n      className={cn('relative h-9 w-9', className)}\n      onClick={() => handleThemeChange(currentTheme === 'dark' ? 'light' : 'dark')}\n      aria-label=\"Toggle theme\"\n    >\n      <IconToggle />\n    </Button>\n  );\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/registry/theme-toggle.test.json

@@ -0,0 +1,13 @@
+{
+  "name": "theme-toggle.test",
+  "type": "registry:ui",
+  "dependencies": [],
+  "registryDependencies": [],
+  "files": [
+    {
+      "path": "ui/theme-toggle.test.tsx",
+      "content": "import { ThemeToggle } from '@/components/ui/theme-toggle';\nimport { render, screen } from '@testing-library/react';\nimport userEvent from '@testing-library/user-event';\nimport { ThemeProvider } from 'next-themes';\nimport { describe, expect, it, vi } from 'vitest';\n\n// Mock the useTheme hook to control its return values\nvi.mock('@/hooks/use-theme', async () => {\n  const actual = await vi.importActual('@/hooks/use-theme');\n  return {\n    ...actual,\n    useTheme: () => ({\n      theme: 'light',\n      setTheme: vi.fn(),\n      resolvedTheme: 'light',\n      tokens: {},\n    }),\n  };\n});\n\ndescribe('ThemeToggle', () => {\n  it('renders binary toggle by default', () => {\n    render(\n      <ThemeProvider>\n        <ThemeToggle />\n      </ThemeProvider>,\n    );\n    // Use role button which is accessible\n    const button = screen.getByRole('button', { name: /toggle theme/i });\n    expect(button).toBeInTheDocument();\n  });\n\n  it('renders ternary toggle with dropdown', async () => {\n    const user = userEvent.setup();\n    render(\n      <ThemeProvider>\n        <ThemeToggle variant=\"ternary\" />\n      </ThemeProvider>,\n    );\n    const button = screen.getByRole('button'); // Dropdown trigger\n    expect(button).toBeInTheDocument();\n\n    // Open dropdown\n    await user.click(button);\n    expect(await screen.findByText('Light')).toBeInTheDocument();\n    expect(screen.getByText('Dark')).toBeInTheDocument();\n    expect(screen.getByText('System')).toBeInTheDocument();\n  });\n});\n",
+      "type": "registry:ui"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gv-tech/design-system",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Garcia Ventures react design system",
   "repository": "git@github.com:Garcia-Ventures/gvtech-design.git",
   "license": "MIT",

package/scripts/validate.js

@@ -15,6 +15,7 @@ const steps = [
     cmd: fix ? 'yarn lint:fix' : 'yarn lint',
   },
   { name: 'TypeScript type check', cmd: 'npx tsc --noEmit' },
+  { name: 'Test (vitest)', cmd: 'yarn test:ci' },
   { name: 'Build (vite)', cmd: 'yarn build' },
 ];
 

package/src/components/ui/alert-dialog.test.tsx

@@ -50,6 +50,7 @@ describe('AlertDialog', () => {
         <AlertDialogContent>
           <AlertDialogHeader>
             <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
             <AlertDialogCancel>Cancel</AlertDialogCancel>
@@ -72,6 +73,7 @@ describe('AlertDialog', () => {
         <AlertDialogContent>
           <AlertDialogHeader>
             <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
             <AlertDialogAction>Continue</AlertDialogAction>

package/src/components/ui/theme-toggle.test.tsx

@@ -0,0 +1,49 @@
+import { ThemeToggle } from '@/components/ui/theme-toggle';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ThemeProvider } from 'next-themes';
+import { describe, expect, it, vi } from 'vitest';
+
+// Mock the useTheme hook to control its return values
+vi.mock('@/hooks/use-theme', async () => {
+  const actual = await vi.importActual('@/hooks/use-theme');
+  return {
+    ...actual,
+    useTheme: () => ({
+      theme: 'light',
+      setTheme: vi.fn(),
+      resolvedTheme: 'light',
+      tokens: {},
+    }),
+  };
+});
+
+describe('ThemeToggle', () => {
+  it('renders binary toggle by default', () => {
+    render(
+      <ThemeProvider>
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    // Use role button which is accessible
+    const button = screen.getByRole('button', { name: /toggle theme/i });
+    expect(button).toBeInTheDocument();
+  });
+
+  it('renders ternary toggle with dropdown', async () => {
+    const user = userEvent.setup();
+    render(
+      <ThemeProvider>
+        <ThemeToggle variant="ternary" />
+      </ThemeProvider>,
+    );
+    const button = screen.getByRole('button'); // Dropdown trigger
+    expect(button).toBeInTheDocument();
+
+    // Open dropdown
+    await user.click(button);
+    expect(await screen.findByText('Light')).toBeInTheDocument();
+    expect(screen.getByText('Dark')).toBeInTheDocument();
+    expect(screen.getByText('System')).toBeInTheDocument();
+  });
+});

package/src/components/ui/theme-toggle.tsx

@@ -5,9 +5,9 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
+import { useTheme } from '@/hooks/use-theme';
 import { cn } from '@/lib/utils';
 import { Moon, Sun, SunMoon } from 'lucide-react';
-import { useTheme } from 'next-themes';
 
 export interface ThemeToggleProps {
   /**

package/src/hooks/use-theme.test.tsx

@@ -0,0 +1,27 @@
+import { useTheme } from '@/hooks/use-theme';
+import { theme } from '@/theme/tokens';
+import { renderHook } from '@testing-library/react';
+import { ThemeProvider } from 'next-themes';
+import { describe, expect, it } from 'vitest';
+
+describe('useTheme', () => {
+  it('returns default light tokens when no theme is set', () => {
+    const { result } = renderHook(() => useTheme(), {
+      wrapper: ({ children }) => <ThemeProvider>{children}</ThemeProvider>,
+    });
+
+    expect(result.current.tokens).toEqual(theme.light);
+  });
+
+  it('returns dark tokens when theme is dark', () => {
+    const { result } = renderHook(() => useTheme(), {
+      wrapper: ({ children }) => (
+        <ThemeProvider defaultTheme="dark" enableSystem={false}>
+          {children}
+        </ThemeProvider>
+      ),
+    });
+
+    expect(result.current.tokens).toEqual(theme.dark);
+  });
+});

package/src/hooks/use-theme.ts

@@ -0,0 +1,15 @@
+import { theme } from '@/theme/tokens';
+import { useTheme as useNextTheme } from 'next-themes';
+
+export function useTheme() {
+  const context = useNextTheme();
+  const { resolvedTheme } = context;
+
+  // Default to light theme tokens if resolvedTheme is undefined or invalid
+  const activeTokens = resolvedTheme === 'dark' ? theme.dark : theme.light;
+
+  return {
+    ...context,
+    tokens: activeTokens,
+  };
+}

package/src/index.ts

@@ -53,4 +53,5 @@ export * from './components/ui/toggle-group';
 export * from './components/ui/tooltip';
 
 // Hooks
+export * from './hooks/use-theme';
 export * from './hooks/use-toast';

package/src/pages/components/ThemeToggleDocs.tsx

@@ -30,23 +30,48 @@ export function ThemeToggleDocs() {
       </ComponentShowcase>
 
       <ComponentShowcase
-        title="Custom State Integration"
-        description="You can control the theme externally by passing customTheme and onThemeChange props."
+        title="Controlled Mode"
+        description="You can control the theme externally by passing customTheme and onThemeChange props. This is useful for testing or when using a different theme provider."
         code={`const [theme, setTheme] = useState('light');
 
 <ThemeToggle
   customTheme={theme}
-  onThemeChange={(newTheme) => setTheme(newTheme)}
+  onThemeChange={setTheme}
 />
 
 <p>Current Theme: {theme}</p>`}
       >
         <div className="flex flex-col items-center gap-4">
-          <ThemeToggle customTheme={customTheme} onThemeChange={(newTheme) => setCustomTheme(newTheme)} />
+          <ThemeToggle customTheme={customTheme} onThemeChange={setCustomTheme} />
           <p className="text-sm font-medium">Current Selection: {customTheme}</p>
         </div>
       </ComponentShowcase>
 
+      <div className="space-y-4">
+        <h3 className="text-xl font-semibold">useTheme Hook</h3>
+        <p className="text-sm text-muted-foreground">
+          The `useTheme` hook provides access to the current theme and the active design tokens.
+        </p>
+        <div className="rounded-md border bg-muted p-4">
+          <pre className="text-xs">
+            <code>
+              {`import { useTheme } from '@gv-tech/design-system';
+
+export function MyComponent() {
+  const { theme, setTheme, tokens } = useTheme();
+
+  return (
+    <div style={{ backgroundColor: tokens.background }}>
+      <p>Current theme: {theme}</p>
+      <button onClick={() => setTheme('dark')}>Dark Mode</button>
+    </div>
+  );
+}`}
+            </code>
+          </pre>
+        </div>
+      </div>
+
       <div className="space-y-4">
         <h3 className="text-xl font-semibold">ThemeToggle Props</h3>
         <PropsTable
@@ -104,14 +129,16 @@ export function ThemeToggleDocs() {
           </div>
 
           <div className="rounded-lg border bg-muted/50 p-6">
-            <h4 className="font-medium text-foreground">Custom Provider</h4>
+            <h4 className="font-medium text-foreground">Controlled / Custom State</h4>
             <p className="mt-1 text-sm text-muted-foreground">
               Pass your own theme state and change handler to integrate with custom logic or external storage.
             </p>
             <pre className="mt-4 overflow-x-auto rounded-md bg-background p-4 text-xs">
-              <code>{`<ThemeToggle 
-  customTheme={myTheme} 
-  onThemeChange={(t) => updateMyTheme(t)} 
+              <code>{`const [theme, setTheme] = useState("light")
+
+<ThemeToggle 
+  customTheme={theme} 
+  onThemeChange={setTheme} 
 />`}</code>
             </pre>
           </div>