@stevederico/skateboard-ui 4.6.0 → 4.9.0

package/README.md

@@ -1,16 +1,8 @@
 # skateboard-ui
 
-React component library for rapid application development. Built with TypeScript, TailwindCSS v4, and shadcn/ui.
+React component library for rapid application development. Built with TypeScript, TailwindCSS v4, and shadcn-style primitives.
 
-**Zero runtime npm dependencies.** Only React, React-DOM, and React Router are peer-resolved. Everything else — the 47 UI components, lucide icons, tailwind-merge, drag physics, command palette, date picker, theme provider — is authored, ported, or recreated inside the repo.
-
-**Self-contained components (v4.0).** Every component is now hand-written with no primitive framework underneath — the previously-vendored `@base-ui/react` bundle (~31k lines) is gone. Floating positioning, focus trapping, dismiss layers, and animations are small in-house hooks; modals use the native `<dialog>` element. The legacy `shadcn/ui/*` import paths still work — they re-export the new `ui/*` components — so existing apps need no changes.
-
-**Accessibility-hardened (v4.1–4.3).** The self-contained tier was put through three rounds of a11y work: menu/select typeahead, correct keyboard focus management and tab-stops (menus, tabs, radios, popovers, navigation menu), ARIA wiring (`aria-controls`, labelled-by, indeterminate checkbox mixed state, named popover/slider dialogs), scroll-lock and exit-animation fixes, plus matching DOMException error names. Each release adds to a Playwright a11y regression suite that runs `workers: 1`.
-
-**TypeScript with full type declarations.** Source is TypeScript, compiled to plain JavaScript + `.d.ts` in `dist/` (`npm run build`). JavaScript apps consume the compiled JS exactly as before — import paths are unchanged — and TypeScript apps get real types for every export (`SkateboardConstants`, `User`, component props, `VariantProps`, typed icons).
-
-**Node.js 24+** is required in the app repo for build tooling and backend (see `engines` in `package.json`). The UI package itself runs in the browser.
+Requires **Node.js 24+** in the app repo (see `engines` in `package.json`).
 
 ## Installation
 
@@ -37,150 +29,21 @@ const appRoutes = [
 createSkateboardApp({ constants, appRoutes });
 ```
 
-That's it! You get routing, auth, layout, landing page, settings, and payments.
-
-## Dependency Footprint
-
-Across the v3.x series, every npm runtime dep was either vendored, recreated, or dropped. v3.5 finished the job by vendoring `@base-ui/react`; **v4.0 removes that vendored bundle entirely** by rewriting every component to be self-contained.
-
-| | Hard deps | Optional peer deps | Total |
-|---|---|---|---|
-| Before (v2.23) | 15 | 0 | 15 |
-| v3.0 | 4 | 3 | 7 |
-| v3.1 | 3 | 1 | 4 |
-| v3.2 | 2 | 1 | 3 |
-| v3.3 | 2 | 0 | 2 |
-| v3.4 | 1 | 0 | 1 |
-| v3.5 | 0 | 0 | 0 |
-| **Now (v4.0+)** | **0** | **0** | **0** |
-
-v3.10 converts the package to TypeScript — compiled JS + `.d.ts` ship in `dist/`; the dependency count is unchanged (`typescript` is a devDependency only).
-
-**No hard deps remain.** React + React-DOM + React Router are the only `peerDependencies`. Every other piece of code that runs in a consumer browser is either authored here, recreated as a drop-in, or vendored from upstream.
-
-### Vendored packages
-
-Pre-built copies live in this repo so consumers don't pull them from npm. Refresh scripts in `scripts/` pin a version and re-bundle.
-
-| Source | Lives at | Refresh script |
-|---|---|---|
-| `lucide` icons (1700+) | `icons/*.tsx` | `node scripts/vendor-icons.js` (bump `LUCIDE_TAG`) |
-| `tailwind-merge` | `shadcn/lib/tailwind-merge.js` | `node scripts/vendor-tailwind-merge.js` (bump `TM_VERSION`) |
-
-`@base-ui/react` was vendored in v3.5 and **removed in v4.0** — the 47 components are now self-contained (see _Self-contained components_ above).
-
-### Ported / recreated / inlined
-
-| Replaces | Lives at | Approach |
-|---|---|---|
-| `@base-ui/react` (behavior) | `ui/*.tsx` + `ui/{use-floating,use-dismiss,use-presence,use-controllable-state,slot,portal}.tsx` | rewritten — small in-house hooks for positioning, dismiss, presence, focus; native `<dialog>` for modals |
-| `vaul` (drag gesture) | `ui/drawer.tsx` | ported — drag math copied from vaul `src/index.tsx` (MIT, Emil Kowalski) on a native `<dialog>` shell |
-| `cmdk` | `components/core/Command.tsx` | rewritten drop-in |
-| `react-day-picker` | `components/core/Calendar.tsx` | rewritten drop-in |
-| `next-themes` | `components/core/ThemeProvider.tsx` | rewritten drop-in |
-| `class-variance-authority` | `shadcn/lib/cva.ts` | rewritten drop-in |
-| `clsx` | `shadcn/lib/clsx.ts` | rewritten drop-in |
-| `tailwindcss-animate` | `styles.css` | inlined as plain CSS utilities |
-| `sonner` | — | removed; use `Dialog` / `Alert` |
-
-### Removed components (by version)
-
-| Version | Dropped | Reason |
-|---|---|---|
-| v3.1 | `Carousel`, `Resizable` | unused; consumers can install `embla-carousel-react` / `react-resizable-panels` directly |
-| v3.3 | `Chart` | unused; consumers can install `recharts` directly |
-| v3.4 | `vaul` | drag physics ported; `Drawer` rebuilt on base-ui Dialog |
-| v3.5 | `@base-ui/react` | vendored; see table above |
-| v4.0 | `@base-ui/react` (vendored bundle) | removed; components rewritten self-contained on `ui/*` |
-
-## Migrating to 3.0
-
-Version 3.0 vendors all 1700+ lucide icons into the package and drops the `lucide-react` npm dependency. Icons are pin-versioned, auditable, and re-runnable via `node scripts/vendor-icons.js`.
-
-**One change in your app:**
-
-```diff
-- import { ArrowUp, X } from 'lucide-react';
-+ import { ArrowUp, X } from '@stevederico/skateboard-ui/icons';
-```
-
-One-line migration:
-
-```bash
-find src -type f -name "*.jsx" -exec sed -i '' \
-  "s|from 'lucide-react'|from '@stevederico/skateboard-ui/icons'|g" {} +
-```
-
-Then remove `lucide-react` from your app's `package.json`.
-
-**API is identical** — same component names (`ArrowUp`, `XIcon`, etc.), same props (`size`, `color`, `strokeWidth`, `className`), same `Icon`-suffix aliases shadcn uses. Legacy lucide aliases (e.g., `Loader2` → `LoaderCircle`) are preserved.
-
-To refresh the icon set against a newer lucide release: bump `LUCIDE_TAG` in `scripts/vendor-icons.js` and re-run.
-
-The vendored icons keep their original [Lucide ISC license](icons/LICENSE) (some legacy icons inherit Feather's MIT license — both notices are in that file).
-
-## Refreshing vendored packages
-
-Each vendored library has a script that pins a version, fetches the upstream release, and re-emits the local copy. Trust model: vendoring upgrades from "trust npm on every install" to "trust npm at refresh time." Audit the diff between refreshes.
-
-| Library | Bump | Command | Host requirement |
-|---|---|---|---|
-| `lucide` icons | `LUCIDE_TAG` in `scripts/vendor-icons.js` | `node scripts/vendor-icons.js` | Node |
-| `tailwind-merge` | `TM_VERSION` in `scripts/vendor-tailwind-merge.js` | `node scripts/vendor-tailwind-merge.js` | Node |
-
-## Dark Mode Setup
-
-To prevent flash of unstyled content (FOUC) when using dark mode, add this script to your `index.html` **before** your app loads:
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-
-  <!-- Prevent dark mode FOUC -->
-  <script>
-    try {
-      const theme = localStorage.getItem('theme');
-      const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-      if (theme === 'dark' || (!theme && systemDark)) {
-        document.documentElement.classList.add('dark');
-      }
-    } catch (e) {}
-  </script>
-
-  <title>Your App</title>
-</head>
-<body>
-  <div id="root"></div>
-  <script type="module" src="/src/main.jsx"></script>
-</body>
-</html>
-```
-
-This ensures the correct theme is applied before React renders, eliminating any flash between light and dark modes.
+That's it — routing, auth, layout, landing page, settings, and payments are wired up.
 
 ## Configuration
 
-skateboard-ui requires a `constants` object that configures your application:
+skateboard-ui requires a `constants` object:
 
 ```javascript
-// constants.json or constants.js
 const constants = {
-  // Required: Backend URLs (include /api prefix)
+  // Required
   devBackendURL: "http://localhost:8000/api",
   backendURL: "https://api.myapp.com/api",
-
-  // Required: App identity
   appName: "MyApp",
-  appIcon: "sparkles",  // Lucide icon name
-
-  // Required: Landing page content
+  appIcon: "sparkles",
   tagline: "Build apps faster with skateboard-ui",
   cta: "Get Started",
-
-  // Required: Features section
   features: {
     title: "Everything you need",
     items: [
@@ -188,29 +51,19 @@ const constants = {
       { icon: "Shield", title: "Secure", description: "Authentication included" }
     ]
   },
-
-  // Required: Company information
   companyName: "Your Company",
   companyWebsite: "https://yourcompany.com",
   companyEmail: "hello@yourcompany.com",
 
-  // Optional: Navigation pages (sidebar + tabbar)
+  // Optional
   pages: [
     { title: "Home", icon: "home", url: "home" },
     { title: "Search", icon: "search", url: "search" }
   ],
-
-  // Optional: Authentication
-  noLogin: false,      // Set true to disable authentication entirely
-  // authOverlay defaults to true: lazy auth via the sign-in overlay.
-  // Set `authOverlay: false` to require eager sign-in before /app access.
-
-  // Optional: UI visibility
+  noLogin: false,
   hideSidebar: false,
   hideTabBar: false,
   hideSidebarHeader: false,
-
-  // Optional: Payments (Stripe)
   stripeProducts: [
     {
       name: "Pro Plan",
@@ -219,749 +72,240 @@ const constants = {
       lookup_key: "pro_plan",
       title: "Go Pro",
       interval: "month",
-      features: ["Unlimited usage", "Priority support", "Advanced features"]
+      features: ["Unlimited usage", "Priority support"]
     }
   ],
-
-  // Optional: Landing page customization
-  navLinks: [                                    // Override header nav links
+  navLinks: [
     { label: "Features", href: "#features" },
-    { label: "Pricing", href: "#pricing" },
-    { label: "Blog", href: "/blog" }
+    { label: "Pricing", href: "#pricing" }
   ],
-  pricing: {
-    title: "Simple Pricing",                     // Pricing section heading
-    extras: ["Priority Customer Support", "Cancel anytime"]  // Extra bullets after product features
-  },
-  ctaHeading: "Ready To Build?",                 // CTA section heading
-  footerLinks: [                                 // Override footer links
+  pricing: { title: "Simple Pricing", extras: ["Priority support", "Cancel anytime"] },
+  ctaHeading: "Ready To Build?",
+  footerLinks: [
     { label: "Privacy", href: "/privacy" },
-    { label: "Terms", href: "/terms" },
-    { label: "EULA", href: "/eula" }
+    { label: "Terms", href: "/terms" }
   ],
-  copyrightText: "All rights reserved.",         // Copyright suffix after "© {year} {companyName}."
-
-  // Optional: Legal documents (plain text, supports _COMPANY_, _WEBSITE_, _EMAIL_ placeholders)
+  copyrightText: "All rights reserved.",
   termsOfService: "Terms of Service for _COMPANY_...",
   privacyPolicy: "Privacy Policy for _COMPANY_...",
   EULA: "End User License Agreement...",
   subscriptionDetails: "Subscription details...",
-
-  // Optional: App metadata
   version: "1.0.0"
 }
 ```
 
-### Backend URL Pattern
-
-The `devBackendURL` and `backendURL` should include your full API base path (including the `/api` prefix):
-
-```javascript
-const constants = {
-  devBackendURL: "http://localhost:8000/api",  // Include /api prefix
-  backendURL: "https://api.myapp.com/api",
-}
-```
+`devBackendURL` and `backendURL` should include the full API base path (e.g. `/api`). Endpoints are relative to that base:
 
-Endpoints are relative to this base URL:
 - `${getBackendURL()}/signup` → `http://localhost:8000/api/signup`
 - `${getBackendURL()}/me` → `http://localhost:8000/api/me`
-- `${getBackendURL()}/deals` → `http://localhost:8000/api/deals`
-
-**Tip:** Include API versioning in the base URL (e.g., `/api/v2`) rather than in each endpoint path.
 
 ## createSkateboardApp
 
-The bootstrap function that sets up routing, auth, theming, state, toasts, and error handling.
-
 ```javascript
 import { createSkateboardApp } from '@stevederico/skateboard-ui/App';
 
 createSkateboardApp({
-  constants,       // Required: App configuration object
+  constants,       // Required
   appRoutes,       // Required: [{ path: string, element: JSX.Element }]
-  defaultRoute,    // Optional: Default route path (defaults to first appRoute path)
-  landingPage,     // Optional: Custom landing page JSX element
-  wrapper,         // Optional: React component to wrap the router (e.g., for providers)
+  defaultRoute,    // Optional: defaults to first appRoute path
+  landingPage,     // Optional: custom landing page element
+  wrapper,         // Optional: component to wrap the router
 });
 ```
 
-### What It Sets Up
-
-- **Routes:** Landing, signin, signup, signout, app routes, settings, payment, legal pages (terms, privacy, EULA, subscription)
-- **Authentication:** ProtectedRoute wrapping `/app/*`, AuthOverlay for lazy auth
-- **Theming:** in-house `ThemeProvider` (system / light / dark) — `components/core/ThemeProvider.tsx`
-- **State:** ContextProvider with user, UI, and auth overlay state
-- **Error Boundary:** Catches render errors, unhandled rejections, and global errors
-
-### Generated Routes
+Sets up routing, auth, theming, state, and error handling.
 
 | Route | Component | Protected |
 |-------|-----------|-----------|
 | `/` | LandingView (or custom `landingPage`) | No |
-| `/signin` | SignInView | No |
-| `/signup` | SignUpView | No |
-| `/signout` | SignOutView | No |
+| `/signin`, `/signup`, `/signout` | SignIn/SignUp/SignOutView | No |
 | `/app/:path` | Your appRoutes | Yes |
-| `/app/settings` | SettingsView | Yes |
-| `/app/payment` | PaymentView | Yes |
-| `/terms` | TextView | No |
-| `/privacy` | TextView | No |
-| `/eula` | TextView | No |
-| `/subscription` | TextView | No |
+| `/app/settings`, `/app/payment` | SettingsView, PaymentView | Yes |
+| `/terms`, `/privacy`, `/eula`, `/subscription` | TextView | No |
 | `*` | NotFound | No |
 
 ## Authentication
 
-### Overview
-
-skateboard-ui uses a **hybrid cookie + localStorage authentication system** that combines security with performance:
-
-```
-  Frontend                    Backend                   Storage
-  ────────                    ───────                   ───────
-
-1. POST /signin           →  Validate credentials
-   credentials
-                          ←  Set-Cookie: {appName}_token (HttpOnly)
-                          ←  Set-Cookie: csrf_token
-                          ←  Response: { csrfToken, ...user }
-
-2. Extract tokens         →                          localStorage:
-   - CSRF from cookie                                  {appName}_csrf
-   - User from response                                {appName}_user
-
-3. isAuthenticated()      →                          Check localStorage
-   (client-side)                                      (fast, no network)
-
-4. ProtectedRoute         →  GET /me
-   (server validation)       Validate cookies
-                          ←  200 OK or 401 Unauthorized
-
-5. API requests           →  Protected endpoints
-   + cookies (automatic)     Validate {appName}_token
-   + X-CSRF-Token header     Validate CSRF header
-```
-
-### Cookie-Based Session Management
-- **Session token** stored in `{appName}_token` cookie (HttpOnly, Secure, SameSite=Strict)
-- Automatically sent with every request via browser
-- Cannot be accessed by JavaScript (XSS protection)
-- Backend validates cookie on each protected endpoint
-
-### localStorage for Client-Side Validation
-- **CSRF token** and **user data** stored in localStorage
-- Enables instant `isAuthenticated()` checks without network calls
-- Used by client-side routing logic (ProtectedRoute initial check)
-- Not used for actual authentication (cookies handle that)
-
-### CSRF Protection
-- Dual-token system prevents CSRF attacks
-- **CSRF token** sent in `X-CSRF-Token` header with state-changing requests
-- Backend validates header matches stored session CSRF token
-- Separate from session cookie to prevent cookie-based CSRF
-
-### CSRF Error Handling
-
-The `apiRequest` utility automatically handles CSRF token failures:
-
-1. **Auto-Regeneration**: Backend auto-regenerates tokens after server restart
-2. **Retry Logic**: Frontend automatically retries failed requests once after refreshing the session
-3. **User Experience**: Transparent recovery without forcing sign-out or page refresh
-
-**Error Flow**:
-```
-POST /api/keys → 403 CSRF error
-    ↓
-Fetch /me (triggers backend auto-regeneration)
-    ↓
-Retry POST /api/keys with fresh token
-    ↓
-Success
-```
-
-### Required Backend Endpoints
-
-#### POST /signup
-Create new user account.
-
-**Request:**
-```json
-{
-  "email": "user@example.com",
-  "password": "securePassword123",
-  "name": "John Doe"
-}
-```
-
-**Response:**
-- Status: 201 Created
-- Headers:
-  - `Set-Cookie: {appName}_token={sessionToken}; HttpOnly; Secure; SameSite=Strict; Path=/`
-  - `Set-Cookie: csrf_token={csrfToken}; Secure; SameSite=Lax; Path=/`
-- Body:
-```json
-{
-  "csrfToken": "csrf_abc123...",
-  "user": {
-    "id": "user123",
-    "email": "user@example.com",
-    "name": "John Doe"
-  }
-}
-```
-
-#### POST /signin
-Authenticate existing user.
-
-**Request:**
-```json
-{
-  "email": "user@example.com",
-  "password": "securePassword123"
-}
-```
-
-**Response:**
-- Status: 200 OK
-- Headers: Same as /signup
-- Body: Same as /signup
-
-#### GET /me
-Validate current session and return user data.
-
-**Request:**
-- Headers: Cookies automatically sent by browser
-
-**Response (authenticated):**
-- Status: 200 OK
-- Body:
-```json
-{
-  "user": {
-    "id": "user123",
-    "email": "user@example.com",
-    "name": "John Doe",
-    "subscription": {
-      "status": "active",
-      "expires": 1735689600,
-      "stripeID": "cus_abc123"
-    }
-  }
-}
-```
-
-**Response (not authenticated):**
-- Status: 401 Unauthorized
-
-#### POST /signout
-End current session.
-
-**Request:**
-- Headers:
-  - Cookies automatically sent
-  - `X-CSRF-Token: {csrfToken}`
+Hybrid cookie + localStorage auth:
 
-**Response:**
-- Status: 200 OK
-- Headers:
-  - `Set-Cookie: {appName}_token=; Max-Age=0; Path=/` (clear cookie)
-  - `Set-Cookie: csrf_token=; Max-Age=0; Path=/` (clear cookie)
+1. **Sign in** — backend sets `{appName}_token` (HttpOnly) and `csrf_token` cookies; frontend stores CSRF + user in localStorage
+2. **Client check** — `isAuthenticated()` reads localStorage (fast, no network)
+3. **Route guard** — `ProtectedRoute` validates via `GET /me`
+4. **API calls** — cookies sent automatically; `X-CSRF-Token` header on state-changing requests
 
-### Optional Backend Endpoints
+### Required backend endpoints
 
-#### POST /usage
-Track and check feature usage limits.
+**POST /signup** and **POST /signin**
 
-**Request:**
 ```json
-{ "operation": "check" }
-```
-or
-```json
-{ "operation": "track" }
-```
+// Request
+{ "email": "user@example.com", "password": "securePassword123", "name": "John Doe" }
 
-**Response:**
-```json
-{ "remaining": 15, "total": 20, "isSubscriber": false }
+// Response (201 / 200)
+// Set-Cookie: {appName}_token=...; HttpOnly; Secure; SameSite=Strict
+// Set-Cookie: csrf_token=...
+{ "csrfToken": "...", "user": { "id": "...", "email": "...", "name": "..." } }
 ```
 
-#### GET /isSubscriber
-Check subscription status.
+**GET /me** — validate session, return user (401 if not authenticated)
 
-**Response:**
-```json
-{ "isSubscriber": true }
-```
+**POST /signout** — requires `X-CSRF-Token`, clears cookies
 
-#### POST /checkout (Stripe)
-Create a Stripe checkout session.
+### Optional endpoints
 
-**Request:**
-```json
-{ "lookup_key": "pro_plan", "email": "user@example.com" }
-```
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /usage` | Track/check feature usage limits |
+| `GET /isSubscriber` | Subscription status |
+| `POST /checkout` | Stripe checkout session |
+| `POST /portal` | Stripe billing portal |
 
-**Response:**
-```json
-{ "url": "https://checkout.stripe.com/..." }
-```
+### Lazy auth (default)
 
-#### POST /portal (Stripe)
-Open Stripe billing portal.
+Users can browse `/app` without signing in. Protected actions trigger the auth overlay via `useAuthGate`:
 
-**Request:**
-```json
-{ "customerID": "cus_abc123" }
-```
-
-**Response:**
-```json
-{ "url": "https://billing.stripe.com/..." }
-```
-
-### Cookie Configuration
-
-**Session Token Cookie:**
 ```javascript
-{
-  name: '{appName}_token',
-  httpOnly: true,      // Prevents JavaScript access (XSS protection)
-  secure: true,        // HTTPS only (production)
-  sameSite: 'Strict',  // Strongest CSRF protection
-  path: '/',
-  maxAge: 7 * 24 * 60 * 60 * 1000  // 7 days (configurable)
-}
-```
+import { useAuthGate } from '@stevederico/skateboard-ui/useAuthGate';
 
-**CSRF Token Cookie:**
-```javascript
-{
-  name: 'csrf_token',
-  httpOnly: false,     // Must be readable by JavaScript
-  secure: true,        // HTTPS only (production)
-  sameSite: 'Lax',     // Allow top-level navigation
-  path: '/',
-  maxAge: 7 * 24 * 60 * 60 * 1000  // Match session token
+function SaveButton() {
+  const requireAuth = useAuthGate();
+  return <button onClick={() => requireAuth(() => saveThing())}>Save</button>;
 }
 ```
 
-### Protected Endpoints
-All authenticated endpoints must:
-1. Validate `{appName}_token` cookie exists and is valid
-2. For state-changing operations (POST, PUT, DELETE), validate `X-CSRF-Token` header
-3. Return 401 if authentication fails
-4. Return 403 if CSRF validation fails
-
-### Security Considerations
+Set `authOverlay: false` in constants to require sign-in before `/app` access.
 
-- **XSS Protection**: Session token is HttpOnly — JavaScript cannot access it
-- **CSRF Protection**: Dual-token pattern prevents cookie-based CSRF attacks
-- **SameSite Policy**: Session token (Strict), CSRF token (Lax)
-- **HTTPS Requirement**: All cookies marked `Secure` in production
-- **localStorage Trade-offs**: Acceptable for CSRF token (cannot authenticate alone), never store session token
-
-### Example Backend Implementation (Express.js)
+### No-login mode
 
 ```javascript
-import express from 'express';
-import cookieParser from 'cookie-parser';
-import crypto from 'crypto';
-
-const app = express();
-app.use(express.json());
-app.use(cookieParser());
-
-// In-memory session store (use Redis in production)
-const sessions = new Map();
-
-function generateToken() {
-  return crypto.randomBytes(32).toString('hex');
-}
-
-function requireAuth(req, res, next) {
-  const sessionToken = req.cookies.myapp_token;
-  const session = sessions.get(sessionToken);
-  if (!session) return res.status(401).json({ error: 'Not authenticated' });
-  req.session = session;
-  next();
-}
-
-function requireCSRF(req, res, next) {
-  const csrfToken = req.headers['x-csrf-token'];
-  if (!req.session || req.session.csrfToken !== csrfToken) {
-    return res.status(403).json({ error: 'Invalid CSRF token' });
-  }
-  next();
-}
-
-app.post('/api/signup', async (req, res) => {
-  const { email, password, name } = req.body;
-  if (!email || !password) return res.status(400).json({ error: 'Email and password required' });
-
-  const user = await createUser(email, password, name);
-  const sessionToken = generateToken();
-  const csrfToken = generateToken();
+const constants = { noLogin: true };
+```
 
-  sessions.set(sessionToken, { userId: user.id, csrfToken, createdAt: Date.now() });
+### Troubleshooting
 
-  res.cookie('myapp_token', sessionToken, {
-    httpOnly: true, secure: process.env.NODE_ENV === 'production',
-    sameSite: 'strict', maxAge: 7 * 24 * 60 * 60 * 1000
-  });
-  res.cookie('csrf_token', csrfToken, {
-    httpOnly: false, secure: process.env.NODE_ENV === 'production',
-    sameSite: 'lax', maxAge: 7 * 24 * 60 * 60 * 1000
-  });
+| Problem | Fix |
+|---------|-----|
+| "Not authenticated" after signin | Ensure `credentials: 'include'` in fetch calls |
+| CSRF 403 errors | Verify `X-CSRF-Token` header and `csrf_token` cookie |
+| Cookies not persisting (dev) | Set `secure: false` in dev, check domain match |
 
-  res.status(201).json({ csrfToken, user: { id: user.id, email: user.email, name: user.name } });
-});
+## Dark Mode
 
-app.get('/api/me', requireAuth, async (req, res) => {
-  const user = await getUserById(req.session.userId);
-  res.json({ user: { id: user.id, email: user.email, name: user.name } });
-});
+Add this script to `index.html` **before** your app loads to prevent FOUC:
 
-app.post('/api/signout', requireAuth, requireCSRF, (req, res) => {
-  sessions.delete(req.cookies.myapp_token);
-  res.clearCookie('myapp_token');
-  res.clearCookie('csrf_token');
-  res.json({ message: 'Signed out successfully' });
-});
+```html
+<script>
+  try {
+    const theme = localStorage.getItem('theme');
+    const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    if (theme === 'dark' || (!theme && systemDark)) {
+      document.documentElement.classList.add('dark');
+    }
+  } catch (e) {}
+</script>
 ```
 
-### Auth Troubleshooting
+## Styling
 
-| Problem | Cause | Fix |
-|---------|-------|-----|
-| "Not authenticated" after signin | Cookies not sent | Verify `credentials: 'include'` in fetch calls |
-| CSRF 403 errors | Token mismatch | Check `X-CSRF-Token` header, verify cookie exists |
-| Cookies not persisting | SameSite/Secure flags | Set `secure: false` in dev, check domain match |
-| `isAuthenticated()` false but cookie exists | localStorage cleared | Re-fetch from `/me` endpoint |
+```css
+@import "@stevederico/skateboard-ui/styles.css";
 
-### No-Login Mode
+@source '../../node_modules/@stevederico/skateboard-ui';
 
-```javascript
-const constants = { noLogin: true };
+@theme {
+  --color-app: var(--color-purple-500);
+}
 ```
 
-Effects: `isAuthenticated()` always returns `true`, ProtectedRoute allows all access.
+Key variables: `--color-app` (brand), `--background`, `--foreground`, `--accent`, `--radius`.
 
 ## Components
 
-### Core Components
+### App components
 
 | Component | Import | Description |
 |-----------|--------|-------------|
-| Sidebar | `@stevederico/skateboard-ui/Sidebar` | Desktop navigation sidebar with collapsible icon mode |
-| Header | `@stevederico/skateboard-ui/Header` | App header with title and action button |
-| Layout | `@stevederico/skateboard-ui/Layout` | Page layout with sidebar (desktop) and tabbar (mobile) |
-| TabBar | `@stevederico/skateboard-ui/TabBar` | Mobile bottom navigation with labels |
+| Sidebar | `@stevederico/skateboard-ui/Sidebar` | Desktop navigation sidebar |
+| Header | `@stevederico/skateboard-ui/Header` | Page header with optional action button |
+| Layout | `@stevederico/skateboard-ui/Layout` | Sidebar (desktop) + tabbar (mobile) |
+| TabBar | `@stevederico/skateboard-ui/TabBar` | Mobile bottom navigation |
 | DynamicIcon | `@stevederico/skateboard-ui/DynamicIcon` | Lucide icon by name string |
-| ThemeToggle | `@stevederico/skateboard-ui/ThemeToggle` | Dark/light mode toggle button |
+| ThemeToggle | `@stevederico/skateboard-ui/ThemeToggle` | Dark/light mode toggle |
 | Sheet | `@stevederico/skateboard-ui/Sheet` | Slide-out panel |
 | UpgradeSheet | `@stevederico/skateboard-ui/UpgradeSheet` | Premium upgrade drawer |
 | ErrorBoundary | `@stevederico/skateboard-ui/ErrorBoundary` | Error boundary wrapper |
 
-### View Components
-
-| Component | Import | Description |
-|-----------|--------|-------------|
-| LandingView | `@stevederico/skateboard-ui/LandingView` | Landing page — sticky header, hero, features, pricing, CTA, footer |
-| SignInView | `@stevederico/skateboard-ui/SignInView` | Sign in form with Card layout |
-| SignUpView | `@stevederico/skateboard-ui/SignUpView` | Sign up form with password validation |
-| SignOutView | `@stevederico/skateboard-ui/SignOutView` | Sign out handler with redirect |
-| SettingsView | `@stevederico/skateboard-ui/SettingsView` | User settings, billing, theme |
-| PaymentView | `@stevederico/skateboard-ui/PaymentView` | Stripe payment redirect handler |
-| TextView | `@stevederico/skateboard-ui/TextView` | Legal document viewer with placeholder replacement |
-| NotFound | `@stevederico/skateboard-ui/NotFound` | 404 page |
-
-### Auth Components
-
-| Export | Import | Description |
-|--------|--------|-------------|
-| AuthOverlay | `@stevederico/skateboard-ui/AuthOverlay` | Modal sign-in/sign-up dialog |
-| useAuthGate | `@stevederico/skateboard-ui/useAuthGate` | Hook to gate actions behind auth |
-
-### State & Utilities
-
-| Export | Import | Description |
-|--------|--------|-------------|
-| Context | `@stevederico/skateboard-ui/Context` | App state provider and accessor |
-| Utilities | `@stevederico/skateboard-ui/Utilities` | API, auth, formatting, and UI utilities |
-| App | `@stevederico/skateboard-ui/App` | createSkateboardApp bootstrap function |
-| ProtectedRoute | `@stevederico/skateboard-ui/ProtectedRoute` | Route guard with server validation |
+### Views
 
-## Component Details
+| Component | Import |
+|-----------|--------|
+| LandingView | `@stevederico/skateboard-ui/LandingView` |
+| SignInView | `@stevederico/skateboard-ui/SignInView` |
+| SignUpView | `@stevederico/skateboard-ui/SignUpView` |
+| SignOutView | `@stevederico/skateboard-ui/SignOutView` |
+| SettingsView | `@stevederico/skateboard-ui/SettingsView` |
+| PaymentView | `@stevederico/skateboard-ui/PaymentView` |
+| TextView | `@stevederico/skateboard-ui/TextView` |
+| NotFound | `@stevederico/skateboard-ui/NotFound` |
 
-### Sidebar
+### Auth
 
-Desktop navigation sidebar with collapsible icon mode, user dropdown, and settings link.
+| Export | Import |
+|--------|--------|
+| AuthOverlay | `@stevederico/skateboard-ui/AuthOverlay` |
+| useAuthGate | `@stevederico/skateboard-ui/useAuthGate` |
+| ProtectedRoute | `@stevederico/skateboard-ui/ProtectedRoute` |
 
-```javascript
-import Sidebar from '@stevederico/skateboard-ui/Sidebar';
-
-// Used internally by Layout. Renders automatically based on constants.
-```
-
-**Reads from constants:**
-- `pages` — Navigation items rendered as sidebar menu buttons
-- `appName` — Displayed in sidebar header
-- `appIcon` — Icon in sidebar header
-- `hideSidebarHeader` — Hides the header when `true`
-
-**Features:**
-- Collapsible to icon-only mode via rail
-- Active page highlighting based on current route
-- Tooltip labels when collapsed
-- Footer with Settings button and user dropdown (account, billing, notifications, sign out)
-
-### Header
-
-```javascript
-import Header from '@stevederico/skateboard-ui/Header';
-
-<Header
-  title="Dashboard"
-  buttonTitle="Add"
-  onButtonTitleClick={() => console.log('clicked')}
-  buttonClass="bg-app text-white"
-  className="sticky top-0"
->
-  {/* Optional: custom right-side content */}
-</Header>
-```
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| title | string | required | Header title |
-| buttonTitle | string | — | Action button text (omit to hide) |
-| onButtonTitleClick | function | — | Button click handler |
-| buttonClass | string | — | Additional button CSS classes |
-| className | string | — | Additional header CSS classes |
-| children | ReactNode | — | Custom right-side content |
-
-### DynamicIcon
+### UI primitives
 
-Renders a Lucide icon by name string. Accepts kebab-case, snake_case, or PascalCase.
+Import from `@stevederico/skateboard-ui/ui/*`.
 
 ```javascript
-import DynamicIcon from '@stevederico/skateboard-ui/DynamicIcon';
-
-<DynamicIcon name="home" size={24} />
-<DynamicIcon name="arrow-right" size={20} color="red" />
-<DynamicIcon name="settings" className="text-muted-foreground" />
-```
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| name | string | required | Icon name (e.g. "home", "arrow-right", "Settings") |
-| size | number | 24 | Icon size in pixels |
-| color | string | 'currentColor' | Stroke color |
-| strokeWidth | number | 2 | Stroke width |
-| className | string | — | Additional CSS classes |
-
-Icons vendored from [lucide](https://lucide.dev/icons/) at `scripts/vendor-icons.js`. Returns null if icon name not found.
-
-### ThemeToggle
-
-```javascript
-import ThemeToggle from '@stevederico/skateboard-ui/ThemeToggle';
-
-<ThemeToggle />
-<ThemeToggle variant="landing" iconSize={18} />
-```
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| className | string | "" | Additional CSS classes |
-| iconSize | number | 16 | Icon size in pixels |
-| variant | string | "settings" | "settings" (ghost) or "landing" (outline) |
-
-### TabBar
-
-Mobile bottom navigation bar. Hidden on `md+` screens. Renders pages from `constants.pages` plus a Settings link.
-
-```javascript
-import TabBar from '@stevederico/skateboard-ui/TabBar';
-
-// Used internally by Layout. Renders automatically.
+import { Button } from '@stevederico/skateboard-ui/ui/button';
+import { Card, CardHeader, CardTitle, CardContent } from '@stevederico/skateboard-ui/ui/card';
+import { Input } from '@stevederico/skateboard-ui/ui/input';
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@stevederico/skateboard-ui/ui/dialog';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@stevederico/skateboard-ui/ui/select';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@stevederico/skateboard-ui/ui/dropdown-menu';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@stevederico/skateboard-ui/ui/tabs';
 ```
 
-**Features:**
-- Fixed bottom position on mobile
-- Active page highlighting with bold stroke
-- Text labels under each icon
-- Settings link appended automatically
-
-### UpgradeSheet
-
-Drawer component for premium upgrade prompts. Controlled via ref.
-
 ```javascript
-import { useRef } from 'react';
-import UpgradeSheet from '@stevederico/skateboard-ui/UpgradeSheet';
-import { showUpgradeSheet } from '@stevederico/skateboard-ui/Utilities';
-
-function MyComponent() {
-  const upgradeRef = useRef();
-
-  return (
-    <>
-      <button onClick={() => showUpgradeSheet(upgradeRef)}>
-        Upgrade
-      </button>
-      <UpgradeSheet ref={upgradeRef} userEmail={user.email} />
-    </>
-  );
-}
+import { cn } from '@stevederico/skateboard-ui/shadcn/lib/utils';
+import { useIsMobile } from '@stevederico/skateboard-ui/shadcn/hooks/use-mobile';
 ```
 
-**Ref Methods:** `show()`, `open()`, `hide()`, `close()`, `toggle()`
-
-**Props:**
-
-| Prop | Type | Description |
-|------|------|-------------|
-| userEmail | string | User's email for Stripe checkout |
-
-**Reads from constants:** `stripeProducts[0]` (title, price, features)
-
-### TextView
-
-Renders legal documents with placeholder replacement.
+### Icons
 
 ```javascript
-import TextView from '@stevederico/skateboard-ui/TextView';
-
-<TextView details={constants.termsOfService} />
+import { ArrowUp, X } from '@stevederico/skateboard-ui/icons';
 ```
 
-**Props:**
-
-| Prop | Type | Description |
-|------|------|-------------|
-| details | string | Text content with optional placeholders |
-| className | string | Additional CSS classes |
-
-**Placeholders:** `_COMPANY_` → companyName, `_WEBSITE_` → companyWebsite, `_EMAIL_` → companyEmail
-
-### ErrorBoundary
-
-Catches render errors, unhandled promise rejections, and global errors. Shows an error card with retry options.
-
-```javascript
-import ErrorBoundary from '@stevederico/skateboard-ui/ErrorBoundary';
-
-<ErrorBoundary>
-  <App />
-</ErrorBoundary>
-```
-
-## Context (State Management)
+## Context
 
 ```javascript
 import { getState, useUser, useDispatch } from '@stevederico/skateboard-ui/Context';
 
-function MyComponent() {
-  const { state, dispatch } = getState();
-
-  // Access state
-  const user = state.user;
-  const constants = state.constants;
-
-  // Dispatch actions
-  dispatch({ type: 'SET_USER', payload: userData });
-  dispatch({ type: 'CLEAR_USER' });
-}
+const { state, dispatch } = getState();
+dispatch({ type: 'SET_USER', payload: userData });
+dispatch({ type: 'CLEAR_USER' });
 ```
 
-### Optimized Hooks
-
-Use these hooks to avoid unnecessary re-renders:
-
-```javascript
-import { useUser, useDispatch } from '@stevederico/skateboard-ui/Context';
-
-// Only re-renders when user changes (not on sidebar/theme changes)
-function ProfileCard() {
-  const user = useUser();
-  if (!user) return null;
-  return <div>{user.name}</div>;
-}
-
-// Stable dispatch reference, never causes re-renders
-function SignOutButton() {
-  const dispatch = useDispatch();
-  return <button onClick={() => dispatch({ type: 'CLEAR_USER' })}>Sign Out</button>;
-}
-```
-
-| Hook | Returns | Re-renders on |
-|------|---------|---------------|
-| `getState()` | `{ state, dispatch }` | Any state change |
-| `useUser()` | `user` or `null` | User changes only |
-| `useDispatch()` | `dispatch` | Never (stable) |
-
-### State Shape
-
-```javascript
-{
-  user: {
-    id: string,
-    email: string,
-    name: string,
-    subscription: {
-      status: 'active' | 'canceled' | null,
-      expires: number,      // Unix timestamp (seconds)
-      stripeID: string
-    }
-  } | null,
-
-  ui: {
-    sidebarVisible: boolean,
-    tabBarVisible: boolean
-  },
-
-  authOverlay: {
-    visible: boolean,
-    pendingCallbacks: Function[]   // queued 401 retries; run on sign-in, rejected on dismiss
-  },
-
-  constants: Object  // App configuration
-}
-```
-
-### Available Actions
+| Hook | Re-renders on |
+|------|---------------|
+| `getState()` | Any state change |
+| `useUser()` | User changes only |
+| `useDispatch()` | Never (stable) |
 
 | Action | Payload | Description |
 |--------|---------|-------------|
 | `SET_USER` | user object | Set authenticated user |
-| `CLEAR_USER` | — | Clear user (logout) |
+| `CLEAR_USER` | — | Clear user |
 | `SET_SIDEBAR_VISIBLE` | boolean | Show/hide sidebar |
 | `SET_TABBAR_VISIBLE` | boolean | Show/hide tab bar |
-| `SET_UI_VISIBILITY` | `{ sidebar?, tabBar? }` | Batch update UI visibility |
-| `SHOW_AUTH_OVERLAY` | callback or null | Show auth dialog, optionally queue callback |
+| `SHOW_AUTH_OVERLAY` | callback or null | Show auth dialog |
 | `HIDE_AUTH_OVERLAY` | — | Hide auth dialog |
-| `AUTH_OVERLAY_SUCCESS` | — | Auth success, run pending callback and close |
-
-### localStorage Keys
-
-All keys are namespaced with `{appName}_`:
-
-| Key | Description |
-|-----|-------------|
-| `{appName}_user` | Persisted user object |
-| `{appName}_csrf` | CSRF token (fallback, primary is cookie) |
-| `{appName}_beforeCheckoutURL` | Redirect URL after Stripe checkout |
-| `{appName}_beforeManageURL` | Redirect URL after Stripe portal |
+| `AUTH_OVERLAY_SUCCESS` | — | Run pending callback and close |
 
 ## Utilities
 
@@ -974,7 +318,6 @@ import {
   isSubscriber,
   getCSRFToken,
   getBackendURL,
-  getAppKey,
   getConstants,
   getRemainingUsage,
   trackUsage,
@@ -985,338 +328,38 @@ import {
   hideSidebar,
   showTabBar,
   hideTabBar,
-  setSidebarVisible,
-  setTabBarVisible,
-  setUIVisibility,
   timestampToString,
   useListData,
   useForm,
-  useAppSetup,
   isAppMode,
-  validateConstants,
 } from '@stevederico/skateboard-ui/Utilities';
 ```
 
-### API Requests
-
 ```javascript
-// GET
+// API — auto-includes credentials, CSRF header, auth overlay on 401
 const data = await apiRequest('/deals');
+await apiRequest('/deals', { method: 'POST', body: JSON.stringify({ name: 'New Deal' }) });
 
-// POST
-const newDeal = await apiRequest('/deals', {
-  method: 'POST',
-  body: JSON.stringify({ name: 'New Deal', amount: 5000 })
-});
-
-// GET with query params
-const filtered = await apiRequestWithParams('/deals', { status: 'active', limit: 10 });
-```
-
-**Features:**
-- Auto-includes credentials (cookies)
-- Auto-adds `X-CSRF-Token` header for POST, PUT, DELETE, PATCH
-- On 401, shows the auth overlay and retries after sign-in (default); redirects to `/signout` only when `authOverlay: false`
-- Auto-retries once on CSRF 403 failure
-
-### Auth Utilities
-
-```javascript
-// Client-side check (fast, no network)
-if (isAuthenticated()) {
-  const user = getCurrentUser();
-}
-
-// Server-side validation
-const user = await getCurrentUser();  // Calls GET /me
-
-// Check subscription
-const subscribed = await isSubscriber();  // Calls GET /isSubscriber
-
-// Get CSRF token (from cookie, falls back to localStorage)
-const token = getCSRFToken();
-
-// Get backend URL (devBackendURL in dev, backendURL in production)
-const url = getBackendURL();
-
-// Generate app-namespaced localStorage key
-const key = getAppKey('user');  // → "{appName}_user"
-```
-
-### Usage Tracking
-
-```javascript
-// Check remaining usage for an action
-const usage = await getRemainingUsage('messages');
-// { remaining: 15, total: 20, isSubscriber: false }
-
-// Track usage (decrements remaining)
-const updated = await trackUsage('messages');
-```
+// Data fetching
+const { data, loading, error, refetch } = useListData('/deals');
 
-### Stripe Payments
+// Timestamps
+timestampToString(1706000000, 'ago');   // "2 hours ago"
+timestampToString(1706000000, 'DOB');   // "Jan 23, 2024"
 
-```javascript
-// Redirect to Stripe checkout
-showCheckout('user@example.com', 0);  // productIndex defaults to 0
-
-// Open Stripe billing portal
+// Stripe
+showCheckout('user@example.com', 0);
 showManage('cus_abc123');
-
-// Show upgrade sheet if not subscriber
-showUpgradeSheet(upgradeSheetRef);
 ```
 
-### Data Fetching Hook
-
-```javascript
-import { useListData } from '@stevederico/skateboard-ui/Utilities';
-
-function DealsList() {
-  const { data, loading, error, refetch } = useListData('/deals');
-
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error}</div>;
-
-  return data.map(deal => <DealCard key={deal.id} {...deal} />);
-}
-
-// With custom sort
-const { data } = useListData('/deals', (a, b) => b.amount - a.amount);
-```
-
-### Form Hook
-
-```javascript
-import { useForm } from '@stevederico/skateboard-ui/Utilities';
-
-function ContactForm() {
-  const { values, handleChange, handleSubmit, reset, submitting, error } = useForm(
-    { name: '', email: '', message: '' },
-    async (formValues) => {
-      await apiRequest('/contact', {
-        method: 'POST',
-        body: JSON.stringify(formValues)
-      });
-    }
-  );
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <input name="name" value={values.name} onChange={handleChange} />
-      <input name="email" value={values.email} onChange={handleChange} />
-      <textarea name="message" value={values.message} onChange={handleChange} />
-      <button type="submit" disabled={submitting}>Send</button>
-      {error && <p>{error}</p>}
-    </form>
-  );
-}
-```
+## Peer dependencies
 
-### Timestamp Formatting
-
-```javascript
-import { timestampToString } from '@stevederico/skateboard-ui/Utilities';
-
-timestampToString(1706000000, 'ago');           // "2 hours ago"
-timestampToString(1706000000, 'DOB');           // "Jan 23, 2024"
-timestampToString(1706000000, 'DOBT');          // "Jan 23, 2024 3:00 PM"
-timestampToString(1706000000, 'ISO');           // "2024-01-23"
-timestampToString(1706000000, 'day-month-time');// "23 Jan 3:00 PM"
-timestampToString(1706000000, 'day');           // "Monday"
-timestampToString(1706000000, 'time');          // "3:00 PM"
-timestampToString(1706000000, 'full');          // "Monday, Jan 23, 2024 3:00 PM"
-```
-
-### UI Visibility Control
-
-```javascript
-// Programmatic control
-hideSidebar();
-showSidebar();
-hideTabBar();
-showTabBar();
-
-// Set directly
-setSidebarVisible(false);
-setTabBarVisible(true);
-
-// Batch control
-setUIVisibility({ sidebar: false, tabBar: false });
-```
-
-### Other Utilities
-
-```javascript
-// Check if running inside native WebKit wrapper (iOS/macOS app)
-if (isAppMode()) { /* native context */ }
-
-// Validate constants object (called internally by createSkateboardApp)
-validateConstants(constants);
-
-// Get constants object
-const constants = getConstants();
-```
-
-## Lazy Authentication (Auth Overlay)
-
-Let users explore `/app` without signing in — prompt them only when they perform a protected action. This is the **default** behavior.
-
-### Setup
-
-Lazy auth is on by default — no config needed. The `AuthOverlay` component is rendered automatically by `createSkateboardApp` and unauthenticated visitors can reach `/app` routes.
-
-To opt out and require eager sign-in instead, set `authOverlay: false` in your constants. `ProtectedRoute` then validates the session up front and redirects unauthenticated users to `/signin`:
-
-```json
-{
-  "authOverlay": false
-}
-```
-
-### Usage
-
-```javascript
-import { useAuthGate } from '@stevederico/skateboard-ui/useAuthGate';
-
-function SaveButton() {
-  const requireAuth = useAuthGate();
-
-  function handleSave() {
-    requireAuth(() => {
-      // Only runs if user is authenticated
-      // If not signed in, auth overlay appears first
-      saveThing();
-    });
-  }
-
-  return <button onClick={handleSave}>Save</button>;
-}
-```
-
-### How It Works
-
-1. User clicks a protected action (Save, Like, Post, etc.)
-2. `requireAuth()` checks if user is signed in
-3. If signed in — callback runs immediately
-4. If not — a modal dialog appears with sign-in/sign-up forms
-5. After successful auth, the original callback executes automatically
-6. User stays on the same page throughout — no navigation
-
-The dialog supports toggling between sign-in and sign-up modes inline, and can be dismissed with the X button (cancels the action).
-
-## Toast Notifications
-
-Removed in v3.0. The Sonner dependency is gone — surface short-lived feedback with `Dialog` or `Alert` from `shadcn/ui` instead.
-
-## Styling
-
-Import base theme and override as needed:
-
-```css
-/* styles.css */
-@import "@stevederico/skateboard-ui/styles.css";
-
-@source '../../node_modules/@stevederico/skateboard-ui';
-
-@theme {
-  --color-app: var(--color-purple-500);
-}
-```
-
-### Theme Variables
-
-| Variable | Description |
-|----------|-------------|
-| `--color-app` | Primary brand color (used for app icon backgrounds, gradient buttons) |
-| `--background` | Page background |
-| `--foreground` | Text color |
-| `--accent` | Secondary backgrounds |
-| `--radius` | Border radius |
-
-Dark mode is automatic via CSS custom properties and the in-house `ThemeProvider` (`components/core/ThemeProvider.tsx`).
-
-## Components
-
-47 self-contained components available at `@stevederico/skateboard-ui/ui/*`. The legacy `@stevederico/skateboard-ui/ui/*` paths still resolve to the same components (re-export shims), so existing imports keep working.
-
-Components follow the shadcn API. `asChild` renders the styling onto a single child element; the old base-ui `render={<El/>}` / `nativeButton` props are still accepted for backward compatibility.
-
-```javascript
-import { Button } from '@stevederico/skateboard-ui/ui/button';
-import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter, CardAction } from '@stevederico/skateboard-ui/ui/card';
-import { Input } from '@stevederico/skateboard-ui/ui/input';
-import { Label } from '@stevederico/skateboard-ui/ui/label';
-import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription } from '@stevederico/skateboard-ui/ui/dialog';
-import { Avatar, AvatarFallback, AvatarImage } from '@stevederico/skateboard-ui/ui/avatar';
-import { Badge } from '@stevederico/skateboard-ui/ui/badge';
-import { Separator } from '@stevederico/skateboard-ui/ui/separator';
-import { ScrollArea } from '@stevederico/skateboard-ui/ui/scroll-area';
-import { Skeleton } from '@stevederico/skateboard-ui/ui/skeleton';
-import { Alert, AlertDescription, AlertTitle } from '@stevederico/skateboard-ui/ui/alert';
-import { Progress } from '@stevederico/skateboard-ui/ui/progress';
-import { Switch } from '@stevederico/skateboard-ui/ui/switch';
-import { Checkbox } from '@stevederico/skateboard-ui/ui/checkbox';
-import { Textarea } from '@stevederico/skateboard-ui/ui/textarea';
-import { Tooltip, TooltipContent, TooltipTrigger } from '@stevederico/skateboard-ui/ui/tooltip';
-```
-
-```javascript
-import {
-  Select, SelectContent, SelectItem, SelectTrigger, SelectValue,
-} from '@stevederico/skateboard-ui/ui/select';
-
-import {
-  DropdownMenu, DropdownMenuContent, DropdownMenuItem,
-  DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger,
-} from '@stevederico/skateboard-ui/ui/dropdown-menu';
-
-import {
-  AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent,
-  AlertDialogDescription, AlertDialogFooter, AlertDialogHeader,
-  AlertDialogTitle, AlertDialogTrigger,
-} from '@stevederico/skateboard-ui/ui/alert-dialog';
-
-import {
-  Accordion, AccordionContent, AccordionItem, AccordionTrigger,
-} from '@stevederico/skateboard-ui/ui/accordion';
-
-import {
-  Table, TableBody, TableCell, TableHead, TableHeader, TableRow,
-} from '@stevederico/skateboard-ui/ui/table';
-
-import {
-  Tabs, TabsContent, TabsList, TabsTrigger,
-} from '@stevederico/skateboard-ui/ui/tabs';
-```
-
-### Utilities
-
-```javascript
-// Tailwind className merger
-import { cn } from '@stevederico/skateboard-ui/shadcn/lib/utils';
-
-cn('px-2 py-1', condition && 'bg-red-500', 'px-4');  // Merges without conflicts
-
-// Mobile detection hook (< 768px)
-import { useIsMobile } from '@stevederico/skateboard-ui/shadcn/hooks/use-mobile';
-
-const isMobile = useIsMobile();
-```
-
-All components support dark mode automatically and accept a `className` prop for customization.
-
-## Dependencies
-
-### Required peer dependencies
 - React 19.1+
 - react-dom 19.1+
 - react-router 7.0+
 
-### Hard dependencies
-
-None. As of v4.0 the components are self-contained — `@base-ui/react` is no longer vendored or required. See the dep-count table near the top of this README for the full history.
-
 ## Repository
 
 https://github.com/stevederico/skateboard-ui
+
+Version history and migration notes: [CHANGELOG.md](./CHANGELOG.md)