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

@devalok/shilp-sutra 0.37.1 → 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 (63) 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/hooks/index.d.ts +2 -2
package/dist/hooks/index.d.ts.map +1 -1
package/dist/hooks/index.js +0 -1
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/ui/alert.md +4 -1
package/docs/components/ui/banner.md +3 -1
package/docs/components/ui/input.md +4 -2
package/docs/components/ui/segmented-control.md +13 -6
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 +26 -53
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 -41

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).

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.