@voltro/ui-shadcn 0.1.0

package/src/cookies.ts

@@ -0,0 +1,109 @@
+// User-preference cookies — the canonical names the framework's pre-paint
+// theme script + auto-wired i18n resolver agree on (innovation/00). The kit's
+// ProfileMenu / ThemeToggle write them; the server parses them at SSR time.
+//
+// Why cookies (and not localStorage)? Cookies travel on every HTTP request,
+// so the SERVER can read them and bake the correct HTML (dark class,
+// translated strings) BEFORE first paint — no theme/locale flash.
+// localStorage is browser-only and would force a post-hydration flicker.
+//
+// Every helper is isomorphic: pass the request `Cookie` header on the server,
+// omit it in the browser (falls back to `document.cookie`).
+
+export const THEME_COOKIE = 'voltro:theme'
+export const LANG_COOKIE = 'voltro:lang'
+
+export type ThemePreference = 'system' | 'light' | 'dark'
+
+const isThemePreference = (v: string): v is ThemePreference =>
+  v === 'system' || v === 'light' || v === 'dark'
+
+// 400 days — Chrome caps cookie lifetime at 400d (RFC 6265bis). Picking the
+// max so the preference survives long absences without being silently
+// re-defaulted.
+const DEFAULT_MAX_AGE_SEC = 60 * 60 * 24 * 400
+
+/** Read a cookie by name from a header string (SSR: the request `Cookie`
+ *  header) or, when omitted, `document.cookie` (browser). Returns undefined
+ *  when absent or off-document. */
+export const getCookie = (name: string, cookieHeader?: string): string | undefined => {
+  const header = cookieHeader ?? (typeof document !== 'undefined' ? document.cookie : '')
+  if (!header) return undefined
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    if (part.slice(0, eq).trim() === name) {
+      try { return decodeURIComponent(part.slice(eq + 1).trim()) } catch { return part.slice(eq + 1).trim() }
+    }
+  }
+  return undefined
+}
+
+export interface SetCookieOptions {
+  /** Default: 400 days (Chrome's cap). Pass 0 to delete the cookie. */
+  readonly maxAgeSeconds?: number
+  /** Default: '/' — preference applies app-wide. */
+  readonly path?: string
+  /** Default: 'lax' — allows top-level navigation but blocks cross-site
+   *  XHR, which is what preference cookies want. 'none' implies `Secure`
+   *  (modern browsers reject a SameSite=None cookie without it). */
+  readonly sameSite?: 'lax' | 'strict' | 'none'
+}
+
+/** Build a `Set-Cookie`-style string AND, in the browser, write it to
+ *  `document.cookie`. Returns the string so SSR callers can emit a header. */
+export const setCookie = (name: string, value: string, options: SetCookieOptions = {}): string => {
+  const { maxAgeSeconds = DEFAULT_MAX_AGE_SEC, path = '/', sameSite = 'lax' } = options
+  const parts = [
+    `${name}=${encodeURIComponent(value)}`,
+    `Path=${path}`,
+    `Max-Age=${maxAgeSeconds}`,
+    `SameSite=${sameSite}`,
+  ]
+  if (sameSite === 'none') parts.push('Secure')
+  const cookie = parts.join('; ')
+  if (typeof document !== 'undefined') document.cookie = cookie
+  return cookie
+}
+
+/** Expire a cookie (Max-Age=0). Same isomorphic contract as `setCookie`:
+ *  writes `document.cookie` in the browser, returns the header string. */
+export const deleteCookie = (name: string, path = '/'): string =>
+  setCookie(name, '', { maxAgeSeconds: 0, path })
+
+export interface PreferenceCookies {
+  /** undefined → server should fall back to its default (typically the
+   *  app config's theme). 'system' means the client's pre-paint script
+   *  decides against `prefers-color-scheme`. */
+  readonly theme?: ThemePreference
+  /** Language code as written by the client. Consumer decides which codes
+   *  are valid + how to fall back if the value is unknown. */
+  readonly lang?: string
+}
+
+/** Extract both preference cookies (theme + lang) from a cookie header (or
+ *  `document.cookie` when omitted). Tolerates `null`/`undefined` headers.
+ *  An invalid theme value is dropped (not coerced); an empty lang is dropped. */
+export const parsePreferenceCookies = (cookieHeader?: string | null): PreferenceCookies => {
+  const header = cookieHeader ?? undefined
+  const themeRaw = getCookie(THEME_COOKIE, header)
+  const lang = getCookie(LANG_COOKIE, header)
+  return {
+    ...(themeRaw !== undefined && isThemePreference(themeRaw) ? { theme: themeRaw } : {}),
+    ...(lang !== undefined && lang !== '' ? { lang } : {}),
+  }
+}
+
+/** Apply a theme preference to `<html>` (browser only) — adds/removes the
+ *  `dark` class, resolving `system` against `prefers-color-scheme`. The kit's
+ *  ProfileMenu / ThemeToggle call this after writing the cookie so the change
+ *  is immediate (the pre-paint `themeBootScript` handles the first load). */
+export const applyTheme = (theme: ThemePreference): void => {
+  if (typeof document === 'undefined') return
+  const dark =
+    theme === 'dark' ||
+    (theme === 'system' &&
+      typeof window !== 'undefined' &&
+      window.matchMedia?.('(prefers-color-scheme: dark)').matches === true)
+  document.documentElement.classList.toggle('dark', dark)
+}

package/src/index.ts

@@ -0,0 +1,160 @@
+// @voltro/ui-shadcn — Voltro's first-party shadcn/ui kit.
+//
+// Surfaces:
+//
+//   Widgets      — `shadcnWidgets`: Tailwind-styled implementations of the
+//                  @voltro/ui widget seam. Drop into
+//                  `<WidgetRegistryProvider>` to style every AutoForm.
+//
+//   Primitives   — Button/Card/Input/… wrap an HTML element with
+//                  theme-aware styles. Copy into your project if you want
+//                  to own them outright; importing here works when you
+//                  don't want to diverge from the framework's defaults.
+//
+//   Compositions — opinionated layouts (LoginCard, HeroSection, DocShell,
+//                  AppShell, DocsLayout, ProfileMenu, ThemeToggle).
+//                  Updated as the framework evolves. Apps adopting them
+//                  get design refreshes for free.
+//
+//   Cookies      — the canonical `voltro:theme` / `voltro:lang`
+//                  preference-cookie helpers the framework's SSR theme +
+//                  i18n resolution agree on.
+//
+// Tokens live in `@voltro/ui-shadcn/tokens.css`. Import it once at the top
+// of your app's globals.css; add the kit `@source` so Tailwind scans the
+// kit's classes (see the tokens.css header / the styling docs).
+
+export const UI_SHADCN_NAME = 'framework-ui-shadcn' as const
+
+export { cn } from './cn'
+
+// ---- Widget seam ----
+export { shadcnWidgets } from './widgets'
+
+// ---- User-preference cookies (theme + language) ----
+export {
+  THEME_COOKIE, LANG_COOKIE,
+  getCookie, setCookie, deleteCookie,
+  parsePreferenceCookies, applyTheme,
+} from './cookies'
+export type {
+  ThemePreference, PreferenceCookies, SetCookieOptions,
+} from './cookies'
+
+// ---- Primitives ----
+export { Button, buttonVariants } from './primitives/button'
+export type { ButtonProps } from './primitives/button'
+
+export {
+  Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter,
+} from './primitives/card'
+
+export { Input } from './primitives/input'
+export { Textarea } from './primitives/textarea'
+export { Checkbox, type CheckboxProps } from './primitives/checkbox'
+export { Label } from './primitives/label'
+
+export { Badge, badgeVariants } from './primitives/badge'
+export type { BadgeProps } from './primitives/badge'
+
+export { Separator } from './primitives/separator'
+
+export { Avatar } from './primitives/avatar'
+export { Skeleton } from './primitives/skeleton'
+export { Select } from './primitives/select'
+
+export {
+  Dialog, DialogHeader, DialogTitle, DialogDescription, DialogFooter,
+} from './primitives/dialog'
+
+export {
+  Tabs, TabsList, TabsTrigger, TabsContent,
+} from './primitives/tabs'
+
+export { Toast, ToastTitle, ToastDescription } from './primitives/toast'
+
+export {
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent,
+  DropdownMenuItem, DropdownMenuSeparator, DropdownMenuLabel,
+  DropdownMenuGroup, DropdownMenuPortal,
+  DropdownMenuRadioGroup, DropdownMenuRadioItem,
+} from './primitives/dropdownMenu'
+
+export { Toggle, toggleVariants } from './primitives/toggle'
+export { ToggleGroup, ToggleGroupItem } from './primitives/toggleGroup'
+
+export { LocaleSwitcher } from './primitives/localeSwitcher'
+export type { LocaleSwitcherProps, LocaleOption } from './primitives/localeSwitcher'
+
+// ---- Compositions ----
+export { LoginCard } from './compositions/loginCard'
+export type { LoginCardLabels } from './compositions/loginCard'
+export { HeroSection } from './compositions/heroSection'
+export { FeatureGrid } from './compositions/featureGrid'
+export { DocShell } from './compositions/docShell'
+export type { DocNavEntry, DocNavGroup, ShellLinkProps } from './compositions/docShell'
+export { DocsLayout } from './compositions/docsLayout'
+export type {
+  DocsNavItem, DocsNavGroup, DocsNavSubGroup, DocsTocEntry, DocsBreadcrumb,
+  DocsLayoutLabels,
+} from './compositions/docsLayout'
+export { AppShell } from './compositions/appShell'
+export { PageHeader } from './compositions/pageHeader'
+export { ProfileMenu } from './compositions/profileMenu'
+export type {
+  ProfileMenuProps, ProfileMenuLink, ProfileMenuLanguage, ProfileMenuLabels,
+} from './compositions/profileMenu'
+export { ThemeToggle, themeBootScript } from './compositions/themeToggle'
+
+// ---- Brand ----
+export {
+  VoltroMark, VoltroIcon, VoltroWordmark,
+  VOLTRO_VIOLET, VOLTRO_BOLT_PATH,
+} from './brand/voltroLogo'
+export type {
+  VoltroMarkProps, VoltroMarkVariant,
+  VoltroIconProps, VoltroIconTone,
+  VoltroWordmarkProps,
+} from './brand/voltroLogo'
+
+// ---- Landing-page compositions ----
+export { LandingHero } from './compositions/landingHero'
+export { Bento, BentoCell } from './compositions/featureBento'
+export type { BentoCellProps } from './compositions/featureBento'
+export { CodeCompare } from './compositions/codeCompare'
+export { LandingStats } from './compositions/landingStats'
+export type { StatSpec } from './compositions/landingStats'
+export { LandingCta } from './compositions/landingCta'
+export { SiteFooter, StatusBadge } from './compositions/siteFooter'
+export type {
+  SiteFooterColumn, SiteFooterLink, SiteFooterSocial,
+} from './compositions/siteFooter'
+
+// ---- Backdrop + animation primitives ----
+export { MeshBackdrop } from './primitives/meshBackdrop'
+export { GridOverlay } from './primitives/gridOverlay'
+export { Sparkles } from './primitives/sparkles'
+export { CodeWindow } from './primitives/codeWindow'
+export { ScrollReveal } from './primitives/scrollReveal'
+export { AnimatedNumber } from './primitives/animatedNumber'
+export {
+  HighlightedCode, whenHighlighterReady, SHIKI_LANGS,
+} from './primitives/highlightedCode'
+export type { ShikiLang } from './primitives/highlightedCode'
+
+// ---- Doc-content primitives ----
+export { Callout } from './primitives/callout'
+export { CodeBlock } from './primitives/codeBlock'
+export { Steps, Step } from './primitives/steps'
+export { DocCard, DocCards } from './primitives/docCard'
+export { TocScrollSpy } from './primitives/tocScrollSpy'
+export {
+  RocketIcon, CompassIcon, PackageIcon, FolderIcon, FileIcon,
+  BroadcastIcon, PencilIcon, BellIcon, CogIcon, BuildingIcon,
+  DatabaseIcon, LockIcon, BotIcon, TerminalIcon, LayersIcon,
+  PuzzleIcon, HookIcon, GlobeIcon, CloudIcon, HomeIcon,
+  ChevronLeftIcon, ChevronRightIcon, SearchIcon, ArrowReturnIcon,
+  GitHubIcon, XIcon, DiscordIcon, LinkedInIcon, RssIcon, ChartIcon,
+} from './primitives/docIcons'
+export { SearchModal, SearchTrigger } from './primitives/searchModal'
+export type { SearchModalProps, SearchModalLabels } from './primitives/searchModal'

package/src/primitives/animatedNumber.tsx

@@ -0,0 +1,73 @@
+// AnimatedNumber — counts from 0 to the target value when scrolled
+// into view. Mounts an IntersectionObserver, runs ONE rAF loop for
+// ~700ms, then stops. No re-trigger.
+//
+// Use for the stats row on the landing — gives the impression of
+// "live numbers" without actually polling anything.
+//
+// Respects prefers-reduced-motion (jumps straight to the final value).
+
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+
+interface AnimatedNumberProps {
+  /** Target value. */
+  readonly value: number
+  /** Formatting — `'integer'` (default), `'percent'`, or a custom
+   *  formatter. */
+  readonly format?: 'integer' | 'percent' | ((n: number) => string)
+  /** Animation duration in ms. Default 800. */
+  readonly duration?: number
+}
+
+const fmt = (n: number, format: AnimatedNumberProps['format']): string => {
+  if (typeof format === 'function') return format(n)
+  if (format === 'percent') return `${n.toFixed(0)}%`
+  return Math.round(n).toLocaleString('en-US')
+}
+
+export const AnimatedNumber = ({
+  value, format = 'integer', duration = 800,
+}: AnimatedNumberProps): ReactNode => {
+  const ref = useRef<HTMLSpanElement>(null)
+  const [current, setCurrent] = useState(0)
+
+  useEffect(() => {
+    if (typeof IntersectionObserver === 'undefined') {
+      setCurrent(value)
+      return
+    }
+    const prefersReduced = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+    if (prefersReduced) {
+      setCurrent(value)
+      return
+    }
+    const node = ref.current
+    if (!node) return
+    const observer = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          observer.disconnect()
+          const start = performance.now()
+          const tick = (now: number): void => {
+            const t = Math.min((now - start) / duration, 1)
+            // ease-out cubic — fast at first, gentle stop
+            const eased = 1 - Math.pow(1 - t, 3)
+            setCurrent(value * eased)
+            if (t < 1) requestAnimationFrame(tick)
+            else setCurrent(value)
+          }
+          requestAnimationFrame(tick)
+          return
+        }
+      }
+    }, { threshold: 0.4 })
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [value, duration])
+
+  return (
+    <span ref={ref} className="font-tabular">
+      {fmt(current, format)}
+    </span>
+  )
+}

package/src/primitives/avatar.tsx

@@ -0,0 +1,39 @@
+// shadcn Avatar — circular image with text fallback.
+// Minimal: no async image-state machine, plain <img> + <span> fallback.
+// Upgrade to Radix Avatar when load-state UX matters.
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface AvatarProps extends HTMLAttributes<HTMLDivElement> {
+  readonly src?: string
+  readonly alt?: string
+  readonly fallback?: string
+  readonly size?: 'sm' | 'md' | 'lg'
+}
+
+const sizeClasses = {
+  sm: 'size-6 text-xs',
+  md: 'size-9 text-sm',
+  lg: 'size-12 text-base',
+} as const
+
+export const Avatar = ({ src, alt, fallback, size = 'md', className, ...props }: AvatarProps): ReactNode => (
+  <div
+    data-slot="avatar"
+    className={cn(
+      'relative inline-flex items-center justify-center overflow-hidden rounded-full bg-muted',
+      sizeClasses[size],
+      className,
+    )}
+    {...props}
+  >
+    {src ? (
+      <img src={src} alt={alt ?? ''} className="size-full object-cover" />
+    ) : (
+      <span className="font-medium text-muted-foreground select-none">
+        {fallback ?? '?'}
+      </span>
+    )}
+  </div>
+)

package/src/primitives/badge.tsx

@@ -0,0 +1,39 @@
+// shadcn Badge — small pill for status, tags, count indicators.
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '../cn'
+
+const badgeVariants = cva(
+  'inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 ' +
+  '[&>svg]:size-3 [&>svg]:pointer-events-none gap-1 transition-[color,box-shadow] overflow-hidden ' +
+  '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',
+  {
+    variants: {
+      variant: {
+        default:     'border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+        secondary:   'border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+        destructive: 'border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90',
+        outline:     'text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+)
+
+export interface BadgeProps
+  extends HTMLAttributes<HTMLSpanElement>,
+    VariantProps<typeof badgeVariants> {}
+
+export const Badge = ({ className, variant, children, ...props }: BadgeProps): ReactNode => (
+  <span
+    data-slot="badge"
+    className={cn(badgeVariants({ variant }), className)}
+    {...props}
+  >
+    {children}
+  </span>
+)
+
+export { badgeVariants }

package/src/primitives/button.tsx

@@ -0,0 +1,53 @@
+// shadcn Button — variants via class-variance-authority. Drops the
+// `asChild` slot escape hatch in V1 to keep transitive dependencies
+// minimal; reach for the dashboard's full component if you need it.
+
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '../cn'
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium " +
+  "transition-all disabled:pointer-events-none disabled:opacity-50 " +
+  "[&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 " +
+  "outline-none 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 cursor-pointer",
+  {
+    variants: {
+      variant: {
+        default:     'bg-primary text-primary-foreground shadow-xs hover:bg-primary/90',
+        destructive: 'bg-destructive text-destructive-foreground shadow-xs hover:bg-destructive/90',
+        outline:     'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground ' +
+                     'dark:bg-input/30 dark:border-input dark:hover:bg-input/50',
+        secondary:   'bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80',
+        ghost:       'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
+        link:        'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+        sm:      'h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5',
+        lg:      'h-10 rounded-md px-6 has-[>svg]:px-4',
+        icon:    'size-9',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'default' },
+  },
+)
+
+export interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export const Button = ({
+  className, variant, size, children, ...props
+}: ButtonProps): ReactNode => (
+  <button
+    data-slot="button"
+    className={cn(buttonVariants({ variant, size, className }))}
+    {...props}
+  >
+    {children}
+  </button>
+)
+
+export { buttonVariants }

package/src/primitives/callout.tsx

@@ -0,0 +1,97 @@
+// Callout — coloured note box for docs content. Four variants matching
+// the Fumadocs/Docusaurus convention: info (default), tip, warning,
+// danger. Uses semantic CSS tokens so dark/light both work without
+// per-variant overrides in app code.
+//
+// Usage:
+//   <Callout type="warning" title="Heads up">
+//     This API is still pre-release. Names + shape can change.
+//   </Callout>
+
+import type { ReactNode } from 'react'
+import { cn } from '../cn'
+
+type CalloutType = 'info' | 'tip' | 'warning' | 'danger' | 'note'
+
+interface CalloutProps {
+  readonly type?: CalloutType
+  readonly title?: ReactNode
+  readonly children: ReactNode
+  readonly className?: string
+}
+
+const styles: Record<CalloutType, { ring: string; icon: string; iconPath: ReactNode }> = {
+  info: {
+    ring: 'border-info/30 bg-info/5 text-info',
+    icon: 'text-info',
+    iconPath: (
+      <>
+        <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="1.5" />
+        <path d="M8 5.5 V8.5 M8 10.5 V11" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+      </>
+    ),
+  },
+  tip: {
+    ring: 'border-success/30 bg-success/5 text-success',
+    icon: 'text-success',
+    iconPath: (
+      <>
+        <path d="M5 8.5 L7 10.5 L11 6" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+        <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="1.5" />
+      </>
+    ),
+  },
+  warning: {
+    ring: 'border-warning/30 bg-warning/5 text-warning',
+    icon: 'text-warning',
+    iconPath: (
+      <>
+        <path d="M8 2 L14 13 L2 13 Z" stroke="currentColor" strokeWidth="1.5" strokeLinejoin="round" />
+        <path d="M8 6.5 V9 M8 10.5 V11" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+      </>
+    ),
+  },
+  danger: {
+    ring: 'border-destructive/40 bg-destructive/5 text-destructive',
+    icon: 'text-destructive',
+    iconPath: (
+      <>
+        <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="1.5" />
+        <path d="M5.5 5.5 L10.5 10.5 M10.5 5.5 L5.5 10.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+      </>
+    ),
+  },
+  note: {
+    ring: 'border-border bg-card/40 text-muted-foreground',
+    icon: 'text-muted-foreground',
+    iconPath: (
+      <>
+        <rect x="2.5" y="2.5" width="11" height="11" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
+        <path d="M5 6 H11 M5 8.5 H11 M5 11 H8.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+      </>
+    ),
+  },
+}
+
+export const Callout = ({
+  type = 'info', title, children, className,
+}: CalloutProps): ReactNode => {
+  const s = styles[type]
+  return (
+    <div className={cn('not-prose my-5 rounded-lg border px-4 py-3 flex gap-3', s.ring, className)}>
+      <svg
+        width="16" height="16" viewBox="0 0 16 16" fill="none"
+        className={cn('shrink-0 mt-0.5', s.icon)}
+        aria-hidden="true"
+      >
+        {s.iconPath}
+      </svg>
+      <div className="min-w-0 flex-1">
+        {title ? (
+          <div className="font-semibold text-foreground mb-1 leading-tight">{title}</div>
+        ) : null}
+        <div className="text-sm text-foreground/90 leading-relaxed">{children}</div>
+      </div>
+    </div>
+  )
+}

package/src/primitives/card.tsx

@@ -0,0 +1,68 @@
+// shadcn Card — surface container with optional header / content / footer.
+// Compound component: <Card><CardHeader><CardTitle/></CardHeader>...</Card>.
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+export const Card = ({ className, children, ...props }: HTMLAttributes<HTMLDivElement>): ReactNode => (
+  <div
+    data-slot="card"
+    className={cn(
+      'bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+)
+
+export const CardHeader = ({ className, children, ...props }: HTMLAttributes<HTMLDivElement>): ReactNode => (
+  <div
+    data-slot="card-header"
+    className={cn('grid auto-rows-min grid-rows-[auto_auto] items-start gap-1.5 px-6', className)}
+    {...props}
+  >
+    {children}
+  </div>
+)
+
+export const CardTitle = ({ className, children, ...props }: HTMLAttributes<HTMLHeadingElement>): ReactNode => (
+  <h3
+    data-slot="card-title"
+    className={cn('leading-none font-semibold tracking-tight', className)}
+    {...props}
+  >
+    {children}
+  </h3>
+)
+
+export const CardDescription = ({ className, children, ...props }: HTMLAttributes<HTMLParagraphElement>): ReactNode => (
+  <p
+    data-slot="card-description"
+    className={cn('text-muted-foreground text-sm', className)}
+    {...props}
+  >
+    {children}
+  </p>
+)
+
+export const CardContent = ({ className, children, ...props }: HTMLAttributes<HTMLDivElement>): ReactNode => (
+  <div
+    data-slot="card-content"
+    className={cn('px-6', className)}
+    {...props}
+  >
+    {children}
+  </div>
+)
+
+export const CardFooter = ({ className, children, ...props }: HTMLAttributes<HTMLDivElement>): ReactNode => (
+  <div
+    data-slot="card-footer"
+    className={cn('flex items-center px-6', className)}
+    {...props}
+  >
+    {children}
+  </div>
+)