@sableui/react 0.6.2 → 0.7.1

package/dist/foundations/motion.js

@@ -0,0 +1,135 @@
+// src/foundations/motion.ts
+var motion = {
+  slug: "motion",
+  title: "Motion",
+  summary: "Motion explains a change: where something came from, what responded, and that work is happening. It is subtle by default, built from named recipes, and one switch turns it off.",
+  headline: "4 slots \xB7 3 speeds \xB7 enter-only overshoot \xB7 1 kill switch",
+  vocabularies: [
+    {
+      title: "Three speeds",
+      note: "Match duration to the distance and size of what moves. Each value is multiplied by --motion-scale. Two edge steps sit outside the three: --motion-duration-instant (75ms) for a checkbox tick or tab swap, and --motion-duration-slower (500ms) for progress and value changes.",
+      terms: [
+        { name: "fast  --motion-duration-fast", value: "150ms", use: "Hover, press, focus, tooltips, small toggles. Also every exit." },
+        { name: "base  --motion-duration-base", value: "200ms", use: "Menus, popovers, tabs, disclosure. The default enter." },
+        { name: "slow  --motion-duration-slow", value: "300ms", use: "Dialogs, sheets, page-level transitions." }
+      ]
+    },
+    {
+      title: "Recipes",
+      note: "Reach for one named class before writing a transition.",
+      terms: [
+        { name: "motion-interactive", value: "fast \xB7 standard", use: "Hover/focus/press chrome on anything clickable. Replaces transition-colors." },
+        { name: "motion-press", value: "fast \xB7 scale settle", use: "Tactile press. Always paired with motion-interactive." },
+        { name: "motion-fade", value: "enter base / exit fast", use: "Scrims and backdrops." },
+        { name: "motion-pop", value: "enter base \xB7 spring", use: "Anchored or centred surfaces: popovers, menus, dialogs." },
+        { name: "motion-slide-{up,down,left,right}", value: "enter base / exit fast", use: "Directional surfaces: sheets, toasts." },
+        { name: "motion-disclosure", value: "base \xB7 standard", use: "Height changes: accordion, collapsible." },
+        { name: "motion-icon-swap", value: "enter \xB7 emphasized cross-fade", use: "Two icons of one control trading places: play/pause, outline/fill." },
+        { name: "motion-draw", value: "slower \xB7 decelerate", use: 'SVG line art drawing on when a <Reveal> scrolls in. The path needs pathLength="1"; stagger siblings with --motion-draw-delay.' },
+        { name: "motion-spin \xB7 pulse \xB7 shimmer \xB7 dot-bounce \xB7 ping", value: "loops", use: "Activity. Scale-aware, so reduced motion freezes them." }
+      ]
+    },
+    {
+      title: "Easings",
+      terms: [
+        { name: "ease-standard", value: "cubic-bezier(0.4, 0, 0.2, 1)", use: "The default for state changes." },
+        { name: "ease-decelerate", value: "cubic-bezier(0, 0, 0.2, 1)", use: "Entrances: arrive fast, settle slowly." },
+        { name: "ease-emphasized", value: "cubic-bezier(0.2, 0, 0, 1)", use: "Large surfaces covering a lot of distance." },
+        { name: "ease-spring", value: "~4% overshoot", use: "A gentle pop on enter. Never on exit." },
+        { name: "ease-bounce", value: "~10% overshoot", use: "A playful pop, opt-in only. Enter only, never on exit." }
+      ]
+    },
+    {
+      title: "The four slots",
+      note: "Every interactive component answers all four, by filling the slot or declining it with a reason in meta.motion.",
+      terms: [
+        { name: "arrival", value: "fade \xB7 slide \xB7 pop \xB7 Reveal", use: "How does it enter?" },
+        { name: "response", value: "motion-interactive \xB7 motion-press", use: "What happens under the pointer?" },
+        { name: "transition", value: "motion-disclosure \xB7 eased transform", use: "How does it move between its own states?" },
+        { name: "activity", value: "spin \xB7 pulse \xB7 shimmer", use: "How do you tell working from frozen?" }
+      ]
+    }
+  ],
+  rules: [
+    {
+      rule: "Every motion has a reason: orientation, feedback, continuity or activity.",
+      why: "Motion with no reason is latency. If you cannot say which of the four it serves, remove it."
+    },
+    {
+      rule: "Reach for a recipe first; drop to tokens only when none fits.",
+      why: "Recipes are reviewed once and respect the kill switch. A bespoke transition string is reviewed never.",
+      enforcedBy: "sable-lint: transition-colors, transition-all"
+    },
+    {
+      rule: "Exits are one step faster than entrances, and never overshoot.",
+      why: "Something leaving should get out of the way. A bounce on exit draws the eye to what the user just dismissed."
+    },
+    {
+      rule: "Animate opacity and transform only.",
+      why: "They run on the compositor. Width, height, top and left cause layout on every frame. motion-disclosure is the one sanctioned exception."
+    },
+    {
+      rule: "Durations come from tokens, so --motion-scale can stop them.",
+      why: "prefers-reduced-motion and <MotionProvider> off both set --motion-scale to 0. A raw duration ignores that.",
+      enforcedBy: "sable-lint: raw-duration, builtin-animate"
+    },
+    {
+      rule: "Interactive elements always respond. Something styled for hover with no motion recipe snaps.",
+      why: "A snap between states reads as broken. The four prohibitive rules could not catch missing motion, so this one does.",
+      enforcedBy: "sable-lint: static-interactive"
+    },
+    {
+      rule: "JS motion reads useMotion().enabled and does nothing when it is false.",
+      why: "Reduced motion is an accessibility setting, not a style preference."
+    }
+  ],
+  noGos: [
+    {
+      never: "Tailwind's animate-spin / animate-pulse / animate-ping / animate-bounce.",
+      instead: "motion-spin, motion-pulse, motion-ping, motion-dot-bounce.",
+      why: "The built-ins ignore --motion-scale, so reduced motion cannot freeze them.",
+      enforcedBy: "sable-lint: builtin-animate"
+    },
+    {
+      never: "duration-150, duration-300, or any raw duration utility.",
+      instead: "duration-(--motion-duration-fast) and siblings.",
+      why: "Raw durations bypass the kill switch.",
+      enforcedBy: "sable-lint: raw-duration"
+    },
+    {
+      never: "transition-all, or transition-colors on its own.",
+      instead: "motion-interactive, or name the properties you animate.",
+      why: "transition-all animates unrelated layout changes and defeats the browser's pre-computation.",
+      enforcedBy: "sable-lint: transition-all, transition-colors"
+    },
+    {
+      never: "Motion on first paint of static content, or staggered entrances on every list.",
+      instead: "Reveal for one deliberate moment per view.",
+      why: "Entrance choreography repeated everywhere becomes a loading delay."
+    },
+    {
+      never: "The motion library in the core package.",
+      instead: "src/motion (WAAPI, IntersectionObserver, View Transitions).",
+      why: "Sable's motion layer is zero-dependency; drag, FLIP and velocity springs belong in an optional adapter."
+    }
+  ],
+  details: [
+    {
+      title: "Hover that respects the kill switch",
+      before: '<button className="transition-colors duration-150 sable-surface-interactive">',
+      after: '<button className="motion-interactive sable-surface-interactive">',
+      why: "Same feel, but reduced motion now resolves it instantly."
+    },
+    {
+      title: "Faster exits",
+      before: "transition: opacity 200ms ease-in-out;  /* in and out */",
+      after: "data-[starting-style]: enter 200ms decelerate \xB7 data-[ending-style]: exit 150ms standard",
+      why: "motion-pop and motion-slide-* already do this; dismissing feels responsive instead of sluggish."
+    }
+  ],
+  related: ["accessibility", "sable docs reviewing-motion", "sable token motion"]
+};
+var motion_default = motion;
+export {
+  motion_default as default
+};

package/dist/foundations/scrolling.js

@@ -0,0 +1,62 @@
+// src/foundations/scrolling.ts
+var scrolling = {
+  slug: "scrolling",
+  title: "Scrolling",
+  summary: "Every scroll container declares a policy. Vertical regions get a quiet bar that appears only while you are in them; horizontal strips get edge fades instead of a rail.",
+  headline: "2 policies \xB7 vertical gets a bar \xB7 horizontal gets a fade",
+  vocabularies: [
+    {
+      title: "Policies",
+      terms: [
+        { name: "scrollbar-quiet", value: "4px thumb \xB7 hidden at rest \u2192 12% active \u2192 16% hovered \u2192 20% dragging", use: "The default for vertical scrolling. Grows to 6px under the pointer." },
+        { name: "scrollbar-hidden", value: "no bar", use: "Only when something else carries the affordance \u2014 and you can name it (an edge fade, paging controls)." },
+        { name: "<Scroller>", value: "edge fades + wheel mapping", use: "Horizontal strips: media rows, chip rows, tab overflow." },
+        { name: "useScrollActivity", value: "data-scrolling for ~600ms", use: "Lets the bar respond to touch drags and programmatic scrolls, which hover cannot see." }
+      ]
+    }
+  ],
+  rules: [
+    {
+      rule: "Every overflow-*-auto|scroll declares scrollbar-quiet or scrollbar-hidden.",
+      why: "Left bare, the platform draws its own: on Windows, stepper arrows hard against the padding edge that poke out of rounded corners.",
+      enforcedBy: "sable-lint: unmanaged-overflow (also checked over every registry example)"
+    },
+    {
+      rule: "Vertical regions get a bar; horizontal regions get an edge fade.",
+      why: "A vertical list needs position feedback. A horizontal strip needs 'there is more this way', which a fade says better than a 4px rail."
+    },
+    {
+      rule: "A horizontal region must work without a horizontal input.",
+      why: "Most mice have no horizontal wheel. Scroller maps the vertical wheel sideways and handles arrow keys, Home and End."
+    },
+    {
+      rule: "Reveal on scrolling, not only on hover.",
+      why: "Touch drags and programmatic scrolls (a chat following a reply) hover nothing, and those are the moments a reader needs to see where they are."
+    }
+  ],
+  noGos: [
+    {
+      never: "scrollbar-hidden on a vertical list with no fade or paging.",
+      instead: "scrollbar-quiet.",
+      why: "It leaves the reader with no sense of position and nothing to discover."
+    },
+    {
+      never: "A styled ::-webkit-scrollbar written per component.",
+      instead: "The scrollbar-quiet utility.",
+      why: "Chromium ignores ::-webkit-scrollbar once scrollbar-width is set; the utility handles both engines."
+    }
+  ],
+  details: [
+    {
+      title: "A scrolling panel",
+      before: '<div className="overflow-y-auto">',
+      after: '<div className="overflow-y-auto scrollbar-quiet" ref={useScrollActivity()}>',
+      why: "No bar at rest; it appears while scrolling, hovered or focused, and fades a beat after. Content cut off at the edge is what says the region scrolls."
+    }
+  ],
+  related: ["surfaces", "accessibility", "sable component Scroller"]
+};
+var scrolling_default = scrolling;
+export {
+  scrolling_default as default
+};

package/dist/foundations/shape.js

@@ -0,0 +1,113 @@
+// src/foundations/shape.ts
+var shape = {
+  slug: "shape",
+  title: "Shape",
+  summary: "Radius signals what something is: tight on containers, full on actions. Nested corners stay concentric, and one edge treatment marks a boundary.",
+  headline: "7 radius steps \xB7 concentric nesting \xB7 1 edge treatment per boundary",
+  vocabularies: [
+    {
+      title: "The radius ladder",
+      note: "Each step is 4px apart, so common insets land on a real step. Themes and the customizer retune every step together.",
+      terms: [
+        { name: "rounded-none", value: "0", use: "Full-bleed media." },
+        { name: "rounded-xs", value: "4px", use: "Tags, kbd, small inline marks." },
+        { name: "rounded-sm", value: "8px", use: "Inputs, menu items, list rows." },
+        { name: "rounded-md", value: "12px", use: "Popovers, menus, toasts." },
+        { name: "rounded-lg", value: "16px", use: "Cards, dialogs, sheets." },
+        { name: "rounded-xl", value: "20px", use: "Hero surfaces." },
+        { name: "rounded-full", value: "pill", use: "Buttons (via --button-radius), avatars, pills, dots." }
+      ]
+    },
+    {
+      title: "Edges",
+      terms: [
+        { name: "border-border", value: "hairline", use: "The default edge: inputs, cards, badges." },
+        { name: "border-border-strong", value: "hairline, higher contrast", use: "Structural rules: table grids, section separators." },
+        { name: "border-border-floating", value: "faint, alpha", use: "Every floating surface: popovers, menus, selects, tooltips, dialogs, sheets, toasts. Lighter than border; the shadow carries the elevation." },
+        { name: "ring-2 ring-ring", value: "2px focus ring", use: "Focus only. Never a thick border." }
+      ]
+    }
+  ],
+  rules: [
+    {
+      rule: "Nested corners are concentric: inner radius = outer radius \u2212 inset. Write it as rounded-concentric-<outer>/<inset>, not a hardcoded step.",
+      why: "A 12px popover with 4px padding takes 8px items. The utility computes the subtraction from the live tokens, so the pair stays concentric when a theme or the customizer rescales the radius ladder; a hardcoded rounded-sm drifts."
+    },
+    {
+      rule: "A list of rows inside a rounded popup uses popup-inset on the popup, rounded-popup-item on the rows and popup-bleed on a separator.",
+      why: "All three derive from the popup's radius: the inset grows to a third of it (never below --spacing(1), so density moves it too), the rows take what is left after the inset and the 1px border, and a separator bleeds by exactly the inset. A rounder look gets more room instead of rows that round into pills; the default ladder lands on a 4px inset and 7px rows.",
+      enforcedBy: "sable-lint: popup-separator-bleed"
+    },
+    {
+      rule: "A Button, Pill or Badge gets its look from a variant, never from override classes.",
+      why: `border, bg, rounded, ring and shadow classes on a component fight the variant's own hover, selected and focus states, and give one call site a look no other site can ask for. Use the variant that exists (Button variant="floating" over content, "on-color" on a fill; Pill appearance="outline"; Badge appearance and tone) or add one to the component.`,
+      enforcedBy: "sable-lint: component-restyle"
+    },
+    {
+      rule: "The outer radius is always at least the inner radius.",
+      why: "If the inset is larger than the outer radius, square the inner element or step the container up."
+    },
+    {
+      rule: "Never mix radii within one component.",
+      why: "A component reads as one object when its corners agree."
+    },
+    {
+      rule: "Actions are full; containers are tight.",
+      why: "The contrast itself says 'this is a control'. A theme flattens buttons through --button-radius, not by editing each one."
+    },
+    {
+      rule: "High-contrast outlines (selection, emphasis) are inset rings; hairline chrome is a border.",
+      why: "Rings anti-alias on rounded corners at any display scale; a 1px light border on dark snaps to the pixel grid and looks jagged."
+    },
+    {
+      rule: "One edge treatment per boundary: a border, a ring or a shadow.",
+      why: "Stacking all three makes an edge heavier than the content it holds."
+    },
+    {
+      rule: "Prefer a tonal step or space over a divider line.",
+      why: "The flattest thing that reads is best."
+    }
+  ],
+  noGos: [
+    {
+      never: "rounded-[10px] or any off-ladder radius.",
+      instead: "The ladder step for the role.",
+      why: "Off-ladder radii cannot follow a theme or the customizer's radius control."
+    },
+    {
+      never: "A card inside a card with the same radius.",
+      instead: "Flatten the inner one, or use rounded-concentric-*.",
+      why: "Nested surfaces with equal corners look misaligned at every corner."
+    },
+    {
+      never: '<Button className="rounded-full">, <Pill className="border bg-card">, a -mx-1 separator in a popup.',
+      instead: "The component's variant (add one if it is missing); popup-bleed for the separator.",
+      why: "An override fights the component's own states and does not follow the radius ladder, the density or a theme.",
+      enforcedBy: "sable-lint: component-restyle, popup-separator-bleed"
+    },
+    {
+      never: "border-2 for emphasis or focus.",
+      instead: "ring-2 ring-ring for focus; a tonal fill for emphasis.",
+      why: "A thick border shifts layout and competes with the focus ring."
+    }
+  ],
+  details: [
+    {
+      title: "Crisp selected outlines on dark surfaces",
+      before: '<button className="rounded-lg border border-foreground">',
+      after: '<button className="rounded-lg ring-[1.5px] ring-foreground ring-inset">',
+      why: "A 1px high-contrast border on a rounded corner snaps unevenly at fractional device-pixel ratios (Windows 125%/150%) and reads as jagged, worst light-on-dark. A box-shadow ring is anti-aliased instead, and inset keeps it from changing the element's size. Keep hairline borders for low-contrast chrome, where the snapping is invisible."
+    },
+    {
+      title: "Concentric menu items",
+      before: '<div className="rounded-md p-1"><div className="rounded-md">Item</div></div>',
+      after: '<div className="rounded-md popup-inset"><div className="rounded-popup-item">Item</div></div>',
+      why: "12px outer \u2212 4px inset = 8px inner at the default ladder, and the utilities keep the subtraction right when a preset or the customizer rescales the radius or the density."
+    }
+  ],
+  related: ["surfaces", "spacing", "sable token radii"]
+};
+var shape_default = shape;
+export {
+  shape_default as default
+};

package/dist/foundations/spacing.js

@@ -0,0 +1,121 @@
+// src/foundations/spacing.ts
+var spacing = {
+  slug: "spacing",
+  title: "Spacing & sizing",
+  summary: "One 4px scale governs every gap, inset and size, and space is assigned by role. Controls read a height ladder that a density scope can retune all at once.",
+  headline: "4px base \xB7 8px rhythm \xB7 3 roles \xB7 1 control ladder",
+  vocabularies: [
+    {
+      title: "Spacing by role",
+      note: "Steps below 2 (8px) are optical correction only.",
+      terms: [
+        { name: "Inset  p-4", value: "16px", use: "Padding inside a surface. p-3 for a dense card, px-3 py-2 for a row." },
+        { name: "Stack, within a group  gap-1.5 \u2013 gap-2", value: "6\u20138px", use: "Label to field, title to description." },
+        { name: "Stack, between groups  gap-4 \u2013 gap-6", value: "16\u201324px", use: "Field to field, card to card." },
+        { name: "Stack, between sections  gap-12+", value: "48px+", use: "Major regions of a page." },
+        { name: "Inline  gap-2 \u2013 gap-3", value: "8\u201312px", use: "Icon to label, control to control." }
+      ]
+    },
+    {
+      title: "The control ladder",
+      note: 'Comfortable values; data-density="compact" (or <Density>) redefines every step for a region.',
+      terms: [
+        { name: "h-(--control-xs)", value: "28px \xB7 compact 24", use: "Inline chips, tree rows." },
+        { name: "h-(--control-sm)", value: "32px \xB7 compact 28", use: "Compact buttons, toolbar controls." },
+        { name: "h-(--control-md)", value: "40px \xB7 compact 32", use: "The default: inputs, buttons, selects, menu triggers." },
+        { name: "h-(--control-cta)", value: "44px \xB7 compact 36", use: "The primary call to action; clears the touch floor on its own." },
+        { name: "h-(--control-lg)", value: "48px \xB7 compact 40", use: "Prominent or touch-first actions." }
+      ]
+    },
+    {
+      title: "Icons and touch",
+      terms: [
+        { name: "text-base (16px)", value: "sm", use: "Inline with label-md / body-sm." },
+        { name: "text-xl (20px)", value: "md \xB7 default", use: "The default UI glyph beside label-lg." },
+        { name: "hit-target", value: "44\xD744px", use: "Keeps a visually small control's hit area at the WCAG floor without moving layout." }
+      ]
+    }
+  ],
+  rules: [
+    {
+      rule: "Every margin, padding and gap is a step on the 4px scale.",
+      why: "Off-scale values break the rhythm that lets adjacent components line up without coordination."
+    },
+    {
+      rule: "Padding, gaps and insets in a component sit on the spacing scale: a step (p-4, gap-2) or --spacing(n) inside an arbitrary value (p-[var(--card-p,--spacing(6))]).",
+      why: 'The density (Character) control works by retuning --spacing, so anything on the scale moves with it. A literal p-[1.5rem] or padding: "12px" stays put while everything around it tightens. Keep fixed rem/px for what must not scale: a 1px hairline, a ring width.',
+      enforcedBy: "design-lint: fixed-spacing (library source)"
+    },
+    {
+      rule: "Related things sit closer than unrelated things.",
+      why: "Proximity groups content without a divider line. Use space first; reach for a border only when space is not enough."
+    },
+    {
+      rule: "Space lives on the container (gap), not on children (margins).",
+      why: "gap survives reordering, conditional children and RTL; per-child margins do not."
+    },
+    {
+      rule: "Control heights read the --control-* ladder.",
+      why: "A density scope retunes every control at once. A hardcoded height has to be found and overridden by hand.",
+      enforcedBy: "sable-lint: raw-control-height"
+    },
+    {
+      rule: "Single-column content inside a card stacks with flex flex-col and a gap, not CSS grid.",
+      why: "A grid track sizes to its widest min-content child, so one long unbreakable string (a URL, a code line, a table) blows the column out past the card. A flex column lets children shrink to the card."
+    },
+    {
+      rule: "A compact surface drops one whole step; a spacious one adds one.",
+      why: "Moving in whole steps keeps density changes proportional."
+    },
+    {
+      rule: "Every interactive element clears a 44\xD744px hit area.",
+      why: "WCAG 2.5.5. Use padding or hit-target to grow the hit area; never a bigger glyph."
+    },
+    {
+      rule: "Borderless controls get roughly twice the gap of bordered ones.",
+      why: "A border declares where a control ends. Two ghost buttons 12px apart read as one target."
+    }
+  ],
+  noGos: [
+    {
+      never: "Arbitrary values: p-[15px], gap-[7px], mt-[13px].",
+      instead: "The nearest scale step.",
+      why: "Arbitrary values cannot follow density or a customized scale."
+    },
+    {
+      never: "h-[40px] on a control.",
+      instead: "h-(--control-md).",
+      why: "It will not follow <Density>.",
+      enforcedBy: "sable-lint: raw-control-height"
+    },
+    {
+      never: "Icons sized with type utilities (text-body-md on an <Icon>).",
+      instead: "text-{size} scale classes.",
+      why: "Type utilities carry line-height and tracking that misalign glyphs."
+    },
+    {
+      never: "A fixed width sized to an English label.",
+      instead: "padding-inline and max-width with wrapping.",
+      why: "German and Finnish run 30\u201350% longer."
+    }
+  ],
+  details: [
+    {
+      title: "A dense region in one attribute",
+      before: '<div className="[&_button]:h-8 [&_input]:h-8">\u2026</div>',
+      after: '<Density value="compact">\u2026</Density>',
+      why: "Every control, menu and popup inside retunes, including portaled overlays."
+    },
+    {
+      title: "Grouping by space",
+      before: "<Separator /> between every field",
+      after: "<Stack gap={3}> between groups (24px), <Stack gap={1}> inside a group (8px)",
+      why: "Two spacing steps do the work of every divider, with less ink. Stack's numeric gap counts --rhythm-unit \u2014 two spacing steps \u2014 so it follows the density control like every other spacing value."
+    }
+  ],
+  related: ["shape", "typography", "sable docs building-a-tool", "sable token layout"]
+};
+var spacing_default = spacing;
+export {
+  spacing_default as default
+};

package/dist/foundations/surfaces.js

@@ -0,0 +1,107 @@
+// src/foundations/surfaces.ts
+var surfaces = {
+  slug: "surfaces",
+  title: "Surfaces & elevation",
+  summary: "Depth is a step up the surface ladder, chosen by how transient a surface is. Dark mode lifts with lighter tones and edge light; light mode adds soft shadows.",
+  headline: "4 surface tokens \xB7 5 elevation roles \xB7 1 shadow per surface \xB7 1 layer scale",
+  vocabularies: [
+    {
+      title: "The surface ladder",
+      terms: [
+        { name: "bg-background", value: "the page", use: "The document body; the furthest-back surface." },
+        { name: "bg-card", value: "+1 step", use: "Resting containers: cards, panels, dialogs." },
+        { name: "bg-muted", value: "+1 step, quieter", use: "Wells, code blocks, inactive fills inside a card." },
+        { name: "bg-popover", value: "+2 steps", use: "Anything that floats: menus, popovers, selects, tooltips. Always distinct from card, so a menu in a dialog never melts into it." },
+        { name: "bg-overlay", value: "scrim", use: "Behind modals, and pills over imagery." }
+      ]
+    },
+    {
+      title: "Elevation by role",
+      note: "Raise by transience \u2014 how much a surface floats over content \u2014 not by importance.",
+      terms: [
+        { name: "Resting", value: "no shadow", use: "Page content and flat cards. A hairline border if it needs an edge." },
+        { name: "Raised  shadow-sm", value: "subtle", use: "A draggable card, a sticky header over scrolled content." },
+        { name: "Floating  shadow-md", value: "anchored", use: "Menus, popovers, selects, dropdowns." },
+        { name: "Modal  shadow-lg", value: "with scrim", use: "Dialogs, sheets, the command menu." },
+        { name: "Top  shadow-xl", value: "rare", use: "The toast stack." }
+      ]
+    },
+    {
+      title: "Layers",
+      terms: [
+        { name: "z-(--z-sticky)", value: "30", use: "Sticky in-content chrome: table headers." },
+        { name: "z-(--z-nav)", value: "40", use: "App chrome: header, sidebar, bottom nav." },
+        { name: "z-(--z-overlay)", value: "50", use: "Every portaled transient surface." },
+        { name: "z-(--z-toast)", value: "60", use: "Toasts, above modals." },
+        { name: "z-(--z-skip-link)", value: "100", use: "The skip link, above everything." }
+      ]
+    }
+  ],
+  rules: [
+    {
+      rule: "Pick the elevation role, not a shadow value.",
+      why: "Elevation is a five-step system. A custom box-shadow cannot follow a theme or the light/dark split."
+    },
+    {
+      rule: "Floating surfaces use bg-popover, resting ones bg-card. Anything with shadow-md or above floats: menus, popovers, selects, tooltips, dialogs, sheets, toasts, a floating panel.",
+      why: "In dark mode popover is guaranteed lighter than card, so a menu opened inside a dialog always reads as on top of it. In light mode several presets make background, card and popover the same colour, so the fill alone never carries elevation.",
+      enforcedBy: "themes.test.ts + sable-lint: floating-surface"
+    },
+    {
+      rule: "A floating surface's edge is border-border-floating (or ring-border-floating), never the full border-border. The shadow carries the elevation.",
+      why: "A full hairline plus a shadow stacks into a heavy dark outline. border-floating is a faint alpha edge: it defines the shape against a same-coloured page in light mode and reads as a lit edge in dark mode, where shadows barely show.",
+      enforcedBy: "sable-lint: floating-surface"
+    },
+    {
+      rule: "A recessed area inside a surface (a segmented-control track, a pad, a preview well) is sable-well, and it takes no outline. Whatever sits on the well takes the surface's own colour back (bg-popover inside a popover).",
+      why: "sable-well mixes a fixed amount of ink into the surface it sits in, so it is the same visible step on the page, in a card or in a floating panel, in every theme and mode. A fixed bg-muted can nearly vanish inside a popover in dark mode, and adding an outline to every well to compensate stacks a panel into boxes."
+    },
+    {
+      rule: "One shadow per surface; never a heavy shadow with a heavy border.",
+      why: "Stacked depth cues read as decoration rather than position."
+    },
+    {
+      rule: "Do not elevate a static section to make it stand out.",
+      why: "Elevation means 'this floats'. Use a tonal step or space for emphasis."
+    },
+    {
+      rule: "For modals, the scrim is the primary depth cue.",
+      why: "The scrim is what tells the user the page behind is inert; the shadow is secondary."
+    },
+    {
+      rule: "Stack with the named layer scale.",
+      why: "Overlays portal to the end of body and order themselves by open order; the layer only has to clear in-flow chrome."
+    }
+  ],
+  noGos: [
+    {
+      never: "z-[9999] or any raw z-index.",
+      instead: "z-(--z-overlay) and the other named layers.",
+      why: "Raw z-indexes become a bidding war that a future overlay always loses.",
+      enforcedBy: "sable-lint: raw-z-index"
+    },
+    {
+      never: "shadow-[0_8px_30px_rgba(0,0,0,.2)] or any custom shadow.",
+      instead: "shadow-sm \u2026 shadow-xl by role.",
+      why: "Custom shadows ignore the theme's light/dark elevation recipes."
+    },
+    {
+      never: "bg-card on a popover, or bg-popover on a resting card.",
+      instead: "Match the token to the role.",
+      why: "Swapping them is how floating surfaces melt into the surface beneath."
+    }
+  ],
+  details: [
+    {
+      title: "A menu inside a dialog",
+      before: "Dialog bg-card \xB7 Menu bg-card \u2014 identical in dark mode",
+      after: "Dialog bg-card \xB7 Menu bg-popover \u2014 one step lighter, plus edge light",
+      why: "The menu reads as above the dialog without any prop."
+    }
+  ],
+  related: ["shape", "sable docs token-intent"]
+};
+var surfaces_default = surfaces;
+export {
+  surfaces_default as default
+};