@designtools/docs 0.0.0-stage → 0.2.0

package/src/type-ramp.tsx

@@ -0,0 +1,150 @@
+import type { ReactNode } from "react";
+import { shortName, tokensOfTier, typeScale, withGroupDescriptions } from "./lib/manifest";
+import type { TokensManifest } from "./lib/manifest-types";
+
+type Token = TokensManifest["tokens"][number];
+
+/** `1.125rem` → `18px`, so a person reads the size they know. */
+function px(value?: string): string | undefined {
+  const m = value && /^(\d*\.?\d+)rem$/.exec(value.trim());
+  return m ? `${Math.round(Number(m[1]) * 16 * 100) / 100}px` : undefined;
+}
+
+/**
+ * Type, set in its own tokens: each family as a specimen, then the scale, each
+ * size with the leading and tracking Tailwind pairs with it, then weights,
+ * leading and tracking on their own. Every sample reads its token; nothing is restated.
+ */
+export function TypeRamp({
+  tokens,
+  sample = "The quick brown fox jumps over the lazy dog",
+}: {
+  tokens: TokensManifest;
+  sample?: string;
+}) {
+  const steps = withGroupDescriptions(typeScale(tokens).map((s) => ({ ...s, description: s.size.description })));
+  const families = tokensOfTier(tokens, "font");
+  const weights = tokensOfTier(tokens, "font-weight");
+  const leading = tokensOfTier(tokens, "leading");
+  const tracking = tokensOfTier(tokens, "tracking");
+
+  return (
+    <div data-slot="type-ramp" className="flex flex-col gap-14">
+      {families.length > 0 && (
+        <div className="grid gap-x-12 gap-y-10 md:grid-cols-2">
+          {families.map((f) => (
+            <figure key={f.name} data-slot="type-family" className="flex flex-col gap-5 border-t border-border pt-6">
+              <div className="flex flex-col gap-6" style={{ fontFamily: `var(${f.name})` }}>
+                <span className="text-8xl leading-none font-light tracking-tighter">Aa</span>
+                <span className="text-sm leading-relaxed break-all text-muted-foreground">
+                  ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789 &amp;?!
+                </span>
+              </div>
+              <figcaption className="flex flex-col gap-0.5">
+                <code className="font-mono text-xs font-medium">{shortName(f, "font")}</code>
+                <span className="truncate font-mono text-xs text-muted-foreground" title={f.values.default}>
+                  {f.description ?? f.values.default}
+                </span>
+              </figcaption>
+            </figure>
+          ))}
+        </div>
+      )}
+
+      <ol data-slot="type-scale" className="flex flex-col">
+        {steps.map((step) => (
+          <li key={step.name} data-slot="type-step" className="grid grid-cols-1 gap-3 border-t border-border py-5 md:grid-cols-[11rem_minmax(0,1fr)] md:items-center md:gap-6">
+            <div className="flex flex-col gap-1">
+              <span className="flex items-baseline gap-2">
+                <code className="font-mono text-xs font-semibold">{shortName(step.size, "text")}</code>
+                <span className="font-mono text-xs text-muted-foreground">{px(step.size.values.default) ?? step.size.values.default}</span>
+              </span>
+              <span className="font-mono text-xs text-muted-foreground">
+                {[step.lineHeight && `lh ${step.lineHeight.values.default}`, step.letterSpacing && `tr ${step.letterSpacing.values.default}`].filter(Boolean).join(" · ")}
+              </span>
+              {step.description && <span className="text-xs text-muted-foreground">{step.description}</span>}
+            </div>
+            <p
+              className="min-w-0 truncate"
+              style={{
+                fontSize: `var(${step.name})`,
+                lineHeight: step.lineHeight ? `var(${step.lineHeight.name})` : undefined,
+                letterSpacing: step.letterSpacing ? `var(${step.letterSpacing.name})` : undefined,
+                fontWeight: step.fontWeight ? `var(${step.fontWeight.name})` : undefined,
+              }}
+            >
+              {sample}
+            </p>
+          </li>
+        ))}
+      </ol>
+
+      {weights.length > 0 && (
+        <Group title="Weights">
+          <ul className="grid grid-cols-2 gap-x-10 gap-y-8 sm:grid-cols-4">
+            {weights.map((t) => (
+              <li key={t.name} className="flex flex-col gap-3 border-t border-border pt-4">
+                <span className="text-4xl leading-none tracking-tight" style={{ fontWeight: `var(${t.name})` }}>
+                  Aa
+                </span>
+                <Meta token={t} prefix="font-weight" />
+              </li>
+            ))}
+          </ul>
+        </Group>
+      )}
+      {(leading.length > 0 || tracking.length > 0) && (
+        <div className="grid gap-10 lg:grid-cols-2">
+          {leading.length > 0 && (
+            <Group title="Leading">
+              <ul className="flex flex-col">
+                {leading.map((t) => (
+                  <li key={t.name} className="grid grid-cols-[6rem_minmax(0,1fr)] gap-4 border-t border-border py-4">
+                    <Meta token={t} prefix="leading" />
+                    <span className="line-clamp-2 text-sm" style={{ lineHeight: `var(${t.name})` }}>
+                      {sample}. {sample}.
+                    </span>
+                  </li>
+                ))}
+              </ul>
+            </Group>
+          )}
+          {tracking.length > 0 && (
+            <Group title="Tracking">
+              <ul className="flex flex-col">
+                {tracking.map((t) => (
+                  <li key={t.name} className="grid grid-cols-[6rem_minmax(0,1fr)] items-center gap-4 border-t border-border py-4">
+                    <Meta token={t} prefix="tracking" />
+                    <span className="truncate text-lg font-medium" style={{ letterSpacing: `var(${t.name})` }}>
+                      {sample}
+                    </span>
+                  </li>
+                ))}
+              </ul>
+            </Group>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function Group({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <div data-slot="type-table" className="flex flex-col gap-4">
+      <h3 className="text-2xl tracking-tight">{title}</h3>
+      {children}
+    </div>
+  );
+}
+
+function Meta({ token, prefix }: { token: Token; prefix: string }) {
+  return (
+    <span className="flex min-w-0 flex-col font-mono text-xs">
+      <span className="font-medium">{shortName(token, prefix)}</span>
+      <span className="truncate text-muted-foreground" title={token.values.default}>
+        {token.values.default}
+      </span>
+    </span>
+  );
+}

package/src/usage.tsx

@@ -0,0 +1,148 @@
+import { ArrowUpRight, CircleCheck, CircleX } from "lucide-react";
+import Link from "next/link";
+import type { ReactNode } from "react";
+import { cx } from "./lib/cx";
+import { slugOf } from "./lib/manifest";
+import type { ComponentEntry, ComponentsManifest } from "./lib/manifest-types";
+import { StatusBadge } from "./lib/status";
+import { inline } from "./lib/text";
+
+/**
+ * When to use a component and when not, side by side, with what to use instead;
+ * then its facts in one strip: status, role, keys, the primitive it wraps and the
+ * elements it replaces. Written by people as JSDoc (`@use`, `@avoid`, `@instead`,
+ * `@status`, `@role`, `@keyboard`); a component without them says so.
+ */
+export function Usage({
+  entry,
+  manifest,
+  basePath = "/design/system",
+}: {
+  entry: ComponentEntry;
+  /** To link `instead` names that are components. */
+  manifest?: ComponentsManifest;
+  basePath?: string;
+}) {
+  const usage = entry.usage;
+  const known = new Map((manifest?.components ?? []).map((c) => [c.name, c]));
+  const instead = usage?.instead?.length ? (
+    <p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
+      Use instead
+      {usage.instead.map((name) => {
+        const c = known.get(name);
+        return c ? (
+          <Link
+            key={name}
+            href={`${basePath}/components/${slugOf(c)}`}
+            className="relative inline-flex items-center gap-0.5 text-canvas-foreground underline decoration-border underline-offset-4 hover:decoration-current focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-3 after:content-['']"
+          >
+            {name}
+            <ArrowUpRight aria-hidden className="size-3.5 text-muted-foreground" />
+          </Link>
+        ) : (
+          <span key={name} className="font-medium text-canvas-foreground">
+            {name}
+          </span>
+        );
+      })}
+    </p>
+  ) : null;
+
+  const facts: [string, ReactNode][] = [["Status", <Status key="s" entry={entry} />]];
+  if (entry.a11y?.role) facts.push(["Role", <code key="r" className="font-mono text-xs">{entry.a11y.role}</code>]);
+  if (entry.a11y?.keyboard?.length)
+    facts.push([
+      "Keyboard",
+      <span key="k" className="flex flex-wrap gap-1">
+        {entry.a11y.keyboard.map((k) => (
+          <kbd key={k} className="rounded-sm border border-border px-1.5 font-mono text-xs leading-5">
+            {k}
+          </kbd>
+        ))}
+      </span>,
+    ]);
+  if (entry.primitive) facts.push(["Built on", <Source key="p" href={entry.primitive} />]);
+  if (entry.replaces?.length)
+    facts.push([
+      "Replaces",
+      <span key="x" className="flex flex-wrap gap-1">
+        {entry.replaces.map((r) => (
+          <code key={r} className="font-mono text-xs">
+            {`<${r}>`}
+          </code>
+        ))}
+      </span>,
+    ]);
+
+  return (
+    <div data-slot="usage" className="flex flex-col gap-10">
+      {usage?.use || usage?.avoid ? (
+        <div className="grid gap-10 md:grid-cols-2 md:gap-12">
+          <Column tone="do" title="Use it for">
+            {usage?.use ? inline(usage.use) : <span className="text-muted-foreground">Not written yet.</span>}
+          </Column>
+          <Column tone="dont" title="Not for" footer={instead}>
+            {usage?.avoid ? inline(usage.avoid) : <span className="text-muted-foreground">Not written yet.</span>}
+          </Column>
+        </div>
+      ) : (
+        <p className="text-base text-muted-foreground">
+          No usage guidance yet. Add <code className="font-mono text-sm">@use</code>, <code className="font-mono text-sm">@avoid</code> and{" "}
+          <code className="font-mono text-sm">@instead</code> to its JSDoc.
+        </p>
+      )}
+      <dl data-slot="usage-facts" className="flex flex-wrap gap-x-12 gap-y-6">
+        {facts.map(([term, detail]) => (
+          <div key={term} className="flex min-w-0 flex-col gap-2">
+            <dt className="text-xs text-muted-foreground">{term}</dt>
+            <dd className="text-sm">{detail}</dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  );
+}
+
+/** One side of when to use it: a hairline, a small label with its icon in the status colour, and the guidance at reading size. */
+function Column({ tone, title, footer, children }: { tone: "do" | "dont"; title: string; footer?: ReactNode; children: ReactNode }) {
+  const Icon = tone === "do" ? CircleCheck : CircleX;
+  return (
+    <div className="flex flex-col gap-3 border-t border-border pt-5">
+      <p className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Icon aria-hidden className={cx("size-4", tone === "do" ? "text-success-subdued-foreground" : "text-destructive-subdued-foreground")} />
+        {title}
+      </p>
+      <p className="text-lg leading-relaxed text-canvas-foreground/85 [&_code]:bg-transparent [&_code]:p-0 [&_code]:text-[0.875em]">{children}</p>
+      {footer}
+    </div>
+  );
+}
+
+function Status({ entry }: { entry: ComponentEntry }) {
+  return (
+    <span className="flex flex-col items-start gap-1.5">
+      <StatusBadge status={entry.status} />
+      {entry.statusNote && <span className="text-xs text-muted-foreground">{inline(entry.statusNote)}</span>}
+    </span>
+  );
+}
+
+/** A primitive: a link names the site and the page (`Base UI · avatar`), a package path shows as code. */
+function Source({ href }: { href: string }) {
+  if (!/^https?:/.test(href)) return <code className="font-mono text-xs">{href}</code>;
+  const url = new URL(href);
+  const name = url.pathname.split("/").filter(Boolean).pop() ?? "";
+  const host = url.host.replace(/^www\./, "");
+  const site = host === "base-ui.com" ? "Base UI" : host.replace(/\.[a-z]+$/, "");
+  return (
+    <a
+      href={href}
+      title={href}
+      className="group inline-flex items-center gap-1 whitespace-nowrap hover:underline hover:underline-offset-4 focus-visible:outline-2 focus-visible:outline-ring"
+    >
+      {site}
+      {name && <span className="text-muted-foreground">· {name}</span>}
+      <ArrowUpRight aria-hidden className="size-3.5 text-muted-foreground" />
+    </a>
+  );
+}

package/src/variant-matrix.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+import { Live } from "./lib/live";
+import { Grid3x3, Moon, Sun } from "lucide-react";
+import { type ReactNode, useEffect, useState } from "react";
+import { cx } from "./lib/cx";
+import { coerce, Missing, useLookup } from "./lib/lookup";
+import type { ComponentEntry, VariantAxis } from "./lib/manifest-types";
+import { installPseudoStates } from "./lib/pseudo";
+import { Frame, IconButton, Toolbar } from "./lib/ui";
+
+/**
+ * Every variant, rendered live. The first two axes form a grid; each further
+ * axis gets its own row, with the others at their defaults. Pass `props` for
+ * anything the component needs to render (an `options` list, a `value`).
+ */
+export function VariantMatrix({
+  entry,
+  props = {},
+  children,
+  axes: only,
+}: {
+  entry: ComponentEntry;
+  props?: Record<string, unknown>;
+  /** What to render inside each instance. Defaults to the component's name. */
+  children?: ReactNode;
+  /** Limit and order the axes shown. */
+  axes?: string[];
+}) {
+  const lookup = useLookup();
+  const Component = lookup.componentFor(entry);
+  const [theme, setTheme] = useState<"light" | "dark" | undefined>();
+  const all = entry.variants?.axes ?? [];
+  const axes = only ? only.map((n) => all.find((a) => a.name === n)).filter((a): a is VariantAxis => !!a) : all;
+  if (!Component) return <Missing name={entry.name} />;
+  if (axes.length === 0) return <p className="text-sm text-muted-foreground">{entry.name} has no variants.</p>;
+
+  const content = children ?? entry.name;
+  const render = (extra: Record<string, string>) => (
+    <Live>
+      <Component {...props} {...coerce(extra)}>
+        {content}
+      </Component>
+    </Live>
+  );
+  const [rows, cols, ...rest] = axes;
+  const toggle = (
+    <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")}
+    />
+  );
+
+  return (
+    <Frame data-slot="variant-matrix">
+      <Toolbar>
+        <span className="flex items-center gap-2 pl-2 font-mono text-xs text-muted-foreground">
+          <Grid3x3 aria-hidden className="size-(--dt-size-xs)" />
+          {cols ? `${rows.name} × ${cols.name}` : rows.name}
+          {rest.length > 0 && `, ${rest.map((a) => a.name).join(", ")}`}
+        </span>
+        {toggle}
+      </Toolbar>
+      {/* one stage: the matrix, any further axes and the states, separated by space rather than rules */}
+      <div data-docs-stage="" data-theme={theme} className="flex flex-col gap-12 bg-canvas px-6 py-8 text-canvas-foreground sm:px-8">
+        {cols ? (
+          <div className="overflow-x-auto" tabIndex={0} role="region" aria-label="Variants">
+            <table className="w-full border-collapse text-sm">
+              <caption className="sr-only">
+                {entry.name}: {rows.name} by {cols.name}
+              </caption>
+              <thead>
+                <tr>
+                  <th scope="col" className="w-0 p-0" />
+                  {cols.options.map((c) => (
+                    <th key={c.name} scope="col" title={c.description} className="px-4 pb-4 text-center font-mono text-xs font-normal text-muted-foreground">
+                      <OptionName axis={cols} option={c.name} />
+                    </th>
+                  ))}
+                </tr>
+              </thead>
+              <tbody>
+                {rows.options.map((r) => (
+                  <tr key={r.name}>
+                    <th scope="row" title={r.description} className="py-4 pr-6 text-left font-mono text-xs font-normal whitespace-nowrap text-muted-foreground">
+                      <OptionName axis={rows} option={r.name} />
+                    </th>
+                    {cols.options.map((c) => (
+                      <td key={c.name} data-slot="variant-cell" className="px-4 py-4 text-center align-middle">
+                        <span className="inline-flex justify-center">{render({ [rows.name]: r.name, [cols.name]: c.name })}</span>
+                      </td>
+                    ))}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        ) : (
+          <AxisRow axis={rows} render={render} />
+        )}
+        {rest.map((axis) => (
+          <AxisRow key={axis.name} axis={axis} render={render} />
+        ))}
+        <States render={render} canDisable={"disabled" in entry.props} />
+      </div>
+    </Frame>
+  );
+}
+
+/** A titled row of figures inside the variants stage. */
+function Group({ title, slot, children }: { title: string; slot: string; children: ReactNode }) {
+  return (
+    <section data-slot={slot} className="flex flex-col gap-5">
+      <h3 className="font-mono text-xs text-muted-foreground">{title}</h3>
+      <div className="flex flex-wrap items-end gap-x-10 gap-y-6">{children}</div>
+    </section>
+  );
+}
+
+/**
+ * The component at its defaults in each state at once: at rest, hovered, focused,
+ * pressed and disabled, pinned without a pointer or a keyboard, so states are
+ * reviewed side by side rather than by mousing over each.
+ */
+function States({ render, canDisable }: { render: (extra: Record<string, string>) => ReactNode; canDisable: boolean }) {
+  useEffect(() => installPseudoStates(), []);
+  const states: { name: string; pseudo?: string; extra?: Record<string, string> }[] = [
+    { name: "rest" },
+    { name: "hover", pseudo: "hover" },
+    { name: "focus", pseudo: "focus" },
+    { name: "press", pseudo: "active" },
+    ...(canDisable ? [{ name: "disabled", extra: { disabled: "true" } }] : []),
+  ];
+  return (
+    <Group title="state" slot="variant-states">
+      {states.map((s) => (
+        <figure key={s.name} className="flex flex-col items-center gap-3">
+          <div data-pseudo={s.pseudo}>{render(s.extra ?? {})}</div>
+          <figcaption className="font-mono text-xs text-muted-foreground">{s.name}</figcaption>
+        </figure>
+      ))}
+    </Group>
+  );
+}
+
+function AxisRow({ axis, render }: { axis: VariantAxis; render: (extra: Record<string, string>) => ReactNode }) {
+  return (
+    <Group title={axis.name} slot="variant-axis">
+      {axis.options.map((o) => (
+        <figure key={o.name} className="flex flex-col items-center gap-3">
+          {render({ [axis.name]: o.name })}
+          <figcaption className="font-mono text-xs text-muted-foreground" title={o.description}>
+            <OptionName axis={axis} option={o.name} />
+          </figcaption>
+        </figure>
+      ))}
+    </Group>
+  );
+}
+
+/** An option's name, with the default marked by a dot and said for screen readers. */
+function OptionName({ axis, option }: { axis: VariantAxis; option: string }) {
+  const isDefault = axis.default === option;
+  return (
+    <span className={cx("inline-flex items-center gap-1.5", isDefault && "text-canvas-foreground")}>
+      {option}
+      {isDefault && (
+        <>
+          <span aria-hidden className="size-1.5 rounded-full bg-[var(--docs-accent,var(--primary))]" />
+          <span className="sr-only">(default)</span>
+        </>
+      )}
+    </span>
+  );
+}
+

package/src/voice-terms.tsx

@@ -0,0 +1,37 @@
+import type { TermEntry } from "./lib/manifest-types";
+import { TermHead, TermRow } from "./lib/terms";
+import { DocsSection } from "./shell";
+
+/** The words to use, beside the ones not to: the product's words first, then the system's names that have wrong forms. */
+export function VoiceTerms({ terms }: { terms: TermEntry[] }) {
+  const product = terms.filter((t) => t.kind === "product");
+  const system = terms.filter((t) => t.kind !== "product" && t.wrong?.length);
+  if (product.length + system.length === 0) return <p className="text-sm text-muted-foreground">No terms yet. Add them to the taxonomy file.</p>;
+  return (
+    <>
+      {product.length > 0 && (
+        <DocsSection title="In the product" lead="The words the product uses with the people it serves, in copy, on screens and in emails.">
+          <Terms terms={product} />
+        </DocsSection>
+      )}
+      {system.length > 0 && (
+        <DocsSection title="In the system" lead="The names the design system gives its parts, and the ones people reach for instead.">
+          <Terms terms={system} />
+        </DocsSection>
+      )}
+    </>
+  );
+}
+
+function Terms({ terms }: { terms: TermEntry[] }) {
+  return (
+    <div data-slot="voice-terms">
+      <TermHead />
+      <dl>
+        {terms.map((t) => (
+          <TermRow key={`${t.kind}:${t.name}`} term={t} />
+        ))}
+      </dl>
+    </div>
+  );
+}