@devalok/shilp-sutra 0.37.1 → 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 (260) hide show
  1. package/MIGRATION.md +185 -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/tiptap.js +977 -968
  25. package/dist/_chunks/tiptap.js.map +1 -1
  26. package/dist/_chunks/tree-view.js +1 -1
  27. package/dist/_chunks/tree-view.js.map +1 -1
  28. package/dist/_chunks/use-calendar.js +5 -5
  29. package/dist/_chunks/use-calendar.js.map +1 -1
  30. package/dist/ai/command-bar.js +10 -10
  31. package/dist/ai/command-bar.js.map +1 -1
  32. package/dist/ai/conversation.js +4 -4
  33. package/dist/ai/conversation.js.map +1 -1
  34. package/dist/composed/activity-feed.js +5 -5
  35. package/dist/composed/activity-feed.js.map +1 -1
  36. package/dist/composed/avatar-group.js +4 -4
  37. package/dist/composed/avatar-group.js.map +1 -1
  38. package/dist/composed/bulk-action-bar.js +1 -1
  39. package/dist/composed/bulk-action-bar.js.map +1 -1
  40. package/dist/composed/command-palette.js +5 -5
  41. package/dist/composed/command-palette.js.map +1 -1
  42. package/dist/composed/content-card.js +1 -1
  43. package/dist/composed/content-card.js.map +1 -1
  44. package/dist/composed/emoji-picker.js +4 -4
  45. package/dist/composed/emoji-picker.js.map +1 -1
  46. package/dist/composed/empty-state.js +1 -1
  47. package/dist/composed/empty-state.js.map +1 -1
  48. package/dist/composed/error-boundary.js +3 -3
  49. package/dist/composed/error-boundary.js.map +1 -1
  50. package/dist/composed/filter-bar.js +1 -1
  51. package/dist/composed/filter-bar.js.map +1 -1
  52. package/dist/composed/index.d.ts +0 -2
  53. package/dist/composed/index.d.ts.map +1 -1
  54. package/dist/composed/index.js +5 -6
  55. package/dist/composed/inline-edit.js +1 -1
  56. package/dist/composed/inline-edit.js.map +1 -1
  57. package/dist/composed/loading-skeleton.js +9 -9
  58. package/dist/composed/loading-skeleton.js.map +1 -1
  59. package/dist/composed/markdown-viewer.js +3 -3
  60. package/dist/composed/markdown-viewer.js.map +1 -1
  61. package/dist/composed/multi-select-popover.js +1 -1
  62. package/dist/composed/multi-select-popover.js.map +1 -1
  63. package/dist/composed/page-header.js +1 -1
  64. package/dist/composed/page-header.js.map +1 -1
  65. package/dist/composed/page-skeletons.js +15 -15
  66. package/dist/composed/page-skeletons.js.map +1 -1
  67. package/dist/composed/priority-indicator.js +3 -3
  68. package/dist/composed/priority-indicator.js.map +1 -1
  69. package/dist/composed/rich-text-editor.js +11 -11
  70. package/dist/composed/rich-text-editor.js.map +1 -1
  71. package/dist/composed/schedule-view.js +3 -3
  72. package/dist/composed/schedule-view.js.map +1 -1
  73. package/dist/composed/status-badge.js +3 -3
  74. package/dist/composed/status-badge.js.map +1 -1
  75. package/dist/hooks/index.d.ts +2 -2
  76. package/dist/hooks/index.d.ts.map +1 -1
  77. package/dist/hooks/index.js +0 -1
  78. package/dist/shell/bottom-navbar.js +6 -6
  79. package/dist/shell/bottom-navbar.js.map +1 -1
  80. package/dist/shell/notification-center.js +8 -8
  81. package/dist/shell/notification-center.js.map +1 -1
  82. package/dist/shell/notification-preferences.js +1 -1
  83. package/dist/shell/notification-preferences.js.map +1 -1
  84. package/dist/shell/sidebar.js +6 -6
  85. package/dist/shell/sidebar.js.map +1 -1
  86. package/dist/shell/top-bar.js +4 -4
  87. package/dist/shell/top-bar.js.map +1 -1
  88. package/dist/tokens/semantic.css +82 -9
  89. package/dist/ui/accordion.js +1 -1
  90. package/dist/ui/accordion.js.map +1 -1
  91. package/dist/ui/alert-dialog.js +3 -3
  92. package/dist/ui/alert-dialog.js.map +1 -1
  93. package/dist/ui/alert.d.ts +1 -2
  94. package/dist/ui/alert.d.ts.map +1 -1
  95. package/dist/ui/alert.js +3 -29
  96. package/dist/ui/alert.js.map +1 -1
  97. package/dist/ui/autocomplete.js +2 -2
  98. package/dist/ui/autocomplete.js.map +1 -1
  99. package/dist/ui/avatar.js +11 -11
  100. package/dist/ui/avatar.js.map +1 -1
  101. package/dist/ui/badge-indicator.js +1 -1
  102. package/dist/ui/badge-indicator.js.map +1 -1
  103. package/dist/ui/banner.d.ts +3 -5
  104. package/dist/ui/banner.d.ts.map +1 -1
  105. package/dist/ui/banner.js +14 -14
  106. package/dist/ui/banner.js.map +1 -1
  107. package/dist/ui/breadcrumb.js +1 -1
  108. package/dist/ui/breadcrumb.js.map +1 -1
  109. package/dist/ui/button.d.ts +2 -2
  110. package/dist/ui/button.js +14 -14
  111. package/dist/ui/button.js.map +1 -1
  112. package/dist/ui/card.js +5 -5
  113. package/dist/ui/card.js.map +1 -1
  114. package/dist/ui/charts/index.js +5 -5
  115. package/dist/ui/charts/index.js.map +1 -1
  116. package/dist/ui/checkbox.js +1 -1
  117. package/dist/ui/checkbox.js.map +1 -1
  118. package/dist/ui/code.js +2 -2
  119. package/dist/ui/code.js.map +1 -1
  120. package/dist/ui/color-input.js +10 -10
  121. package/dist/ui/color-input.js.map +1 -1
  122. package/dist/ui/color-swatch.js +3 -3
  123. package/dist/ui/color-swatch.js.map +1 -1
  124. package/dist/ui/combobox.js +5 -5
  125. package/dist/ui/combobox.js.map +1 -1
  126. package/dist/ui/context-menu.js +6 -6
  127. package/dist/ui/context-menu.js.map +1 -1
  128. package/dist/ui/data-table-body.js +1 -1
  129. package/dist/ui/data-table-body.js.map +1 -1
  130. package/dist/ui/data-table-bulk-actions.js +2 -2
  131. package/dist/ui/data-table-bulk-actions.js.map +1 -1
  132. package/dist/ui/data-table-card.js +2 -2
  133. package/dist/ui/data-table-card.js.map +1 -1
  134. package/dist/ui/data-table-header.js +2 -2
  135. package/dist/ui/data-table-header.js.map +1 -1
  136. package/dist/ui/data-table-pagination.js +3 -3
  137. package/dist/ui/data-table-pagination.js.map +1 -1
  138. package/dist/ui/data-table-toolbar.js +1 -1
  139. package/dist/ui/data-table-toolbar.js.map +1 -1
  140. package/dist/ui/data-table.js +1 -1
  141. package/dist/ui/data-table.js.map +1 -1
  142. package/dist/ui/devalok-grain.d.ts +1 -1
  143. package/dist/ui/devalok-grain.js.map +1 -1
  144. package/dist/ui/dialog.js +2 -2
  145. package/dist/ui/dialog.js.map +1 -1
  146. package/dist/ui/dropdown-menu.js +6 -6
  147. package/dist/ui/dropdown-menu.js.map +1 -1
  148. package/dist/ui/file-upload.js +4 -4
  149. package/dist/ui/file-upload.js.map +1 -1
  150. package/dist/ui/hover-card.js +1 -1
  151. package/dist/ui/hover-card.js.map +1 -1
  152. package/dist/ui/icon-button.js +1 -1
  153. package/dist/ui/icon-button.js.map +1 -1
  154. package/dist/ui/index.d.ts +1 -1
  155. package/dist/ui/index.d.ts.map +1 -1
  156. package/dist/ui/index.js +2 -2
  157. package/dist/ui/index.js.map +1 -1
  158. package/dist/ui/input-otp.js +1 -1
  159. package/dist/ui/input-otp.js.map +1 -1
  160. package/dist/ui/input.d.ts +1 -9
  161. package/dist/ui/input.d.ts.map +1 -1
  162. package/dist/ui/input.js +28 -29
  163. package/dist/ui/input.js.map +1 -1
  164. package/dist/ui/link.js +1 -1
  165. package/dist/ui/link.js.map +1 -1
  166. package/dist/ui/menubar.js +8 -8
  167. package/dist/ui/menubar.js.map +1 -1
  168. package/dist/ui/navigation-menu.js +3 -3
  169. package/dist/ui/navigation-menu.js.map +1 -1
  170. package/dist/ui/number-input.js +3 -3
  171. package/dist/ui/number-input.js.map +1 -1
  172. package/dist/ui/pagination.js +1 -1
  173. package/dist/ui/pagination.js.map +1 -1
  174. package/dist/ui/progress.js +1 -1
  175. package/dist/ui/progress.js.map +1 -1
  176. package/dist/ui/radio.js +1 -1
  177. package/dist/ui/radio.js.map +1 -1
  178. package/dist/ui/segmented-control.d.ts +1 -1
  179. package/dist/ui/segmented-control.d.ts.map +1 -1
  180. package/dist/ui/segmented-control.js +5 -7
  181. package/dist/ui/segmented-control.js.map +1 -1
  182. package/dist/ui/select.js +3 -3
  183. package/dist/ui/select.js.map +1 -1
  184. package/dist/ui/sheet.js +2 -2
  185. package/dist/ui/sheet.js.map +1 -1
  186. package/dist/ui/sidebar.js +11 -11
  187. package/dist/ui/sidebar.js.map +1 -1
  188. package/dist/ui/skeleton.js +9 -9
  189. package/dist/ui/skeleton.js.map +1 -1
  190. package/dist/ui/slider.js +2 -2
  191. package/dist/ui/slider.js.map +1 -1
  192. package/dist/ui/split-button.js +7 -7
  193. package/dist/ui/split-button.js.map +1 -1
  194. package/dist/ui/stat-card.js +7 -7
  195. package/dist/ui/stat-card.js.map +1 -1
  196. package/dist/ui/status-dot.js +2 -2
  197. package/dist/ui/status-dot.js.map +1 -1
  198. package/dist/ui/stepper.js +2 -2
  199. package/dist/ui/stepper.js.map +1 -1
  200. package/dist/ui/switch.js +2 -2
  201. package/dist/ui/switch.js.map +1 -1
  202. package/dist/ui/tabs.js +3 -3
  203. package/dist/ui/tabs.js.map +1 -1
  204. package/dist/ui/textarea.js +1 -1
  205. package/dist/ui/textarea.js.map +1 -1
  206. package/dist/ui/toast.js +8 -8
  207. package/dist/ui/toast.js.map +1 -1
  208. package/dist/ui/toggle.js +1 -1
  209. package/dist/ui/toggle.js.map +1 -1
  210. package/dist/ui/tooltip.js +1 -1
  211. package/dist/ui/tooltip.js.map +1 -1
  212. package/docs/components/_header.md +91 -2
  213. package/docs/components/ui/alert.md +4 -1
  214. package/docs/components/ui/banner.md +3 -1
  215. package/docs/components/ui/input.md +4 -2
  216. package/docs/components/ui/segmented-control.md +13 -6
  217. package/docs/recipes/customize-brand.md +297 -0
  218. package/docs/recipes/index.md +51 -0
  219. package/docs/recipes/install-astro.md +178 -0
  220. package/docs/recipes/install-next-app-router.md +230 -0
  221. package/docs/recipes/install-next-pages.md +123 -0
  222. package/docs/recipes/install-remix.md +171 -0
  223. package/docs/recipes/install-tanstack-start.md +143 -0
  224. package/docs/recipes/install-vite.md +170 -0
  225. package/docs/recipes/server-components.md +209 -0
  226. package/docs/recipes/troubleshoot.md +217 -0
  227. package/llms-full.txt +116 -54
  228. package/llms.txt +42 -17
  229. package/package.json +46 -35
  230. package/skill/README.md +99 -0
  231. package/skill/SKILL.md +144 -0
  232. package/skill/install.sh +59 -0
  233. package/skill/references/components-full.md +6997 -0
  234. package/skill/references/components.md +673 -0
  235. package/skill/references/customize-brand.md +299 -0
  236. package/skill/references/server-components.md +211 -0
  237. package/skill/references/setup-astro.md +180 -0
  238. package/skill/references/setup-next-app-router.md +232 -0
  239. package/skill/references/setup-next-pages.md +125 -0
  240. package/skill/references/setup-remix.md +173 -0
  241. package/skill/references/setup-tanstack-start.md +145 -0
  242. package/skill/references/setup-vite.md +172 -0
  243. package/skill/references/troubleshoot.md +219 -0
  244. package/dist/composed/responsive-overlay.d.ts +0 -23
  245. package/dist/composed/responsive-overlay.d.ts.map +0 -1
  246. package/dist/composed/responsive-overlay.js +0 -40
  247. package/dist/composed/responsive-overlay.js.map +0 -1
  248. package/dist/hooks/use-toast.d.ts +0 -17
  249. package/dist/hooks/use-toast.d.ts.map +0 -1
  250. package/dist/hooks/use-toast.js +0 -3
  251. package/dist/tailwind/index.cjs +0 -41
  252. package/dist/tailwind/index.d.ts +0 -2
  253. package/dist/tailwind/index.d.ts.map +0 -1
  254. package/dist/tailwind/index.js +0 -2
  255. package/dist/tailwind/preset.d.ts +0 -25
  256. package/dist/tailwind/preset.d.ts.map +0 -1
  257. package/dist/tailwind/preset.js +0 -17
  258. package/dist/tailwind/preset.js.map +0 -1
  259. package/docs/components/composed/responsive-overlay.md +0 -41
  260. /package/{LICENSE → skill/LICENSE} +0 -0
package/docs/recipes/customize-brand.md ADDED
@@ -0,0 +1,297 @@
1
+ # Customize: Brand & Tokens
2
+
3
+ Override colors, radius, fonts, and spacing without forking the package. All customization happens through CSS custom properties — no JS configuration.
4
+
5
+ ## How tokens layer
6
+
7
+ Shilp Sutra's tokens are organized in three tiers:
8
+
9
+ 1. **Primitives** (`primitives.css`) — raw OKLCH palette values. Private. You should not need to touch these.
10
+ 2. **Semantic** (`semantic.css`) — intent-based mappings (`--color-accent-9`, `--color-surface-2`, `--font-sans`). Public, exposed to Tailwind 4's `@theme`.
11
+ 3. **Utility output** — Tailwind generates classes (`bg-accent-9`, `text-surface-fg`, `font-sans`) from the semantic layer.
12
+
13
+ To override a token, redefine it AFTER the design-system import. The cascade does the rest.
14
+
15
+ ```css
16
+ @import "tailwindcss";
17
+ @import "@devalok/shilp-sutra/css";
18
+
19
+ @theme {
20
+ /* Overrides go here */
21
+ --color-accent-9: oklch(0.55 0.22 195);
22
+ }
23
+ ```
24
+
25
+ `@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).
26
+
27
+ ## Common overrides
28
+
29
+ ### Change the accent color
30
+
31
+ 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.
32
+
33
+ To swap to teal:
34
+
35
+ ```css
36
+ @theme {
37
+ --color-accent-1: oklch(0.985 0.005 195);
38
+ --color-accent-2: oklch(0.96 0.012 195);
39
+ --color-accent-3: oklch(0.92 0.025 195);
40
+ --color-accent-4: oklch(0.88 0.04 195);
41
+ --color-accent-5: oklch(0.82 0.07 195);
42
+ --color-accent-6: oklch(0.74 0.10 195);
43
+ --color-accent-7: oklch(0.66 0.14 195);
44
+ --color-accent-8: oklch(0.60 0.17 195);
45
+ --color-accent-9: oklch(0.54 0.22 195);
46
+ --color-accent-10: oklch(0.49 0.21 195);
47
+ --color-accent-11: oklch(0.42 0.16 195);
48
+ --color-accent-12: oklch(0.20 0.05 195);
49
+ }
50
+
51
+ .dark {
52
+ --color-accent-9: oklch(0.62 0.21 195);
53
+ /* ...override remaining steps for dark mode */
54
+ }
55
+ ```
56
+
57
+ 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.
58
+
59
+ ### Shape presets (`[data-shape]`)
60
+
61
+ The simplest way to change roundness for the whole UI is to set a `data-shape` attribute on the document (or any subtree). Three presets ship by default — `sharp`, `slightly-rounded` (the default if no attribute), and `rounded`. Pill shapes (Badge, Switch, Slider, Avatar circle) stay pill in every preset.
62
+
63
+ ```html
64
+ <!-- Whole-app, sharp/technical feel -->
65
+ <html data-shape="sharp">
66
+
67
+ <!-- Whole-app, soft/consumer feel -->
68
+ <html data-shape="rounded">
69
+ ```
70
+
71
+ You can scope it to a subtree if a particular section wants different shape language than the rest:
72
+
73
+ ```tsx
74
+ <div data-shape="sharp">
75
+ <DeveloperConsole />
76
+ </div>
77
+ ```
78
+
79
+ Visual feel:
80
+
81
+ | Preset | Identity | Comparable to |
82
+ |---|---|---|
83
+ | `sharp` | Technical, precise, "serious software" | Vercel, Linear, terminal UIs |
84
+ | `slightly-rounded` (default) | Modern SaaS neutral | shadcn default, Stripe, Notion sidebar |
85
+ | `rounded` | Friendly, soft, consumer | iOS, Notion content, modern startup landings |
86
+
87
+ ### Custom radius — override a role token
88
+
89
+ If a preset doesn't fit, you can override any semantic radius role token directly. Components reference these role tokens (not the primitive scale), so a single override propagates everywhere.
90
+
91
+ ```css
92
+ /* Tighten controls only; leave overlays / surfaces alone */
93
+ :root {
94
+ --radius-control: 4px;
95
+ }
96
+
97
+ /* Or scoped to a subtree */
98
+ .checkout {
99
+ --radius-control: 8px;
100
+ --radius-surface: 20px;
101
+ }
102
+ ```
103
+
104
+ The role tokens (defaults shown — the "slightly-rounded" preset):
105
+
106
+ | Token | Default | Used by |
107
+ |--------------------------|---------|---------|
108
+ | `--radius-control` | 6px | Button, Input, Select, Tabs trigger, Toggle, Code block |
109
+ | `--radius-control-inner` | 2px | Checkbox box, ±/close buttons, inline Code |
110
+ | `--radius-surface` | 10px | Card, Alert, Accordion |
111
+ | `--radius-overlay-sm` | 6px | Tooltip, Toast |
112
+ | `--radius-overlay` | 10px | Popover, HoverCard, DropdownMenu / ContextMenu / Menubar content, listboxes |
113
+ | `--radius-overlay-lg` | 16px | Dialog, AlertDialog, Sheet, BottomSheet, ColorInput picker |
114
+ | `--radius-pill` | 9999px | Badge, StatusDot, Radio, Switch, Slider, Progress, Avatar circle |
115
+ | `--radius-bubble` | 24px | ChatMessage bubble |
116
+
117
+ ### Build your own preset
118
+
119
+ Define your own `[data-shape="…"]` block and swap to it whenever you want:
120
+
121
+ ```css
122
+ [data-shape="brand-soft"] {
123
+ --radius-control: 8px;
124
+ --radius-control-inner: 3px;
125
+ --radius-surface: 14px;
126
+ --radius-overlay-sm: 8px;
127
+ --radius-overlay: 14px;
128
+ --radius-overlay-lg: 20px;
129
+ --radius-pill: 9999px;
130
+ --radius-bubble: 28px;
131
+ }
132
+ ```
133
+
134
+ ```html
135
+ <html data-shape="brand-soft">
136
+ ```
137
+
138
+ ### Change the primitive radius scale (advanced)
139
+
140
+ If you're rebuilding the entire system rather than just rebranding, you can also override the primitive scale that the role tokens reference:
141
+
142
+ ```css
143
+ @theme {
144
+ --radius-ds-sm: 0.25rem;
145
+ --radius-ds-md: 0.5rem;
146
+ --radius-ds-lg: 0.75rem;
147
+ --radius-ds-xl: 1rem;
148
+ --radius: 0.5rem; /* unsuffixed — generates bare `rounded` */
149
+ }
150
+ ```
151
+
152
+ Most consumers should NOT touch this — overriding the role tokens above is the cleaner path.
153
+
154
+ ### Change fonts
155
+
156
+ The design system uses three font families, each backed by a CSS variable:
157
+
158
+ - `--font-sans` — Inter (body)
159
+ - `--font-display` — Ranade (headings)
160
+ - `--font-mono` — JetBrains Mono (code)
161
+
162
+ To swap with `next/font`:
163
+
164
+ ```tsx
165
+ // app/layout.tsx (Next.js App Router)
166
+ import { Inter, Plus_Jakarta_Sans, JetBrains_Mono } from "next/font/google";
167
+
168
+ const fontSans = Plus_Jakarta_Sans({ subsets: ["latin"], variable: "--font-sans" });
169
+ const fontDisplay = Plus_Jakarta_Sans({ subsets: ["latin"], weight: "700", variable: "--font-display" });
170
+ const fontMono = JetBrains_Mono({ subsets: ["latin"], variable: "--font-mono" });
171
+
172
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
173
+ return (
174
+ <html lang="en" className={`${fontSans.variable} ${fontDisplay.variable} ${fontMono.variable}`}>
175
+ <body>{children}</body>
176
+ </html>
177
+ );
178
+ }
179
+ ```
180
+
181
+ For Vite/Remix/Astro/TanStack, drop the `@font-face` declarations into the global CSS and override the variables:
182
+
183
+ ```css
184
+ @font-face {
185
+ font-family: "Plus Jakarta Sans";
186
+ src: url("/fonts/PlusJakartaSans-Variable.woff2") format("woff2");
187
+ font-weight: 100 900;
188
+ font-display: swap;
189
+ }
190
+
191
+ @theme {
192
+ --font-sans: "Plus Jakarta Sans", system-ui, sans-serif;
193
+ --font-display: "Plus Jakarta Sans", system-ui, sans-serif;
194
+ }
195
+ ```
196
+
197
+ ### Change the spacing scale
198
+
199
+ 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.
200
+
201
+ ```css
202
+ @theme {
203
+ --spacing-ds-00: 0;
204
+ --spacing-ds-01: 0.125rem;
205
+ --spacing-ds-02: 0.25rem;
206
+ --spacing-ds-03: 0.5rem;
207
+ --spacing-ds-04: 0.75rem;
208
+ --spacing-ds-05: 1rem;
209
+ /* etc. */
210
+ }
211
+ ```
212
+
213
+ 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.
214
+
215
+ ### Change a single shadow
216
+
217
+ ```css
218
+ @theme {
219
+ --shadow-raised: 0 1px 2px oklch(0 0 0 / 0.06), 0 2px 4px oklch(0 0 0 / 0.04);
220
+ }
221
+ ```
222
+
223
+ 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.
224
+
225
+ ## Light + dark in lockstep
226
+
227
+ Every override should consider both modes. Pattern:
228
+
229
+ ```css
230
+ @theme {
231
+ --color-accent-9: oklch(0.54 0.22 195);
232
+ --color-accent-fg: oklch(0.99 0 0);
233
+ }
234
+
235
+ /* Dark mode override */
236
+ .dark {
237
+ --color-accent-9: oklch(0.62 0.21 195);
238
+ --color-accent-fg: oklch(0.10 0 0);
239
+ }
240
+ ```
241
+
242
+ `.dark` is a regular class selector — its specificity is higher than `:root`/`@theme` body, so dark-mode overrides win when the class is active.
243
+
244
+ ## Forced colors (Windows high-contrast)
245
+
246
+ 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.
247
+
248
+ If you need a custom forced-colors mapping, override inside `@media (forced-colors: active)`:
249
+
250
+ ```css
251
+ @media (forced-colors: active) {
252
+ :root {
253
+ --color-accent-9: Highlight;
254
+ --color-accent-fg: HighlightText;
255
+ }
256
+ }
257
+ ```
258
+
259
+ ## Per-route theming
260
+
261
+ Apply a class on a wrapper element to scope token overrides:
262
+
263
+ ```css
264
+ .theme-karm {
265
+ --color-accent-9: oklch(0.55 0.22 195);
266
+ }
267
+ .theme-karm.dark,
268
+ .dark .theme-karm {
269
+ --color-accent-9: oklch(0.62 0.21 195);
270
+ }
271
+ ```
272
+
273
+ Then:
274
+
275
+ ```tsx
276
+ <div className="theme-karm">
277
+ <Button>Karm-themed</Button>
278
+ </div>
279
+ ```
280
+
281
+ ## What you cannot override via CSS variables
282
+
283
+ - The component DOM structure (use the `asChild` pattern or wrap the component to insert)
284
+ - The vendored Radix primitives' behavior
285
+ - Animation keyframes (override the `--animate-*` references via `@theme` — but the keyframe definitions themselves are package-private)
286
+
287
+ For deeper changes, fork the source or use the `className` prop with arbitrary Tailwind utilities to layer styling on top.
288
+
289
+ ## Verifying an override
290
+
291
+ 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.
292
+
293
+ If the override isn't winning, check:
294
+
295
+ 1. The `@theme` override comes AFTER `@import "@devalok/shilp-sutra/css";` in source order
296
+ 2. There's no `!important` in the package overriding you (there isn't — file an issue if you find one)
297
+ 3. The selector specificity matches the target (`.dark` class is on a parent of the inspected element, etc.)
package/docs/recipes/index.md ADDED
@@ -0,0 +1,51 @@
1
+ # Recipes
2
+
3
+ Copy-paste-ready setup guides for installing and customizing **`@devalok/shilp-sutra`** in any React project.
4
+
5
+ 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.
6
+
7
+ When the package is installed, recipes ship at:
8
+
9
+ ```
10
+ node_modules/@devalok/shilp-sutra/docs/recipes/
11
+ ```
12
+
13
+ ## Install recipes
14
+
15
+ Pick the recipe that matches your framework. Detection criteria are listed at the top of each file.
16
+
17
+ | Framework | Recipe | When to pick it |
18
+ |---|---|---|
19
+ | Next.js (App Router) | [install-next-app-router.md](./install-next-app-router.md) | `app/` directory exists; using React Server Components |
20
+ | Next.js (Pages Router) | [install-next-pages.md](./install-next-pages.md) | `pages/` directory is the primary router; legacy or pre-13 codebases |
21
+ | Vite + React | [install-vite.md](./install-vite.md) | `vite.config.*` exists; SPA or MPA |
22
+ | Astro | [install-astro.md](./install-astro.md) | `astro.config.*` exists |
23
+ | Remix | [install-remix.md](./install-remix.md) | `remix.config.*` or Remix v2 with Vite |
24
+ | TanStack Start | [install-tanstack-start.md](./install-tanstack-start.md) | `app.config.*` with `@tanstack/start` |
25
+
26
+ If the framework is not listed, start with [install-vite.md](./install-vite.md) and adapt — most React+Tailwind setups follow the same shape.
27
+
28
+ ## Customization recipes
29
+
30
+ | Recipe | What it covers |
31
+ |---|---|
32
+ | [customize-brand.md](./customize-brand.md) | Token override cookbook — colors, radius role tokens, `[data-shape]` presets, fonts, spacing scale, dark-mode mapping |
33
+ | [server-components.md](./server-components.md) | Per-component RSC-safety matrix; correct import patterns for Server Components |
34
+
35
+ ## Diagnostics
36
+
37
+ | Recipe | What it covers |
38
+ |---|---|
39
+ | [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 |
40
+
41
+ ## What every recipe assumes
42
+
43
+ - React `^18 || ^19`
44
+ - Node `>= 18.18` (no `engines.node` declared by us, but Tailwind 4 + Vite 5+ require it)
45
+ - A bundler that supports CSS imports from `node_modules` (every modern React framework does)
46
+
47
+ ## What every recipe excludes
48
+
49
+ - Database/auth/state-management setup — out of scope. Shilp Sutra is presentation-only.
50
+ - IDE configuration — your call.
51
+ - Testing setup — see [packages/core/CONTRIBUTING.md](../../CONTRIBUTING.md) if contributing to the design system itself.
package/docs/recipes/install-astro.md ADDED
@@ -0,0 +1,178 @@
1
+ # Install: Astro
2
+
3
+ > Setup recipe for adding `@devalok/shilp-sutra` to an Astro project with React islands.
4
+
5
+ ## 1. Detect
6
+
7
+ You are in this recipe if:
8
+
9
+ - `astro.config.{ts,mjs,js}` exists at the project root
10
+ - `package.json` lists `"astro"`
11
+ - React is integrated via `@astrojs/react`
12
+
13
+ If `@astrojs/react` is not installed, install it first:
14
+
15
+ ```bash
16
+ pnpm astro add react
17
+ ```
18
+
19
+ ## 2. Install dependencies
20
+
21
+ ```bash
22
+ pnpm add @devalok/shilp-sutra framer-motion
23
+ pnpm add -D tailwindcss@^4 @tailwindcss/vite
24
+ ```
25
+
26
+ Add only if rendering `<Toaster />`:
27
+
28
+ ```bash
29
+ pnpm add sonner
30
+ ```
31
+
32
+ ## 3. Wire Tailwind 4 in `astro.config`
33
+
34
+ Astro has its own `@astrojs/tailwind` integration, but for Tailwind 4 use the Vite plugin directly (Astro 4.5+ supports this):
35
+
36
+ ```ts
37
+ // astro.config.ts
38
+ import { defineConfig } from "astro/config";
39
+ import react from "@astrojs/react";
40
+ import tailwindcss from "@tailwindcss/vite";
41
+
42
+ export default defineConfig({
43
+ integrations: [react()],
44
+ vite: {
45
+ plugins: [tailwindcss()],
46
+ },
47
+ });
48
+ ```
49
+
50
+ Do **not** also enable `@astrojs/tailwind` — that integration is Tailwind 3 only and will conflict.
51
+
52
+ ## 4. Wire tokens
53
+
54
+ Create `src/styles/globals.css`:
55
+
56
+ ```css
57
+ @import "tailwindcss";
58
+ @import "@devalok/shilp-sutra/css";
59
+ ```
60
+
61
+ Import it from a layout component (e.g., `src/layouts/BaseLayout.astro`):
62
+
63
+ ```astro
64
+ ---
65
+ import "../styles/globals.css";
66
+ const { title = "App" } = Astro.props;
67
+ ---
68
+ <!doctype html>
69
+ <html lang="en" class="">
70
+ <head>
71
+ <meta charset="utf-8" />
72
+ <meta name="viewport" content="width=device-width" />
73
+ <title>{title}</title>
74
+ </head>
75
+ <body>
76
+ <slot />
77
+ </body>
78
+ </html>
79
+ ```
80
+
81
+ ## 5. Theme toggle
82
+
83
+ Add the bootstrap script to `<head>` of `BaseLayout.astro` (before stylesheet imports):
84
+
85
+ ```astro
86
+ ---
87
+ import "../styles/globals.css";
88
+ ---
89
+ <!doctype html>
90
+ <html lang="en">
91
+ <head>
92
+ <script is:inline>
93
+ try {
94
+ var stored = localStorage.getItem("theme");
95
+ var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
96
+ if (stored === "dark" || (!stored && prefersDark))
97
+ document.documentElement.classList.add("dark");
98
+ } catch (e) {}
99
+ </script>
100
+ <!-- ... -->
101
+ </head>
102
+ <body><slot /></body>
103
+ </html>
104
+ ```
105
+
106
+ `is:inline` keeps it out of bundling, so it runs before any other JS.
107
+
108
+ 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).
109
+
110
+ ## 6. Use components in islands
111
+
112
+ Shilp Sutra components are **client-only** (they use React hooks). Mount them in islands with a `client:*` directive:
113
+
114
+ ```astro
115
+ ---
116
+ import { Button } from "@devalok/shilp-sutra/ui/button";
117
+ ---
118
+ <Button client:load>Hello</Button>
119
+ ```
120
+
121
+ Static / non-interactive primitives (Text, Stack, Container, Code, VisuallyHidden) work without `client:*` because they render to static markup. Per-component imports are still required.
122
+
123
+ ## 7. Toaster (optional)
124
+
125
+ Mount once in a top-level island. The simplest approach is a small React wrapper component:
126
+
127
+ ```tsx
128
+ // src/components/AppToaster.tsx
129
+ "use client";
130
+ import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
131
+ export default function AppToaster() {
132
+ return <Toaster />;
133
+ }
134
+ ```
135
+
136
+ ```astro
137
+ ---
138
+ import AppToaster from "../components/AppToaster";
139
+ ---
140
+ <AppToaster client:load />
141
+ ```
142
+
143
+ ## 8. Verify
144
+
145
+ Create `src/pages/index.astro`:
146
+
147
+ ```astro
148
+ ---
149
+ import BaseLayout from "../layouts/BaseLayout.astro";
150
+ import { Button } from "@devalok/shilp-sutra/ui/button";
151
+ import { Stack } from "@devalok/shilp-sutra/ui/stack";
152
+ import { Text } from "@devalok/shilp-sutra/ui/text";
153
+ ---
154
+ <BaseLayout title="Home">
155
+ <Stack className="p-ds-08" gap="ds-04">
156
+ <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
157
+ <Stack direction="row" gap="ds-03">
158
+ <Button client:load>Primary</Button>
159
+ <Button client:load variant="soft">Soft</Button>
160
+ </Stack>
161
+ </Stack>
162
+ </BaseLayout>
163
+ ```
164
+
165
+ Run `pnpm dev` and open the URL.
166
+
167
+ ## 9. Astro-specific gotchas
168
+
169
+ - **No `transpilePackages` equivalent — and you do not need one.** Astro's Vite uses native ESM and resolves `@devalok/shilp-sutra` from `node_modules` directly.
170
+ - **Component must be inside a `client:*` island to be interactive.** A button without `client:load` will render but not respond to clicks.
171
+ - **Server-side islands (`server:defer`)** — fine, but RSC import rules apply (per-component imports only). See [server-components.md](./server-components.md).
172
+ - **`@astrojs/tailwind` and `@tailwindcss/vite` conflict.** Pick one. For Tailwind 4 use the Vite plugin.
173
+
174
+ ## 10. What NOT to do
175
+
176
+ - ❌ Use `@astrojs/tailwind` (Tailwind 3 only).
177
+ - ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
178
+ - ❌ Import shilp-sutra components into a `.astro` file expecting interactivity without `client:*`.