@devalok/shilp-sutra 0.56.0 → 0.57.0

package/docs/components/ui/data-table.md

@@ -5,20 +5,23 @@
 - Category: ui
 
 ## Props
-    columns: ColumnDef<TData>[] (TanStack column definitions)
+    columns: ColumnDef<TData, TValue>[] (TanStack column definitions)
     data: TData[]
+    className: string — class name for the wrapper div
     sortable: boolean — enable column sorting
-    onSort: (key: string, dir: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)
+    onSort: (key: string, direction: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)
     filterable: boolean — enable per-column filters
+    filterableColumns: string[] — restrict filter inputs to these column IDs (only with filterable; omit for all filterable columns)
     globalFilter: boolean — enable global search
     paginated: boolean — enable client-side pagination
     pagination: { page: number, pageSize: number, total: number, onPageChange: (page: number) => void } — server-side pagination (1-based page)
     pageSize: number (default 10)
+    pageSizeOptions: number[] — page-size selector options (default [10, 20, 50, 100])
     selectable: boolean — enable row selection with checkboxes
     selectedIds: Set<string> — controlled selection state
     selectableFilter: (row: TData) => boolean — disable selection on certain rows
     getRowId: (row: TData) => string — custom row ID accessor
-    onSelectionChange: (selectedRows: TData[]) => void
+    onSelectionChange: (selectedRows: TData[], selectedIds: Set<string>) => void — does NOT fire on mount
     expandable: boolean — enable row expansion
     renderExpanded: (row: TData) => ReactNode — expanded row content
     singleExpand: boolean — only one row expanded at a time
@@ -27,15 +30,23 @@
     noResultsText: string (default "No results.")
     stickyHeader: boolean — sticky table header
     onRowClick: (row: TData) => void — row click handler (excludes interactive element clicks)
-    bulkActions: BulkAction<TData>[] — floating action bar on selection — { label, onClick, color?: 'default'|'error', disabled? }
+    rowClassName: (row: TData) => string | undefined — conditional per-row class (the <tr> in table mode, the Card in card mode)
+    bulkActions: BulkAction<TData>[] — floating action bar on selection — { label, onClick, icon?: IconInput, color?: 'accent'|'error', disabled? }
+    bulkActionsPosition: 'bottom' | 'top' | 'inline' — where the bulk-actions bar renders (default 'bottom')
     toolbar: boolean — show DataTableToolbar (column visibility, density, CSV export)
+    enableExport: boolean — show the toolbar's Export CSV button (default true)
+    onExport: (visibleRows: TData[]) => void — replace the built-in CSV export
     editable: boolean — enable double-click cell editing
+    onCellEdit: (rowIndex: number, columnId: string, value: unknown) => void — fired on cell edit commit
     virtualRows: boolean — virtualize rows for large datasets
+    virtualRowHeight: number — ESTIMATED row height in px (default 48); real heights are measured after mount
+    maxHeight: number — max height of the virtual scroll container in px (default 600)
+    mobileView: 'card' | 'table' — stacked cards below the sm breakpoint (default 'table')
     columnPinning: { left?: string[], right?: string[] }
     density: 'compact' | 'standard' | 'comfortable'
 
 ## Defaults
-    pageSize=10, noResultsText="No results."
+    pageSize=10, noResultsText="No results.", enableExport=true, mobileView='table', virtualRowHeight=48, maxHeight=600, density='standard'
 
 ## Example
 ```jsx
@@ -75,7 +86,11 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 **Row click model:**
 - `onRowClick` fires on row-level click BUT excludes clicks on checkboxes, buttons, links, and inputs automatically. No manual `stopPropagation` needed for standard interactive elements.
 
-**Virtualization:** `virtualRows={true}` enables row virtualization via `@tanstack/react-virtual`. Turn it on for 1000+ row datasets; the scroll container must have a bounded height.
+**Virtualization:** `virtualRows={true}` enables row virtualization via `@tanstack/react-virtual`. Turn it on for 1000+ row datasets; the scroll container must have a bounded height. Rows stay in normal table flow (each windowed row is its own `<tbody>` measured by the virtualizer, with spacer row groups reserving the un-rendered remainder), so column widths keep tracking `<thead>` and `virtualRowHeight` is only the pre-measurement estimate.
+
+**Virtualization + expansion:** `virtualRows` and `expandable` compose. Because each row group is measured, an expanded detail panel of any height contributes to the total scroll size and pushes the rows below it down. The reveal is instant in virtual mode (no height animation) — an animating height would fire a resize on every frame.
+
+**Toolbar export:** the Export button renders whenever `toolbar` is on. The built-in CSV export walks `getFilteredRowModel()`, which under server-side `pagination` is only the current page — pass `onExport` to fetch the full set yourself, or `enableExport={false}` to drop the button.
 
 **Density integration:** density is forwarded to `Table`'s `density` prop, which sets `--table-py` (compact 4 / standard 8 / comfortable 12px → rows ≈ 29 / 37 / 45px; header tracks it). DataTableToolbar's density switcher updates this at runtime; the prop sets the initial state only.
 
@@ -88,13 +103,32 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 - onRowClick does NOT fire when clicking checkboxes, buttons, links, or inputs
 - Use density="compact" for Karm-style h-9 rows
 - `virtualRows={true}` requires a bounded scroll container — unbounded height silently disables virtualization
+- `onSelectionChange` does NOT fire on mount, and does NOT fire when selection is synced from the `selectedIds` prop — only on genuine selection changes
+- `filterableColumns` is ignored unless `filterable` is also set
+- `rowClassName` returns are passed through `cn()` verbatim — a class that does not exist in the token set silently does nothing (use the real scale steps, e.g. `bg-error-3`, not invented names like `bg-error-subtle`)
 
 ## Changes
+### Unreleased
+- **Added** `bulkActions[].icon?: IconInput` — icon rendered before the label in a bulk-action button.
+- **Added** `bulkActionsPosition?: 'bottom' | 'top' | 'inline'` — where the bulk-actions bar renders (default `'bottom'`, matching prior behavior).
+
+### v0.57.0
+- **Fixed** `onSelectionChange` no longer fires on mount with `[]` — first-render guard added. Root cause of the cascade reported in #213.
+- **Fixed** `virtualRows + expandable` was a silent no-op — the expanded row was only rendered on the non-virtual path. Virtual rows now render one measured `<tbody>` per windowed row (with spacer row groups for the remainder) so the expanded panel renders, contributes its real height to `getTotalSize()`, and cannot overlap the row below.
+- **Changed** Virtual rows are no longer absolutely positioned with a forced `virtualRowHeight`; they sit in normal table flow at their measured height, so column widths track `<thead>`. `virtualRowHeight` is now the pre-measurement ESTIMATE.
+- **Fixed** `enableExport` was stranded on `DataTableToolbar` and never wired through `DataTableProps`. Now exposed with an `onExport` override. Default is unchanged (`true`) — the Export button still renders whenever `toolbar` is on.
+- **Fixed** `filterable + mobileView="card"` rendered no filter inputs — they now render above the card list in `DataTableCards` (card mode renders no `<thead>` for them to live in).
+- **Added** `onSelectionChange` receives `selectedIds: Set<string>` as second argument — complement of the `selectedIds` prop.
+- **Added** `filterableColumns?: string[]` — restrict filter inputs to specific column IDs.
+- **Added** `rowClassName?: (row: TData) => string | undefined` — conditional row classes in table and card layouts.
+- **Added** `enableExport?: boolean` — hide the toolbar's Export CSV button from `DataTableProps`.
+- **Added** `onExport?: (visibleRows: TData[]) => void` — override built-in CSV with a custom export handler.
+
 ### v0.45.0
 - **Fixed** Expander a11y per the expando-row spec: `aria-expanded` on the toggle button, visually-hidden "Expand rows" column header; chevron rotation uses `duration-fast-02 ease-productive-standard`.
 - **Added** Expanded-row content animates open/closed (height + opacity via framer, `springs.smooth`), self-guarded with `useReducedMotion` — instant swap for reduced-motion users. Virtualized tables keep the instant reveal (a height animation would fight the virtualizer's measurements).
 - **Changed** Density now drives Table's `--table-py` variable (rows ≈ 29 / 37 / 45px; was 29 / 53 / 85). Per-cell `cellPadding` threading removed from context.
-- **Fixed** Hover/selected states visible on cards: row/sort-button/expander hover use `surface-raised-hover` (was the invisible `surface-raised`); expanded row is a `surface-base` recess; sticky header bg is `surface-raised`; empty state uses `py-ds-07` (was raw `h-24`).
+- **Fixed** Hover/selected states visible on cards: row/sort-button/expander hover use `surface-panel-hover` (was the invisible `surface-panel`); expanded row is a `surface-base` recess; sticky header bg is `surface-panel`; empty state uses `py-ds-07` (was raw `h-24`).
 - **Changed** Mobile card view composes `<Card size="sm" variant="outline">` (was a hand-rolled 12px bordered box).
 
 ### v0.29.0

package/docs/components/ui/dot.md

@@ -49,7 +49,7 @@ sized, optionally pulsing, filled or ring.
 - **`pulse` = "live".** Off by default (static status). Turn it on for active/attention states (recording, live, connecting) — a pulsing dot reads as "happening now", so leave it off for settled statuses.
 - **Powers the higher-level pieces.** `StatusBadge` composes `<Badge>` + `<Dot>`; use `Dot` directly anywhere you need a coloured indicator without a pill.
 - **Three treatments:** `filled` (active), `ring` (hollow outline), `off` (faint same-tone fill + light border — present but inactive/disabled).
-- **`withBorder`** adds a contrast ring (`ring-2 ring-surface-raised`) so the dot reads on avatars, images, or coloured fills — the pattern Avatar's status dot uses.
+- **`withBorder`** adds a contrast ring (`ring-2 ring-surface-panel`) so the dot reads on avatars, images, or coloured fills — the pattern Avatar's status dot uses.
 - **`pulseSpeed`** (slow/normal/fast) tunes the pulse tempo — fast for urgent (recording), slow for ambient (syncing).
 
 ## Gotchas

package/docs/components/ui/progress.md

@@ -66,6 +66,7 @@ common cases, or the compound parts (`Progress.Root` / `Track` / `Indicator` /
 - Omit `value` (or pass `null`) for indeterminate.
 - Pass an explicit `color` to override `autoColor`.
 - Compound `Progress.Track` needs a name — an `aria-label`, or a `Progress.Label` whose `id` the Track's `aria-labelledby` points to. A Track with neither is an unnamed progressbar (axe will flag it).
+- **`<Progress value={72} />` with no name warns in DEV.** `aria-valuenow` already carries the number, so an unnamed bar announces as "progressbar, 72%" — the reader learns the value but not *what* is progressing. Pass `label` (renders visible text and wires `aria-labelledby`) or `aria-label` when the bar must stay visually unlabelled. The component deliberately does **not** invent a default like "Progress: 72%": that would silence the audit while leaving the announcement equally uninformative, and only you know what the bar measures. Warns once per session, not per render.
 - `Progress.Indicator` / `Segment` / `Value` throw if rendered outside `Progress.Root`.
 
 ## Changes

package/docs/components/ui/surface.md

@@ -18,8 +18,8 @@ The low-level elevated container primitive. Owns background + shadow + radius +
     Surface: elevation="raised", padding="none", radius="surface", bordered=false
 
 ## Elevation
-    flat      — bg-surface-raised, no shadow (pair with `bordered` for an on-page tile)
-    raised    — bg-surface-raised + shadow-raised (card level)
+    flat      — bg-surface-panel, no shadow (pair with `bordered` for an on-page tile)
+    raised    — bg-surface-panel + shadow-raised (card level)
     floating  — bg-surface-overlay + shadow-floating (toasts, floating toolbars)
     overlay   — bg-surface-overlay + shadow-overlay (popovers, menus, dialogs)
 
@@ -48,7 +48,7 @@ The low-level elevated container primitive. Owns background + shadow + radius +
 
 ## Gotchas
 - **Edge OR elevation, never both.** Combining `bordered` with a shadowed elevation (raised/floating/overlay) is the double-edge anti-pattern and dev-warns. Use `elevation="flat"` with `bordered`, or drop `bordered` and let the shadow be the edge.
-- `flat` still uses `bg-surface-raised` (a card without a shadow), not the page background — it is a surface, not a hole.
+- `flat` still uses `bg-surface-panel` (a card without a shadow), not the page background — it is a surface, not a hole.
 
 ## Changes
 ### Unreleased

package/docs/components/ui/table.md

@@ -106,12 +106,12 @@ See the `RichCells` story for all of these live.
 - **Added** `TableRowLink` (ui/table-row-link) — real-anchor whole-row navigation with pseudo-element stretch (Safari-safe: anchored to the cell, clipped by the table's `overflow-x-clip`), row-level focus ring, `stretch={false}` title-only mode.
 - **Added** `TableRowActions` — hover/focus-revealed action cluster (opacity reveal, permanently tabbable, `:focus-within` + touch fallbacks, `persist` mode).
 - **Added** `numeric` prop on TableCell/TableHead — right-align + tabular figures.
-- **Fixed** TableFooter background was `color-mix(surface-raised 50%)` — invisible on cards (same mis-mapped shadcn `muted/50` family as the row hover). Now a `surface-base` band with a top hairline.
+- **Fixed** TableFooter background was `color-mix(surface-panel 50%)` — invisible on cards (same mis-mapped shadcn `muted/50` family as the row hover). Now a `surface-base` band with a top hairline.
 - **Fixed** Selected+hover tie: selected rows get an explicit `hover:bg-accent-4` step (hover and selected previously tied on specificity).
 - **Added** Cell recipes section (user cell, tag overflow, money, empty-dash) + density→avatar mapping; `RichCells` / `SelectedRows` stories.
 - **Added** `density` prop (`compact | standard | comfortable`) via `--table-py`; header height tracks density instead of a fixed 40px
 - **Added** `striped` prop — opt-in zebra
-- **Changed** Rows regain their hairline separator (`border-b border-surface-border-subtle` — lost in the original port) and hover becomes visible on cards (`hover:bg-surface-raised-hover`, was the invisible `surface-raised`)
+- **Changed** Rows regain their hairline separator (`border-b border-surface-border-subtle` — lost in the original port) and hover becomes visible on cards (`hover:bg-surface-panel-hover`, was the invisible `surface-panel`)
 - **Changed** Cells: `px-ds-04` interior, first/last cells read `--table-edge` (= `--card-spacing` inside a Card); header drops to `text-ds-sm` muted
 - **Changed** Default vertical rhythm tightens: standard rows ~53px → ~37px
 

package/docs/recipes/install-astro.md

@@ -39,6 +39,7 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |

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

@@ -52,6 +52,7 @@ Some components depend on third-party libraries that ship as optional peers. **I
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |

package/docs/recipes/install-remix.md

@@ -35,6 +35,7 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |

package/docs/recipes/install-tanstack-start.md

@@ -44,6 +44,7 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |

package/docs/recipes/install-vite.md

@@ -50,6 +50,7 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |

package/llms.txt

@@ -1,6 +1,6 @@
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.56.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.57.0.
 > Built on the same primitives as shadcn/ui but with DIFFERENT prop APIs — never guess from shadcn knowledge; verify every prop.
 > This file is a ROUTER: it tells you what exists and where to get details. Do not look for prop tables here — fetch them per component (MCP tool or per-component doc file below).
 
@@ -152,6 +152,7 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 
 ### shell
 - [app-command-palette](docs/components/shell/app-command-palette.md)
+- [app-shell](docs/components/shell/app-shell.md)
 - [bottom-navbar](docs/components/shell/bottom-navbar.md)
 - [command-registry](docs/components/shell/command-registry.md): Exports: CommandRegistryProvider, useCommandRegistry
 - [link-context](docs/components/shell/link-context.md): Exports: LinkProvider, useLink

package/make-kit/Guidelines.md

@@ -22,10 +22,10 @@
 These are not preferences. Generated code that violates them is wrong.
 
 1. **Use design system components, not raw HTML.** `<Button>` not `<button>`. `<Input>` not `<input>`. `<Text>` not `<span>`/`<p>` (when typographic semantics matter). `<Stack>` not bare flex divs.
-2. **Use semantic tokens, never hex / rgb / hsl.** `bg-surface-raised` not `bg-white`. `text-fg` not `text-zinc-900`. `bg-accent-9` not `bg-pink-500`.
+2. **Use semantic tokens, never hex / rgb / hsl.** `bg-surface-panel` not `bg-white`. `text-fg` not `text-zinc-900`. `bg-accent-9` not `bg-pink-500`.
 3. **Spacing uses `ds-*` cadence.** `p-ds-05`, `gap-ds-03`. Never `p-4` / `p-6`. Default cadence is `ds-03 / ds-05 / ds-07` (related items / grouped sections / page sections). Do not reach for every adjacent token (`ds-04`, `ds-06`) — three tiers, not five.
 4. **Prefer `variant="soft"` over `variant="outline"` for non-primary actions.** Soft (tinted bg, no visible border) reads better in data-dense UIs. Outline only when on a colored bg or paired with a primary for explicit hierarchy.
-5. **Surface layering is strict.** Page = `surface-base`. Cards/panels/widgets = `surface-raised`. Dialogs/popovers/dropdowns/inputs = `surface-overlay`. Shell chrome (sidebar, topbar) = `surface-sunken`. Tooltips = `surface-inverted`. If you're unsure, read `foundations/surfaces.md`.
+5. **Surface layering is strict.** Page = `surface-base`. Cards/panels/widgets = `surface-panel`. Dialogs/popovers/dropdowns/inputs = `surface-overlay`. Shell chrome (sidebar, topbar) = `surface-sunken`. Tooltips = `surface-inverted`. If you're unsure, read `foundations/surfaces.md`.
 6. **Never combine `border-*` + `shadow-*` tokens.** Shadow tokens already include a 1px ring layer. Adding an explicit border creates a 2-px edge.
 7. **Icons use `<Icon icon={...} />` from `@tabler/icons-react`.** Do not import lucide, heroicons, mui-icons. The icon system auto-sizes via `IconProvider` context.
 8. **Toasts mount once at app root.** `<Toaster />` (singleton). All triggering is imperative: `toast.success("...")`, `toast.error("...")`.

package/make-kit/components/button.md

@@ -19,7 +19,7 @@ import { Button } from '@devalok/shilp-sutra/ui/button'
 |---|---|
 | `solid` (default) | Primary CTA. One per region. Heavy visual weight. |
 | `soft` | Secondary action. **Preferred default for any non-primary action.** Tinted bg, colored text, no visible border — warmer than outline, brand-consistent. |
-| `outline` | Secondary action on a colored / `surface-raised` bg where soft's tint disappears. In toolbars / icon-dense rows. Paired adjacent to a primary that needs explicit hierarchy. |
+| `outline` | Secondary action on a colored / `surface-panel` bg where soft's tint disappears. In toolbars / icon-dense rows. Paired adjacent to a primary that needs explicit hierarchy. |
 | `ghost` | Tertiary / dismissive — close, cancel, skip. Minimal weight. |
 | `link` | Inline action that should read as a link but behave as a button. Use sparingly. |
 

package/make-kit/components/card.md

@@ -20,18 +20,18 @@ import {
 
 - Any rectangular region that reads as a discrete unit on the page: dashboards widgets, list items, marketing feature blocks.
 - Header / actions / footer are built in as slots (`CardHeader`, `CardAction`, `CardFooter`) — don't reach for a wrapper. (`<ContentCard>` is deprecated; use Card slots.)
-- Need just a tinted region with no card affordance? Use a `<div className="bg-surface-raised">` (rare; usually Card is right).
+- Need just a tinted region with no card affordance? Use a `<div className="bg-surface-panel">` (rare; usually Card is right).
 
-Card renders on `surface-raised`. The `default` variant is tonal — a surface-tone shift plus a whisper hairline (`border-card`), no shadow. **Never** override its background or border.
+Card renders on `surface-panel`. The `default` variant is tonal — a surface-tone shift plus a whisper hairline (`border-card`), no shadow. **Never** override its background or border.
 
 ## Variants
 
 | Variant | Use |
 |---|---|
-| `default` (default) | `surface-raised` + tonal `border-card` hairline, no shadow. Standard card — depth from tone, not a drop shadow. |
+| `default` (default) | `surface-panel` + tonal `border-card` hairline, no shadow. Standard card — depth from tone, not a drop shadow. |
 | `elevated` | `shadow-raised-hover`, no border. Use when a card must visibly pop (hero, dragged tile, spotlight panel). |
-| `outline` | `surface-raised` + strong border-only (no shadow). Dense lists where stacked shadowed cards would feel too lifted. |
-| `flat` | `surface-raised` + no shadow, no border. For cards inside an already-elevated container. |
+| `outline` | `surface-panel` + strong border-only (no shadow). Dense lists where stacked shadowed cards would feel too lifted. |
+| `flat` | `surface-panel` + no shadow, no border. For cards inside an already-elevated container. |
 
 ## Colors
 
@@ -186,7 +186,7 @@ wrap the text column in `<CardSection>`, which re-establishes py + gap from the
 
 ## Rules
 
-- **Never** `bg-surface-base` on a Card — cards sit on `surface-raised`. The pre-publish audit rejects this.
+- **Never** `bg-surface-base` on a Card — cards sit on `surface-panel`. The pre-publish audit rejects this.
 - **Never** combine `border-*` + `shadow-*` on a Card. Pick one (Card already does — don't override).
 - **Use `interactive` + `onClick` + `aria-label`** for clickable cards. Don't wrap a Card in a `<button>` — broken nesting.
 - **`size` on Card** drives all spacing via `--card-spacing`. Never set `p-*` on Card or a slot — override the variable if a one-off is truly needed.

package/make-kit/components/surface.md

@@ -9,7 +9,7 @@ The low-level elevated container. It paints a tokened surface — background + s
 ## When to use
 
 - You need a plain elevated box (a promo, a callout, a small panel) and don't need Card's header/content/footer slots.
-- You're building a new component that sits on a surface — compose `Surface`, never hand-roll `bg-surface-raised … shadow-raised`.
+- You're building a new component that sits on a surface — compose `Surface`, never hand-roll `bg-surface-panel … shadow-raised`.
 
 Use `<Card>` instead when you want the gap-model padding rhythm and the `CardHeader`/`CardContent`/`CardFooter` slots. Use raw utilities for nothing — if it's a surface, it's a `Surface`.
 
@@ -17,8 +17,8 @@ Use `<Card>` instead when you want the gap-model padding rhythm and the `CardHea
 
 | `elevation` | Surface | Use for |
 |---|---|---|
-| `flat` | `bg-surface-raised`, no shadow | On-page tiles. Pair with `bordered` for an edge. |
-| `raised` *(default)* | `bg-surface-raised` + `shadow-raised` | Cards, panels — anything sitting on the page. |
+| `flat` | `bg-surface-panel`, no shadow | On-page tiles. Pair with `bordered` for an edge. |
+| `raised` *(default)* | `bg-surface-panel` + `shadow-raised` | Cards, panels — anything sitting on the page. |
 | `floating` | `bg-surface-overlay` + `shadow-floating` | Toasts, floating toolbars. |
 | `overlay` | `bg-surface-overlay` + `shadow-overlay` | Popovers, menus, dialogs. |
 
@@ -55,6 +55,6 @@ Plus all native `div` props. Server-safe; forwards ref.
 ## Rules
 
 - **Edge OR elevation, never both.** `bordered` + a shadowed `elevation` is the double-edge anti-pattern (dev-warns). Use `elevation="flat" bordered`, or drop `bordered`.
-- `flat` is still a surface (`bg-surface-raised`), not the page — a card without a shadow, not a hole in the page.
+- `flat` is still a surface (`bg-surface-panel`), not the page — a card without a shadow, not a hole in the page.
 - Don't reach for `Surface` when you mean `Card` — if you're rebuilding header/content/footer spacing by hand, use `Card`.
 - Padding is symmetric. For anything asymmetric, use `className` or `Card`.

package/make-kit/foundations/color.md

@@ -13,7 +13,7 @@ The kit ships an OKLCH 12-step ramp per color family (`1`=app-bg, `9`=solid/acce
 ```
 Surface (background of a region)?
   → page bg                → bg-surface-base
-  → card / widget / panel  → bg-surface-raised
+  → card / widget / panel  → bg-surface-panel
   → sidebar / topbar       → bg-surface-sunken
   → dialog / popover / dropdown / input → bg-surface-overlay
   → tooltip                → bg-surface-inverted
@@ -50,9 +50,9 @@ Brand emphasis?
 | Token | Use |
 |---|---|
 | `surface-base` | Page background. The "back wall" of the app. |
-| `surface-raised` | Cards, widgets, panels, anything that sits **on** the page. |
-| `surface-raised-hover` | Hover state on a `surface-raised` element. |
-| `surface-raised-active` | Pressed / active state. |
+| `surface-panel` | Cards, widgets, panels, anything that sits **on** the page. |
+| `surface-panel-hover` | Hover state on a `surface-panel` element. |
+| `surface-panel-active` | Pressed / active state. |
 | `surface-sunken` | Shell chrome (sidebar, topbar), board columns, segmented-control tracks. |
 | `surface-overlay` | Floating layers — dialogs, popovers, dropdowns, inputs, toasts. |
 | `surface-inverted` | Tooltips, inverted badges. Pair with `surface-inverted-fg`. |

package/make-kit/foundations/dark-mode.md

@@ -39,7 +39,7 @@ function ThemeToggle() {
 
 ## What you have to do per-component
 
-Nothing. Semantic tokens flip automatically. As long as you use `bg-surface-raised` not `bg-white`, dark mode works.
+Nothing. Semantic tokens flip automatically. As long as you use `bg-surface-panel` not `bg-white`, dark mode works.
 
 The only exception: **images, illustrations, decorative SVGs**. These don't flip. Author them as theme-aware:
 

package/make-kit/foundations/radius.md

@@ -36,7 +36,7 @@ In components: never — they apply the right role automatically.
 In your own elements (rare):
 
 ```tsx
-<div className="bg-surface-raised rounded-(--radius-surface) p-ds-05">…</div>
+<div className="bg-surface-panel rounded-(--radius-surface) p-ds-05">…</div>
 ```
 
 TW4 shorthand `rounded-(--radius-surface)` is the right way. **Do not** use `rounded-ds-lg` directly — it's not a semantic role, and the pre-publish audit rejects it in `src/ui/`.

package/make-kit/foundations/surfaces.md

@@ -7,15 +7,15 @@ The kit ships five semantic surface tiers and a paired shadow system. **Picking
 | Tier | Token | What sits here |
 |---|---|---|
 | **Base** | `surface-base` | Page background. The "back wall." |
-| **Raised** | `surface-raised` | Cards, widgets, panels — anything that floats **on** the page. |
+| **Raised** | `surface-panel` | Cards, widgets, panels — anything that floats **on** the page. |
 | **Sunken** | `surface-sunken` | Shell chrome (Sidebar, TopBar), board columns, segmented-control tracks. |
 | **Overlay** | `surface-overlay` | Floating layers — Dialog, Sheet, Popover, Dropdown, Toast, Tooltip-when-light, Input field. |
 | **Inverted** | `surface-inverted` | Tooltips, inverted badges. Pair with `text-surface-inverted-fg`. |
 
 Each tier has hover / active variants:
 
-- `surface-raised-hover` — hover on a raised element.
-- `surface-raised-active` — pressed / selected raised element.
+- `surface-panel-hover` — hover on a raised element.
+- `surface-panel-active` — pressed / selected raised element.
 
 And a disabled state:
 
@@ -27,8 +27,8 @@ And a disabled state:
 |---|---|---|
 | Page / layout shell | `surface-base` | none |
 | Sidebar / TopBar (shell) | `surface-sunken` | `shadow-raised` |
-| Card / widget / panel | `surface-raised` | `shadow-raised` |
-| Card on hover | `surface-raised` | `shadow-raised-hover` |
+| Card / widget / panel | `surface-panel` | `shadow-raised` |
+| Card on hover | `surface-panel` | `shadow-raised-hover` |
 | Board column / well / track | `surface-sunken` | none |
 | Popover / dropdown / menu | `surface-overlay` | `shadow-floating` |
 | Dialog / modal / sheet | `surface-overlay` | `shadow-overlay` |
@@ -64,17 +64,17 @@ Shadow tokens include a 1-px ring layer (inset hairline + drop shadow). Adding a
 
 ❌ **Wrong:**
 ```tsx
-<div className="bg-surface-raised border border-surface-border shadow-raised rounded-(--radius-surface)">
+<div className="bg-surface-panel border border-surface-border shadow-raised rounded-(--radius-surface)">
 ```
 
 ✅ **Right (shadow only):**
 ```tsx
-<div className="bg-surface-raised shadow-raised rounded-(--radius-surface)">
+<div className="bg-surface-panel shadow-raised rounded-(--radius-surface)">
 ```
 
 ✅ **Right (border only — when shadow is unwanted, e.g. dense lists):**
 ```tsx
-<div className="bg-surface-raised border border-surface-border rounded-(--radius-surface)">
+<div className="bg-surface-panel border border-surface-border rounded-(--radius-surface)">
 ```
 
 `<Card>` already follows this rule. Don't override with extra border classes.
@@ -113,7 +113,7 @@ In dark mode the kit lightens surfaces with elevation (so `surface-overlay` is *
 
 ## Rules
 
-- **Card-like elements** (anything that reads as a panel on the page) → `surface-raised`, never `surface-base`.
+- **Card-like elements** (anything that reads as a panel on the page) → `surface-panel`, never `surface-base`.
 - **Overlay-like elements** → `surface-overlay`, always.
 - **Never** combine an explicit border with a shadow token.
 - **Never** invent a sixth tier. Five is the system.