@devalok/shilp-sutra 0.56.0 → 0.59.0

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.