@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/skill/references/customize-brand.md ADDED
@@ -0,0 +1,299 @@
1
+ <!-- Source: packages/core/docs/recipes/customize-brand.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
2
+
3
+ # Customize: Brand & Tokens
4
+
5
+ Override colors, radius, fonts, and spacing without forking the package. All customization happens through CSS custom properties — no JS configuration.
6
+
7
+ ## How tokens layer
8
+
9
+ Shilp Sutra's tokens are organized in three tiers:
10
+
11
+ 1. **Primitives** (`primitives.css`) — raw OKLCH palette values. Private. You should not need to touch these.
12
+ 2. **Semantic** (`semantic.css`) — intent-based mappings (`--color-accent-9`, `--color-surface-2`, `--font-sans`). Public, exposed to Tailwind 4's `@theme`.
13
+ 3. **Utility output** — Tailwind generates classes (`bg-accent-9`, `text-surface-fg`, `font-sans`) from the semantic layer.
14
+
15
+ To override a token, redefine it AFTER the design-system import. The cascade does the rest.
16
+
17
+ ```css
18
+ @import "tailwindcss";
19
+ @import "@devalok/shilp-sutra/css";
20
+
21
+ @theme {
22
+ /* Overrides go here */
23
+ --color-accent-9: oklch(0.55 0.22 195);
24
+ }
25
+ ```
26
+
27
+ `@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).
28
+
29
+ ## Common overrides
30
+
31
+ ### Change the accent color
32
+
33
+ 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.
34
+
35
+ To swap to teal:
36
+
37
+ ```css
38
+ @theme {
39
+ --color-accent-1: oklch(0.985 0.005 195);
40
+ --color-accent-2: oklch(0.96 0.012 195);
41
+ --color-accent-3: oklch(0.92 0.025 195);
42
+ --color-accent-4: oklch(0.88 0.04 195);
43
+ --color-accent-5: oklch(0.82 0.07 195);
44
+ --color-accent-6: oklch(0.74 0.10 195);
45
+ --color-accent-7: oklch(0.66 0.14 195);
46
+ --color-accent-8: oklch(0.60 0.17 195);
47
+ --color-accent-9: oklch(0.54 0.22 195);
48
+ --color-accent-10: oklch(0.49 0.21 195);
49
+ --color-accent-11: oklch(0.42 0.16 195);
50
+ --color-accent-12: oklch(0.20 0.05 195);
51
+ }
52
+
53
+ .dark {
54
+ --color-accent-9: oklch(0.62 0.21 195);
55
+ /* ...override remaining steps for dark mode */
56
+ }
57
+ ```
58
+
59
+ 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.
60
+
61
+ ### Shape presets (`[data-shape]`)
62
+
63
+ 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.
64
+
65
+ ```html
66
+ <!-- Whole-app, sharp/technical feel -->
67
+ <html data-shape="sharp">
68
+
69
+ <!-- Whole-app, soft/consumer feel -->
70
+ <html data-shape="rounded">
71
+ ```
72
+
73
+ You can scope it to a subtree if a particular section wants different shape language than the rest:
74
+
75
+ ```tsx
76
+ <div data-shape="sharp">
77
+ <DeveloperConsole />
78
+ </div>
79
+ ```
80
+
81
+ Visual feel:
82
+
83
+ | Preset | Identity | Comparable to |
84
+ |---|---|---|
85
+ | `sharp` | Technical, precise, "serious software" | Vercel, Linear, terminal UIs |
86
+ | `slightly-rounded` (default) | Modern SaaS neutral | shadcn default, Stripe, Notion sidebar |
87
+ | `rounded` | Friendly, soft, consumer | iOS, Notion content, modern startup landings |
88
+
89
+ ### Custom radius — override a role token
90
+
91
+ 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.
92
+
93
+ ```css
94
+ /* Tighten controls only; leave overlays / surfaces alone */
95
+ :root {
96
+ --radius-control: 4px;
97
+ }
98
+
99
+ /* Or scoped to a subtree */
100
+ .checkout {
101
+ --radius-control: 8px;
102
+ --radius-surface: 20px;
103
+ }
104
+ ```
105
+
106
+ The role tokens (defaults shown — the "slightly-rounded" preset):
107
+
108
+ | Token | Default | Used by |
109
+ |--------------------------|---------|---------|
110
+ | `--radius-control` | 6px | Button, Input, Select, Tabs trigger, Toggle, Code block |
111
+ | `--radius-control-inner` | 2px | Checkbox box, ±/close buttons, inline Code |
112
+ | `--radius-surface` | 10px | Card, Alert, Accordion |
113
+ | `--radius-overlay-sm` | 6px | Tooltip, Toast |
114
+ | `--radius-overlay` | 10px | Popover, HoverCard, DropdownMenu / ContextMenu / Menubar content, listboxes |
115
+ | `--radius-overlay-lg` | 16px | Dialog, AlertDialog, Sheet, BottomSheet, ColorInput picker |
116
+ | `--radius-pill` | 9999px | Badge, StatusDot, Radio, Switch, Slider, Progress, Avatar circle |
117
+ | `--radius-bubble` | 24px | ChatMessage bubble |
118
+
119
+ ### Build your own preset
120
+
121
+ Define your own `[data-shape="…"]` block and swap to it whenever you want:
122
+
123
+ ```css
124
+ [data-shape="brand-soft"] {
125
+ --radius-control: 8px;
126
+ --radius-control-inner: 3px;
127
+ --radius-surface: 14px;
128
+ --radius-overlay-sm: 8px;
129
+ --radius-overlay: 14px;
130
+ --radius-overlay-lg: 20px;
131
+ --radius-pill: 9999px;
132
+ --radius-bubble: 28px;
133
+ }
134
+ ```
135
+
136
+ ```html
137
+ <html data-shape="brand-soft">
138
+ ```
139
+
140
+ ### Change the primitive radius scale (advanced)
141
+
142
+ If you're rebuilding the entire system rather than just rebranding, you can also override the primitive scale that the role tokens reference:
143
+
144
+ ```css
145
+ @theme {
146
+ --radius-ds-sm: 0.25rem;
147
+ --radius-ds-md: 0.5rem;
148
+ --radius-ds-lg: 0.75rem;
149
+ --radius-ds-xl: 1rem;
150
+ --radius: 0.5rem; /* unsuffixed — generates bare `rounded` */
151
+ }
152
+ ```
153
+
154
+ Most consumers should NOT touch this — overriding the role tokens above is the cleaner path.
155
+
156
+ ### Change fonts
157
+
158
+ The design system uses three font families, each backed by a CSS variable:
159
+
160
+ - `--font-sans` — Inter (body)
161
+ - `--font-display` — Ranade (headings)
162
+ - `--font-mono` — JetBrains Mono (code)
163
+
164
+ To swap with `next/font`:
165
+
166
+ ```tsx
167
+ // app/layout.tsx (Next.js App Router)
168
+ import { Inter, Plus_Jakarta_Sans, JetBrains_Mono } from "next/font/google";
169
+
170
+ const fontSans = Plus_Jakarta_Sans({ subsets: ["latin"], variable: "--font-sans" });
171
+ const fontDisplay = Plus_Jakarta_Sans({ subsets: ["latin"], weight: "700", variable: "--font-display" });
172
+ const fontMono = JetBrains_Mono({ subsets: ["latin"], variable: "--font-mono" });
173
+
174
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
175
+ return (
176
+ <html lang="en" className={`${fontSans.variable} ${fontDisplay.variable} ${fontMono.variable}`}>
177
+ <body>{children}</body>
178
+ </html>
179
+ );
180
+ }
181
+ ```
182
+
183
+ For Vite/Remix/Astro/TanStack, drop the `@font-face` declarations into the global CSS and override the variables:
184
+
185
+ ```css
186
+ @font-face {
187
+ font-family: "Plus Jakarta Sans";
188
+ src: url("/fonts/PlusJakartaSans-Variable.woff2") format("woff2");
189
+ font-weight: 100 900;
190
+ font-display: swap;
191
+ }
192
+
193
+ @theme {
194
+ --font-sans: "Plus Jakarta Sans", system-ui, sans-serif;
195
+ --font-display: "Plus Jakarta Sans", system-ui, sans-serif;
196
+ }
197
+ ```
198
+
199
+ ### Change the spacing scale
200
+
201
+ 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.
202
+
203
+ ```css
204
+ @theme {
205
+ --spacing-ds-00: 0;
206
+ --spacing-ds-01: 0.125rem;
207
+ --spacing-ds-02: 0.25rem;
208
+ --spacing-ds-03: 0.5rem;
209
+ --spacing-ds-04: 0.75rem;
210
+ --spacing-ds-05: 1rem;
211
+ /* etc. */
212
+ }
213
+ ```
214
+
215
+ 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.
216
+
217
+ ### Change a single shadow
218
+
219
+ ```css
220
+ @theme {
221
+ --shadow-raised: 0 1px 2px oklch(0 0 0 / 0.06), 0 2px 4px oklch(0 0 0 / 0.04);
222
+ }
223
+ ```
224
+
225
+ 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.
226
+
227
+ ## Light + dark in lockstep
228
+
229
+ Every override should consider both modes. Pattern:
230
+
231
+ ```css
232
+ @theme {
233
+ --color-accent-9: oklch(0.54 0.22 195);
234
+ --color-accent-fg: oklch(0.99 0 0);
235
+ }
236
+
237
+ /* Dark mode override */
238
+ .dark {
239
+ --color-accent-9: oklch(0.62 0.21 195);
240
+ --color-accent-fg: oklch(0.10 0 0);
241
+ }
242
+ ```
243
+
244
+ `.dark` is a regular class selector — its specificity is higher than `:root`/`@theme` body, so dark-mode overrides win when the class is active.
245
+
246
+ ## Forced colors (Windows high-contrast)
247
+
248
+ 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.
249
+
250
+ If you need a custom forced-colors mapping, override inside `@media (forced-colors: active)`:
251
+
252
+ ```css
253
+ @media (forced-colors: active) {
254
+ :root {
255
+ --color-accent-9: Highlight;
256
+ --color-accent-fg: HighlightText;
257
+ }
258
+ }
259
+ ```
260
+
261
+ ## Per-route theming
262
+
263
+ Apply a class on a wrapper element to scope token overrides:
264
+
265
+ ```css
266
+ .theme-karm {
267
+ --color-accent-9: oklch(0.55 0.22 195);
268
+ }
269
+ .theme-karm.dark,
270
+ .dark .theme-karm {
271
+ --color-accent-9: oklch(0.62 0.21 195);
272
+ }
273
+ ```
274
+
275
+ Then:
276
+
277
+ ```tsx
278
+ <div className="theme-karm">
279
+ <Button>Karm-themed</Button>
280
+ </div>
281
+ ```
282
+
283
+ ## What you cannot override via CSS variables
284
+
285
+ - The component DOM structure (use the `asChild` pattern or wrap the component to insert)
286
+ - The vendored Radix primitives' behavior
287
+ - Animation keyframes (override the `--animate-*` references via `@theme` — but the keyframe definitions themselves are package-private)
288
+
289
+ For deeper changes, fork the source or use the `className` prop with arbitrary Tailwind utilities to layer styling on top.
290
+
291
+ ## Verifying an override
292
+
293
+ 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.
294
+
295
+ If the override isn't winning, check:
296
+
297
+ 1. The `@theme` override comes AFTER `@import "@devalok/shilp-sutra/css";` in source order
298
+ 2. There's no `!important` in the package overriding you (there isn't — file an issue if you find one)
299
+ 3. The selector specificity matches the target (`.dark` class is on a parent of the inspected element, etc.)
package/skill/references/server-components.md ADDED
@@ -0,0 +1,211 @@
1
+ <!-- Source: packages/core/docs/recipes/server-components.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
2
+
3
+ # Server vs Client Components
4
+
5
+ Reference for using `@devalok/shilp-sutra` correctly inside React Server Components (Next.js App Router, TanStack Start, Remix v3+, Astro, future RSC frameworks).
6
+
7
+ ## TL;DR
8
+
9
+ - **Always use per-component imports** (`@devalok/shilp-sutra/ui/button`, NOT `@devalok/shilp-sutra/ui`) — barrels drag in client-only siblings and trip the RSC barrel-import error.
10
+ - **Importing a client component into a Server Component is fine.** The client component renders as a client island at that point. The Server Component shell stays server-rendered.
11
+ - **What actually breaks RSC**, in order of frequency: (a) calling a client hook in a server file; (b) passing functions or class instances as props from server → client; (c) reading `window`/`document` in a server module's top-level body.
12
+ - The matrix below tells you which components have NO `"use client"` (so they SSR without hydration cost) vs. which become client islands (still importable, just hydrate).
13
+
14
+ ## RSC-safety matrix
15
+
16
+ The list is generated from the `// @server-safe` source annotation. Components without the annotation get `"use client"` injected at build time and ship as client islands.
17
+
18
+ ### `@devalok/shilp-sutra/ui`
19
+
20
+ | Server-safe (renders without hydration) | Everything else |
21
+ |---|---|
22
+ | `Text` | All other UI primitives become client islands when rendered |
23
+ | `Stack` | |
24
+ | `Container` | |
25
+ | `Skeleton` | |
26
+ | `Table` (and child components: `TableHeader`, `TableRow`, `TableCell`) | |
27
+ | `Code` | |
28
+ | `VisuallyHidden` | |
29
+
30
+ ```tsx
31
+ // ✅ Server Component — Text/Stack/Container/etc. SSR with zero hydration cost
32
+ import { Text } from "@devalok/shilp-sutra/ui/text";
33
+ import { Stack } from "@devalok/shilp-sutra/ui/stack";
34
+
35
+ export default function ServerPage() {
36
+ return (
37
+ <Stack className="p-ds-08">
38
+ <Text variant="heading-2xl">Server-rendered</Text>
39
+ </Stack>
40
+ );
41
+ }
42
+ ```
43
+
44
+ ```tsx
45
+ // ✅ Also fine — Button is a client component, but importing one into a Server
46
+ // Component just creates a client island at that boundary. No wrapper needed.
47
+ import { Button } from "@devalok/shilp-sutra/ui/button";
48
+
49
+ export default function ServerPage() {
50
+ return <Button>Click</Button>;
51
+ }
52
+ ```
53
+
54
+ ```tsx
55
+ // ❌ NOT fine — passing a function as a prop from server → client.
56
+ // Functions are not serializable across the RSC boundary.
57
+ import { Button } from "@devalok/shilp-sutra/ui/button";
58
+
59
+ export default function ServerPage() {
60
+ return <Button onClick={() => console.log("hi")}>Click</Button>;
61
+ // ^^^^^^^ — define handler inside a "use client" wrapper instead
62
+ }
63
+ ```
64
+
65
+ When you need an event handler, define it inside a client component:
66
+
67
+ ```tsx
68
+ // app/components/MyButton.tsx
69
+ "use client";
70
+ import { Button } from "@devalok/shilp-sutra/ui/button";
71
+
72
+ export function MyButton() {
73
+ return <Button onClick={() => console.log("hi")}>Click</Button>;
74
+ }
75
+ ```
76
+
77
+ ### `@devalok/shilp-sutra/composed`
78
+
79
+ | Server-safe (renders without hydration) | Everything else |
80
+ |---|---|
81
+ | `ContentCard` | All other composed components become client islands when rendered |
82
+ | `PageHeader` | |
83
+ | `LoadingSkeleton` | |
84
+ | `PageSkeletons` | |
85
+
86
+ ### `@devalok/shilp-sutra/shell`
87
+
88
+ All shell components are client islands. They manage state (open/close, active route, viewport detection) and require hydration.
89
+
90
+ ### `@devalok/shilp-sutra/ai`
91
+
92
+ All AI components are client islands. They manage conversation state, streaming responses, and command bar focus.
93
+
94
+ ### `@devalok/shilp-sutra/hooks`
95
+
96
+ All hooks (`useColorMode`, `useIsMobile`, etc.) are client-only by definition (React hooks).
97
+
98
+ ### `@devalok/shilp-sutra/utils`, `/ui/lib/utils`, `/ui/lib/motion`, `/ui/lib/date-utils`
99
+
100
+ Pure functions. Server-safe.
101
+
102
+ ## Why barrel imports break RSC
103
+
104
+ The barrel re-exports every component in a layer. When a Server Component imports anything from `@devalok/shilp-sutra/ui`, the bundler walks the barrel and pulls in code from sibling components. If any sibling has `"use client"`, the bundler complains:
105
+
106
+ ```
107
+ You're importing a component that needs useState.
108
+ It only works in a Client Component.
109
+ ```
110
+
111
+ Per-component imports avoid this — the bundler only walks the imported file's module graph.
112
+
113
+ This is also why **per-component imports tree-shake better** even in non-RSC frameworks. They're the recommended pattern everywhere.
114
+
115
+ ## "use client" propagation
116
+
117
+ A component is server-safe only if:
118
+
119
+ 1. It has no `"use client"` directive at the top of its source file
120
+ 2. None of its imports have `"use client"` either (transitively)
121
+
122
+ We mark sources `// @server-safe` and a build-time check verifies the import graph stays clean. The `"use client"` directive is injected automatically during the build for components without that annotation.
123
+
124
+ If you fork the source and remove `"use client"` from a component that uses `useState`, the build will still inject it back unless you also remove the React-hook usage. Don't fight the system — wrap in a client component instead.
125
+
126
+ ## Streaming and Suspense
127
+
128
+ All shilp-sutra components SSR cleanly. They have no client-only side effects at module top-level — no `window.*`, `document.*`, or `localStorage.*` access during render. Side effects happen in `useEffect`, which runs after hydration.
129
+
130
+ Use `<Suspense>` boundaries normally:
131
+
132
+ ```tsx
133
+ import { Suspense } from "react";
134
+ import { LoadingSkeleton } from "@devalok/shilp-sutra/composed/loading-skeleton";
135
+
136
+ export default function Page() {
137
+ return (
138
+ <Suspense fallback={<LoadingSkeleton variant="page" />}>
139
+ <ClientHeavyComponent />
140
+ </Suspense>
141
+ );
142
+ }
143
+ ```
144
+
145
+ Both `<Suspense>` and `<LoadingSkeleton>` are server-safe.
146
+
147
+ ## Common RSC mistakes
148
+
149
+ ### Mistake 1: Calling a client hook in a Server Component
150
+
151
+ ```tsx
152
+ // ❌ — useColorMode is a React hook; hooks only run in client components
153
+ import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
154
+
155
+ export default function ServerPage() {
156
+ const { mode } = useColorMode(); // breaks
157
+ return <div>{mode}</div>;
158
+ }
159
+ ```
160
+
161
+ Fix: use the hook inside a `"use client"` component.
162
+
163
+ ### Mistake 2: Reading `window.*` in a server module's top level
164
+
165
+ ```tsx
166
+ // ❌ — window is undefined on the server
167
+ const w = window.innerWidth;
168
+
169
+ export default function ServerPage() {
170
+ return <p>{w}px</p>;
171
+ }
172
+ ```
173
+
174
+ Fix: read inside a `useEffect` of a client component, or use `useIsMobile` in a client wrapper.
175
+
176
+ ### Mistake 3: Passing functions as props from a Server Component to a client island
177
+
178
+ ```tsx
179
+ // ❌ — function props are not serializable across the RSC boundary
180
+ import { Button } from "@devalok/shilp-sutra/ui/button";
181
+
182
+ export default function ServerPage() {
183
+ return <Button onClick={() => console.log("hi")}>Click</Button>;
184
+ }
185
+ ```
186
+
187
+ Fix: define the handler inside the client island, or use a Server Action and pass the action reference (Server Actions ARE serializable).
188
+
189
+ ### Mistake 4: Barrel-importing into a Server Component
190
+
191
+ ```tsx
192
+ // ❌ — pulls every UI primitive's module graph into the server file,
193
+ // and any sibling with "use client" trips the bundler error.
194
+ import { Text } from "@devalok/shilp-sutra/ui";
195
+ ```
196
+
197
+ Fix: per-component import.
198
+
199
+ ```tsx
200
+ // ✅
201
+ import { Text } from "@devalok/shilp-sutra/ui/text";
202
+ ```
203
+
204
+ ## When in doubt
205
+
206
+ If you're unsure whether a component is server-safe, look at the source:
207
+
208
+ - `packages/core/src/ui/<name>.tsx` — top of file. The `// @server-safe` annotation marks components that ship without `"use client"`.
209
+ - `packages/core/src/composed/<name>/index.tsx` — same.
210
+
211
+ The matrix in this file is the authoritative public list. If you find a discrepancy, file an issue.
package/skill/references/setup-astro.md ADDED
@@ -0,0 +1,180 @@
1
+ <!-- Source: packages/core/docs/recipes/install-astro.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
2
+
3
+ # Install: Astro
4
+
5
+ > Setup recipe for adding `@devalok/shilp-sutra` to an Astro project with React islands.
6
+
7
+ ## 1. Detect
8
+
9
+ You are in this recipe if:
10
+
11
+ - `astro.config.{ts,mjs,js}` exists at the project root
12
+ - `package.json` lists `"astro"`
13
+ - React is integrated via `@astrojs/react`
14
+
15
+ If `@astrojs/react` is not installed, install it first:
16
+
17
+ ```bash
18
+ pnpm astro add react
19
+ ```
20
+
21
+ ## 2. Install dependencies
22
+
23
+ ```bash
24
+ pnpm add @devalok/shilp-sutra framer-motion
25
+ pnpm add -D tailwindcss@^4 @tailwindcss/vite
26
+ ```
27
+
28
+ Add only if rendering `<Toaster />`:
29
+
30
+ ```bash
31
+ pnpm add sonner
32
+ ```
33
+
34
+ ## 3. Wire Tailwind 4 in `astro.config`
35
+
36
+ Astro has its own `@astrojs/tailwind` integration, but for Tailwind 4 use the Vite plugin directly (Astro 4.5+ supports this):
37
+
38
+ ```ts
39
+ // astro.config.ts
40
+ import { defineConfig } from "astro/config";
41
+ import react from "@astrojs/react";
42
+ import tailwindcss from "@tailwindcss/vite";
43
+
44
+ export default defineConfig({
45
+ integrations: [react()],
46
+ vite: {
47
+ plugins: [tailwindcss()],
48
+ },
49
+ });
50
+ ```
51
+
52
+ Do **not** also enable `@astrojs/tailwind` — that integration is Tailwind 3 only and will conflict.
53
+
54
+ ## 4. Wire tokens
55
+
56
+ Create `src/styles/globals.css`:
57
+
58
+ ```css
59
+ @import "tailwindcss";
60
+ @import "@devalok/shilp-sutra/css";
61
+ ```
62
+
63
+ Import it from a layout component (e.g., `src/layouts/BaseLayout.astro`):
64
+
65
+ ```astro
66
+ ---
67
+ import "../styles/globals.css";
68
+ const { title = "App" } = Astro.props;
69
+ ---
70
+ <!doctype html>
71
+ <html lang="en" class="">
72
+ <head>
73
+ <meta charset="utf-8" />
74
+ <meta name="viewport" content="width=device-width" />
75
+ <title>{title}</title>
76
+ </head>
77
+ <body>
78
+ <slot />
79
+ </body>
80
+ </html>
81
+ ```
82
+
83
+ ## 5. Theme toggle
84
+
85
+ Add the bootstrap script to `<head>` of `BaseLayout.astro` (before stylesheet imports):
86
+
87
+ ```astro
88
+ ---
89
+ import "../styles/globals.css";
90
+ ---
91
+ <!doctype html>
92
+ <html lang="en">
93
+ <head>
94
+ <script is:inline>
95
+ try {
96
+ var stored = localStorage.getItem("theme");
97
+ var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
98
+ if (stored === "dark" || (!stored && prefersDark))
99
+ document.documentElement.classList.add("dark");
100
+ } catch (e) {}
101
+ </script>
102
+ <!-- ... -->
103
+ </head>
104
+ <body><slot /></body>
105
+ </html>
106
+ ```
107
+
108
+ `is:inline` keeps it out of bundling, so it runs before any other JS.
109
+
110
+ 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).
111
+
112
+ ## 6. Use components in islands
113
+
114
+ Shilp Sutra components are **client-only** (they use React hooks). Mount them in islands with a `client:*` directive:
115
+
116
+ ```astro
117
+ ---
118
+ import { Button } from "@devalok/shilp-sutra/ui/button";
119
+ ---
120
+ <Button client:load>Hello</Button>
121
+ ```
122
+
123
+ Static / non-interactive primitives (Text, Stack, Container, Code, VisuallyHidden) work without `client:*` because they render to static markup. Per-component imports are still required.
124
+
125
+ ## 7. Toaster (optional)
126
+
127
+ Mount once in a top-level island. The simplest approach is a small React wrapper component:
128
+
129
+ ```tsx
130
+ // src/components/AppToaster.tsx
131
+ "use client";
132
+ import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
133
+ export default function AppToaster() {
134
+ return <Toaster />;
135
+ }
136
+ ```
137
+
138
+ ```astro
139
+ ---
140
+ import AppToaster from "../components/AppToaster";
141
+ ---
142
+ <AppToaster client:load />
143
+ ```
144
+
145
+ ## 8. Verify
146
+
147
+ Create `src/pages/index.astro`:
148
+
149
+ ```astro
150
+ ---
151
+ import BaseLayout from "../layouts/BaseLayout.astro";
152
+ import { Button } from "@devalok/shilp-sutra/ui/button";
153
+ import { Stack } from "@devalok/shilp-sutra/ui/stack";
154
+ import { Text } from "@devalok/shilp-sutra/ui/text";
155
+ ---
156
+ <BaseLayout title="Home">
157
+ <Stack className="p-ds-08" gap="ds-04">
158
+ <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
159
+ <Stack direction="row" gap="ds-03">
160
+ <Button client:load>Primary</Button>
161
+ <Button client:load variant="soft">Soft</Button>
162
+ </Stack>
163
+ </Stack>
164
+ </BaseLayout>
165
+ ```
166
+
167
+ Run `pnpm dev` and open the URL.
168
+
169
+ ## 9. Astro-specific gotchas
170
+
171
+ - **No `transpilePackages` equivalent — and you do not need one.** Astro's Vite uses native ESM and resolves `@devalok/shilp-sutra` from `node_modules` directly.
172
+ - **Component must be inside a `client:*` island to be interactive.** A button without `client:load` will render but not respond to clicks.
173
+ - **Server-side islands (`server:defer`)** — fine, but RSC import rules apply (per-component imports only). See [server-components.md](./server-components.md).
174
+ - **`@astrojs/tailwind` and `@tailwindcss/vite` conflict.** Pick one. For Tailwind 4 use the Vite plugin.
175
+
176
+ ## 10. What NOT to do
177
+
178
+ - ❌ Use `@astrojs/tailwind` (Tailwind 3 only).
179
+ - ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
180
+ - ❌ Import shilp-sutra components into a `.astro` file expecting interactivity without `client:*`.