@designtools/docs 0.0.0-stage → 0.1.0

package/src/ask-claude.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { Check, Copy, Sparkles } from "lucide-react";
+import { useId, useState } from "react";
+import { importOf } from "./lib/manifest";
+import type { ComponentEntry } from "./lib/manifest-types";
+
+/**
+ * Copies a ready-made prompt for Claude: the component, its source file, the
+ * variant and example in view, and what should change. Paste it into Claude
+ * Code in the project and it starts from the right file.
+ */
+export function AskClaude({
+  entry,
+  variant,
+  example,
+}: {
+  entry: ComponentEntry;
+  /** The variant in view, e.g. `{ intent: "success" }`. */
+  variant?: Record<string, string>;
+  /** The example in view, by export name. */
+  example?: string;
+}) {
+  const id = useId();
+  const [request, setRequest] = useState("");
+  const [copied, setCopied] = useState(false);
+
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(promptFor(entry, request, variant, example));
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      // clipboard refused: nothing changes
+    }
+  };
+
+  return (
+    <div data-slot="ask-claude" className="flex flex-col gap-4 rounded-2xl border border-border bg-surface p-5 text-surface-foreground shadow-xs sm:p-6">
+      <div className="flex items-start gap-3">
+        <span className="flex size-9 shrink-0 items-center justify-center rounded-lg bg-primary-subdued text-primary-subdued-foreground">
+          <Sparkles aria-hidden className="size-(--dt-size-xs)" />
+        </span>
+        <span className="flex flex-col gap-0.5">
+          <label htmlFor={id} className="text-base font-semibold tracking-tight">
+            Ask Claude to change {entry.name}
+          </label>
+          <span className="text-sm text-muted-foreground">
+            Copies a prompt naming the file{example ? ", the example" : ""}, its parts and the variant, ready to paste into Claude Code.
+          </span>
+        </span>
+      </div>
+      <div className="flex flex-col overflow-hidden rounded-xl border border-input bg-canvas focus-within:outline-2 focus-within:outline-ring">
+        <textarea
+          id={id}
+          rows={3}
+          value={request}
+          onChange={(e) => setRequest(e.target.value)}
+          placeholder={`What should change about ${entry.name}?`}
+          className="resize-none bg-transparent px-4 py-3 text-base outline-none placeholder:text-muted-foreground"
+        />
+        <div className="flex items-center justify-between gap-3 px-2 pb-2 pl-4">
+          <code className="truncate font-mono text-xs text-muted-foreground">{entry.source}</code>
+          <button
+            type="button"
+            onClick={copy}
+            className="inline-flex min-h-(--docs-target,2.75rem) shrink-0 cursor-pointer items-center gap-2 rounded-lg bg-primary px-4 text-sm font-medium text-primary-foreground hover:bg-primary-hover focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
+          >
+            {copied ? <Check aria-hidden className="size-(--dt-size-xs)" /> : <Copy aria-hidden className="size-(--dt-size-xs)" />}
+            {copied ? "Copied" : "Copy prompt"}
+          </button>
+        </div>
+      </div>
+      <span className="sr-only" aria-live="polite">
+        {copied ? "Prompt copied" : ""}
+      </span>
+    </div>
+  );
+}
+
+export function promptFor(entry: ComponentEntry, request: string, variant?: Record<string, string>, example?: string): string {
+  const lines = [`Component: ${entry.name}, exported as ${entry.export} from ${entry.source} (imported from "${importOf(entry)}")`];
+  const shown = Object.entries(variant ?? {});
+  if (shown.length) lines.push(`Variant in view: ${shown.map(([k, v]) => `${k}="${v}"`).join(", ")}`);
+  if (example && entry.examples) lines.push(`Example in view: ${example}, from ${entry.examples.source}`);
+  if (entry.status && entry.status !== "stable") lines.push(`Status: ${entry.status}${entry.statusNote ? `. ${entry.statusNote}` : ""}`);
+  if (entry.slots.length) lines.push(`Its parts (data-slot): ${entry.slots.join(", ")}`);
+  lines.push("", request.trim() || "What should change: ");
+  return lines.join("\n");
+}

package/src/code-view.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import { ChevronDown, FileCode } from "lucide-react";
+import { useEffect, useState } from "react";
+import { cx } from "./lib/cx";
+import { CopyButton } from "./lib/ui";
+
+/* Shiki writes both themes as CSS variables; these pick the one for the page's mode, and number the lines. */
+const THEME_CSS = `
+[data-slot="code-view"] .shiki { background: transparent !important; counter-reset: line; }
+[data-slot="code-view"][data-numbered] .shiki .line::before { counter-increment: line; content: counter(line); display: inline-block; width: 2ch; margin-right: 1.25rem; text-align: right; color: var(--muted-foreground); opacity: .6; }
+[data-theme="dark"] [data-slot="code-view"] .shiki, [data-theme="dark"] [data-slot="code-view"] .shiki span { color: var(--shiki-dark) !important; }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) [data-slot="code-view"] .shiki, :root:not([data-theme="light"]) [data-slot="code-view"] .shiki span { color: var(--shiki-dark) !important; }
+}`;
+
+/** Lines past which the code folds, with a fade and a "Show all". */
+const FOLD = 14;
+
+/**
+ * Code, highlighted once Shiki has loaded (it loads on first use, so pages
+ * without code never pay for it) and readable as plain text before then. A file
+ * header with a copy button, numbered lines, and long code folded behind "Show
+ * all". `bare` drops the frame, for code inside another frame.
+ */
+export function CodeView({
+  code,
+  lang = "tsx",
+  label = "Code",
+  wrap = false,
+  bare = false,
+  numbered,
+}: {
+  code: string;
+  lang?: string;
+  label?: string;
+  /** Wrap long lines, for prose such as markdown, instead of scrolling them. */
+  wrap?: boolean;
+  /** No border or header of its own: for code inside an example or playground frame. */
+  bare?: boolean;
+  /** Line numbers. On by default for more than one line of code, off for prose. */
+  numbered?: boolean;
+}) {
+  const [html, setHtml] = useState<string | null>(null);
+  const lines = code.split("\n").length;
+  const [open, setOpen] = useState(lines <= FOLD);
+  const numbers = numbered ?? (!wrap && lines > 1);
+
+  useEffect(() => {
+    let live = true;
+    import("shiki")
+      .then(({ codeToHtml }) => codeToHtml(code, { lang, themes: { light: "github-light", dark: "github-dark" } }))
+      .then((out) => live && setHtml(out))
+      .catch(() => live && setHtml(null));
+    return () => {
+      live = false;
+    };
+  }, [code, lang]);
+
+  const body = cx(
+    "overflow-x-auto px-4 py-3.5 font-mono text-sm leading-relaxed",
+    wrap && "[&_pre]:break-words [&_pre]:whitespace-pre-wrap",
+    // room for the copy button floating at the top right
+    bare && "pr-12",
+    !open && "max-h-96 overflow-y-hidden",
+  );
+
+  return (
+    <figure
+      data-slot="code-view"
+      data-numbered={numbers || undefined}
+      className={cx("relative min-w-0", !bare && "overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground")}
+    >
+      <style>{THEME_CSS}</style>
+      {!bare && (
+        <figcaption className="flex min-h-11 items-center justify-between gap-3 border-b border-border bg-muted/40 py-1 pr-1.5 pl-4 text-xs text-muted-foreground">
+          <span className="flex min-w-0 items-center gap-2">
+            <FileCode aria-hidden className="size-(--dt-size-xs) shrink-0" />
+            <span className="truncate font-medium text-canvas-foreground">{label}</span>
+          </span>
+          <CopyButton text={code} label="Copy code" />
+        </figcaption>
+      )}
+      <div className="relative">
+        {bare && (
+          <span className="absolute top-1.5 right-1.5 z-10">
+            <CopyButton text={code} label="Copy code" />
+          </span>
+        )}
+        {html ? (
+          // biome-ignore lint/security/noDangerouslySetInnerHtml: Shiki's output for code from the manifest, escaped by Shiki
+          <div className={body} tabIndex={0} role="region" aria-label={label} dangerouslySetInnerHTML={{ __html: html }} />
+        ) : (
+          <pre tabIndex={0} aria-label={label} className={cx(body, wrap && "break-words whitespace-pre-wrap")}>
+            <code>{code}</code>
+          </pre>
+        )}
+        {!open && (
+          <div className="absolute inset-x-0 bottom-0 flex h-24 items-end justify-center bg-linear-to-t from-surface via-surface/80 to-transparent pb-3">
+            <button
+              type="button"
+              onClick={() => setOpen(true)}
+              className="inline-flex min-h-(--docs-target,2.75rem) cursor-pointer items-center gap-1.5 rounded-full border border-border bg-surface px-4 text-xs font-medium text-surface-foreground shadow-sm hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring"
+            >
+              Show all {lines} lines <ChevronDown aria-hidden className="size-(--dt-size-xs)" />
+            </button>
+          </div>
+        )}
+      </div>
+    </figure>
+  );
+}

package/src/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/src/examples.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { CircleCheck, CircleX, Code, Eye, Maximize2, Moon, Smartphone, Sun } from "lucide-react";
+import { type ReactNode, useState } from "react";
+import { CodeView } from "./code-view";
+import { Boundary } from "./lib/boundary";
+import { cx } from "./lib/cx";
+import { Missing, renderExample, useLookup } from "./lib/lookup";
+import type { ComponentEntry, ExampleRef } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+import { CopyButton, IconButton, IconLink, Segmented, SegmentedList, SegmentedPanel, Stage, Toolbar } from "./lib/ui";
+
+/**
+ * The canonical example first, the one to copy, then each do beside its don't.
+ * Every example is the real component; the code behind it is the code that drew it.
+ */
+export function Examples({ entry, previewHref }: { entry: ComponentEntry; previewHref?: string }) {
+  const lookup = useLookup();
+  const ex = entry.examples;
+  if (!ex) {
+    return (
+      <p data-slot="examples-empty" className="rounded-xl border border-dashed border-border p-6 text-sm text-muted-foreground">
+        No examples yet. Add <code className="font-mono text-xs">{entry.source.replace(/\.tsx$/, ".examples.tsx")}</code> with a{" "}
+        <code className="font-mono text-xs">canonical</code> export and do and don&apos;t pairs.
+      </p>
+    );
+  }
+  const module = lookup.examplesFor(entry);
+  if (!module) return <Missing name={entry.name} what="examples" />;
+
+  const pairs = Array.from({ length: Math.max(ex.do.length, ex.dont.length) }, (_, i) => [ex.do[i], ex.dont[i]] as const);
+  const frame = (ref: ExampleRef, kind: Kind) => (
+    <ExampleFrame
+      key={ref.name}
+      name={ref.name}
+      kind={kind}
+      description={ref.description}
+      code={ref.code}
+      href={previewHref && `${previewHref}/${encodeURIComponent(ref.name)}`}
+    >
+      {renderExample(module[ref.name], ref.name)}
+    </ExampleFrame>
+  );
+
+  return (
+    <div data-slot="examples" className="flex flex-col gap-10">
+      {ex.canonical && frame(ex.canonical, "canonical")}
+      {pairs.length > 0 && (
+        <div className="flex flex-col gap-6">
+          {pairs.map(([d, n], i) => (
+            <div key={d?.name ?? n?.name ?? i} data-slot="examples-pair" className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+              {d ? frame(d, "do") : <span />}
+              {n ? frame(n, "dont") : <span />}
+            </div>
+          ))}
+        </div>
+      )}
+      {ex.other.length > 0 && <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">{ex.other.map((o) => frame(o, "other"))}</div>}
+    </div>
+  );
+}
+
+type Kind = "canonical" | "do" | "dont" | "other";
+
+const MARK: Record<Kind, { label: string; icon?: typeof CircleCheck; tone: string }> = {
+  // the canonical example is simply first, the usual use; it needs no badge to say so
+  canonical: { label: "", tone: "" },
+  // a measured pairing, never a fill colour used as text (text-success read 3.9:1 on the canvas)
+  do: { label: "Do", icon: CircleCheck, tone: "bg-success-subdued text-success-subdued-foreground" },
+  dont: { label: "Don't", icon: CircleX, tone: "bg-destructive-subdued text-destructive-subdued-foreground" },
+  other: { label: "", tone: "" },
+};
+
+/**
+ * One example in its frame: Preview and Code on a switch, the stage in either mode
+ * or at a phone's width, a copy button, and a link to it alone. The caption says
+ * what kind of example it is and why. Patterns use it for their compositions too.
+ */
+export function ExampleFrame({
+  name,
+  kind = "other",
+  description,
+  code,
+  href,
+  children,
+}: {
+  name: string;
+  kind?: Kind;
+  description?: string;
+  code?: string;
+  href?: string;
+  children: ReactNode;
+}) {
+  const [theme, setTheme] = useState<"light" | "dark" | undefined>();
+  const [narrow, setNarrow] = useState(false);
+  const mark = MARK[kind];
+  const Icon = mark.icon;
+  const views = [{ value: "preview", label: "Preview", icon: Eye }, ...(code ? [{ value: "code", label: "Code", icon: Code }] : [])];
+
+  return (
+    <figure data-slot="example" data-kind={kind} className="flex min-w-0 flex-col gap-3">
+      <Segmented defaultValue="preview" className="overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground shadow-xs">
+        <Toolbar>
+          <SegmentedList items={views} label={`${name}: preview or code`} />
+          <span className="flex items-center gap-0.5">
+            <IconButton icon={Smartphone} label="Phone width" pressed={narrow} onClick={() => setNarrow(!narrow)} />
+            <IconButton
+              icon={theme === "dark" ? Sun : Moon}
+              label={theme === "dark" ? "Show in light mode" : "Show in dark mode"}
+              pressed={theme !== undefined}
+              onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+            />
+            {code && <CopyButton text={code} label="Copy code" />}
+            {href && <IconLink icon={Maximize2} label="Open on its own" href={href} />}
+          </span>
+        </Toolbar>
+        <SegmentedPanel value="preview">
+          <Stage theme={theme} width={narrow ? 375 : undefined} className={kind === "canonical" ? "min-h-64" : "min-h-48"}>
+            <Boundary label={name}>{children}</Boundary>
+          </Stage>
+        </SegmentedPanel>
+        {code && (
+          <SegmentedPanel value="code">
+            <CodeView code={code} label={name} bare />
+          </SegmentedPanel>
+        )}
+      </Segmented>
+      {(mark.label || description) && (
+        <figcaption className="flex items-start gap-2 px-1">
+          {mark.label && (
+            <span className={cx("inline-flex h-6 shrink-0 items-center gap-1.5 rounded-full pr-2.5 pl-2 text-xs font-medium", mark.tone)}>
+              {Icon && <Icon aria-hidden className="size-3.5" />}
+              {mark.label}
+            </span>
+          )}
+          {description && <span className="pt-0.5 text-sm">{inline(description)}</span>}
+        </figcaption>
+      )}
+    </figure>
+  );
+}

package/src/glossary.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { Search } from "lucide-react";
+import { useId, useState } from "react";
+import type { TermEntry } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+
+/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. */
+export function Glossary({ terms }: { terms: TermEntry[] }) {
+  const id = useId();
+  const [query, setQuery] = useState("");
+  const q = query.trim().toLowerCase();
+  const matches = q ? terms.filter((t) => t.name.toLowerCase().includes(q) || t.wrong?.some((w) => w.toLowerCase().includes(q))) : terms;
+  const corrected = q ? terms.find((t) => t.wrong?.some((w) => w.toLowerCase() === q)) : undefined;
+
+  return (
+    <div data-slot="glossary" className="flex flex-col gap-5">
+      <div className="flex flex-col gap-2">
+        <label htmlFor={id} className="sr-only">
+          Find a term
+        </label>
+        <div className="relative max-w-xl">
+          <Search aria-hidden className="pointer-events-none absolute top-1/2 left-4 size-(--dt-size-sm) -translate-y-1/2 text-muted-foreground" />
+          <input
+            id={id}
+            type="search"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            placeholder="Find a term, or a name you half remember"
+            className="h-(--dt-size-2xl) w-full rounded-lg border border-border bg-canvas pr-4 pl-12 text-base placeholder:text-muted-foreground hover:border-input focus-visible:outline-2 focus-visible:outline-ring"
+          />
+        </div>
+        <p aria-live="polite" className="text-sm text-muted-foreground">
+          {corrected ? (
+            <>
+              The system calls “{query.trim()}” <strong className="text-canvas-foreground">{corrected.name}</strong>.
+            </>
+          ) : q ? (
+            `${matches.length} ${matches.length === 1 ? "term" : "terms"}`
+          ) : (
+            `${terms.length} terms`
+          )}
+        </p>
+      </div>
+      <dl data-slot="glossary-list" className="grid gap-x-12 sm:grid-cols-2">
+        {matches.map((t) => (
+          <div key={`${t.kind}:${t.name}`} className="flex flex-col gap-1.5 border-t border-border py-4">
+            <dt className="flex items-center justify-between gap-2">
+              <span className="text-lg">{t.name}</span>
+              <span className="font-mono text-xs text-muted-foreground">{t.kind}</span>
+            </dt>
+            <dd className="flex flex-col gap-1 text-sm text-muted-foreground">
+              {t.wrong?.length ? (
+                <span className="flex flex-wrap items-center gap-1">
+                  Not
+                  {t.wrong.map((w) => (
+                    <s key={w} className="decoration-destructive">
+                      {w}
+                    </s>
+                  ))}
+                </span>
+              ) : null}
+              {t.note && <span>{inline(t.note)}</span>}
+              {t.ref && <code className="font-mono text-xs">{t.ref}</code>}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  );
+}

package/src/imagery.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import { useLookup } from "./lib/lookup";
+import type { AssetEntry } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+import { Stage } from "./lib/ui";
+
+/** The approved icons and imagery, each on a stage with how to use it; an icon is shown at its three sizes too. */
+export function Imagery({ assets, kinds = ["icon", "image", "other"] }: { assets: AssetEntry[]; kinds?: AssetEntry["kind"][] }) {
+  const lookup = useLookup();
+  const shown = assets.filter((a) => kinds.includes(a.kind));
+  if (shown.length === 0) return <p className="text-sm text-muted-foreground">No icons or imagery in the brand folder yet.</p>;
+  return (
+    <ul data-slot="imagery" className="grid grid-cols-1 gap-4 sm:grid-cols-2 xl:grid-cols-3">
+      {shown.map((a) => {
+        const src = lookup.assetUrl(a);
+        const icon = a.kind === "icon";
+        return (
+          <li key={a.file} className="min-w-0">
+            <figure data-slot="asset" className="flex h-full flex-col overflow-hidden rounded-2xl border border-border bg-surface text-surface-foreground shadow-xs">
+              <Stage className="h-44 p-6">
+                {src ? (
+                  icon ? (
+                    // icons drawn in currentColor show in the stage's text colour, in either mode
+                    <span
+                      aria-hidden={!a.alt}
+                      role={a.alt ? "img" : undefined}
+                      aria-label={a.alt || undefined}
+                      className="block size-14 bg-current"
+                      style={{ mask: `url(${src}) center / contain no-repeat`, WebkitMask: `url(${src}) center / contain no-repeat` }}
+                    />
+                  ) : (
+                    <img src={src} alt={a.alt ?? ""} className="max-h-full max-w-full rounded-md object-contain" />
+                  )
+                ) : (
+                  <span className="font-mono text-xs text-muted-foreground">{a.file}</span>
+                )}
+              </Stage>
+              <figcaption className="flex flex-1 flex-col gap-2 border-t border-border p-4 text-sm">
+                <span className="flex items-center justify-between gap-2">
+                  <span className="text-lg">{a.name}</span>
+                  {icon && src ? (
+                    <span aria-hidden className="flex items-end gap-2 text-muted-foreground">
+                      {[16, 20, 24].map((size) => (
+                        <span key={size} className="block bg-current" style={{ width: size, height: size, mask: `url(${src}) center / contain no-repeat`, WebkitMask: `url(${src}) center / contain no-repeat` }} />
+                      ))}
+                    </span>
+                  ) : (
+                    <span className="rounded-full bg-muted px-2 py-0.5 font-mono text-xs text-muted-foreground">{a.kind}</span>
+                  )}
+                </span>
+                <span className="text-muted-foreground">{a.usage ? inline(a.usage) : "No usage notes yet."}</span>
+                <span className="mt-auto pt-1 font-mono text-xs text-muted-foreground">
+                  {a.file}
+                  {a.width && a.height ? ` · ${a.width} × ${a.height}` : ""}
+                </span>
+              </figcaption>
+            </figure>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @designtools/docs: every block, for a project composing its own pages. Most
+ * projects use `@designtools/docs/next` instead, which composes them.
+ */
+export { A11yPanel, AxeReport, useAxe } from "./a11y-panel";
+export { AdherenceSummary } from "./adherence-summary";
+export { AgentInstructions, AgentView } from "./agent-view";
+export { Anatomy } from "./anatomy";
+export { AskClaude } from "./ask-claude";
+export { CodeView } from "./code-view";
+export { ExampleFrame, Examples } from "./examples";
+export { Glossary } from "./glossary";
+export { Imagery } from "./imagery";
+export { LogoUsage } from "./logo-usage";
+export { PageActions } from "./page-actions";
+export { Pattern } from "./pattern";
+export { Playground } from "./playground";
+export { PreviewComposition, PreviewExample, PreviewFrame, PreviewSurface } from "./preview-frame";
+export { PropsTable } from "./props-table";
+export { Rule } from "./rule";
+export { Scale } from "./scale";
+export { DocsSearch } from "./search";
+export { type DocsLink, DocsFooter, DocsHeader, DocsSection, DocsShell } from "./shell";
+export { Standards } from "./standards";
+export { PageContrast, RampSwatches, SemanticSwatches } from "./swatches";
+export { ThemeSwitch, themeScript, useThemeScript } from "./theme-switch";
+export { TypeRamp } from "./type-ramp";
+export { Usage } from "./usage";
+export { VariantMatrix } from "./variant-matrix";
+export { VoiceTerms } from "./voice-terms";
+export { Workbench } from "./workbench";
+export { type Registry, RegistryProvider, useRegistry } from "./lib/registry";
+export * from "./lib/manifest-types";
+export type { AdherenceReport } from "./lib/adherence-types";