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/customize-brand.md ADDED Viewed

@@ -0,0 +1,216 @@
+# Customize: Brand & Tokens
+Override colors, radius, fonts, and spacing without forking the package. All customization happens through CSS custom properties — no JS configuration.
+## How tokens layer
+Shilp Sutra's tokens are organized in three tiers:
+1. **Primitives** (`primitives.css`) — raw OKLCH palette values. Private. You should not need to touch these.
+2. **Semantic** (`semantic.css`) — intent-based mappings (`--color-accent-9`, `--color-surface-2`, `--font-sans`). Public, exposed to Tailwind 4's `@theme`.
+3. **Utility output** — Tailwind generates classes (`bg-accent-9`, `text-surface-fg`, `font-sans`) from the semantic layer.
+To override a token, redefine it AFTER the design-system import. The cascade does the rest.
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+@theme {
+  /* Overrides go here */
+  --color-accent-9: oklch(0.55 0.22 195);
+}
+```
+`@theme` is the Tailwind 4 directive that registers a CSS variable AND auto-generates the matching utility (so `bg-accent-9` picks up the override).
+## Common overrides
+### Change the accent color
+The accent scale runs from `--color-accent-1` (lightest) to `--color-accent-12` (darkest). Step 9 is the saturated default-button background, step 11 is on-tint text.
+To swap to teal:
+```css
+@theme {
+  --color-accent-1: oklch(0.985 0.005 195);
+  --color-accent-2: oklch(0.96 0.012 195);
+  --color-accent-3: oklch(0.92 0.025 195);
+  --color-accent-4: oklch(0.88 0.04 195);
+  --color-accent-5: oklch(0.82 0.07 195);
+  --color-accent-6: oklch(0.74 0.10 195);
+  --color-accent-7: oklch(0.66 0.14 195);
+  --color-accent-8: oklch(0.60 0.17 195);
+  --color-accent-9: oklch(0.54 0.22 195);
+  --color-accent-10: oklch(0.49 0.21 195);
+  --color-accent-11: oklch(0.42 0.16 195);
+  --color-accent-12: oklch(0.20 0.05 195);
+}
+.dark {
+  --color-accent-9: oklch(0.62 0.21 195);
+  /* ...override remaining steps for dark mode */
+}
+```
+For a quick swap without redoing the full scale, only override step 9 (background) and step 11 (foreground). Other steps will still reference the original chroma — visually mismatched but functional.
+### Change the radius scale
+```css
+@theme {
+  --radius-ds-sm: 0.25rem;   /* small */
+  --radius-ds-md: 0.5rem;    /* default */
+  --radius-ds-lg: 0.75rem;
+  --radius-ds-xl: 1rem;
+  --radius: 0.5rem;          /* unsuffixed — generates bare `rounded` */
+}
+```
+For a flat, sharp brand, set everything to `0`. For a heavily rounded brand, scale up.
+### Change fonts
+The design system uses three font families, each backed by a CSS variable:
+- `--font-sans` — Inter (body)
+- `--font-display` — Ranade (headings)
+- `--font-mono` — JetBrains Mono (code)
+To swap with `next/font`:
+```tsx
+// app/layout.tsx (Next.js App Router)
+import { Inter, Plus_Jakarta_Sans, JetBrains_Mono } from "next/font/google";
+const fontSans = Plus_Jakarta_Sans({ subsets: ["latin"], variable: "--font-sans" });
+const fontDisplay = Plus_Jakarta_Sans({ subsets: ["latin"], weight: "700", variable: "--font-display" });
+const fontMono = JetBrains_Mono({ subsets: ["latin"], variable: "--font-mono" });
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${fontSans.variable} ${fontDisplay.variable} ${fontMono.variable}`}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+For Vite/Remix/Astro/TanStack, drop the `@font-face` declarations into the global CSS and override the variables:
+```css
+@font-face {
+  font-family: "Plus Jakarta Sans";
+  src: url("/fonts/PlusJakartaSans-Variable.woff2") format("woff2");
+  font-weight: 100 900;
+  font-display: swap;
+}
+@theme {
+  --font-sans: "Plus Jakarta Sans", system-ui, sans-serif;
+  --font-display: "Plus Jakarta Sans", system-ui, sans-serif;
+}
+```
+### Change the spacing scale
+The DS spacing scale runs `--spacing-ds-00` (0) to `--spacing-ds-12` (highest). Each step roughly doubles. The Tailwind classes are `p-ds-04`, `m-ds-08`, `gap-ds-03`, etc.
+```css
+@theme {
+  --spacing-ds-00: 0;
+  --spacing-ds-01: 0.125rem;
+  --spacing-ds-02: 0.25rem;
+  --spacing-ds-03: 0.5rem;
+  --spacing-ds-04: 0.75rem;
+  --spacing-ds-05: 1rem;
+  /* etc. */
+}
+```
+Most consumers should not touch this. The DS scale is tuned for the typography rhythm; changing one step without re-tuning typography looks visually off.
+### Change a single shadow
+```css
+@theme {
+  --shadow-raised: 0 1px 2px oklch(0 0 0 / 0.06), 0 2px 4px oklch(0 0 0 / 0.04);
+}
+```
+Available shadows: `--shadow-raised`, `--shadow-overlay`, `--shadow-floating`, `--shadow-brand`. Each is a multi-layer composite — overriding one without considering its layers usually produces flat-looking shadows.
+## Light + dark in lockstep
+Every override should consider both modes. Pattern:
+```css
+@theme {
+  --color-accent-9: oklch(0.54 0.22 195);
+  --color-accent-fg: oklch(0.99 0 0);
+}
+/* Dark mode override */
+.dark {
+  --color-accent-9: oklch(0.62 0.21 195);
+  --color-accent-fg: oklch(0.10 0 0);
+}
+```
+`.dark` is a regular class selector — its specificity is higher than `:root`/`@theme` body, so dark-mode overrides win when the class is active.
+## Forced colors (Windows high-contrast)
+If you override semantic colors, the `@media (forced-colors: active)` block in `semantic.css` continues to remap to system keywords. Your override is ignored when the user is in high-contrast mode — this is the correct behavior.
+If you need a custom forced-colors mapping, override inside `@media (forced-colors: active)`:
+```css
+@media (forced-colors: active) {
+  :root {
+    --color-accent-9: Highlight;
+    --color-accent-fg: HighlightText;
+  }
+}
+```
+## Per-route theming
+Apply a class on a wrapper element to scope token overrides:
+```css
+.theme-karm {
+  --color-accent-9: oklch(0.55 0.22 195);
+}
+.theme-karm.dark,
+.dark .theme-karm {
+  --color-accent-9: oklch(0.62 0.21 195);
+}
+```
+Then:
+```tsx
+<div className="theme-karm">
+  <Button>Karm-themed</Button>
+</div>
+```
+## What you cannot override via CSS variables
+- The component DOM structure (use the `asChild` pattern or wrap the component to insert)
+- The vendored Radix primitives' behavior
+- Animation keyframes (override the `--animate-*` references via `@theme` — but the keyframe definitions themselves are package-private)
+For deeper changes, fork the source or use the `className` prop with arbitrary Tailwind utilities to layer styling on top.
+## Verifying an override
+Open DevTools, inspect a component, and check the Computed tab for the variable's resolved value. The cascade origin column shows where the value came from — your override should appear there, not the package's default.
+If the override isn't winning, check:
+1. The `@theme` override comes AFTER `@import "@devalok/shilp-sutra/css";` in source order
+2. There's no `!important` in the package overriding you (there isn't — file an issue if you find one)
+3. The selector specificity matches the target (`.dark` class is on a parent of the inspected element, etc.)

package/docs/recipes/index.md ADDED Viewed

@@ -0,0 +1,51 @@
+# Recipes
+Copy-paste-ready setup guides for installing and customizing **`@devalok/shilp-sutra`** in any React project.
+These files are designed to be read by AI coding agents (Claude Code, Cursor, Copilot, Codex) and humans alike. Every step is concrete: file paths, exact strings, expected outcomes.
+When the package is installed, recipes ship at:
+```
+node_modules/@devalok/shilp-sutra/docs/recipes/
+```
+## Install recipes
+Pick the recipe that matches your framework. Detection criteria are listed at the top of each file.
+| Framework | Recipe | When to pick it |
+|---|---|---|
+| Next.js (App Router) | [install-next-app-router.md](./install-next-app-router.md) | `app/` directory exists; using React Server Components |
+| Next.js (Pages Router) | [install-next-pages.md](./install-next-pages.md) | `pages/` directory is the primary router; legacy or pre-13 codebases |
+| Vite + React | [install-vite.md](./install-vite.md) | `vite.config.*` exists; SPA or MPA |
+| Astro | [install-astro.md](./install-astro.md) | `astro.config.*` exists |
+| Remix | [install-remix.md](./install-remix.md) | `remix.config.*` or Remix v2 with Vite |
+| TanStack Start | [install-tanstack-start.md](./install-tanstack-start.md) | `app.config.*` with `@tanstack/start` |
+If the framework is not listed, start with [install-vite.md](./install-vite.md) and adapt — most React+Tailwind setups follow the same shape.
+## Customization recipes
+| Recipe | What it covers |
+|---|---|
+| [customize-brand.md](./customize-brand.md) | Token override cookbook — change colors, radius, fonts, spacing scale, dark-mode mapping |
+| [server-components.md](./server-components.md) | Per-component RSC-safety matrix; correct import patterns for Server Components |
+## Diagnostics
+| Recipe | What it covers |
+|---|---|
+| [troubleshoot.md](./troubleshoot.md) | Decision tree for the eight most common breakages: Tailwind not detecting tokens, framer-motion duplicates, missing `transpilePackages`, wrong CSS import order, dark mode not toggling, RSC import errors, font 404s, hydration mismatches |
+## What every recipe assumes
+- React `^18 || ^19`
+- Node `>= 18.18` (no `engines.node` declared by us, but Tailwind 4 + Vite 5+ require it)
+- A bundler that supports CSS imports from `node_modules` (every modern React framework does)
+## What every recipe excludes
+- Database/auth/state-management setup — out of scope. Shilp Sutra is presentation-only.
+- IDE configuration — your call.
+- Testing setup — see [packages/core/CONTRIBUTING.md](../../CONTRIBUTING.md) if contributing to the design system itself.

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

@@ -0,0 +1,178 @@
+# Install: Astro
+> Setup recipe for adding `@devalok/shilp-sutra` to an Astro project with React islands.
+## 1. Detect
+You are in this recipe if:
+- `astro.config.{ts,mjs,js}` exists at the project root
+- `package.json` lists `"astro"`
+- React is integrated via `@astrojs/react`
+If `@astrojs/react` is not installed, install it first:
+```bash
+pnpm astro add react
+```
+## 2. Install dependencies
+```bash
+pnpm add @devalok/shilp-sutra framer-motion
+pnpm add -D tailwindcss@^4 @tailwindcss/vite
+```
+Add only if rendering `<Toaster />`:
+```bash
+pnpm add sonner
+```
+## 3. Wire Tailwind 4 in `astro.config`
+Astro has its own `@astrojs/tailwind` integration, but for Tailwind 4 use the Vite plugin directly (Astro 4.5+ supports this):
+```ts
+// astro.config.ts
+import { defineConfig } from "astro/config";
+import react from "@astrojs/react";
+import tailwindcss from "@tailwindcss/vite";
+export default defineConfig({
+  integrations: [react()],
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});
+```
+Do **not** also enable `@astrojs/tailwind` — that integration is Tailwind 3 only and will conflict.
+## 4. Wire tokens
+Create `src/styles/globals.css`:
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+Import it from a layout component (e.g., `src/layouts/BaseLayout.astro`):
+```astro
+---
+import "../styles/globals.css";
+const { title = "App" } = Astro.props;
+---
+<!doctype html>
+<html lang="en" class="">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <title>{title}</title>
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+## 5. Theme toggle
+Add the bootstrap script to `<head>` of `BaseLayout.astro` (before stylesheet imports):
+```astro
+---
+import "../styles/globals.css";
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <script is:inline>
+      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) {}
+    </script>
+    <!-- ... -->
+  </head>
+  <body><slot /></body>
+</html>
+```
+`is:inline` keeps it out of bundling, so it runs before any other JS.
+For runtime toggling inside React islands, use the same `useColorMode` hook shown in [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
+## 6. Use components in islands
+Shilp Sutra components are **client-only** (they use React hooks). Mount them in islands with a `client:*` directive:
+```astro
+---
+import { Button } from "@devalok/shilp-sutra/ui/button";
+---
+<Button client:load>Hello</Button>
+```
+Static / non-interactive primitives (Text, Stack, Container, Code, VisuallyHidden) work without `client:*` because they render to static markup. Per-component imports are still required.
+## 7. Toaster (optional)
+Mount once in a top-level island. The simplest approach is a small React wrapper component:
+```tsx
+// src/components/AppToaster.tsx
+"use client";
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+export default function AppToaster() {
+  return <Toaster />;
+}
+```
+```astro
+---
+import AppToaster from "../components/AppToaster";
+---
+<AppToaster client:load />
+```
+## 8. Verify
+Create `src/pages/index.astro`:
+```astro
+---
+import BaseLayout from "../layouts/BaseLayout.astro";
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+---
+<BaseLayout title="Home">
+  <Stack className="p-ds-08" gap="ds-04">
+    <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+    <Stack direction="row" gap="ds-03">
+      <Button client:load>Primary</Button>
+      <Button client:load variant="soft">Soft</Button>
+    </Stack>
+  </Stack>
+</BaseLayout>
+```
+Run `pnpm dev` and open the URL.
+## 9. Astro-specific gotchas
+- **No `transpilePackages` equivalent — and you do not need one.** Astro's Vite uses native ESM and resolves `@devalok/shilp-sutra` from `node_modules` directly.
+- **Component must be inside a `client:*` island to be interactive.** A button without `client:load` will render but not respond to clicks.
+- **Server-side islands (`server:defer`)** — fine, but RSC import rules apply (per-component imports only). See [server-components.md](./server-components.md).
+- **`@astrojs/tailwind` and `@tailwindcss/vite` conflict.** Pick one. For Tailwind 4 use the Vite plugin.
+## 10. What NOT to do
+- ❌ Use `@astrojs/tailwind` (Tailwind 3 only).
+- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Import shilp-sutra components into a `.astro` file expecting interactivity without `client:*`.

package/docs/recipes/install-next-app-router.md ADDED Viewed

@@ -0,0 +1,230 @@
+# Install: Next.js (App Router)
+> Setup recipe for adding `@devalok/shilp-sutra` to a Next.js 13+ App Router project.
+## 1. Detect the framework
+You are in this recipe if **all** of these are true:
+- `package.json` lists `"next"` at version `^13.0.0` or higher
+- An `app/` directory exists at the project root or under `src/`
+- An `app/layout.tsx` (or `.jsx`) file exists
+- No `pages/` directory at the project root, OR `pages/` exists but only contains `_app.{js,tsx}` and `_document.{js,tsx}` (legacy artifacts)
+If `pages/` is the primary router, use [install-next-pages.md](./install-next-pages.md).
+## 2. Install dependencies
+Pick the package manager that matches the project's lockfile.
+```bash
+# pnpm  (lockfile: pnpm-lock.yaml)
+pnpm add @devalok/shilp-sutra framer-motion next-themes
+pnpm add -D tailwindcss@^4 @tailwindcss/postcss
+# npm  (lockfile: package-lock.json)
+npm install @devalok/shilp-sutra framer-motion next-themes
+npm install -D tailwindcss@^4 @tailwindcss/postcss
+# yarn  (lockfile: yarn.lock)
+yarn add @devalok/shilp-sutra framer-motion next-themes
+yarn add -D tailwindcss@^4 @tailwindcss/postcss
+# bun  (lockfile: bun.lockb)
+bun add @devalok/shilp-sutra framer-motion next-themes
+bun add -d tailwindcss@^4 @tailwindcss/postcss
+```
+Add only if you will render `<Toaster />`:
+```bash
+pnpm add sonner
+```
+Add brand assets package if you need Devalok or Karm logos:
+```bash
+pnpm add @devalok/shilp-sutra-brand
+```
+## 3. Configure PostCSS
+Create or update `postcss.config.mjs` at the project root:
+```js
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+```
+If a `postcss.config.{js,cjs,json}` already exists, merge the plugin in. Do not delete the existing file.
+## 4. Wire Tailwind 4 + design tokens
+Locate the global CSS file. Common paths in priority order:
+- `app/globals.css`
+- `src/app/globals.css`
+- `app/global.css`
+If none exists, create `app/globals.css`. Set the file contents to (or merge into):
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+**Order matters.** `tailwindcss` MUST come first. The shilp-sutra `/css` entry registers `@theme` blocks that the Tailwind import must process.
+If the project has its own theme overrides, place them AFTER both imports:
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+@theme {
+  --color-brand: oklch(0.65 0.2 280);
+}
+```
+Import the CSS file once from `app/layout.tsx` (it should already be imported in a fresh `create-next-app` project):
+```tsx
+import "./globals.css";
+```
+## 5. Configure `transpilePackages`
+Edit `next.config.{ts,js,mjs}`. Add the `transpilePackages` field:
+```ts
+import type { NextConfig } from "next";
+const nextConfig: NextConfig = {
+  transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+};
+export default nextConfig;
+```
+If a `transpilePackages` array already exists, append to it. Do not replace.
+Without `transpilePackages`, Next will refuse to load our pre-built `dist/*.js` because it ships native ESM that does not match Next's CJS-leaning loader for `node_modules`.
+## 6. Scaffold the Providers wrapper
+Create `app/providers.tsx`:
+```tsx
+"use client";
+import type { ReactNode } from "react";
+import { ThemeProvider } from "next-themes";
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      {children}
+      <Toaster />
+    </ThemeProvider>
+  );
+}
+```
+`next-themes` is already in the install list from § 2 — no extra install step needed here. If `<Toaster />` is not used:
+- Drop the `Toaster` import and its JSX usage
+- Skip installing `sonner`
+Mount `<Providers>` from `app/layout.tsx`:
+```tsx
+import "./globals.css";
+import { Providers } from "./providers";
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+`suppressHydrationWarning` on `<html>` is required because `next-themes` writes the `class` attribute before React hydrates. Without it, every page logs a hydration warning.
+## 7. Verify the install
+Replace the contents of `app/page.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>
+        <Button variant="outline">Outline</Button>
+      </Stack>
+    </Stack>
+  );
+}
+```
+Run the dev server:
+```bash
+pnpm dev
+```
+Open `http://localhost:3000`. You should see:
+- The heading rendered in **Ranade** (display font), the buttons in **Inter** (body font)
+- The primary button on a saturated accent background, the soft button with a tinted background and no border, the outline button with a border and transparent background
+- No hydration warning in the browser console
+- No 404 for fonts (fonts are bundled inside the package; `next/font` is not required)
+If anything is off, see [troubleshoot.md](./troubleshoot.md).
+## 8. Common gotchas
+- **CSS import order.** `tailwindcss` BEFORE `@devalok/shilp-sutra/css`. Reversing the order silently produces a build with no design-system utilities.
+- **Multiple `framer-motion` copies.** Run `pnpm why framer-motion`. If it shows more than one resolved version, contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break. Fix:
+  ```jsonc
+  // package.json
+  {
+    "pnpm": {
+      "overrides": {
+        "framer-motion": "^12"
+      }
+    }
+  }
+  ```
+  For npm/yarn/bun equivalents, see [troubleshoot.md](./troubleshoot.md).
+- **Server Component imports.** Use per-component imports (`@devalok/shilp-sutra/ui/text`) inside Server Components. The barrel import `@devalok/shilp-sutra/ui` pulls client-only code and breaks RSC. See [server-components.md](./server-components.md).
+- **`p-3` vs `p-ds-03`.** Our spacing namespace is `--spacing-ds-*` to avoid collision with consumer numeric spacing. Use `p-ds-04`, not `p-4`.
+- **Bare `shadow` is dead.** Tailwind 4 has no `--shadow-DEFAULT`. Use `shadow-raised`, `shadow-overlay`, or `shadow-floating`.
+## 9. What you should NOT do
+- ❌ Create `tailwind.config.ts` with `presets: [shilpSutra]` — the JS preset was removed in 0.38.
+- ❌ Add `@plugin "@devalok/shilp-sutra/tailwind"` — also removed.
+- ❌ Wrap the whole app in `<MotionConfig reducedMotion="...">` unless the user explicitly asks for a global motion override; Shilp Sutra components already respect `prefers-reduced-motion`.
+- ❌ Import from `@devalok/shilp-sutra/tailwind` — the export was removed in 0.38.
+- ❌ Run `pnpm add @radix-ui/react-*` — Radix is vendored; no @radix-ui runtime deps are required.
+## 10. Optional next steps
+- **Brand customization** — swap accent color, radius scale, or fonts: see [customize-brand.md](./customize-brand.md).
+- **App shell** — add a sidebar + topbar layout: read `llms-full.txt` sections for `AppSidebar` and `TopBar`.
+- **Server-safe components** — push as much rendering as possible into Server Components: see [server-components.md](./server-components.md).