basis-design 0.1.0 → 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

@@ -0,0 +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.

package/template/components/Field.module.css

@@ -23,9 +23,19 @@
 }
 
 .error {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-1);
   color: var(--color-danger);
 }
 
+.errorIcon {
+  flex: none;
+  width: 1.15em;
+  height: 1.15em;
+  margin-top: 0.1em;
+}
+
 .input {
   width: 100%;
   min-width: 0;

package/template/components/Field.tsx

@@ -31,6 +31,12 @@ export function Field({ label, hint, error, children }: FieldProps) {
       )}
       {error && (
         <span id={errorId} className={styles.error}>
+          {/* An icon as well as the colour, so the error does not rely on colour alone. */}
+          <svg className={styles.errorIcon} viewBox="0 0 16 16" aria-hidden>
+            <circle cx="8" cy="8" r="6.25" fill="none" stroke="currentColor" strokeWidth="1.5" />
+            <path d="M8 4.75v3.75" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+            <circle cx="8" cy="11.1" r="0.9" fill="currentColor" />
+          </svg>
           {error}
         </span>
       )}

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

@@ -0,0 +1,123 @@
+{
+  "components/Button.module.css": [
+    "2d8464bdd6324a9283902a51948359659223a1d14a14699ec05db3c48a1e6f5e",
+    "e1089f131e089edbea8c96cfd932e999b65e5987e7aa46ffa6ec1771bcc58913"
+  ],
+  "components/Button.specimen.tsx": [
+    "78be211c4ebe57be4d3e8fbda178aa1ea4a50874427f50918d5b519b30f1366d"
+  ],
+  "components/Controls.module.css": [
+    "11cd2a14dff9b941386b1e3f73904021501b5d11b92e2c2a5c7db740ccdebf78",
+    "6180d0705587ce7c9d721367b3a93968be63620470ca8053842cc9b97416c17f"
+  ],
+  "components/Controls.specimen.tsx": [
+    "44d057760788eafde4648ff245bc88757148aea950d784679a9013929b2fd3f6"
+  ],
+  "components/Controls.tsx": [
+    "bf2dcb69e0d11f2ff9c79be769689c1d2be4425824ecc2aafdbb9d4e916cc7a2"
+  ],
+  "components/Display.module.css": [
+    "5911e1d5ca62edb6baaca2b887a92f7f75e3f71c59d333bc4bffc35d5581481e"
+  ],
+  "components/Display.specimen.tsx": [
+    "4a00e90b3e9e18031132c36b3e9e2f2e338abe59901f99b3418cce9122de72a2",
+    "f833c9458080cf9cb05aca5f61b1e314ed2069466f5567f3a36add6c5f33cb53"
+  ],
+  "components/Display.tsx": [
+    "88ad53b91e4faccf1c85d8e60f7f8c5a98cca4b2061ac583ee3a87796ac92661",
+    "f676585a048fea80de64e2be1cd2032d63547d6891011deec9cf3540763a039f"
+  ],
+  "components/Field.module.css": [
+    "8a02df76c308cbe1c731cd5cfca4c2c7d5f1ae2492c4266d11a60c24143281d9"
+  ],
+  "components/Field.tsx": [
+    "170d7e50605f5bc342fe03a0f6fcb72e24e7ad4481ddd7b73402fbb62272bb2d",
+    "9c278ae0f37efe55fd73b03204c0e3f6997d6c3c7873856798efc8ce95222ef0",
+    "ebb3f7ed65f00184d71a0697871181d8f2fb8d723dc28d94171b11e0cc44ebe7"
+  ],
+  "components/Overlay.module.css": [
+    "15f18fe8494bb008e85f06a8ebd2d491826e565ddb16a6a01b270e115977838b",
+    "f1bae693a614018f19d7f9cdb2f5d9b950a711016d2639ba0ea03acbe05ef797"
+  ],
+  "components/Tabs.module.css": [
+    "f794ecc0a17aea3390c72851f56a005a16b9a5c532809c57b0bd597f49faf7cc"
+  ],
+  "components/Tabs.specimen.tsx": [
+    "0c871b0745e9206a6301025b0fc2e49b15b6798c8fe34499a04fe212cb0ca8d3"
+  ],
+  "components/Tabs.tsx": [
+    "7a3178fd1fce2697329049a23581ed40a018777b9a8d121e92b6cf0bbb20beb1"
+  ],
+  "components/index.ts": [
+    "c8e48a994b9283dbfba7cf83d15f8ccb327ea4b09f1138f84153dcd206262626"
+  ],
+  "components/specimen.ts": [
+    "03370daf9bba1c4329d3dac7b76199970cab9c11a6ea2d23e1a484ead80d36d6",
+    "1f826f8c8f183e311fd20cca0e5e3c138ac2775c4e156862600c24e9dad7cf7d",
+    "2f4b9f188c981a690c271b100cf4174339637d4bd8f27b3daa200ac089b6256e",
+    "e04c6fc2a3e85090b7672d229d95ca8c5a42009f6397332230d324357b993169"
+  ],
+  "patterns/AppShell.module.css": [
+    "8327a6a221d3822f31e2413ea2d83978e89dc5ed093ab348efbc3fb74659a76b"
+  ],
+  "patterns/AppShell.specimen.tsx": [
+    "bbf6e40b1eb59ab81faec7d298daedf964721210acd319518370d654828e61b5"
+  ],
+  "patterns/DataTable.specimen.tsx": [
+    "07ddde9be4ff6b5fbe080145b59cb98719ebf17665efea5168ce653e45e52328",
+    "fef38e643e27c8515167d03b2f9578c4f490dc3c472f39db5ec8a3f8de5b0405"
+  ],
+  "patterns/DataTable.tsx": [
+    "bee57f1686bbbfeb08670475c687c18f8e33b19b09b804d2e3b857c9575f4227"
+  ],
+  "patterns/EmptyState.tsx": [
+    "7b9f3ad1ad9467b537154426823da185062d99f9b5481329ec87c8e21edefe19"
+  ],
+  "patterns/FormSection.specimen.tsx": [
+    "947b384b3ff7b0874fd7210b2db767623ba980142e33f6daf98261b5c725b363"
+  ],
+  "patterns/Navbar.module.css": [
+    "7a4c07e69235c8b0667424a3794a7ca927fb6c1a852b174fed9c445d3ce31b05",
+    "a3d8cdfd7817bee2deca487115863b8e9a904159ccf1a62a4252269f9a00974b"
+  ],
+  "patterns/Navbar.specimen.tsx": [
+    "c5dca4b21abd2fb9e6a3dc6c881dd946691eb4b193030355897cf4837c1fbd33",
+    "e0db053892604c3e48fe688481f2d7659179aa37f15f7a1733c65eaf58d2037b",
+    "ff2ef3ab16212f5d49952a425d4a55b5c1a23bbf0273032fcbf309ef4cc42425"
+  ],
+  "patterns/Navbar.tsx": [
+    "629e3a72fac39fbddcef20ee2761b20637ac6ecf931e7c40ec497fb5717c76b5",
+    "a519ebc213b050332897d49ca3d3f218e0f81657b45dfeabf12ba4851e27ea9d",
+    "c30d7c50eca1d5f5403bfe279f82c0fc0892c3ec7c117eba529a2c4d67011e85"
+  ],
+  "patterns/PageHeader.specimen.tsx": [
+    "ed1adf47bc0873aa2888e3f344b4e6d8949cdcbe4d5932a05c014e6552872107"
+  ],
+  "patterns/SidebarNav.module.css": [
+    "c5c61ad5ef76d19fdafdd62c3e7d2762c8f4e65a659d79630679cc77143c6fcf"
+  ],
+  "patterns/SidebarNav.specimen.tsx": [
+    "5ebc259eaec7004cd0836c3f108e6f26e4c209f1722a5102971edd3048bffcb4"
+  ],
+  "patterns/SidebarNav.tsx": [
+    "e11bb61819ea9ff36d963eec2b92f1d7cf2b4e2b14e74edc7a9ab001338a4fc8"
+  ],
+  "patterns/StatCard.module.css": [
+    "30c76bf5527125a41d5237b01aba8d7f3575df6732edc1b0636a1086e4304c45"
+  ],
+  "patterns/StatCard.specimen.tsx": [
+    "1841a58bce6c35b23f8715bb00c04b641381c9c7d829accb9a2900d49bf9709d"
+  ],
+  "patterns/StatCard.tsx": [
+    "55a9c20673d8a8a191ac2ee70fa27a0ec9ac65f4ea1cf8af5a7be654209e31c8"
+  ],
+  "patterns/icons.tsx": [
+    "5a7c631c8ad5195f82b852814c850af74c3807e09aff1dafec465ce92adc364c"
+  ],
+  "patterns/index.ts": [
+    "06b2fe73440972fbd91e9c64d8a3f4a5cf37e1f2d749cc6a821ce59f9b9d8c02"
+  ],
+  "patterns/specimen-data.ts": [
+    "4e355b5dc7eeaed260e6092f88cf85194a9377bce6accce5e9db6e97e22761e3"
+  ]
+}

package/template/patterns/Navbar.module.css

@@ -87,7 +87,8 @@
 .link:focus-visible,
 .link[data-force="focus"],
 .menuLink:focus-visible,
-.menuButton:focus-visible {
+.menuButton:focus-visible,
+.searchButton:focus-visible {
   outline: var(--focus-ring-width) solid var(--color-focus-ring);
   outline-offset: calc(var(--focus-ring-width) * -1);
 }
@@ -155,7 +156,8 @@
   display: inline-flex;
 }
 
-.menuButton {
+.menuButton,
+.searchButton {
   display: none;
   flex: none;
   place-items: center;
@@ -170,7 +172,8 @@
   transition: background-color var(--duration-fast) var(--ease-standard);
 }
 
-.menuButton:hover {
+.menuButton:hover,
+.searchButton:hover {
   background: var(--color-secondary);
 }
 
@@ -187,32 +190,55 @@
   gap: 2px;
 }
 
-/* Narrow layout, forced by compact or when the bar is under 960px wide: the links, the search and the actions
-   move into the menu behind the menu button. */
-.navbar[data-compact] .menuButton {
-  display: grid;
+/* Three layouts by the bar's own width. From 1024px everything sits in the bar. From 800px the search becomes a
+   button that opens it below the bar. Under 800px, or with compact, the links, the search and the actions move
+   into the menu behind the menu button. */
+@container (width < 1024px) {
+  .bar .search {
+    display: none;
+  }
+
+  .searchButton,
+  .menu {
+    display: grid;
+  }
+
+  .menu :is(.actions, .menuLinks) {
+    display: none;
+  }
 }
 
-.navbar[data-compact] .menu {
+.navbar[data-compact] .menuButton,
+.navbar[data-compact] .menu,
+.navbar[data-compact] .menu .menuLinks {
   display: grid;
 }
 
-.navbar[data-compact] .bar :is(.links, .search, .actions) {
+.navbar[data-compact] .menu .actions {
+  display: flex;
+}
+
+.navbar[data-compact] .bar :is(.links, .search, .actions, .searchButton) {
   display: none;
 }
 
-@container (width < 960px) {
+@container (width < 800px) {
   .bar {
     gap: var(--space-3);
     padding-inline: var(--space-3);
   }
 
   .menuButton,
-  .menu {
+  .menu,
+  .menu .menuLinks {
     display: grid;
   }
 
-  .bar :is(.links, .search, .actions) {
+  .menu .actions {
+    display: flex;
+  }
+
+  .bar :is(.links, .search, .actions, .searchButton) {
     display: none;
   }
 }

package/template/patterns/Navbar.specimen.tsx

@@ -101,7 +101,7 @@ export default defineSpecimen({
     },
     {
       kind: "block",
-      title: "Narrow · under 960px the links and search move behind the menu",
+      title: "Narrow · under 800px the links and search move behind the menu",
       render: () => (
         <div style={{ ...frame, maxWidth: 380 }}>
           <Navbar

package/template/patterns/Navbar.tsx

@@ -1,4 +1,4 @@
-import { useId, useState, type ReactNode } from "react";
+import { useEffect, useId, useRef, useState, type ReactNode } from "react";
 import { Avatar } from "../components/index.ts";
 import { Icon } from "./icons.tsx";
 import styles from "./Navbar.module.css";
@@ -25,7 +25,7 @@ export interface NavbarProps {
   elevated?: boolean;
   /**
    * Forces the narrow layout, where links, search and actions move behind a menu button. Without it the bar switches by
-   * itself when it is narrower than 960px.
+   * itself: under 1024px the search becomes a button, under 800px everything moves behind the menu button.
    */
   compact?: boolean;
   /** Controls the menu from outside; otherwise the bar keeps its own open state. */
@@ -51,6 +51,18 @@ export function Navbar({
   const [ownOpen, setOwnOpen] = useState(false);
   const open = menuOpen ?? ownOpen;
   const toggle = onMenuToggle ?? (() => setOwnOpen((value) => !value));
+  const menu = useRef<HTMLDivElement>(null);
+  // The search button opens the panel below the bar; the field there gets focus, so typing can start at once.
+  const focusSearch = useRef(false);
+  const openSearch = () => {
+    focusSearch.current = !open;
+    toggle();
+  };
+  useEffect(() => {
+    if (!open || !focusSearch.current) return;
+    focusSearch.current = false;
+    menu.current?.querySelector("input")?.focus();
+  }, [open]);
 
   const search = searchPlaceholder && (
     <label className={styles.search}>
@@ -102,6 +114,18 @@ export function Navbar({
         </nav>
         <div className={styles.end}>
           {search}
+          {searchPlaceholder && (
+            <button
+              type="button"
+              className={styles.searchButton}
+              aria-expanded={open}
+              aria-controls={menuId}
+              aria-label="Search"
+              onClick={openSearch}
+            >
+              <Icon name="search" size={18} />
+            </button>
+          )}
           {actions && <div className={styles.actions}>{actions}</div>}
           {user && (
             <span className={styles.user} title={user.name}>
@@ -111,7 +135,7 @@ export function Navbar({
         </div>
       </div>
       {open && (
-        <div id={menuId} className={styles.menu}>
+        <div id={menuId} ref={menu} className={styles.menu}>
           {search}
           {actions && <div className={styles.actions}>{actions}</div>}
           <nav className={styles.menuLinks} aria-label="Main">