@devalok/shilp-sutra 0.22.2 → 0.23.0

package/docs/components/ui/avatar.md

@@ -34,11 +34,15 @@
 ## Gotchas
 - Status dot renders with role="img" and aria-label (accessible, not decorative)
 - Dot size scales automatically with avatar size
+- AvatarFallback font size scales automatically with avatar size (via AvatarSizeContext)
 - Ring offset color matches the surface context — ensure it sits on the expected background
 - Badge is hidden when value is `0` (falsy); use `"dot"` for presence without a count
 - Online status dot pulses with a CSS animation
 
 ## Changes
+### v0.22.3
+- **Fixed** AvatarFallback text now auto-scales with avatar size — xs gets `text-[9px]`, sm `text-ds-xs`, md `text-ds-sm`, lg `text-ds-md`, xl `text-ds-lg`
+
 ### v0.22.0
 - **Fixed** Fallback always rendered `rounded-ds-full` regardless of `shape` prop. Now uses `AvatarShapeContext` to inherit the correct border-radius from `shape="square"` or `shape="rounded"`.
 

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.22.2
+> Version: 0.23.0
 
 ---
 
@@ -353,11 +353,15 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
 ## Gotchas
 - Status dot renders with role="img" and aria-label (accessible, not decorative)
 - Dot size scales automatically with avatar size
+- AvatarFallback font size scales automatically with avatar size (via AvatarSizeContext)
 - Ring offset color matches the surface context — ensure it sits on the expected background
 - Badge is hidden when value is `0` (falsy); use `"dot"` for presence without a count
 - Online status dot pulses with a CSS animation
 
 ## Changes
+### v0.22.3
+- **Fixed** AvatarFallback text now auto-scales with avatar size — xs gets `text-[9px]`, sm `text-ds-xs`, md `text-ds-sm`, lg `text-ds-md`, xl `text-ds-lg`
+
 ### v0.22.0
 - **Fixed** Fallback always rendered `rounded-ds-full` regardless of `shape` prop. Now uses `AvatarShapeContext` to inherit the correct border-radius from `shape="square"` or `shape="rounded"`.
 
@@ -3042,8 +3046,13 @@ export default function RootLayout({ children }) {
 - Missing `image` falls back to initials derived from `name`
 - Hover expand animation uses CSS `group-hover` — parent must not clip overflow
 - `borderColor` should match the surface context the group sits on (e.g., `surface-1` on cards)
+- `renderAvatar` wrapper is positioning-only — pass `size` directly to your Avatar (do NOT use `className="h-full w-full"`)
 
 ## Changes
+### v0.22.3
+- **Fixed** `renderAvatar` wrapper no longer clips consumer Avatar content (removed overflow-hidden, border, and size classes from wrapper)
+- **Fixed** Removed redundant text-size classes from wrapper — Avatar handles font scaling internally
+
 ### v0.21.0
 - **Added** `xs` and `xl` size variants
 - **Added** `borderColor` prop for overlap border matching surface context

package/llms.txt

@@ -4,6 +4,65 @@
 > Built on the same primitives as shadcn/ui but with key API differences.
 > Read this file BEFORE writing any UI code. Do NOT guess from shadcn/ui knowledge.
 
+## BREAKING CHANGES (v0.23.0 — Semantic Surface & Shadow Tokens)
+
+**Surface tokens renamed:** Numeric `surface-1..4` replaced with semantic names.
+| Old | New | Usage |
+|-----|-----|-------|
+| `bg-surface-1` | `bg-surface-base` | Page background |
+| `bg-surface-1` | `bg-surface-sunken` | Shell chrome (sidebar, topbar), board columns |
+| `bg-surface-1` | `bg-surface-overlay` | Dialogs, popovers, dropdowns, inputs |
+| `bg-surface-2` | `bg-surface-raised` | Cards, widgets, panels |
+| `bg-surface-3` | `bg-surface-raised-hover` | Hover states on raised elements |
+| `bg-surface-4` | `bg-surface-raised-active` | Active/pressed states |
+
+Same pattern for `border-surface-*`, `text-surface-*`, `ring-surface-*`.
+
+**Shadow tokens renamed:** Numeric `shadow-01..05` replaced with semantic names.
+| Old | New |
+|-----|-----|
+| `shadow-01` | `shadow-raised` |
+| `shadow-02` | `shadow-raised-hover` |
+| `shadow-03` | `shadow-floating` |
+| `shadow-04` | `shadow-overlay` |
+| `shadow-05` | (removed — was unused) |
+
+**New surface tokens:**
+- `bg-surface-sunken` — recessed areas (sidebar, board columns, segmented track)
+- `bg-surface-overlay` — floating elements (dialogs, popovers, inputs). Diverges from base in dark mode.
+- `bg-surface-inverted` / `text-surface-inverted-fg` — tooltips, inverted badges
+- `bg-surface-disabled` / `text-surface-fg-disabled` — disabled elements
+- `border-surface-border-subtle` — hairline dividers
+- `bg-backdrop` — dialog/sheet backdrop overlay
+
+**New shadow tokens:**
+- `shadow-glow` — selection/focus accent glow
+- `shadow-inset` — toggle/segmented track deboss
+- `shadow-ring` / `shadow-ring-sm` — focus ring / subtle separator
+
+**Hard rule: never combine explicit border + shadow.** Shadows include a 1px ring layer. Adding a CSS border creates a 2px edge. Use shadow OR border, never both.
+
+**Backward compat:** Old CSS variable names (`--color-surface-1`, `--shadow-01`) preserved as aliases. Old Tailwind classes still resolve. Will be removed in a future major version.
+
+**Component Decision Matrix:**
+| Building... | Surface | Shadow |
+|-------------|---------|--------|
+| Page/layout | `surface-base` | none |
+| Shell (sidebar/topbar) | `surface-sunken` | `shadow-raised` |
+| Card/widget/panel | `surface-raised` | `shadow-raised` |
+| Card hover | `surface-raised` | `shadow-raised-hover` |
+| Board column/well | `surface-sunken` | none |
+| Popover/menu/dropdown | `surface-overlay` | `shadow-floating` |
+| Dialog/modal/sheet | `surface-overlay` | `shadow-overlay` |
+| Tooltip | `surface-inverted` | `shadow-floating` |
+| Toast | `surface-overlay` | `shadow-floating` |
+| Input (rest) | `surface-overlay` | none |
+| Input (focus) | `surface-overlay` | `shadow-ring` |
+| Button (solid) | accent colors | `shadow-raised` |
+| Button (disabled) | `surface-disabled` | none |
+| Segmented track | `surface-sunken` | `shadow-inset` |
+| Selected item | current surface | `shadow-glow` |
+
 ## BREAKING CHANGES (v0.18.0 — Framer Motion + OKLCH)
 
 **New runtime dependency:** `framer-motion@^12.36.0` (bundled). Karm consumers must install `framer-motion@^12.0.0` as peer dep.
@@ -77,9 +136,9 @@
 - All color primitives migrated from hex (50-950 shades) to OKLCH (12 functional steps)
 - Old shade numbers: --pink-50..950. New step numbers: --pink-1..12 (OKLCH values)
 - Step purposes: 1=app-bg, 2=subtle-bg, 3=component-bg, 4=hover, 5=active, 6=border-subtle, 7=border, 8=border-strong, 9=solid/accent, 10=solid-hover, 11=lo-contrast-text, 12=hi-contrast-text
-- New semantic tokens: --color-accent-{1-12}, --color-secondary-{1-12}, --color-surface-{1-4}, --color-surface-fg/fg-muted/fg-subtle/border
+- New semantic tokens: --color-accent-{1-12}, --color-secondary-{1-12}, --color-surface-{base,raised,raised-hover,raised-active,sunken,overlay,inverted,disabled}, --color-surface-fg/fg-muted/fg-subtle/border/border-subtle
 - Status tokens: --color-error-{3,7,9,11,fg}, --color-success-{3,7,9,11,fg}, --color-warning-{3,7,9,11,fg}, --color-info-{3,7,9,11,fg}
-- New Tailwind utilities: accent-1..12, secondary-1..12, surface-1..4, status/category step utilities
+- New Tailwind utilities: accent-1..12, secondary-1..12, surface-base/raised/sunken/overlay/inverted/disabled (+ legacy surface-1..4 aliases), status/category step utilities
 - Backward compat: ALL old semantic token names preserved as aliases. --color-interactive still works → maps to --color-accent-9
 - Consumer rebranding: override --color-accent-1..12 CSS vars OR use generateScale() utility with a seed color
 - Dark mode: algorithmically derived (OKLCH curves), NOT hex overrides. Surfaces lighten with elevation.
@@ -87,7 +146,7 @@
 
 ## v0.22.0 — UI Polish & Micro-Refinement
 
-**Shadows**: All shadow tokens now use 3-layer stacks. Visual change only — same token names.
+**Shadows**: All shadow tokens now use 3-layer stacks. Visual change only — same token names. Shadow tokens renamed in v0.23.0 (see breaking changes above).
 
 **Transitions**: All CSS transitions use `ease-productive-standard` easing. Tween presets aligned: `tweens.fade` = 0.11s, `tweens.colorShift` = 0.07s.
 
@@ -101,7 +160,9 @@
 
 **Tooltip**: Auto-wraps with `<TooltipProvider>` — no manual provider needed. Text color fixed for dark mode.
 
-**Avatar fallback**: Now respects `shape` prop (was always circle).
+**Avatar fallback**: Now respects `shape` prop (was always circle). Font size auto-scales with avatar size (v0.22.3).
+
+**AvatarGroup renderAvatar**: Wrapper is positioning-only — pass `size` directly to your Avatar, do NOT use `className="h-full w-full"` (v0.22.3).
 
 **New hover states**: Checkbox, Radio, Switch track, Select items, DropdownMenu items, Combobox trigger.
 
@@ -242,7 +303,7 @@ NOTIFICATION SELECTION GUIDE:
 ### Composed Components
 - ConfirmDialog: open, onOpenChange, title, description, onConfirm + confirmText, cancelText, color(default|error), loading
 - PageHeader: title, subtitle, breadcrumbs[], actions(ReactNode)
-- AvatarGroup: users(AvatarUser[]), max?(number), size?(xs|sm|md|lg|xl), showTooltip?, borderColor?('surface-1'|'surface-2'), onOverflowClick?(), renderAvatar?((user,index)=>ReactNode), expandDirection?('left'|'right'), expandAmount?('compact'|'default'|'wide'). Type: AvatarUser = { name, image?, ring? }. GPU-composited hover expand via translateX. Use expandDirection="left" for right-aligned groups.
+- AvatarGroup: users(AvatarUser[]), max?(number), size?(xs|sm|md|lg|xl), showTooltip?, borderColor?('surface-base'|'surface-raised'), onOverflowClick?(), renderAvatar?((user,index)=>ReactNode), expandDirection?('left'|'right'), expandAmount?('compact'|'default'|'wide'). Type: AvatarUser = { name, image?, ring? }. GPU-composited hover expand via translateX. Use expandDirection="left" for right-aligned groups.
 - StatusBadge: DISCRIMINATED UNION — pass status OR color, not both. status(active|pending|approved|rejected|completed|blocked|cancelled|draft) color(success|warning|error|info|neutral) size(sm|md)
 - ContentCard: variant(default|outline|ghost) padding(default|compact|spacious|none)
 - EmptyState: icon(ReactNode or ComponentType), title(required), description, action(ReactNode), compact

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "description": "Devalok Design System — tokens, components, and patterns for Next.js",
   "license": "MIT",
   "type": "module",