@voltro/ui-shadcn 0.1.0

package/src/compositions/featureGrid.tsx

@@ -0,0 +1,41 @@
+// FeatureGrid composition — auto-fitting grid of feature cards.
+// Tile shape inherits from the shadcn Card primitive.
+
+import type { ReactNode } from 'react'
+import { Card, CardHeader, CardTitle, CardDescription } from '../primitives/card'
+import { cn } from '../cn'
+
+interface Feature {
+  readonly title: string
+  readonly body: string
+  readonly icon?: ReactNode
+}
+
+interface FeatureGridProps {
+  readonly sectionTitle?: string
+  readonly features: ReadonlyArray<Feature>
+  readonly className?: string
+}
+
+export const FeatureGrid = ({
+  sectionTitle, features, className,
+}: FeatureGridProps): ReactNode => (
+  <section className={cn('py-16 max-w-6xl mx-auto px-6', className)}>
+    {sectionTitle ? (
+      <h2 className="text-2xl md:text-3xl font-semibold text-center mb-12 text-foreground">
+        {sectionTitle}
+      </h2>
+    ) : null}
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+      {features.map((f) => (
+        <Card key={f.title} className="hover:border-primary/40 transition-colors">
+          <CardHeader>
+            {f.icon ? <div className="text-primary mb-2">{f.icon}</div> : null}
+            <CardTitle className="text-base">{f.title}</CardTitle>
+            <CardDescription>{f.body}</CardDescription>
+          </CardHeader>
+        </Card>
+      ))}
+    </div>
+  </section>
+)

package/src/compositions/heroSection.tsx

@@ -0,0 +1,55 @@
+// HeroSection composition — opinionated marketing hero with eyebrow
+// pill, gradient title, sub copy, and dual CTAs.
+
+import type { ReactNode } from 'react'
+import { Button } from '../primitives/button'
+import { Badge } from '../primitives/badge'
+import { cn } from '../cn'
+
+interface HeroCta {
+  readonly label: string
+  readonly href: string
+}
+
+interface HeroSectionProps {
+  readonly eyebrow?: string
+  readonly title: ReactNode
+  readonly subtitle?: ReactNode
+  readonly primaryCta?: HeroCta
+  readonly secondaryCta?: HeroCta
+  readonly footnote?: ReactNode
+  readonly className?: string
+}
+
+export const HeroSection = ({
+  eyebrow, title, subtitle, primaryCta, secondaryCta, footnote, className,
+}: HeroSectionProps): ReactNode => (
+  <section className={cn('py-20 text-center max-w-4xl mx-auto px-6', className)}>
+    {eyebrow ? (
+      <Badge variant="outline" className="mb-6 border-primary/30 text-primary">{eyebrow}</Badge>
+    ) : null}
+    <h1 className="text-4xl md:text-6xl font-bold tracking-tight leading-tight mb-4 text-foreground">
+      {title}
+    </h1>
+    {subtitle ? (
+      <p className="text-lg md:text-xl text-muted-foreground max-w-2xl mx-auto mb-8">
+        {subtitle}
+      </p>
+    ) : null}
+    <div className="flex gap-3 justify-center flex-wrap mb-4">
+      {primaryCta ? (
+        <a href={primaryCta.href}>
+          <Button size="lg">{primaryCta.label}</Button>
+        </a>
+      ) : null}
+      {secondaryCta ? (
+        <a href={secondaryCta.href}>
+          <Button size="lg" variant="outline">{secondaryCta.label}</Button>
+        </a>
+      ) : null}
+    </div>
+    {footnote ? (
+      <p className="text-sm text-muted-foreground">{footnote}</p>
+    ) : null}
+  </section>
+)

package/src/compositions/landingCta.tsx

@@ -0,0 +1,85 @@
+// LandingCta — big final "start shipping" section with a deploy-style
+// animated gradient backdrop. Use once near the footer.
+
+import type { ComponentType, ReactNode } from 'react'
+import { cn } from '../cn'
+import type { ShellLinkProps } from './docShell'
+
+interface LandingCtaProps {
+  readonly title: ReactNode
+  readonly subtitle?: ReactNode
+  readonly primaryCta: { readonly label: string; readonly href: string }
+  readonly secondaryCta?: { readonly label: string; readonly href: string }
+  readonly footnote?: ReactNode
+  readonly className?: string
+  readonly LinkComponent?: ComponentType<ShellLinkProps>
+}
+
+// A schemed href (`https://…`) points off-origin → open in a new tab with a safe
+// rel; relative/hash hrefs stay same-tab.
+const isSchemed = (href: string): boolean => /^[a-z][a-z0-9+.-]*:\/\//i.test(href)
+
+const PlainLink = ({ to, className, children }: ShellLinkProps): ReactNode =>
+  isSchemed(to)
+    ? <a href={to} className={className} target="_blank" rel="noopener noreferrer">{children}</a>
+    : <a href={to} className={className}>{children}</a>
+
+
+export const LandingCta = ({
+  title, subtitle, primaryCta, secondaryCta, footnote,
+  className, LinkComponent = PlainLink,
+}: LandingCtaProps): ReactNode => {
+  const Link = LinkComponent
+  return (
+    <section
+      className={cn(
+        'relative overflow-hidden rounded-2xl border border-border',
+        'bg-gradient-to-br from-card/60 via-card/30 to-card/60 backdrop-blur-sm',
+        // Slow-panning gradient layer behind the content
+        'before:absolute before:inset-0 before:bg-[radial-gradient(circle_at_20%_30%,oklch(0.55_0.25_290_/_0.25),transparent_60%),radial-gradient(circle_at_80%_70%,oklch(0.55_0.2_220_/_0.2),transparent_60%)]',
+        // Hairline highlight along top
+        'after:absolute after:inset-x-12 after:top-0 after:h-px after:bg-gradient-to-r after:from-transparent after:via-primary/60 after:to-transparent',
+        'p-12 md:p-16 lg:p-20 text-center',
+        className,
+      )}
+    >
+      <div className="relative max-w-2xl mx-auto">
+        <h2 className="text-3xl md:text-4xl lg:text-5xl font-bold tracking-[-0.02em] leading-[1.1] text-foreground">
+          {title}
+        </h2>
+        {subtitle ? (
+          <p className="mt-5 text-base md:text-lg text-muted-foreground leading-relaxed">
+            {subtitle}
+          </p>
+        ) : null}
+        <div className="mt-8 flex flex-wrap items-center justify-center gap-3">
+          <Link
+            to={primaryCta.href}
+            prefetch
+            className={cn(
+              'group inline-flex items-center gap-2 px-6 py-3 rounded-md',
+              'bg-foreground text-background font-medium text-sm',
+              'hover:opacity-90 active:scale-[0.98] transition-all',
+              'shadow-[0_0_0_1px_oklch(1_0_0_/_0.08),0_8px_32px_-8px_oklch(0.55_0.25_290_/_0.45)]',
+            )}
+          >
+            {primaryCta.label}
+            <span aria-hidden="true" className="transition-transform group-hover:translate-x-0.5">→</span>
+          </Link>
+          {secondaryCta ? (
+            <Link
+              to={secondaryCta.href}
+              prefetch
+              className="inline-flex items-center gap-2 px-6 py-3 rounded-md border border-border bg-card/40 backdrop-blur-sm text-foreground font-medium text-sm hover:bg-card/70 hover:border-input transition-colors"
+            >
+              {secondaryCta.label}
+            </Link>
+          ) : null}
+        </div>
+        {footnote ? (
+          <div className="mt-6 text-xs text-muted-foreground">{footnote}</div>
+        ) : null}
+      </div>
+    </section>
+  )
+}

package/src/compositions/landingHero.tsx

@@ -0,0 +1,174 @@
+// LandingHero — cinematic above-the-fold for dev-tooling landings.
+//
+// Layout (desktop):
+//   ┌───────────────────────────────────────────────────────────────┐
+//   │  • eyebrow                                                    │
+//   │  ▌                                                            │
+//   │  Big gradient heading (2 lines)        ┌────────────────────┐│
+//   │                                        │ CodeWindow (right) ││
+//   │  subtitle, body-size                   │   filename.tsx     ││
+//   │                                        │   …syntax…         ││
+//   │  [Primary CTA]  [Secondary CTA]        └────────────────────┘│
+//   │                                                               │
+//   │  footnote                                                     │
+//   └───────────────────────────────────────────────────────────────┘
+//
+// On mobile the code window moves below the text. The component
+// itself does not render the background — wrap it with MeshBackdrop +
+// GridOverlay in the parent so multiple sections can share the same
+// ambient layers.
+
+import type { ComponentType, ReactNode } from 'react'
+import { cn } from '../cn'
+import type { ShellLinkProps } from './docShell'
+
+interface CtaSpec {
+  readonly label: string
+  readonly href: string
+}
+
+interface LandingHeroProps {
+  readonly eyebrow?: ReactNode
+  /** Two-line heading: the second line gets the gradient + animation. */
+  readonly title: ReactNode
+  /** Optional second line — when set, the layout renders title on
+   *  line 1 and this on line 2 with the gradient/animation. */
+  readonly titleAccent?: ReactNode
+  readonly subtitle?: ReactNode
+  readonly primaryCta?: CtaSpec
+  readonly secondaryCta?: CtaSpec
+  readonly footnote?: ReactNode
+  /** Code window / illustration slot — sits on the right at md+, below
+   *  the CTAs on mobile. */
+  readonly aside?: ReactNode
+  /** Anchor link for "scroll down" hint. */
+  readonly scrollAnchor?: string
+  /** Visible caption on the scroll-down hint. Default `'Scroll'`. */
+  readonly scrollLabel?: ReactNode
+  /** `aria-label` for the scroll-down hint. Default `'Scroll down'`. */
+  readonly scrollAriaLabel?: string
+  readonly className?: string
+  readonly LinkComponent?: ComponentType<ShellLinkProps>
+}
+
+// A schemed href (`https://…`, `mailto:` …) points off-origin, so open it in a
+// new tab with a safe rel; relative/hash hrefs stay same-tab.
+const isSchemed = (href: string): boolean => /^[a-z][a-z0-9+.-]*:\/\//i.test(href)
+
+const PlainLink = ({ to, className, children }: ShellLinkProps): ReactNode =>
+  isSchemed(to)
+    ? <a href={to} className={className} target="_blank" rel="noopener noreferrer">{children}</a>
+    : <a href={to} className={className}>{children}</a>
+
+
+export const LandingHero = ({
+  eyebrow, title, titleAccent, subtitle, primaryCta, secondaryCta,
+  footnote, aside, scrollAnchor, scrollLabel = 'Scroll',
+  scrollAriaLabel = 'Scroll down', className,
+  LinkComponent = PlainLink,
+}: LandingHeroProps): ReactNode => {
+  const Link = LinkComponent
+  return (
+    <section
+      className={cn(
+        'relative isolate overflow-hidden',
+        // Extra bottom padding leaves room for the scroll hint to sit BELOW the
+        // content (it's anchored to the section, not the content column).
+        'pt-24 md:pt-32 pb-24 md:pb-32',
+        className,
+      )}
+    >
+      <div className="relative mx-auto max-w-7xl px-6">
+        <div className="grid grid-cols-1 lg:grid-cols-[1.1fr_1fr] gap-10 lg:gap-16 items-center">
+          {/* ---- Left column: copy + CTAs ---- */}
+          <div className="motion-safe:animate-in motion-safe:fade-in motion-safe:slide-in-from-bottom-4 motion-safe:duration-700">
+            {eyebrow ? (
+              <div className="inline-flex items-center gap-2 text-xs uppercase tracking-[0.12em] text-primary font-semibold mb-5">
+                <span className="inline-block w-1.5 h-1.5 rounded-full bg-primary motion-safe:animate-pulse" />
+                {eyebrow}
+              </div>
+            ) : null}
+
+            <h1 className="text-4xl sm:text-5xl lg:text-6xl font-bold tracking-[-0.02em] leading-[1.05] text-foreground">
+              {title}
+              {titleAccent ? (
+                <>
+                  <br />
+                  <span className="text-gradient motion-safe:animate-gradient-pan">
+                    {titleAccent}
+                  </span>
+                </>
+              ) : null}
+            </h1>
+
+            {subtitle ? (
+              <p className="mt-6 text-base sm:text-lg text-muted-foreground leading-relaxed max-w-xl">
+                {subtitle}
+              </p>
+            ) : null}
+
+            {(primaryCta || secondaryCta) ? (
+              <div className="mt-8 flex flex-wrap items-center gap-3">
+                {primaryCta ? (
+                  <Link
+                    to={primaryCta.href}
+                    prefetch
+                    className={cn(
+                      'group relative inline-flex items-center gap-2 px-5 py-2.5 rounded-md',
+                      'bg-foreground text-background font-medium text-sm',
+                      'hover:opacity-90 active:scale-[0.98] transition-all',
+                      'shadow-[0_0_0_1px_oklch(1_0_0_/_0.08),0_8px_24px_-8px_oklch(0_0_0_/_0.5)]',
+                    )}
+                  >
+                    {primaryCta.label}
+                    <span aria-hidden="true" className="transition-transform group-hover:translate-x-0.5">→</span>
+                  </Link>
+                ) : null}
+                {secondaryCta ? (
+                  <Link
+                    to={secondaryCta.href}
+                    prefetch
+                    className={cn(
+                      'inline-flex items-center gap-2 px-5 py-2.5 rounded-md',
+                      'border border-border bg-card/40 backdrop-blur-sm',
+                      'text-foreground font-medium text-sm',
+                      'hover:bg-card/70 hover:border-input transition-colors',
+                    )}
+                  >
+                    {secondaryCta.label}
+                  </Link>
+                ) : null}
+              </div>
+            ) : null}
+
+            {footnote ? (
+              <div className="mt-8 text-sm text-muted-foreground">{footnote}</div>
+            ) : null}
+          </div>
+
+          {/* ---- Right column: code/illustration ---- */}
+          {aside ? (
+            <div className="lg:pl-4 motion-safe:animate-in motion-safe:fade-in motion-safe:slide-in-from-bottom-6 motion-safe:duration-700 motion-safe:delay-150">
+              {aside}
+            </div>
+          ) : null}
+        </div>
+      </div>
+
+      {/* Scroll hint — anchored to the SECTION (not the content column), so it
+          sits at the bottom of the full-height hero, at the fold. */}
+      {scrollAnchor ? (
+        <a
+          href={scrollAnchor}
+          className="hidden md:flex absolute left-1/2 -translate-x-1/2 bottom-8 text-xs text-muted-foreground items-center gap-1.5 hover:text-foreground transition-colors"
+          aria-label={scrollAriaLabel}
+        >
+          <span>{scrollLabel}</span>
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true" className="motion-safe:animate-bounce">
+            <path d="M7 2 V12 M3 8 L7 12 L11 8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+          </svg>
+        </a>
+      ) : null}
+    </section>
+  )
+}

package/src/compositions/landingStats.tsx

@@ -0,0 +1,99 @@
+// LandingStats — strip of 3-4 big numbers under a "by the numbers"
+// section. Each value uses AnimatedNumber so the digits roll up when
+// the section scrolls into view.
+//
+// Layout per cell (top → bottom):
+//   1. Eyebrow row: icon chip + small uppercase label aligned together
+//      so the icon reads AS a label, not as decoration. Chip is sized
+//      to match cap-height of the label (gives the icon real weight
+//      without competing with the number).
+//   2. Big number with tabular figures, generous breathing room.
+//      Prefix + unit are visually subordinate via size, not opacity
+//      collapse (kept above the 4.5:1 contrast floor).
+//   3. Sub-caption — one line of detail, muted but readable.
+//
+// The previous version had a 16px svg next to a 60px number, a
+// freestanding hairline "accent rail" that aligned to nothing, and a
+// glass background with a decorative hover-gradient hairline. All
+// three were AI-grammar tells; this revision removes them. Hierarchy
+// is carried by the size step between the number and the eyebrow,
+// plus the kit's normal hover state on the cell.
+
+import type { ReactNode } from 'react'
+import { cn } from '../cn'
+import { AnimatedNumber } from '../primitives/animatedNumber'
+
+export interface StatSpec {
+  /** Numeric value — drives the count-up animation. */
+  readonly value: number
+  /** Optional unit suffix shown next to the value (e.g. "ms", "%"). */
+  readonly unit?: string
+  /** Static prefix (e.g. "<", "~"). Useful for things like "<5ms". */
+  readonly prefix?: string
+  /** Formatter — passed through to AnimatedNumber. */
+  readonly format?: 'integer' | 'percent' | ((n: number) => string)
+  /** Caption below the number (becomes the eyebrow label at the top
+   *  of the cell). */
+  readonly label: ReactNode
+  /** Small sub-caption below the number. */
+  readonly sub?: ReactNode
+  /** Optional icon — pass any kit icon. Sized to the eyebrow's
+   *  cap-height so it reads as part of the label, not as decoration. */
+  readonly icon?: ReactNode
+}
+
+interface LandingStatsProps {
+  readonly stats: ReadonlyArray<StatSpec>
+  readonly className?: string
+}
+
+export const LandingStats = ({
+  stats, className,
+}: LandingStatsProps): ReactNode => (
+  <div
+    className={cn(
+      // grid-cols-N gives a clean wall of cells with hairline separators
+      // (the gap-px + bg-border below the grid layer). The outer
+      // rounded-2xl frame ties them into one composed strip.
+      'grid grid-cols-2 lg:grid-cols-4 gap-px overflow-hidden rounded-2xl border border-border bg-border',
+      className,
+    )}
+  >
+    {stats.map((s, i) => (
+      <div
+        key={i}
+        className="relative bg-card p-7 lg:p-9 transition-colors duration-300 hover:bg-accent/40"
+      >
+        {/* Eyebrow row — icon + label travel together. Icon is sized
+         * to the label's cap-height so it reads as a sibling, not a
+         * floating chip. */}
+        <div className="flex items-center gap-2 mb-6 text-xs uppercase tracking-[0.14em] text-muted-foreground font-medium">
+          {s.icon ? (
+            <span className="text-foreground/80 [&_svg]:w-3.5 [&_svg]:h-3.5">
+              {s.icon}
+            </span>
+          ) : null}
+          <span>{s.label}</span>
+        </div>
+
+        {/* Big number — tabular figures, leading-none for tight
+         * vertical rhythm against the eyebrow above and the sub
+         * below. Prefix/unit are subordinate via SIZE (not via
+         * pushing opacity below readable contrast). */}
+        <div className="text-5xl lg:text-6xl font-semibold tracking-[-0.035em] text-foreground inline-flex items-baseline gap-1 font-tabular leading-none">
+          {s.prefix ? (
+            <span className="text-3xl lg:text-4xl text-muted-foreground font-medium">{s.prefix}</span>
+          ) : null}
+          <AnimatedNumber value={s.value} {...(s.format ? { format: s.format } : {})} />
+          {s.unit ? (
+            <span className="text-2xl lg:text-3xl text-muted-foreground font-medium ml-0.5">{s.unit}</span>
+          ) : null}
+        </div>
+
+        {s.sub ? (
+          <div className="mt-4 text-sm text-muted-foreground leading-relaxed">{s.sub}</div>
+        ) : null}
+      </div>
+    ))}
+  </div>
+)

package/src/compositions/loginCard.tsx

@@ -0,0 +1,139 @@
+// LoginCard composition — pairs email + password inputs with an
+// optional OAuth row. The card is stylistically opinionated (max
+// width, centred, raised) so apps don't reinvent the same shell.
+//
+// Submit handling stays with the consumer (form action / onSubmit).
+// The component just renders the surface.
+
+import type { FormHTMLAttributes, ReactNode } from 'react'
+import { Button } from '../primitives/button'
+import { Card, CardContent, CardHeader, CardTitle, CardDescription, CardFooter } from '../primitives/card'
+import { Input } from '../primitives/input'
+import { Label } from '../primitives/label'
+import { cn } from '../cn'
+
+interface OAuthProvider {
+  readonly id: string
+  readonly label: string
+}
+
+/** User-facing strings — pass catalog values to localize. Defaults are
+ *  English so the card works unconfigured. */
+export interface LoginCardLabels {
+  /** Email field label. Default `'Email'`. */
+  readonly email?: string
+  /** Email input placeholder. Default `'you@company.com'`. */
+  readonly emailPlaceholder?: string
+  /** Password field label. Default `'Password'`. */
+  readonly password?: string
+  /** "Forgot password?" link text (shown when `forgotHref` is set).
+   *  Default `'Forgot?'`. */
+  readonly forgot?: string
+  /** OAuth divider caption. Default `'or continue with'`. */
+  readonly oauthDivider?: string
+  /** Sign-up footer prompt (shown when `signUpHref` is set).
+   *  Default `'New here?'`. */
+  readonly signUpPrompt?: string
+  /** Sign-up footer link text. Default `'Create an account'`. */
+  readonly signUp?: string
+}
+
+const DEFAULT_LOGIN_LABELS: Required<LoginCardLabels> = {
+  email: 'Email',
+  emailPlaceholder: 'you@company.com',
+  password: 'Password',
+  forgot: 'Forgot?',
+  oauthDivider: 'or continue with',
+  signUpPrompt: 'New here?',
+  signUp: 'Create an account',
+}
+
+interface LoginCardProps extends Omit<FormHTMLAttributes<HTMLFormElement>, 'children'> {
+  readonly title?: string
+  readonly description?: string
+  readonly eyebrow?: string
+  readonly submitLabel?: string
+  readonly oauthProviders?: ReadonlyArray<OAuthProvider>
+  readonly onOAuth?: (providerId: string) => void
+  readonly signUpHref?: string
+  readonly forgotHref?: string
+  readonly className?: string
+  /** Override the card's own chrome strings. Defaults are English. */
+  readonly labels?: LoginCardLabels
+}
+
+export const LoginCard = ({
+  title = 'Welcome back',
+  description = 'Sign in to your account to continue.',
+  eyebrow,
+  submitLabel = 'Sign in',
+  oauthProviders,
+  onOAuth,
+  signUpHref,
+  forgotHref,
+  className,
+  labels,
+  ...formProps
+}: LoginCardProps): ReactNode => {
+  const t = { ...DEFAULT_LOGIN_LABELS, ...labels }
+  return (
+  <div className={cn('w-full max-w-md mx-auto', className)}>
+    <Card>
+      <CardHeader>
+        {eyebrow ? (
+          <div className="text-xs uppercase tracking-wider text-muted-foreground font-medium">
+            {eyebrow}
+          </div>
+        ) : null}
+        <CardTitle className="text-2xl">{title}</CardTitle>
+        <CardDescription>{description}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form className="space-y-4" {...formProps}>
+          <div className="space-y-1.5">
+            <Label htmlFor="email">{t.email}</Label>
+            <Input id="email" name="email" type="email" autoComplete="email" placeholder={t.emailPlaceholder} />
+          </div>
+          <div className="space-y-1.5">
+            <div className="flex items-center justify-between">
+              <Label htmlFor="password">{t.password}</Label>
+              {forgotHref ? (
+                <a href={forgotHref} className="text-xs text-muted-foreground hover:text-foreground">{t.forgot}</a>
+              ) : null}
+            </div>
+            <Input id="password" name="password" type="password" autoComplete="current-password" placeholder="••••••••" />
+          </div>
+          <Button type="submit" className="w-full">{submitLabel}</Button>
+        </form>
+
+        {oauthProviders && oauthProviders.length > 0 ? (
+          <>
+            <div className="my-5 flex items-center gap-3 text-xs text-muted-foreground">
+              <div className="h-px flex-1 bg-border" />
+              <span>{t.oauthDivider}</span>
+              <div className="h-px flex-1 bg-border" />
+            </div>
+            <div className="grid gap-2" style={{ gridTemplateColumns: `repeat(${oauthProviders.length}, minmax(0, 1fr))` }}>
+              {oauthProviders.map((p) => (
+                <Button
+                  key={p.id}
+                  type="button"
+                  variant="outline"
+                  onClick={() => onOAuth?.(p.id)}
+                >
+                  {p.label}
+                </Button>
+              ))}
+            </div>
+          </>
+        ) : null}
+      </CardContent>
+      {signUpHref ? (
+        <CardFooter className="justify-center text-xs text-muted-foreground">
+          {t.signUpPrompt} <a href={signUpHref} className="ml-1 text-foreground hover:underline">{t.signUp}</a>
+        </CardFooter>
+      ) : null}
+    </Card>
+  </div>
+  )
+}

package/src/compositions/pageHeader.tsx

@@ -0,0 +1,58 @@
+// Shared page header chrome for every Voltro-Cloud-style app:
+// landing, docs, dashboard, marketplace. The single source of truth
+// for the sticky top bar that wraps brand + navigation across all
+// four web apps — keeps height, glass treatment, max-width, and
+// padding identical so they read as one product.
+//
+// Treatment:
+//   • sticky top-0, z-40 (above the docs sidebar's top-16 sticky)
+//   • Fixed `h-16` (64px). NOT scroll-shrinking — DocsLayout's
+//     sidebar uses `sticky top-16` and a height-changing header
+//     would leave a gap or overlap on scroll. The visual
+//     "compactness on scroll" effect is delivered by the glass
+//     fade-in instead.
+//   • Glass + border fade in once `scrollY > 24`. At rest the
+//     header is fully transparent → the hero / page background
+//     bleeds through.
+//
+// The children prop is the row contents (brand on the left, nav /
+// actions on the right). Consumers compose freely; the kit just
+// owns the wrapper.
+
+import { useEffect, useState, type ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface PageHeaderProps {
+  readonly children: ReactNode
+  readonly className?: string
+}
+
+export const PageHeader = ({ children, className }: PageHeaderProps): ReactNode => {
+  const [scrolled, setScrolled] = useState(false)
+  useEffect(() => {
+    // 24px threshold — smaller flickers on subpixel scroll;
+    // bigger leaves a moment where content touches the bare header.
+    const onScroll = (): void => setScrolled(window.scrollY > 24)
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    return () => window.removeEventListener('scroll', onScroll)
+  }, [])
+
+  return (
+    <header className={cn('sticky top-0 z-40', className)}>
+      {/* Glass + hairline border, fade-in on scroll. Separate <div>
+       * so opacity transitions don't affect the foreground row. */}
+      <div
+        aria-hidden="true"
+        className={cn(
+          'absolute inset-0 -z-10 transition-opacity duration-300 ease-out',
+          'bg-background/80 backdrop-blur-lg border-b border-border',
+          scrolled ? 'opacity-100' : 'opacity-0',
+        )}
+      />
+      <div className="mx-auto max-w-7xl px-6 h-16 flex items-center justify-between gap-4">
+        {children}
+      </div>
+    </header>
+  )
+}