@voltro/ui-shadcn 0.1.0

package/src/primitives/docIcons.tsx

@@ -0,0 +1,268 @@
+// Lucide-style stroke icons for doc landing cards. All icons share the
+// same visual language: 24×24 viewBox, 1.5px stroke, rounded caps,
+// `currentColor` for fill/stroke so they pick up `text-*` Tailwind
+// utilities + the theme tokens.
+//
+// Hand-rolled (vs depending on `lucide-react`) because we only need a
+// dozen icons here and a 200KB dep for that is silly. Add more shapes
+// to this file as the doc catalogue grows.
+
+import type { ReactNode } from 'react'
+
+interface DocIconProps {
+  readonly className?: string
+  /** Accessible label. When omitted the icon is `aria-hidden` and
+   *  should sit next to text. */
+  readonly title?: string
+}
+
+const Icon = ({
+  children, className, title,
+}: DocIconProps & { children: ReactNode }): ReactNode => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24" height="24"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.5"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className={className}
+    {...(title ? { role: 'img', 'aria-label': title } : { 'aria-hidden': true })}
+  >
+    {title ? <title>{title}</title> : null}
+    {children}
+  </svg>
+)
+
+export const RocketIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M4.5 16.5 c-1.5 1.26 -2 5 -2 5 s3.74 -.5 5 -2 c.71 -.84 .7 -2.13 -.09 -2.91 a2.18 2.18 0 0 0 -2.91 -.09Z" />
+    <path d="m12 15 -3 -3 a22 22 0 0 1 2 -3.95 A12.88 12.88 0 0 1 22 2 c0 2.72 -.78 7.5 -6 11 a22.35 22.35 0 0 1 -4 2Z" />
+    <path d="M9 12 H4 s.55 -3.03 2 -4 c1.62 -1.08 5 0 5 0" />
+    <path d="M12 15 v5 s3.03 -.55 4 -2 c1.08 -1.62 0 -5 0 -5" />
+  </Icon>
+)
+
+export const CompassIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <circle cx="12" cy="12" r="10" />
+    <polygon points="16.24,7.76 14.12,14.12 7.76,16.24 9.88,9.88" />
+  </Icon>
+)
+
+export const PackageIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="m7.5 4.27 9 5.15" />
+    <path d="M21 8 a2 2 0 0 0 -1 -1.73 l-7 -4 a2 2 0 0 0 -2 0 l-7 4 A2 2 0 0 0 3 8 v8 a2 2 0 0 0 1 1.73 l7 4 a2 2 0 0 0 2 0 l7 -4 A2 2 0 0 0 21 16 Z" />
+    <path d="M3.3 7 12 12 l8.7 -5" />
+    <path d="M12 22 V12" />
+  </Icon>
+)
+
+export const FolderIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M20 20 H4 a2 2 0 0 1 -2 -2 V6 a2 2 0 0 1 2 -2 h5.93 a2 2 0 0 1 1.66 .9 l.82 1.2 a2 2 0 0 0 1.66 .9 H20 a2 2 0 0 1 2 2 v8 a2 2 0 0 1 -2 2 z" />
+  </Icon>
+)
+
+export const FileIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M14.5 2 H6 a2 2 0 0 0 -2 2 v16 a2 2 0 0 0 2 2 h12 a2 2 0 0 0 2 -2 V7.5 z" />
+    <polyline points="14 2 14 8 20 8" />
+  </Icon>
+)
+
+export const BroadcastIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M4.93 4.93 a10 10 0 0 0 0 14.14" />
+    <path d="M19.07 4.93 a10 10 0 0 1 0 14.14" />
+    <path d="M7.76 7.76 a6 6 0 0 0 0 8.49" />
+    <path d="M16.24 7.76 a6 6 0 0 1 0 8.49" />
+    <circle cx="12" cy="12" r="2" />
+  </Icon>
+)
+
+export const PencilIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M17 3 a2.85 2.83 0 1 1 4 4 L7.5 20.5 2 22 l1.5 -5.5 z" />
+  </Icon>
+)
+
+export const BellIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M6 8 a6 6 0 0 1 12 0 c0 7 3 9 3 9 H3 s3 -2 3 -9" />
+    <path d="M10.3 21 a1.94 1.94 0 0 0 3.4 0" />
+  </Icon>
+)
+
+export const CogIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M12 2 v4 M12 18 v4 M4.93 4.93 l2.83 2.83 M16.24 16.24 l2.83 2.83 M2 12 h4 M18 12 h4 M4.93 19.07 l2.83 -2.83 M16.24 7.76 l2.83 -2.83" />
+    <circle cx="12" cy="12" r="4" />
+  </Icon>
+)
+
+export const BuildingIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <rect x="4" y="2" width="16" height="20" rx="2" />
+    <path d="M9 22 V12 h6 v10" />
+    <path d="M8 6 h.01 M12 6 h.01 M16 6 h.01 M8 10 h.01 M16 10 h.01" />
+  </Icon>
+)
+
+export const DatabaseIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <ellipse cx="12" cy="5" rx="9" ry="3" />
+    <path d="M3 5 v14 a9 3 0 0 0 18 0 V5" />
+    <path d="M3 12 a9 3 0 0 0 18 0" />
+  </Icon>
+)
+
+export const LockIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <rect x="3" y="11" width="18" height="11" rx="2" />
+    <path d="M7 11 V7 a5 5 0 0 1 10 0 v4" />
+  </Icon>
+)
+
+export const BotIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M12 8 V4 H8" />
+    <rect x="2" y="8" width="20" height="14" rx="2" />
+    <path d="M2 14 h2 M20 14 h2 M15 13 v2 M9 13 v2" />
+  </Icon>
+)
+
+export const TerminalIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <polyline points="4 17 10 11 4 5" />
+    <line x1="12" y1="19" x2="20" y2="19" />
+  </Icon>
+)
+
+export const LayersIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <polygon points="12 2 2 7 12 12 22 7 12 2" />
+    <polyline points="2 17 12 22 22 17" />
+    <polyline points="2 12 12 17 22 12" />
+  </Icon>
+)
+
+export const PuzzleIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M19.43 12.98 a8 8 0 0 0 0 -1.96 l2.11 -1.65 -2 -3.46 -2.49 1 a8 8 0 0 0 -1.7 -.98 L15 3 H9 l-.38 2.93 a8 8 0 0 0 -1.7 .98 L4.43 5.91 l-2 3.46 2.11 1.65 a8 8 0 0 0 0 1.96 L2.43 14.63 l2 3.46 2.49 -1 a8 8 0 0 0 1.7 .98 L9 21 h6 l.38 -2.93 a8 8 0 0 0 1.7 -.98 l2.49 1 2 -3.46 z" />
+    <circle cx="12" cy="12" r="3" />
+  </Icon>
+)
+
+export const HookIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M9 9 a3 3 0 0 1 6 0 v9 a3 3 0 0 1 -6 0 V12 a1 1 0 0 1 2 0 v6 a1 1 0 0 0 2 0 V9 a1 1 0 0 0 -2 0" />
+  </Icon>
+)
+
+export const GlobeIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <circle cx="12" cy="12" r="10" />
+    <line x1="2" y1="12" x2="22" y2="12" />
+    <path d="M12 2 a15.3 15.3 0 0 1 4 10 a15.3 15.3 0 0 1 -4 10 a15.3 15.3 0 0 1 -4 -10 a15.3 15.3 0 0 1 4 -10 z" />
+  </Icon>
+)
+
+export const CloudIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M17.5 19 a4.5 4.5 0 1 0 -1.41 -8.78 a6 6 0 1 0 -11.05 4.5" />
+  </Icon>
+)
+
+export const HomeIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M3 9 l9 -7 9 7 v11 a2 2 0 0 1 -2 2 H5 a2 2 0 0 1 -2 -2 z" />
+    <polyline points="9 22 9 12 15 12 15 22" />
+  </Icon>
+)
+
+export const ChevronLeftIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}><polyline points="15 18 9 12 15 6" /></Icon>
+)
+
+export const ChevronRightIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}><polyline points="9 18 15 12 9 6" /></Icon>
+)
+
+export const SearchIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <circle cx="11" cy="11" r="8" />
+    <line x1="21" y1="21" x2="16.65" y2="16.65" />
+  </Icon>
+)
+
+export const ArrowReturnIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <polyline points="9 10 4 15 9 20" />
+    <path d="M20 4 v7 a4 4 0 0 1 -4 4 H4" />
+  </Icon>
+)
+
+// ---- Social / brand icons ----
+//
+// Filled (not stroked) — that's the convention for brand marks since
+// the official lockups are filled. Same 24×24 viewBox + currentColor
+// fill so they pick up text-* utilities and theme tokens.
+
+const FilledIcon = ({
+  children, className, title,
+}: DocIconProps & { children: ReactNode }): ReactNode => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24" height="24"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    className={className}
+    {...(title ? { role: 'img', 'aria-label': title } : { 'aria-hidden': true })}
+  >
+    {title ? <title>{title}</title> : null}
+    {children}
+  </svg>
+)
+
+export const GitHubIcon = (p: DocIconProps): ReactNode => (
+  <FilledIcon {...p}>
+    <path d="M12 0C5.37 0 0 5.37 0 12c0 5.3 3.44 9.8 8.21 11.39.6.11.82-.26.82-.58 0-.29-.01-1.04-.02-2.05-3.34.72-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.09-.74.08-.73.08-.73 1.2.09 1.84 1.24 1.84 1.24 1.07 1.84 2.81 1.31 3.5 1 .11-.78.42-1.31.76-1.61-2.67-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.24-3.22-.12-.3-.54-1.52.12-3.18 0 0 1.01-.32 3.31 1.23.96-.27 1.99-.4 3.02-.41 1.02.01 2.05.14 3.02.41 2.3-1.55 3.31-1.23 3.31-1.23.66 1.66.24 2.88.12 3.18.77.84 1.24 1.91 1.24 3.22 0 4.61-2.81 5.63-5.49 5.93.43.37.81 1.1.81 2.22 0 1.6-.01 2.89-.01 3.29 0 .32.21.7.83.58C20.57 21.8 24 17.3 24 12c0-6.63-5.37-12-12-12z" />
+  </FilledIcon>
+)
+
+export const XIcon = (p: DocIconProps): ReactNode => (
+  <FilledIcon {...p}>
+    <path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z" />
+  </FilledIcon>
+)
+
+export const DiscordIcon = (p: DocIconProps): ReactNode => (
+  <FilledIcon {...p}>
+    <path d="M20.317 4.37a19.79 19.79 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.74 19.74 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057 19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028 14.09 14.09 0 0 0 1.226-1.994.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.84 19.84 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.946 2.418-2.157 2.418z" />
+  </FilledIcon>
+)
+
+export const LinkedInIcon = (p: DocIconProps): ReactNode => (
+  <FilledIcon {...p}>
+    <path d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433a2.062 2.062 0 0 1-2.063-2.065 2.063 2.063 0 1 1 2.063 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z" />
+  </FilledIcon>
+)
+
+export const RssIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M4 11 a9 9 0 0 1 9 9" />
+    <path d="M4 4 a16 16 0 0 1 16 16" />
+    <circle cx="5" cy="19" r="1" />
+  </Icon>
+)
+
+export const ChartIcon = (p: DocIconProps): ReactNode => (
+  <Icon {...p}>
+    <path d="M3 3 v18 h18" />
+    <path d="M7 14 l3 -3 l4 4 l6 -7" />
+  </Icon>
+)

package/src/primitives/dropdownMenu.tsx

@@ -0,0 +1,162 @@
+// shadcn-style DropdownMenu — Radix wrappers with kit token styling.
+//
+// 1:1 API with shadcn/ui reference so docs + examples lifted from
+// there work without rename:
+//
+//   <DropdownMenu>
+//     <DropdownMenuTrigger asChild><Button … /></DropdownMenuTrigger>
+//     <DropdownMenuContent align="end">
+//       <DropdownMenuLabel>Account</DropdownMenuLabel>
+//       <DropdownMenuItem onSelect={…}>Settings</DropdownMenuItem>
+//       <DropdownMenuSeparator />
+//       <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
+//         <DropdownMenuRadioItem value="system">System</DropdownMenuRadioItem>
+//         <DropdownMenuRadioItem value="light">Light</DropdownMenuRadioItem>
+//         <DropdownMenuRadioItem value="dark">Dark</DropdownMenuRadioItem>
+//       </DropdownMenuRadioGroup>
+//     </DropdownMenuContent>
+//   </DropdownMenu>
+//
+// Not yet wrapped: CheckboxItem, Sub / SubTrigger / SubContent.
+// Add when something needs them — keeps the surface lean.
+
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ComponentRef,
+  type ReactNode,
+} from 'react'
+import * as RDM from '@radix-ui/react-dropdown-menu'
+import { cn } from '../cn'
+
+// ---- Pass-through wrappers ----
+
+export const DropdownMenu = RDM.Root
+export const DropdownMenuTrigger = RDM.Trigger
+export const DropdownMenuGroup = RDM.Group
+export const DropdownMenuPortal = RDM.Portal
+export const DropdownMenuRadioGroup = RDM.RadioGroup
+
+// ---- Content ----
+
+export const DropdownMenuContent = forwardRef<
+  ComponentRef<typeof RDM.Content>,
+  ComponentPropsWithoutRef<typeof RDM.Content>
+>(({ className, sideOffset = 6, ...props }, ref) => (
+  <RDM.Portal>
+    <RDM.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 min-w-[10rem] overflow-hidden rounded-md border border-border',
+        'bg-popover text-popover-foreground shadow-lg p-1',
+        '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=top]:slide-in-from-bottom-2',
+        'data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2',
+        className,
+      )}
+      {...props}
+    />
+  </RDM.Portal>
+))
+DropdownMenuContent.displayName = 'DropdownMenuContent'
+
+// ---- Label ----
+
+export const DropdownMenuLabel = forwardRef<
+  ComponentRef<typeof RDM.Label>,
+  ComponentPropsWithoutRef<typeof RDM.Label> & { readonly inset?: boolean }
+>(({ className, inset, ...props }, ref) => (
+  <RDM.Label
+    ref={ref}
+    className={cn(
+      'px-2 py-1.5 text-[0.65rem] font-semibold uppercase tracking-wider text-muted-foreground',
+      inset && 'pl-8',
+      className,
+    )}
+    {...props}
+  />
+))
+DropdownMenuLabel.displayName = 'DropdownMenuLabel'
+
+// ---- Separator ----
+
+export const DropdownMenuSeparator = forwardRef<
+  ComponentRef<typeof RDM.Separator>,
+  ComponentPropsWithoutRef<typeof RDM.Separator>
+>(({ className, ...props }, ref) => (
+  <RDM.Separator
+    ref={ref}
+    className={cn('-mx-1 my-1 h-px bg-border', className)}
+    {...props}
+  />
+))
+DropdownMenuSeparator.displayName = 'DropdownMenuSeparator'
+
+// ---- Item ----
+//
+// `destructive` opts into the destructive token — shorthand for the
+// common "Sign out / Delete" use case so callers don't repeat the
+// same Tailwind chain.
+
+export const DropdownMenuItem = forwardRef<
+  ComponentRef<typeof RDM.Item>,
+  ComponentPropsWithoutRef<typeof RDM.Item> & {
+    readonly inset?: boolean
+    readonly destructive?: boolean
+  }
+>(({ className, inset, destructive, ...props }, ref) => (
+  <RDM.Item
+    ref={ref}
+    className={cn(
+      'relative flex items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none',
+      'transition-colors select-none cursor-pointer',
+      'focus:bg-accent focus:text-accent-foreground',
+      'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      "[&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 [&_svg]:pointer-events-none",
+      inset && 'pl-8',
+      destructive
+        ? 'text-destructive focus:bg-destructive/10 focus:text-destructive'
+        : 'text-foreground',
+      className,
+    )}
+    {...props}
+  />
+))
+DropdownMenuItem.displayName = 'DropdownMenuItem'
+
+// ---- RadioItem ----
+//
+// Indicator: filled dot on the left, slot reserved (pl-8) so
+// unselected items stay aligned with selected ones.
+
+const RadioDot = (): ReactNode => (
+  <span className="size-2 rounded-full bg-current" />
+)
+
+export const DropdownMenuRadioItem = forwardRef<
+  ComponentRef<typeof RDM.RadioItem>,
+  ComponentPropsWithoutRef<typeof RDM.RadioItem>
+>(({ className, children, ...props }, ref) => (
+  <RDM.RadioItem
+    ref={ref}
+    className={cn(
+      'relative flex items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-none',
+      'transition-colors select-none cursor-pointer text-foreground',
+      'focus:bg-accent focus:text-accent-foreground',
+      'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className,
+    )}
+    {...props}
+  >
+    <span className="absolute left-2.5 flex size-3.5 items-center justify-center">
+      <RDM.ItemIndicator>
+        <RadioDot />
+      </RDM.ItemIndicator>
+    </span>
+    {children}
+  </RDM.RadioItem>
+))
+DropdownMenuRadioItem.displayName = 'DropdownMenuRadioItem'

package/src/primitives/gridOverlay.tsx

@@ -0,0 +1,51 @@
+// GridOverlay — subtle dot or line grid pattern, faded with a radial
+// mask so it brightest at the centre and disappears toward the
+// edges. The classic "engineering blueprint" tech vibe without
+// fighting the foreground content.
+//
+// Stacks on top of MeshBackdrop, beneath foreground content. Pointer-
+// events off; aria-hidden.
+
+import type { ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface GridOverlayProps {
+  readonly className?: string
+  /** Grid style — dotted (default, gentler) or lined (stronger
+   *  blueprint feel). */
+  readonly variant?: 'dots' | 'lines'
+  /** Cell size in px. Default 32. */
+  readonly size?: number
+}
+
+export const GridOverlay = ({
+  className, variant = 'dots', size = 32,
+}: GridOverlayProps): ReactNode => {
+  // For dots: a single radial gradient repeating in a tiny tile.
+  // For lines: two linear gradients (h + v) over the same tile.
+  const dotsBg = `radial-gradient(circle, var(--foreground) 1px, transparent 1.5px)`
+  const linesBg
+    = `linear-gradient(to right, var(--foreground) 1px, transparent 1px),`
+    + `linear-gradient(to bottom, var(--foreground) 1px, transparent 1px)`
+
+  return (
+    <div
+      aria-hidden="true"
+      className={cn(
+        'absolute inset-0 pointer-events-none opacity-[0.06]',
+        className,
+      )}
+      style={{
+        backgroundImage: variant === 'lines' ? linesBg : dotsBg,
+        backgroundSize: `${size}px ${size}px`,
+        // Radial mask: full opacity at centre, fades to 0 at edges.
+        // Tailwind doesn't have a mask utility in stable v4 so this
+        // stays inline.
+        WebkitMaskImage:
+          'radial-gradient(ellipse at center, black 0%, transparent 75%)',
+        maskImage:
+          'radial-gradient(ellipse at center, black 0%, transparent 75%)',
+      }}
+    />
+  )
+}

package/src/primitives/highlightedCode.tsx

@@ -0,0 +1,112 @@
+// HighlightedCode — Shiki-powered syntax highlighting as a reusable
+// primitive. Apps drop `<HighlightedCode code lang />` anywhere and
+// get dual-theme (light + dark) output that flips with the
+// `.dark` class on <html>.
+//
+// Lazy + shared singleton: the first usage triggers an async Shiki
+// load (~200ms WASM bootstrap), subsequent renders share the same
+// highlighter instance. Until Shiki is ready, the component renders
+// plain escaped code so the layout doesn't jump.
+//
+// Browser-safe via dynamic import; runs on the Node side too (SSR /
+// `voltro build` waits for it via `whenReady`).
+
+import {
+  useEffect, useMemo, useState, type ReactNode,
+} from 'react'
+import type { Highlighter } from 'shiki'
+import { cn } from '../cn'
+
+declare global {
+  var __voltroShikiHighlighter: Highlighter | null | undefined
+  var __voltroShikiHighlighterPromise: Promise<Highlighter | null> | null | undefined
+}
+
+// Languages we ship support for. Add to this list as new doc + landing
+// snippets need them; loading is one-shot at highlighter init.
+export const SHIKI_LANGS = [
+  'text', 'ts', 'tsx', 'typescript', 'js', 'jsx', 'json', 'bash', 'sh',
+  'shell', 'sql', 'yaml', 'toml', 'md', 'mdx', 'html', 'css', 'diff',
+] as const
+export type ShikiLang = typeof SHIKI_LANGS[number]
+
+// Global singleton — shared across HighlightedCode calls, HMR reloads,
+// and docs-content rendering so we only pay the WASM bootstrap once.
+const ensure = async (): Promise<Highlighter | null> => {
+  if (globalThis.__voltroShikiHighlighter) return globalThis.__voltroShikiHighlighter
+  if (globalThis.__voltroShikiHighlighterPromise) {
+    return globalThis.__voltroShikiHighlighterPromise
+  }
+  globalThis.__voltroShikiHighlighterPromise = (async () => {
+    const { createHighlighter } = await import('shiki')
+    const highlighter = await createHighlighter({
+      themes: ['github-dark-dimmed', 'github-light'],
+      langs: SHIKI_LANGS as unknown as string[],
+    })
+    globalThis.__voltroShikiHighlighter = highlighter
+    return highlighter
+  })()
+  return globalThis.__voltroShikiHighlighterPromise
+}
+
+/** Promise that resolves once Shiki has loaded — for SSR/build callers
+ *  that want to await before rendering. */
+export const whenHighlighterReady = (): Promise<void> =>
+  ensure().then(() => { /* discard */ })
+
+const escapeHtml = (s: string): string =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+interface HighlightedCodeProps {
+  readonly code: string
+  readonly lang?: ShikiLang
+  /** Outer wrapper class. */
+  readonly className?: string
+}
+
+export const HighlightedCode = ({
+  code, lang = 'ts', className,
+}: HighlightedCodeProps): ReactNode => {
+  const [html, setHtml] = useState<string | null>(null)
+
+  // Render the highlighted HTML when Shiki is ready. Re-runs only when
+  // code/lang changes — the highlighter itself is stable.
+  useEffect(() => {
+    let cancelled = false
+    ensure().then((hl) => {
+      if (cancelled || !hl) return
+      try {
+        const out = hl.codeToHtml(code, {
+          lang,
+          themes: { light: 'github-light', dark: 'github-dark-dimmed' },
+          defaultColor: false,
+        })
+        setHtml(out)
+      } catch {
+        // Lang missing → fall through to plain escaped code.
+      }
+    })
+    return () => { cancelled = true }
+  }, [code, lang])
+
+  // Cached escaped fallback — what renders before Shiki ships its
+  // first highlighted batch.
+  const fallback = useMemo(() => escapeHtml(code), [code])
+
+  if (html) {
+    return (
+      <div
+        className={cn(
+          'text-sm leading-relaxed [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:p-5 overflow-x-auto',
+          className,
+        )}
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    )
+  }
+  return (
+    <pre className={cn('p-5 text-sm leading-relaxed overflow-x-auto font-mono', className)}>
+      <code dangerouslySetInnerHTML={{ __html: fallback }} />
+    </pre>
+  )
+}

package/src/primitives/input.tsx

@@ -0,0 +1,25 @@
+// shadcn Input — minimal HTML input with theme-aware styles.
+
+import type { InputHTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+export const Input = ({ className, type = 'text', ...props }: InputHTMLAttributes<HTMLInputElement>): ReactNode => (
+  <input
+    type={type}
+    data-slot="input"
+    className={cn(
+      'flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs',
+      'transition-[color,box-shadow] outline-none',
+      'file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium',
+      'placeholder:text-muted-foreground',
+      'selection:bg-primary selection:text-primary-foreground',
+      'dark:bg-input/30',
+      'disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50',
+      'md:text-sm',
+      'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+      'aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive',
+      className,
+    )}
+    {...props}
+  />
+)

package/src/primitives/label.tsx

@@ -0,0 +1,19 @@
+// shadcn Label — paired with form inputs for accessible naming.
+
+import type { LabelHTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+export const Label = ({ className, children, ...props }: LabelHTMLAttributes<HTMLLabelElement>): ReactNode => (
+  <label
+    data-slot="label"
+    className={cn(
+      'flex items-center gap-2 text-sm leading-none font-medium select-none',
+      'group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50',
+      'peer-disabled:cursor-not-allowed peer-disabled:opacity-50',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+  </label>
+)