@designtools/docs 0.1.0 → 0.2.0

package/src/variant-matrix.tsx

@@ -1,5 +1,6 @@
 "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";
@@ -36,9 +37,11 @@ export function VariantMatrix({
 
   const content = children ?? entry.name;
   const render = (extra: Record<string, string>) => (
-    <Component {...props} {...coerce(extra)}>
-      {content}
-    </Component>
+    <Live>
+      <Component {...props} {...coerce(extra)}>
+        {content}
+      </Component>
+    </Live>
   );
   const [rows, cols, ...rest] = axes;
   const toggle = (
@@ -51,26 +54,28 @@ export function VariantMatrix({
   );
 
   return (
-    <div data-slot="variant-matrix" className="flex flex-col gap-6">
-      {cols ? (
-        <Frame>
-          <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)" />
-              {rows.name} × {cols.name}
-            </span>
-            {toggle}
-          </Toolbar>
-          <div data-docs-stage="" data-theme={theme} className="overflow-x-auto bg-canvas text-canvas-foreground" tabIndex={0} role="region" aria-label="Variants">
+    <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 className="border-b border-border">
+                <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 py-3 text-center font-mono text-xs font-medium text-muted-foreground">
+                    <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>
                   ))}
@@ -78,12 +83,12 @@ export function VariantMatrix({
               </thead>
               <tbody>
                 {rows.options.map((r) => (
-                  <tr key={r.name} className="border-b border-border last:border-b-0">
-                    <th scope="row" title={r.description} className="border-r border-border px-4 py-5 text-left font-mono text-xs font-medium whitespace-nowrap text-muted-foreground">
+                  <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-5 text-center align-middle">
+                      <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>
                     ))}
@@ -92,15 +97,25 @@ export function VariantMatrix({
               </tbody>
             </table>
           </div>
-        </Frame>
-      ) : (
-        <AxisRow axis={rows} render={render} theme={theme} toggle={toggle} />
-      )}
-      {rest.map((axis) => (
-        <AxisRow key={axis.name} axis={axis} render={render} theme={theme} toggle={toggle} />
-      ))}
-      <States render={render} theme={theme} toggle={toggle} canDisable={"disabled" in entry.props} />
-    </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>
   );
 }
 
@@ -109,17 +124,7 @@ export function VariantMatrix({
  * 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,
-  theme,
-  toggle,
-  canDisable,
-}: {
-  render: (extra: Record<string, string>) => ReactNode;
-  theme?: "light" | "dark";
-  toggle: ReactNode;
-  canDisable: boolean;
-}) {
+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" },
@@ -129,51 +134,29 @@ function States({
     ...(canDisable ? [{ name: "disabled", extra: { disabled: "true" } }] : []),
   ];
   return (
-    <Frame data-slot="variant-states">
-      <Toolbar>
-        <span className="pl-2 font-mono text-xs text-muted-foreground">state</span>
-        {toggle}
-      </Toolbar>
-      <div data-docs-stage="" data-theme={theme} className="flex flex-wrap items-end justify-center gap-x-10 gap-y-6 bg-canvas px-6 py-8 text-canvas-foreground">
-        {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>
-        ))}
-      </div>
-    </Frame>
+    <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,
-  theme,
-  toggle,
-}: {
-  axis: VariantAxis;
-  render: (extra: Record<string, string>) => ReactNode;
-  theme?: "light" | "dark";
-  toggle: ReactNode;
-}) {
+function AxisRow({ axis, render }: { axis: VariantAxis; render: (extra: Record<string, string>) => ReactNode }) {
   return (
-    <Frame data-slot="variant-axis">
-      <Toolbar>
-        <span className="pl-2 font-mono text-xs text-muted-foreground">{axis.name}</span>
-        {toggle}
-      </Toolbar>
-      <div data-docs-stage="" data-theme={theme} className="flex flex-wrap items-end justify-center gap-x-10 gap-y-6 bg-canvas px-6 py-8 text-canvas-foreground">
-        {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>
-        ))}
-      </div>
-    </Frame>
+    <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>
   );
 }
 

package/src/voice-terms.tsx

@@ -1,5 +1,6 @@
 import type { TermEntry } from "./lib/manifest-types";
-import { inline } from "./lib/text";
+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[] }) {
@@ -7,40 +8,30 @@ export function VoiceTerms({ terms }: { terms: TermEntry[] }) {
   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 (
-    <div data-slot="voice-terms" className="flex flex-col gap-12">
-      {product.length > 0 && <Group title="In the product" terms={product} />}
-      {system.length > 0 && <Group title="In the system" terms={system} />}
-    </div>
+    <>
+      {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 Group({ title, terms }: { title: string; terms: TermEntry[] }) {
+function Terms({ terms }: { terms: TermEntry[] }) {
   return (
-    <section className="flex flex-col gap-2">
-      <h3 className="text-xs font-medium tracking-wide text-muted-foreground uppercase">{title}</h3>
-      <dl className="grid gap-x-12 sm:grid-cols-2">
+    <div data-slot="voice-terms">
+      <TermHead />
+      <dl>
         {terms.map((t) => (
-          <div key={`${t.kind}:${t.name}`} data-slot="term" className="flex flex-col gap-1.5 border-t border-border py-5">
-            <dt className="text-3xl tracking-tight">
-              {t.name}
-              <span className="sr-only">, say this</span>
-            </dt>
-            {(t.wrong ?? []).length > 0 && (
-              <dd className="flex flex-wrap gap-x-3 text-base text-muted-foreground">
-                <span className="sr-only">not </span>
-                {(t.wrong ?? []).map((w) => (
-                  <s key={w} className="decoration-destructive decoration-2">
-                    {w}
-                  </s>
-                ))}
-              </dd>
-            )}
-            {(t.note || t.kind !== "product") && (
-              <dd className="text-sm text-muted-foreground">{t.note ? inline(t.note) : `The ${t.kind}'s name in the code.`}</dd>
-            )}
-          </div>
+          <TermRow key={`${t.kind}:${t.name}`} term={t} />
         ))}
       </dl>
-    </section>
+    </div>
   );
 }

package/src/workbench.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { Live } from "./lib/live";
 import { Tabs } from "@base-ui/react/tabs";
 import { Toggle } from "@base-ui/react/toggle";
 import { ToggleGroup } from "@base-ui/react/toggle-group";
@@ -267,9 +268,11 @@ export function Workbench({
   const dotted = view.bg === "canvas";
 
   const node = (
-    <Component {...base} {...logged} {...chosen}>
-      {content ?? (text || undefined)}
-    </Component>
+    <Live>
+      <Component {...base} {...logged} {...chosen}>
+        {content ?? (text || undefined)}
+      </Component>
+    </Live>
   );
   const scope = [
     entry.name,