@designtools/blocks 0.0.0-stage → 0.2.0

package/registry/swatches.tsx

@@ -0,0 +1,225 @@
+"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" tabIndex={0} role="region" aria-label="Colours">
+      <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" && "w-fit rounded-sm bg-destructive-subdued px-1 font-medium text-destructive-subdued-foreground")}>
+            {ratio.toFixed(2)}:1 · {grade}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Each colour on each background, per mode: a label is measured on its own fill, and this is
+ * everything else, red text on the page, a brand fill on a dark section. Backgrounds are the
+ * canvas, surface and overlay and every named `--surface-<name>`; colours are each semantic fill
+ * and muted text. T: fine as text (4.5:1); S: fine as a shape only (3:1); none: neither.
+ * Measured on what the browser paints, inside each mode's `data-theme`.
+ */
+export function PageContrast({ tokens, modes = ["light", "dark"] }: { tokens: TokensManifest; modes?: Mode[] }) {
+  const names = new Set(semanticColours(tokens).map((c) => c.name));
+  const colours = [...names].filter((n) => names.has(`${n}-subdued`)).concat(names.has("--muted") ? ["--muted-foreground"] : []);
+  const grounds = ["--canvas", "--surface", "--overlay", ...[...names].filter((n) => n.startsWith("--surface-") && !n.endsWith("-foreground") && n !== "--surface-foreground")];
+  return (
+    <div data-slot="page-contrast" className="flex flex-col gap-6">
+      {modes.map((mode) => (
+        <PageGrid key={mode} mode={mode} colours={colours} grounds={grounds} />
+      ))}
+    </div>
+  );
+}
+
+function PageGrid({ mode, colours, grounds }: { mode: Mode; colours: string[]; grounds: string[] }) {
+  const probe = useRef<HTMLDivElement>(null);
+  const [ratios, setRatios] = useState<Record<string, number | null>>({});
+  useEffect(() => {
+    const node = probe.current;
+    if (!node) return;
+    const paint = (v: string) => {
+      node.style.color = `var(${v})`;
+      return getComputedStyle(node).color;
+    };
+    const painted = Object.fromEntries([...colours, ...grounds].map((v) => [v, paint(v)]));
+    const out: Record<string, number | null> = {};
+    for (const c of colours) for (const g of grounds) out[`${c}|${g}`] = contrastRatio(painted[c], painted[g]);
+    setRatios(out);
+  }, [colours, grounds]);
+  return (
+    <div className="overflow-x-auto" tabIndex={0} role="region" aria-label={`Colours on each background, ${mode} mode`}>
+      <div ref={probe} data-theme={mode} hidden />
+      <table className="w-full min-w-[32rem] border-collapse text-left text-sm">
+        <caption className="pb-2 text-left text-sm font-medium capitalize">{mode}</caption>
+        <thead>
+          <tr className="border-b border-border text-xs text-muted-foreground">
+            <th scope="col" className="py-2 pr-4 font-medium">Colour</th>
+            {grounds.map((g) => (
+              <th key={g} scope="col" className="py-2 pr-4 font-mono font-medium">{g.slice(2)}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {colours.map((c) => (
+            <tr key={c} className="border-b border-border">
+              <th scope="row" className="py-2 pr-4 font-mono text-xs font-medium">{c.slice(2)}</th>
+              {grounds.map((g) => {
+                const r = ratios[`${c}|${g}`];
+                const mark = r == null ? "" : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
+                return (
+                  <td key={g} className="py-2 pr-4">
+                    <div className="flex items-center gap-2">
+                      {/* only the sample takes the mode; the number is read on the page */}
+                      <span data-theme={mode} className="flex h-9 w-12 items-center justify-center rounded-md border border-(--border) text-base font-bold" style={{ background: `var(${g})`, color: `var(${c})` }} aria-hidden>
+                        Aa
+                      </span>
+                      {r != null && (
+                        <span className={cx("font-mono text-xs", mark === "none" && "rounded-sm bg-destructive-subdued px-1 text-destructive-subdued-foreground")}>
+                          {r.toFixed(1)} {mark}
+                        </span>
+                      )}
+                    </div>
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </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-xs 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,73 @@
+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";
+import { target } from "./lib/cx";
+
+/**
+ * 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={`${target} inline-flex items-center 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>
+  );
+}

package/registry/variant-matrix.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { coerce, componentFor, Missing } from "./lib/lookup";
+import type { ComponentEntry, VariantAxis } from "./lib/manifest-types";
+
+/**
+ * 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 Component = componentFor(entry);
+  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>) => (
+    <Component {...props} {...coerce(extra)}>
+      {content}
+    </Component>
+  );
+  const [rows, cols, ...rest] = axes;
+
+  return (
+    <div data-slot="variant-matrix" className="flex flex-col gap-8">
+      {cols ? (
+        <div className="overflow-x-auto" tabIndex={0} role="region" aria-label="Variants">
+          <table className="border-collapse text-sm">
+            <caption className="sr-only">
+              {entry.name}: {rows.name} by {cols.name}
+            </caption>
+            <thead>
+              <tr>
+                <th scope="col" className="p-2 text-left text-xs font-normal text-muted-foreground">
+                  <span className="font-mono">{rows.name}</span> \ <span className="font-mono">{cols.name}</span>
+                </th>
+                {cols.options.map((c) => (
+                  <th key={c.name} scope="col" className="p-2 text-left font-mono text-xs font-medium">
+                    {label(cols, c.name)}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {rows.options.map((r) => (
+                <tr key={r.name}>
+                  <th scope="row" className="p-2 text-left font-mono text-xs font-medium">
+                    {label(rows, r.name)}
+                  </th>
+                  {cols.options.map((c) => (
+                    <td key={c.name} data-slot="variant-cell" className="p-2 align-middle">
+                      {render({ [rows.name]: r.name, [cols.name]: c.name })}
+                    </td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      ) : (
+        <AxisRow axis={rows} render={render} />
+      )}
+      {rest.map((axis) => (
+        <AxisRow key={axis.name} axis={axis} render={render} />
+      ))}
+    </div>
+  );
+}
+
+function AxisRow({ axis, render }: { axis: VariantAxis; render: (extra: Record<string, string>) => ReactNode }) {
+  return (
+    <div data-slot="variant-axis" className="flex flex-col gap-2">
+      <p className="font-mono text-xs text-muted-foreground">{axis.name}</p>
+      <div className="flex flex-wrap items-center gap-4">
+        {axis.options.map((o) => (
+          <figure key={o.name} className="flex flex-col items-start gap-1.5">
+            {render({ [axis.name]: o.name })}
+            <figcaption className="font-mono text-xs text-muted-foreground" title={o.description}>
+              {label(axis, o.name)}
+            </figcaption>
+          </figure>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function label(axis: VariantAxis, option: string): string {
+  return axis.default === option ? `${option} (default)` : option;
+}

package/registry/voice-terms.tsx

@@ -0,0 +1,45 @@
+import type { TermEntry } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+
+/** The words to use, beside the ones not to: product terms first, then the system's names that have wrong forms. */
+export function VoiceTerms({ terms }: { terms: TermEntry[] }) {
+  const shown = [...terms.filter((t) => t.kind === "product"), ...terms.filter((t) => t.kind !== "product" && t.wrong?.length)];
+  if (shown.length === 0) return <p className="text-sm text-muted-foreground">No terms yet. Add them to the taxonomy file.</p>;
+  return (
+    <div data-slot="voice-terms" className="overflow-x-auto" tabIndex={0} role="region" aria-label="Terms">
+      <table className="w-full min-w-[28rem] 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">
+              Say
+            </th>
+            <th scope="col" className="py-2 pr-4 font-medium">
+              Not
+            </th>
+            <th scope="col" className="py-2 font-medium">
+              Why
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          {shown.map((t) => (
+            <tr key={`${t.kind}:${t.name}`} className="border-b border-border align-top">
+              <th scope="row" className="py-2 pr-4 font-medium">
+                {t.name}
+              </th>
+              <td className="py-2 pr-4 text-muted-foreground">
+                {(t.wrong ?? []).map((w, i) => (
+                  <span key={w}>
+                    {i > 0 && ", "}
+                    <s>{w}</s>
+                  </span>
+                ))}
+              </td>
+              <td className="py-2 text-muted-foreground">{t.note ? inline(t.note) : t.kind === "product" ? "" : `The ${t.kind}'s name in the code.`}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}