feat(core, react): css scoping

Author: chakrihacker

docs-site/src/App.tsx

@@ -10,6 +10,7 @@ import OrganizationDetailsEditDocs from './pages/OrganizationDetailsEditDocs';
 import SsoProviderCreateDocs from './pages/SsoProviderCreateDocs';
 import SsoProviderEditDocs from './pages/SsoProviderEditDocs';
 import SsoProviderTableDocs from './pages/SsoProviderTableDocs';
+import Styling from './pages/Styling';
 import UserMFAMgmtDocs from './pages/UserMFAMgmtDocs';
 
 function AppContent() {
@@ -18,6 +19,7 @@ function AppContent() {
       <Routes>
         <Route path="/" element={<GettingStarted />} />
         <Route path="/getting-started" element={<GettingStarted />} />
+        <Route path="/styling" element={<Styling />} />
         <Route path="/my-account" element={<MyAccountIntroduction />} />
         <Route path="/my-account/user-mfa-management" element={<UserMFAMgmtDocs />} />
         <Route path="/my-organization" element={<MyOrganizationIntroduction />} />

docs-site/src/components/Layout.tsx

@@ -8,6 +8,7 @@ import {
   Zap,
   Github,
   BookOpenText,
+  Palette,
 } from 'lucide-react';
 import type { ReactNode } from 'react';
 import { Link, useLocation } from 'react-router-dom';
@@ -68,6 +69,12 @@ export default function Layout({ children }: LayoutProps) {
       color: 'text-purple-500',
       href: '/',
     },
+    {
+      title: 'Styling',
+      icon: Palette,
+      color: 'text-violet-500',
+      href: '/styling',
+    },
     {
       title: 'My Account',
       icon: User,

docs-site/src/pages/GettingStarted.tsx

@@ -592,6 +592,80 @@ export default function OrganizationManagementPage() {
         )}
       </section>
 
+      {/* Styling */}
+      <section className="space-y-6">
+        <h2 className="text-2xl font-semibold text-gray-900">Styling</h2>
+        <p className="text-gray-600">
+          The package ships two stylesheets. Pick the one that matches how your application handles
+          CSS.
+        </p>
+
+        <div className="grid md:grid-cols-2 gap-6">
+          <div className="bg-white border border-gray-200 rounded-lg p-6 space-y-3">
+            <div className="flex items-center gap-2">
+              <span className="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-violet-100 text-violet-800">
+                Recommended
+              </span>
+            </div>
+            <h3 className="text-lg font-semibold text-gray-900">
+              <code className="text-sm bg-gray-100 px-2 py-1 rounded">styles.css</code>
+            </h3>
+            <p className="text-gray-600 text-sm">
+              A self-contained stylesheet with all Tailwind utilities pre-compiled and scoped to
+              Auth0 components. No Tailwind installation required.
+            </p>
+            <CodeBlock code={`import '@auth0/universal-components-react/styles';`} language="tsx" />
+          </div>
+
+          <div className="bg-white border border-gray-200 rounded-lg p-6 space-y-3">
+            <div className="flex items-center gap-2">
+              <span className="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-blue-100 text-blue-800">
+                Tailwind apps
+              </span>
+            </div>
+            <h3 className="text-lg font-semibold text-gray-900">Tailwind v4 theme variables</h3>
+            <p className="text-gray-600 text-sm">
+              If your app already uses Tailwind v4, import the Auth0 CSS alongside Tailwind and
+              define standard design tokens in your <code className="text-xs">:root</code> /{' '}
+              <code className="text-xs">.dark</code> blocks (e.g.{' '}
+              <code className="text-xs">--background</code>,{' '}
+              <code className="text-xs">--primary</code>).
+            </p>
+            <CodeBlock
+              code={`/* app.css */
+@import "tailwindcss";
+@import "@auth0/universal-components-react/tailwind";
+
+:root {
+  --background: oklch(1 0 0);
+  --primary:    oklch(0.205 0 0);
+  /* ... see Styling page for full list */
+}`}
+              language="css"
+            />
+          </div>
+        </div>
+
+        <div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
+          <p className="text-sm text-blue-800">
+            <strong>When to use which:</strong> If your app does not use Tailwind, import{' '}
+            <code className="text-xs">styles.css</code> — it is self-contained and works without
+            Tailwind. If your app uses Tailwind v4, import{' '}
+            <code className="text-xs">@auth0/universal-components-react/tailwind</code> and define
+            the standard tokens in your <code className="text-xs">:root</code> /{' '}
+            <code className="text-xs">.dark</code> blocks instead.
+          </p>
+        </div>
+
+        <p className="text-gray-600">
+          For full details on CSS variables, theming, and color modes, see the{' '}
+          <a href="/styling" className="text-blue-600 hover:underline font-medium">
+            Styling &amp; Theming
+          </a>{' '}
+          page.
+        </p>
+      </section>
+
       {/* Provider Configuration */}
       <section className="space-y-6">
         <h2 className="text-2xl font-semibold text-gray-900">