@voltro/ui-shadcn 0.1.0

package/src/brand/assets/voltro-icon-dark.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none" role="img" aria-label="Voltro">
+  <!-- Dark variant: glowing violet bolt on a near-black violet-tinted squircle.
+       Matches the dark product aesthetic; great for dark-mode favicons / OG. -->
+  <defs>
+    <linearGradient id="voltroIconDarkBg" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#1B1726"/>
+      <stop offset="1" stop-color="#120F1A"/>
+    </linearGradient>
+    <radialGradient id="voltroIconDarkGlow" cx="0.5" cy="0.46" r="0.5">
+      <stop stop-color="#7C3AED" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#7C3AED" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="voltroIconDarkFront" x1="13" y1="5" x2="33" y2="43" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#C4A6FF"/>
+      <stop offset="1" stop-color="#9D5BFF"/>
+    </linearGradient>
+    <linearGradient id="voltroIconDarkBack" x1="22" y1="5" x2="35" y2="43" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#A874FF"/>
+      <stop offset="1" stop-color="#7C3AED"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14.5" fill="url(#voltroIconDarkBg)"/>
+  <ellipse cx="32" cy="30" rx="26" ry="26" fill="url(#voltroIconDarkGlow)"/>
+  <path transform="translate(8 8)" d="M28 5 13 27 22 26 20 43Z" fill="url(#voltroIconDarkFront)"/>
+  <path transform="translate(8 8)" d="M28 5 20 43 35 21 26 22Z" fill="url(#voltroIconDarkBack)"/>
+</svg>

package/src/brand/assets/voltro-icon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none" role="img" aria-label="Voltro">
+  <!-- Primary app / advertising icon: two-tone bolt (white + pale violet) on
+       the brand violet squircle. Keeps the folded-light look — not a flat
+       glyph — while staying legible. Self-contained bg → works anywhere. -->
+  <defs>
+    <linearGradient id="voltroIconBg" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#8B5CFF"/>
+      <stop offset="1" stop-color="#6D28D9"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14.5" fill="url(#voltroIconBg)"/>
+  <path transform="translate(8 8)" d="M28 5 13 27 22 26 20 43Z" fill="#FFFFFF"/>
+  <path transform="translate(8 8)" d="M28 5 20 43 35 21 26 22Z" fill="#D7C4FF"/>
+</svg>

package/src/brand/assets/voltro-mark-mono.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48" fill="currentColor" role="img" aria-label="Voltro">
+  <!-- Single-colour mark. Inherits `color` via currentColor — drop it on any
+       surface and it adapts to light/dark. Override with fill="#7C3AED" etc. -->
+  <path d="M28 5 13 27 22 26 20 43 35 21 26 22Z"/>
+</svg>

package/src/brand/assets/voltro-mark.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48" fill="none" role="img" aria-label="Voltro">
+  <defs>
+    <linearGradient id="voltroMarkFront" x1="13" y1="5" x2="33" y2="43" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#A874FF"/>
+      <stop offset="1" stop-color="#7C3AED"/>
+    </linearGradient>
+    <linearGradient id="voltroMarkBack" x1="22" y1="5" x2="35" y2="43" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#6D28D9"/>
+      <stop offset="1" stop-color="#4C1D95"/>
+    </linearGradient>
+  </defs>
+  <path d="M28 5 13 27 22 26 20 43Z" fill="url(#voltroMarkFront)"/>
+  <path d="M28 5 20 43 35 21 26 22Z" fill="url(#voltroMarkBack)"/>
+</svg>

package/src/brand/voltroLogo.tsx

@@ -0,0 +1,244 @@
+// Voltro brand mark — the company + framework logo.
+//
+// The mark is a faceted lightning bolt ("volt") that also reads as the
+// "V" of Voltro: two folded facets catch light off a central crease, so
+// it has depth at billboard size yet stays legible as a 16px favicon.
+// On-brand violet (oklch(0.55 0.25 290) ≈ #7C3AED — the same hue the
+// text-gradient + mesh backdrop use).
+//
+//   ▲  VoltroMark      — the bolt alone. variant: gradient | mono | white.
+//   ◳  VoltroIcon      — app/ad icon: bolt on a rounded "squircle".
+//   ▦  VoltroWordmark  — mark + "Voltro" set in the current font.
+//
+// Every app consumes ONE source: `import { VoltroMark } from
+// '@voltro/ui-shadcn'`. `mono` paints in `currentColor`, so it inherits
+// the surrounding text colour and is automatically correct in light AND
+// dark mode. The gradient + icon variants carry their own colour and
+// work on any background. For static assets (favicon, OG image, app-store
+// icon) use the sibling `assets/*.svg` files.
+
+import type { CSSProperties, ReactNode, SVGProps } from 'react'
+import { useId } from 'react'
+import { cn } from '../cn'
+
+// The bolt geometry, authored once in a 48×48 box and reused everywhere.
+// Sharp joins read as "electric"; the facets share the crease T→C.
+const BOLT_FULL = 'M28 5 13 27 22 26 20 43 35 21 26 22Z' // outer silhouette (one fill)
+const BOLT_FRONT = 'M28 5 13 27 22 26 20 43Z' // left / lit facet
+const BOLT_BACK = 'M28 5 20 43 35 21 26 22Z' // right / shaded facet
+
+/** Brand violet — the canonical primary. Exposed for ad-hoc usage. */
+export const VOLTRO_VIOLET = '#7C3AED'
+
+export type VoltroMarkVariant = 'gradient' | 'mono' | 'white'
+
+// The component owns the structural attrs (viewBox / fill / xmlns / children) and
+// the a11y trio (role / aria-label / aria-hidden, driven by `title`), so they are
+// excluded from the pass-through: leaving them in would let the last-spread `rest`
+// clobber the component's own literals with `T | undefined`, which trips a strict
+// consumer's `exactOptionalPropertyTypes` (the mark typechecks in its own project but
+// broke when a downstream app compiled this source under that flag).
+//
+// `ref` is excluded too, and for a different reason: this is a plain function
+// component (not `forwardRef`), so it never wires a ref anywhere — the prop was
+// never honoured. Keeping it in the pass-through also spreads `SVGProps['ref']`
+// onto the `<svg>`; when a downstream app compiles THIS source, that `ref` type
+// resolves against the framework's `@types/react` copy while the intrinsic `<svg>`
+// resolves against the app's own copy. Same version, but two structurally-distinct
+// `Ref`/`VoidOrUndefinedOnly` types → TS reports them as "unrelated" and the spread
+// fails. Dropping `ref` from the surface removes the dead prop and the clash at once.
+export interface VoltroMarkProps
+  extends Omit<
+    SVGProps<SVGSVGElement>,
+    'width' | 'height' | 'viewBox' | 'fill' | 'xmlns' | 'children' | 'ref' | 'role' | 'aria-label' | 'aria-hidden'
+  > {
+  /** Pixel size (square). Default 32. Pass a string like '1em' to track font-size. */
+  readonly size?: number | string
+  /** `gradient` (default, two-facet violet) · `mono` (currentColor) · `white`. */
+  readonly variant?: VoltroMarkVariant
+  /** Accessible label. Omit + set `aria-hidden` when paired with a text label. */
+  readonly title?: string
+}
+
+/** The bolt mark on a transparent background. */
+export const VoltroMark = ({
+  size = 32,
+  variant = 'gradient',
+  title,
+  className,
+  ...rest
+}: VoltroMarkProps): ReactNode => {
+  const uid = useId()
+  const front = `vmF-${uid}`
+  const back = `vmB-${uid}`
+  const labelled = title !== undefined
+  // One non-union type: explicit `role={... : undefined}` props violate
+  // exactOptionalPropertyTypes, and a conditional-spread union chokes older
+  // checkers in cross-repo consumers.
+  const a11y: Pick<SVGProps<SVGSVGElement>, 'role' | 'aria-label' | 'aria-hidden'> = labelled
+    ? { role: 'img', 'aria-label': title }
+    : { 'aria-hidden': true }
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 48 48"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...a11y}
+      className={cn('inline-block shrink-0', className)}
+      {...rest}
+    >
+      {variant === 'gradient' ? (
+        <>
+          <defs>
+            <linearGradient id={front} x1="13" y1="5" x2="33" y2="43" gradientUnits="userSpaceOnUse">
+              <stop stopColor="#A874FF" />
+              <stop offset="1" stopColor="#7C3AED" />
+            </linearGradient>
+            <linearGradient id={back} x1="22" y1="5" x2="35" y2="43" gradientUnits="userSpaceOnUse">
+              <stop stopColor="#6D28D9" />
+              <stop offset="1" stopColor="#4C1D95" />
+            </linearGradient>
+          </defs>
+          <path d={BOLT_FRONT} fill={`url(#${front})`} />
+          <path d={BOLT_BACK} fill={`url(#${back})`} />
+        </>
+      ) : (
+        <path d={BOLT_FULL} fill={variant === 'white' ? '#FFFFFF' : 'currentColor'} />
+      )}
+    </svg>
+  )
+}
+
+export type VoltroIconTone = 'brand' | 'dark'
+
+export interface VoltroIconProps {
+  /** Pixel size (square). Default 40. */
+  readonly size?: number
+  /** `brand` (violet squircle + white bolt — works on any surface) · `dark` (near-black squircle + glowing violet bolt). */
+  readonly tone?: VoltroIconTone
+  /** Corner radius as a fraction of size. Default 0.225 (iOS-style squircle look). */
+  readonly radius?: number
+  readonly title?: string
+  readonly className?: string
+  readonly style?: CSSProperties
+}
+
+/**
+ * The app / advertising icon: the bolt centred on a rounded square with
+ * its own background, so it stands on a home screen, store listing, or
+ * ad placement regardless of the surface behind it.
+ */
+export const VoltroIcon = ({
+  size = 40,
+  tone = 'brand',
+  radius = 0.225,
+  title = 'Voltro',
+  className,
+  style,
+}: VoltroIconProps): ReactNode => {
+  const uid = useId()
+  const bg = `viBg-${uid}`
+  const glow = `viGlow-${uid}`
+  const front = `viF-${uid}`
+  const back = `viB-${uid}`
+  const rx = (64 * radius).toFixed(2)
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 64 64"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      role="img"
+      aria-label={title}
+      className={cn('inline-block shrink-0', className)}
+      style={style}
+    >
+      <defs>
+        <linearGradient id={bg} x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+          {tone === 'brand' ? (
+            <>
+              <stop stopColor="#8B5CFF" />
+              <stop offset="1" stopColor="#6D28D9" />
+            </>
+          ) : (
+            <>
+              <stop stopColor="#1B1726" />
+              <stop offset="1" stopColor="#120F1A" />
+            </>
+          )}
+        </linearGradient>
+        {tone === 'dark' ? (
+          <radialGradient id={glow} cx="0.5" cy="0.46" r="0.5">
+            <stop stopColor="#7C3AED" stopOpacity="0.55" />
+            <stop offset="1" stopColor="#7C3AED" stopOpacity="0" />
+          </radialGradient>
+        ) : null}
+        <linearGradient id={front} x1="13" y1="5" x2="33" y2="43" gradientUnits="userSpaceOnUse">
+          <stop stopColor="#C4A6FF" />
+          <stop offset="1" stopColor="#9D5BFF" />
+        </linearGradient>
+        <linearGradient id={back} x1="22" y1="5" x2="35" y2="43" gradientUnits="userSpaceOnUse">
+          <stop stopColor="#A874FF" />
+          <stop offset="1" stopColor="#7C3AED" />
+        </linearGradient>
+      </defs>
+
+      <rect width="64" height="64" rx={rx} fill={`url(#${bg})`} />
+      {tone === 'brand' ? (
+        // Two-tone bolt — white front facet + pale-violet back facet keep the
+        // folded-light identity readable on the violet field (not a flat glyph).
+        <>
+          <path transform="translate(8 8)" d={BOLT_FRONT} fill="#FFFFFF" />
+          <path transform="translate(8 8)" d={BOLT_BACK} fill="#D7C4FF" />
+        </>
+      ) : (
+        <>
+          <ellipse cx="32" cy="30" rx="26" ry="26" fill={`url(#${glow})`} />
+          <path transform="translate(8 8)" d={BOLT_FRONT} fill={`url(#${front})`} />
+          <path transform="translate(8 8)" d={BOLT_BACK} fill={`url(#${back})`} />
+        </>
+      )}
+    </svg>
+  )
+}
+
+export interface VoltroWordmarkProps {
+  /** Mark height in px; the wordmark text scales with it. Default 28. */
+  readonly size?: number
+  readonly markVariant?: VoltroMarkVariant
+  /** Wordmark label. Default "Voltro". */
+  readonly label?: string
+  readonly className?: string
+  readonly style?: CSSProperties
+}
+
+/**
+ * Mark + wordmark lock-up for headers / marketing. The text is real
+ * type set in the surrounding font and `currentColor`, so it inherits
+ * the app's typography and is correct in light + dark automatically.
+ */
+export const VoltroWordmark = ({
+  size = 28,
+  markVariant = 'gradient',
+  label = 'Voltro',
+  className,
+  style,
+}: VoltroWordmarkProps): ReactNode => (
+  <span
+    className={cn('inline-flex items-center font-semibold tracking-tight leading-none', className)}
+    style={{ gap: size * 0.28, fontSize: size * 0.74, ...style }}
+  >
+    {/* Mark rendered larger than the cap height so the bolt reads as the
+        lead element, not a small adornment beside the wordmark. */}
+    <VoltroMark size={Math.round(size * 1.18)} variant={markVariant} aria-hidden />
+    <span>{label}</span>
+  </span>
+)
+
+/** Raw bolt path data, for apps that need to compose their own SVG. */
+export const VOLTRO_BOLT_PATH = { full: BOLT_FULL, front: BOLT_FRONT, back: BOLT_BACK } as const

package/src/cn.ts

@@ -0,0 +1,10 @@
+// Class-name composition helper used by every shadcn primitive.
+// clsx handles conditional / array / object forms; tailwind-merge
+// dedupes conflicting Tailwind utilities (e.g. `px-2 px-4` → `px-4`).
+// Exported as a tiny subpath so consumers can grab it without
+// pulling the entire `@voltro/ui-shadcn` surface.
+
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export const cn = (...inputs: ClassValue[]): string => twMerge(clsx(inputs))

package/src/compositions/appShell.tsx

@@ -0,0 +1,72 @@
+// AppShell composition — topbar + main scroll region. Used by the
+// dashboard, portal, admin templates as the authenticated-app skeleton.
+// The shell itself is dumb; auth gates / sidebar collapse / search /
+// command palette layer on top.
+//
+// `LinkComponent` lets apps pass `Link` from `@voltro/web` so the
+// top nav uses client-side routing + loader prefetch instead of full
+// page reloads. Default is plain `<a>` so the kit stays
+// router-agnostic.
+//
+// The top bar chrome (sticky, glass-on-scroll, h-16, max-w-7xl) is
+// the shared <PageHeader> — same one consumed by DocsLayout and by
+// landing / marketplace pages directly. That's the single visual
+// source of truth across the four sibling apps; do not duplicate
+// the header treatment here.
+
+import type { ComponentType, ReactNode } from 'react'
+import { cn } from '../cn'
+import type { ShellLinkProps } from './docShell'
+import { PageHeader } from './pageHeader'
+
+interface NavLink {
+  readonly label: string
+  readonly href: string
+}
+
+interface AppShellProps {
+  readonly brand: ReactNode
+  readonly nav?: ReadonlyArray<NavLink>
+  readonly right?: ReactNode
+  readonly children: ReactNode
+  readonly className?: string
+  readonly LinkComponent?: ComponentType<ShellLinkProps>
+}
+
+const PlainLink = ({ to, className, children }: ShellLinkProps): ReactNode => (
+  <a href={to} className={className}>{children}</a>
+)
+
+export const AppShell = ({
+  brand, nav, right, children, className,
+  LinkComponent = PlainLink,
+}: AppShellProps): ReactNode => {
+  const Link = LinkComponent
+  return (
+    <div className={cn('min-h-screen flex flex-col bg-background text-foreground', className)}>
+      <PageHeader>
+        <div className="font-semibold flex items-center gap-2">{brand}</div>
+        <div className="flex items-center gap-6">
+          {nav && nav.length > 0 ? (
+            <nav className="hidden md:flex gap-6 text-sm">
+              {nav.map((l) => (
+                <Link
+                  key={l.href}
+                  to={l.href}
+                  prefetch
+                  className="text-muted-foreground hover:text-foreground transition-colors"
+                >
+                  {l.label}
+                </Link>
+              ))}
+            </nav>
+          ) : null}
+          {right ? <div>{right}</div> : null}
+        </div>
+      </PageHeader>
+      <main className="flex-1">{children}</main>
+    </div>
+  )
+}
+
+

package/src/compositions/codeCompare.tsx

@@ -0,0 +1,88 @@
+// CodeCompare — side-by-side "before / after" code panels. Common
+// landing-page pattern for dev tooling: left = the messy world,
+// right = your product's clean replacement. The dividing label sits
+// in the centre on desktop, between the two panels on mobile.
+
+import type { ReactNode } from 'react'
+import { cn } from '../cn'
+import { HighlightedCode, type ShikiLang } from '../primitives/highlightedCode'
+
+interface CodeComparePanelProps {
+  readonly label: ReactNode
+  /** Pre-highlighted HTML (Shiki) — skips internal highlighting. */
+  readonly html?: string
+  /** Plain code text. When `lang` is also provided, the panel
+   *  runs Shiki syntax highlighting automatically. */
+  readonly code?: string
+  /** Shiki language. Triggers syntax highlighting on `code`. */
+  readonly lang?: ShikiLang
+  /** Visual treatment — `'muted'` is dimmed (the "before"),
+   *  `'highlight'` keeps the full styling + adds a primary border. */
+  readonly tone?: 'muted' | 'highlight'
+}
+
+interface CodeCompareProps {
+  readonly before: CodeComparePanelProps
+  readonly after: CodeComparePanelProps
+  readonly className?: string
+}
+
+const Panel = ({ label, html, code, lang, tone = 'muted' }: CodeComparePanelProps): ReactNode => (
+  <div
+    className={cn(
+      'relative rounded-xl border overflow-hidden bg-card/40 backdrop-blur-sm',
+      tone === 'highlight'
+        ? 'border-primary/40 shadow-[0_0_0_1px_oklch(0.55_0.25_290_/_0.15),0_12px_40px_-12px_oklch(0.55_0.25_290_/_0.35)]'
+        : 'border-border',
+    )}
+  >
+    <div className="flex items-center justify-between px-4 py-2 border-b border-border/60 bg-background/40">
+      <div className="text-xs font-mono text-muted-foreground">{label}</div>
+      <span
+        className={cn(
+          'text-[0.65rem] uppercase tracking-[0.08em] font-semibold',
+          tone === 'highlight' ? 'text-primary' : 'text-muted-foreground/70',
+        )}
+      >
+        {tone === 'highlight' ? 'With Voltro' : 'Before'}
+      </span>
+    </div>
+    <div
+      className={cn(
+        'text-sm leading-relaxed [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:p-5 overflow-x-auto',
+        tone === 'muted' && 'opacity-60',
+      )}
+    >
+      {html ? (
+        <div dangerouslySetInnerHTML={{ __html: html }} />
+      ) : code && lang ? (
+        <HighlightedCode code={code} lang={lang} />
+      ) : (
+        <pre className="p-5 font-mono"><code>{code}</code></pre>
+      )}
+    </div>
+  </div>
+)
+
+export const CodeCompare = ({
+  before, after, className,
+}: CodeCompareProps): ReactNode => (
+  <div className={cn('relative grid grid-cols-1 lg:grid-cols-[1fr_auto_1fr] gap-4 lg:gap-6 items-stretch', className)}>
+    <Panel {...before} tone="muted" />
+    {/* Arrow / divider — sits between the two panels */}
+    <div
+      className="flex lg:flex-col items-center justify-center gap-2 text-muted-foreground"
+      aria-hidden="true"
+    >
+      <div className="hidden lg:block w-px h-12 bg-gradient-to-b from-transparent via-primary/60 to-transparent" />
+      <svg
+        width="20" height="20" viewBox="0 0 20 20" fill="none"
+        className="rotate-90 lg:rotate-0 text-primary"
+      >
+        <path d="M4 10 H16 M11 5 L16 10 L11 15" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+      <div className="hidden lg:block w-px h-12 bg-gradient-to-b from-primary/60 via-transparent to-transparent" />
+    </div>
+    <Panel {...after} tone="highlight" />
+  </div>
+)

package/src/compositions/docShell.tsx

@@ -0,0 +1,112 @@
+// DocShell composition — sidebar + main grid for documentation.
+// Sidebar nav is data-driven (group → entry tree); apps pass their
+// own structure. Sticky sidebar, scrollable main, responsive collapse
+// to single-column under 800px.
+//
+// `LinkComponent` lets the app inject a client-side router (e.g.
+// `Link` from `@voltro/web`) so sidebar nav doesn't trigger full
+// page reloads. Default is plain `<a>` so the kit stays
+// router-agnostic and works in any host.
+
+import type { ComponentType, ReactNode } from 'react'
+import { cn } from '../cn'
+
+export interface DocNavEntry {
+  readonly label: string
+  readonly href: string
+}
+
+export interface DocNavGroup {
+  readonly section: string
+  readonly entries: ReadonlyArray<DocNavEntry>
+}
+
+// Minimal Link prop surface — matches @voltro/web's Link with `to`,
+// and degrades cleanly to a plain <a href> when not provided.
+export interface ShellLinkProps {
+  readonly to: string
+  readonly className?: string
+  readonly children: ReactNode
+  /** Pre-warm the destination on hover/focus. */
+  readonly prefetch?: boolean
+}
+
+interface DocShellProps {
+  readonly brand: ReactNode
+  readonly nav: ReadonlyArray<DocNavGroup>
+  readonly children: ReactNode
+  readonly currentPath?: string
+  readonly className?: string
+  /** Search form GET action. When set, renders a search input that
+   *  POSTs ?q=… to this URL. */
+  readonly searchAction?: string
+  /** Placeholder for the search input. Default `'Search docs…'`. */
+  readonly searchPlaceholder?: string
+  /** `aria-label` for the search input. Default `'Search docs'`. */
+  readonly searchLabel?: string
+  /** Optional client-router Link. Passing `Link` from `@voltro/web`
+   *  upgrades every sidebar entry to client-side navigation with
+   *  loader prefetch. */
+  readonly LinkComponent?: ComponentType<ShellLinkProps>
+}
+
+const PlainLink = ({ to, className, children }: ShellLinkProps): ReactNode => (
+  <a href={to} className={className}>{children}</a>
+)
+
+export const DocShell = ({
+  brand, nav, children, currentPath, className, searchAction,
+  searchPlaceholder = 'Search docs…', searchLabel = 'Search docs',
+  LinkComponent = PlainLink,
+}: DocShellProps): ReactNode => {
+  const Link = LinkComponent
+  return (
+    <div className={cn('min-h-screen grid grid-cols-1 md:grid-cols-[260px_1fr] bg-background text-foreground', className)}>
+      <aside className="border-r bg-card/30 p-6 md:sticky md:top-0 md:h-screen md:overflow-y-auto">
+        <div className="mb-6">{brand}</div>
+        {searchAction ? (
+          <form method="get" action={searchAction} className="mb-6">
+            <input
+              type="search"
+              name="q"
+              placeholder={searchPlaceholder}
+              aria-label={searchLabel}
+              className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm outline-none focus:ring-2 focus:ring-ring"
+            />
+          </form>
+        ) : null}
+        {nav.map((group) => (
+          <div key={group.section} className="mb-6">
+            <h4 className="text-xs uppercase tracking-wider text-muted-foreground font-medium mb-2">
+              {group.section}
+            </h4>
+            <ul className="space-y-0.5">
+              {group.entries.map((e) => {
+                const active = currentPath === e.href
+                return (
+                  <li key={e.href}>
+                    <Link
+                      to={e.href}
+                      prefetch
+                      className={cn(
+                        'block rounded-md px-2 py-1.5 text-sm transition-colors',
+                        active
+                          ? 'bg-accent text-accent-foreground font-medium'
+                          : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground',
+                      )}
+                    >
+                      {e.label}
+                    </Link>
+                  </li>
+                )
+              })}
+            </ul>
+          </div>
+        ))}
+      </aside>
+      <main className="p-8 md:p-12 lg:p-16 max-w-3xl text-foreground">
+        {children}
+      </main>
+    </div>
+  )
+}