diff --git a/apps/www/src/app/examples/scoped-theme/page.tsx b/apps/www/src/app/examples/scoped-theme/page.tsx
new file mode 100644
index 000000000..388ddad2a
--- /dev/null
+++ b/apps/www/src/app/examples/scoped-theme/page.tsx
@@ -0,0 +1,131 @@
+'use client';
+
+import {
+  Button,
+  Callout,
+  Flex,
+  IconButton,
+  Text,
+  ThemeProvider
+} from '@raystack/apsara';
+import { Moon, Sun } from 'lucide-react';
+import { useState } from 'react';
+import { useTheme } from '@/components/theme';
+
+type ScopeTheme = 'light' | 'dark';
+
+const panelStyle = {
+  minWidth: 320,
+  padding: 'var(--rs-space-7)',
+  borderRadius: 'var(--rs-space-3)',
+  border: '1px solid var(--rs-color-border-base-primary)',
+  backgroundColor: 'var(--rs-color-background-base-primary)'
+};
+
+const Page = () => {
+  const { theme, setTheme } = useTheme();
+  const [scopeTheme, setScopeTheme] = useState<ScopeTheme>('dark');
+  const [calloutScopeTheme, setCalloutScopeTheme] =
+    useState<ScopeTheme>('light');
+  const GlobalIcon = theme === 'dark' ? Sun : Moon;
+
+  return (
+    <Flex
+      direction='column'
+      gap={9}
+      style={{
+        minHeight: '100vh',
+        padding: 'var(--rs-space-11)',
+        backgroundColor: 'var(--rs-color-background-base-primary)'
+      }}
+    >
+      <Flex justify='between' align='center'>
+        <Text size={6} weight={500}>
+          Scoped Theming
+        </Text>
+        <IconButton
+          aria-label='Toggle page theme'
+          size={3}
+          onClick={() =>
+            setTheme({ theme: theme === 'dark' ? 'light' : 'dark' })
+          }
+        >
+          <GlobalIcon />
+        </IconButton>
+      </Flex>
+
+      <ThemeProvider forcedTheme={scopeTheme}>
+        <Flex
+          direction='column'
+          gap={5}
+          style={{ ...panelStyle, alignSelf: 'flex-start' }}
+        >
+          <Flex justify='between' align='center' gap={5}>
+            <Text size={4} weight={500}>
+              Scoped box
+            </Text>
+            <IconButton
+              aria-label='Toggle scope theme'
+              size={3}
+              onClick={() =>
+                setScopeTheme(scopeTheme === 'dark' ? 'light' : 'dark')
+              }
+            >
+              {scopeTheme === 'dark' ? <Sun /> : <Moon />}
+            </IconButton>
+          </Flex>
+          <Text size={3} variant='secondary'>
+            This box themes itself via{' '}
+            <code>data-theme=&quot;{scopeTheme}&quot;</code>, independent of the
+            page.
+          </Text>
+          <Flex gap={3}>
+            <Button variant='solid' color='accent'>
+              Solid
+            </Button>
+            <Button variant='outline' color='neutral'>
+              Outline
+            </Button>
+          </Flex>
+        </Flex>
+      </ThemeProvider>
+
+      <ThemeProvider forcedTheme={calloutScopeTheme}>
+        <Flex
+          direction='column'
+          gap={4}
+          style={{ ...panelStyle, alignSelf: 'flex-start' }}
+        >
+          <Flex justify='between' align='center' gap={5}>
+            <Text size={4} weight={500}>
+              Semantic colors in scope
+            </Text>
+            <IconButton
+              aria-label='Toggle callout scope theme'
+              size={3}
+              onClick={() =>
+                setCalloutScopeTheme(
+                  calloutScopeTheme === 'dark' ? 'light' : 'dark'
+                )
+              }
+            >
+              {calloutScopeTheme === 'dark' ? <Sun /> : <Moon />}
+            </IconButton>
+          </Flex>
+          <Text size={3} variant='secondary'>
+            Accent, success, danger, and attention tokens all re-resolve at the
+            scope.
+          </Text>
+          <Callout type='accent'>Accent — informational message</Callout>
+          <Callout type='success'>Success — operation completed</Callout>
+          <Callout type='alert'>Danger — something went wrong</Callout>
+          <Callout type='attention'>
+            Attention — review before continuing
+          </Callout>
+        </Flex>
+      </ThemeProvider>
+    </Flex>
+  );
+};
+
+export default Page;
diff --git a/apps/www/src/app/examples/theme-overrides/page.tsx b/apps/www/src/app/examples/theme-overrides/page.tsx
new file mode 100644
index 000000000..33b6892fc
--- /dev/null
+++ b/apps/www/src/app/examples/theme-overrides/page.tsx
@@ -0,0 +1,261 @@
+'use client';
+
+import {
+  Button,
+  Callout,
+  Flex,
+  IconButton,
+  Text,
+  ThemeProvider
+} from '@raystack/apsara';
+import { Moon, Sun } from 'lucide-react';
+import { useState } from 'react';
+import { useTheme } from '@/components/theme';
+
+type Accent = 'indigo' | 'orange' | 'mint';
+type Gray = 'gray' | 'mauve' | 'slate';
+type Style = 'modern' | 'traditional';
+type Scheme = 'light' | 'dark';
+
+const ACCENTS: Accent[] = ['indigo', 'orange', 'mint'];
+const GRAYS: Gray[] = ['gray', 'mauve', 'slate'];
+
+const panelStyle = {
+  padding: 'var(--rs-space-7)',
+  borderRadius: 'var(--rs-space-3)',
+  border: '1px solid var(--rs-color-border-base-primary)',
+  backgroundColor: 'var(--rs-color-background-base-primary)'
+};
+
+const cycle = <T,>(values: T[], current: T): T =>
+  values[(values.indexOf(current) + 1) % values.length];
+
+const Page = () => {
+  const { theme, setTheme } = useTheme();
+  const GlobalIcon = theme === 'dark' ? Sun : Moon;
+
+  const [accentScheme, setAccentScheme] = useState<Scheme>('light');
+  const [accent, setAccent] = useState<Accent>('orange');
+
+  const [grayScheme, setGrayScheme] = useState<Scheme>('light');
+  const [gray, setGray] = useState<Gray>('mauve');
+
+  const [styleScheme, setStyleScheme] = useState<Scheme>('light');
+  const [variant, setVariant] = useState<Style>('traditional');
+
+  const [fullScheme, setFullScheme] = useState<Scheme>('dark');
+
+  return (
+    <Flex
+      direction='column'
+      gap={9}
+      style={{
+        minHeight: '100vh',
+        padding: 'var(--rs-space-11)',
+        backgroundColor: 'var(--rs-color-background-base-primary)'
+      }}
+    >
+      <Flex justify='between' align='center'>
+        <Flex direction='column' gap={2}>
+          <Text size={6} weight={500}>
+            Theme Overrides
+          </Text>
+          <Text size={3} variant='secondary'>
+            Each panel nests a `ThemeProvider` that overrides one or more tokens
+            for its subtree. Use the switches inside each panel to change the
+            scope&apos;s theme and tokens — the page-level theme is untouched.
+          </Text>
+        </Flex>
+        <IconButton
+          aria-label='Toggle page theme'
+          size={3}
+          onClick={() =>
+            setTheme({ theme: theme === 'dark' ? 'light' : 'dark' })
+          }
+        >
+          <GlobalIcon />
+        </IconButton>
+      </Flex>
+
+      <div
+        style={{
+          display: 'grid',
+          gridTemplateColumns: 'repeat(auto-fit, minmax(320px, 1fr))',
+          gap: 'var(--rs-space-7)'
+        }}
+      >
+        <ThemeProvider forcedTheme={accentScheme} accentColor={accent}>
+          <Flex direction='column' gap={5} style={panelStyle}>
+            <Flex justify='between' align='center' gap={5}>
+              <Text size={4} weight={500}>
+                Accent override
+              </Text>
+              <Flex gap={3} align='center'>
+                <Button
+                  variant='outline'
+                  color='neutral'
+                  onClick={() => setAccent(cycle(ACCENTS, accent))}
+                >
+                  {accent}
+                </Button>
+                <IconButton
+                  aria-label='Toggle accent scope theme'
+                  size={3}
+                  onClick={() =>
+                    setAccentScheme(accentScheme === 'dark' ? 'light' : 'dark')
+                  }
+                >
+                  {accentScheme === 'dark' ? <Sun /> : <Moon />}
+                </IconButton>
+              </Flex>
+            </Flex>
+            <Text size={3} variant='secondary'>
+              <code>accentColor=&quot;{accent}&quot;</code>. Only the accent
+              token changes here.
+            </Text>
+            <Flex gap={3}>
+              <Button variant='solid' color='accent'>
+                Solid
+              </Button>
+              <Button variant='outline' color='accent'>
+                Outline
+              </Button>
+            </Flex>
+            <Callout type='accent'>
+              Accent uses the scope&apos;s {accent}
+            </Callout>
+          </Flex>
+        </ThemeProvider>
+
+        <ThemeProvider forcedTheme={grayScheme} grayColor={gray}>
+          <Flex direction='column' gap={5} style={panelStyle}>
+            <Flex justify='between' align='center' gap={5}>
+              <Text size={4} weight={500}>
+                Gray override
+              </Text>
+              <Flex gap={3} align='center'>
+                <Button
+                  variant='outline'
+                  color='neutral'
+                  onClick={() => setGray(cycle(GRAYS, gray))}
+                >
+                  {gray}
+                </Button>
+                <IconButton
+                  aria-label='Toggle gray scope theme'
+                  size={3}
+                  onClick={() =>
+                    setGrayScheme(grayScheme === 'dark' ? 'light' : 'dark')
+                  }
+                >
+                  {grayScheme === 'dark' ? <Sun /> : <Moon />}
+                </IconButton>
+              </Flex>
+            </Flex>
+            <Text size={3} variant='secondary'>
+              <code>grayColor=&quot;{gray}&quot;</code>. Neutral surfaces, text,
+              and borders shift hue.
+            </Text>
+            <Flex gap={3}>
+              <Button variant='solid' color='neutral'>
+                Neutral
+              </Button>
+              <Button variant='outline' color='neutral'>
+                Outline
+              </Button>
+            </Flex>
+            <Callout type='grey'>
+              Neutral callout picks up the {gray} grays
+            </Callout>
+          </Flex>
+        </ThemeProvider>
+
+        <ThemeProvider forcedTheme={styleScheme} style={variant}>
+          <Flex direction='column' gap={5} style={panelStyle}>
+            <Flex justify='between' align='center' gap={5}>
+              <Text size={4} weight={500}>
+                Style override
+              </Text>
+              <Flex gap={3} align='center'>
+                <Button
+                  variant='outline'
+                  color='neutral'
+                  onClick={() =>
+                    setVariant(variant === 'modern' ? 'traditional' : 'modern')
+                  }
+                >
+                  {variant}
+                </Button>
+                <IconButton
+                  aria-label='Toggle style scope theme'
+                  size={3}
+                  onClick={() =>
+                    setStyleScheme(styleScheme === 'dark' ? 'light' : 'dark')
+                  }
+                >
+                  {styleScheme === 'dark' ? <Sun /> : <Moon />}
+                </IconButton>
+              </Flex>
+            </Flex>
+            <Text size={3} variant='secondary'>
+              <code>style=&quot;{variant}&quot;</code>. Radius and font tokens
+              flip; same colors as the page.
+            </Text>
+            <Flex gap={3}>
+              <Button variant='solid' color='accent'>
+                Solid
+              </Button>
+              <Button variant='outline' color='neutral'>
+                Outline
+              </Button>
+            </Flex>
+            <Callout type='attention'>
+              Edges are softer; type metrics shift
+            </Callout>
+          </Flex>
+        </ThemeProvider>
+
+        <ThemeProvider
+          forcedTheme={fullScheme}
+          accentColor='mint'
+          grayColor='slate'
+          style='modern'
+        >
+          <Flex direction='column' gap={5} style={panelStyle}>
+            <Flex justify='between' align='center' gap={5}>
+              <Text size={4} weight={500}>
+                Full override
+              </Text>
+              <IconButton
+                aria-label='Toggle full scope theme'
+                size={3}
+                onClick={() =>
+                  setFullScheme(fullScheme === 'dark' ? 'light' : 'dark')
+                }
+              >
+                {fullScheme === 'dark' ? <Sun /> : <Moon />}
+              </IconButton>
+            </Flex>
+            <Text size={3} variant='secondary'>
+              Theme, accent, gray, and style all set explicitly. The scope is
+              independent of the page&apos;s appearance.
+            </Text>
+            <Flex gap={3}>
+              <Button variant='solid' color='accent'>
+                Solid
+              </Button>
+              <Button variant='outline' color='neutral'>
+                Outline
+              </Button>
+            </Flex>
+            <Callout type='success'>
+              All four data-* attributes set on this subtree
+            </Callout>
+          </Flex>
+        </ThemeProvider>
+      </div>
+    </Flex>
+  );
+};
+
+export default Page;
diff --git a/apps/www/src/content/docs/theme/overview/index.mdx b/apps/www/src/content/docs/theme/overview/index.mdx
index 5d72b418b..240876389 100644
--- a/apps/www/src/content/docs/theme/overview/index.mdx
+++ b/apps/www/src/content/docs/theme/overview/index.mdx
@@ -132,3 +132,73 @@ export default function RootLayout({ children }) {
 ```
 
 The `suppressHydrationWarning` is required because the theme script modifies the HTML element before React hydrates.
+
+## Scoped Theming
+
+Themes are not limited to the document root. Any element with a `data-theme` attribute creates an isolated theme scope — descendants resolve every design token from the nearest scoped ancestor. This enables theme preview cards, split-screen comparisons, and dark sidebars in light apps without any extra plumbing.
+
+### Bare attribute
+
+Because scoping is implemented in CSS, you can opt in by simply setting the attribute on any element:
+
+```tsx
+<html data-theme="dark">
+  {/* Page is dark */}
+  <div data-theme="light">
+    {/* This subtree renders with light tokens */}
+    <Button>Light button inside dark page</Button>
+  </div>
+</html>
+```
+
+The package's stylesheet handles the rest: every `--rs-color-*` token, `color-scheme` for native form controls and scrollbars, and the smooth transition during theme switches all follow the scoped attribute.
+
+### Nested `ThemeProvider`
+
+For a typed convenience wrapper, nest `ThemeProvider`:
+
+```tsx
+import { ThemeProvider } from "@raystack/apsara";
+
+<ThemeProvider forcedTheme="dark">
+  <Card>Dark scoped card</Card>
+</ThemeProvider>
+```
+
+When `ThemeProvider` is rendered inside another `ThemeProvider`, it switches to scope mode: it writes `data-theme` (and optionally `data-accent-color`, `data-gray-color`, `data-style`) onto a wrapper `<div>` rather than the document root. The outer provider's state remains the source of truth for `useTheme()`.
+
+### Combining with accent and gray overrides
+
+A scope can override accent or gray independently of theme. This is useful for highlighting a section without changing its color scheme:
+
+```tsx
+<ThemeProvider accentColor="orange">
+  <Button color="accent">Orange accent in this region only</Button>
+</ThemeProvider>
+
+<ThemeProvider forcedTheme="dark" accentColor="mint" grayColor="slate">
+  <Card>Dark mint-on-slate card</Card>
+</ThemeProvider>
+```
+
+### State management
+
+Nested `ThemeProvider` is stateless — the consumer owns the theme value. For an interactive scope, drive it with React state:
+
+```tsx
+const [scopeTheme, setScopeTheme] = useState<'light' | 'dark'>('dark');
+
+<ThemeProvider forcedTheme={scopeTheme}>
+  <Toggle onClick={() => setScopeTheme(t => t === 'dark' ? 'light' : 'dark')}>
+    Toggle this scope
+  </Toggle>
+  <Card>...</Card>
+</ThemeProvider>
+```
+
+If you need persistence across page loads, manage it yourself with `localStorage` and a `useEffect`. Nested providers deliberately avoid touching storage to keep them pure and to avoid disambiguation issues when multiple scopes share a page.
+
+### When to reach for a nested provider vs. the bare attribute
+
+- Use the **bare `data-theme` attribute** when you're already rendering a custom element and don't want another wrapper. The CSS handles everything — components inside will theme correctly.
+- Use a **nested `ThemeProvider`** when you want typed props (`forcedTheme`, `accentColor`, etc.) and a single import that documents intent.
diff --git a/packages/raystack/components/theme-provider/__tests__/theme-provider.test.tsx b/packages/raystack/components/theme-provider/__tests__/theme-provider.test.tsx
index d794b1f0d..4a1dc8ddd 100644
--- a/packages/raystack/components/theme-provider/__tests__/theme-provider.test.tsx
+++ b/packages/raystack/components/theme-provider/__tests__/theme-provider.test.tsx
@@ -1,4 +1,5 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { useState } from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { ThemeSwitcher } from '../switcher';
 import { ThemeProvider, useTheme } from '../theme';
@@ -261,6 +262,97 @@ describe('ThemeProvider', () => {
     });
   });
 
+  describe('resolvedTheme', () => {
+    it('reflects forcedTheme when set', () => {
+      const Probe = () => {
+        const { resolvedTheme } = useTheme();
+        return <span data-testid='resolved'>{resolvedTheme}</span>;
+      };
+
+      render(
+        <ThemeProvider
+          defaultTheme='light'
+          enableSystem={false}
+          forcedTheme='dark'
+        >
+          <Probe />
+        </ThemeProvider>
+      );
+
+      expect(screen.getByTestId('resolved')).toHaveTextContent('dark');
+    });
+  });
+
+  describe('onThemeChange', () => {
+    it('does not fire on initial mount', async () => {
+      const handler = vi.fn();
+
+      render(
+        <ThemeProvider
+          defaultTheme='light'
+          enableSystem={false}
+          onThemeChange={handler}
+        >
+          <div />
+        </ThemeProvider>
+      );
+
+      // Settle any post-mount effects (media-query listener + re-render).
+      await waitFor(() => {
+        expect(document.documentElement.getAttribute('data-theme')).toBe(
+          'light'
+        );
+      });
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('fires when setTheme changes the theme', () => {
+      const handler = vi.fn();
+      const Probe = () => {
+        const { setTheme } = useTheme();
+        return <button onClick={() => setTheme('dark')}>set</button>;
+      };
+
+      render(
+        <ThemeProvider
+          defaultTheme='light'
+          enableSystem={false}
+          onThemeChange={handler}
+        >
+          <Probe />
+        </ThemeProvider>
+      );
+
+      fireEvent.click(screen.getByText('set'));
+      expect(handler).toHaveBeenCalledWith('dark', 'dark');
+    });
+
+    it('does not over-fire when the consumer passes an inline callback', () => {
+      const handler = vi.fn();
+      const Tree = () => {
+        const [count, setCount] = useState(0);
+        return (
+          <ThemeProvider
+            defaultTheme='light'
+            enableSystem={false}
+            // Inline arrow: a fresh function identity every render.
+            onThemeChange={(t, r) => handler(t, r)}
+          >
+            <button onClick={() => setCount(c => c + 1)}>bump {count}</button>
+          </ThemeProvider>
+        );
+      };
+
+      render(<Tree />);
+      fireEvent.click(screen.getByText(/bump/));
+      fireEvent.click(screen.getByText(/bump/));
+
+      // Theme never changed; consumer re-renders shouldn't drive the callback.
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
   describe('Local Storage Integration', () => {
     it('reads initial theme from localStorage', () => {
       localStorageMock.getItem.mockReturnValue('dark');
diff --git a/packages/raystack/components/theme-provider/__tests__/theme-scope.test.tsx b/packages/raystack/components/theme-provider/__tests__/theme-scope.test.tsx
new file mode 100644
index 000000000..2921b2a5a
--- /dev/null
+++ b/packages/raystack/components/theme-provider/__tests__/theme-scope.test.tsx
@@ -0,0 +1,182 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ThemeProvider, useTheme } from '../theme';
+
+// jsdom doesn't ship these; the root ThemeProvider needs them on mount.
+Object.defineProperty(window, 'localStorage', {
+  value: {
+    getItem: vi.fn(),
+    setItem: vi.fn(),
+    removeItem: vi.fn(),
+    clear: vi.fn()
+  }
+});
+
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: vi.fn().mockImplementation(query => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn()
+  }))
+});
+
+const localStorageMock = window.localStorage as unknown as {
+  getItem: ReturnType<typeof vi.fn>;
+  setItem: ReturnType<typeof vi.fn>;
+};
+
+beforeEach(() => {
+  localStorageMock.getItem.mockClear();
+  localStorageMock.setItem.mockClear();
+  document.documentElement.removeAttribute('data-theme');
+  document.documentElement.removeAttribute('data-style');
+  document.documentElement.removeAttribute('data-accent-color');
+  document.documentElement.removeAttribute('data-gray-color');
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+// Nested usage: ThemeProvider renders a scoped wrapper with data-* attrs.
+describe('ThemeProvider (scoped)', () => {
+  it('renders a div wrapper with children when nested', () => {
+    render(
+      <ThemeProvider>
+        <ThemeProvider forcedTheme='dark'>
+          <span data-testid='child'>inside</span>
+        </ThemeProvider>
+      </ThemeProvider>
+    );
+
+    const child = screen.getByTestId('child');
+    expect(child.parentElement?.tagName).toBe('DIV');
+    expect(screen.getByText('inside')).toBeInTheDocument();
+  });
+
+  it('writes data-theme on the scoped wrapper', () => {
+    render(
+      <ThemeProvider>
+        <ThemeProvider forcedTheme='dark'>
+          <span data-testid='child' />
+        </ThemeProvider>
+      </ThemeProvider>
+    );
+
+    expect(screen.getByTestId('child').parentElement).toHaveAttribute(
+      'data-theme',
+      'dark'
+    );
+  });
+
+  it('omits data attributes when their props are not provided', () => {
+    render(
+      <ThemeProvider>
+        <ThemeProvider>
+          <span data-testid='child' />
+        </ThemeProvider>
+      </ThemeProvider>
+    );
+
+    const wrapper = screen.getByTestId('child').parentElement!;
+    expect(wrapper).not.toHaveAttribute('data-theme');
+    expect(wrapper).not.toHaveAttribute('data-accent-color');
+    expect(wrapper).not.toHaveAttribute('data-gray-color');
+    expect(wrapper).not.toHaveAttribute('data-style');
+  });
+
+  it('writes every supported data attribute', () => {
+    render(
+      <ThemeProvider>
+        <ThemeProvider
+          forcedTheme='light'
+          accentColor='orange'
+          grayColor='mauve'
+          style='traditional'
+        >
+          <span data-testid='child' />
+        </ThemeProvider>
+      </ThemeProvider>
+    );
+
+    const wrapper = screen.getByTestId('child').parentElement!;
+    expect(wrapper).toHaveAttribute('data-theme', 'light');
+    expect(wrapper).toHaveAttribute('data-accent-color', 'orange');
+    expect(wrapper).toHaveAttribute('data-gray-color', 'mauve');
+    expect(wrapper).toHaveAttribute('data-style', 'traditional');
+  });
+
+  it('does not propagate scope attrs to the document root', () => {
+    render(
+      <ThemeProvider defaultTheme='light' enableSystem={false}>
+        <ThemeProvider forcedTheme='dark' accentColor='orange'>
+          <span data-testid='child' />
+        </ThemeProvider>
+      </ThemeProvider>
+    );
+
+    // Root provider drives <html>'s attrs; scope only changes its own wrapper.
+    expect(document.documentElement.getAttribute('data-theme')).toBe('light');
+    expect(document.documentElement.getAttribute('data-accent-color')).toBe(
+      'indigo'
+    );
+    expect(screen.getByTestId('child').parentElement).toHaveAttribute(
+      'data-theme',
+      'dark'
+    );
+  });
+});
+
+// `useTheme()` reads context, and scope mode is stateless (no new context),
+// so descendants of a scope still see the root provider's state.
+describe('useTheme inside a scope', () => {
+  it('returns the root provider state, not the scope', () => {
+    const Probe = () => {
+      const { resolvedTheme } = useTheme();
+      return <span data-testid='probe'>{resolvedTheme ?? 'none'}</span>;
+    };
+
+    render(
+      <ThemeProvider defaultTheme='dark' enableSystem={false}>
+        <ThemeProvider forcedTheme='light'>
+          <Probe />
+        </ThemeProvider>
+      </ThemeProvider>
+    );
+
+    expect(screen.getByTestId('probe')).toHaveTextContent('dark');
+  });
+
+  it('exposes the root setTheme to scope descendants', () => {
+    const Probe = () => {
+      const { setTheme } = useTheme();
+      return <button onClick={() => setTheme('dark')}>set</button>;
+    };
+
+    render(
+      <ThemeProvider defaultTheme='light' enableSystem={false}>
+        <ThemeProvider forcedTheme='dark'>
+          <Probe />
+        </ThemeProvider>
+      </ThemeProvider>
+    );
+
+    fireEvent.click(screen.getByText('set'));
+    // setTheme on a scope descendant writes through to the root's storage.
+    expect(localStorageMock.setItem).toHaveBeenCalledWith('theme', 'dark');
+  });
+});
+
+// `Theme` is the canonical export; `ThemeProvider` is a back-compat alias.
+describe('Theme alias compatibility', () => {
+  it('exports Theme and ThemeProvider as the same value', async () => {
+    const { Theme, ThemeProvider: TP } = await import('../theme');
+    expect(TP).toBe(Theme);
+  });
+});
diff --git a/packages/raystack/components/theme-provider/index.tsx b/packages/raystack/components/theme-provider/index.tsx
index f791f82eb..1421d368f 100644
--- a/packages/raystack/components/theme-provider/index.tsx
+++ b/packages/raystack/components/theme-provider/index.tsx
@@ -1,3 +1,3 @@
 export { ThemeSwitcher } from './switcher';
-export { ThemeProvider, useTheme } from './theme';
+export { Theme, ThemeProvider, useTheme } from './theme';
 export { ThemeProviderProps } from './types';
diff --git a/packages/raystack/components/theme-provider/theme.tsx b/packages/raystack/components/theme-provider/theme.tsx
index 8698d104b..b66addef6 100644
--- a/packages/raystack/components/theme-provider/theme.tsx
+++ b/packages/raystack/components/theme-provider/theme.tsx
@@ -2,7 +2,6 @@
 
 import {
   createContext,
-  Fragment,
   memo,
   useCallback,
   useContext,
@@ -11,10 +10,10 @@ import {
   useRef,
   useState
 } from 'react';
-
 import type { ThemeProviderProps, UseThemeProps } from './types';
+import { COLOR_SCHEMES } from './types';
 
-const colorSchemes = ['light', 'dark'];
+const colorSchemes: string[] = [...COLOR_SCHEMES];
 const MEDIA = '(prefers-color-scheme: dark)';
 const isServer = typeof window === 'undefined';
 const ThemeContext = createContext<UseThemeProps | undefined>(undefined);
@@ -22,19 +21,45 @@ const defaultContext: UseThemeProps = { setTheme: _ => {}, themes: [] };
 
 export const useTheme = () => useContext(ThemeContext) ?? defaultContext;
 
-export function ThemeProvider(props: ThemeProviderProps) {
+export function Theme(props: ThemeProviderProps) {
   const context = useContext(ThemeContext);
 
-  // Ignore nested context providers, just passthrough children
-  if (context) return <Fragment>{props.children}</Fragment>;
-  return <Theme {...props} />;
+  // Nested usage: scoped subtree. Render a wrapper element that overrides
+  // theme tokens locally via `data-*` attributes; the parent provider's
+  // global state remains the source of truth for descendants reading
+  // `useTheme()`.
+  if (context) return <Scoped {...props} />;
+  return <Root {...props} />;
 }
 
-ThemeProvider.displayName = 'ThemeProvider';
+Theme.displayName = 'Theme';
+
+/**
+ * @deprecated Use `Theme` instead. `ThemeProvider` is kept as an alias for
+ * backward compatibility and will be removed in a future major release.
+ */
+export const ThemeProvider = Theme;
+
+const Scoped = ({
+  forcedTheme,
+  accentColor,
+  grayColor,
+  style,
+  children
+}: ThemeProviderProps) => (
+  <div
+    data-theme={forcedTheme}
+    data-accent-color={accentColor}
+    data-gray-color={grayColor}
+    data-style={style}
+  >
+    {children}
+  </div>
+);
 
-const defaultThemes = ['light', 'dark'];
+const defaultThemes: string[] = [...COLOR_SCHEMES];
 
-const Theme = ({
+const Root = ({
   forcedTheme,
   disableTransitionOnChange = false,
   enableSystem = true,
diff --git a/packages/raystack/components/theme-provider/types.ts b/packages/raystack/components/theme-provider/types.ts
index debebb2c7..8d51d7142 100644
--- a/packages/raystack/components/theme-provider/types.ts
+++ b/packages/raystack/components/theme-provider/types.ts
@@ -2,6 +2,16 @@ interface ValueObject {
   [themeName: string]: string;
 }
 
+export const COLOR_SCHEMES = ['light', 'dark'] as const;
+export const ACCENT_COLORS = ['indigo', 'orange', 'mint'] as const;
+export const GRAY_COLORS = ['gray', 'mauve', 'slate'] as const;
+export const STYLE_VARIANTS = ['modern', 'traditional'] as const;
+
+export type ColorScheme = (typeof COLOR_SCHEMES)[number];
+export type AccentColor = (typeof ACCENT_COLORS)[number];
+export type GrayColor = (typeof GRAY_COLORS)[number];
+export type StyleVariant = (typeof STYLE_VARIANTS)[number];
+
 export interface UseThemeProps {
   /** List of all available theme names */
   themes: string[];
@@ -40,12 +50,12 @@ export interface ThemeProviderProps {
   nonce?: string;
   /** React children to be rendered within the ThemeProvider */
   children?: React.ReactNode;
-  /** Style variant of the theme, either 'modern' or 'traditional'. Affects the radius and font properties. */
-  style?: 'modern' | 'traditional';
-  /** Accent color for the theme, options are 'indigo', 'orange', or 'mint' */
-  accentColor?: 'indigo' | 'orange' | 'mint';
-  /** Gray color variant for the theme, options are 'gray', 'mauve', or 'slate' */
-  grayColor?: 'gray' | 'mauve' | 'slate';
+  /** Style variant of the theme. Affects the radius and font properties. */
+  style?: StyleVariant;
+  /** Accent color for the theme. */
+  accentColor?: AccentColor;
+  /** Gray color variant for the theme. */
+  grayColor?: GrayColor;
   /** Called when the active theme changes. `resolvedTheme` is the actual applied theme (`'light'`/`'dark'` when `theme` is `'system'`). Not fired on initial mount. */
   onThemeChange?: (theme: string, resolvedTheme: string) => void;
 }
diff --git a/packages/raystack/index.tsx b/packages/raystack/index.tsx
index 3e177e22f..306880a9e 100644
--- a/packages/raystack/index.tsx
+++ b/packages/raystack/index.tsx
@@ -85,6 +85,7 @@ export { Tabs } from './components/tabs';
 export { Text } from './components/text';
 export { TextArea } from './components/text-area';
 export {
+  Theme,
   ThemeProvider,
   ThemeProviderProps,
   ThemeSwitcher,
diff --git a/packages/raystack/styles/colors.css b/packages/raystack/styles/colors.css
index 95dd91a05..be687f6ac 100644
--- a/packages/raystack/styles/colors.css
+++ b/packages/raystack/styles/colors.css
@@ -1,9 +1,10 @@
 /*
  * Note: Use color variables from this file only.
- * Avoid using color variables from other files in the v1/styles folder directly.
+ * Avoid using color variables from other files in the styles folder directly.
  */
 
-:root {
+[data-theme='light'],
+[data-theme='dark'] {
   /* Base Foreground Colors */
   --rs-color-foreground-base-primary: var(--rs-neutral-12);
   --rs-color-foreground-base-secondary: var(--rs-neutral-11);
diff --git a/packages/raystack/styles/effects.css b/packages/raystack/styles/effects.css
index a498d3f20..2ebecd2ab 100644
--- a/packages/raystack/styles/effects.css
+++ b/packages/raystack/styles/effects.css
@@ -18,6 +18,14 @@
     --rs-blur-xl: blur(4px);
 }
 
+[data-theme="light"] {
+  --rs-shadow-feather: 0px 1px 1px 0px oklch(0 0 0 / 0.06), 0px 4px 4px -1px oklch(0 0 0 / 0.02);
+  --rs-shadow-soft: 0px 2px 4px 0px oklch(0 0 0 / 0.04), 0px 1px 2px 0px oklch(0 0 0 / 0.04);
+  --rs-shadow-lifted: 0px 1px 1px 0px oklch(0 0 0 / 0.07), 0px 2px 5px 0px oklch(0 0 0 / 0.07), 0px 3px 8px 0px oklch(0 0 0 / 0.07);
+  --rs-shadow-floating: 0px 1px 1px 0px oklch(0 0 0 / 0.04), 0px 2px 8px 0px oklch(0 0 0 / 0.04), 0px 3px 17px 0px oklch(0 0 0 / 0.04), 0px 4px 30px 0px oklch(0 0 0 / 0.13);
+  --rs-shadow-inset: 0px 1px 1px 0px oklch(0 0 0 / 0.04) inset;
+}
+
 [data-theme="dark"] {
   --rs-shadow-feather: 0px 1px 1px 0px oklch(0 0 0 / 0.3), 0px 4px 4px -1px oklch(0 0 0 / 0.25);
   --rs-shadow-soft: 0px 2px 4px 0px oklch(0 0 0 / 0.3), 0px 1px 2px 0px oklch(0 0 0 / 0.25);
diff --git a/packages/raystack/styles/primitives/accent.css b/packages/raystack/styles/primitives/accent.css
index 3f8a65da0..ae445015e 100644
--- a/packages/raystack/styles/primitives/accent.css
+++ b/packages/raystack/styles/primitives/accent.css
@@ -1,11 +1,11 @@
-/* 
- * Note: Do not use this file directly. 
- * It is used for generating the final colors file. 
+/*
+ * Note: Do not use this file directly.
+ * It is used for generating the final colors file.
  * All variables must be used from colors.css file only.
  */
 
 /* [data-accent-color='indigo']  { */
-:root {
+[data-theme='light'] {
     --rs-accent-1: oklch(0.9943 0.0013 286.38);
     --rs-accent-2: oklch(0.9823 0.0083 271.33);
     --rs-accent-3: oklch(0.9609 0.017 267.79);
diff --git a/packages/raystack/styles/primitives/appearance.css b/packages/raystack/styles/primitives/appearance.css
index 5837c13f8..80df5e758 100644
--- a/packages/raystack/styles/primitives/appearance.css
+++ b/packages/raystack/styles/primitives/appearance.css
@@ -4,26 +4,36 @@
  * All variables must be used from colors.css file only.
  */
 
-/* Light Theme Colors */
-:root {
-  /* Smooth theme switch transition */
-  transition:
-    background-color 0.4s ease,
-    color 0.4s ease;
+/* Smooth theme switch transition — applies regardless of which theme is active */
+[data-theme="light"],
+[data-theme="dark"] {
+    transition: background-color 0.4s ease, color 0.4s ease;
+}
+
+/* Native UI (form controls, scrollbars, text selection) follows the scoped theme */
+[data-theme="light"] {
+    color-scheme: light;
+}
 
-  /* Neutral Colors */
-  --rs-neutral-1: var(--rs-gray-1);
-  --rs-neutral-2: var(--rs-gray-2);
-  --rs-neutral-3: var(--rs-gray-3);
-  --rs-neutral-4: var(--rs-gray-4);
-  --rs-neutral-5: var(--rs-gray-5);
-  --rs-neutral-6: var(--rs-gray-6);
-  --rs-neutral-7: var(--rs-gray-7);
-  --rs-neutral-8: var(--rs-gray-8);
-  --rs-neutral-9: var(--rs-gray-9);
-  --rs-neutral-10: var(--rs-gray-10);
-  --rs-neutral-11: var(--rs-gray-11);
-  --rs-neutral-12: var(--rs-gray-12);
+[data-theme="dark"] {
+    color-scheme: dark;
+}
+
+/* Light Theme Colors */
+[data-theme="light"] {
+    /* Neutral Colors */
+    --rs-neutral-1: var(--rs-gray-1);
+    --rs-neutral-2: var(--rs-gray-2);
+    --rs-neutral-3: var(--rs-gray-3);
+    --rs-neutral-4: var(--rs-gray-4);
+    --rs-neutral-5: var(--rs-gray-5);
+    --rs-neutral-6: var(--rs-gray-6);
+    --rs-neutral-7: var(--rs-gray-7);
+    --rs-neutral-8: var(--rs-gray-8);
+    --rs-neutral-9: var(--rs-gray-9);
+    --rs-neutral-10: var(--rs-gray-10);
+    --rs-neutral-11: var(--rs-gray-11);
+    --rs-neutral-12: var(--rs-gray-12);
 
   /* Attention Colors */
   --rs-attention-1: oklch(0.9943 0.0028 84.56);
@@ -146,20 +156,20 @@
 }
 
 /* Dark Theme Colors */
-html[data-theme="dark"] {
-  /* Neutral Colors */
-  --rs-neutral-1: var(--rs-gray-1);
-  --rs-neutral-2: var(--rs-gray-2);
-  --rs-neutral-3: var(--rs-gray-3);
-  --rs-neutral-4: var(--rs-gray-4);
-  --rs-neutral-5: var(--rs-gray-5);
-  --rs-neutral-6: var(--rs-gray-6);
-  --rs-neutral-7: var(--rs-gray-7);
-  --rs-neutral-8: var(--rs-gray-8);
-  --rs-neutral-9: var(--rs-gray-9);
-  --rs-neutral-10: var(--rs-gray-10);
-  --rs-neutral-11: var(--rs-gray-11);
-  --rs-neutral-12: var(--rs-gray-12);
+[data-theme="dark"] {
+    /* Neutral Colors */
+    --rs-neutral-1: var(--rs-gray-1);
+    --rs-neutral-2: var(--rs-gray-2);
+    --rs-neutral-3: var(--rs-gray-3);
+    --rs-neutral-4: var(--rs-gray-4);
+    --rs-neutral-5: var(--rs-gray-5);
+    --rs-neutral-6: var(--rs-gray-6);
+    --rs-neutral-7: var(--rs-gray-7);
+    --rs-neutral-8: var(--rs-gray-8);
+    --rs-neutral-9: var(--rs-gray-9);
+    --rs-neutral-10: var(--rs-gray-10);
+    --rs-neutral-11: var(--rs-gray-11);
+    --rs-neutral-12: var(--rs-gray-12);
 
   /* Attention Colors */
   --rs-attention-1: oklch(0.1976 0.0409 80.17);
diff --git a/packages/raystack/styles/primitives/gray.css b/packages/raystack/styles/primitives/gray.css
index 6c7d32884..66c7e901e 100644
--- a/packages/raystack/styles/primitives/gray.css
+++ b/packages/raystack/styles/primitives/gray.css
@@ -5,7 +5,8 @@
  */
 
 
-[data-gray-color='gray'] {
+[data-gray-color='gray'],
+[data-theme='light'] {
     --rs-gray-1: oklch(0.9911 0 0);
     --rs-gray-2: oklch(0.9821 0 0);
     --rs-gray-3: oklch(0.9551 0 0);
@@ -20,7 +21,8 @@
     --rs-gray-12: oklch(0.2435 0 0);
 }
 
-[data-gray-color='gray'][data-theme='dark'] {
+[data-gray-color='gray'][data-theme='dark'],
+[data-theme='dark'] {
     --rs-gray-1: oklch(0.1776 0 0);
     --rs-gray-2: oklch(0.2134 0 0);
     --rs-gray-3: oklch(0.252 0 0);