@devalok/shilp-sutra 0.38.0 → 0.39.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 (212) hide show
  1. package/MIGRATION.md +118 -0
  2. package/dist/_chunks/badge-group.js +4 -4
  3. package/dist/_chunks/badge-group.js.map +1 -1
  4. package/dist/_chunks/chat.js +14 -14
  5. package/dist/_chunks/chat.js.map +1 -1
  6. package/dist/_chunks/date-picker.js +9 -9
  7. package/dist/_chunks/date-picker.js.map +1 -1
  8. package/dist/_chunks/document-preview.js +2 -2
  9. package/dist/_chunks/document-preview.js.map +1 -1
  10. package/dist/_chunks/file-preview.js +11 -11
  11. package/dist/_chunks/file-preview.js.map +1 -1
  12. package/dist/_chunks/image-preview.js +2 -2
  13. package/dist/_chunks/image-preview.js.map +1 -1
  14. package/dist/_chunks/mention-suggestion.js +5 -5
  15. package/dist/_chunks/mention-suggestion.js.map +1 -1
  16. package/dist/_chunks/popover.js +3 -3
  17. package/dist/_chunks/popover.js.map +1 -1
  18. package/dist/_chunks/rich-chat-input.js +33 -33
  19. package/dist/_chunks/rich-chat-input.js.map +1 -1
  20. package/dist/_chunks/shared.js +5 -5
  21. package/dist/_chunks/shared.js.map +1 -1
  22. package/dist/_chunks/text.js +2 -2
  23. package/dist/_chunks/text.js.map +1 -1
  24. package/dist/_chunks/tree-view.js +1 -1
  25. package/dist/_chunks/tree-view.js.map +1 -1
  26. package/dist/_chunks/use-calendar.js +5 -5
  27. package/dist/_chunks/use-calendar.js.map +1 -1
  28. package/dist/ai/command-bar.js +10 -10
  29. package/dist/ai/command-bar.js.map +1 -1
  30. package/dist/ai/conversation.js +4 -4
  31. package/dist/ai/conversation.js.map +1 -1
  32. package/dist/composed/activity-feed.js +5 -5
  33. package/dist/composed/activity-feed.js.map +1 -1
  34. package/dist/composed/avatar-group.js +4 -4
  35. package/dist/composed/avatar-group.js.map +1 -1
  36. package/dist/composed/bulk-action-bar.js +1 -1
  37. package/dist/composed/bulk-action-bar.js.map +1 -1
  38. package/dist/composed/command-palette.js +5 -5
  39. package/dist/composed/command-palette.js.map +1 -1
  40. package/dist/composed/content-card.js +1 -1
  41. package/dist/composed/content-card.js.map +1 -1
  42. package/dist/composed/emoji-picker.js +4 -4
  43. package/dist/composed/emoji-picker.js.map +1 -1
  44. package/dist/composed/empty-state.js +1 -1
  45. package/dist/composed/empty-state.js.map +1 -1
  46. package/dist/composed/error-boundary.js +3 -3
  47. package/dist/composed/error-boundary.js.map +1 -1
  48. package/dist/composed/filter-bar.js +1 -1
  49. package/dist/composed/filter-bar.js.map +1 -1
  50. package/dist/composed/inline-edit.js +1 -1
  51. package/dist/composed/inline-edit.js.map +1 -1
  52. package/dist/composed/loading-skeleton.js +9 -9
  53. package/dist/composed/loading-skeleton.js.map +1 -1
  54. package/dist/composed/markdown-viewer.js +3 -3
  55. package/dist/composed/markdown-viewer.js.map +1 -1
  56. package/dist/composed/multi-select-popover.js +1 -1
  57. package/dist/composed/multi-select-popover.js.map +1 -1
  58. package/dist/composed/page-header.js +1 -1
  59. package/dist/composed/page-header.js.map +1 -1
  60. package/dist/composed/page-skeletons.js +15 -15
  61. package/dist/composed/page-skeletons.js.map +1 -1
  62. package/dist/composed/priority-indicator.js +3 -3
  63. package/dist/composed/priority-indicator.js.map +1 -1
  64. package/dist/composed/rich-text-editor.js +11 -11
  65. package/dist/composed/rich-text-editor.js.map +1 -1
  66. package/dist/composed/schedule-view.js +3 -3
  67. package/dist/composed/schedule-view.js.map +1 -1
  68. package/dist/composed/status-badge.js +3 -3
  69. package/dist/composed/status-badge.js.map +1 -1
  70. package/dist/shell/bottom-navbar.js +6 -6
  71. package/dist/shell/bottom-navbar.js.map +1 -1
  72. package/dist/shell/notification-center.js +8 -8
  73. package/dist/shell/notification-center.js.map +1 -1
  74. package/dist/shell/notification-preferences.js +1 -1
  75. package/dist/shell/notification-preferences.js.map +1 -1
  76. package/dist/shell/sidebar.js +6 -6
  77. package/dist/shell/sidebar.js.map +1 -1
  78. package/dist/shell/top-bar.js +4 -4
  79. package/dist/shell/top-bar.js.map +1 -1
  80. package/dist/tokens/semantic.css +82 -9
  81. package/dist/ui/accordion.js +1 -1
  82. package/dist/ui/accordion.js.map +1 -1
  83. package/dist/ui/alert-dialog.js +3 -3
  84. package/dist/ui/alert-dialog.js.map +1 -1
  85. package/dist/ui/alert.js +2 -2
  86. package/dist/ui/alert.js.map +1 -1
  87. package/dist/ui/autocomplete.js +2 -2
  88. package/dist/ui/autocomplete.js.map +1 -1
  89. package/dist/ui/avatar.js +11 -11
  90. package/dist/ui/avatar.js.map +1 -1
  91. package/dist/ui/badge-indicator.js +1 -1
  92. package/dist/ui/badge-indicator.js.map +1 -1
  93. package/dist/ui/banner.js +1 -1
  94. package/dist/ui/banner.js.map +1 -1
  95. package/dist/ui/breadcrumb.js +1 -1
  96. package/dist/ui/breadcrumb.js.map +1 -1
  97. package/dist/ui/button.d.ts +2 -2
  98. package/dist/ui/button.js +14 -14
  99. package/dist/ui/button.js.map +1 -1
  100. package/dist/ui/card.js +5 -5
  101. package/dist/ui/card.js.map +1 -1
  102. package/dist/ui/charts/index.js +5 -5
  103. package/dist/ui/charts/index.js.map +1 -1
  104. package/dist/ui/checkbox.js +1 -1
  105. package/dist/ui/checkbox.js.map +1 -1
  106. package/dist/ui/code.js +2 -2
  107. package/dist/ui/code.js.map +1 -1
  108. package/dist/ui/color-input.js +10 -10
  109. package/dist/ui/color-input.js.map +1 -1
  110. package/dist/ui/color-swatch.js +3 -3
  111. package/dist/ui/color-swatch.js.map +1 -1
  112. package/dist/ui/combobox.js +5 -5
  113. package/dist/ui/combobox.js.map +1 -1
  114. package/dist/ui/context-menu.js +6 -6
  115. package/dist/ui/context-menu.js.map +1 -1
  116. package/dist/ui/data-table-body.js +1 -1
  117. package/dist/ui/data-table-body.js.map +1 -1
  118. package/dist/ui/data-table-bulk-actions.js +2 -2
  119. package/dist/ui/data-table-bulk-actions.js.map +1 -1
  120. package/dist/ui/data-table-card.js +2 -2
  121. package/dist/ui/data-table-card.js.map +1 -1
  122. package/dist/ui/data-table-header.js +2 -2
  123. package/dist/ui/data-table-header.js.map +1 -1
  124. package/dist/ui/data-table-pagination.js +3 -3
  125. package/dist/ui/data-table-pagination.js.map +1 -1
  126. package/dist/ui/data-table-toolbar.js +1 -1
  127. package/dist/ui/data-table-toolbar.js.map +1 -1
  128. package/dist/ui/data-table.js +1 -1
  129. package/dist/ui/data-table.js.map +1 -1
  130. package/dist/ui/devalok-grain.d.ts +1 -1
  131. package/dist/ui/devalok-grain.js.map +1 -1
  132. package/dist/ui/dialog.js +2 -2
  133. package/dist/ui/dialog.js.map +1 -1
  134. package/dist/ui/dropdown-menu.js +6 -6
  135. package/dist/ui/dropdown-menu.js.map +1 -1
  136. package/dist/ui/file-upload.js +4 -4
  137. package/dist/ui/file-upload.js.map +1 -1
  138. package/dist/ui/hover-card.js +1 -1
  139. package/dist/ui/hover-card.js.map +1 -1
  140. package/dist/ui/icon-button.js +1 -1
  141. package/dist/ui/icon-button.js.map +1 -1
  142. package/dist/ui/input-otp.js +1 -1
  143. package/dist/ui/input-otp.js.map +1 -1
  144. package/dist/ui/input.js +2 -2
  145. package/dist/ui/input.js.map +1 -1
  146. package/dist/ui/link.js +1 -1
  147. package/dist/ui/link.js.map +1 -1
  148. package/dist/ui/menubar.js +8 -8
  149. package/dist/ui/menubar.js.map +1 -1
  150. package/dist/ui/navigation-menu.js +3 -3
  151. package/dist/ui/navigation-menu.js.map +1 -1
  152. package/dist/ui/number-input.js +3 -3
  153. package/dist/ui/number-input.js.map +1 -1
  154. package/dist/ui/pagination.js +1 -1
  155. package/dist/ui/pagination.js.map +1 -1
  156. package/dist/ui/progress.js +1 -1
  157. package/dist/ui/progress.js.map +1 -1
  158. package/dist/ui/radio.js +1 -1
  159. package/dist/ui/radio.js.map +1 -1
  160. package/dist/ui/segmented-control.js +3 -3
  161. package/dist/ui/segmented-control.js.map +1 -1
  162. package/dist/ui/select.js +3 -3
  163. package/dist/ui/select.js.map +1 -1
  164. package/dist/ui/sheet.js +2 -2
  165. package/dist/ui/sheet.js.map +1 -1
  166. package/dist/ui/sidebar.js +11 -11
  167. package/dist/ui/sidebar.js.map +1 -1
  168. package/dist/ui/skeleton.js +9 -9
  169. package/dist/ui/skeleton.js.map +1 -1
  170. package/dist/ui/slider.js +2 -2
  171. package/dist/ui/slider.js.map +1 -1
  172. package/dist/ui/split-button.js +7 -7
  173. package/dist/ui/split-button.js.map +1 -1
  174. package/dist/ui/stat-card.js +7 -7
  175. package/dist/ui/stat-card.js.map +1 -1
  176. package/dist/ui/status-dot.js +2 -2
  177. package/dist/ui/status-dot.js.map +1 -1
  178. package/dist/ui/stepper.js +2 -2
  179. package/dist/ui/stepper.js.map +1 -1
  180. package/dist/ui/switch.js +2 -2
  181. package/dist/ui/switch.js.map +1 -1
  182. package/dist/ui/tabs.js +3 -3
  183. package/dist/ui/tabs.js.map +1 -1
  184. package/dist/ui/textarea.js +1 -1
  185. package/dist/ui/textarea.js.map +1 -1
  186. package/dist/ui/toast.js +8 -8
  187. package/dist/ui/toast.js.map +1 -1
  188. package/dist/ui/toggle.js +1 -1
  189. package/dist/ui/toggle.js.map +1 -1
  190. package/dist/ui/tooltip.js +1 -1
  191. package/dist/ui/tooltip.js.map +1 -1
  192. package/docs/components/_header.md +90 -1
  193. package/docs/recipes/customize-brand.md +85 -4
  194. package/docs/recipes/index.md +1 -1
  195. package/llms-full.txt +91 -2
  196. package/llms.txt +9 -1
  197. package/package.json +2 -1
  198. package/skill/README.md +99 -0
  199. package/skill/SKILL.md +144 -0
  200. package/skill/install.sh +59 -0
  201. package/skill/references/components-full.md +6997 -0
  202. package/skill/references/components.md +673 -0
  203. package/skill/references/customize-brand.md +299 -0
  204. package/skill/references/server-components.md +211 -0
  205. package/skill/references/setup-astro.md +180 -0
  206. package/skill/references/setup-next-app-router.md +232 -0
  207. package/skill/references/setup-next-pages.md +125 -0
  208. package/skill/references/setup-remix.md +173 -0
  209. package/skill/references/setup-tanstack-start.md +145 -0
  210. package/skill/references/setup-vite.md +172 -0
  211. package/skill/references/troubleshoot.md +219 -0
  212. /package/{LICENSE → skill/LICENSE} +0 -0
@@ -0,0 +1,172 @@
1
+ <!-- Source: packages/core/docs/recipes/install-vite.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
2
+
3
+ # Install: Vite + React
4
+
5
+ > Setup recipe for adding `@devalok/shilp-sutra` to a Vite + React SPA.
6
+
7
+ ## 1. Detect
8
+
9
+ You are in this recipe if:
10
+
11
+ - `vite.config.{ts,js,mjs}` exists at the project root
12
+ - `package.json` lists `"vite"` and `"react"`
13
+ - `src/main.{tsx,jsx}` is the entry that calls `createRoot(...).render(<App />)`
14
+
15
+ This recipe also covers Vite + React + React Router (any version) — the design system is router-agnostic.
16
+
17
+ 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).
18
+
19
+ ## 2. Install dependencies
20
+
21
+ ```bash
22
+ # pnpm
23
+ pnpm add @devalok/shilp-sutra framer-motion
24
+ pnpm add -D tailwindcss@^4 @tailwindcss/vite
25
+
26
+ # npm
27
+ npm install @devalok/shilp-sutra framer-motion
28
+ npm install -D tailwindcss@^4 @tailwindcss/vite
29
+
30
+ # yarn
31
+ yarn add @devalok/shilp-sutra framer-motion
32
+ yarn add -D tailwindcss@^4 @tailwindcss/vite
33
+
34
+ # bun
35
+ bun add @devalok/shilp-sutra framer-motion
36
+ bun add -d tailwindcss@^4 @tailwindcss/vite
37
+ ```
38
+
39
+ Add only if rendering `<Toaster />`:
40
+
41
+ ```bash
42
+ pnpm add sonner
43
+ ```
44
+
45
+ ## 3. Wire Tailwind 4 in `vite.config.ts`
46
+
47
+ Use the official Tailwind 4 Vite plugin (faster than PostCSS for Vite):
48
+
49
+ ```ts
50
+ import { defineConfig } from "vite";
51
+ import react from "@vitejs/plugin-react";
52
+ import tailwindcss from "@tailwindcss/vite";
53
+
54
+ export default defineConfig({
55
+ plugins: [react(), tailwindcss()],
56
+ });
57
+ ```
58
+
59
+ 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.
60
+
61
+ ## 4. Wire tokens in the global CSS
62
+
63
+ Common CSS entry paths in priority order:
64
+
65
+ - `src/index.css`
66
+ - `src/main.css`
67
+ - `src/styles/globals.css`
68
+ - `src/App.css`
69
+
70
+ If none exists, create `src/index.css`. Set or merge:
71
+
72
+ ```css
73
+ @import "tailwindcss";
74
+ @import "@devalok/shilp-sutra/css";
75
+ ```
76
+
77
+ Import it once from the entry (`src/main.tsx`):
78
+
79
+ ```tsx
80
+ import "./index.css";
81
+ ```
82
+
83
+ ## 5. Theme toggle (no `next-themes` here)
84
+
85
+ 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.
86
+
87
+ Add the bootstrap to `index.html` (in `<head>`, before any stylesheet):
88
+
89
+ ```html
90
+ <script>
91
+ (function () {
92
+ try {
93
+ var stored = localStorage.getItem("theme");
94
+ var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
95
+ var dark = stored === "dark" || (!stored && prefersDark);
96
+ if (dark) document.documentElement.classList.add("dark");
97
+ } catch (e) {}
98
+ })();
99
+ </script>
100
+ ```
101
+
102
+ Wire the runtime hook from anywhere in the app (e.g., a header button):
103
+
104
+ ```tsx
105
+ import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
106
+
107
+ export function ThemeToggle() {
108
+ const { mode, toggle } = useColorMode();
109
+ return (
110
+ <button onClick={toggle} aria-label="Toggle theme">
111
+ {mode === "dark" ? "☀" : "☾"}
112
+ </button>
113
+ );
114
+ }
115
+ ```
116
+
117
+ ## 6. Mount Toaster (optional)
118
+
119
+ If you installed `sonner`, mount the Toaster once near the app root:
120
+
121
+ ```tsx
122
+ // src/main.tsx
123
+ import { StrictMode } from "react";
124
+ import { createRoot } from "react-dom/client";
125
+ import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
126
+ import { App } from "./App";
127
+ import "./index.css";
128
+
129
+ createRoot(document.getElementById("root")!).render(
130
+ <StrictMode>
131
+ <App />
132
+ <Toaster />
133
+ </StrictMode>,
134
+ );
135
+ ```
136
+
137
+ ## 7. Verify
138
+
139
+ Replace `src/App.tsx`:
140
+
141
+ ```tsx
142
+ import { Button } from "@devalok/shilp-sutra/ui/button";
143
+ import { Stack } from "@devalok/shilp-sutra/ui/stack";
144
+ import { Text } from "@devalok/shilp-sutra/ui/text";
145
+
146
+ export function App() {
147
+ return (
148
+ <Stack className="p-ds-08" gap="ds-04">
149
+ <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
150
+ <Stack direction="row" gap="ds-03">
151
+ <Button>Primary</Button>
152
+ <Button variant="soft">Soft</Button>
153
+ </Stack>
154
+ </Stack>
155
+ );
156
+ }
157
+ ```
158
+
159
+ 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).
160
+
161
+ ## 8. Gotchas (Vite-specific)
162
+
163
+ - **`@tailwindcss/vite` and `@tailwindcss/postcss` together.** Pick one — running both causes utilities to be processed twice and CSS bloat.
164
+ - **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`.
165
+ - **Multiple framer-motion copies.** Same fix as Next — see [install-next-app-router.md § 8](./install-next-app-router.md#8-common-gotchas).
166
+ - **Spacing utilities.** Use `p-ds-04` (not `p-4`). Tailwind composite text utilities: `text-heading-xl`, `text-body-md`, `text-code`.
167
+
168
+ ## 9. What NOT to do
169
+
170
+ - ❌ Add `@devalok/shilp-sutra/tailwind` — the export was removed in 0.38.
171
+ - ❌ Add a `tailwind.config.{ts,js}` with `presets: [shilpSutra]` — JS preset removed.
172
+ - ❌ Try to use `next-themes` here — it requires Next. Use the bootstrap script + `useColorMode` shown in § 5.
@@ -0,0 +1,219 @@
1
+ <!-- Source: packages/core/docs/recipes/troubleshoot.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
2
+
3
+ # Troubleshoot
4
+
5
+ A decision tree for the most common shilp-sutra setup breakages. Read symptoms top-to-bottom; the first match is usually the right diagnosis.
6
+
7
+ ## Symptom: Tailwind utilities don't apply (no styling at all)
8
+
9
+ **Diagnosis:** Tailwind is not detecting design-system source classes, OR the CSS imports are out of order.
10
+
11
+ Check 1 — import order. Open the global CSS file. The order MUST be:
12
+
13
+ ```css
14
+ @import "tailwindcss"; /* FIRST */
15
+ @import "@devalok/shilp-sutra/css"; /* SECOND */
16
+ ```
17
+
18
+ If reversed, swap them.
19
+
20
+ Check 2 — both imports present. Some setups accidentally drop `@import "tailwindcss"` after a refactor. Both imports are required.
21
+
22
+ Check 3 — file is actually loaded. In Next.js, `globals.css` must be imported from `app/layout.tsx` (App Router) or `pages/_app.tsx` (Pages Router). In Vite, from `src/main.tsx`. In Remix, via `links` export. In Astro, from a layout file.
23
+
24
+ ## Symptom: Spacing utilities like `p-4` don't work but `p-ds-04` does
25
+
26
+ **Diagnosis:** Working as designed.
27
+
28
+ Shilp Sutra uses the `--spacing-ds-*` namespace to avoid colliding with consumer numeric spacing. Use `p-ds-04`, `gap-ds-03`, `mx-ds-08`, etc. Plain `p-4` is the consumer's own spacing (Tailwind's default scale) — it works but is unrelated to the design system.
29
+
30
+ If `p-ds-*` does NOT work, you have the styling-not-applying issue above.
31
+
32
+ ## Symptom: Console error or weird animation glitches involving `MotionConfig`, `LayoutGroup`, or `AnimatePresence`
33
+
34
+ **Diagnosis:** Multiple copies of `framer-motion` are resolved.
35
+
36
+ Run:
37
+
38
+ ```bash
39
+ pnpm why framer-motion
40
+ # or
41
+ npm ls framer-motion
42
+ ```
43
+
44
+ If more than one version is listed, fix with overrides:
45
+
46
+ **pnpm:**
47
+ ```jsonc
48
+ // package.json
49
+ {
50
+ "pnpm": {
51
+ "overrides": {
52
+ "framer-motion": "^12"
53
+ }
54
+ }
55
+ }
56
+ ```
57
+
58
+ **npm:**
59
+ ```jsonc
60
+ // package.json
61
+ {
62
+ "overrides": {
63
+ "framer-motion": "^12"
64
+ }
65
+ }
66
+ ```
67
+
68
+ **yarn (berry):**
69
+ ```jsonc
70
+ // package.json
71
+ {
72
+ "resolutions": {
73
+ "framer-motion": "^12"
74
+ }
75
+ }
76
+ ```
77
+
78
+ **bun:**
79
+ ```jsonc
80
+ // package.json
81
+ {
82
+ "overrides": {
83
+ "framer-motion": "^12"
84
+ }
85
+ }
86
+ ```
87
+
88
+ After editing, delete the lockfile + `node_modules` and reinstall.
89
+
90
+ ## Symptom: Next.js error: `Cannot find module '@devalok/shilp-sutra/...'` or `Module parse failed: Unexpected token`
91
+
92
+ **Diagnosis:** `transpilePackages` is missing from `next.config.{ts,js,mjs}`.
93
+
94
+ Add:
95
+
96
+ ```ts
97
+ transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
98
+ ```
99
+
100
+ If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutra`.
101
+
102
+ ## Symptom: Hydration warning on every page load (Next.js)
103
+
104
+ **Diagnosis:** `next-themes` writes the `class` attribute on `<html>` before React hydrates, causing a server/client class mismatch.
105
+
106
+ Add `suppressHydrationWarning` to `<html>` in `app/layout.tsx` (App Router) or `pages/_document.tsx` (Pages Router):
107
+
108
+ ```tsx
109
+ <html lang="en" suppressHydrationWarning>
110
+ ```
111
+
112
+ This warning is specific to the `class` attribute on `<html>` — it does NOT suppress hydration warnings on other elements.
113
+
114
+ ## Symptom: Dark mode toggle does nothing
115
+
116
+ **Diagnosis:** The `.dark` class is not being applied to `<html>` (or any ancestor of the components).
117
+
118
+ Quick verification — open the browser console and run:
119
+
120
+ ```js
121
+ document.documentElement.classList.add("dark");
122
+ ```
123
+
124
+ If components now render in dark mode, the toggle wiring is broken (not the design system). Check:
125
+
126
+ - `next-themes` is installed and `<ThemeProvider attribute="class">` wraps the app
127
+ - For Vite/Remix/Astro/TanStack: the `theme-bootstrap.js` script runs before any React mount
128
+
129
+ If `.dark` IS on `<html>` and components still look light, the CSS imports are out of order — see the first symptom above.
130
+
131
+ ## Symptom: RSC error — `You're importing a component that needs useState. It only works in a Client Component`
132
+
133
+ **Diagnosis:** A client-only shilp-sutra component is being imported into a Server Component via the barrel.
134
+
135
+ Switch to per-component imports:
136
+
137
+ ```tsx
138
+ // ❌ pulls client code into RSC
139
+ import { Button } from "@devalok/shilp-sutra/ui";
140
+
141
+ // ✅ component-scoped, declares "use client" only where needed
142
+ import { Button } from "@devalok/shilp-sutra/ui/button";
143
+ ```
144
+
145
+ For the full RSC-safety matrix, see [server-components.md](./server-components.md).
146
+
147
+ ## Symptom: Fonts render in browser default (Times/Arial), not Inter/Ranade
148
+
149
+ **Diagnosis:** Either the CSS import did not load (see first symptom), or the consumer is overriding `--font-sans` / `--font-display` and pointing at a font that isn't loaded.
150
+
151
+ Check the computed value of `--font-sans` on `<html>` in DevTools. It should be `"Inter Variable", system-ui, ...`. If the override variable points at a font that isn't loaded, the browser falls back.
152
+
153
+ The font files ship inside the package — no `next/font` configuration is required for the defaults to work.
154
+
155
+ ## Symptom: Bare `shadow` class produces no visible shadow
156
+
157
+ **Diagnosis:** Working as designed. Tailwind 4 has no default `--shadow` token, so the `shadow` utility no longer exists.
158
+
159
+ Use the explicit shadow variants:
160
+
161
+ - `shadow-raised` — cards, buttons
162
+ - `shadow-overlay` — popovers, dropdowns
163
+ - `shadow-floating` — modals, dialogs
164
+ - `shadow-brand` — accent emphasis
165
+
166
+ ## Symptom: `<Toaster />` is mounted but `toast()` doesn't show anything
167
+
168
+ **Diagnosis:** Either `sonner` is not installed, or two `<Toaster />` instances are mounted at different positions and they're stacking off-screen.
169
+
170
+ Check 1 — `pnpm list sonner` shows `^2.0.0` or higher.
171
+
172
+ Check 2 — only ONE `<Toaster />` is mounted in the app. Search the project: `grep -r "<Toaster" src/ app/`.
173
+
174
+ In dev mode, calling `toast()` without a mounted `<Toaster />` logs a one-time console warning pointing to the fix (since v0.36.0).
175
+
176
+ ## Symptom: Build error mentioning `use-sync-external-store`
177
+
178
+ **Diagnosis:** Should not happen since v0.37.0 — `use-sync-external-store` was moved to runtime dependencies and is auto-installed transitively.
179
+
180
+ If it still happens, install it explicitly:
181
+
182
+ ```bash
183
+ pnpm add use-sync-external-store
184
+ ```
185
+
186
+ And open an issue at <https://github.com/devalok-design/shilp-sutra/issues> with the resolution graph (`pnpm why use-sync-external-store`) so we can fix the root cause.
187
+
188
+ ## Symptom: Storybook MCP server `localhost:6006/mcp` returns 404
189
+
190
+ **Diagnosis:** Storybook dev server isn't running, OR the MCP plugin is not enabled in this Storybook version.
191
+
192
+ Check 1 — `pnpm dev` is running and `http://localhost:6006/` shows the Storybook UI.
193
+ Check 2 — the MCP endpoint requires Storybook 9+ with the MCP plugin enabled. Older versions of this repo's Storybook setup may need an upgrade.
194
+
195
+ The MCP server is a development convenience for AI agents — `llms.txt` and `llms-full.txt` are the authoritative docs and do not require a running server.
196
+
197
+ ## Still stuck
198
+
199
+ Open an issue with this template:
200
+
201
+ ```md
202
+ ## Environment
203
+ - Framework + version (Next.js 15.x / Vite 5.x / Remix 2.x / Astro 5.x / TanStack Start ...)
204
+ - Package manager + version (pnpm 10.x / npm 11.x / yarn / bun)
205
+ - Node version
206
+ - @devalok/shilp-sutra version
207
+ - Other peer deps (framer-motion, sonner, tailwindcss versions)
208
+
209
+ ## What I tried
210
+ [Recipe followed, step where it broke]
211
+
212
+ ## What happened
213
+ [Exact error message, stack trace, screenshot]
214
+
215
+ ## What I expected
216
+ [Behavior described in the recipe]
217
+ ```
218
+
219
+ File at: <https://github.com/devalok-design/shilp-sutra/issues/new>
File without changes