@designtools/blocks 0.0.0-stage → 0.1.0

package/registry/scale.tsx

@@ -0,0 +1,115 @@
+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];
+
+/**
+ * Everything that is not colour or type: space, size, radius, elevation and
+ * motion, each tier drawn the way it is used. Hover a motion row to play it.
+ * 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-10">
+      {tiers.map((tier) => {
+        const rows = tokensOfTier(tokens, tier);
+        if (rows.length === 0) return null;
+        return (
+          <div key={tier} data-slot="scale-tier" className="flex flex-col gap-2">
+            <h3 className="text-sm font-medium capitalize">{tier}</h3>
+            {tier === "spacing" ? <Spacing rows={rows} /> : <Rows rows={rows} tier={tier} />}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+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 && (
+        <>
+          <p className="text-xs text-muted-foreground">
+            {multiplier.description ?? "One multiplier"}: <span className="font-mono">--spacing: {multiplier.values.default}</span>
+          </p>
+          <ul className="flex flex-col gap-1.5">
+            {SPACING_STEPS.map((n) => (
+              <li key={n} className="grid grid-cols-[4rem_1fr] items-center gap-3 font-mono text-xs">
+                <span className="text-muted-foreground">{n}</span>
+                <span data-slot="scale-bar" className="h-3 rounded-sm bg-primary" style={{ width: `calc(var(--spacing) * ${n})` }} />
+              </li>
+            ))}
+          </ul>
+        </>
+      )}
+      {named.length > 0 && <Rows rows={named} tier="spacing" />}
+    </div>
+  );
+}
+
+function Rows({ rows, tier }: { rows: TokenEntry[]; tier: TokenTier }) {
+  return (
+    <ul className="flex flex-col divide-y divide-border border-y border-border">
+      {withGroupDescriptions(rows).map((t) => (
+        <li key={t.name} data-slot="scale-row" className="group flex flex-col gap-2 py-3">
+          {t.groupDescription && <p className="text-xs text-muted-foreground">{t.groupDescription}</p>}
+          <div className="grid grid-cols-1 items-center gap-3 md:grid-cols-[10rem_minmax(0,1fr)]">
+            <span className="flex min-w-0 flex-col font-mono text-xs text-muted-foreground">
+              <span className="font-medium text-canvas-foreground">{shortName(t, tier)}</span>
+              <span className="truncate" title={t.values.default}>
+                {t.values.default}
+              </span>
+            </span>
+            <span className="min-w-0">{sample(t, tier)}</span>
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function sample(t: TokenEntry, tier: TokenTier): ReactNode {
+  const v = `var(${t.name})`;
+  switch (tier) {
+    case "spacing":
+      return <span className="block h-3 rounded-sm bg-primary" style={{ width: v }} />;
+    case "size":
+      return <span className="block rounded-sm bg-primary" style={{ width: v, height: v }} />;
+    case "radius":
+      return <span className="block size-16 border-2 border-primary bg-primary-subdued" style={{ borderRadius: v }} />;
+    case "shadow":
+      return <span className="block h-16 w-32 rounded-md bg-surface" style={{ boxShadow: v }} />;
+    case "duration":
+      return <Motion duration={v} easing="var(--ease-out, ease-out)" />;
+    case "ease":
+      return <Motion duration="var(--duration-slow, 400ms)" easing={v} />;
+    default:
+      return <span className="font-mono text-xs">{t.values.default}</span>;
+  }
+}
+
+/** A dot that crosses its track on hover, with the token's duration or easing. Reduced motion jumps instead. */
+function Motion({ duration, easing }: { duration: string; easing: string }) {
+  return (
+    <span data-slot="scale-motion" className="relative block h-4 w-full max-w-sm 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-0 right-4 left-0 block transition-transform group-hover:translate-x-full motion-reduce:transition-none"
+        style={{ transitionDuration: duration, transitionTimingFunction: easing }}
+      >
+        <span className="block size-4 rounded-full bg-primary" />
+      </span>
+    </span>
+  );
+}

package/registry/shell.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import type { ReactNode } from "react";
+import { cx } from "./lib/cx";
+import { groupByCategory, slugOf } from "./lib/manifest";
+import { Prose } from "./lib/text";
+import type { ComponentsManifest, PatternsManifest, RulesManifest } from "./lib/manifest-types";
+
+export interface DocsLink {
+  label: string;
+  href: string;
+}
+
+/**
+ * The docs frame, in the site's order: brand, foundations, rules, patterns,
+ * components by `@category`, standards. Editorial pages are the links you pass;
+ * rules, patterns and components come from the manifest. On a narrow screen
+ * the navigation folds into a disclosure. Put it in the docs layout; it marks
+ * the page you are on.
+ */
+export function DocsShell({
+  manifest,
+  rules,
+  patterns,
+  title = "Design system",
+  basePath = "/design/system",
+  brand = [],
+  foundations = [],
+  standards = [],
+  children,
+}: {
+  manifest: ComponentsManifest;
+  /** Listed under Rules, each linking to its anchor on `${basePath}/rules`. */
+  rules?: RulesManifest;
+  /** Listed under Patterns, each at `${basePath}/patterns/${id}`. */
+  patterns?: PatternsManifest;
+  title?: string;
+  /** Component pages live at `${basePath}/components/${slug}`. */
+  basePath?: string;
+  /** Brand pages: principles, design language, voice, logo, imagery. */
+  brand?: DocsLink[];
+  /** Foundations pages: colour, type, scale. */
+  foundations?: DocsLink[];
+  /** Standards pages: budgets, accessibility, adherence. */
+  standards?: DocsLink[];
+  children: ReactNode;
+}) {
+  const current = usePathname();
+  const groups = [
+    ...(brand.length ? [{ heading: "Brand", links: brand }] : []),
+    ...(foundations.length ? [{ heading: "Foundations", links: foundations }] : []),
+    ...(rules?.rules.length
+      ? [{ heading: "Rules", links: [{ label: "All rules", href: `${basePath}/rules` }] }]
+      : []),
+    ...(patterns?.patterns.length
+      ? [{ heading: "Patterns", links: patterns.patterns.map((p) => ({ label: p.name, href: `${basePath}/patterns/${p.id}` })) }]
+      : []),
+    ...groupByCategory(manifest).map((g) => ({
+      heading: g.category,
+      links: g.components.map((c) => ({ label: c.name, href: `${basePath}/components/${slugOf(c)}` })),
+    })),
+    ...(standards.length ? [{ heading: "Standards", links: standards }] : []),
+  ];
+
+  const nav = (
+    <nav aria-label={title} data-slot="docs-nav" className="flex flex-col gap-6 p-4 text-sm">
+      {groups.map((group) => (
+        <div key={group.heading} data-slot="docs-nav-group" className="flex flex-col gap-1">
+          <p data-slot="docs-nav-heading" className="px-2 text-xs font-medium text-muted-foreground">
+            {group.heading}
+          </p>
+          <ul className="flex flex-col">
+            {group.links.map((link) => {
+              const active = current === link.href;
+              return (
+                <li key={link.href}>
+                  <Link
+                    href={link.href}
+                    aria-current={active ? "page" : undefined}
+                    data-slot="docs-nav-link"
+                    className={cx(
+                      "block rounded-md px-2 py-1.5 hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
+                      active && "bg-muted font-medium",
+                    )}
+                  >
+                    {link.label}
+                  </Link>
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      ))}
+    </nav>
+  );
+
+  return (
+    <div data-slot="docs-shell" className="min-h-dvh bg-canvas text-canvas-foreground md:grid md:grid-cols-[16rem_1fr]">
+      <aside
+        data-slot="docs-sidebar"
+        className="hidden border-r border-border bg-surface text-surface-foreground md:sticky md:top-0 md:block md:h-dvh md:overflow-y-auto"
+      >
+        <Link href={basePath} data-slot="docs-title" className="block px-6 pt-6 pb-2 font-semibold">
+          {title}
+        </Link>
+        {nav}
+      </aside>
+      <details data-slot="docs-nav-disclosure" className="border-b border-border bg-surface text-surface-foreground md:hidden">
+        <summary className="cursor-pointer px-4 py-3 font-semibold">{title}</summary>
+        {nav}
+      </details>
+      <main data-slot="docs-main" className="min-w-0 px-4 py-8 md:px-10 md:py-12">
+        <div className="mx-auto flex max-w-5xl flex-col gap-12">{children}</div>
+      </main>
+    </div>
+  );
+}
+
+/**
+ * A page's heading, lead and source, and where it comes from: a generated page
+ * names the version and commit it was built from; an editorial page names its
+ * author, when it was last reviewed, and whether it is settled. Never both, and
+ * never a review date on a generated page, which would be invented.
+ */
+export function DocsHeader({
+  title,
+  lead,
+  source,
+  provenance,
+  editorial,
+  children,
+}: {
+  title: string;
+  lead?: string;
+  /** Shown as the file the page documents. */
+  source?: string;
+  /** For a generated page: `Generated from acme-web@1.4.0 at 3f2a9c1`, from `designtools-manifest provenance`. */
+  provenance?: string;
+  /** For an editorial page. */
+  editorial?: { author: string; reviewed: string; status: "draft" | "published" };
+  children?: ReactNode;
+}) {
+  return (
+    <header data-slot="docs-header" className="flex flex-col gap-3">
+      {(provenance || editorial) && (
+        <p data-slot="docs-provenance" className="text-xs text-muted-foreground">
+          {editorial
+            ? `Written by ${editorial.author} · last reviewed ${editorial.reviewed} · ${editorial.status}`
+            : `${provenance} · generated from the code`}
+        </p>
+      )}
+      <h1 className="text-3xl font-semibold">{title}</h1>
+      {lead && (
+        <div data-slot="docs-lead" className="flex max-w-prose flex-col gap-3 text-muted-foreground">
+          <Prose text={lead} />
+        </div>
+      )}
+      {source && (
+        <p data-slot="docs-source" className="font-mono text-xs text-muted-foreground">
+          {source}
+        </p>
+      )}
+      {children}
+    </header>
+  );
+}
+
+/** A titled section of a docs page. */
+export function DocsSection({ title, lead, children }: { title: string; lead?: string; children: ReactNode }) {
+  const id = title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  return (
+    <section data-slot="docs-section" aria-labelledby={id} className="flex flex-col gap-4">
+      <div className="flex flex-col gap-1">
+        <h2 id={id} className="text-xl font-semibold">
+          {title}
+        </h2>
+        {lead && <p className="max-w-prose text-sm text-muted-foreground">{lead}</p>}
+      </div>
+      {children}
+    </section>
+  );
+}

package/registry/standards.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from "react";
+
+/**
+ * The project's performance budgets, accessibility target and support baseline,
+ * rendered from the thresholds it already records (`.mxa/stack.json`
+ * `baselines`), so the docs and the checks cannot disagree.
+ */
+export function Standards({ baselines, children }: { baselines: Record<string, unknown>; children?: ReactNode }) {
+  const sections = Object.entries(baselines).filter(([k]) => !k.startsWith("$"));
+  return (
+    <div data-slot="standards" className="flex flex-col gap-8">
+      {sections.map(([name, value]) => (
+        <section key={name} data-slot="standard" className="flex flex-col gap-2">
+          <h3 className="text-sm font-medium">{TITLES[name] ?? name}</h3>
+          {value && typeof value === "object" && !Array.isArray(value) ? (
+            <dl className="grid gap-x-6 gap-y-2 text-sm sm:grid-cols-[12rem_1fr]">
+              {Object.entries(value as Record<string, unknown>).map(([k, v]) => (
+                <div key={k} className="contents">
+                  <dt className="font-mono text-xs">{k}</dt>
+                  <dd className="text-muted-foreground">{show(v)}</dd>
+                </div>
+              ))}
+            </dl>
+          ) : (
+            <p className="text-sm text-muted-foreground">{show(value)}</p>
+          )}
+        </section>
+      ))}
+      {typeof baselines.$note === "string" && <p className="text-sm text-muted-foreground">{baselines.$note}</p>}
+      {children}
+    </div>
+  );
+}
+
+const TITLES: Record<string, string> = {
+  a11y: "Accessibility",
+  performance: "Performance budgets",
+  support: "Support",
+};
+
+function show(v: unknown): string {
+  if (Array.isArray(v)) return v.length ? v.join(", ") : "none set";
+  if (v && typeof v === "object") return JSON.stringify(v);
+  return String(v);
+}

package/registry/swatches.tsx

@@ -0,0 +1,146 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { contrastRatio, wcagGrade } from "./lib/contrast";
+import { cx } from "./lib/cx";
+import { ramps, semanticColours, valueIn, type Mode } from "./lib/manifest";
+import type { TokensManifest } from "./lib/manifest-types";
+
+/**
+ * Colour, painted from the tokens rather than restated: one row per semantic
+ * colour, each mode side by side. Each chip renders inside its own
+ * `data-theme`, so dark is shown as the dark tokens resolve, and each pair's
+ * contrast is measured on the colours the browser actually paints.
+ */
+export function SemanticSwatches({
+  tokens,
+  modes = ["light", "dark"],
+}: {
+  tokens: TokensManifest;
+  modes?: Mode[];
+}) {
+  const colours = semanticColours(tokens);
+  return (
+    <div data-slot="swatches" className="overflow-x-auto">
+      <table className="w-full min-w-[32rem] border-collapse text-left text-sm">
+        <thead>
+          <tr className="border-b border-border text-xs text-muted-foreground">
+            <th scope="col" className="py-2 pr-4 font-medium">
+              Token
+            </th>
+            {modes.map((mode) => (
+              <th key={mode} scope="col" className="py-2 pr-4 font-medium capitalize">
+                {mode}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {colours.map((c) => (
+            <tr key={c.name} data-slot="swatch-row" className="border-b border-border align-middle">
+              <th scope="row" className="py-2 pr-4 font-normal">
+                <code className="font-mono text-xs font-medium">{c.name}</code>
+                {c.foreground && <span className="block font-mono text-xs text-muted-foreground">with {c.foreground.name}</span>}
+              </th>
+              {modes.map((mode) => (
+                <td key={mode} className="py-2 pr-4">
+                  <Swatch
+                    mode={mode}
+                    name={c.name}
+                    background={valueIn(c.background, mode)}
+                    foreground={c.foreground && valueIn(c.foreground, mode)}
+                    paired={!!c.foreground}
+                  />
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+/** `var(--color-primary-500)` → `primary-500`: the step it points at, which is what a person compares. */
+function pointsAt(value: string | undefined): string | undefined {
+  const m = value && /^var\(--color-([\w-]+)\)$/.exec(value);
+  return m ? m[1] : value;
+}
+
+function Swatch({
+  mode,
+  name,
+  background,
+  foreground,
+  paired,
+}: {
+  mode: Mode;
+  name: string;
+  background?: string;
+  foreground?: string;
+  paired: boolean;
+}) {
+  const chip = useRef<HTMLDivElement>(null);
+  const [ratio, setRatio] = useState<number | null>(null);
+
+  useEffect(() => {
+    const node = chip.current;
+    if (!node || !paired) return;
+    const style = getComputedStyle(node);
+    setRatio(contrastRatio(style.color, style.backgroundColor));
+  }, [paired, background, foreground]);
+
+  const grade = ratio === null ? null : wcagGrade(ratio);
+  return (
+    <div data-slot="swatch" className="flex items-center gap-3">
+      {/* only the chip switches mode: the label stays in the page's, where it is read */}
+      <div
+        ref={chip}
+        data-theme={mode}
+        data-slot="swatch-chip"
+        className="flex h-10 w-14 shrink-0 items-center justify-center rounded-md border border-(--border) font-medium"
+        style={{ background: `var(${name})`, color: paired ? `var(${name}-foreground)` : "transparent" }}
+        aria-hidden
+      >
+        Aa
+      </div>
+      <div className="flex min-w-0 flex-col font-mono text-xs">
+        <span className="truncate" title={background}>
+          {pointsAt(background)}
+          {foreground && <span className="text-muted-foreground"> / {pointsAt(foreground)}</span>}
+        </span>
+        {grade && ratio !== null && (
+          <span data-slot="swatch-contrast" className={cx("text-muted-foreground", grade === "Fail" && "font-medium text-destructive")}>
+            {ratio.toFixed(2)}:1 · {grade}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** The primitive ramps, one row per colour family, each step painted from its own token. */
+export function RampSwatches({ tokens }: { tokens: TokensManifest }) {
+  return (
+    <div data-slot="ramps" className="flex flex-col gap-4">
+      {ramps(tokens).map((ramp) => (
+        <div key={ramp.family} data-slot="ramp" className="flex flex-col gap-1.5">
+          <p className="font-mono text-xs font-medium">{ramp.family}</p>
+          <ol className="grid grid-flow-col auto-cols-fr overflow-hidden rounded-md border border-border">
+            {ramp.steps.map(({ step, token }) => (
+              <li
+                key={step}
+                data-slot="ramp-step"
+                title={`${token.name}: ${token.values.default ?? ""}`}
+                className="flex h-14 items-end p-1.5"
+                style={{ background: `var(${token.name})` }}
+              >
+                <span className="rounded-sm bg-canvas/80 px-1 font-mono text-[0.625rem] text-canvas-foreground">{step}</span>
+              </li>
+            ))}
+          </ol>
+        </div>
+      ))}
+    </div>
+  );
+}

package/registry/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["react", "react-dom"],
+    "noEmit": true,
+    "declaration": false,
+    "declarationMap": false,
+    "ignoreDeprecations": "6.0"
+  },
+  "include": ["."]
+}

package/registry/type-ramp.tsx

@@ -0,0 +1,105 @@
+import { shortName, tokensOfTier, typeScale, withGroupDescriptions } from "./lib/manifest";
+import type { TokensManifest } from "./lib/manifest-types";
+
+/**
+ * The type scale, each size set in its own token with the leading and tracking
+ * Tailwind pairs with it, then the families, weights, leading and tracking
+ * tiers 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-10">
+      <ol data-slot="type-scale" className="flex flex-col divide-y divide-border border-y border-border">
+        {steps.map((step) => (
+          <li key={step.name} data-slot="type-step" className="flex flex-col gap-2 py-4">
+            {step.groupDescription && <p className="text-xs text-muted-foreground">{step.groupDescription}</p>}
+            <div className="grid grid-cols-1 gap-2 md:grid-cols-[10rem_minmax(0,1fr)] md:items-baseline">
+              <dl className="flex flex-col font-mono text-xs text-muted-foreground">
+                <dt className="font-medium text-canvas-foreground">{shortName(step.size, "text")}</dt>
+                <dd>{step.size.values.default}</dd>
+                {step.lineHeight && <dd>line-height {step.lineHeight.values.default}</dd>}
+                {step.letterSpacing && <dd>tracking {step.letterSpacing.values.default}</dd>}
+              </dl>
+              <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>
+            </div>
+          </li>
+        ))}
+      </ol>
+
+      {families.length > 0 && (
+        <TokenTable title="Families" rows={families} prefix="font" render={(t) => <span style={{ fontFamily: `var(${t.name})` }}>{sample}</span>} />
+      )}
+      {weights.length > 0 && (
+        <TokenTable title="Weights" rows={weights} prefix="font-weight" render={(t) => <span style={{ fontWeight: `var(${t.name})` }}>{sample}</span>} />
+      )}
+      {leading.length > 0 && (
+        <TokenTable
+          title="Leading"
+          rows={leading}
+          prefix="leading"
+          render={(t) => (
+            <span className="block max-w-sm text-sm" style={{ lineHeight: `var(${t.name})` }}>
+              {sample}. {sample}.
+            </span>
+          )}
+        />
+      )}
+      {tracking.length > 0 && (
+        <TokenTable title="Tracking" rows={tracking} prefix="tracking" render={(t) => <span style={{ letterSpacing: `var(${t.name})` }}>{sample}</span>} />
+      )}
+    </div>
+  );
+}
+
+function TokenTable({
+  title,
+  rows,
+  prefix,
+  render,
+}: {
+  title: string;
+  rows: TokensManifest["tokens"];
+  prefix: string;
+  render: (token: TokensManifest["tokens"][number]) => React.ReactNode;
+}) {
+  return (
+    <div data-slot="type-table" className="flex flex-col gap-2">
+      <h3 className="text-sm font-medium">{title}</h3>
+      <ul className="flex flex-col divide-y divide-border border-y border-border">
+        {rows.map((t) => (
+          <li key={t.name} className="grid grid-cols-1 gap-2 py-3 md:grid-cols-[10rem_minmax(0,1fr)] md:items-baseline">
+            <span className="flex flex-col font-mono text-xs text-muted-foreground">
+              <span className="font-medium text-canvas-foreground">{shortName(t, prefix)}</span>
+              <span className="truncate" title={t.values.default}>
+                {t.values.default}
+              </span>
+            </span>
+            <span className="min-w-0 truncate">{render(t)}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/registry/usage.tsx

@@ -0,0 +1,72 @@
+import Link from "next/link";
+import type { ReactNode } from "react";
+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, when not, and what to use instead, under its status.
+ * Written by people as JSDoc (`@use`, `@avoid`, `@instead`, `@status`); a
+ * component without them says so, rather than leaving a gap.
+ */
+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 rows: [string, ReactNode][] = [];
+  if (usage?.use) rows.push(["Use it for", inline(usage.use)]);
+  if (usage?.avoid) rows.push(["Not for", inline(usage.avoid)]);
+  if (usage?.instead?.length) {
+    rows.push([
+      "Instead",
+      usage.instead.map((name, i) => {
+        const c = known.get(name);
+        return (
+          <span key={name}>
+            {i > 0 && ", "}
+            {c ? (
+              <Link href={`${basePath}/components/${slugOf(c)}`} className="underline underline-offset-2">
+                {name}
+              </Link>
+            ) : (
+              name
+            )}
+          </span>
+        );
+      }),
+    ]);
+  }
+
+  return (
+    <div data-slot="usage" className="flex flex-col gap-4">
+      <p className="flex flex-wrap items-center gap-2 text-sm">
+        <StatusBadge status={entry.status} />
+        {entry.statusNote && <span className="text-muted-foreground">{inline(entry.statusNote)}</span>}
+      </p>
+      {rows.length ? (
+        <dl data-slot="usage-list" className="grid gap-x-6 gap-y-3 text-sm sm:grid-cols-[8rem_1fr]">
+          {rows.map(([term, detail]) => (
+            <div key={term} className="contents">
+              <dt className="font-medium">{term}</dt>
+              <dd className="text-muted-foreground">{detail}</dd>
+            </div>
+          ))}
+        </dl>
+      ) : (
+        <p className="text-sm text-muted-foreground">
+          No usage guidance yet. Add <code className="font-mono text-xs">@use</code>, <code className="font-mono text-xs">@avoid</code> and{" "}
+          <code className="font-mono text-xs">@instead</code> to its JSDoc.
+        </p>
+      )}
+    </div>
+  );
+}