basis-design 0.1.1 → 0.2.0

package/src/shell/VerifyKit.tsx

@@ -0,0 +1,133 @@
+import { useState } from "react";
+import type { ClientMessage, VerifyKitResult } from "../../shared/protocol.ts";
+import { BrowseButton } from "./FolderField.tsx";
+import { readPref, writePref } from "./prefs.ts";
+import styles from "./Shell.module.css";
+
+export interface VerifyKitProps {
+  workspace: string;
+  /** The product repo the project designs for: where the kit belongs, unless the user chose a folder before. */
+  repo: string | undefined;
+  progress: { step: string; done?: number; total?: number } | null;
+  result: VerifyKitResult | null;
+  send: (message: ClientMessage) => void;
+}
+
+/** The product folder the kit was last written to, per project. */
+const targetPref = (workspace: string) => `verify-target:${workspace}`;
+
+function plural(count: number, one: string, many = `${one}s`): string {
+  return `${count} ${count === 1 ? one : many}`;
+}
+
+/**
+ * The verification kit tab of the Export dialog: builds the kit (a runnable copy of the design, screenshots of
+ * every view's screens and the scripts that check an implementation against them) as a zip or into the product's
+ * folder.
+ */
+export function VerifyKit({ workspace, repo, progress, result: latest, send }: VerifyKitProps) {
+  const [target, setTarget] = useState(() => readPref(targetPref(workspace)) ?? repo ?? "");
+  const [browseError, setBrowseError] = useState<string | null>(null);
+  // Only show results of kits built while this dialog is open.
+  const [stale] = useState(latest);
+  const result = latest === stale ? null : latest;
+  const busy = progress !== null;
+
+  const build = (project?: string) => {
+    if (project !== undefined) writePref(targetPref(workspace), project);
+    send({ type: "verify-kit", project });
+  };
+
+  return (
+    <div className={styles.kit}>
+      <p className={styles.kitIntro}>
+        Proof that a feature was built as designed. The kit holds a runnable copy of the design, screenshots of every
+        view's screens at the widths the view asks for, and two scripts: one captures the implementation the same way,
+        the other compares the images pixel for pixel. Give it to the agent that builds the feature; the target is 0%
+        difference, and anything allowed to differ is a named exception.
+      </p>
+      <form
+        className={styles.kitWrite}
+        onSubmit={(event) => {
+          event.preventDefault();
+          build(target);
+        }}
+      >
+        <label htmlFor="verify-target">Write into the product's folder</label>
+        <div className={styles.kitWriteRow}>
+          <input
+            id="verify-target"
+            value={target}
+            onChange={(event) => setTarget(event.target.value)}
+            placeholder="Browse, or paste the folder's path"
+            spellCheck={false}
+          />
+          <BrowseButton
+            title="Choose the product's folder"
+            start={target}
+            onPick={setTarget}
+            onError={setBrowseError}
+          />
+          <button type="submit" className={styles.chromeButton} disabled={!target.trim() || busy}>
+            Write kit
+          </button>
+        </div>
+        <span className={styles.kitNote}>
+          The kit goes into <code>basis-verify/</code> there. Writing it again replaces what Basis generated and keeps
+          the project's targets, exceptions and captures.
+        </span>
+        {browseError && <p className={styles.kitError}>{browseError}</p>}
+      </form>
+      {progress && (
+        <p className={styles.kitNote} role="status">
+          {progress.step}
+          {progress.total ? ` ${progress.done ?? 0} of ${progress.total}` : ""}…
+        </p>
+      )}
+      {result && !result.ok && <p className={styles.kitError}>{result.error}</p>}
+      {result?.ok && <Summary result={result} />}
+    </div>
+  );
+}
+
+function Summary({ result }: { result: Extract<VerifyKitResult, { ok: true }> }) {
+  const { summary, dir } = result;
+  if (summary.views === 0) {
+    return (
+      <p className={styles.kitWarning}>
+        There are no views to capture. Ask the agent for a view of a screen in the product, then build the kit.
+      </p>
+    );
+  }
+  return (
+    <>
+      <p className={styles.kitSuccess}>
+        Captured {plural(summary.shots, "shot")} of {plural(summary.screens, "screen")} in{" "}
+        {plural(summary.views, "view")} with {summary.browser}.{" "}
+        {dir ? (
+          <>
+            Wrote the kit to <code>{dir}</code>.
+          </>
+        ) : (
+          <a href="/export/verification-kit.zip" download>
+            Download the .zip
+          </a>
+        )}
+      </p>
+      {summary.failed.length > 0 && (
+        <p className={styles.kitWarning}>
+          {plural(summary.failed.length, "shot")} of screens that failed to render: {summary.failed.join(", ")}.
+        </p>
+      )}
+      {summary.unstable.length > 0 && (
+        <p className={styles.kitWarning}>
+          {plural(summary.unstable.length, "shot")} came out differently on a second capture, so nothing can match them
+          exactly: {summary.unstable.join(", ")}. Look for clocks, random values or animations in those screens.
+        </p>
+      )}
+      {summary.problems.length > 0 && (
+        <p className={styles.kitWarning}>Specimens that could not be loaded: {summary.problems.join("; ")}.</p>
+      )}
+    </>
+  );
+}

package/template/CHANGES.md

@@ -1,25 +1,25 @@
-# Starter template changes
-
-What changed in Basis' starter components, patterns and views, by template version. Basis updates the files a
-workspace never changed by itself; the agent brings these changes into the ones it did change, keeping the
-design system's own look.
-
-## 1
-
-- Reduced motion in every component and pattern: under `@media (prefers-reduced-motion: reduce)` nothing slides,
-  zooms, shimmers or loops (presses do not shrink, cards do not lift, the indeterminate progress bar and the
-  skeleton stand still, tooltips, toasts and dialogs only fade, the tab indicator and underlines jump). Spinners
-  keep turning, since they are the only sign that work goes on. See the `@media (prefers-reduced-motion: reduce)`
-  block at the end of each stylesheet.
-- Field: the label is a `<label for>` above the control, then the hint, then the error, then the control. The hint
-  and the error are tied to the control with `aria-describedby`, the control gets `aria-invalid` from the Field's
-  error (through a React context, so TextInput, Textarea and Select need no extra props), and the error has an
-  icon as well as the danger colour.
-- Navbar responds to its own width, as a size container: from 1024px everything sits in the bar; from 800px the
-  search becomes a button that opens the field below the bar, with focus in it; under 800px the links, the search
-  and the actions move into a menu behind a menu button. `compact` still forces the narrow layout, and the menu
-  keeps its own open state unless `menuOpen` is given.
-- AppShell is a size container named `app-shell`; SidebarNav becomes its icon rail inside a narrow one (under
-  640px). The rail's grid column is pinned so its icons stay centred.
-- Small text that used `textSubtle` (SidebarNav section titles, StatCard hints) uses `textMuted`, since subtle is
-  held to 3:1 and small text needs 4.5:1.
+# Starter template changes
+
+What changed in Basis' starter components, patterns and views, by template version. Basis updates the files a
+workspace never changed by itself; the agent brings these changes into the ones it did change, keeping the
+design system's own look.
+
+## 1
+
+- Reduced motion in every component and pattern: under `@media (prefers-reduced-motion: reduce)` nothing slides,
+  zooms, shimmers or loops (presses do not shrink, cards do not lift, the indeterminate progress bar and the
+  skeleton stand still, tooltips, toasts and dialogs only fade, the tab indicator and underlines jump). Spinners
+  keep turning, since they are the only sign that work goes on. See the `@media (prefers-reduced-motion: reduce)`
+  block at the end of each stylesheet.
+- Field: the label is a `<label for>` above the control, then the hint, then the error, then the control. The hint
+  and the error are tied to the control with `aria-describedby`, the control gets `aria-invalid` from the Field's
+  error (through a React context, so TextInput, Textarea and Select need no extra props), and the error has an
+  icon as well as the danger colour.
+- Navbar responds to its own width, as a size container: from 1024px everything sits in the bar; from 800px the
+  search becomes a button that opens the field below the bar, with focus in it; under 800px the links, the search
+  and the actions move into a menu behind a menu button. `compact` still forces the narrow layout, and the menu
+  keeps its own open state unless `menuOpen` is given.
+- AppShell is a size container named `app-shell`; SidebarNav becomes its icon rail inside a narrow one (under
+  640px). The rail's grid column is pinned so its icons stay centred.
+- Small text that used `textSubtle` (SidebarNav section titles, StatCard hints) uses `textMuted`, since subtle is
+  held to 3:1 and small text needs 4.5:1.

package/template/components/specimen.ts

@@ -57,7 +57,30 @@ export type SpecimenBlock =
    * Whole screens of one flow, for views: the gallery shows one at a time, full width, with a strip to jump
    * between them. The first screen shows first; each moves on with `go(id)`.
    */
-  | { kind: "flow"; title?: string; screens: { id: string; label: string; render: ComponentType<ScreenProps> }[] };
+  | {
+      kind: "flow";
+      title?: string;
+      screens: { id: string; label: string; render: ComponentType<ScreenProps> }[];
+      /** How the verification kit captures each screen; Basis' defaults when left out (see Capture). */
+      capture?: Capture;
+    };
+
+/**
+ * The screenshots a view's screens are checked against during development. Every screen is captured at every
+ * width (and theme), and the implementation must match them pixel for pixel, so a screen must render the same
+ * every time: no clock, no randomness, no animation that does not settle.
+ */
+export interface Capture {
+  /** Viewport widths in CSS pixels; Basis' default is [375, 768, 1440]. */
+  widths?: number[];
+  /**
+   * "full" (the default) captures the whole page, which must then also be as tall as the design. A number
+   * captures exactly that viewport height, for screens such as app shells that scroll inside.
+   */
+  height?: "full" | number;
+  /** Themes to capture; Basis' default is ["light"]. */
+  themes?: ("light" | "dark")[];
+}
 
 export interface Specimen {
   /** Anchor and sidebar id; defaults to the title in kebab-case. */

package/template/history.json

@@ -54,6 +54,7 @@
   "components/specimen.ts": [
     "03370daf9bba1c4329d3dac7b76199970cab9c11a6ea2d23e1a484ead80d36d6",
     "1f826f8c8f183e311fd20cca0e5e3c138ac2775c4e156862600c24e9dad7cf7d",
+    "2f4b9f188c981a690c271b100cf4174339637d4bd8f27b3daa200ac089b6256e",
     "e04c6fc2a3e85090b7672d229d95ca8c5a42009f6397332230d324357b993169"
   ],
   "patterns/AppShell.module.css": [