@devalok/shilp-sutra 0.55.1 → 0.57.0

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.