@designtools/docs 0.0.0-stage → 0.1.0

package/src/rule.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import { Bot, Eye, Hash, ShieldCheck } from "lucide-react";
+import type { ReactNode } from "react";
+import { CodeView } from "./code-view";
+import { cx } from "./lib/cx";
+import { ruleMarkdown } from "./lib/markdown";
+import type { RuleEntry } from "./lib/manifest-types";
+import { StatusBadge } from "./lib/status";
+import { inline, Prose } from "./lib/text";
+import { Eyebrow, Segmented, SegmentedList, SegmentedPanel, Stage } from "./lib/ui";
+
+const CHECK: Record<string, string> = { test: "Tested", lint: "Linted", audit: "Audited", manual: "Checked by a person" };
+
+/**
+ * One rule, brand or interface, written for people: the statement set large, the
+ * line it draws, what it applies to and the check that proves it, then why. A
+ * switch shows the same rule as an agent reads it. Pass a demonstration as
+ * children where the rule needs persuading; it is shown on a stage.
+ */
+export function Rule({ rule, children }: { rule: RuleEntry; children?: ReactNode }) {
+  const chips = (items: string[], mono = false) => (
+    <span className="flex flex-wrap gap-1.5">
+      {items.map((t) => (
+        <span key={t} className={cx("inline-flex min-h-6 items-center rounded-sm bg-muted px-1.5 text-xs", mono && "font-mono")}>
+          {t}
+        </span>
+      ))}
+    </span>
+  );
+  const facts: [string, ReactNode][] = [];
+  if (rule.threshold) facts.push(["Threshold", <span key="t" className="font-medium">{rule.threshold}</span>]);
+  if (rule.appliesTo?.length) facts.push(["Applies to", chips(rule.appliesTo)]);
+  if (rule.exceptions?.length) facts.push(["Exceptions", <span key="e">{rule.exceptions.join("; ")}</span>]);
+  if (rule.tokens?.length) facts.push(["Tokens", chips(rule.tokens, true)]);
+
+  return (
+    <article id={rule.id} data-slot="rule" className="scroll-mt-24 border-t border-border pt-8">
+      <Segmented defaultValue="rendered">
+        <header className="flex flex-wrap items-start justify-between gap-3">
+          <div className="flex min-w-0 flex-col gap-2">
+            <span className="flex flex-wrap items-center gap-2">
+              <StatusBadge status={rule.status} />
+              <span className="text-xs font-medium text-muted-foreground">{rule.kind === "brand" ? "Brand rule" : "Interface rule"}</span>
+            </span>
+            <h3 className="group flex items-center gap-2 text-3xl tracking-tight">
+              {rule.title}
+              <a
+                href={`#${rule.id}`}
+                aria-label={`Link to ${rule.title}`}
+                className="relative inline-flex size-7 items-center justify-center rounded-md text-muted-foreground opacity-0 group-hover:opacity-100 hover:bg-muted focus-visible:opacity-100 focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-2 after:content-['']"
+              >
+                <Hash aria-hidden className="size-4" />
+              </a>
+            </h3>
+          </div>
+          <SegmentedList
+            label={`${rule.title}, two ways`}
+            items={[
+              { value: "rendered", label: "For people", icon: Eye },
+              { value: "agent", label: "For agents", icon: Bot },
+            ]}
+          />
+        </header>
+        <SegmentedPanel value="rendered" className="flex flex-col gap-6 pt-4">
+          <p data-slot="rule-statement" className="max-w-3xl text-xl leading-snug tracking-tight">
+            {inline(rule.statement)}
+          </p>
+          {children && (
+            <div data-slot="rule-demonstration" className="overflow-hidden rounded-xl border border-border">
+              <Stage className="min-h-40">{children}</Stage>
+            </div>
+          )}
+          {facts.length > 0 && (
+            <dl className="grid gap-x-10 gap-y-5 sm:grid-cols-2">
+              {facts.map(([term, detail]) => (
+                <div key={term} className="flex flex-col gap-1.5">
+                  <dt className="text-xs font-medium text-muted-foreground">{term}</dt>
+                  <dd className="text-sm">{detail}</dd>
+                </div>
+              ))}
+            </dl>
+          )}
+          {rule.check && (
+            <div className="flex items-start gap-2.5 text-sm">
+              <ShieldCheck aria-hidden className="mt-0.5 size-(--dt-size-xs) shrink-0 text-muted-foreground" />
+              <p className="flex flex-col gap-0.5">
+                <span className="font-medium">
+                  {CHECK[rule.check.kind] ?? rule.check.kind}
+                  {rule.check.ref && (
+                    <>
+                      {" "}
+                      by <code className="font-mono text-xs">{rule.check.ref}</code>
+                    </>
+                  )}
+                </span>
+                {rule.check.description && <span className="text-muted-foreground">{inline(rule.check.description)}</span>}
+              </p>
+            </div>
+          )}
+          {rule.rationale && (
+            <div className="flex max-w-3xl flex-col gap-2">
+              <Eyebrow>Why</Eyebrow>
+              <div className="flex flex-col gap-2 text-sm text-muted-foreground">
+                <Prose text={rule.rationale} />
+              </div>
+            </div>
+          )}
+        </SegmentedPanel>
+        <SegmentedPanel value="agent" className="pt-4">
+          <CodeView code={ruleMarkdown(rule)} lang="markdown" label={`${rule.id}.md`} wrap />
+        </SegmentedPanel>
+      </Segmented>
+    </article>
+  );
+}

package/src/scale.tsx

@@ -0,0 +1,175 @@
+import type { ReactNode } from "react";
+import { shortName, tokensOfTier, withGroupDescriptions } from "./lib/manifest";
+import type { TokenEntry, TokenTier, TokensManifest } from "./lib/manifest-types";
+
+/** Steps drawn for a single `--spacing` multiplier, as Tailwind's p-1, p-2, … would use it. */
+const SPACING_STEPS = [1, 2, 3, 4, 6, 8, 12, 16, 24];
+
+const TITLE: Partial<Record<TokenTier, [string, string]>> = {
+  spacing: ["Space", "The gap between things: padding, margin and gap."],
+  size: ["Size", "The extent of a thing: icons, avatars and control heights."],
+  radius: ["Radius", "Corners, scaled to the element: bigger box, bigger step."],
+  shadow: ["Elevation", "How far a thing lifts from the page."],
+  duration: ["Duration", "How long a change takes. Point at a row to play it."],
+  ease: ["Easing", "How a change moves. Point at a row to play it."],
+};
+
+/**
+ * Everything that is not colour or type: space, size, radius, elevation and
+ * motion, each tier drawn the way it is used. Pass `tiers` to show only some, in your order.
+ */
+export function Scale({
+  tokens,
+  tiers = ["spacing", "size", "radius", "shadow", "duration", "ease"],
+}: {
+  tokens: TokensManifest;
+  tiers?: TokenTier[];
+}) {
+  return (
+    <div data-slot="scale" className="flex flex-col gap-14">
+      {tiers.map((tier) => {
+        const rows = tokensOfTier(tokens, tier);
+        if (rows.length === 0) return null;
+        const [title, lead] = TITLE[tier] ?? [tier, ""];
+        return (
+          <section key={tier} data-slot="scale-tier" className="flex flex-col gap-4">
+            <header className="flex flex-col gap-1">
+              <h3 className="text-2xl tracking-tight capitalize">{title}</h3>
+              {lead && <p className="text-sm text-muted-foreground">{lead}</p>}
+            </header>
+            {tier === "spacing" ? (
+              <Spacing rows={rows} />
+            ) : tier === "duration" || tier === "ease" ? (
+              <MotionRows rows={rows} tier={tier} />
+            ) : (
+              <Tiles rows={rows} tier={tier} />
+            )}
+          </section>
+        );
+      })}
+    </div>
+  );
+}
+
+const card = "rounded-2xl border border-border bg-surface text-surface-foreground";
+
+function Spacing({ rows }: { rows: TokenEntry[] }) {
+  const multiplier = rows.find((t) => t.name === "--spacing");
+  const named = rows.filter((t) => t !== multiplier);
+  return (
+    <div className="flex flex-col gap-4">
+      {multiplier && (
+        <div className={`${card} flex flex-col gap-1 p-5`}>
+          <p className="mb-3 text-xs text-muted-foreground">
+            {multiplier.description ?? "One multiplier"} · <code className="font-mono">--spacing: {multiplier.values.default}</code>
+          </p>
+          <ul className="flex flex-col gap-2">
+            {SPACING_STEPS.map((n) => (
+              <li key={n} className="grid grid-cols-[3rem_4rem_1fr] items-center gap-3 font-mono text-xs">
+                <span className="font-medium">{n}</span>
+                <span className="text-muted-foreground">{n * 4}px</span>
+                <span
+                  data-slot="scale-bar"
+                  className="h-5 rounded-sm border border-primary-subdued-foreground/40 bg-primary-subdued"
+                  style={{ width: `calc(var(--spacing) * ${n})` }}
+                />
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+      {named.length > 0 && <Tiles rows={named} tier="spacing" />}
+    </div>
+  );
+}
+
+function Tiles({ rows, tier }: { rows: TokenEntry[]; tier: TokenTier }) {
+  return (
+    <ul className={tier === "shadow" ? "grid grid-cols-2 gap-4 lg:grid-cols-3" : "grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-4"}>
+      {rows.map((t) => (
+        <li key={t.name} data-slot="scale-row" className={`${card} flex flex-col overflow-hidden`}>
+          <div
+            className={
+              tier === "shadow"
+                ? "flex h-36 items-center justify-center bg-canvas p-6"
+                : "flex h-28 items-center justify-center bg-[radial-gradient(color-mix(in_oklch,var(--border)_85%,transparent)_1px,transparent_1px)] [background-size:14px_14px] p-4"
+            }
+          >
+            {sample(t, tier)}
+          </div>
+          <div className="flex flex-col gap-0.5 border-t border-border px-4 py-3 font-mono text-xs">
+            <span className="font-medium">{shortName(t, tier)}</span>
+            {tier !== "shadow" && (
+              <span className="truncate text-muted-foreground" title={t.values.default}>
+                {t.values.default}
+              </span>
+            )}
+            {t.description && (
+              <span className="truncate font-sans text-muted-foreground" title={t.description}>
+                {t.description}
+              </span>
+            )}
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function MotionRows({ rows, tier }: { rows: TokenEntry[]; tier: TokenTier }) {
+  return (
+    <ul className={`${card} flex flex-col divide-y divide-border overflow-hidden`}>
+      {withGroupDescriptions(rows).map((t) => (
+        // focusable, so a keyboard can play a row as a pointer does
+        // biome-ignore lint/a11y/noNoninteractiveTabindex: a row a keyboard can focus to play its motion
+        <li key={t.name} data-slot="scale-row" tabIndex={0} className="group grid grid-cols-1 items-center gap-3 px-5 py-4 outline-none hover:bg-muted/50 focus-visible:bg-muted/50 md:grid-cols-[12rem_minmax(0,1fr)]">
+          <span className="flex min-w-0 flex-col font-mono text-xs">
+            <span className="font-medium">{shortName(t, tier)}</span>
+            <span className="truncate text-muted-foreground" title={t.values.default}>
+              {t.values.default}
+            </span>
+            {t.description && <span className="truncate font-sans text-muted-foreground">{t.description}</span>}
+          </span>
+          <span className="min-w-0">
+            {tier === "duration" ? (
+              <Motion duration={`var(${t.name})`} easing="var(--dt-ease-out, ease-out)" />
+            ) : (
+              <Motion duration="var(--dt-duration-slow, 400ms)" easing={`var(${t.name})`} />
+            )}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function sample(t: TokenEntry, tier: TokenTier): ReactNode {
+  const v = `var(${t.name})`;
+  switch (tier) {
+    case "spacing":
+      return <span className="block h-5 rounded-sm bg-primary-subdued" style={{ width: v }} />;
+    case "size":
+      return <span className="block rounded-md border border-primary-subdued-foreground/40 bg-primary-subdued" style={{ width: v, height: v }} />;
+    case "radius":
+      return <span className="block size-16 border-2 border-primary-subdued-foreground/60 bg-primary-subdued" style={{ borderRadius: v }} />;
+    case "shadow":
+      return <span className="block h-16 w-28 rounded-lg bg-surface" style={{ boxShadow: v }} />;
+    default:
+      return <span className="font-mono text-xs">{t.values.default}</span>;
+  }
+}
+
+/** A dot that crosses its track when the row is pointed at or focused. Reduced motion jumps instead. */
+function Motion({ duration, easing }: { duration: string; easing: string }) {
+  return (
+    <span data-slot="scale-motion" className="relative block h-6 w-full rounded-full bg-muted">
+      {/* the runner is the track less the dot, so translating it by its own width lands the dot at the end */}
+      <span
+        className="absolute inset-y-1 right-5 left-1 block transition-transform group-hover:translate-x-full group-focus-visible:translate-x-full motion-reduce:transition-none"
+        style={{ transitionDuration: duration, transitionTimingFunction: easing }}
+      >
+        <span className="block size-4 rounded-full bg-primary shadow-sm" />
+      </span>
+    </span>
+  );
+}

package/src/search.tsx

@@ -0,0 +1,155 @@
+"use client";
+
+import { Autocomplete } from "@base-ui/react/autocomplete";
+import { Dialog } from "@base-ui/react/dialog";
+import { Search } from "lucide-react";
+import { useRouter } from "next/navigation";
+import { useEffect, useId, useMemo, useState } from "react";
+import { cx, target } from "./lib/cx";
+import { search, type SearchGroup, type SearchItem } from "./lib/search";
+
+const PLURAL: Record<SearchGroup["kind"], string> = { Component: "Components", Rule: "Rules", Pattern: "Patterns", Page: "Pages" };
+
+/**
+ * Find a component, a part, a rule, a pattern or a page by name, fuzzily, and go
+ * there. A wrong name finds the right thing ("Dropdown" finds Select, and says
+ * so). Opens with ⌘K or Ctrl+K anywhere, or / when you are not typing. Build the
+ * items with `searchIndex` from `lib/search`; the shell does, when you pass it the
+ * taxonomy. Navigation only: it does not search page text.
+ */
+export function DocsSearch({
+  items,
+  shortcuts = true,
+  variant = "field",
+  className,
+}: {
+  items: SearchItem[];
+  /** Listen for ⌘K, Ctrl+K and /. Give one search on a page the shortcuts. */
+  shortcuts?: boolean;
+  /** A field with its shortcut, or an icon on its own for a phone's top bar. */
+  variant?: "field" | "icon";
+  className?: string;
+}) {
+  const router = useRouter();
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [shortcut, setShortcut] = useState("Ctrl K");
+  const hintId = useId();
+  const groups = useMemo(() => search(items, query), [items, query]);
+
+  useEffect(() => {
+    if (/Mac|iPhone|iPad/.test(navigator.platform)) setShortcut("⌘K");
+    if (!shortcuts) return;
+    const onKey = (e: KeyboardEvent) => {
+      const typing = e.target instanceof HTMLElement && (e.target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName));
+      if ((e.key === "k" && (e.metaKey || e.ctrlKey)) || (e.key === "/" && !typing && !e.metaKey && !e.ctrlKey && !e.altKey)) {
+        e.preventDefault();
+        setOpen(true);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [shortcuts]);
+
+  const go = (item: SearchItem) => {
+    setOpen(false);
+    setQuery("");
+    router.push(item.href);
+  };
+
+  return (
+    <Dialog.Root open={open} onOpenChange={(next) => (setOpen(next), next || setQuery(""))}>
+      {variant === "icon" ? (
+        <Dialog.Trigger
+          data-slot="docs-search-trigger"
+          aria-label="Search the design system"
+          className={cx(
+            "inline-flex size-(--docs-target,2.75rem) shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring",
+            className,
+          )}
+        >
+          <Search aria-hidden className="size-(--dt-size-sm)" />
+        </Dialog.Trigger>
+      ) : (
+        <Dialog.Trigger
+          data-slot="docs-search-trigger"
+          className={cx(
+            target,
+            "flex w-full items-center gap-2.5 rounded-md border border-border bg-canvas px-3 text-sm text-muted-foreground transition-colors duration-(--dt-duration-fast) hover:border-input hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
+            className,
+          )}
+        >
+          <Search aria-hidden className="size-(--dt-size-xs) shrink-0" />
+          <span className="flex-1 text-left">Search</span>
+          <kbd className="rounded-sm border border-border bg-surface px-1.5 py-0.5 font-mono text-xs pointer-coarse:hidden">{shortcut}</kbd>
+        </Dialog.Trigger>
+      )}
+      <Dialog.Portal>
+        <Dialog.Backdrop data-designtools="" className="fixed inset-0 z-40 bg-canvas-foreground/30 backdrop-blur-xs transition-opacity duration-(--dt-duration-base) data-ending-style:opacity-0 data-starting-style:opacity-0" />
+        <Dialog.Viewport data-designtools="" className="fixed inset-0 z-50 flex items-start justify-center px-4 pt-[12dvh]">
+          <Dialog.Popup
+            data-slot="docs-search"
+            aria-label="Search the design system"
+            className="flex max-h-[min(36rem,80dvh)] w-full max-w-xl flex-col overflow-hidden rounded-xl border border-border bg-overlay text-overlay-foreground shadow-xl transition-[opacity,scale] duration-(--dt-duration-base) ease-(--dt-ease-out) data-ending-style:scale-[0.98] data-ending-style:opacity-0 data-starting-style:scale-[0.98] data-starting-style:opacity-0"
+          >
+            <Autocomplete.Root
+              open
+              inline
+              items={groups}
+              filter={null}
+              value={query}
+              onValueChange={(next) => setQuery(next)}
+              itemToStringValue={(item: SearchItem) => item.label}
+              autoHighlight="always"
+              keepHighlight
+            >
+              <div className="flex items-center gap-3 border-b border-border px-4">
+                <Search aria-hidden className="size-(--dt-size-sm) shrink-0 text-muted-foreground" />
+                <Autocomplete.Input
+                  aria-label="Search components, rules, patterns and pages"
+                  aria-describedby={hintId}
+                  placeholder="Search components, rules, patterns…"
+                  className="h-(--dt-size-3xl) w-full bg-transparent text-lg outline-none placeholder:text-muted-foreground"
+                />
+              </div>
+              <Dialog.Close className="sr-only">Close search</Dialog.Close>
+              <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain p-2">
+                <Autocomplete.Empty>
+                  <p className="px-4 py-6 text-sm text-muted-foreground">{query.trim() ? `Nothing called “${query.trim()}”.` : "Type a name, or a name you half remember."}</p>
+                </Autocomplete.Empty>
+                <Autocomplete.List>
+                  {(group: SearchGroup) => (
+                    <Autocomplete.Group key={group.kind} items={group.items} className="not-last:mb-2">
+                      <Autocomplete.GroupLabel className="px-3 pt-2 pb-1 text-xs font-medium tracking-wide text-muted-foreground uppercase">{PLURAL[group.kind]}</Autocomplete.GroupLabel>
+                      <Autocomplete.Collection>
+                        {(item: SearchGroup["items"][number]) => (
+                          <Autocomplete.Item
+                            key={item.href}
+                            value={item}
+                            onClick={() => go(item)}
+                            className={cx(
+                              target,
+                              "flex cursor-pointer items-center justify-between gap-3 rounded-md px-3 py-2 text-sm outline-none select-none data-highlighted:bg-muted",
+                            )}
+                          >
+                            <span className="min-w-0 truncate font-medium">{item.label}</span>
+                            <span className="shrink-0 text-xs text-muted-foreground">
+                              {item.matched ? `for “${item.matched}”` : item.detail}
+                            </span>
+                          </Autocomplete.Item>
+                        )}
+                      </Autocomplete.Collection>
+                    </Autocomplete.Group>
+                  )}
+                </Autocomplete.List>
+              </div>
+              <p id={hintId} className="border-t border-border px-4 py-2 text-xs text-muted-foreground">
+                Arrow keys to move, Enter to go, Escape to close.
+              </p>
+            </Autocomplete.Root>
+          </Dialog.Popup>
+        </Dialog.Viewport>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}