@ponti-studios/ui 0.1.2 → 0.3.0

package/src/components/forms/radio-group.tsx

@@ -1,38 +1,39 @@
 "use client";
 
-import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
+import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group";
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
 import { Circle } from "lucide-react";
 import * as React from "react";
 
 import { cn } from "../../lib/utils";
 
 const RadioGroup = React.forwardRef<
-  React.ComponentRef<typeof RadioGroupPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>
+  React.ComponentRef<typeof RadioGroupPrimitive>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive>
 >(({ className, ...props }, ref) => {
-  return <RadioGroupPrimitive.Root className={cn("grid gap-2", className)} {...props} ref={ref} />;
+  return <RadioGroupPrimitive className={cn("grid gap-2", className)} {...props} ref={ref} />;
 });
-RadioGroup.displayName = RadioGroupPrimitive.Root.displayName;
+RadioGroup.displayName = "RadioGroup";
 
 const RadioGroupItem = React.forwardRef<
-  React.ComponentRef<typeof RadioGroupPrimitive.Item>,
-  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>
+  React.ComponentRef<typeof RadioPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof RadioPrimitive.Root>
 >(({ className, ...props }, ref) => {
   return (
-    <RadioGroupPrimitive.Item
+    <RadioPrimitive.Root
       ref={ref}
       className={cn(
-        "border-accent bg-canvas text-primary focus-visible:border-foreground focus-visible:bg-accent/25 focus-visible:ring-focus aspect-square h-6 w-6 rounded-full border focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50",
+        "border-primary bg-background text-foreground focus-visible:border-ring focus-visible:bg-accent/25 focus-visible:ring-ring aspect-square h-6 w-6 rounded-full border focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50",
         className,
       )}
       {...props}
     >
-      <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
+      <RadioPrimitive.Indicator className="flex items-center justify-center">
         <Circle className="fill-primary h-4 w-4" />
-      </RadioGroupPrimitive.Indicator>
-    </RadioGroupPrimitive.Item>
+      </RadioPrimitive.Indicator>
+    </RadioPrimitive.Root>
   );
 });
-RadioGroupItem.displayName = RadioGroupPrimitive.Item.displayName;
+RadioGroupItem.displayName = "Radio";
 
 export { RadioGroup, RadioGroupItem };

package/src/components/forms/select.stories.tsx

@@ -22,7 +22,7 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   render: () => (
     <Select>
-      <SelectTrigger className="w-[180px]">
+      <SelectTrigger className="w-[180px]" aria-label="Select a fruit">
         <SelectValue placeholder="Select a fruit" />
       </SelectTrigger>
       <SelectContent>
@@ -39,7 +39,7 @@ export const Default: Story = {
 export const WithGroups: Story = {
   render: () => (
     <Select>
-      <SelectTrigger className="w-[200px]">
+      <SelectTrigger className="w-[200px]" aria-label="Select timezone">
         <SelectValue placeholder="Select timezone" />
       </SelectTrigger>
       <SelectContent>
@@ -62,7 +62,7 @@ export const WithGroups: Story = {
 export const Disabled: Story = {
   render: () => (
     <Select disabled>
-      <SelectTrigger className="w-[180px]">
+      <SelectTrigger className="w-[180px]" aria-label="Select a fruit">
         <SelectValue placeholder="Select a fruit" />
       </SelectTrigger>
       <SelectContent>
@@ -75,7 +75,7 @@ export const Disabled: Story = {
 export const Small: Story = {
   render: () => (
     <Select>
-      <SelectTrigger size="sm" className="w-[160px]">
+      <SelectTrigger size="sm" className="w-[160px]" aria-label="Select an option">
         <SelectValue placeholder="Select" />
       </SelectTrigger>
       <SelectContent>

package/src/components/forms/select.tsx

@@ -1,11 +1,25 @@
-import * as SelectPrimitive from "@radix-ui/react-select";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
 import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
 import * as React from "react";
 
 import { cn } from "../../lib/utils";
 
-function Select({ ...props }: React.ComponentProps<typeof SelectPrimitive.Root>) {
-  return <SelectPrimitive.Root data-slot="select" {...props} />;
+type SelectProps = Omit<React.ComponentProps<typeof SelectPrimitive.Root<string>>, "onValueChange" | "value" | "defaultValue"> & {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+};
+
+function Select({ onValueChange, ...props }: SelectProps) {
+  return (
+    <SelectPrimitive.Root
+      data-slot="select"
+      {...props}
+      onValueChange={(value) => {
+        if (value !== null) onValueChange?.(value);
+      }}
+    />
+  );
 }
 
 function SelectGroup({ ...props }: React.ComponentProps<typeof SelectPrimitive.Group>) {
@@ -21,21 +35,19 @@ function SelectTrigger({
   size = "default",
   children,
   ...props
-}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
-  size?: "sm" | "default";
-}) {
+}: React.ComponentProps<typeof SelectPrimitive.Trigger> & { size?: "sm" | "default" }) {
   return (
     <SelectPrimitive.Trigger
       data-slot="select-trigger"
       data-size={size}
       className={cn(
-        "data-placeholder:text-secondary [&_svg:not([class*='text-'])]:text-secondary focus-visible:border-focus focus-visible:ring-focus/50 aria-invalid:ring-destructive/20 aria-invalid:border-destructive flex w-fit items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:ring-inset disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "data-placeholder:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 aria-invalid:border-destructive flex w-fit items-center justify-between gap-2 rounded-md border border-input bg-transparent px-3 py-2 text-sm whitespace-nowrap transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:ring-inset disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         className,
       )}
       {...props}
     >
       {children}
-      <SelectPrimitive.Icon asChild>
+      <SelectPrimitive.Icon>
         <ChevronDownIcon className="size-4 opacity-50" />
       </SelectPrimitive.Icon>
     </SelectPrimitive.Trigger>
@@ -45,34 +57,27 @@ function SelectTrigger({
 function SelectContent({
   className,
   children,
-  position = "item-aligned",
+  position: _position = "item-aligned",
   ...props
-}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+}: React.ComponentProps<typeof SelectPrimitive.Popup> & {
+  position?: "item-aligned" | "popper";
+}) {
   return (
     <SelectPrimitive.Portal>
-      <SelectPrimitive.Content
-        data-slot="select-content"
-        className={cn(
-          "bg-raised text-primary data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 max-h-(--radix-select-content-available-height) min-w-32 origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border",
-          position === "popper" &&
-            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
-          className,
-        )}
-        position={position}
-        {...props}
-      >
-        <SelectScrollUpButton />
-        <SelectPrimitive.Viewport
+      <SelectPrimitive.Positioner sideOffset={4}>
+        <SelectPrimitive.Popup
+          data-slot="select-content"
           className={cn(
-            "p-1",
-            position === "popper" &&
-              "h-(--radix-select-trigger-height) w-full min-w-(--radix-select-trigger-width) scroll-my-1",
+            "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 relative z-50 max-h-(--available-height) min-w-32 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-md border p-1 outline-none",
+            className,
           )}
+          {...props}
         >
-          {children}
-        </SelectPrimitive.Viewport>
-        <SelectScrollDownButton />
-      </SelectPrimitive.Content>
+          <SelectScrollUpButton />
+          <SelectPrimitive.List>{children}</SelectPrimitive.List>
+          <SelectScrollDownButton />
+        </SelectPrimitive.Popup>
+      </SelectPrimitive.Positioner>
     </SelectPrimitive.Portal>
   );
 }
@@ -81,30 +86,23 @@ function SelectLabel({ className, ...props }: React.ComponentProps<typeof Select
   return (
     <SelectPrimitive.Label
       data-slot="select-label"
-      className={cn("text-secondary px-2 py-1.5 text-xs", className)}
+      className={cn("text-muted-foreground px-2 py-1.5 text-xs", className)}
       {...props}
     />
   );
 }
 
-function SelectItem({
-  className,
-  children,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+function SelectItem({ className, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Item>) {
   return (
     <SelectPrimitive.Item
       data-slot="select-item"
       className={cn(
-        "focus:bg-accent focus:text-on-accent [&_svg:not([class*='text-'])]:text-secondary relative flex w-full cursor-default items-center gap-2 rounded-md py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        "data-highlighted:bg-accent data-highlighted:text-accent-foreground relative flex w-full cursor-default items-center gap-2 rounded-md py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50",
         className,
       )}
       {...props}
     >
-      <span
-        data-slot="select-item-indicator"
-        className="absolute right-2 flex size-3.5 items-center justify-center"
-      >
+      <span className="absolute right-2 flex size-3.5 items-center justify-center">
         <SelectPrimitive.ItemIndicator>
           <CheckIcon className="size-4" />
         </SelectPrimitive.ItemIndicator>
@@ -114,33 +112,27 @@ function SelectItem({
   );
 }
 
-function SelectScrollUpButton({
-  className,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+function SelectScrollUpButton({ className, ...props }: React.ComponentProps<"div">) {
   return (
-    <SelectPrimitive.ScrollUpButton
+    <SelectPrimitive.ScrollUpArrow
       data-slot="select-scroll-up-button"
       className={cn("flex cursor-default items-center justify-center py-1", className)}
       {...props}
     >
       <ChevronUpIcon className="size-4" />
-    </SelectPrimitive.ScrollUpButton>
+    </SelectPrimitive.ScrollUpArrow>
   );
 }
 
-function SelectScrollDownButton({
-  className,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+function SelectScrollDownButton({ className, ...props }: React.ComponentProps<"div">) {
   return (
-    <SelectPrimitive.ScrollDownButton
+    <SelectPrimitive.ScrollDownArrow
       data-slot="select-scroll-down-button"
       className={cn("flex cursor-default items-center justify-center py-1", className)}
       {...props}
     >
       <ChevronDownIcon className="size-4" />
-    </SelectPrimitive.ScrollDownButton>
+    </SelectPrimitive.ScrollDownArrow>
   );
 }
 

package/src/components/forms/slider.stories.tsx

@@ -30,6 +30,7 @@ export const Default: Story = {
     defaultValue: [50],
     min: 0,
     max: 100,
+    "aria-label": "Volume",
   },
 };
 
@@ -39,6 +40,7 @@ export const WithStep: Story = {
     min: 0,
     max: 100,
     step: 10,
+    "aria-label": "Volume",
   },
 };
 
@@ -47,9 +49,9 @@ export const Controlled: Story = {
     const [value, setValue] = React.useState([33]);
     return (
       <div className="w-full max-w-sm space-y-4 px-1">
-        <Slider value={value} onValueChange={setValue} min={0} max={100} />
+        <Slider aria-label="Volume" value={value} onValueChange={setValue} min={0} max={100} />
         <div className="flex justify-between text-sm">
-          <span className="text-secondary">Volume</span>
+          <span className="text-muted-foreground">Volume</span>
           <span className="font-medium tabular-nums">{value[0]}%</span>
         </div>
       </div>
@@ -63,5 +65,6 @@ export const Disabled: Story = {
     disabled: true,
     min: 0,
     max: 100,
+    "aria-label": "Volume",
   },
 };

package/src/components/forms/slider.tsx

@@ -1,25 +1,35 @@
 "use client";
 
-import * as SliderPrimitive from "@radix-ui/react-slider";
+import { Slider as SliderPrimitive } from "@base-ui/react/slider";
 import * as React from "react";
 
 import { cn } from "../../lib/utils";
 
-const Slider = React.forwardRef<
-  React.ComponentRef<typeof SliderPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>
->(({ className, ...props }, ref) => (
-  <SliderPrimitive.Root
-    ref={ref}
-    className={cn("relative flex w-full touch-none items-center select-none", className)}
-    {...props}
-  >
-    <SliderPrimitive.Track className="bg-panel/40 relative h-2 w-full grow overflow-hidden rounded-full">
-      <SliderPrimitive.Range className="bg-accent absolute h-full" />
-    </SliderPrimitive.Track>
-    <SliderPrimitive.Thumb className="border-default focus-visible:border-foreground focus-visible:bg-accent focus-visible:ring-focus block h-6 w-6 rounded-full border bg-white shadow-sm ring-1 ring-black/5 transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50" />
-  </SliderPrimitive.Root>
-));
-Slider.displayName = SliderPrimitive.Root.displayName;
+type SliderProps = Omit<React.ComponentProps<typeof SliderPrimitive.Root>, "onValueChange" | "value" | "defaultValue"> & {
+  value?: number[];
+  defaultValue?: number[];
+  onValueChange?: (value: number[]) => void;
+};
+
+const Slider = React.forwardRef<HTMLDivElement, SliderProps>(
+  ({ className, onValueChange, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, ...props }, ref) => (
+    <SliderPrimitive.Root
+      ref={ref}
+      className={cn("relative flex w-full touch-none items-center select-none", className)}
+      {...props}
+      onValueChange={(value) => onValueChange?.(Array.isArray(value) ? [...value] : [value])}
+    >
+      <SliderPrimitive.Track className="bg-muted relative h-2 w-full grow overflow-hidden rounded-full">
+        <SliderPrimitive.Indicator className="bg-accent absolute h-full" />
+      </SliderPrimitive.Track>
+      <SliderPrimitive.Thumb
+        aria-label={ariaLabel ?? "Slider"}
+        aria-labelledby={ariaLabelledby}
+        className="border-border focus-visible:border-ring focus-visible:bg-accent focus-visible:ring-ring block h-6 w-6 rounded-full border bg-background shadow-sm ring-1 ring-black/5 transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50"
+      />
+    </SliderPrimitive.Root>
+  ),
+);
+Slider.displayName = "Slider";
 
 export { Slider };

package/src/components/forms/stepper.tsx

@@ -32,19 +32,19 @@ function Stepper({
   const atMax = value >= max;
 
   return (
-    <div className={cn("border-default bg-inset flex items-center rounded-lg border", className)}>
+    <div className={cn("flex items-center rounded-lg border border-input bg-muted", className)}>
       <Button
         type="button"
         variant="ghost"
         onClick={() => onChange(Math.max(min, value - step))}
         disabled={disabled || atMin}
-        className="border-default text-secondary rounded-none rounded-l-lg border-r"
+        className="text-muted-foreground rounded-none rounded-l-lg border-r"
         aria-label={decreaseLabel}
       >
         <Minus className="size-3.5" />
       </Button>
       <div className="flex min-w-[3ch] flex-1 items-center justify-center px-3">
-        <span className="text-primary font-['Geist'] text-sm font-semibold tabular-nums">
+        <span className="text-foreground text-sm font-semibold tabular-nums">
           {format ? format(value) : value}
         </span>
       </div>
@@ -53,7 +53,7 @@ function Stepper({
         variant="ghost"
         onClick={() => onChange(Math.min(max, value + step))}
         disabled={disabled || atMax}
-        className="border-default text-secondary rounded-none rounded-r-lg border-l"
+        className="text-muted-foreground rounded-none rounded-r-lg border-l"
         aria-label={increaseLabel}
       >
         <Plus className="size-3.5" />

package/src/components/forms/switch.stories.tsx

@@ -49,7 +49,7 @@ function SwitchPreview({
         onCheckedChange={setCurrentChecked}
         size={size}
       />
-      <label htmlFor={id} className="text-primary text-sm leading-none font-medium">
+      <label htmlFor={id} className="text-foreground text-sm leading-none font-medium">
         {label}
       </label>
     </div>

package/src/components/forms/switch.tsx

@@ -1,4 +1,4 @@
-import * as SwitchPrimitive from "@radix-ui/react-switch";
+import { Switch as SwitchPrimitive } from "@base-ui/react/switch";
 import * as React from "react";
 
 import { cn } from "../../lib/utils";
@@ -15,7 +15,7 @@ function Switch({
       data-slot="switch"
       data-size={size}
       className={cn(
-        "peer data-[state=checked]:bg-accent data-[state=unchecked]:bg-inset focus-visible:ring-focus inline-flex shrink-0 items-center rounded-full border border-transparent p-px focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:justify-end data-[state=unchecked]:justify-start",
+        "peer data-checked:bg-primary data-unchecked:bg-input focus-visible:ring-ring inline-flex shrink-0 items-center rounded-full border border-transparent p-px focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 data-checked:justify-end data-unchecked:justify-start",
         size === "default" ? "h-[1.15rem] w-8" : "h-3.5 w-6",
         className,
       )}

package/src/components/forms/textarea.stories.tsx

@@ -22,7 +22,7 @@ function TextareaField({
 
   return (
     <div className="grid gap-2">
-      <label htmlFor={id} className="text-primary text-sm leading-none font-medium">
+      <label htmlFor={id} className="text-foreground text-sm leading-none font-medium">
         {label}
       </label>
       <Textarea
@@ -32,7 +32,7 @@ function TextareaField({
         {...props}
       />
       {helpText ? (
-        <p id={helpId} className="text-secondary text-sm">
+        <p id={helpId} className="text-muted-foreground text-sm">
           {helpText}
         </p>
       ) : null}

package/src/components/forms/textarea.tsx

@@ -7,7 +7,7 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
     <textarea
       data-slot="textarea"
       className={cn(
-        "placeholder:text-secondary aria-invalid:ring-destructive/20 aria-invalid:border-destructive focus-visible:ring-focus flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "placeholder:text-muted-foreground aria-invalid:ring-destructive/20 aria-invalid:border-destructive focus-visible:ring-ring flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-transparent px-3 py-2 text-base transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
         className,
       )}
       {...props}

package/src/components/layout/index.ts

@@ -1,2 +1,5 @@
 export { ScrollArea } from "./scroll-area";
 export type { ScrollAreaProps } from "./scroll-area";
+export { SectionIntro } from "./section-intro";
+export type { SectionIntroProps } from "./section-intro";
+export { SurfacePanel } from "./surface-panel";

package/src/components/layout/scroll-area.stories.tsx

@@ -25,7 +25,7 @@ export const Default: Story = {
         className="flex size-40 shrink-0 items-center justify-center rounded-lg"
         style={{ backgroundColor: item.bg }}
       >
-        <span className="text-primary font-medium">{item.label}</span>
+        <span className="text-foreground font-medium">{item.label}</span>
       </div>
     )),
   },
@@ -41,7 +41,7 @@ export const WithSnap: Story = {
         className="flex size-48 shrink-0 items-center justify-center rounded-lg"
         style={{ backgroundColor: item.bg }}
       >
-        <span className="text-primary font-medium">{item.label}</span>
+        <span className="text-foreground font-medium">{item.label}</span>
       </div>
     )),
   },
@@ -57,7 +57,7 @@ export const Vertical: Story = {
         className="flex h-24 shrink-0 items-center justify-center rounded-lg"
         style={{ backgroundColor: item.bg }}
       >
-        <span className="text-primary font-medium">{item.label}</span>
+        <span className="text-foreground font-medium">{item.label}</span>
       </div>
     )),
   },
@@ -74,7 +74,7 @@ export const ScreenshotsGallery: Story = {
             className="flex aspect-video w-72 shrink-0 items-center justify-center overflow-hidden rounded-xl border"
             style={{ backgroundColor: item.bg }}
           >
-            <span className="text-primary/70 text-sm">{item.label}</span>
+            <span className="text-foreground/70 text-sm">{item.label}</span>
           </div>
         ))}
       </ScrollArea>

package/src/components/layout/scroll-area.tsx

@@ -1,7 +1,9 @@
+import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area";
 import * as React from "react";
+
 import { cn } from "../../lib/utils";
 
-interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
+interface ScrollAreaProps extends React.ComponentProps<typeof ScrollAreaPrimitive.Root> {
   orientation?: "horizontal" | "vertical";
   snap?: "start" | "center" | "none";
 }
@@ -9,31 +11,31 @@ interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
 const ScrollArea = React.forwardRef<HTMLDivElement, ScrollAreaProps>(
   ({ className, children, orientation = "horizontal", snap = "none", ...props }, ref) => {
     return (
-      <div
-        ref={ref}
-        className={cn(
-          "scrollbar-hide flex overflow-auto",
-          orientation === "horizontal" && "flex-row",
-          orientation === "vertical" && "flex-col",
-          snap !== "none" && orientation === "horizontal" && "snap-x snap-mandatory",
-          snap !== "none" && orientation === "vertical" && "snap-y snap-mandatory",
-          className,
-        )}
-        {...props}
-      >
-        {React.Children.map(children, (child) => {
-          if (!React.isValidElement(child)) return child;
-          if (snap !== "none") {
+      <ScrollAreaPrimitive.Root ref={ref} className={cn("relative", className)} {...props}>
+        <ScrollAreaPrimitive.Viewport
+          className={cn(
+            "scrollbar-hide flex overflow-auto",
+            orientation === "horizontal" ? "flex-row" : "flex-col",
+            snap !== "none" && (orientation === "horizontal" ? "snap-x" : "snap-y"),
+            snap !== "none" && "snap-mandatory",
+          )}
+        >
+          {React.Children.map(children, (child) => {
+            if (!React.isValidElement(child)) return child;
             return React.cloneElement(child as React.ReactElement<{ className?: string }>, {
-              className: cn(`snap-${snap}`, (child.props as { className?: string }).className),
+              className: cn(
+                snap !== "none" && orientation === "horizontal" && `snap-${snap}`,
+                snap !== "none" && orientation === "vertical" && `snap-${snap}`,
+                (child.props as { className?: string }).className,
+              ),
             });
-          }
-          return child;
-        })}
-      </div>
+          })}
+        </ScrollAreaPrimitive.Viewport>
+      </ScrollAreaPrimitive.Root>
     );
   },
 );
+
 ScrollArea.displayName = "ScrollArea";
 
 export { ScrollArea };

package/src/components/layout/section-intro.stories.tsx

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Button } from "../primitives/button";
+import { SectionIntro } from "./section-intro";
+
+const meta = {
+  title: "Layout/SectionIntro",
+  component: SectionIntro,
+  tags: ["autodocs"],
+} satisfies Meta<typeof SectionIntro>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    title: "Accounts",
+    description: "Connect and manage the accounts you track.",
+  },
+};
+
+export const WithEyebrowAndActions: Story = {
+  args: {
+    eyebrow: "Settings",
+    title: "Security",
+    description: "Manage how you sign in and keep your account secure.",
+    actions: <Button variant="outline">Add passkey</Button>,
+  },
+};

package/src/components/layout/section-intro.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+
+export interface SectionIntroProps {
+  eyebrow?: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+  actions?: ReactNode;
+}
+
+/**
+ * Page-level heading composition: eyebrow label, title, description, and an
+ * optional trailing actions slot.
+ */
+export function SectionIntro({ eyebrow, title, description, actions }: SectionIntroProps) {
+  return (
+    <div className="flex items-start justify-between gap-6">
+      <div className="min-w-0 flex-1">
+        {eyebrow ? (
+          <div className="text-muted-foreground mb-3 text-[11px] font-medium tracking-[0.18em] uppercase">
+            {eyebrow}
+          </div>
+        ) : null}
+        <div className="space-y-3">
+          <h1 className="text-title-2 text-foreground font-semibold tracking-tight">{title}</h1>
+          {description ? <p className="text-sm text-muted-foreground">{description}</p> : null}
+        </div>
+      </div>
+      {actions ? <div className="shrink-0">{actions}</div> : null}
+    </div>
+  );
+}

package/src/components/layout/surface-panel.stories.tsx

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { SurfacePanel } from "./surface-panel";
+
+const meta = {
+  title: "Layout/SurfacePanel",
+  component: SurfacePanel,
+  tags: ["autodocs"],
+} satisfies Meta<typeof SurfacePanel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="w-80">
+      <SurfacePanel>
+        <p className="text-muted-foreground text-sm">Panel content goes here.</p>
+      </SurfacePanel>
+    </div>
+  ),
+};
+
+export const AsSection: Story = {
+  render: () => (
+    <div className="w-80">
+      <SurfacePanel as="section" aria-label="Example panel">
+        <p className="text-muted-foreground text-sm">Rendered as a semantic &lt;section&gt;.</p>
+      </SurfacePanel>
+    </div>
+  ),
+};