@tanishqkancharla/maui 0.0.70 → 0.0.72

package/dist/components/Button.js

@@ -225,7 +225,7 @@ const coloredButtonClass = memoize((variant, color) => {
     }
     const scale = paletteFill(color);
     if (variant === "primary") {
-        return primaryClass(scale[9], darkTextOnSolid.has(color) ? scale[12] : "white", paletteAlpha(color)[6]);
+        return primaryClass(scale[9], darkTextOnSolid.has(color) ? onSolidText(scale[9]) : "white", paletteAlpha(color)[6]);
     }
     return quietClass(scale[11], scale[12], variant === "quiet" ? paletteAlpha(color)[9] : undefined);
 });

package/dist/components/ListBox.js

@@ -32,9 +32,12 @@ const item = style(spacing.padding({ x: 4, y: 2 }), text({ size: "sm", fontWeigh
         background: backgroundColor.elementHover,
     },
     "&[data-selected]": {
-        color: colors.accent[9],
+        color: colors.accent[11],
         fontWeight: 500,
     },
+    "&[data-selected]:not([data-disabled]):is(:hover, [data-hovered], [data-focused])": {
+        color: colors.accent[12],
+    },
     "&[data-selected]::after": {
         content: '"✓"',
         position: "absolute",

package/dist/components/Table.js

@@ -69,7 +69,7 @@ const row = style({
     "&[data-selection-mode][data-selected] td": {
         backgroundColor: colors.accent[3],
     },
-    "&[data-disabled]": {
+    "&[data-disabled] td": {
         color: colors.gray[8],
     },
 });
@@ -105,11 +105,11 @@ const selectionCheck = style({
     height: "10px",
     paddingTop: "0.5px",
     paddingLeft: "0.5px",
-    fill: colors.gray[3],
+    fill: "white",
     opacity: 0,
     transform: "scale(0)",
 });
-const selectionCheckbox = style(flex({ alignItems: "center", justifyContent: "center" }), focusRing(`&[data-focus-visible] ${selectionBox}`, shadowVars.control), {
+const selectionCheckbox = style(flex({ alignItems: "center", justifyContent: "center" }), focusRing(`&[data-focus-visible] ${selectionBox}`, shadowVars.control), focusRing(`&[data-selected][data-focus-visible] ${selectionBox}, &[data-indeterminate][data-focus-visible] ${selectionBox}`, shadowVars.selectedControl), {
     position: "relative",
     width: "fit-content",
     cursor: "default",
@@ -129,6 +129,7 @@ const selectionCheckbox = style(flex({ alignItems: "center", justifyContent: "ce
     },
     [`&[data-selected] ${selectionBox}, &[data-indeterminate] ${selectionBox}`]: {
         backgroundColor: colors.accent[9],
+        boxShadow: shadowVars.selectedControl,
     },
     [`&[data-hovered][data-selected] ${selectionBox}, &[data-hovered][data-indeterminate] ${selectionBox}`]: {
         backgroundColor: surfaceWash(colors.gray[12], surfaceMixPercent.hover, colors.accent[9]),

package/dist/components/navigationItem.js

@@ -13,7 +13,10 @@ export const navigationItem = style(spacing.padding({ x: 4, y: 2 }), text({ size
         background: backgroundColor.elementHover,
     },
     "&[aria-current='page']": {
-        color: colors.accent[9],
+        color: colors.accent[11],
         fontWeight: 500,
     },
+    "&[aria-current='page']:hover": {
+        color: colors.accent[12],
+    },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tanishqkancharla/maui",
-	"version": "0.0.70",
+	"version": "0.0.72",
 	"description": "Maui design system",
 	"type": "module",
 	"main": "./dist/maui.js",

package/skills/maui/references/components/buttons.md

@@ -29,16 +29,16 @@ Styled React Aria `Button` (default `type="button"`). Consumes `ButtonContext`,
 | `variant` | `"default"` (raised element) \| `"quiet"` (transparent, hover wash) \| `"text"` (transparent, color-only hover) \| `"primary"` (solid fill) |
 | `variantColor` | Palette name or opaque `#hex` / `rgb(...)`. Primary defaults to `"accent"`; quiet and text default to gray and tint the label/icon when set |
 | `isDisabled` | React Aria name. Maps to native `disabled`. **No `disabled` React prop** |
-| `isPending` | Shows a current-color indicator beside visible content: `xs` (14px) by default, `2xs` (12px) for small buttons, with equal leading/top/bottom insets. Crossfades content and resizes over 150ms in both directions; reduced motion switches instantly. Blocks activation immediately and suppresses hover fill, retaining focusability and variant color. Controlled by the caller, not by returned promises |
+| `isPending` | Shows a current-color indicator beside visible content. Blocks activation and suppresses hover fill while retaining focusability and variant color. Controlled by the caller, not by returned promises |
 | `pendingLabel` | Optional visible string replacing children while pending (e.g. `"Saving…"`). Omit to keep children; provide it to replace an icon with progress text |
 | `onClick` | Still supported. React Aria also exposes `onPress` |
 | `children` | Text is wrapped for cap-height trim; SVG icons sit beside text. Icon-only needs `aria-label` |
 
-Primary: fill step 9, light text (`onAccent`, or step 12 on amber/lime/mint/sky/yellow). Custom CSS fill drops alpha; text is white or near-black from lightness. The fill is a diagonal gradient (`to top left`) from the fill shifted by OKLCH `l − 0.027`, `c × 1.05`, `h − 6.8` to the fill itself. In dark mode the shadow has a 0.5px white top highlight at 15% (`shadow.control` uses 9%); light mode has none. The shadow tints a soft lift from the fill, at half strength in dark mode, and adds a 0.5px edge painted beneath the lift: the fill color’s alpha step 6 in light mode (a custom CSS fill uses the fill at 35%); in dark mode a near-black tint of the fill (OKLCH lightness 0.18, half chroma) — no neutral gray. Hover layers a white-to-transparent sheen over the gradient; disabled drops the gradient. Quiet: no fill; `variantColor` tints the label/icon. Hover/press mix `grayAlpha[9]` (or that color’s alpha 9, or the hex) into transparent at 6% light / 9% dark; press is 2×. Hover fills snap.
+Use primary for an emphasized action, default for a raised neutral control, quiet for a low-emphasis action, and text for an inline-style action without a hover fill. Let Button manage its palette and state colors rather than rebuilding the fill or shadow. For exact treatment, inspect `src/components/Button.tsx` in the installed package as described in [design conventions](../design_conventions.md).
 
-While a menu or overlay is open, the trigger keeps the active fill via RAC `data-pressed` / `aria-expanded` (same tokens as `:active`: `elementActive`, or primary step 10).
+Prefer plain labels (optionally alongside icons) so Button controls their foreground; see the [composition rule](../design_conventions.md#composition).
 
-Text: zero padding in both sizes, including icons and pending content; retains the control height and focus ring. No background or resting shadow. Only the label/icon color changes on hover (palette step 11 → 12, or a darker custom color). Disabled and pending suppress hover changes.
+The text variant removes horizontal spacing and surface chrome while keeping the control height and focus ring. Use it when an action should align directly with surrounding text; hover changes the foreground, not the fill.
 
 `useButton(props)` is exported for custom focus-tracked buttons; prefer `Button`.
 

package/skills/maui/references/components/menu.md

@@ -23,7 +23,7 @@ Exactly two children on `MenuTrigger`: **trigger**, then **menu**. Use Maui `But
 </MenuTrigger>
 ```
 
-`isDisabled` on the trigger button blocks open. Escape closes and focus returns to the trigger (`aria-expanded` tracks open state). While open, the Maui `Button` keeps its active fill from RAC `data-pressed` / `aria-expanded`.
+`isDisabled` on the trigger button blocks open. Escape closes and focus returns to the trigger (`aria-expanded` tracks open state).
 
 `placement` defaults to `"bottom start"`. Popover uses `shadow.strong` via `CollectionPopover`.
 

package/skills/maui/references/design_conventions.md

@@ -1,6 +1,6 @@
 # Maui design conventions
 
-Prefer the Maui skill for composition knowledge: how to assemble tokens, components, patterns, and apps. Read every matching reference linked from `SKILL.md` before designing or implementing UI, and reuse its structure, tokens, and interactions. Reach for package source under `"maui/src/patterns"`, `"maui/src/apps"`, or an installed `node_modules` package only when the references do not cover a needed detail.
+Use the matching skill references for Maui's design choices, composition rules, and reusable token patterns. Inspect the installed package's source for tactical questions about props, defaults, state styling, or exact values. Source ships under `node_modules/maui/src/` with the documented npm alias, or `node_modules/@tanishqkancharla/maui/src/` without it. Follow components into their token definitions as needed; current implementation is not a guarantee of contrast or design intent.
 
 Patterns, demo apps, and the gallery `Panel` preview frame are not package components. `Panel` is not on the `"maui"` barrel, in `src/components`, or in the JSX editor catalog. Rebuild reference recipes with barrel exports such as `Button`, `Flex`, and `text(...)`.
 
@@ -24,30 +24,59 @@ State styles key off React Aria attributes (`data-hovered`, `data-selected`, `da
 
 ## Composition
 
-- Use Maui's `Text` component instead of raw `<span>` elements for inline text. Set typography through its `size`, `fontWeight`, `color`, `monospace`, and `tabular` props; see [Text](components/text.md). Keep semantic elements such as headings, paragraphs, labels, and links for their respective roles.
+- Use Maui's `Text` component for standalone inline typography; see [Text](components/text.md). `Text` and `text(...)` set an explicit color by default, overriding inherited variant, selected, or disabled colors. Prefer plain Button labels so the Button controls its foreground. Keep semantic elements such as headings, paragraphs, labels, and links for their respective roles.
 - Hover backgrounds have no transitions. Hover fills such as `backgroundColor.elementHover`, quiet-button washes, and list or row highlights snap instantly. Do not animate `background` or `background-color` on hover with `motion.standard(...)` or a CSS `transition`. Other motion, including tooltips and transforms, is allowed.
 - Simple apps default to a prose column: `style(proseContainerStyle, { width: "100%", marginInline: "auto" })`. `sizing.contentWidth` is that same style. Use it for single-column tools, settings, forms, and reading layouts. Multi-pane or full-bleed apps such as inboxes, calendars, and IDEs are exceptions.
 - Design an intentional empty composition for every list, inbox, search result, or collection. Include copy and, when useful, an action. Do not leave a blank panel.
 
+## Decorative edge strips
+
+When a rounded surface uses a colored edge for emphasis, use a full-height rectangular strip inside a `position: relative; overflow: hidden` container. Keep the radius on the container, not the strip: a CSS left border follows the corners and curls inward. This is a composition recipe for custom UI, not a new component or a change to existing component borders. Keep using `border()` for outlines and dividers.
+
+```tsx
+const surface = style(radius.md, spacing.padding({ all: 6 }), {
+	position: "relative",
+	overflow: "hidden",
+	backgroundColor: colors.orange[3],
+})
+const strip = style({
+	position: "absolute",
+	insetBlock: 0,
+	left: 0,
+	width: "3px",
+	backgroundColor: colors.orange[9],
+	pointerEvents: "none",
+})
+
+function DecoratedSurface() {
+	const surfaceClass = useStyles(surface)
+	const stripClass = useStyles(strip)
+	return (
+		<div className={surfaceClass}>
+			<div aria-hidden="true" className={stripClass} />
+			<Text>Surface content</Text>
+		</div>
+	)
+}
+```
+
 ## Shadows
 
-Use `shadow.control` for interactive control surfaces. It combines two inset
-highlights with a compact outer edge. Use the three-level elevation scale for
-other raised surfaces:
+Use `shadow.control` for interactive control surfaces. Use the three-level elevation scale for other raised surfaces:
 
 - `shadow.subtle` — cards and ordinary raised surfaces
-- `shadow.medium` — tooltips and larger floating panels
+- `shadow.medium` — larger floating panels
 - `shadow.strong` — dropdowns, popovers, and dominant overlays
 
-All three include a 1px ring. Do not also apply `border()`, `borderColor.outline`, or another ring to the same element.
+These shadows include their own edge or ring. Do not also apply `border()`, `borderColor.outline`, or another ring to the same element. Not every floating component uses elevation: reuse its exported styles rather than inferring a shadow from its placement.
 
 Buttons and form-control surfaces use `shadow.control` by default. For compound controls, apply it once to the outer control boundary instead of to every internal button or segment.
 
 ## Focus
 
-`focusRing()` applies a theme-aware Radix blue shadow with a `blueAlpha[8]` hard edge and `blueAlpha[5]` glow. Do not add a competing outline or box shadow for keyboard focus.
+Use `focusRing()` for Maui's theme-aware keyboard-focus treatment rather than adding a competing outline or box shadow.
 
-**Control safe area.** Input and form-control shadows paint outside the component's layout box; reserve room for the resting, hovered, and keyboard-focused states, even when hover does not change the background. The focus treatment includes a 1px ring and a 6px blur. Use `spacing.padding(4)` (9px) as a practical safe inset between controls and clipping edges, and leave gaps between neighboring controls. Keep overflow visible on immediate wrappers; when a panel, rounded container, or scroll viewport must clip, put the safe inset inside that clipping boundary, not outside it as margin. Check the first and last controls at scroll edges, including checkbox, radio, switch, and slider focus states. Do not remove shadows or focus rings to fit a tight layout.
+**Control safe area.** Input and form-control shadows paint outside the component's layout box; reserve room for the resting, hovered, and keyboard-focused states, even when hover does not change the background. Use `spacing.padding(4)` as a starting inset between controls and clipping edges, and leave gaps between neighboring controls. Keep overflow visible on immediate wrappers; when a panel, rounded container, or scroll viewport must clip, put the safe inset inside that clipping boundary, not outside it as margin. Check the first and last controls at scroll edges, including checkbox, radio, switch, and slider focus states. Do not remove shadows or focus rings to fit a tight layout.
 
 ```tsx
 // Keep the control's visual overflow inside the scrolling boundary.
@@ -61,7 +90,7 @@ Buttons and form-control surfaces use `shadow.control` by default. For compound
 
 ## Layout utilities
 
-`Flex` and `Gap` take spacing scale steps (`1 | 2 | 3 | 4 | 6 | 8 | 12 | 16`), not raw pixels. For example, `<Flex row gap={4} padding={4}>` has a 9px gap and 9px inset.
+`Flex` and `Gap` take spacing scale steps, not raw pixels. For example, `<Flex row gap={4} padding={4}>` uses the same token for its gap and inset.
 
 Put padding on `Flex` with `padding` or `p`, `px`, `py`, `pt`, `pr`, `pb`, and `pl`; there is no `Padding` component. `alignItems` and `justifyContent` use the same tokens as `flex()` (`start`, `center`, `end`, and others; `justifyContent` also supports `between`, `around`, and `evenly`). `background` is a surface token such as `app`, `element`, or `accent`. `Spacer` grows to fill leftover flex space. `Divider` is a horizontal rule.
 

package/skills/maui/references/tokens.md

@@ -56,12 +56,14 @@ function Row({ children }: { children: React.ReactNode }) {
 
 `colors` is Radix Scales with a brand `accent` (teal in light, violet in dark). Each scale has steps **1–12**. Alpha scales are `colors.grayAlpha`, `colors.accentAlpha`, `colors.blueAlpha`, …
 
+The scale roles below are a starting point, not a contrast guarantee or a state recipe for every component. Use text roles for labels rather than copying a solid fill's step. Check the actual foreground/background pair in light and dark themes, including selected and disabled states; preserve non-color cues for state and status.
+
 | Steps | Use |
 | --- | --- |
 | 1–2 | App / subtle surfaces |
 | 3–5 | Interactive washes |
 | 6–8 | Borders / strong lines |
-| 9–10 | Solid fills (9 rest, 10 hover) |
+| 9–10 | Solid fills |
 | 11–12 | Text (11 secondary, 12 primary) |
 
 ```ts
@@ -74,6 +76,8 @@ colors.blueAlpha[8]
 
 `colorNames` is `"accent"` plus every Radix palette name. `paletteNames` omits `"accent"`. `"blue"` as a `variantColor` is the Radix blue scale, not CSS `blue`.
 
+Brand accent, semantic status, and decorative identity serve different roles. Prefer a component's variant or tone before assembling custom colors; follow the matching component's source when composing similar UI. For example, [Banner](components/banner.md) owns status tones, while [Avatar](components/avatar.md) uses paired decorative colors, not status meanings.
+
 Prefer semantic surfaces over raw scale steps for chrome:
 
 ```ts
@@ -81,14 +85,14 @@ import { background, backgroundColor } from "maui"
 
 backgroundColor.app            // page
 backgroundColor.element        // raised control / card
-backgroundColor.elementHover   // 3.5% gray-12 wash over element
-backgroundColor.elementActive  // 7% wash
+backgroundColor.elementHover   // hovered element surface
+backgroundColor.elementActive  // active element surface
 background.app                 // style objects of the same values
 background.element
 background.accent              // accent[9]
 ```
 
-Hover/active washes use `color-mix` in oklch (`surfaceWash`, transparent by default). **Do not transition `background` / `background-color` on hover.** Quiet `Button` uses `surfaceMixPercent` (6% light / 9% dark, press 2×) with Alpha[9]. Raised `elementHover` is still 3.5% gray-12 over the element surface.
+Alpha washes depend on their backdrop. A quiet control's transparent overlay is not interchangeable with `elementHover`, which is precomposed over the element surface. Reuse the matching component styles rather than recreating its wash. Hover fills snap instantly; see [design conventions](design_conventions.md#composition).
 
 ## Text
 
@@ -115,7 +119,7 @@ text({
 
 Sizes step up on the **Large platform scale** (`:root[data-scale="large"]`, driven by `(pointer: coarse)` under the system preference): `md` is 14px/22px on desktop and 17px/26px on coarse pointers. See `useScale` / `ScaleProvider`.
 
-- `lowContrast` → `gray[11]`, `highContrast` → `gray[12]`, `accent` → `accent[11]`, `onAccent` → white.
+- `lowContrast` → `gray[11]`, `highContrast` → `gray[12]`, `accent` → `accent[11]`, `onAccent` → white. `onAccent` is literal white, not an adaptive foreground for every solid fill.
 - UI sans: `fontFamily` (system ui-sans-serif stack). Mono: Commit Mono with `ss05` smart kerning (`monoFontStyle` / `monospace`).
 - `tabular: true` → `font-variant-numeric: tabular-nums`. NumberField, TableHead, and TableCell turn this on by default. Body copy and Prose stay off.
 - `baseTextStyle` is md / 400 / highContrast — already on `html, body`.
@@ -178,13 +182,12 @@ shadowVars.control | .subtle | .medium | .strong // raw box-shadow strings
 tintedSubtle(color)                             // subtle ring+blur tinted from a fill
 ```
 
-`shadow.control` is a small drop over a 0.5px edge: gray A6 (`grayAlpha[6]`) in light mode, 80% black in dark mode so the control looks cut into the surface. Dark mode also adds a 0.5px top highlight. Every elevation
-already includes a 1px ring. **Do not also `border()` the same element.**
+For elevation choice, compound control boundaries, and avoiding doubled rings, follow the [shadow conventions](design_conventions.md#shadows).
 
 `border(sides, color)`:
 
 - `sides`: `[]` for all sides, or `"top" | "right" | "bottom" | "left"`
-- `color`: `"border"` (gray-12 @ 5%) | `"outline"` (10%) | `"accent"` (`accent[8]`)
+- `color`: `"border"` (subtle separator) | `"outline"` (stronger edge) | `"accent"` (accent edge)
 
 `borderColor.border` / `borderColor.outline` are the raw color strings (hairlines, `borderBottom`).
 
@@ -195,20 +198,14 @@ already includes a 1px ring. **Do not also `border()` the same element.**
 ## Motion
 
 ```ts
-motionDurationMs          // 80
-motionStreamDurationMs    // 80 — Streamdown word fade
-motionEasing              // "ease-in-out"
-motion.standard("opacity", "transform")  // 80ms ease-in-out on those properties
-overlayMotion             // shared tooltip, dialog, backdrop, and reduced timings
+motion.standard("opacity", "transform")  // shared transition style
+motionDurationMs          // standard duration
+motionStreamDurationMs    // streaming text duration
+motionEasing              // standard easing
+overlayMotion             // overlay and reduced-motion presets
 ```
 
-Use `motion.standard` for opacity, transform, box-shadow, color. **Never** for hover `background` / `background-color`.
-
-`overlayMotion` defines tooltip enter (120ms entrance curve), tooltip exit
-(80ms ease-in), dialog enter (200ms entrance curve), dialog exit (120ms
-ease-in), backdrop (100ms), and opacity-only reduced motion (80ms). Crossfade
-enter is a 0.3s spring (`bounce` 0.2); exit uses `motionDurationMs` /
-ease-in-out. Streaming markdown uses `motionStreamDurationMs`.
+Use `motion.standard` for opacity, transform, box-shadow, and color, not hover fills; see [design conventions](design_conventions.md#composition). Reuse `overlayMotion` for custom overlay enter/exit and reduced-motion handling; inspect the matching component for how it applies those presets.
 
 ## Sizing and icons
 
@@ -229,7 +226,7 @@ Stroke/fill is `currentColor`. Pass `size` on the icon component; optional `widt
 
 ## Avatar tokens
 
-`avatar.green` / `avatar.orange` / `avatar.pink` each have `background` and `foreground`. The `Avatar` component also uses `accent[4]`/`[11]`. You rarely need these tokens directly.
+`avatar.green` / `avatar.orange` / `avatar.pink` each provide a paired `background` and `foreground`; keep the pair together when using these decorative tokens. Prefer `Avatar` for identity UI rather than choosing its colors manually.
 
 ## Prose tokens
 

package/src/apps/Calendar/Calendar.tsx

@@ -1463,7 +1463,7 @@ const miniDayClass = style(
 	text({ size: "xs", fontWeight: 400, color: "highContrast" }),
 	radius.circle,
 	focusRing(),
-	motion.standard("background-color", "color"),
+	motion.standard("color"),
 	{
 		display: "grid",
 		placeItems: "center",

package/src/components/Button.tsx

@@ -303,7 +303,7 @@ const coloredButtonClass = memoize(
 		if (variant === "primary") {
 			return primaryClass(
 				scale[9],
-				darkTextOnSolid.has(color) ? scale[12] : "white",
+				darkTextOnSolid.has(color) ? onSolidText(scale[9]) : "white",
 				paletteAlpha(color)[6],
 			)
 		}

package/src/components/ListBox.tsx

@@ -41,9 +41,12 @@ const item = style(
 			background: backgroundColor.elementHover,
 		},
 		"&[data-selected]": {
-			color: colors.accent[9],
+			color: colors.accent[11],
 			fontWeight: 500,
 		},
+		"&[data-selected]:not([data-disabled]):is(:hover, [data-hovered], [data-focused])": {
+			color: colors.accent[12],
+		},
 		"&[data-selected]::after": {
 			content: '"✓"',
 			position: "absolute",

package/src/components/Table.tsx

@@ -111,7 +111,7 @@ const row = style({
 	"&[data-selection-mode][data-selected] td": {
 		backgroundColor: colors.accent[3],
 	},
-	"&[data-disabled]": {
+	"&[data-disabled] td": {
 		color: colors.gray[8],
 	},
 })
@@ -172,7 +172,7 @@ const selectionCheck = style({
 	height: "10px",
 	paddingTop: "0.5px",
 	paddingLeft: "0.5px",
-	fill: colors.gray[3],
+	fill: "white",
 	opacity: 0,
 	transform: "scale(0)",
 })
@@ -180,6 +180,10 @@ const selectionCheck = style({
 const selectionCheckbox = style(
 	flex({ alignItems: "center", justifyContent: "center" }),
 	focusRing(`&[data-focus-visible] ${selectionBox}`, shadowVars.control),
+	focusRing(
+		`&[data-selected][data-focus-visible] ${selectionBox}, &[data-indeterminate][data-focus-visible] ${selectionBox}`,
+		shadowVars.selectedControl,
+	),
 	{
 		position: "relative",
 		width: "fit-content",
@@ -201,6 +205,7 @@ const selectionCheckbox = style(
 		[`&[data-selected] ${selectionBox}, &[data-indeterminate] ${selectionBox}`]:
 			{
 				backgroundColor: colors.accent[9],
+				boxShadow: shadowVars.selectedControl,
 			},
 		[`&[data-hovered][data-selected] ${selectionBox}, &[data-hovered][data-indeterminate] ${selectionBox}`]:
 			{

package/src/components/navigationItem.ts

@@ -18,8 +18,11 @@ export const navigationItem = style(
 			background: backgroundColor.elementHover,
 		},
 		"&[aria-current='page']": {
-			color: colors.accent[9],
+			color: colors.accent[11],
 			fontWeight: 500,
 		},
+		"&[aria-current='page']:hover": {
+			color: colors.accent[12],
+		},
 	},
 )

package/src/pages/BordersTokenPage.tsx

@@ -36,11 +36,11 @@ const borderExamples = [
 		use: "Pane headers and horizontal section breaks.",
 	},
 	{
-		label: 'border(["left"], "accent") + borderLeftWidth',
+		label: "Clipped left accent",
 		sides: ["left"] as BorderSide[],
 		color: "accent" as const,
 		edgeWidth: "2px",
-		use: "Blockquotes and left-edge emphasis bars.",
+		use: "Decorative emphasis on rounded surfaces.",
 	},
 ] as const
 
@@ -119,17 +119,46 @@ export function BordersTokenPage() {
 				</TableBody>
 			</Table>
 
-			<CodeBlock lang="typescript">{`const panel = style(
+			<CodeBlock lang="tsx">{`const panel = style(
 	background.element,
 	border([], "outline"),
 	radius.md,
 )
 
-const blockquote = style(
-	border(["left"], "accent"),
-	{ borderLeftWidth: "2px" },
-	spacing.padding({ left: 12 }),
-)`}</CodeBlock>
+const accentedSurface = style(
+	radius.md,
+	{
+		position: "relative",
+		overflow: "hidden",
+		padding: "16px",
+		backgroundColor: colors.gray[2],
+	},
+)
+const strip = style({
+	position: "absolute",
+	insetBlock: 0,
+	left: 0,
+	width: "2px",
+	backgroundColor: colors.accent[8],
+	pointerEvents: "none",
+})
+
+function DecoratedSurface() {
+	const surfaceClass = useStyles(accentedSurface)
+	const stripClass = useStyles(strip)
+	return (
+		<div className={surfaceClass}>
+			<div aria-hidden="true" className={stripClass} />
+			<Text>Surface content</Text>
+		</div>
+	)
+}`}</CodeBlock>
+			<P>
+				For left-edge emphasis, clip a full-height rectangular accent inside
+				the rounded container instead of using a left border. The container
+				keeps its rounding without curling the accent inward. This is a
+				composition recipe, not a change to existing component borders.
+			</P>
 
 			<Panel style={{ marginTop: "16px" }}>
 				<div
@@ -166,20 +195,13 @@ function BorderExample(props: {
 	color: BorderColor
 	edgeWidth?: string
 }) {
+	const leftAccent = props.sides.length === 1 && props.sides[0] === "left"
 	const className = useStyles(
-		border(props.sides, props.color),
-		props.edgeWidth
-			? style(
-					Object.fromEntries(
-						props.sides.map((side) => [
-							`border${capitalize(side)}Width`,
-							props.edgeWidth,
-						]),
-					),
-				)
-			: undefined,
+		!leftAccent && border(props.sides, props.color),
 		radius.md,
 		style({
+			position: "relative",
+			overflow: "hidden",
 			background: colors.gray[2],
 			padding: "16px",
 			textAlign: "center",
@@ -190,15 +212,26 @@ function BorderExample(props: {
 
 	return (
 		<div>
-			<div className={className}>{props.label}</div>
+			<div className={className}>
+				{leftAccent && (
+					<div
+						aria-hidden="true"
+						style={{
+							position: "absolute",
+							insetBlock: 0,
+							left: 0,
+							width: props.edgeWidth ?? "1px",
+							backgroundColor: colors.accent[8],
+							pointerEvents: "none",
+						}}
+					/>
+				)}
+				{props.label}
+			</div>
 		</div>
 	)
 }
 
-function capitalize(value: string) {
-	return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`
-}
-
 function SingleEdgeExample() {
 	const className = useStyles(
 		border(["bottom"], "border"),

package/src/patterns/Sidebar.tsx

@@ -142,7 +142,7 @@ const itemClass = style(navigationItem, focusRing("&:focus-visible"), {
 	backgroundColor: "transparent",
 	color: colors.gray[12],
 	"&[aria-current='page']": {
-		color: colors.accent[9],
+		color: colors.accent[11],
 		fontWeight: 500,
 		backgroundColor: "transparent",
 	},