@gv-tech/design-system 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gv-tech/design-system",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Garcia Ventures react design system",
   "repository": "git@github.com:Garcia-Ventures/gvtech-design.git",
   "license": "MIT",
@@ -99,7 +99,6 @@
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
     "lucide-react": "^0.563.0",
-    "next-themes": "^0.4.6",
     "react-day-picker": "^9.13.2",
     "react-hook-form": "^7.71.1",
     "react-icons": "^5.5.0",
@@ -131,6 +130,7 @@
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
     "lint-staged": "^16.2.7",
+    "next-themes": "^0.4.6",
     "postcss": "^8.5.6",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
@@ -145,6 +145,7 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
+    "next-themes": "^0.4.0",
     "prop-types": "^15.8.0",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19",

package/src/App.tsx

@@ -1,4 +1,3 @@
-import { ThemeProvider } from 'next-themes';
 import * as React from 'react';
 import { Footer, Sidebar } from './components/docs';
 import { navItems } from './components/docs/Sidebar';
@@ -21,6 +20,7 @@ import {
   SearchTrigger,
 } from './components/ui/search';
 import { Toaster as SonnerToaster } from './components/ui/sonner';
+import { ThemeProvider } from './components/ui/theme-provider';
 import { ThemeToggle } from './components/ui/theme-toggle';
 import { Toaster } from './components/ui/toaster';
 import { TooltipProvider } from './components/ui/tooltip';
@@ -205,7 +205,7 @@ function App() {
   };
 
   return (
-    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+    <ThemeProvider>
       <TooltipProvider>
         <div className="flex h-screen bg-background">
           {/* Sidebar */}

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

@@ -0,0 +1,47 @@
+import { ThemeProvider } from '@/components/ui/theme-provider';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+describe('ThemeProvider', () => {
+  it('renders children correctly', () => {
+    render(
+      <ThemeProvider>
+        <div data-testid="child">Hello</div>
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('child')).toBeInTheDocument();
+    expect(screen.getByTestId('child')).toHaveTextContent('Hello');
+  });
+
+  it('applies class attribute to html element by default', () => {
+    render(
+      <ThemeProvider>
+        <div>Content</div>
+      </ThemeProvider>,
+    );
+    // next-themes applies the attribute to the html element;
+    // in jsdom the attribute should be set to 'class' by default
+    const html = document.documentElement;
+    // The attribute prop controls how the theme class is toggled.
+    // We verify the provider renders without error, which confirms the defaults are valid.
+    expect(html).toBeDefined();
+  });
+
+  it('allows overriding default props', () => {
+    render(
+      <ThemeProvider defaultTheme="dark" enableSystem={false}>
+        <div data-testid="child">Dark Mode</div>
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('child')).toBeInTheDocument();
+  });
+
+  it('passes additional next-themes props through', () => {
+    render(
+      <ThemeProvider storageKey="my-app-theme" themes={['light', 'dark', 'ocean']}>
+        <div data-testid="child">Custom themes</div>
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('child')).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,12 @@
+import type { ThemeProviderProps as NextThemesProviderProps } from 'next-themes';
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+
+export type ThemeProviderProps = NextThemesProviderProps;
+
+export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
+  return (
+    <NextThemesProvider attribute="class" defaultTheme="system" enableSystem {...props}>
+      {children}
+    </NextThemesProvider>
+  );
+}

package/src/index.ts

@@ -45,6 +45,7 @@ export * from './components/ui/switch';
 export * from './components/ui/table';
 export * from './components/ui/tabs';
 export * from './components/ui/textarea';
+export * from './components/ui/theme-provider';
 export * from './components/ui/theme-toggle';
 export * from './components/ui/toast';
 export { Toaster as ToasterToast } from './components/ui/toaster';

package/src/pages/GettingStarted.tsx

@@ -133,10 +133,34 @@ export function InstallationPage() {
         <CodeBlock
           code={`{
   "react": "^18 || ^19",
-  "react-dom": "^18 || ^19"
+  "react-dom": "^18 || ^19",
+  "next-themes": "^0.4.0"
 }`}
           language="json"
         />
+        <p className="text-sm text-muted-foreground">
+          <code className="text-sm bg-muted px-1.5 py-0.5 rounded">next-themes</code> is required for the design
+          system's <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code>,{' '}
+          <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeToggle</code>, and{' '}
+          <code className="text-sm bg-muted px-1.5 py-0.5 rounded">useTheme</code> to work. Install it alongside the
+          design system:
+        </p>
+        <Tabs defaultValue="npm" className="w-full">
+          <TabsList>
+            <TabsTrigger value="npm">npm</TabsTrigger>
+            <TabsTrigger value="yarn">yarn</TabsTrigger>
+            <TabsTrigger value="pnpm">pnpm</TabsTrigger>
+          </TabsList>
+          <TabsContent value="npm" className="mt-4">
+            <CodeBlock code="npm install next-themes" language="bash" />
+          </TabsContent>
+          <TabsContent value="yarn" className="mt-4">
+            <CodeBlock code="yarn add next-themes" language="bash" />
+          </TabsContent>
+          <TabsContent value="pnpm" className="mt-4">
+            <CodeBlock code="pnpm add next-themes" language="bash" />
+          </TabsContent>
+        </Tabs>
       </section>
 
       <section className="space-y-4">
@@ -253,15 +277,22 @@ module.exports = {
 
       <section className="space-y-4">
         <h2 className="text-2xl font-semibold tracking-tight">Start Using Components</h2>
-        <p className="text-muted-foreground">Now you can import and use components from the design system:</p>
+        <p className="text-muted-foreground">
+          Wrap your app with <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code> and start
+          importing components:
+        </p>
         <CodeBlock
-          code={`import { Button } from '@gv-tech/design-system';
+          code={`import { ThemeProvider, ThemeToggle, Button } from '@gv-tech/design-system';
+import '@gv-tech/design-system/style.css';
 
 export default function App() {
   return (
-    <Button variant="default">
-      Click me
-    </Button>
+    <ThemeProvider>
+      <div>
+        <ThemeToggle variant="ternary" />
+        <Button variant="default">Click me</Button>
+      </div>
+    </ThemeProvider>
   );
 }`}
         />

package/src/pages/components/ThemeToggleDocs.tsx

@@ -47,10 +47,107 @@ export function ThemeToggleDocs() {
         </div>
       </ComponentShowcase>
 
-      <div className="space-y-4">
+      {/* ThemeProvider Section */}
+      <div className="mt-12 space-y-6">
+        <div>
+          <h3 className="text-xl font-semibold">ThemeProvider</h3>
+          <p className="mt-2 text-muted-foreground">
+            The design system exports a pre-configured{' '}
+            <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code> that wraps{' '}
+            <code className="text-sm bg-muted px-1.5 py-0.5 rounded">next-themes</code> with sensible defaults. Wrap
+            your application with it to enable theme switching for all design system components.
+          </p>
+        </div>
+
+        <div className="rounded-md border bg-muted p-4">
+          <pre className="text-xs">
+            <code>
+              {`import { ThemeProvider, ThemeToggle } from '@gv-tech/design-system';
+import '@gv-tech/design-system/style.css';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <ThemeToggle variant="ternary" />
+      {/* Your app content */}
+    </ThemeProvider>
+  );
+}`}
+            </code>
+          </pre>
+        </div>
+
+        <div className="space-y-4">
+          <h4 className="font-medium text-foreground">Defaults</h4>
+          <p className="text-sm text-muted-foreground">
+            Out of the box, <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code> applies these
+            defaults. You can override any of them by passing the corresponding prop.
+          </p>
+          <div className="rounded-md border">
+            <table className="w-full text-sm">
+              <thead>
+                <tr className="border-b bg-muted/50">
+                  <th className="p-3 text-left font-medium">Prop</th>
+                  <th className="p-3 text-left font-medium">Default</th>
+                  <th className="p-3 text-left font-medium">Description</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr className="border-b">
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">attribute</code>
+                  </td>
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">"class"</code>
+                  </td>
+                  <td className="p-3 text-muted-foreground">Applies the theme as a CSS class on the HTML element</td>
+                </tr>
+                <tr className="border-b">
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">defaultTheme</code>
+                  </td>
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">"system"</code>
+                  </td>
+                  <td className="p-3 text-muted-foreground">Respects the user's operating system preference</td>
+                </tr>
+                <tr>
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">enableSystem</code>
+                  </td>
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">true</code>
+                  </td>
+                  <td className="p-3 text-muted-foreground">Enables automatic detection of the OS color scheme</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
+
+        <div className="rounded-md border bg-muted p-4">
+          <p className="text-xs font-medium text-muted-foreground mb-2">Overriding defaults:</p>
+          <pre className="text-xs">
+            <code>
+              {`<ThemeProvider
+  defaultTheme="dark"
+  storageKey="my-app-theme"
+  themes={['light', 'dark', 'ocean']}
+>
+  <App />
+</ThemeProvider>`}
+            </code>
+          </pre>
+        </div>
+      </div>
+
+      {/* useTheme Section */}
+      <div className="mt-12 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.
+          The <code className="text-sm bg-muted px-1.5 py-0.5 rounded">useTheme</code> hook provides access to the
+          current theme, theme controls, and the active design tokens. It must be used within a{' '}
+          <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code>.
         </p>
         <div className="rounded-md border bg-muted p-4">
           <pre className="text-xs">
@@ -58,11 +155,12 @@ export function ThemeToggleDocs() {
               {`import { useTheme } from '@gv-tech/design-system';
 
 export function MyComponent() {
-  const { theme, setTheme, tokens } = useTheme();
+  const { theme, setTheme, resolvedTheme, tokens } = useTheme();
 
   return (
     <div style={{ backgroundColor: tokens.background }}>
       <p>Current theme: {theme}</p>
+      <p>Resolved theme: {resolvedTheme}</p>
       <button onClick={() => setTheme('dark')}>Dark Mode</button>
     </div>
   );
@@ -70,8 +168,40 @@ export function MyComponent() {
             </code>
           </pre>
         </div>
+
+        <PropsTable
+          props={[
+            {
+              name: 'theme',
+              type: 'string',
+              required: false,
+              description: 'The current theme name ("light", "dark", or "system").',
+            },
+            {
+              name: 'setTheme',
+              type: '(theme: string) => void',
+              required: false,
+              description: 'Function to programmatically change the theme.',
+            },
+            {
+              name: 'resolvedTheme',
+              type: 'string',
+              required: false,
+              description:
+                'The resolved theme ("light" or "dark"). Useful when theme is "system" and you need the actual value.',
+            },
+            {
+              name: 'tokens',
+              type: 'ThemeTokens',
+              required: false,
+              description:
+                'The active color tokens for the current resolved theme (light or dark). Contains background, foreground, primary, and other design token values.',
+            },
+          ]}
+        />
       </div>
 
+      {/* ThemeToggle Props Section */}
       <div className="space-y-4">
         <h3 className="text-xl font-semibold">ThemeToggle Props</h3>
         <PropsTable
@@ -106,23 +236,29 @@ export function MyComponent() {
         />
       </div>
 
+      {/* Integration Section */}
       <div className="mt-12 space-y-6">
         <div>
           <h3 className="text-xl font-semibold">Integration</h3>
           <p className="mt-2 text-muted-foreground">
-            The `ThemeToggle` component is built to be flexible and works seamlessly with `next-themes` by default, but
-            it can also be used in a fully controlled manner with any theme provider or custom state.
+            The <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeToggle</code> component works seamlessly
+            with the design system's <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code>. It
+            can also be used in a fully controlled manner with any theme provider or custom state.
           </p>
         </div>
 
         <div className="grid gap-6 md:grid-cols-2">
           <div className="rounded-lg border bg-muted/50 p-6">
-            <h4 className="font-medium text-foreground">With next-themes</h4>
+            <h4 className="font-medium text-foreground">With ThemeProvider (Recommended)</h4>
             <p className="mt-1 text-sm text-muted-foreground">
-              Simply drop the component anywhere. It will automatically detect the `ThemeProvider` and handle switching.
+              Wrap your app with the design system's{' '}
+              <code className="text-xs bg-muted px-1 py-0.5 rounded">ThemeProvider</code> and drop in the toggle.
+              Everything connects automatically.
             </p>
             <pre className="mt-4 overflow-x-auto rounded-md bg-background p-4 text-xs">
-              <code>{`<ThemeProvider attribute="class">
+              <code>{`import { ThemeProvider, ThemeToggle } from '@gv-tech/design-system';
+
+<ThemeProvider>
   <ThemeToggle />
 </ThemeProvider>`}</code>
             </pre>
@@ -143,6 +279,17 @@ export function MyComponent() {
             </pre>
           </div>
         </div>
+
+        <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-6">
+          <h4 className="font-medium text-amber-600 dark:text-amber-400">⚠️ Important: Shared Context</h4>
+          <p className="mt-1 text-sm text-muted-foreground">
+            The design system marks <code className="text-xs bg-muted px-1 py-0.5 rounded">next-themes</code> as a{' '}
+            <strong>peer dependency</strong>, meaning it uses the same instance as your project. This ensures that{' '}
+            <code className="text-xs bg-muted px-1 py-0.5 rounded">useTheme</code>,{' '}
+            <code className="text-xs bg-muted px-1 py-0.5 rounded">ThemeToggle</code>, and your own components all share
+            the same theme context — no duplicate providers needed.
+          </p>
+        </div>
       </div>
     </ComponentSection>
   );

package/vite.config.ts

@@ -27,13 +27,14 @@ export default defineConfig({
         }
       : undefined,
     rollupOptions: {
-      external: isLibrary ? ['react', 'react-dom', 'prop-types'] : [],
+      external: isLibrary ? ['react', 'react-dom', 'prop-types', 'next-themes'] : [],
       output: {
         globals: isLibrary
           ? {
               react: 'React',
               'react-dom': 'ReactDOM',
               'prop-types': 'PropTypes',
+              'next-themes': 'NextThemes',
             }
           : {},
         manualChunks(id) {