@devalok/shilp-sutra 0.45.1 → 0.47.0

package/dist/ui/surface.js

@@ -0,0 +1,51 @@
+import { Hn as e } from "../_chunks/primitives.js";
+import { t } from "../_chunks/vendor-utils.js";
+import { cn as n } from "./lib/utils.js";
+import * as r from "react";
+import { jsx as i } from "react/jsx-runtime";
+//#region src/ui/surface.tsx
+var a = t("", {
+	variants: {
+		elevation: {
+			flat: "bg-surface-raised",
+			raised: "bg-surface-raised shadow-raised",
+			floating: "bg-surface-overlay shadow-floating",
+			overlay: "bg-surface-overlay shadow-overlay"
+		},
+		padding: {
+			none: "",
+			sm: "p-ds-04",
+			md: "p-ds-05",
+			lg: "p-ds-06"
+		},
+		radius: {
+			none: "rounded-none",
+			control: "rounded-control",
+			surface: "rounded-surface",
+			overlay: "rounded-overlay",
+			pill: "rounded-pill"
+		},
+		bordered: {
+			true: "border border-surface-border-strong",
+			false: ""
+		}
+	},
+	defaultVariants: {
+		elevation: "raised",
+		padding: "none",
+		radius: "surface",
+		bordered: !1
+	}
+}), o = r.forwardRef(({ className: t, elevation: r, padding: o, radius: s, bordered: c, asChild: l = !1, ...u }, d) => (typeof process < "u" && process.env.NODE_ENV !== "production" && c && (r ?? "raised") !== "flat" && console.warn("[shilp-sutra] <Surface> combines `bordered` with a raised `elevation` — the double-edge anti-pattern. Pick one: use elevation=\"flat\" with `bordered`, or drop `bordered` and let the elevation carry the edge."), /* @__PURE__ */ i(l ? e : "div", {
+	ref: d,
+	className: n(a({
+		elevation: r,
+		padding: o,
+		radius: s,
+		bordered: c
+	}), t),
+	...u
+})));
+o.displayName = "Surface";
+//#endregion
+export { o as Surface, a as surfaceVariants };

package/dist/ui/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","names":[],"sources":["../../src/ui/surface.tsx"],"sourcesContent":["// @server-safe\nimport { Slot } from '@primitives/react-slot'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport * as React from 'react'\n\nimport { cn } from './lib/utils'\n\n// Bundlers (Vite, Next.js, webpack) define process.env.NODE_ENV; guard for raw ESM.\ndeclare const process: { env: { NODE_ENV?: string } } | undefined\n\nconst surfaceVariants = cva('', {\n  variants: {\n    // Elevation binds a surface-bg token to a shadow token — the one axis that\n    // matters. `flat` sits on the page with no shadow (pair with `bordered` for a\n    // Carbon-Tile edge); `raised` is the card level; `floating`/`overlay` are the\n    // popover/menu/toast levels. bg + shadow always move together, so there is no\n    // way to produce an un-tokened surface.\n    elevation: {\n      flat: 'bg-surface-raised',\n      raised: 'bg-surface-raised shadow-raised',\n      floating: 'bg-surface-overlay shadow-floating',\n      overlay: 'bg-surface-overlay shadow-overlay',\n    },\n    // Simple, symmetric all-side padding — NOT Card's gap model. This is what keeps\n    // Surface low-level: a plain box you can drop content into. Reach for Card when\n    // you want the header/content/footer slot rhythm.\n    padding: {\n      none: '',\n      sm: 'p-ds-04',\n      md: 'p-ds-05',\n      lg: 'p-ds-06',\n    },\n    radius: {\n      none: 'rounded-none',\n      control: 'rounded-control',\n      surface: 'rounded-surface',\n      overlay: 'rounded-overlay',\n      pill: 'rounded-pill',\n    },\n    // Border-led edge (Carbon-Tile style). Meant for `elevation=\"flat\"`; combining it\n    // with a shadowed elevation is the double-edge anti-pattern and dev-warns below.\n    bordered: {\n      true: 'border border-surface-border-strong',\n      false: '',\n    },\n  },\n  defaultVariants: {\n    elevation: 'raised',\n    padding: 'none',\n    radius: 'surface',\n    bordered: false,\n  },\n})\n\nexport interface SurfaceProps\n  extends React.HTMLAttributes<HTMLDivElement>,\n    VariantProps<typeof surfaceVariants> {\n  /** Render as the passed child element (Radix Slot) instead of a `div` — wrap a link,\n   * section, or `motion.div` without adding a wrapper node. */\n  asChild?: boolean\n}\n\n/**\n * Surface — the low-level elevated container primitive.\n *\n * The building block every panel, card, popover, and toast surface sits on. It owns\n * exactly one job: paint a tokened surface (background + shadow), with optional radius,\n * padding, and border. It has no slots, no color axis, and no motion — those belong to\n * the components composed on top of it (Card = Surface + gap-model padding + slots).\n *\n * **Elevation:** `flat` (bg, no shadow — pair with `bordered`) | `raised` (card level,\n * default) | `floating` (toasts, floating toolbars) | `overlay` (popovers, menus, dialogs).\n *\n * **Padding:** `none` (default) | `sm` (12px) | `md` (16px) | `lg` (24px) — simple all-side.\n *\n * **Edge vs. elevation:** use a shadow (`raised`/`floating`/`overlay`) OR a `bordered`\n * `flat` — never both (the double-edge anti-pattern; dev-warns).\n *\n * @example\n * // A raised panel with comfortable padding:\n * <Surface elevation=\"raised\" padding=\"md\">…</Surface>\n *\n * @example\n * // An on-page, border-led tile (no shadow):\n * <Surface elevation=\"flat\" bordered padding=\"sm\">…</Surface>\n *\n * @example\n * // Wrap a link as the surface itself:\n * <Surface asChild elevation=\"raised\" padding=\"sm\">\n *   <a href=\"/upgrade\">…</a>\n * </Surface>\n */\nconst Surface = React.forwardRef<HTMLDivElement, SurfaceProps>(\n  (\n    { className, elevation, padding, radius, bordered, asChild = false, ...props },\n    ref,\n  ) => {\n    if (\n      typeof process !== 'undefined' &&\n      process?.env.NODE_ENV !== 'production' &&\n      bordered &&\n      (elevation ?? 'raised') !== 'flat'\n    ) {\n      console.warn(\n        '[shilp-sutra] <Surface> combines `bordered` with a raised `elevation` — the double-edge anti-pattern. Pick one: use elevation=\"flat\" with `bordered`, or drop `bordered` and let the elevation carry the edge.',\n      )\n    }\n    const Comp = asChild ? Slot : 'div'\n    return (\n      <Comp\n        ref={ref}\n        className={cn(\n          surfaceVariants({ elevation, padding, radius, bordered }),\n          className,\n        )}\n        {...props}\n      />\n    )\n  },\n)\nSurface.displayName = 'Surface'\n\nexport { Surface, surfaceVariants }\n"],"mappings":";;;;;;AAUA,IAAM,IAAkB,EAAI,IAAI;CAC9B,UAAU;EAMR,WAAW;GACT,MAAM;GACN,QAAQ;GACR,UAAU;GACV,SAAS;GACV;EAID,SAAS;GACP,MAAM;GACN,IAAI;GACJ,IAAI;GACJ,IAAI;GACL;EACD,QAAQ;GACN,MAAM;GACN,SAAS;GACT,SAAS;GACT,SAAS;GACT,MAAM;GACP;EAGD,UAAU;GACR,MAAM;GACN,OAAO;GACR;EACF;CACD,iBAAiB;EACf,WAAW;EACX,SAAS;EACT,QAAQ;EACR,UAAU;EACX;CACF,CAAC,EAwCI,IAAU,EAAM,YAElB,EAAE,cAAW,cAAW,YAAS,WAAQ,aAAU,aAAU,IAAO,GAAG,KACvE,OAGE,OAAO,UAAY,OAAA,QAAA,IAAA,aACO,gBAC1B,MACC,KAAa,cAAc,UAE5B,QAAQ,KACN,mNACD,EAID,kBAFW,IAAU,IAAO,OAE5B;CACO;CACL,WAAW,EACT,EAAgB;EAAE;EAAW;EAAS;EAAQ;EAAU,CAAC,EACzD,EACD;CACD,GAAI;CACJ,CAAA,EAGP;AACD,EAAQ,cAAc"}

package/dist/ui/text.js

@@ -4,12 +4,12 @@ import * as n from "react";
 //#region src/ui/text.tsx
 var r = e("font-sans", {
 	variants: { variant: {
-		"heading-2xl": "text-[length:var(--typo-heading-2xl-size)] font-[number:var(--typo-heading-2xl-weight)] leading-[var(--typo-heading-2xl-leading)] tracking-[var(--typo-heading-2xl-tracking)]",
-		"heading-xl": "text-[length:var(--typo-heading-xl-size)] font-[number:var(--typo-heading-xl-weight)] leading-[var(--typo-heading-xl-leading)] tracking-[var(--typo-heading-xl-tracking)]",
-		"heading-lg": "text-[length:var(--typo-heading-lg-size)] font-[number:var(--typo-heading-lg-weight)] leading-[var(--typo-heading-lg-leading)] tracking-[var(--typo-heading-lg-tracking)]",
-		"heading-md": "text-[length:var(--typo-heading-md-size)] font-[number:var(--typo-heading-md-weight)] leading-[var(--typo-heading-md-leading)] tracking-[var(--typo-heading-md-tracking)]",
-		"heading-sm": "text-[length:var(--typo-heading-sm-size)] font-[number:var(--typo-heading-sm-weight)] leading-[var(--typo-heading-sm-leading)] tracking-[var(--typo-heading-sm-tracking)]",
-		"heading-xs": "text-[length:var(--typo-heading-xs-size)] font-[number:var(--typo-heading-xs-weight)] leading-[var(--typo-heading-xs-leading)] tracking-[var(--typo-heading-xs-tracking)]",
+		"heading-2xl": "font-display text-[length:var(--typo-heading-2xl-size)] font-[number:var(--typo-heading-2xl-weight)] leading-[var(--typo-heading-2xl-leading)] tracking-[var(--typo-heading-2xl-tracking)]",
+		"heading-xl": "font-display text-[length:var(--typo-heading-xl-size)] font-[number:var(--typo-heading-xl-weight)] leading-[var(--typo-heading-xl-leading)] tracking-[var(--typo-heading-xl-tracking)]",
+		"heading-lg": "font-display text-[length:var(--typo-heading-lg-size)] font-[number:var(--typo-heading-lg-weight)] leading-[var(--typo-heading-lg-leading)] tracking-[var(--typo-heading-lg-tracking)]",
+		"heading-md": "font-display text-[length:var(--typo-heading-md-size)] font-[number:var(--typo-heading-md-weight)] leading-[var(--typo-heading-md-leading)] tracking-[var(--typo-heading-md-tracking)]",
+		"heading-sm": "font-display text-[length:var(--typo-heading-sm-size)] font-[number:var(--typo-heading-sm-weight)] leading-[var(--typo-heading-sm-leading)] tracking-[var(--typo-heading-sm-tracking)]",
+		"heading-xs": "font-display text-[length:var(--typo-heading-xs-size)] font-[number:var(--typo-heading-xs-weight)] leading-[var(--typo-heading-xs-leading)] tracking-[var(--typo-heading-xs-tracking)]",
 		"body-lg": "text-[length:var(--typo-body-lg-size)] font-[number:var(--typo-body-lg-weight)] leading-[var(--typo-body-lg-leading)] tracking-[var(--typo-body-lg-tracking)]",
 		"body-md": "text-[length:var(--typo-body-md-size)] font-[number:var(--typo-body-md-weight)] leading-[var(--typo-body-md-leading)] tracking-[var(--typo-body-md-tracking)]",
 		"body-sm": "text-[length:var(--typo-body-sm-size)] font-[number:var(--typo-body-sm-weight)] leading-[var(--typo-body-sm-leading)] tracking-[var(--typo-body-sm-tracking)]",

package/dist/ui/text.js.map

@@ -1 +1 @@
-{"version":3,"file":"text.js","names":[],"sources":["../../src/ui/text.tsx"],"sourcesContent":["// @server-safe\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport * as React from 'react'\n\nimport { cn } from './lib/utils'\n\nconst textVariants = cva('font-sans', {\n  variants: {\n    variant: {\n      'heading-2xl': 'text-[length:var(--typo-heading-2xl-size)] font-[number:var(--typo-heading-2xl-weight)] leading-[var(--typo-heading-2xl-leading)] tracking-[var(--typo-heading-2xl-tracking)]',\n      'heading-xl':  'text-[length:var(--typo-heading-xl-size)] font-[number:var(--typo-heading-xl-weight)] leading-[var(--typo-heading-xl-leading)] tracking-[var(--typo-heading-xl-tracking)]',\n      'heading-lg':  'text-[length:var(--typo-heading-lg-size)] font-[number:var(--typo-heading-lg-weight)] leading-[var(--typo-heading-lg-leading)] tracking-[var(--typo-heading-lg-tracking)]',\n      'heading-md':  'text-[length:var(--typo-heading-md-size)] font-[number:var(--typo-heading-md-weight)] leading-[var(--typo-heading-md-leading)] tracking-[var(--typo-heading-md-tracking)]',\n      'heading-sm':  'text-[length:var(--typo-heading-sm-size)] font-[number:var(--typo-heading-sm-weight)] leading-[var(--typo-heading-sm-leading)] tracking-[var(--typo-heading-sm-tracking)]',\n      'heading-xs':  'text-[length:var(--typo-heading-xs-size)] font-[number:var(--typo-heading-xs-weight)] leading-[var(--typo-heading-xs-leading)] tracking-[var(--typo-heading-xs-tracking)]',\n      'body-lg':     'text-[length:var(--typo-body-lg-size)] font-[number:var(--typo-body-lg-weight)] leading-[var(--typo-body-lg-leading)] tracking-[var(--typo-body-lg-tracking)]',\n      'body-md':     'text-[length:var(--typo-body-md-size)] font-[number:var(--typo-body-md-weight)] leading-[var(--typo-body-md-leading)] tracking-[var(--typo-body-md-tracking)]',\n      'body-sm':     'text-[length:var(--typo-body-sm-size)] font-[number:var(--typo-body-sm-weight)] leading-[var(--typo-body-sm-leading)] tracking-[var(--typo-body-sm-tracking)]',\n      'body-xs':     'text-[length:var(--typo-body-xs-size)] font-[number:var(--typo-body-xs-weight)] leading-[var(--typo-body-xs-leading)] tracking-[var(--typo-body-xs-tracking)]',\n      'label-lg':    'text-[length:var(--typo-label-lg-size)] font-[number:var(--typo-label-lg-weight)] leading-[var(--typo-label-lg-leading)] tracking-[var(--typo-label-lg-tracking)] uppercase',\n      'label-md':    'text-[length:var(--typo-label-md-size)] font-[number:var(--typo-label-md-weight)] leading-[var(--typo-label-md-leading)] tracking-[var(--typo-label-md-tracking)] uppercase',\n      'label-sm':    'text-[length:var(--typo-label-sm-size)] font-[number:var(--typo-label-sm-weight)] leading-[var(--typo-label-sm-leading)] tracking-[var(--typo-label-sm-tracking)] uppercase',\n      'label-xs':    'text-[length:var(--typo-label-xs-size)] font-[number:var(--typo-label-xs-weight)] leading-[var(--typo-label-xs-leading)] tracking-[var(--typo-label-xs-tracking)] uppercase',\n      caption:       'text-[length:var(--typo-caption-size)] font-[number:var(--typo-caption-weight)] leading-[var(--typo-caption-leading)] tracking-[var(--typo-caption-tracking)]',\n      overline:      'text-[length:var(--typo-overline-size)] font-[number:var(--typo-overline-weight)] leading-[var(--typo-overline-leading)] tracking-[var(--typo-overline-tracking)] uppercase',\n      code:              'text-[length:var(--typo-code-size)] font-[number:var(--typo-code-weight)] leading-[var(--typo-code-leading)] tracking-[var(--typo-code-tracking)] font-mono',\n      'label-plain-lg':  'text-[length:var(--typo-label-plain-lg-size)] font-[number:var(--typo-label-plain-lg-weight)] leading-[var(--typo-label-plain-lg-leading)] tracking-[var(--typo-label-plain-lg-tracking)]',\n      'label-plain-md':  'text-[length:var(--typo-label-plain-md-size)] font-[number:var(--typo-label-plain-md-weight)] leading-[var(--typo-label-plain-md-leading)] tracking-[var(--typo-label-plain-md-tracking)]',\n      'label-plain-sm':  'text-[length:var(--typo-label-plain-sm-size)] font-[number:var(--typo-label-plain-sm-weight)] leading-[var(--typo-label-plain-sm-leading)] tracking-[var(--typo-label-plain-sm-tracking)]',\n    },\n  },\n  defaultVariants: {\n    variant: 'body-md',\n  },\n})\n\ntype TextVariant = NonNullable<VariantProps<typeof textVariants>['variant']>\n\nconst defaultElementMap: Record<TextVariant, keyof React.JSX.IntrinsicElements> = {\n  'heading-2xl': 'h1',\n  'heading-xl':  'h2',\n  'heading-lg':  'h3',\n  'heading-md':  'h4',\n  'heading-sm':  'h5',\n  'heading-xs':  'h6',\n  'body-lg':     'p',\n  'body-md':     'p',\n  'body-sm':     'p',\n  'body-xs':     'p',\n  'label-lg':    'span',\n  'label-md':    'span',\n  'label-sm':    'span',\n  'label-xs':    'span',\n  caption:       'span',\n  overline:      'span',\n  code:              'code',\n  'label-plain-lg':  'span',\n  'label-plain-md':  'span',\n  'label-plain-sm':  'span',\n}\n\n/**\n * Props for Text — a polymorphic typography component covering the full type scale:\n * headings, body, labels, captions, and overlines — with automatic semantic HTML element selection.\n *\n * **Variants (grouped):**\n * - Headings: `heading-2xl` → `h1`, `heading-xl` → `h2`, `heading-lg` → `h3`, etc.\n * - Body: `body-lg` | `body-md` (default) | `body-sm` | `body-xs` → `<p>`\n * - Labels: `label-lg` | `label-md` | `label-sm` | `label-xs` → `<span>` (uppercase)\n * - Misc: `caption` | `overline` → `<span>` (overline is uppercase)\n *\n * **`as` prop:** Override the rendered element. E.g. `<Text variant=\"heading-lg\" as=\"div\">` renders\n * `<div class=\"text-heading-lg ...\">` — useful when you need heading styles on a non-heading element.\n *\n * @example\n * // Page heading:\n * <Text variant=\"heading-2xl\">Welcome to Shilp Sutra</Text>\n *\n * @example\n * // Section label (uppercase, small):\n * <Text variant=\"label-sm\" className=\"text-surface-fg-muted\">Recent activity</Text>\n *\n * @example\n * // Body copy with custom element (renders as <span> for inline use):\n * <Text variant=\"body-sm\" as=\"span\" className=\"text-surface-fg-muted\">\n *   Last updated 3 hours ago\n * </Text>\n *\n * @example\n * // Caption under an image or figure:\n * <Text variant=\"caption\" className=\"text-surface-fg-subtle\">Figure 1: System architecture</Text>\n * // These are just a few ways — feel free to combine props creatively!\n */\ntype TextProps<T extends React.ElementType = 'p'> = {\n  variant?: TextVariant\n  as?: T\n  className?: string\n  children?: React.ReactNode\n} & Omit<React.ComponentPropsWithRef<T>, 'as' | 'variant' | 'className' | 'children'>\n\n// Polymorphic component type — preserves T across the call site so element-\n// specific props (e.g. `htmlFor` on `as=\"label\"`, `href` on `as=\"a\"`) typecheck.\n// React.forwardRef can't keep a generic parameter live at its export, so we\n// type the implementation loosely and cast the public export to a generic\n// callable. Standard polymorphic-component pattern (same shape as Radix).\ntype TextComponent = (<T extends React.ElementType = 'p'>(\n  props: TextProps<T> & { ref?: React.ComponentPropsWithRef<T>['ref'] },\n) => React.ReactElement | null) & { displayName?: string }\n\nconst TextImpl = React.forwardRef<HTMLElement, TextProps>(\n  ({ variant = 'body-md', as, className, children, ...props }, ref) => {\n    const Component = as || defaultElementMap[variant] || 'p'\n    return React.createElement(\n      Component,\n      { ref, className: cn(textVariants({ variant }), className), ...props },\n      children,\n    )\n  },\n)\nTextImpl.displayName = 'Text'\n\nconst Text = TextImpl as unknown as TextComponent\n\nexport { Text, type TextProps, type TextVariant,textVariants }\n"],"mappings":";;;;AAMA,IAAM,IAAe,EAAI,aAAa;CACpC,UAAU,EACR,SAAS;EACP,eAAe;EACf,cAAe;EACf,cAAe;EACf,cAAe;EACf,cAAe;EACf,cAAe;EACf,WAAe;EACf,WAAe;EACf,WAAe;EACf,WAAe;EACf,YAAe;EACf,YAAe;EACf,YAAe;EACf,YAAe;EACf,SAAe;EACf,UAAe;EACf,MAAmB;EACnB,kBAAmB;EACnB,kBAAmB;EACnB,kBAAmB;EACpB,EACF;CACD,iBAAiB,EACf,SAAS,WACV;CACF,CAAC,EAII,IAA4E;CAChF,eAAe;CACf,cAAe;CACf,cAAe;CACf,cAAe;CACf,cAAe;CACf,cAAe;CACf,WAAe;CACf,WAAe;CACf,WAAe;CACf,WAAe;CACf,YAAe;CACf,YAAe;CACf,YAAe;CACf,YAAe;CACf,SAAe;CACf,UAAe;CACf,MAAmB;CACnB,kBAAmB;CACnB,kBAAmB;CACnB,kBAAmB;CACpB,EAkDK,IAAW,EAAM,YACpB,EAAE,aAAU,WAAW,OAAI,cAAW,aAAU,GAAG,KAAS,MAAQ;CACnE,IAAM,IAAY,KAAM,EAAkB,MAAY;AACtD,QAAO,EAAM,cACX,GACA;EAAE;EAAK,WAAW,EAAG,EAAa,EAAE,YAAS,CAAC,EAAE,EAAU;EAAE,GAAG;EAAO,EACtE,EACD;EAEJ;AACD,EAAS,cAAc;AAEvB,IAAM,IAAO"}
+{"version":3,"file":"text.js","names":[],"sources":["../../src/ui/text.tsx"],"sourcesContent":["// @server-safe\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport * as React from 'react'\n\nimport { cn } from './lib/utils'\n\nconst textVariants = cva('font-sans', {\n  variants: {\n    variant: {\n      'heading-2xl': 'font-display text-[length:var(--typo-heading-2xl-size)] font-[number:var(--typo-heading-2xl-weight)] leading-[var(--typo-heading-2xl-leading)] tracking-[var(--typo-heading-2xl-tracking)]',\n      'heading-xl':  'font-display text-[length:var(--typo-heading-xl-size)] font-[number:var(--typo-heading-xl-weight)] leading-[var(--typo-heading-xl-leading)] tracking-[var(--typo-heading-xl-tracking)]',\n      'heading-lg':  'font-display text-[length:var(--typo-heading-lg-size)] font-[number:var(--typo-heading-lg-weight)] leading-[var(--typo-heading-lg-leading)] tracking-[var(--typo-heading-lg-tracking)]',\n      'heading-md':  'font-display text-[length:var(--typo-heading-md-size)] font-[number:var(--typo-heading-md-weight)] leading-[var(--typo-heading-md-leading)] tracking-[var(--typo-heading-md-tracking)]',\n      'heading-sm':  'font-display text-[length:var(--typo-heading-sm-size)] font-[number:var(--typo-heading-sm-weight)] leading-[var(--typo-heading-sm-leading)] tracking-[var(--typo-heading-sm-tracking)]',\n      'heading-xs':  'font-display text-[length:var(--typo-heading-xs-size)] font-[number:var(--typo-heading-xs-weight)] leading-[var(--typo-heading-xs-leading)] tracking-[var(--typo-heading-xs-tracking)]',\n      'body-lg':     'text-[length:var(--typo-body-lg-size)] font-[number:var(--typo-body-lg-weight)] leading-[var(--typo-body-lg-leading)] tracking-[var(--typo-body-lg-tracking)]',\n      'body-md':     'text-[length:var(--typo-body-md-size)] font-[number:var(--typo-body-md-weight)] leading-[var(--typo-body-md-leading)] tracking-[var(--typo-body-md-tracking)]',\n      'body-sm':     'text-[length:var(--typo-body-sm-size)] font-[number:var(--typo-body-sm-weight)] leading-[var(--typo-body-sm-leading)] tracking-[var(--typo-body-sm-tracking)]',\n      'body-xs':     'text-[length:var(--typo-body-xs-size)] font-[number:var(--typo-body-xs-weight)] leading-[var(--typo-body-xs-leading)] tracking-[var(--typo-body-xs-tracking)]',\n      'label-lg':    'text-[length:var(--typo-label-lg-size)] font-[number:var(--typo-label-lg-weight)] leading-[var(--typo-label-lg-leading)] tracking-[var(--typo-label-lg-tracking)] uppercase',\n      'label-md':    'text-[length:var(--typo-label-md-size)] font-[number:var(--typo-label-md-weight)] leading-[var(--typo-label-md-leading)] tracking-[var(--typo-label-md-tracking)] uppercase',\n      'label-sm':    'text-[length:var(--typo-label-sm-size)] font-[number:var(--typo-label-sm-weight)] leading-[var(--typo-label-sm-leading)] tracking-[var(--typo-label-sm-tracking)] uppercase',\n      'label-xs':    'text-[length:var(--typo-label-xs-size)] font-[number:var(--typo-label-xs-weight)] leading-[var(--typo-label-xs-leading)] tracking-[var(--typo-label-xs-tracking)] uppercase',\n      caption:       'text-[length:var(--typo-caption-size)] font-[number:var(--typo-caption-weight)] leading-[var(--typo-caption-leading)] tracking-[var(--typo-caption-tracking)]',\n      overline:      'text-[length:var(--typo-overline-size)] font-[number:var(--typo-overline-weight)] leading-[var(--typo-overline-leading)] tracking-[var(--typo-overline-tracking)] uppercase',\n      code:              'text-[length:var(--typo-code-size)] font-[number:var(--typo-code-weight)] leading-[var(--typo-code-leading)] tracking-[var(--typo-code-tracking)] font-mono',\n      'label-plain-lg':  'text-[length:var(--typo-label-plain-lg-size)] font-[number:var(--typo-label-plain-lg-weight)] leading-[var(--typo-label-plain-lg-leading)] tracking-[var(--typo-label-plain-lg-tracking)]',\n      'label-plain-md':  'text-[length:var(--typo-label-plain-md-size)] font-[number:var(--typo-label-plain-md-weight)] leading-[var(--typo-label-plain-md-leading)] tracking-[var(--typo-label-plain-md-tracking)]',\n      'label-plain-sm':  'text-[length:var(--typo-label-plain-sm-size)] font-[number:var(--typo-label-plain-sm-weight)] leading-[var(--typo-label-plain-sm-leading)] tracking-[var(--typo-label-plain-sm-tracking)]',\n    },\n  },\n  defaultVariants: {\n    variant: 'body-md',\n  },\n})\n\ntype TextVariant = NonNullable<VariantProps<typeof textVariants>['variant']>\n\nconst defaultElementMap: Record<TextVariant, keyof React.JSX.IntrinsicElements> = {\n  'heading-2xl': 'h1',\n  'heading-xl':  'h2',\n  'heading-lg':  'h3',\n  'heading-md':  'h4',\n  'heading-sm':  'h5',\n  'heading-xs':  'h6',\n  'body-lg':     'p',\n  'body-md':     'p',\n  'body-sm':     'p',\n  'body-xs':     'p',\n  'label-lg':    'span',\n  'label-md':    'span',\n  'label-sm':    'span',\n  'label-xs':    'span',\n  caption:       'span',\n  overline:      'span',\n  code:              'code',\n  'label-plain-lg':  'span',\n  'label-plain-md':  'span',\n  'label-plain-sm':  'span',\n}\n\n/**\n * Props for Text — a polymorphic typography component covering the full type scale:\n * headings, body, labels, captions, and overlines — with automatic semantic HTML element selection.\n *\n * **Variants (grouped):**\n * - Headings: `heading-2xl` → `h1`, `heading-xl` → `h2`, `heading-lg` → `h3`, etc.\n * - Body: `body-lg` | `body-md` (default) | `body-sm` | `body-xs` → `<p>`\n * - Labels: `label-lg` | `label-md` | `label-sm` | `label-xs` → `<span>` (uppercase)\n * - Misc: `caption` | `overline` → `<span>` (overline is uppercase)\n *\n * **`as` prop:** Override the rendered element. E.g. `<Text variant=\"heading-lg\" as=\"div\">` renders\n * `<div class=\"text-heading-lg ...\">` — useful when you need heading styles on a non-heading element.\n *\n * @example\n * // Page heading:\n * <Text variant=\"heading-2xl\">Welcome to Shilp Sutra</Text>\n *\n * @example\n * // Section label (uppercase, small):\n * <Text variant=\"label-sm\" className=\"text-surface-fg-muted\">Recent activity</Text>\n *\n * @example\n * // Body copy with custom element (renders as <span> for inline use):\n * <Text variant=\"body-sm\" as=\"span\" className=\"text-surface-fg-muted\">\n *   Last updated 3 hours ago\n * </Text>\n *\n * @example\n * // Caption under an image or figure:\n * <Text variant=\"caption\" className=\"text-surface-fg-subtle\">Figure 1: System architecture</Text>\n * // These are just a few ways — feel free to combine props creatively!\n */\ntype TextProps<T extends React.ElementType = 'p'> = {\n  variant?: TextVariant\n  as?: T\n  className?: string\n  children?: React.ReactNode\n} & Omit<React.ComponentPropsWithRef<T>, 'as' | 'variant' | 'className' | 'children'>\n\n// Polymorphic component type — preserves T across the call site so element-\n// specific props (e.g. `htmlFor` on `as=\"label\"`, `href` on `as=\"a\"`) typecheck.\n// React.forwardRef can't keep a generic parameter live at its export, so we\n// type the implementation loosely and cast the public export to a generic\n// callable. Standard polymorphic-component pattern (same shape as Radix).\ntype TextComponent = (<T extends React.ElementType = 'p'>(\n  props: TextProps<T> & { ref?: React.ComponentPropsWithRef<T>['ref'] },\n) => React.ReactElement | null) & { displayName?: string }\n\nconst TextImpl = React.forwardRef<HTMLElement, TextProps>(\n  ({ variant = 'body-md', as, className, children, ...props }, ref) => {\n    const Component = as || defaultElementMap[variant] || 'p'\n    return React.createElement(\n      Component,\n      { ref, className: cn(textVariants({ variant }), className), ...props },\n      children,\n    )\n  },\n)\nTextImpl.displayName = 'Text'\n\nconst Text = TextImpl as unknown as TextComponent\n\nexport { Text, type TextProps, type TextVariant,textVariants }\n"],"mappings":";;;;AAMA,IAAM,IAAe,EAAI,aAAa;CACpC,UAAU,EACR,SAAS;EACP,eAAe;EACf,cAAe;EACf,cAAe;EACf,cAAe;EACf,cAAe;EACf,cAAe;EACf,WAAe;EACf,WAAe;EACf,WAAe;EACf,WAAe;EACf,YAAe;EACf,YAAe;EACf,YAAe;EACf,YAAe;EACf,SAAe;EACf,UAAe;EACf,MAAmB;EACnB,kBAAmB;EACnB,kBAAmB;EACnB,kBAAmB;EACpB,EACF;CACD,iBAAiB,EACf,SAAS,WACV;CACF,CAAC,EAII,IAA4E;CAChF,eAAe;CACf,cAAe;CACf,cAAe;CACf,cAAe;CACf,cAAe;CACf,cAAe;CACf,WAAe;CACf,WAAe;CACf,WAAe;CACf,WAAe;CACf,YAAe;CACf,YAAe;CACf,YAAe;CACf,YAAe;CACf,SAAe;CACf,UAAe;CACf,MAAmB;CACnB,kBAAmB;CACnB,kBAAmB;CACnB,kBAAmB;CACpB,EAkDK,IAAW,EAAM,YACpB,EAAE,aAAU,WAAW,OAAI,cAAW,aAAU,GAAG,KAAS,MAAQ;CACnE,IAAM,IAAY,KAAM,EAAkB,MAAY;AACtD,QAAO,EAAM,cACX,GACA;EAAE;EAAK,WAAW,EAAG,EAAa,EAAE,YAAS,CAAC,EAAE,EAAU;EAAE,GAAG;EAAO,EACtE,EACD;EAEJ;AACD,EAAS,cAAc;AAEvB,IAAM,IAAO"}

package/docs/components/ui/surface.md

@@ -0,0 +1,55 @@
+# Surface
+
+- Import: @devalok/shilp-sutra/ui/surface
+- Server-safe: Yes
+- Category: ui
+
+The low-level elevated container primitive. Owns background + shadow + radius + optional padding and border — nothing else. Card, Popover, Toast, Sheet, and other surfaces compose it.
+
+## Props
+### Surface
+    elevation: "flat" | "raised" | "floating" | "overlay"
+    padding: "none" | "sm" | "md" | "lg"
+    radius: "none" | "control" | "surface" | "overlay" | "pill"
+    bordered: "true" | "false"
+    asChild: boolean — render as the passed child element (Radix Slot) instead of a div
+
+## Defaults
+    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)
+    floating  — bg-surface-overlay + shadow-floating (toasts, floating toolbars)
+    overlay   — bg-surface-overlay + shadow-overlay (popovers, menus, dialogs)
+
+## Padding
+    none=0 · sm=ds-04 (12px) · md=ds-05 (16px) · lg=ds-06 (24px) — simple all-side (not Card's gap model)
+
+## Example
+```jsx
+// Raised panel with padding
+<Surface elevation="raised" padding="md">…</Surface>
+
+// On-page, border-led tile (no shadow)
+<Surface elevation="flat" bordered padding="sm">…</Surface>
+
+// The whole surface is a link
+<Surface asChild elevation="raised" padding="sm">
+  <a href="/upgrade">Upgrade to Pro</a>
+</Surface>
+```
+
+## Composability
+- Server-safe — renders in RSC trees.
+- The base layer: `Card` = Surface + gap-model padding + color edge + header/content/footer slots. Reach for Card when you want that slot rhythm; reach for Surface for a plain elevated box.
+- `asChild` merges the surface classes onto your own element (a link, section, or `motion.div`) with no extra wrapper node.
+- Padding is symmetric all-side. For asymmetric or gap-model spacing, use Card or add your own utilities via `className`.
+
+## 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.
+
+## Changes
+### Unreleased
+- **Added** Initial release — `elevation` / `padding` / `radius` / `bordered` / `asChild`. The low-level surface primitive that Card and other surfaces compose.

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

@@ -1,20 +1,29 @@
 # Install: TanStack Start
 
-> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vinxi/Vite).
+> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vite).
+
+> **Updated 2026-07-10 for the Vite-plugin era.** TanStack Start moved off Vinxi: the package is now `@tanstack/react-start` (not `@tanstack/start`), config lives in `vite.config.ts` (not `app.config.ts`), and the app root is `src/` (not `app/`). If you are on an old Vinxi-based project (`app.config.ts`, `@tanstack/start`), migrate to the Vite plugin first — see the TanStack Start docs.
 
 ## 1. Detect
 
 You are in this recipe if:
 
-- `package.json` lists `"@tanstack/start"` and `"@tanstack/react-router"`
-- `app.config.{ts,js}` (Vinxi) exists at the project root
-- `app/router.tsx` and `app/routes/__root.tsx` exist
+- `package.json` lists `"@tanstack/react-start"` and `"@tanstack/react-router"`
+- `vite.config.{ts,js}` exists and uses the `tanstackStart` plugin from `@tanstack/react-start/plugin/vite`
+- `src/router.tsx` and `src/routes/__root.tsx` exist (a `src/routeTree.gen.ts` is generated on first run)
+
+If instead you see `app.config.ts` + `@tanstack/start`, that is the legacy Vinxi setup — this recipe does not apply until you migrate.
 
 ## 2. Install
 
 ```bash
+# pnpm
 pnpm add @devalok/shilp-sutra framer-motion
 pnpm add -D tailwindcss@^4 @tailwindcss/vite
+
+# npm
+npm install @devalok/shilp-sutra framer-motion
+npm install -D tailwindcss@^4 @tailwindcss/vite
 ```
 
 Optional:
@@ -38,39 +47,79 @@ Some components ship hard peers as optional. **Install BEFORE first import** or
 | `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
 | Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
 
-## 3. Wire Tailwind 4 in `app.config.ts`
+## 3. Wire Tailwind 4 in `vite.config.ts`
+
+Add `@tailwindcss/vite` to the existing plugins array. `tanstackStart()` must come before `viteReact()`; `tailwindcss()` can go first so tokens are processed early.
 
 ```ts
-import { defineConfig } from "@tanstack/start/config";
+import { defineConfig } from "vite";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import viteReact from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 
 export default defineConfig({
-  vite: {
-    plugins: [tailwindcss()],
-  },
+  plugins: [
+    tailwindcss(),
+    tanstackStart(),
+    viteReact(),
+  ],
 });
 ```
 
+Do **not** add a `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+
 ## 4. Wire tokens
 
-Create `app/styles/globals.css`:
+Create `src/styles/globals.css`:
 
 ```css
 @import "tailwindcss";
 @import "@devalok/shilp-sutra/css";
 ```
 
-Import it from `app/routes/__root.tsx`:
+Wire it as an asset-URL stylesheet from the root route's `head` (the TanStack Start idiom — the `?url` suffix emits the file as an asset instead of inlining it):
 
 ```tsx
-import "../styles/globals.css";
-```
+// src/routes/__root.tsx
+import {
+  createRootRoute,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import globalsCss from "../styles/globals.css?url";
 
-If you prefer asset-URL imports the way Remix does it, use `import css from "../styles/globals.css?url"` and add `<link rel="stylesheet" href={css} />` to the `<head>` returned by `__root.tsx`.
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+    ],
+    links: [{ rel: "stylesheet", href: globalsCss }],
+  }),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
 
 ## 5. Theme toggle
 
-Create `public/theme-bootstrap.js` (a static asset served verbatim):
+Add a pre-hydration bootstrap so there is no flash of the wrong theme. The cleanest place is a `scripts` entry on the root route (runs before hydration); a static `public/theme-bootstrap.js` referenced from `<head>` also works and is CSP-friendly.
+
+Static-asset approach — create `public/theme-bootstrap.js`:
 
 ```js
 (function () {
@@ -84,44 +133,36 @@ Create `public/theme-bootstrap.js` (a static asset served verbatim):
 })();
 ```
 
-Reference it from `app/routes/__root.tsx`:
+Reference it from the root route's `head` scripts:
 
 ```tsx
-import { createRootRoute, Outlet } from "@tanstack/react-router";
-
 export const Route = createRootRoute({
-  component: () => (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <script src="/theme-bootstrap.js" />
-      </head>
-      <body>
-        <Outlet />
-      </body>
-    </html>
-  ),
+  head: () => ({
+    // ...meta, links as above...
+    scripts: [{ src: "/theme-bootstrap.js" }],
+  }),
+  component: RootComponent,
 });
 ```
 
-For runtime toggling, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
+For runtime toggling inside components, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
 
 ## 6. Toaster (optional)
 
-Mount in `__root.tsx` next to `<Outlet />`:
+Mount once in `__root.tsx`'s `RootComponent`, next to `<Outlet />`:
 
 ```tsx
 import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
 
 // inside <body>
-<>
-  <Outlet />
-  <Toaster />
-</>
+<Outlet />
+<Toaster />
+<Scripts />
 ```
 
 ## 7. Verify
 
-Create or replace `app/routes/index.tsx`:
+Create or replace `src/routes/index.tsx`:
 
 ```tsx
 import { createFileRoute } from "@tanstack/react-router";
@@ -130,7 +171,11 @@ import { Stack } from "@devalok/shilp-sutra/ui/stack";
 import { Text } from "@devalok/shilp-sutra/ui/text";
 
 export const Route = createFileRoute("/")({
-  component: () => (
+  component: Home,
+});
+
+function Home() {
+  return (
     <Stack className="p-ds-08" gap="ds-04">
       <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
       <Stack direction="row" gap="ds-03">
@@ -138,21 +183,23 @@ export const Route = createFileRoute("/")({
         <Button variant="soft">Soft</Button>
       </Stack>
     </Stack>
-  ),
-});
+  );
+}
 ```
 
-Run `pnpm dev` and open the URL.
+Run `pnpm dev` and open the printed URL. Expected output matches [Next App Router § 7](./install-next-app-router.md#7-verify-the-install).
 
 ## 8. TanStack Start specifics
 
+- **No `transpilePackages` equivalent — and you do not need one.** TanStack Start's Vite resolves `@devalok/shilp-sutra` from `node_modules` as native ESM.
 - **Server functions** (`createServerFn`) — do not import shilp-sutra components inside server functions; they run server-only.
-- **Streaming SSR** is the default. All shilp-sutra components SSR cleanly because they have no client-only side effects at module top-level.
+- **Streaming SSR** is the default. Shilp Sutra components SSR cleanly (no client-only side effects at module top-level).
 - **`framer-motion` SSR** — animations gracefully degrade on the initial render.
-- **CSP.** The static `theme-bootstrap.js` asset complies with strict CSP (no inline scripts required).
+- **`routeTree.gen.ts` is generated** — do not edit it by hand; it regenerates on dev/build.
 
 ## 9. What NOT to do
 
-- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
-- ❌ Mount `<Toaster />` inside route components — it should live once at the `__root`.
-- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick one (Vite plugin recommended for TanStack Start).
+- ❌ Add a `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Use `@tanstack/start` / `app.config.ts` / `@tanstack/start/config` — that is the retired Vinxi setup. Current TanStack Start is `@tanstack/react-start` + `vite.config.ts`.
+- ❌ Mount `<Toaster />` inside route components — it lives once at the `__root`.
+- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick the Vite plugin.

package/llms.txt

@@ -1,6 +1,6 @@
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.45.1.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.47.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).
 
@@ -100,6 +100,7 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 - [stat-flash](docs/components/ui/stat-flash.md)
 - [status-dot](docs/components/ui/status-dot.md)
 - [stepper](docs/components/ui/stepper.md)
+- [surface](docs/components/ui/surface.md): The low-level elevated container primitive
 - [switch](docs/components/ui/switch.md)
 - [table](docs/components/ui/table.md)
 - [table-row-link](docs/components/ui/table-row-link.md)

package/make-kit/components/overview.md

@@ -144,8 +144,11 @@ Page wrapper?
 Vertical / horizontal stack?
   → <Stack direction="col|row" gap="ds-*">
 
-A card / panel?
-  → <Card> — surface-raised + shadow-raised
+A plain elevated box (no slots)?
+  → <Surface elevation="raised" padding="md"> — the low-level surface Card is built on
+
+A card / panel (header / content / footer rhythm)?
+  → <Card> — Surface + gap-model padding + slots
   → <Card variant="..."> — tinted by color prop
 
 A grid?
@@ -261,6 +264,7 @@ Code?
 |---|---|
 | Container | `/ui/container` |
 | Stack | `/ui/stack` |
+| Surface | `/ui/surface` |
 | Card | `/ui/card` |
 | AspectRatio | `/ui/aspect-ratio` |
 | Separator | `/ui/separator` |
@@ -305,4 +309,4 @@ Code?
 
 ## Per-component guides
 
-See `components/{button|card|input|dialog|badge|select|tabs|toast|form|table|dropdown-menu|popover|text|stack|icon}.md` for prop tables, examples, and rules.
+See `components/{button|card|surface|input|dialog|badge|select|tabs|toast|form|table|dropdown-menu|popover|text|stack|icon}.md` for prop tables, examples, and rules.

package/make-kit/components/surface.md

@@ -0,0 +1,60 @@
+# Surface
+
+```tsx
+import { Surface } from '@devalok/shilp-sutra/ui/surface'
+```
+
+The low-level elevated container. It paints a tokened surface — background + shadow + radius, with optional padding and border — and nothing else. Card, Popover, Toast, and Sheet are built on it.
+
+## 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`.
+
+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`.
+
+## Elevation — and which to pick
+
+| `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. |
+| `floating` | `bg-surface-overlay` + `shadow-floating` | Toasts, floating toolbars. |
+| `overlay` | `bg-surface-overlay` + `shadow-overlay` | Popovers, menus, dialogs. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `elevation` | `flat \| raised \| floating \| overlay` | `raised` | bg + shadow together. |
+| `padding` | `none \| sm \| md \| lg` | `none` | Simple all-side: 0 / 12 / 16 / 24px. Not Card's gap model. |
+| `radius` | `none \| control \| surface \| overlay \| pill` | `surface` | Maps `rounded-*` tokens. |
+| `bordered` | `boolean` | `false` | Border-led edge. Only for `flat` — see Rules. |
+| `asChild` | `boolean` | `false` | Render as the child element (Slot). |
+
+Plus all native `div` props. Server-safe; forwards ref.
+
+## Examples
+
+```tsx
+// Raised panel with padding
+<Surface elevation="raised" padding="md">…</Surface>
+
+// On-page, border-led tile (no shadow)
+<Surface elevation="flat" bordered padding="sm">…</Surface>
+
+// Overlay chrome
+<Surface elevation="overlay" padding="sm" radius="overlay">…</Surface>
+
+// The whole surface is a link — no wrapper node
+<Surface asChild elevation="raised" padding="sm">
+  <a href="/upgrade">Upgrade to Pro</a>
+</Surface>
+```
+
+## 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.
+- 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`.