@cychien/ezdesign 0.0.0-stage → 0.9.1

package/dist/vite.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Structural subset of Vite's Plugin type. Deliberately not imported from
+ * 'vite' so the emitted d.ts never pins a Vite major — the object is
+ * assignable to Plugin in every Vite version that has these hooks (5+).
+ */
+export interface EzdesignSourcePlugin {
+    name: string;
+    apply: 'serve';
+    enforce: 'pre';
+    configResolved(config: {
+        root: string;
+    }): void;
+    transform(code: string, id: string): {
+        code: string;
+        map: string;
+    } | null;
+}
+/**
+ * Dev-only JSX transform: stamps `data-ez-source="relative/file.tsx:line"` on
+ * host elements (lowercase tags) so overlay annotations resolve to exact
+ * source locations. `apply: 'serve'` — never part of a production build.
+ *
+ * Relative to the *project*, not to Vite's root: the path is for the agent to
+ * open, and the agent stands where the CLI was run - see `projectRoot`.
+ */
+export declare function ezdesignSource(): EzdesignSourcePlugin;

package/dist/vite.mjs

@@ -0,0 +1,105 @@
+// src/vite.ts
+import { relative } from "node:path";
+import { parse as parse2 } from "@babel/parser";
+import MagicString from "magic-string";
+
+// src/constants.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+var APP_NAME = "ezdesign";
+var ENV_PREFIX = APP_NAME.toUpperCase();
+var DATA_DIR = process.env[`${ENV_PREFIX}_DATA_DIR`] ?? join(homedir(), `.${APP_NAME}`);
+var SESSIONS_DIR = join(DATA_DIR, "sessions");
+var LEGACY_SESSIONS_DIR = join(DATA_DIR, "sessions-legacy");
+var REGISTRY_FILE = join(DATA_DIR, "daemon.json");
+var DAEMON_LOG = join(DATA_DIR, "daemon.log");
+var VERSIONS_DIR = join(DATA_DIR, "versions");
+var UPDATE_CHECK_FILE = join(DATA_DIR, "update-check.json");
+var LIBRARY_HOME_ENV = `${ENV_PREFIX}_LIBRARY_HOME`;
+var NO_UPDATE_CHECK_ENV = `${ENV_PREFIX}_NO_UPDATE_CHECK`;
+var DESIGN_HARNESS_ENV = `${ENV_PREFIX}_DESIGN_HARNESS`;
+var API_URL_ENV = `${ENV_PREFIX}_API_URL`;
+var NO_IDLE_STOP_ENV = `${ENV_PREFIX}_NO_IDLE_STOP`;
+var CONTROL_PORT_ENV = `${ENV_PREFIX}_CONTROL_PORT`;
+var MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+var ATTACHMENT_GRACE_MS = 24 * 60 * 6e4;
+var UPDATE_CHECK_TTL_MS = 4 * 60 * 6e4;
+var IDLE_STOP_MS = 30 * 6e4;
+var SOURCE_ATTR = "data-ez-source";
+
+// src/project-root.ts
+import { existsSync } from "node:fs";
+import { dirname, join as join2, parse, resolve } from "node:path";
+function projectRoot(from) {
+  let dir = resolve(from);
+  const { root } = parse(dir);
+  for (; ; ) {
+    if (existsSync(join2(dir, ".git")) || existsSync(join2(dir, "package.json"))) return dir;
+    if (dir === root) return resolve(from);
+    dir = dirname(dir);
+  }
+}
+
+// src/vite.ts
+function walk(node, visit) {
+  visit(node);
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child && typeof child === "object" && "type" in child) {
+          walk(child, visit);
+        }
+      }
+    } else if (value && typeof value === "object" && "type" in value) {
+      walk(value, visit);
+    }
+  }
+}
+function ezdesignSource() {
+  let root = projectRoot(process.cwd());
+  return {
+    name: "ezdesign:source",
+    apply: "serve",
+    enforce: "pre",
+    configResolved(config) {
+      root = projectRoot(config.root);
+    },
+    transform(code, id) {
+      const [file] = id.split("?");
+      if (!file || !/\.[jt]sx$/.test(file) || file.includes("node_modules") || id.startsWith("\0")) {
+        return null;
+      }
+      let ast;
+      try {
+        ast = parse2(code, {
+          sourceType: "module",
+          plugins: ["jsx", "typescript", "decorators-legacy"]
+        });
+      } catch {
+        return null;
+      }
+      const rel = relative(root, file);
+      const s = new MagicString(code);
+      let changed = false;
+      walk(ast.program, (node) => {
+        if (node.type !== "JSXOpeningElement") return;
+        const name = node.name;
+        if (!name || name.type !== "JSXIdentifier") return;
+        const tag = name["name"];
+        if (typeof tag !== "string" || !/^[a-z]/.test(tag)) return;
+        const attrs = node["attributes"];
+        const hasAttr = attrs?.some(
+          (a) => a.type === "JSXAttribute" && a["name"]?.["name"] === SOURCE_ATTR
+        );
+        if (hasAttr || typeof name.end !== "number" || !node.loc) return;
+        s.appendRight(name.end, ` ${SOURCE_ATTR}="${rel}:${node.loc.start.line}"`);
+        changed = true;
+      });
+      if (!changed) return null;
+      return { code: s.toString(), map: s.generateMap({ hires: true }).toString() };
+    }
+  };
+}
+export {
+  ezdesignSource
+};

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "@cychien/ezdesign",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "Annotate your live dev app in the browser; feedback flows to your local coding agent, which edits the source. Review, iterate, repeat.",
+  "type": "module",
+  "author": "Justin Chien",
+  "homepage": "https://github.com/cychien/ezdesign#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cychien/ezdesign.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cychien/ezdesign/issues"
+  },
+  "bin": {
+    "ezdesign": "dist/cli.mjs"
+  },
+  "exports": {
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "skills/ezdesign",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "dev": "node scripts/dev.mjs",
+    "dev:agent": "node scripts/dev-agent.mjs",
+    "dev:cli": "node scripts/dev-cli.mjs",
+    "brand": "node scripts/brand-wordmark.mjs && node --import tsx scripts/brand-assets.mjs",
+    "check": "npm run build && npm run typecheck && npm test",
+    "typecheck": "tsc --noEmit && tsc -p src/extension --noEmit && tsc -p fixtures/playground --noEmit",
+    "test": "node scripts/test.mjs",
+    "version": "node scripts/sync-skill-version.mjs && git add skills/ezdesign/SKILL.md",
+    "prepublishOnly": "npm run check"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "keywords": [
+    "agent",
+    "review",
+    "annotation",
+    "feedback",
+    "dev-server",
+    "vite",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.4.0",
+    "@babel/parser": "^7.26.0",
+    "@hugeicons/core-free-icons": "^4.3.5",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "express": "^5.1.0",
+    "http-proxy-middleware": "^3.0.3",
+    "magic-string": "^0.30.17",
+    "open": "^10.1.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@fontsource/geist-sans": "5.3.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "@vitejs/plugin-react": "^4.7.0",
+    "esbuild": "^0.25.0",
+    "opentype.js": "1.3.4",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsx": "^4.23.11",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}

package/skills/ezdesign/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: ezdesign
+description: Open an ezdesign review session on a running web page. The user annotates the page in the browser, and each batch reaches the coding agent with exact source locations. Use when the user invokes /ezdesign, or asks to review, annotate or give visual feedback on a running page, or to explore designs on a canvas.
+metadata:
+  version: 0.9.1
+---
+
+# ezdesign
+
+Open a review: [reference/start.md](reference/start.md). A bare `/ezdesign`, with nothing after
+it, is that request: open a review on the project's running dev server.
+
+## Inside a review session
+
+The daemon has done the routing: its prompt says whether the turn is a feedback batch or an
+explore round, and what to do with it. Do not route again. A batch carries the page's `url`, the
+annotated `items` with their `anchor` (source `file:line`, selector, viewport), `references`, and
+`attachments`. An explore adds one element's capture - its markup, computed styles, slot and the
+page's tokens - and takes each variant back through a tool, editing no file.
+
+## Canvases
+
+An ACP review session also gives you the `ezdesign-canvas` tools. Each turn's prompt says which tab
+the user sent the batch from and which canvases exist.
+
+- When the user wants to explore directions, compare options or see a design before it is built,
+  put each one in a frame on a canvas: one `add_frame` per design, as soon as each is ready, on the
+  canvas the turn's prompt names. Call `create_canvas` only when no canvas is open or the user asks
+  for a new one. Leave `position` out; frames are placed for you.
+- A frame is a complete HTML document with its own `<head>` and styles, at a real viewport width
+  (390 phone, 768 tablet, 1280 desktop). Nothing is shared between frames.
+- An item whose `anchor.frame` is set was made inside a frame: `anchor.source` is a line of that
+  frame's file under `.ezdesign/canvases/`. Change a frame with `update_frame` (pass the
+  `expectedHash` you last read) or by editing its file.
+- Never edit `canvas.json` or `layout.json` by hand. Where a frame sits and its size are the user's.

package/skills/ezdesign/reference/baseline.md

@@ -0,0 +1,131 @@
+# Baseline
+
+> Only for a turn whose prompt says 增強設計 (the design harness) is on for it, or a request that
+> asks for it by name. In any other turn, handle the request as if you had never read this file.
+
+This is the taste the harness is built on, and the standard every piece is held to, whatever its
+direction. `DESIGN.md` sets how this product looks; the baseline is what good means under any look.
+The user's own words, in the request or in `.ezdesign/taste.md`, can move a rule here; nothing else
+does.
+
+Everything below serves one goal: the person on the page understands it quickly and gets done what
+they came to do.
+
+## Usability comes first
+
+- **Never hide what matters to look minimal.** The information and the actions the page exists for
+  stay in view and within one step. Only what matters less goes a level deeper, behind a menu, a
+  tab, a disclosure or a settings page. A product with a lot to do, like a Stripe or Shopify
+  dashboard, cannot be sparse, but it keeps the everyday work in front.
+- **Easy to use first; the looks follow.** A paragraph set in one colour leaves the reader to find
+  what matters. Darken what carries the point and lighten the rest, and it reads at ease and looks
+  better for it.
+- **Design serves the viewer and the business.** `PRODUCT.md` says who they are and what they need.
+  A striking home page is not there to be beautiful; it is there so the visitor stays.
+- **Start from the least the screen can do its job with.** Add an element only when it is needed;
+  each one has to earn its place.
+
+The check: every choice can be justified by what it does for the viewer or the business, and taking
+any element away makes the screen worse at its job.
+
+## Aim for outstanding, never average
+
+- **Do not settle for the safe average.** The first design that comes to mind is usually the mean
+  of every interface you have seen: competent, interchangeable, and forgettable. Aim for the
+  version an outstanding designer would ship, and for refined over merely correct.
+- **Outstanding comes from judgment and precision, not novelty.** Hierarchy that is exactly right,
+  spacing that is exactly right, details finished down to the states: that is what sets great work
+  apart. A clever gimmick is not the way there.
+- **Safe is not the same as right.** Do not reach for the conventional treatment because it cannot
+  be wrong. Use it when it is the best answer for this screen, and then make it better than usual.
+
+The check: someone who cares about design would stop and notice how well it is made. A piece
+nobody would comment on is not done.
+
+## Know what the point of the page is
+
+The point is what the person most wants to get done on this page, or what the business most wants
+them to do there. Purpose, in `make.md`, works it out; every rule below leans on it, so decide it
+before you style anything.
+
+It depends on the page, not on the kind of element:
+
+- On a blog post, the body text is the point.
+- On a list of posts, each post's title is the point, and its excerpt is not.
+- On a pricing page, the plans and the action that buys one are the point.
+
+One point per view, sometimes one per repeated item. When everything is emphasised, nothing is:
+a page with many points has none.
+
+## Design for the whole screen
+
+- **A component is designed in its screen, never on its own.** Before changing one, work out what
+  this screen is for: what the person should get done here, and what they should feel, such as
+  confident, calm or eager to start. Style the component for that.
+- **Its role on the screen sets its weight.** Its size, colour, emphasis and spacing are decided
+  against its neighbours and the point of the screen: as loud as its role, no louder.
+- **Better alone and worse on the screen is worse.** A change that polishes the component and
+  pulls the screen out of balance has failed.
+
+The check: look at the whole screen after the change, not only the component, and it reads better
+as a whole.
+
+## Hierarchy is always visible
+
+- **Rank shows before a word is read.** Size, weight, spacing, borders, colour and type set what
+  leads, what follows and what recedes. The eye lands first on the point.
+- **Nearness and likeness mean relation.** Put related things close together and give them a
+  shared style: a ground laid under the group, the same colour, the same shape or treatment. A
+  ground or border that holds a group is its one container, so its members are not boxed again.
+- **Distance and difference mean separation.** Unrelated information sits further apart, in a
+  different style, or across a divider. The same means that set groups apart bind the members of a
+  group together.
+
+The check: at a glance, before reading anything, it is plain what leads and which things go
+together.
+
+## Grey first, colour sparingly
+
+- **Build on the grey tokens.** Most of a page is greys: the ground, the surfaces, the text, the
+  lines. The primary colour appears in small amounts, on what the user acts on or needs to find,
+  such as the main action, the current selection or a live state.
+- **The darkest greys are for the point.** Near-black is kept for what matters most, such as the
+  key heading or the key text. Everything else steps down to a lighter grey, so the point is what
+  stands out.
+- **Lines and borders are light grey.** A divider, a card's edge or a table rule uses the lightest
+  grey that still separates. Do not reach for a dark-grey token to draw a line. A form field's
+  outline can be a step darker so it can be found, but not dark enough to compete with the text.
+- **Weight and colour balance each other.** A heavier weight emphasises and a lighter colour
+  recedes, so the two can be set against each other: a list a step above regular weight (around
+  450) in a lighter grey stays quiet beside the heading while still reading full. Regular weight
+  made lighter looks thin, and the whole UI with it. An in-between weight needs a variable font;
+  with only static weights it snaps to the nearest one, so check it renders.
+
+## Quality comes from proportion and detail
+
+- **Quality is built, not added.** It comes from proportion, a clear type scale, precise spacing,
+  exact alignment and finished states: hover, focus, pressed, selected, disabled, empty, loading,
+  error. It never comes from a gimmick.
+- **Spacing is a decision each time, and it depends on what the page is for.**
+  - On a page that presents, such as a landing or marketing page, spacing only has to feel
+    comfortable: room to breathe around each section and its content.
+  - On a page people work in, such as a dashboard, a table, a settings page or an editor, spacing
+    is compact but easy to scan: tight rows, consistent columns and edges the eye can run down, and
+    groups set apart by a clearly larger gap than the one inside them.
+- **Type runs small.** Most text is set smaller than a first instinct picks, and that restraint is
+  much of what makes a screen look refined. Rank comes from weight, colour and space as much as
+  from size, so a heading does not need to be big to lead. Large, heavy type needs a real reason,
+  such as the one headline of a landing page or the number that is the point of a dashboard; it is
+  never the default for titles, labels or buttons. Small never means hard to read: the craft
+  floor's legibility still holds.
+- **Few elements, each finished with care.** Simple is about how many things there are, not how
+  plainly each is made.
+
+## Decoration serves, never competes
+
+- **Decoration is welcome when it belongs.** A considered shadow, ground, icon, illustration or
+  transition that makes a piece feel finished is worth it. Flatness and bareness are not virtues in
+  themselves; refined beats plain.
+- **It stays in harmony with the whole,** in the page's colours, radii and weight.
+- **It never takes attention from the task.** Nothing decorative is louder than the point of the
+  page.

package/skills/ezdesign/reference/components.md

@@ -0,0 +1,102 @@
+# Build the project's design system and components
+
+> Only for a turn whose prompt says 增強設計 (the design harness) is on for it, or a request that
+> asks for it by name. In any other turn, handle the request as if you had never read this file.
+
+## What this step is
+
+`DESIGN.md` says what the visual language is, in broad strokes. This step makes it real in the
+stack: its anchors and its character become the design system the project actually builds with, and a set of components is built on
+that system in the project's own component library. That set is the foundation the making step
+builds UI from.
+
+The stack step has already recorded which design system and which component library the project
+uses, in `design_system` and `components` in `.ezdesign/config.json`. This step builds to them and
+adds one field, the list of primitives that now exist, so the making step reuses rather than
+reinvents:
+
+```json
+"components": {
+  "library": "shadcn",
+  "path": "src/components/ui",
+  "primitives": ["button", "input", "card", "dialog"]
+}
+```
+
+## The invariant: nothing visible changes
+
+When this step is done, every existing screen renders exactly as it did. The project's rules and
+documents get more complete; its UI does not move. Concretely:
+
+- **The existing system wins.** Where the project's config or components disagree with
+  `DESIGN.md`, keep the project's value untouched and report the divergence to the user; the
+  correction, if they want one, is a refresh of `DESIGN.md`, not an edit to what renders.
+- **New tokens take new keys.** A token `DESIGN.md` has and the system lacks is added under a key
+  nothing uses yet. An existing key is never renamed, retuned or repurposed.
+- **New components do not replace used ones.** An existing component stays as it is, even when a
+  cleaner one could be built; new primitives are added beside it and wired into nothing.
+
+## Step 1: Load current state
+
+`PRODUCT.md`, `DESIGN.md` and `.ezdesign/config.json` with a stack and a browser tool are the
+prerequisites; run [product.md](product.md), [design.md](design.md) or [stack.md](stack.md) for
+whichever is missing, and come back.
+
+Then read what the project already has: the design system at `design_system.path`, and the
+components at `components.path`, with each one's variants and states. If `components.primitives`
+is recorded and still matches the directory, there is nothing to do here; say so in one line and
+go on.
+
+## Step 2: The design system
+
+Carry `DESIGN.md`'s anchors - its colours, type roles and radius - into the design system, in the
+idiom `design_system.kind` names, under the invariant above. When `design_system` is `null`, create
+one in the stack's own idiom and record it there. Keep `DESIGN.md`'s descriptive names (`canvas`,
+`oxblood-deep`) as the keys, so a class or variable reads like the document.
+
+The document is deliberately broad, so the scales it does not write out are this step's: where the
+system has none yet, derive them in the language's character - a type ramp with the contrast its
+Typography describes, a spacing scale with the density its Layout describes, shadows as its
+Elevation & Depth describes. They live in the design system; `DESIGN.md` is not edited for them.
+
+## Step 3: The component set
+
+Build the primitives the product needs and the project lacks: from `PRODUCT.md`'s workflows, the
+set the making step will reach for - button, input, select, checkbox, card, dialog, navigation,
+badge, tooltip, table - and no component the product has no use for. Each carries every state it
+can be in: hover, focus-visible, active, disabled, error, loading where it applies.
+
+**Write them the way the project already writes components.** `components.library` says how:
+
+- **A component library** (`shadcn`, `mui`, `chakra`, `mantine`, and so on): new primitives come
+  from that library, used the way it is meant to be used. With `shadcn`, add them through its own
+  CLI (`npx shadcn@latest add <name>`) so they land where `components.json` says and in shadcn's
+  structure; check first which ones exist, add only the missing ones, and never pass `--overwrite`.
+  The CLI can touch shared files, the global stylesheet and the Tailwind config, so read its diff
+  against the invariant. With any other library, compose its components and theme them through its
+  theme, not with overrides on each instance.
+- **`custom`**: written by hand, after reading two or three of the existing components, in their
+  file layout, naming, props, variant API and styling approach.
+- **`none`**: written by hand in the stack's idiom, at `components.path`.
+
+Whatever the source, style every primitive from the design system's tokens, so it speaks the
+product's language. A library's default look stays where it already fits `DESIGN.md`'s direction;
+it is restyled only where it does not.
+
+Look for precedent before designing a component: [inspiration.md](inspiration.md), searched by what
+the component is and has to show.
+
+## Step 4: Verify the invariant, then record
+
+Before writing anything, screenshot the project's main screens:
+`node <skill>/scripts/page.mjs shots <url> <dir>/before <path> ...`, where `<skill>` is the folder
+above this file's `reference/`, `<url>` the running page and `<dir>` a folder outside the project;
+it shoots every path at desktop and at 390px. After writing, shoot them again into `<dir>/after`
+and run `node <skill>/scripts/page.mjs compare <dir>/before <dir>/after`. Every line must say
+`same`; any difference is a change to undo, not a finding to report. Only when the script cannot
+run - there is no Chrome - do the same with the browser tool. Then write `components.primitives` into
+`.ezdesign/config.json`, and `design_system` when this step created one.
+
+Tell the user in a few lines what the design system now carries, which primitives were added and
+where, and every divergence between `DESIGN.md` and the existing system that you left as it was.
+When this step runs as part of a larger request - a setup turn, or a batch that needed it first - skip this and let that request's reply cover it. Then end, or resume the request that invoked this.

package/skills/ezdesign/reference/critique.md

@@ -0,0 +1,129 @@
+# Review a piece of UI
+
+> Only for a turn whose prompt says 增強設計 (the design harness) is on for it, or a request that
+> asks for it by name. In any other turn, handle the request as if you had never read this file.
+
+You are an independent reviewer. Someone else made this change; you did not see them make it, and
+their reasons are not your concern. You judge what is on the screen, the way the person who asked
+for it will when they look. You change nothing: no file is edited, created or deleted.
+
+Be the hard one to please. A maker's view of their own work is generous by nature, and you are
+here because it is. Assume the piece is not good enough until what you see proves it is, and
+praise nothing you cannot point at.
+
+## What you have
+
+- The user's request, in their words.
+- Where it lives: the page's url, the viewport the request was made at, and the element or file the
+  change is in.
+- Screenshots of the piece in place, taken by the maker at that viewport - and at the narrowest
+  width when the piece reflows - with enough of the page around it to see how it sits, and one of
+  the whole page.
+- `PRODUCT.md` at the project root: who the page is for, and what it has to do for them and for the
+  business behind it.
+- `DESIGN.md`: the visual language the page speaks. A direction, not a rule; judge whether the
+  piece belongs, not whether it complies.
+- `baseline.md` and `principles.md`, which the brief names: the standard every piece is held to,
+  which these criteria are drawn from, and the craft floor. Read both before you score.
+- `.ezdesign/taste.md`, when it exists: what this user has shown they consider good, learned from
+  their own feedback. Read it before you judge; it outranks the examples below where they disagree.
+
+## Look first
+
+Study the screenshots before you score: the pixels are the work, and they are what the user will
+see. Judge details on the piece's own screenshots, which are at twice the page's pixels, and the
+rhythm of the page on the whole-page one; the files named `-hover`, `-focus` and `-active` are the
+piece in those states, and a state that looks wrong is a flaw of the piece. Open the page yourself, with the browser tool `.ezdesign/config.json` names, only for what a
+screenshot cannot show - a hover, an open menu, a state behind a click. Then glance at the diff
+(`git diff`) for one thing only: whether a control the project has a component for - a button, an
+input, a card, a dialog, the ones `.ezdesign/config.json` lists under `components` - was built from
+that component rather than by hand. Do not tour other widths or measure the DOM: a review takes a
+minute, and the user is waiting on it. Judge **what changed**,
+and what it does to the page: a flaw elsewhere that the change did not cause is not this piece's.
+
+## The bar
+
+The baseline, in `baseline.md`: outstanding rather than the safe average, designed for the whole
+screen rather than the component alone, the point of the page first and plain, hierarchy visible
+before a word is read, greys carrying the page and colour kept for the point, spacing fit for what
+the page is for, and quality built from proportion and finished detail. A clever idea earns
+nothing on its own; a useful move done cleanly is what impresses. Hold the piece to that bar, not
+to what is usual for the page it is on.
+
+## The criteria
+
+Score each from 1 to 10. They are listed in order of weight.
+
+- **Useful**: at a glance, before reading a word, can the viewer tell what matters here and what to
+  do? Does it serve the person and the business `PRODUCT.md` describes? Emphasis falls on what
+  carries the point, and the rest recedes.
+  - *Hierarchy*: is what the eye lands on first what the user needs most?
+- **Refined**: is it built to the baseline's detail? Proportion and a clear type scale, with type
+  kept small unless size has a reason; spacing comfortable on a page that presents, compact and
+  easy to scan on a page people work in; edges that line up; hover, focus, selected, disabled,
+  empty and error states finished. Greys carry it,
+  lines are light, the darkest text and the colour go to the point only, and any decoration sits in
+  harmony without pulling focus. It comes from precision and refinement, never from a gimmick. A
+  competent piece nobody would comment on scores 5.
+- **Clear**: related things sit together and share a style; unrelated things are set apart by
+  space, a faint rule, a different ground or shape. There is one primary element and it is obvious.
+  Nothing is there that the job does not need.
+  - *Proportion*: does anything secondary take more room than it earns?
+  - *Density*: is the information too spread out, or too crowded, for what it holds?
+- **Fits**: it belongs on this page - its type, colour, spacing, radii and tone agree with what
+  surrounds it, or depart on purpose and look it - and the page as a whole still looks good with
+  it: it does not pull focus from what the page leads with, crowd its neighbours, or break the
+  rhythm of the sections around it. A piece that is lovely alone and hurts the page scores low.
+- **Craft**: alignment, spacing rhythm, contrast, type hierarchy, states. Nothing overflows or
+  clips, and no card is nested in a card; a row's hover, selected or current-step fill is a
+  highlight, not a card. A control the project has a component for is built from it; a
+  hand-made copy that only looks the same is a flaw, since the two drift apart the next time the
+  component changes.
+  - *Consistency*: do headings, spacing and actions at the same level match each other?
+  - *States*: would empty data, long text or an error message break the layout? Judge it from the
+    diff - fixed heights, text that cannot wrap, a list with no empty state - without building the
+    states.
+
+## What good has looked like
+
+What this skill's author picked when judging blind, as the kind of judgment to make - never as
+treatments to ask for. `.ezdesign/taste.md` carries on from here for each user.
+
+- Hierarchy beat decoration: making what matters stand out did more than restyling everything.
+- Plain beat clever: a well-made clever idea lost to a clear, direct treatment every time.
+- A card nested in a card lost every time, however polished the cards.
+
+## The verdict
+
+- **ship**: every criterion is 7 or above and nothing breaks the craft floor.
+- **refine**: the direction is right and the execution is not. Say exactly what to change; when
+  Refined is the low score, one of the items is the move that would get it there.
+- **pivot**: the direction itself fails Useful or Clear, and polishing it will not fix that. Say why
+  in one line, and what a better direction would get right. A failure that one adjustment can fix -
+  an order, a count, one item that must not be missed brought forward - is refine, with that
+  adjustment as the fix, whatever the direction.
+
+## When there is an earlier version
+
+The brief may name a screenshot of an earlier version of the same piece. Open it and compare it with
+what is on the page now, at the same crop. Score the version on the page, and say which of the two
+is better as a whole - not which fixed more of a list.
+
+## Reply
+
+Reply with exactly this, and nothing before or after it:
+
+```
+useful 0/10 · refined 0/10 · clear 0/10 · fits 0/10 · craft 0/10
+verdict: ship | refine | pivot
+better: current | earlier - <one reason>
+1. <where on the page> - <what is wrong> - <what to do instead>
+```
+
+The `better:` line only when there is an earlier version to compare with.
+
+At most three numbered items, the one that matters most first, each specific enough to act on
+without looking again: name the element and the change, not a quality ("the three status labels in
+the right column: same grey as the body text, so the stuck one does not stand out - make it the
+risk colour and the others muted"). A **ship** verdict may list up to two small improvements, or
+none.