ruler-components 0.1.0

package/components/docs/getting-started-doc-page.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import { useState } from "react";
+import { Compass } from "lucide-react";
+import { Accordion, AccordionItem } from "@/components/ui/accordion";
+import { Badge } from "@/components/ui/badge";
+import { CodeBlock } from "@/components/ui/code-block";
+import { PackageManagerTabs } from "@/components/ui/package-manager-tabs";
+import { DocsPage, DocsPageHeader, DocsSection } from "@/components/docs/docs-page";
+import { NextSteps } from "@/components/docs/next-steps";
+import { cn } from "@/lib/cn";
+
+const PREREQUISITES = ["Node.js 18+", "React 18+", "Tailwind CSS 4", "TypeScript (recommended)"];
+
+const FRAMEWORKS = [
+  {
+    id: "next",
+    label: "Next.js",
+    create: "npx create-next-app@latest my-app --typescript",
+    cssFile: "app/globals.css",
+  },
+  {
+    id: "vite",
+    label: "Vite",
+    create: "npm create vite@latest my-app -- --template react-ts",
+    cssFile: "src/index.css",
+  },
+  {
+    id: "cra",
+    label: "Create React App",
+    create: "npx create-react-app my-app --template typescript",
+    cssFile: "src/index.css",
+  },
+] as const;
+
+const THEME_CSS = (cssFile: string) => `/* ${cssFile} */
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #09090b;
+}
+
+.dark {
+  --background: #09090b;
+  --foreground: #fafafa;
+}`;
+
+const APP_CODE = `import { Button } from 'ruler.ui'
+
+export function App() {
+  return <Button variant="primary">Get Started</Button>
+}`;
+
+function StepNumber({ index }: { index: number }) {
+  return (
+    <span className="absolute -left-12 flex h-8 w-8 items-center justify-center rounded-full bg-zinc-900 text-sm font-semibold text-white dark:bg-white dark:text-zinc-900">
+      {index}
+    </span>
+  );
+}
+
+export function GettingStartedDocPage() {
+  const [framework, setFramework] = useState<(typeof FRAMEWORKS)[number]>(FRAMEWORKS[0]);
+
+  return (
+    <DocsPage>
+      <DocsPageHeader
+        icon={Compass}
+        title="Getting Started"
+        description="A complete walkthrough — from a blank project to your first themed component."
+      />
+
+      <DocsSection first title="Prerequisites" description="What you'll need before you start.">
+        <div className="flex flex-wrap gap-2">
+          {PREREQUISITES.map((item) => (
+            <Badge key={item} variant="outline">
+              {item}
+            </Badge>
+          ))}
+        </div>
+      </DocsSection>
+
+      <DocsSection
+        title="Choose your framework"
+        description="Pick whichever you're starting from — the rest of this guide adjusts automatically."
+      >
+        <div className="flex flex-wrap items-center gap-1 rounded-lg border border-zinc-200 bg-zinc-50 p-1 dark:border-zinc-800 dark:bg-zinc-900/60 sm:w-fit">
+          {FRAMEWORKS.map((f) => (
+            <button
+              key={f.id}
+              type="button"
+              onClick={() => setFramework(f)}
+              className={cn(
+                "flex-1 rounded-md px-3.5 py-1.5 text-sm font-medium transition-colors sm:flex-none",
+                framework.id === f.id
+                  ? "bg-white text-zinc-900 shadow-sm dark:bg-zinc-800 dark:text-white"
+                  : "text-zinc-500 hover:text-zinc-800 dark:text-zinc-400 dark:hover:text-zinc-200"
+              )}
+            >
+              {f.label}
+            </button>
+          ))}
+        </div>
+      </DocsSection>
+
+      <DocsSection
+        title="Step by step"
+        description={`Setting up ruler.ui in a ${framework.label} project.`}
+      >
+        <div className="relative flex flex-col gap-10 pl-12">
+          <span className="absolute -left-[1.9375rem] top-8 bottom-8 w-px bg-zinc-200 dark:bg-zinc-800" aria-hidden />
+
+          <div className="relative">
+            <StepNumber index={1} />
+            <h3 className="text-base font-semibold text-zinc-900 dark:text-white">Create a project</h3>
+            <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+              Skip this if you already have a {framework.label} app.
+            </p>
+            <div className="mt-3">
+              <CodeBlock code={framework.create} />
+            </div>
+          </div>
+
+          <div className="relative">
+            <StepNumber index={2} />
+            <h3 className="text-base font-semibold text-zinc-900 dark:text-white">Install ruler.ui</h3>
+            <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+              Add the package with whichever manager you prefer.
+            </p>
+            <div className="mt-3">
+              <PackageManagerTabs />
+            </div>
+          </div>
+
+          <div className="relative">
+            <StepNumber index={3} />
+            <h3 className="text-base font-semibold text-zinc-900 dark:text-white">Add the theme variables</h3>
+            <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+              Two CSS variables drive every component — light values on{" "}
+              <code className="font-mono text-xs">:root</code>, dark values under{" "}
+              <code className="font-mono text-xs">.dark</code>.
+            </p>
+            <div className="mt-3">
+              <CodeBlock code={THEME_CSS(framework.cssFile)} />
+            </div>
+          </div>
+
+          <div className="relative">
+            <StepNumber index={4} />
+            <h3 className="text-base font-semibold text-zinc-900 dark:text-white">Render your first component</h3>
+            <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+              Import from <code className="font-mono text-xs">ruler.ui</code> like any other package.
+            </p>
+            <div className="mt-3 overflow-hidden rounded-2xl border border-zinc-200/50 bg-zinc-950 shadow-2xl dark:border-zinc-800/60">
+              <CodeBlock code={APP_CODE} filename="App.tsx" />
+            </div>
+          </div>
+
+          <div className="relative">
+            <StepNumber index={5} />
+            <h3 className="text-base font-semibold text-zinc-900 dark:text-white">Wire up dark mode</h3>
+            <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+              ruler.ui doesn&apos;t ship a theme provider — toggle the{" "}
+              <code className="font-mono text-xs">.dark</code> class on{" "}
+              <code className="font-mono text-xs">&lt;html&gt;</code> however fits your app (a button,{" "}
+              <code className="font-mono text-xs">next-themes</code>, a stored cookie). See{" "}
+              <a href="/docs/theming" className="font-medium text-zinc-900 underline underline-offset-2 dark:text-white">
+                Theming
+              </a>{" "}
+              for the full picture.
+            </p>
+          </div>
+        </div>
+      </DocsSection>
+
+      <DocsSection title="Troubleshooting" description="Common issues when wiring things up for the first time.">
+        <div className="rounded-2xl border border-zinc-200 p-2 shadow-[0_1px_2px_rgba(0,0,0,0.03)] dark:border-zinc-800">
+          <Accordion defaultValue="1">
+            <AccordionItem value="1" title="Styles aren't applying to components">
+              Make sure your Tailwind content globs pick up ruler.ui's source — components ship as plain
+              TypeScript/JSX, so Tailwind needs to scan{" "}
+              <code className="font-mono text-xs">node_modules/ruler.ui/**/*.{"{js,ts,jsx,tsx}"}</code> (or the
+              equivalent for your Tailwind version) alongside your own app files.
+            </AccordionItem>
+            <AccordionItem value="2" title="Dark mode doesn't switch">
+              Confirm something is actually toggling the <code className="font-mono text-xs">.dark</code> class on{" "}
+              <code className="font-mono text-xs">&lt;html&gt;</code> — ruler.ui reads that class but never sets it
+              itself, by design.
+            </AccordionItem>
+            <AccordionItem value="3" title="TypeScript can't find component types">
+              ruler.ui ships its own <code className="font-mono text-xs">.d.ts</code> files. If imports resolve but
+              types don&apos;t, check that <code className="font-mono text-xs">moduleResolution</code> in your{" "}
+              <code className="font-mono text-xs">tsconfig.json</code> is set to{" "}
+              <code className="font-mono text-xs">"bundler"</code> or <code className="font-mono text-xs">"node16"</code>{" "}
+              or newer.
+            </AccordionItem>
+          </Accordion>
+        </div>
+      </DocsSection>
+
+      <NextSteps />
+    </DocsPage>
+  );
+}

package/components/docs/label-doc-page.tsx

@@ -0,0 +1,173 @@
+import React from "react";
+import { Tag } from "lucide-react";
+import { Field } from "@/components/ui/label";
+import { Input } from "@/components/ui/input";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import {
+  DocsAccessibility,
+  DocsApiSection,
+  DocsApiTable,
+  DocsPage,
+  DocsPageHeader,
+  DocsSection,
+  DocsSectionGrid,
+} from "@/components/docs/docs-page";
+
+const API_ROWS = [
+  { prop: "htmlFor", type: "string", default: "—", description: "Associates the label with a form control" },
+  { prop: "required", type: "boolean", default: "false", description: "Shows a required asterisk indicator" },
+  { prop: "optional", type: "boolean", default: "false", description: "Shows an optional tag on the right" },
+  { prop: "hint", type: "string", default: "—", description: "Helper text displayed below the label" },
+  { prop: "error", type: "string", default: "—", description: "Error message displayed below the label" },
+  { prop: "variant", type: '"default" | "muted"', default: '"default"', description: "The visual style of the label" },
+  { prop: "size", type: '"sm" | "md" | "lg"', default: '"md"', description: "The size of the label text" },
+];
+
+const FIELD_API_ROWS = [
+  { prop: "label", type: "string", default: "—", description: "Label text for the field" },
+  { prop: "htmlFor", type: "string", default: "—", description: "ID of the associated input" },
+  { prop: "required", type: "boolean", default: "false", description: "Marks the field as required" },
+  { prop: "optional", type: "boolean", default: "false", description: "Marks the field as optional" },
+  { prop: "hint", type: "string", default: "—", description: "Helper text below the label" },
+  { prop: "error", type: "string", default: "—", description: "Validation error message" },
+  { prop: "children", type: "ReactNode", default: "—", description: "The form control element" },
+];
+
+const ACCESSIBILITY_ITEMS = [
+  "Always associate labels with form controls using htmlFor.",
+  "Don't use placeholder text as a substitute for labels.",
+  "Required fields should be indicated visually and programmatically.",
+  "Error messages should use role=\"alert\" for screen readers.",
+  "Clicking a label should focus or activate the associated control.",
+];
+
+export function LabelDocPage() {
+  return (
+    <DocsPage>
+      <DocsPageHeader
+        icon={Tag}
+        title="Label"
+        description="Gives every input a clear, accessible name — with built-in support for hints, errors, and required states."
+      />
+
+      <DocsSection
+        first
+        title="Contact Form"
+        description="A real-world form using the Field helper for consistent spacing and hierarchy."
+      >
+        <div className="max-w-md">
+          <Card>
+            <CardHeader>
+              <CardTitle>Get in touch</CardTitle>
+              <CardDescription>We&apos;ll respond within one business day.</CardDescription>
+            </CardHeader>
+            <CardContent className="space-y-4 pt-1">
+              <Field label="Full name" htmlFor="contact-name" required>
+                <Input id="contact-name" placeholder="Jane Cooper" />
+              </Field>
+              <Field label="Email address" htmlFor="contact-email" required hint="We'll never share your email.">
+                <Input id="contact-email" type="email" placeholder="jane@company.com" />
+              </Field>
+              <Field label="Company" htmlFor="contact-company" optional>
+                <Input id="contact-company" placeholder="Acme Inc." />
+              </Field>
+            </CardContent>
+            <CardFooter>
+              <Button size="sm">Send message</Button>
+            </CardFooter>
+          </Card>
+        </div>
+      </DocsSection>
+
+      <DocsSection title="States" description="Required, hinted, error, and optional variants of a field.">
+        <DocsSectionGrid>
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-base">Required</CardTitle>
+              <CardDescription>Marks the field with a required asterisk.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Field label="Username" htmlFor="username-demo" required>
+                <Input id="username-demo" placeholder="johndoe" />
+              </Field>
+            </CardContent>
+          </Card>
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-base">With Hint</CardTitle>
+              <CardDescription>Adds helper text below the label.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Field label="Password" htmlFor="password-demo" hint="Use 8+ characters with a number and symbol.">
+                <Input id="password-demo" type="password" placeholder="••••••••" />
+              </Field>
+            </CardContent>
+          </Card>
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-base">Error State</CardTitle>
+              <CardDescription>Surfaces a validation message below the field.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Field label="Email address" htmlFor="email-error" error="Please enter a valid email address.">
+                <Input id="email-error" state="error" defaultValue="not-an-email" />
+              </Field>
+            </CardContent>
+          </Card>
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-base">Optional Field</CardTitle>
+              <CardDescription>Flags the field as optional with a hint.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Field label="Phone number" htmlFor="phone-optional" optional hint="Include country code if outside the US.">
+                <Input id="phone-optional" type="tel" placeholder="+1 (555) 000-0000" />
+              </Field>
+            </CardContent>
+          </Card>
+        </DocsSectionGrid>
+      </DocsSection>
+
+      <DocsSection title="Sizes" description="Three label sizes to match the paired input.">
+        <Card>
+          <CardContent className="grid max-w-md gap-4 pt-6">
+            <Field label="Small" htmlFor="size-sm" labelSize="sm">
+              <Input id="size-sm" size="sm" />
+            </Field>
+            <Field label="Medium" htmlFor="size-md" labelSize="md">
+              <Input id="size-md" size="md" />
+            </Field>
+            <Field label="Large" htmlFor="size-lg" labelSize="lg">
+              <Input id="size-lg" size="lg" />
+            </Field>
+          </CardContent>
+        </Card>
+      </DocsSection>
+
+      <DocsSection
+        title="Standalone Label"
+        description="Use Label directly when pairing with custom controls like checkboxes."
+      >
+        <Checkbox
+          label="I agree to the terms and conditions"
+          description="You must accept before continuing."
+        />
+      </DocsSection>
+
+      <DocsApiSection>
+        <DocsApiTable title="API Reference — Label" rows={API_ROWS} />
+        <DocsApiTable title="API Reference — Field" rows={FIELD_API_ROWS} />
+        <DocsAccessibility items={ACCESSIBILITY_ITEMS} />
+      </DocsApiSection>
+    </DocsPage>
+  );
+}

package/components/docs/loaders-doc-page.tsx

@@ -0,0 +1,244 @@
+"use client";
+
+import React, { useState } from "react";
+import { Check, Copy, Loader2 } from "lucide-react";
+import * as UI from "@/components/ui/loaders";
+import { Tooltip } from "@/components/ui/tooltip";
+import {
+  DocsAccessibility,
+  DocsApiSection,
+  DocsDemoPanel,
+  DocsPage,
+  DocsPageHeader,
+  DocsSection,
+  DocsSimpleTable,
+} from "@/components/docs/docs-page";
+import { cn } from "@/lib/cn";
+
+const PLAYGROUND_LOADERS = {
+  SpinnerGradient: UI.SpinnerGradient,
+  ProgressRing: UI.ProgressRing,
+  SpinnerDots: UI.SpinnerDots,
+  DotWave: UI.DotWave,
+  PulseLoader: UI.PulseLoader,
+  SquaresLoader: UI.SquaresLoader,
+  MorphingLoader: UI.MorphingLoader,
+  AILoader: UI.AILoader,
+} as const;
+
+type PlaygroundLoader = keyof typeof PLAYGROUND_LOADERS;
+
+const PLAYGROUND_STYLES: PlaygroundLoader[] = [
+  "SpinnerGradient",
+  "ProgressRing",
+  "SpinnerDots",
+  "DotWave",
+  "PulseLoader",
+  "SquaresLoader",
+  "MorphingLoader",
+  "AILoader",
+];
+
+function codeFor(style: PlaygroundLoader) {
+  return `import { ${style} } from "@/components/ui/loaders";\n\n<${style} />`;
+}
+
+function LoaderSwatch({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <div className="flex h-12 items-center justify-center">{children}</div>
+      <span className="text-xs text-zinc-500 dark:text-zinc-400">{label}</span>
+    </div>
+  );
+}
+
+const LOADER_ROWS = [
+  { name: "ProgressRing", description: "A rotating ring with a partial arc — the default spinner." },
+  { name: "SpinnerGradient", description: "A bordered circle spinning with a solid leading edge." },
+  { name: "SpinnerDots", description: "Eight dots fading around a circle, iOS-style." },
+  { name: "HalfCircles", description: "Two overlapping arcs spinning at different opacities." },
+  { name: "SquaresLoader", description: "Two squares pulsing out of phase." },
+  { name: "LoadBar", description: "A pill-shaped track with a bar sweeping across it." },
+  { name: "PulseLoader", description: "A dot with an expanding, fading ring around it." },
+  { name: "MorphingLoader", description: "A shape that morphs between a square and a circle while rotating." },
+  { name: "ThreeDots", description: "Three dots pulsing in sequence — compact inline status." },
+  { name: "DotWave", description: "Three dots bouncing in a wave pattern." },
+  { name: "TypingIndicator", description: "A chat-bubble-style typing indicator." },
+  { name: "ProgressBar", description: "An indeterminate linear progress bar." },
+  { name: "SkeletonShimmer", description: "A shimmering placeholder block for loading content." },
+  { name: "OrbitLoader", description: "A particle orbiting a fixed center dot." },
+  { name: "AILoader", description: "A spinning ring around a pulsing sparkle, with a status label." },
+  { name: "BlurReveal", description: "Fades and sharpens content into view once it's ready." },
+];
+
+const ACCESSIBILITY_ITEMS = [
+  "Pair loaders with an aria-live region or aria-busy so screen readers announce the loading state.",
+  "Give icon-only loaders an accessible label (e.g. aria-label=\"Loading\") — the animation alone conveys nothing to assistive tech.",
+  "Avoid loaders that flash faster than 3 times per second — they can trigger photosensitive reactions.",
+  "Show a loader only after a short delay (~300ms) so fast responses don't flicker unnecessarily.",
+  "Replace the loader with the real content or an error state as soon as it's ready — never leave it spinning indefinitely.",
+];
+
+export function LoadersDocPage() {
+  const [style, setStyle] = useState<PlaygroundLoader>("SpinnerGradient");
+  const [copied, setCopied] = useState(false);
+
+  const SelectedLoader = PLAYGROUND_LOADERS[style];
+  const snippet = codeFor(style);
+
+  function copySnippet() {
+    navigator.clipboard.writeText(snippet).catch(() => {});
+    setCopied(true);
+    setTimeout(() => setCopied(false), 1200);
+  }
+
+  return (
+    <DocsPage>
+      <DocsPageHeader
+        icon={Loader2}
+        title="Loaders"
+        description="Loading indicators for every context — spinners, progress bars, and AI-style status animations."
+      />
+
+      <DocsSection
+        first
+        title="Playground"
+        description="Switch between styles and copy the exact markup — live, with the animation restarting each time."
+      >
+        <div className="overflow-hidden rounded-2xl border border-zinc-200 shadow-[0_2px_8px_rgba(0,0,0,0.04)] dark:border-zinc-800 dark:shadow-[0_2px_8px_rgba(0,0,0,0.2)]">
+          <div className="relative flex min-h-[11rem] items-center justify-center overflow-hidden bg-zinc-50 p-6 dark:bg-zinc-900/40">
+            <div
+              aria-hidden
+              className="pointer-events-none absolute inset-0 opacity-[0.4] dark:opacity-[0.15]"
+              style={{
+                backgroundImage:
+                  "linear-gradient(to right, rgb(161 161 170 / 0.35) 1px, transparent 1px), linear-gradient(to bottom, rgb(161 161 170 / 0.35) 1px, transparent 1px)",
+                backgroundSize: "24px 24px",
+              }}
+            />
+            <div key={style} className="relative animate-[pagination-pop_0.2s_ease-out]">
+              <SelectedLoader />
+            </div>
+          </div>
+
+          <div className="flex flex-col gap-5 border-t border-zinc-200 p-5 dark:border-zinc-800">
+            <div className="flex flex-wrap items-start justify-between gap-6">
+              <div>
+                <p className="mb-2 text-xs font-medium uppercase tracking-wide text-zinc-400 dark:text-zinc-500">
+                  Style
+                </p>
+                <div className="flex flex-wrap gap-1.5">
+                  {PLAYGROUND_STYLES.map((s) => (
+                    <button
+                      key={s}
+                      type="button"
+                      onClick={() => setStyle(s)}
+                      className={cn(
+                        "rounded-lg border px-3 py-1.5 text-xs font-medium transition-colors",
+                        style === s
+                          ? "border-zinc-900 bg-zinc-900 text-white dark:border-white dark:bg-white dark:text-zinc-900"
+                          : "border-zinc-200 text-zinc-500 hover:border-zinc-300 dark:border-zinc-700 dark:text-zinc-400 dark:hover:border-zinc-600"
+                      )}
+                    >
+                      {s}
+                    </button>
+                  ))}
+                </div>
+              </div>
+            </div>
+
+            <div className="flex items-center justify-between gap-3 rounded-xl bg-zinc-900 px-4 py-3 dark:bg-black">
+              <pre className="overflow-x-auto font-mono text-[13px] leading-relaxed text-zinc-100">
+                <code>{snippet}</code>
+              </pre>
+              <Tooltip content={copied ? "Copied!" : "Copy code"}>
+                <button
+                  type="button"
+                  onClick={copySnippet}
+                  className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg text-zinc-400 transition-colors hover:bg-white/10 hover:text-white"
+                >
+                  {copied ? <Check className="h-4 w-4 text-emerald-400" /> : <Copy className="h-4 w-4" />}
+                </button>
+              </Tooltip>
+            </div>
+          </div>
+        </div>
+      </DocsSection>
+
+      <DocsSection title="Circular Spinners" description="Classic rotating indicators for buttons, cards, and page loads.">
+        <DocsDemoPanel>
+          <LoaderSwatch label="Progress Ring">
+            <UI.ProgressRing />
+          </LoaderSwatch>
+          <LoaderSwatch label="Gradient Spinner">
+            <UI.SpinnerGradient />
+          </LoaderSwatch>
+          <LoaderSwatch label="Spinner Dots">
+            <UI.SpinnerDots />
+          </LoaderSwatch>
+          <LoaderSwatch label="Half Circles">
+            <UI.HalfCircles />
+          </LoaderSwatch>
+        </DocsDemoPanel>
+      </DocsSection>
+
+      <DocsSection title="Geometric & Modern" description="Shape-driven motion for a distinct, branded feel.">
+        <DocsDemoPanel>
+          <LoaderSwatch label="Squares Motion">
+            <UI.SquaresLoader />
+          </LoaderSwatch>
+          <LoaderSwatch label="Pill Load Bar">
+            <UI.LoadBar />
+          </LoaderSwatch>
+          <LoaderSwatch label="Pulse Dot">
+            <UI.PulseLoader />
+          </LoaderSwatch>
+          <LoaderSwatch label="Morphing Shape">
+            <UI.MorphingLoader />
+          </LoaderSwatch>
+        </DocsDemoPanel>
+      </DocsSection>
+
+      <DocsSection title="Status Indicators" description="Compact indicators for inline, chat, and progress contexts.">
+        <DocsDemoPanel>
+          <LoaderSwatch label="Three Dots">
+            <UI.ThreeDots />
+          </LoaderSwatch>
+          <LoaderSwatch label="Dot Wave">
+            <UI.DotWave />
+          </LoaderSwatch>
+          <LoaderSwatch label="Typing Mode">
+            <UI.TypingIndicator />
+          </LoaderSwatch>
+          <LoaderSwatch label="Linear Progress">
+            <UI.ProgressBar />
+          </LoaderSwatch>
+        </DocsDemoPanel>
+      </DocsSection>
+
+      <DocsSection title="Skeleton Placeholder" description="Shimmering blocks that mimic the shape of content while it loads.">
+        <div className="flex max-w-sm items-center gap-4 rounded-2xl border border-zinc-200/70 bg-white p-5 shadow-[0_2px_8px_rgba(0,0,0,0.06)] dark:border-zinc-800/80 dark:bg-zinc-900 dark:shadow-[0_2px_8px_rgba(0,0,0,0.25)]">
+          <UI.SkeletonShimmer className="h-12 w-12 shrink-0 rounded-full" />
+          <div className="flex flex-1 flex-col gap-2.5">
+            <UI.SkeletonShimmer className="h-3 w-3/4" />
+            <UI.SkeletonShimmer className="h-3 w-1/2" />
+          </div>
+        </div>
+      </DocsSection>
+
+      <DocsSection title="Premium & AI" description="Distinct, branded loaders for premium flows and AI responses.">
+        <DocsDemoPanel>
+          <LoaderSwatch label="Orbit Particle">
+            <UI.OrbitLoader />
+          </LoaderSwatch>
+          <UI.AILoader />
+        </DocsDemoPanel>
+      </DocsSection>
+
+      <DocsApiSection>
+        <DocsSimpleTable title="Available Loaders" rows={LOADER_ROWS} />
+        <DocsAccessibility items={ACCESSIBILITY_ITEMS} />
+      </DocsApiSection>
+    </DocsPage>
+  );
+}