@repraze/kernelkit 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/components/message.tsx

@@ -65,7 +65,7 @@ function MessageHeader({className, ...props}: React.ComponentProps<"div">) {
         <div
             data-slot="message-header"
             className={cn(
-                "flex max-w-full min-w-0 items-center gap-1.5 px-3 text-xs font-medium text-muted-foreground group-has-data-[variant=ghost]/message:px-0 group-data-[align=end]/message:justify-end [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5 [&_time]:font-mono [&_time]:font-normal [&_time]:tabular-nums",
+                "flex max-w-full min-w-0 items-center gap-1.5 px-3 text-xs font-medium text-muted-foreground group-has-data-[variant=ghost]/message:px-0 group-data-[align=end]/message:justify-end [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5 [&_time]:font-alt [&_time]:font-normal [&_time]:tabular-nums",
                 className,
             )}
             {...props}
@@ -78,7 +78,7 @@ function MessageFooter({className, ...props}: React.ComponentProps<"div">) {
         <div
             data-slot="message-footer"
             className={cn(
-                "flex max-w-full min-w-0 items-center gap-1 px-3 text-xs text-muted-foreground group-has-data-[variant=ghost]/message:px-0 group-data-[align=end]/message:justify-end [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5 [&_time]:font-mono [&_time]:tabular-nums",
+                "flex max-w-full min-w-0 items-center gap-1 px-3 text-xs text-muted-foreground group-has-data-[variant=ghost]/message:px-0 group-data-[align=end]/message:justify-end [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5 [&_time]:font-alt [&_time]:tabular-nums",
                 className,
             )}
             {...props}

package/src/components/meter.tsx

@@ -59,7 +59,7 @@ function MeterValue({className, ...props}: MeterPrimitive.Value.Props) {
     return (
         <MeterPrimitive.Value
             data-slot="meter-value"
-            className={cn("ms-auto font-mono text-xs text-muted-foreground tabular-nums", className)}
+            className={cn("ms-auto font-alt text-xs text-muted-foreground tabular-nums", className)}
             {...props}
         />
     );

package/src/components/progress.tsx

@@ -86,7 +86,7 @@ function ProgressValue({className, ...props}: ProgressPrimitive.Value.Props) {
     return (
         <ProgressPrimitive.Value
             data-slot="progress-value"
-            className={cn("ms-auto font-mono text-xs text-muted-foreground tabular-nums", className)}
+            className={cn("ms-auto font-alt text-xs text-muted-foreground tabular-nums", className)}
             {...props}
         />
     );

package/src/components/questionnaire.tsx

@@ -122,7 +122,7 @@ function QuestionnaireChoice({
             </QuestionnairePrimitive.ChoiceLabel>
             <QuestionnairePrimitive.ChoiceShortcut
                 data-slot="questionnaire-choice-shortcut"
-                className="pointer-events-none ms-auto hidden size-5 shrink-0 translate-y-[--spacing(0.45)] items-center justify-center rounded-sm border border-border bg-muted font-mono text-[0.625rem] leading-none font-medium text-muted-foreground group-has-data-[slot=questionnaire-choice-description]/questionnaire-choice:translate-y-0.5 group-data-[shortcut]/questionnaire-choice:inline-flex"
+                className="pointer-events-none ms-auto hidden size-5 shrink-0 translate-y-[--spacing(0.45)] items-center justify-center rounded-sm border border-border bg-muted font-alt text-[0.625rem] leading-none font-medium text-muted-foreground group-has-data-[slot=questionnaire-choice-description]/questionnaire-choice:translate-y-0.5 group-data-[shortcut]/questionnaire-choice:inline-flex"
             />
         </QuestionnairePrimitive.Choice>
     );

package/src/components/search-dialog.tsx

@@ -84,4 +84,17 @@ function SearchFooter({className, ...props}: React.ComponentProps<"div">) {
     );
 }
 
-export {SearchDialog, SearchFooter, SearchItem};
+/**
+ * The suite's search filter for `<Command filter={substringFilter}>`: a plain substring match (prefix
+ * matches rank first). cmdk's default fuzzy match finds "t…a…b" in nearly every title.
+ */
+function substringFilter(value: string, search: string, keywords?: string[]) {
+    const haystack = [value, ...(keywords ?? [])].join(" ").toLowerCase();
+    const needle = search.trim().toLowerCase();
+    if (haystack.startsWith(needle)) {
+        return 1;
+    }
+    return haystack.includes(needle) ? 0.5 : 0;
+}
+
+export {SearchDialog, SearchFooter, SearchItem, substringFilter};

package/src/components/search-trigger.tsx

@@ -51,16 +51,15 @@ interface SearchTriggerProps extends React.ComponentProps<typeof Button> {
     children?: React.ReactNode;
 }
 
-/** Header search button: icon, placeholder, OS-aware shortcut. Open your dialog in `onClick`. */
+/** Header search button: icon, placeholder, OS-aware shortcut. Same 32px height as the header's icon buttons. Open your dialog in `onClick`. */
 function SearchTrigger({children = "Search…", className, ...props}: SearchTriggerProps) {
     const mod = useModKey();
     return (
         <Button
             variant="outline"
-            size="sm"
             aria-label="Search"
             data-slot="search-trigger"
-            className={cn("w-9 justify-start px-0 text-muted-foreground sm:w-48 sm:px-2.5 md:w-56", className)}
+            className={cn("w-8 justify-start px-0 text-muted-foreground sm:w-48 sm:px-2.5 md:w-56", className)}
             {...props}
         >
             <SearchIcon data-icon="inline-start" className="mx-auto sm:mx-0" />

package/src/components/section.tsx

@@ -50,7 +50,7 @@ function SectionEyebrow({className, render, ...props}: useRender.ComponentProps<
     return useRender({
         defaultTagName: "div",
         props: mergeProps<"div">(
-            {className: cn("font-mono text-xs font-medium text-primary-text uppercase sm:col-start-1", className)},
+            {className: cn("font-alt text-xs font-medium text-primary-text uppercase sm:col-start-1", className)},
             props,
         ),
         render,

package/src/components/sidebar.tsx

@@ -592,7 +592,7 @@ function SidebarMenuBadge({className, ...props}: React.ComponentProps<"div">) {
             data-slot="sidebar-menu-badge"
             data-sidebar="menu-badge"
             className={cn(
-                "pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-sm px-1 font-mono text-xs font-medium text-muted-foreground tabular-nums select-none group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 peer-data-active/menu-button:text-sidebar-accent-foreground",
+                "pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-sm px-1 font-alt text-xs font-medium text-muted-foreground tabular-nums select-none group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 peer-data-active/menu-button:text-sidebar-accent-foreground",
                 className,
             )}
             {...props}

package/src/components/site-footer.tsx

@@ -22,7 +22,7 @@ import type * as React from "react";
 function SiteFooter({className, children, ...props}: React.ComponentProps<"footer">) {
     return (
         <footer data-slot="site-footer" className={cn("border-t border-border", className)} {...props}>
-            <div className="mx-auto flex w-full max-w-(--kk-site-width) flex-col gap-3 px-4 py-6 font-mono text-xs text-muted-foreground sm:flex-row sm:items-center sm:justify-between md:px-6">
+            <div className="mx-auto flex w-full max-w-(--kk-site-width) flex-col gap-3 px-4 py-6 font-alt text-xs text-muted-foreground sm:flex-row sm:items-center sm:justify-between md:px-6">
                 {children}
             </div>
         </footer>

package/src/components/site-header.tsx

@@ -66,7 +66,7 @@ function SiteHeaderBrand({className, render, ...props}: useRender.ComponentProps
         props: mergeProps<"a">(
             {
                 className: cn(
-                    "flex shrink-0 items-center gap-2 rounded-md font-mono text-sm font-semibold tracking-tight",
+                    "flex shrink-0 items-center gap-2 rounded-md font-alt text-sm font-semibold tracking-tight",
                     focusRing,
                     "[&_svg]:shrink-0",
                     className,
@@ -105,7 +105,7 @@ function SiteNavLink({className, render, ...props}: useRender.ComponentProps<"a"
         props: mergeProps<"a">(
             {
                 className: cn(
-                    "relative flex h-8 items-center rounded-md px-2.5 font-mono text-sm text-muted-foreground transition-colors hover:bg-hover hover:text-foreground motion-reduce:transition-none",
+                    "relative flex h-8 items-center rounded-md px-2.5 font-alt text-sm text-muted-foreground transition-colors hover:bg-hover hover:text-foreground motion-reduce:transition-none",
                     focusRing,
                     // indicator: left edge by default, bottom edge inside SiteNav
                     "after:pointer-events-none after:absolute after:top-1.5 after:bottom-1.5 after:left-0 after:w-0.5 after:rounded-pill after:bg-primary-text after:opacity-0",

package/src/components/stat.tsx

@@ -51,7 +51,7 @@ function StatValue({className, ...props}: React.ComponentProps<"div">) {
         <div
             data-slot="stat-value"
             className={cn(
-                "col-start-1 flex items-baseline gap-1 font-mono text-2xl leading-tight font-medium tracking-tight text-foreground tabular-nums",
+                "col-start-1 flex items-baseline gap-1 font-alt text-2xl leading-tight font-medium tracking-tight text-foreground tabular-nums",
                 "group-data-[size=sm]/stat:text-xl group-data-[size=lg]/stat:text-3xl",
                 className,
             )}
@@ -74,7 +74,7 @@ function StatUnit({className, ...props}: React.ComponentProps<"span">) {
 type StatTrend = "up" | "down" | "flat";
 
 const statDeltaVariants = cva(
-    "col-start-1 inline-flex w-fit items-center gap-1 font-mono text-xs font-medium tabular-nums [&_svg]:size-3.5 [&_svg]:shrink-0",
+    "col-start-1 inline-flex w-fit items-center gap-1 font-alt text-xs font-medium tabular-nums [&_svg]:size-3.5 [&_svg]:shrink-0",
     {
         variants: {
             intent: {

package/src/components/tabs.tsx

@@ -18,8 +18,10 @@ function Tabs({className, orientation = "horizontal", ...props}: TabsPrimitive.R
 }
 
 /**
- * `default`: a tray with the active tab raised on a bordered surface (the border keeps it readable in
- * high contrast). `line`: a baseline with a 2px primary indicator under the active tab.
+ * `default`: a track with the active tab tinted with the accent and marked by a 2px pill along its bottom
+ * edge, like a current nav link. Track border + padding = `--radius-xs` (lg − md), so the `rounded-md` chips
+ * stay concentric with the `rounded-lg` track at every radius. `line`: a baseline with the same 2px pill
+ * on it under the active tab.
  * Sizes follow the control table (GUIDELINES §4) so a tabs list lines up with buttons and inputs.
  */
 const tabsListVariants = cva(
@@ -27,7 +29,8 @@ const tabsListVariants = cva(
     {
         variants: {
             variant: {
-                default: "rounded-lg border border-transparent bg-muted p-[3px] data-vertical:gap-0.5 hc:border-border",
+                default:
+                    "rounded-lg border border-transparent bg-muted p-[max(0px,calc(var(--radius-xs)-1px))] data-vertical:gap-0.5 hc:border-border",
                 line: "gap-1 rounded-none border-border bg-transparent data-horizontal:border-b data-horizontal:py-[3px] data-vertical:border-r data-vertical:px-[3px]",
             },
             size: {
@@ -73,13 +76,18 @@ const tabsTriggerClass = cn(
     "group-data-[size=lg]/tabs-list:gap-2 group-data-[size=lg]/tabs-list:px-2.5",
     // vertical: full-width rows
     "data-vertical:w-full data-vertical:flex-none data-vertical:justify-start data-vertical:py-1",
-    // default: raised, bordered surface + foreground text (readable without the shade in hc)
+    // active: foreground text and a 2px primary-text pill; default adds the accent tint (nav link look)
     "data-active:text-foreground",
-    "group-data-[variant=default]/tabs-list:data-active:border-input group-data-[variant=default]/tabs-list:data-active:bg-background group-data-[variant=default]/tabs-list:data-active:shadow-sm group-data-[variant=default]/tabs-list:data-active:shadow-(color:--shadow-color) dark:group-data-[variant=default]/tabs-list:data-active:bg-input/30",
-    // line: 2px primary indicator over the list's baseline
-    "after:pointer-events-none after:absolute after:rounded-pill after:bg-primary-text after:opacity-0 after:transition-opacity group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
-    "data-horizontal:after:inset-x-1 data-horizontal:after:-bottom-1 data-horizontal:after:h-0.5",
-    "data-vertical:after:inset-y-1 data-vertical:after:-right-1 data-vertical:after:w-0.5",
+    "group-data-[variant=default]/tabs-list:data-active:bg-accent group-data-[variant=default]/tabs-list:data-active:text-accent-foreground",
+    "after:pointer-events-none after:absolute after:rounded-pill after:bg-primary-text after:opacity-0 after:transition-opacity data-active:after:opacity-100",
+    // default: the pill sits inside the chip on its bottom edge (vertical: its start edge, like sidebar rows)
+    "group-data-[variant=default]/tabs-list:data-horizontal:after:inset-x-2 group-data-[variant=default]/tabs-list:data-horizontal:after:-bottom-px group-data-[variant=default]/tabs-list:data-horizontal:after:h-0.5",
+    // the pill spans the label: inset = the trigger's padding per size
+    "group-data-[size=sm]/tabs-list:group-data-[variant=default]/tabs-list:data-horizontal:after:inset-x-1.5 group-data-[size=lg]/tabs-list:group-data-[variant=default]/tabs-list:data-horizontal:after:inset-x-2.5",
+    "group-data-[variant=default]/tabs-list:data-vertical:after:inset-y-1.5 group-data-[variant=default]/tabs-list:data-vertical:after:-left-px group-data-[variant=default]/tabs-list:data-vertical:after:w-0.5",
+    // line: the pill sits on the list's baseline
+    "group-data-[variant=line]/tabs-list:data-horizontal:after:inset-x-1 group-data-[variant=line]/tabs-list:data-horizontal:after:-bottom-1 group-data-[variant=line]/tabs-list:data-horizontal:after:h-0.5",
+    "group-data-[variant=line]/tabs-list:data-vertical:after:inset-y-1 group-data-[variant=line]/tabs-list:data-vertical:after:-right-1 group-data-[variant=line]/tabs-list:data-vertical:after:w-0.5",
 );
 
 function TabsTrigger({className, ...props}: TabsPrimitive.Tab.Props) {

package/src/components/theme-menu.tsx

@@ -116,7 +116,7 @@ function ThemeRadiusPicker({className}: {className?: string}) {
             className={cn("w-full", className)}
         >
             {RADII.map((radius) => (
-                <ToggleGroupItem key={radius} value={radius} className="flex-1 font-mono">
+                <ToggleGroupItem key={radius} value={radius} className="flex-1 font-alt">
                     {radius}
                 </ToggleGroupItem>
             ))}

package/src/components/toc.tsx

@@ -35,7 +35,7 @@ function TocTitle({className, render, ...props}: useRender.ComponentProps<"p">)
     return useRender({
         defaultTagName: "p",
         props: mergeProps<"p">(
-            {className: cn("font-mono text-xs font-medium text-muted-foreground uppercase", className)},
+            {className: cn("font-alt text-xs font-medium text-muted-foreground uppercase", className)},
             props,
         ),
         render,

package/src/components/tooltip.tsx

@@ -39,15 +39,27 @@ function TooltipContent({
                 <TooltipPrimitive.Popup
                     data-slot="tooltip-content"
                     className={cn(
-                        // Inverted chip: max contrast against any surface, so it reads in high contrast too.
+                        // Popover-coloured chip: the popup surface and border, small mono text.
                         popupMotion,
-                        "z-50 inline-flex min-h-6 w-fit max-w-xs items-center gap-1.5 rounded-md bg-foreground px-2 py-1 text-xs text-background shadow-md shadow-(color:--shadow-color) has-data-[slot=kbd]:pr-1 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:h-4 **:data-[slot=kbd]:min-w-4 **:data-[slot=kbd]:rounded-xs",
+                        "z-50 inline-flex min-h-6 w-fit max-w-xs items-center gap-1.5 rounded-md border border-border bg-popover px-2 py-1 font-alt text-xs text-popover-foreground shadow-md shadow-(color:--shadow-color) has-data-[slot=kbd]:pr-1 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:h-4 **:data-[slot=kbd]:min-w-4 **:data-[slot=kbd]:rounded-xs",
                         className,
                     )}
                     {...props}
                 >
                     {children}
-                    <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-xs bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
+                    <TooltipPrimitive.Arrow
+                        className={cn(
+                            // A rotated square in the popup colours; the border sits on the two edges that face out,
+                            // centred on the popup's border line so the outline runs on without a seam.
+                            "z-50 size-2.5 rotate-45 rounded-xs border-border bg-popover",
+                            "data-[side=top]:-bottom-1.25 data-[side=top]:border-r data-[side=top]:border-b",
+                            "data-[side=bottom]:-top-1.25 data-[side=bottom]:border-t data-[side=bottom]:border-l",
+                            "data-[side=left]:top-1/2! data-[side=left]:-right-1.25 data-[side=left]:-translate-y-1/2 data-[side=left]:border-t data-[side=left]:border-r",
+                            "data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1.25 data-[side=inline-start]:-translate-y-1/2 data-[side=inline-start]:border-t data-[side=inline-start]:border-r",
+                            "data-[side=right]:top-1/2! data-[side=right]:-left-1.25 data-[side=right]:-translate-y-1/2 data-[side=right]:border-b data-[side=right]:border-l",
+                            "data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1.25 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-end]:border-b data-[side=inline-end]:border-l",
+                        )}
+                    />
                 </TooltipPrimitive.Popup>
             </TooltipPrimitive.Positioner>
         </TooltipPrimitive.Portal>

package/src/components/trace.tsx

@@ -67,7 +67,7 @@ function TraceDescription({className, ...props}: React.ComponentProps<"span">) {
     return (
         <span
             data-slot="trace-description"
-            className={cn("shrink-0 font-mono text-xs text-muted-foreground tabular-nums", className)}
+            className={cn("shrink-0 font-alt text-xs text-muted-foreground tabular-nums", className)}
             {...props}
         />
     );

package/src/docs/doc-kit.tsx

@@ -0,0 +1,176 @@
+"use client";
+
+import {
+    CodeBlock,
+    CodeBlockActions,
+    CodeBlockContent,
+    CodeBlockCopyButton,
+    CodeBlockHeader,
+    CodeBlockTitle,
+} from "@repraze/kernelkit/components/code-block";
+import {Table, TableBody, TableCell, TableHead, TableHeader, TableRow} from "@repraze/kernelkit/components/table";
+import {Tabs, TabsContent, TabsList, TabsTrigger} from "@repraze/kernelkit/components/tabs";
+import {useHighlightedCode} from "@repraze/kernelkit/hooks/use-highlighted-code";
+import {cn} from "cn";
+import type * as React from "react";
+
+export interface PropRow {
+    name: string;
+    type: string;
+    default?: string;
+    description?: string;
+}
+
+export interface DemoDef {
+    title: string;
+    description?: string;
+    component: React.ComponentType;
+    /** Preview frame: "center" (default), "start" (top-left), "full" (no padding), "tall". */
+    layout?: "center" | "start" | "full" | "tall";
+}
+
+/** A docs page: one `defineDoc({...})` per file in the site's docs folder (read statically by docsMetaPlugin). */
+export interface DocDef<Category extends string = string> {
+    title: string;
+    category: Category;
+    description: string;
+    /** A link badge after the category in the page header: the primitive it wraps, the source file it documents. */
+    source?: {label: string; href: string};
+    demos: DemoDef[];
+    props?: {component: string; rows: PropRow[]}[];
+    /** Freeform content after the demos. */
+    notes?: React.ComponentType;
+    /** The notes' own h2 sections (`id` on each), listed in the table of contents after the demos. */
+    sections?: {id: string; title: string}[];
+    /** Sort order inside the category (lower first, default 50). */
+    order?: number;
+}
+
+export interface DocEntry<Category extends string = string> extends DocDef<Category> {
+    slug: string;
+    /** Source of each demo's own function, by demo index. */
+    demoSources: string[];
+}
+
+/**
+ * Declare a docs page. The site narrows the categories once:
+ *
+ * ```ts
+ * export const CATEGORIES = ["Foundations", "Components"] as const;
+ * export const defineDoc = (doc: DocDef<(typeof CATEGORIES)[number]>) => doc;
+ * ```
+ */
+export function defineDoc<Category extends string>(doc: DocDef<Category>): DocDef<Category> {
+    return doc;
+}
+
+export function slugify(text: string) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+
+/** A highlighted, copyable code sample (the kit's CodeBlock), titled with its language by default. */
+export function Code({
+    code,
+    language = "tsx",
+    title,
+    className,
+}: {
+    code: string;
+    language?: string;
+    title?: string;
+    className?: string;
+}) {
+    const lines = useHighlightedCode(code, language);
+    return (
+        <CodeBlock className={className}>
+            <CodeBlockHeader>
+                <CodeBlockTitle>{title ?? language}</CodeBlockTitle>
+                <CodeBlockActions>
+                    <CodeBlockCopyButton value={code} />
+                </CodeBlockActions>
+            </CodeBlockHeader>
+            <CodeBlockContent className="max-h-[480px] text-[13px]">
+                {lines.map((line, i) => (
+                    <span key={i} className="block min-h-lh">
+                        {line}
+                    </span>
+                ))}
+            </CodeBlockContent>
+        </CodeBlock>
+    );
+}
+
+const layoutClass: Record<NonNullable<DemoDef["layout"]>, string> = {
+    center: "flex min-h-56 items-center justify-center p-8",
+    start: "flex min-h-56 items-start justify-start p-8",
+    full: "overflow-hidden",
+    tall: "flex min-h-[28rem] items-center justify-center p-8",
+};
+
+/** One demo: its title and description, then Preview and Code tabs. The section's id is the slugified title. */
+export function Demo({demo, code}: {demo: DemoDef; code: string}) {
+    const Component = demo.component;
+    return (
+        <section className="flex scroll-mt-24 flex-col gap-3" id={slugify(demo.title)}>
+            <div className="flex flex-col gap-1">
+                <h3 className="font-mono text-sm font-medium">{demo.title}</h3>
+                {demo.description ? <p className="text-sm text-muted-foreground">{demo.description}</p> : null}
+            </div>
+            <Tabs defaultValue="preview">
+                <TabsList>
+                    <TabsTrigger value="preview">Preview</TabsTrigger>
+                    <TabsTrigger value="code">Code</TabsTrigger>
+                </TabsList>
+                <TabsContent value="preview">
+                    <div
+                        data-slot="demo-frame"
+                        className={cn("rounded-xl border bg-card", layoutClass[demo.layout ?? "center"])}
+                    >
+                        <Component />
+                    </div>
+                </TabsContent>
+                <TabsContent value="code">
+                    <Code code={code} />
+                </TabsContent>
+            </Tabs>
+        </section>
+    );
+}
+
+/** A component's props: name, type, default and description. */
+export function PropsTable({component, rows}: {component: string; rows: PropRow[]}) {
+    return (
+        <section className="flex flex-col gap-3">
+            <h3 className="font-mono text-sm font-medium">{component}</h3>
+            <div className="overflow-hidden rounded-xl border bg-card">
+                <Table>
+                    <TableHeader>
+                        <TableRow>
+                            <TableHead>Prop</TableHead>
+                            <TableHead>Type</TableHead>
+                            <TableHead>Default</TableHead>
+                            <TableHead>Description</TableHead>
+                        </TableRow>
+                    </TableHeader>
+                    <TableBody>
+                        {rows.map((row) => (
+                            <TableRow key={row.name}>
+                                <TableCell className="font-mono text-xs text-primary-text">{row.name}</TableCell>
+                                <TableCell className="font-mono text-xs whitespace-normal">{row.type}</TableCell>
+                                <TableCell className="font-mono text-xs text-muted-foreground">
+                                    {row.default ?? "-"}
+                                </TableCell>
+                                <TableCell className="text-sm whitespace-normal text-muted-foreground">
+                                    {row.description}
+                                </TableCell>
+                            </TableRow>
+                        ))}
+                    </TableBody>
+                </Table>
+            </div>
+        </section>
+    );
+}

package/src/docs/doc-page.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import {Badge} from "@repraze/kernelkit/components/badge";
+import {
+    PageHeader,
+    PageHeaderDescription,
+    PageHeaderEyebrow,
+    PageHeaderTitle,
+} from "@repraze/kernelkit/components/page-header";
+import {Pager, PagerLink} from "@repraze/kernelkit/components/pager";
+import {SiteAside, SiteLayout, SiteMain, SiteSidebar} from "@repraze/kernelkit/components/site-layout";
+import {Toc, TocItem, TocList, TocTitle, useTocActive} from "@repraze/kernelkit/components/toc";
+import {ExternalLinkIcon} from "lucide-react";
+import type * as React from "react";
+
+import {Demo, type DocEntry, PropsTable, slugify} from "./doc-kit";
+import type {DocsIndex} from "./docs-index";
+
+/** A router link to a docs page, used as a `render` element: `(slug) => <Link to="/docs/$slug" params={{slug}} />`. */
+export type DocLinkFor = (slug: string) => React.ReactElement;
+
+/** The table of contents of a page: its demos, the notes' sections, then the API. */
+export function docToc(doc: DocEntry): {id: string; title: string}[] {
+    return [
+        ...doc.demos.map((demo) => ({id: slugify(demo.title), title: demo.title})),
+        ...(doc.sections ?? []),
+        ...(doc.props?.length ? [{id: "api", title: "API"}] : []),
+    ];
+}
+
+export interface DocPageProps<Category extends string = string> {
+    /** The loaded page (`index.loadDoc(slug)`, usually from the route's loader). */
+    doc: DocEntry<Category>;
+    index: DocsIndex<Category>;
+    linkFor: DocLinkFor;
+}
+
+/**
+ * A docs page in the suite's layout (GUIDELINES §7b): PageHeader (category, source badge, title,
+ * description), the demos, the notes, the API tables and the Pager in SiteMain; the Toc in SiteAside.
+ */
+export function DocPage<Category extends string>({doc, index, linkFor}: DocPageProps<Category>) {
+    const {prev, next} = index.neighbours(doc.slug);
+    const Notes = doc.notes;
+    const sections = docToc(doc);
+    const active = useTocActive(sections.map((s) => s.id));
+
+    return (
+        <>
+            <SiteMain>
+                <PageHeader>
+                    <PageHeaderEyebrow>
+                        <Badge variant="outline">{doc.category}</Badge>
+                        {doc.source ? (
+                            <Badge
+                                variant="secondary"
+                                className="font-mono"
+                                render={<a href={doc.source.href} target="_blank" rel="noreferrer" />}
+                            >
+                                {doc.source.label} <ExternalLinkIcon />
+                            </Badge>
+                        ) : null}
+                    </PageHeaderEyebrow>
+                    <PageHeaderTitle>{doc.title}</PageHeaderTitle>
+                    <PageHeaderDescription>{doc.description}</PageHeaderDescription>
+                </PageHeader>
+
+                {doc.demos.map((demo, i) => (
+                    <Demo key={demo.title} demo={demo} code={doc.demoSources[i] ?? ""} />
+                ))}
+
+                {Notes ? (
+                    <div className="flex flex-col gap-4">
+                        <Notes />
+                    </div>
+                ) : null}
+
+                {doc.props?.length ? (
+                    <section id="api" className="flex scroll-mt-24 flex-col gap-6">
+                        <h2 className="font-heading text-xl font-semibold">API</h2>
+                        {doc.props.map((p) => (
+                            <PropsTable key={p.component} {...p} />
+                        ))}
+                    </section>
+                ) : null}
+
+                <Pager>
+                    {prev ? (
+                        <PagerLink direction="previous" render={linkFor(prev.slug)}>
+                            {prev.title}
+                        </PagerLink>
+                    ) : null}
+                    {next ? (
+                        <PagerLink direction="next" render={linkFor(next.slug)}>
+                            {next.title}
+                        </PagerLink>
+                    ) : null}
+                </Pager>
+            </SiteMain>
+            {sections.length > 1 ? (
+                <SiteAside>
+                    <Toc>
+                        <TocTitle>On this page</TocTitle>
+                        <TocList>
+                            {sections.map((s) => (
+                                <TocItem key={s.id} href={`#${s.id}`} active={s.id === active}>
+                                    {s.title}
+                                </TocItem>
+                            ))}
+                        </TocList>
+                    </Toc>
+                </SiteAside>
+            ) : null}
+        </>
+    );
+}
+
+/** The suite's docs layout: SiteLayout with the docs nav in a sticky SiteSidebar, then the page (which adds its Toc). */
+export function DocsLayout({nav, children}: {nav: React.ReactNode; children: React.ReactNode}) {
+    return (
+        <SiteLayout>
+            <SiteSidebar>{nav}</SiteSidebar>
+            {children}
+        </SiteLayout>
+    );
+}