npm - @devalok/shilp-sutra - Versions diffs - 0.37.0 → 0.38.0 - Mend

@devalok/shilp-sutra 0.37.0 → 0.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (183) hide show

package/MIGRATION.md +67 -0
package/dist/_chunks/tiptap.js +977 -968
package/dist/_chunks/tiptap.js.map +1 -1
package/dist/composed/index.d.ts +0 -2
package/dist/composed/index.d.ts.map +1 -1
package/dist/composed/index.js +5 -6
package/dist/composed/inline-edit.d.ts.map +1 -1
package/dist/composed/inline-edit.js +42 -40
package/dist/composed/inline-edit.js.map +1 -1
package/dist/hooks/index.d.ts +2 -2
package/dist/hooks/index.d.ts.map +1 -1
package/dist/hooks/index.js +0 -1
package/dist/test-utils/conformance.d.ts +37 -0
package/dist/test-utils/conformance.d.ts.map +1 -0
package/dist/ui/alert.d.ts +1 -2
package/dist/ui/alert.d.ts.map +1 -1
package/dist/ui/alert.js +1 -27
package/dist/ui/alert.js.map +1 -1
package/dist/ui/banner.d.ts +3 -5
package/dist/ui/banner.d.ts.map +1 -1
package/dist/ui/banner.js +13 -13
package/dist/ui/banner.js.map +1 -1
package/dist/ui/index.d.ts +1 -1
package/dist/ui/index.d.ts.map +1 -1
package/dist/ui/index.js +2 -2
package/dist/ui/index.js.map +1 -1
package/dist/ui/input.d.ts +1 -9
package/dist/ui/input.d.ts.map +1 -1
package/dist/ui/input.js +26 -27
package/dist/ui/input.js.map +1 -1
package/dist/ui/segmented-control.d.ts +1 -1
package/dist/ui/segmented-control.d.ts.map +1 -1
package/dist/ui/segmented-control.js +2 -4
package/dist/ui/segmented-control.js.map +1 -1
package/docs/components/_header.md +1 -1
package/docs/components/composed/activity-feed.md +6 -0
package/docs/components/composed/avatar-group.md +8 -0
package/docs/components/composed/bulk-action-bar.md +6 -0
package/docs/components/composed/command-palette.md +7 -0
package/docs/components/composed/confirm-dialog.md +6 -0
package/docs/components/composed/content-card.md +6 -0
package/docs/components/composed/date-picker.md +10 -0
package/docs/components/composed/deadline-indicator.md +7 -0
package/docs/components/composed/emoji-picker.md +8 -0
package/docs/components/composed/empty-state.md +8 -0
package/docs/components/composed/error-boundary.md +7 -0
package/docs/components/composed/file-preview.md +8 -0
package/docs/components/composed/filter-bar.md +8 -0
package/docs/components/composed/form-section.md +6 -0
package/docs/components/composed/global-loading.md +6 -0
package/docs/components/composed/inline-edit.md +8 -0
package/docs/components/composed/loading-skeleton.md +7 -0
package/docs/components/composed/markdown-viewer.md +9 -0
package/docs/components/composed/master-detail.md +7 -0
package/docs/components/composed/member-picker.md +7 -0
package/docs/components/composed/multi-select-popover.md +11 -0
package/docs/components/composed/page-header.md +7 -0
package/docs/components/composed/page-skeletons.md +10 -0
package/docs/components/composed/priority-indicator.md +7 -0
package/docs/components/composed/rich-chat-input.md +12 -0
package/docs/components/composed/rich-text-editor.md +9 -0
package/docs/components/composed/schedule-view.md +8 -0
package/docs/components/composed/simple-tooltip.md +7 -0
package/docs/components/composed/status-badge.md +10 -0
package/docs/components/shell/app-command-palette.md +8 -0
package/docs/components/shell/bottom-navbar.md +12 -0
package/docs/components/shell/command-registry.md +7 -0
package/docs/components/shell/link-context.md +15 -0
package/docs/components/shell/notification-center.md +10 -0
package/docs/components/shell/notification-preferences.md +7 -0
package/docs/components/shell/sidebar.md +11 -0
package/docs/components/shell/top-bar.md +11 -0
package/docs/components/ui/accordion.md +10 -0
package/docs/components/ui/alert-dialog.md +10 -1
package/docs/components/ui/alert.md +13 -2
package/docs/components/ui/aspect-ratio.md +7 -0
package/docs/components/ui/autocomplete.md +7 -0
package/docs/components/ui/avatar.md +10 -0
package/docs/components/ui/badge-group.md +7 -0
package/docs/components/ui/badge-indicator.md +7 -0
package/docs/components/ui/badge.md +12 -0
package/docs/components/ui/banner.md +10 -1
package/docs/components/ui/breadcrumb.md +8 -0
package/docs/components/ui/button-group.md +24 -4
package/docs/components/ui/button-processing.md +5 -0
package/docs/components/ui/button.md +9 -0
package/docs/components/ui/card.md +16 -4
package/docs/components/ui/charts.md +9 -0
package/docs/components/ui/chat.md +9 -0
package/docs/components/ui/checkbox.md +15 -1
package/docs/components/ui/chip.md +9 -0
package/docs/components/ui/code.md +7 -0
package/docs/components/ui/collapsible.md +9 -0
package/docs/components/ui/color-input.md +8 -0
package/docs/components/ui/color-swatch.md +7 -0
package/docs/components/ui/combobox.md +16 -3
package/docs/components/ui/container.md +11 -0
package/docs/components/ui/context-menu.md +8 -0
package/docs/components/ui/data-table-body.md +4 -0
package/docs/components/ui/data-table-bulk-actions.md +4 -0
package/docs/components/ui/data-table-card.md +4 -0
package/docs/components/ui/data-table-context.md +4 -0
package/docs/components/ui/data-table-header.md +4 -0
package/docs/components/ui/data-table-pagination.md +4 -0
package/docs/components/ui/data-table-toolbar.md +7 -0
package/docs/components/ui/data-table.md +25 -0
package/docs/components/ui/devalok-grain.md +8 -0
package/docs/components/ui/dialog.md +10 -0
package/docs/components/ui/dropdown-menu.md +10 -0
package/docs/components/ui/file-upload.md +8 -0
package/docs/components/ui/form.md +21 -0
package/docs/components/ui/hover-card.md +9 -0
package/docs/components/ui/icon-button.md +7 -0
package/docs/components/ui/icon-context.md +7 -0
package/docs/components/ui/icon-group.md +9 -0
package/docs/components/ui/icon.md +7 -0
package/docs/components/ui/input-otp.md +29 -7
package/docs/components/ui/input.md +11 -2
package/docs/components/ui/label.md +7 -1
package/docs/components/ui/link.md +7 -0
package/docs/components/ui/menubar.md +9 -0
package/docs/components/ui/navigation-menu.md +9 -0
package/docs/components/ui/number-input.md +10 -0
package/docs/components/ui/pagination.md +10 -0
package/docs/components/ui/popover.md +9 -0
package/docs/components/ui/progress-ring.md +7 -0
package/docs/components/ui/progress.md +7 -0
package/docs/components/ui/radio.md +27 -2
package/docs/components/ui/search-input.md +8 -0
package/docs/components/ui/segmented-control.md +21 -6
package/docs/components/ui/select.md +14 -3
package/docs/components/ui/separator.md +7 -0
package/docs/components/ui/sheet.md +10 -0
package/docs/components/ui/sidebar.md +30 -0
package/docs/components/ui/skeleton.md +7 -0
package/docs/components/ui/slider.md +15 -1
package/docs/components/ui/spinner.md +7 -0
package/docs/components/ui/split-button.md +11 -0
package/docs/components/ui/stack.md +8 -0
package/docs/components/ui/stat-card.md +9 -0
package/docs/components/ui/status-dot.md +9 -0
package/docs/components/ui/stepper.md +8 -0
package/docs/components/ui/switch.md +8 -0
package/docs/components/ui/table.md +8 -0
package/docs/components/ui/tabs.md +10 -2
package/docs/components/ui/text.md +9 -4
package/docs/components/ui/textarea.md +7 -1
package/docs/components/ui/toast.md +9 -0
package/docs/components/ui/toaster.md +8 -0
package/docs/components/ui/toggle-group.md +13 -4
package/docs/components/ui/toggle.md +10 -2
package/docs/components/ui/tooltip.md +11 -1
package/docs/components/ui/tree-view.md +12 -0
package/docs/components/ui/visually-hidden.md +7 -0
package/docs/recipes/customize-brand.md +216 -0
package/docs/recipes/index.md +51 -0
package/docs/recipes/install-astro.md +178 -0
package/docs/recipes/install-next-app-router.md +230 -0
package/docs/recipes/install-next-pages.md +123 -0
package/docs/recipes/install-remix.md +171 -0
package/docs/recipes/install-tanstack-start.md +143 -0
package/docs/recipes/install-vite.md +170 -0
package/docs/recipes/server-components.md +209 -0
package/docs/recipes/troubleshoot.md +217 -0
package/llms-full.txt +1133 -88
package/llms.txt +33 -16
package/package.json +45 -35
package/dist/composed/responsive-overlay.d.ts +0 -23
package/dist/composed/responsive-overlay.d.ts.map +0 -1
package/dist/composed/responsive-overlay.js +0 -40
package/dist/composed/responsive-overlay.js.map +0 -1
package/dist/hooks/use-toast.d.ts +0 -17
package/dist/hooks/use-toast.d.ts.map +0 -1
package/dist/hooks/use-toast.js +0 -3
package/dist/tailwind/index.cjs +0 -41
package/dist/tailwind/index.d.ts +0 -2
package/dist/tailwind/index.d.ts.map +0 -1
package/dist/tailwind/index.js +0 -2
package/dist/tailwind/preset.d.ts +0 -25
package/dist/tailwind/preset.d.ts.map +0 -1
package/dist/tailwind/preset.js +0 -17
package/dist/tailwind/preset.js.map +0 -1
package/docs/components/composed/responsive-overlay.md +0 -34

package/docs/recipes/install-next-pages.md ADDED Viewed

@@ -0,0 +1,123 @@
+# Install: Next.js (Pages Router)
+> Setup recipe for adding `@devalok/shilp-sutra` to a Next.js project that uses the Pages Router (`pages/_app.tsx` as the entry).
+## 1. Detect
+You are in this recipe if:
+- `package.json` lists `"next"` (any version `>= 12`)
+- A `pages/` directory exists at the project root or under `src/` and contains `_app.{js,tsx}` (and optionally `_document.{js,tsx}`)
+- `app/` directory does NOT exist, OR exists but is unused
+If both `app/` and `pages/` exist, prefer [install-next-app-router.md](./install-next-app-router.md) and treat the Pages Router as legacy.
+## 2. Install
+Same dependencies as the App Router recipe — see [install-next-app-router.md § 2](./install-next-app-router.md#2-install-dependencies). Replace `next-themes`'s `attribute="class"` setup with the same on Pages Router (it works identically).
+## 3. PostCSS
+Same as App Router — see [§ 3](./install-next-app-router.md#3-configure-postcss).
+## 4. Wire Tailwind 4 + tokens
+Common CSS entry paths in priority order:
+- `styles/globals.css`
+- `src/styles/globals.css`
+- `pages/_app.css` (rare)
+If none exists, create `styles/globals.css` with:
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+Import it from `pages/_app.tsx`:
+```tsx
+import "../styles/globals.css";
+```
+## 5. `transpilePackages`
+Identical to App Router — see [§ 5](./install-next-app-router.md#5-configure-transpilepackages).
+## 6. Providers in `_app.tsx`
+Replace or merge into `pages/_app.tsx`:
+```tsx
+import "../styles/globals.css";
+import type { AppProps } from "next/app";
+import { ThemeProvider } from "next-themes";
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      <Component {...pageProps} />
+      <Toaster />
+    </ThemeProvider>
+  );
+}
+```
+For `next-themes` to avoid hydration warnings, add a `_document.tsx` with `suppressHydrationWarning` on the `<html>`:
+```tsx
+// pages/_document.tsx
+import { Html, Head, Main, NextScript } from "next/document";
+export default function Document() {
+  return (
+    <Html lang="en" suppressHydrationWarning>
+      <Head />
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  );
+}
+```
+## 7. Verify
+Replace `pages/index.tsx`:
+```tsx
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+export default function Home() {
+  return (
+    <Stack className="p-ds-08" gap="ds-04">
+      <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+      <Stack direction="row" gap="ds-03">
+        <Button>Primary</Button>
+        <Button variant="soft">Soft</Button>
+      </Stack>
+    </Stack>
+  );
+}
+```
+Run `pnpm dev` and open `http://localhost:3000`. Expected output is the same as the App Router recipe — see [§ 7](./install-next-app-router.md#7-verify-the-install).
+## 8. Pages Router specifics
+- **No React Server Components.** Every component runs on the client. Per-component imports still help tree-shaking but are not required for RSC safety.
+- **`getServerSideProps` / `getStaticProps`** — do not import shilp-sutra components inside these (they run server-side and won't render JSX). Components are imported and used in the page module's default export, as usual.
+- **`pages/_document.tsx` runs server-only.** Do not import shilp-sutra components there.
+## 9. Gotchas
+Same as App Router — see [§ 8](./install-next-app-router.md#8-common-gotchas).
+## 10. What NOT to do
+Same as App Router — see [§ 9](./install-next-app-router.md#9-what-you-should-not-do).

package/docs/recipes/install-remix.md ADDED Viewed

@@ -0,0 +1,171 @@
+# Install: Remix
+> Setup recipe for adding `@devalok/shilp-sutra` to a Remix project (v2 with Vite).
+## 1. Detect
+You are in this recipe if:
+- `package.json` lists `"@remix-run/node"` and `"@remix-run/react"`
+- `vite.config.{ts,js}` exists with the `vitePlugin` from `@remix-run/dev`
+- `app/root.tsx` exists with `<Outlet />` inside `<Document>` shell
+For React Router v7 (the spiritual successor to Remix), use the [install-vite.md](./install-vite.md) recipe — it works the same way.
+## 2. Install
+```bash
+pnpm add @devalok/shilp-sutra framer-motion
+pnpm add -D tailwindcss@^4 @tailwindcss/vite
+```
+Optional:
+```bash
+pnpm add sonner   # only if rendering <Toaster />
+```
+## 3. Wire Tailwind 4 in `vite.config.ts`
+```ts
+import { vitePlugin as remix } from "@remix-run/dev";
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "vite";
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    remix(),
+  ],
+});
+```
+`tailwindcss()` should come before `remix()` so the design tokens are processed first.
+## 4. Wire tokens
+Create `app/styles/globals.css`:
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+Wire it as a Remix link export from `app/root.tsx`:
+```tsx
+import type { LinksFunction } from "@remix-run/node";
+import globalsCss from "./styles/globals.css?url";
+export const links: LinksFunction = () => [
+  { rel: "stylesheet", href: globalsCss },
+];
+```
+The `?url` suffix is critical — it tells Vite to emit the file as an asset URL instead of inlining the CSS contents.
+## 5. Theme toggle
+Create `public/theme-bootstrap.js` (a static asset served verbatim):
+```js
+(function () {
+  try {
+    var stored = localStorage.getItem("theme");
+    var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    if (stored === "dark" || (!stored && prefersDark)) {
+      document.documentElement.classList.add("dark");
+    }
+  } catch (e) {}
+})();
+```
+Reference it from `app/root.tsx` so it loads before any React hydration:
+```tsx
+import { Outlet, Meta, Links, Scripts, ScrollRestoration } from "@remix-run/react";
+export default function App() {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <Meta />
+        <Links />
+        <script src="/theme-bootstrap.js" />
+      </head>
+      <body>
+        <Outlet />
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
+For runtime toggling inside React components, use `useColorMode`:
+```tsx
+import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
+export function ThemeToggle() {
+  const { mode, toggle } = useColorMode();
+  return (
+    <button onClick={toggle} aria-label="Toggle theme">
+      {mode === "dark" ? "☀" : "☾"}
+    </button>
+  );
+}
+```
+## 6. Toaster (optional)
+Mount once in `app/root.tsx` next to `<Outlet />`:
+```tsx
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+// inside <body>
+<>
+  <Outlet />
+  <Toaster />
+</>
+```
+## 7. Verify
+Create `app/routes/_index.tsx`:
+```tsx
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+export default function Index() {
+  return (
+    <Stack className="p-ds-08" gap="ds-04">
+      <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+      <Stack direction="row" gap="ds-03">
+        <Button>Primary</Button>
+        <Button variant="soft">Soft</Button>
+      </Stack>
+    </Stack>
+  );
+}
+```
+Run `pnpm dev` and open the URL.
+## 8. Remix-specific gotchas
+- **`?url` suffix on CSS imports.** Without it, Vite tries to inline the CSS, which breaks Tailwind processing.
+- **Loaders are server-only.** Do not import shilp-sutra components inside a `loader` function — they will not render.
+- **Server-rendered output.** Remix SSRs every route. The CSS-in-JS-free approach of shilp-sutra works perfectly here; no extra config needed.
+- **`framer-motion` and SSR.** All shilp-sutra animations gracefully degrade for the initial server render. No special handling required.
+- **CSP.** If your CSP blocks inline scripts, the `theme-bootstrap.js` static asset above already complies (no `unsafe-inline` needed).
+## 9. What NOT to do
+- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Skip the `?url` suffix on CSS imports.
+- ❌ Mount `<Toaster />` inside route components — it should live once at the root.

package/docs/recipes/install-tanstack-start.md ADDED Viewed

@@ -0,0 +1,143 @@
+# Install: TanStack Start
+> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vinxi/Vite).
+## 1. Detect
+You are in this recipe if:
+- `package.json` lists `"@tanstack/start"` and `"@tanstack/react-router"`
+- `app.config.{ts,js}` (Vinxi) exists at the project root
+- `app/router.tsx` and `app/routes/__root.tsx` exist
+## 2. Install
+```bash
+pnpm add @devalok/shilp-sutra framer-motion
+pnpm add -D tailwindcss@^4 @tailwindcss/vite
+```
+Optional:
+```bash
+pnpm add sonner   # only if rendering <Toaster />
+```
+## 3. Wire Tailwind 4 in `app.config.ts`
+```ts
+import { defineConfig } from "@tanstack/start/config";
+import tailwindcss from "@tailwindcss/vite";
+export default defineConfig({
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});
+```
+## 4. Wire tokens
+Create `app/styles/globals.css`:
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+Import it from `app/routes/__root.tsx`:
+```tsx
+import "../styles/globals.css";
+```
+If you prefer asset-URL imports the way Remix does it, use `import css from "../styles/globals.css?url"` and add `<link rel="stylesheet" href={css} />` to the `<head>` returned by `__root.tsx`.
+## 5. Theme toggle
+Create `public/theme-bootstrap.js` (a static asset served verbatim):
+```js
+(function () {
+  try {
+    var stored = localStorage.getItem("theme");
+    var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    if (stored === "dark" || (!stored && prefersDark)) {
+      document.documentElement.classList.add("dark");
+    }
+  } catch (e) {}
+})();
+```
+Reference it from `app/routes/__root.tsx`:
+```tsx
+import { createRootRoute, Outlet } from "@tanstack/react-router";
+export const Route = createRootRoute({
+  component: () => (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script src="/theme-bootstrap.js" />
+      </head>
+      <body>
+        <Outlet />
+      </body>
+    </html>
+  ),
+});
+```
+For runtime toggling, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
+## 6. Toaster (optional)
+Mount in `__root.tsx` next to `<Outlet />`:
+```tsx
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+// inside <body>
+<>
+  <Outlet />
+  <Toaster />
+</>
+```
+## 7. Verify
+Create or replace `app/routes/index.tsx`:
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+export const Route = createFileRoute("/")({
+  component: () => (
+    <Stack className="p-ds-08" gap="ds-04">
+      <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+      <Stack direction="row" gap="ds-03">
+        <Button>Primary</Button>
+        <Button variant="soft">Soft</Button>
+      </Stack>
+    </Stack>
+  ),
+});
+```
+Run `pnpm dev` and open the URL.
+## 8. TanStack Start specifics
+- **Server functions** (`createServerFn`) — do not import shilp-sutra components inside server functions; they run server-only.
+- **Streaming SSR** is the default. All shilp-sutra components SSR cleanly because they have no client-only side effects at module top-level.
+- **`framer-motion` SSR** — animations gracefully degrade on the initial render.
+- **CSP.** The static `theme-bootstrap.js` asset complies with strict CSP (no inline scripts required).
+## 9. What NOT to do
+- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Mount `<Toaster />` inside route components — it should live once at the `__root`.
+- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick one (Vite plugin recommended for TanStack Start).

package/docs/recipes/install-vite.md ADDED Viewed

@@ -0,0 +1,170 @@
+# Install: Vite + React
+> Setup recipe for adding `@devalok/shilp-sutra` to a Vite + React SPA.
+## 1. Detect
+You are in this recipe if:
+- `vite.config.{ts,js,mjs}` exists at the project root
+- `package.json` lists `"vite"` and `"react"`
+- `src/main.{tsx,jsx}` is the entry that calls `createRoot(...).render(<App />)`
+This recipe also covers Vite + React + React Router (any version) — the design system is router-agnostic.
+If you are using Remix (which now runs on Vite), use [install-remix.md](./install-remix.md). If you are using TanStack Start, use [install-tanstack-start.md](./install-tanstack-start.md).
+## 2. Install dependencies
+```bash
+# pnpm
+pnpm add @devalok/shilp-sutra framer-motion
+pnpm add -D tailwindcss@^4 @tailwindcss/vite
+# npm
+npm install @devalok/shilp-sutra framer-motion
+npm install -D tailwindcss@^4 @tailwindcss/vite
+# yarn
+yarn add @devalok/shilp-sutra framer-motion
+yarn add -D tailwindcss@^4 @tailwindcss/vite
+# bun
+bun add @devalok/shilp-sutra framer-motion
+bun add -d tailwindcss@^4 @tailwindcss/vite
+```
+Add only if rendering `<Toaster />`:
+```bash
+pnpm add sonner
+```
+## 3. Wire Tailwind 4 in `vite.config.ts`
+Use the official Tailwind 4 Vite plugin (faster than PostCSS for Vite):
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+If the project already uses PostCSS for other reasons, you can use `@tailwindcss/postcss` instead — see [install-next-app-router.md § 3](./install-next-app-router.md#3-configure-postcss). Stick with one approach; do not load both.
+## 4. Wire tokens in the global CSS
+Common CSS entry paths in priority order:
+- `src/index.css`
+- `src/main.css`
+- `src/styles/globals.css`
+- `src/App.css`
+If none exists, create `src/index.css`. Set or merge:
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+Import it once from the entry (`src/main.tsx`):
+```tsx
+import "./index.css";
+```
+## 5. Theme toggle (no `next-themes` here)
+Vite has no built-in theme provider. Use the design system's `useColorMode` hook with a small bootstrap script to avoid a flash of wrong theme.
+Add the bootstrap to `index.html` (in `<head>`, before any stylesheet):
+```html
+<script>
+  (function () {
+    try {
+      var stored = localStorage.getItem("theme");
+      var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+      var dark = stored === "dark" || (!stored && prefersDark);
+      if (dark) document.documentElement.classList.add("dark");
+    } catch (e) {}
+  })();
+</script>
+```
+Wire the runtime hook from anywhere in the app (e.g., a header button):
+```tsx
+import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
+export function ThemeToggle() {
+  const { mode, toggle } = useColorMode();
+  return (
+    <button onClick={toggle} aria-label="Toggle theme">
+      {mode === "dark" ? "☀" : "☾"}
+    </button>
+  );
+}
+```
+## 6. Mount Toaster (optional)
+If you installed `sonner`, mount the Toaster once near the app root:
+```tsx
+// src/main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+import { App } from "./App";
+import "./index.css";
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+    <Toaster />
+  </StrictMode>,
+);
+```
+## 7. Verify
+Replace `src/App.tsx`:
+```tsx
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+export function App() {
+  return (
+    <Stack className="p-ds-08" gap="ds-04">
+      <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+      <Stack direction="row" gap="ds-03">
+        <Button>Primary</Button>
+        <Button variant="soft">Soft</Button>
+      </Stack>
+    </Stack>
+  );
+}
+```
+Run `pnpm dev` and open the printed Vite URL. Expected output matches [Next App Router § 7](./install-next-app-router.md#7-verify-the-install).
+## 8. Gotchas (Vite-specific)
+- **`@tailwindcss/vite` and `@tailwindcss/postcss` together.** Pick one — running both causes utilities to be processed twice and CSS bloat.
+- **CSS import paths in HMR.** Vite is strict about case-sensitivity even on macOS. `@devalok/shilp-sutra/CSS` will not resolve; use the lowercase `/css`.
+- **Multiple framer-motion copies.** Same fix as Next — see [install-next-app-router.md § 8](./install-next-app-router.md#8-common-gotchas).
+- **Spacing utilities.** Use `p-ds-04` (not `p-4`). Tailwind composite text utilities: `text-heading-xl`, `text-body-md`, `text-code`.
+## 9. What NOT to do
+- ❌ Add `@devalok/shilp-sutra/tailwind` — the export was removed in 0.38.
+- ❌ Add a `tailwind.config.{ts,js}` with `presets: [shilpSutra]` — JS preset removed.
+- ❌ Try to use `next-themes` here — it requires Next. Use the bootstrap script + `useColorMode` shown in § 5.