design-spine 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elizabeth Stein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# Design Spine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Look at every screen before you ship it.
+
+Design Spine screenshots every route of your Next.js app in every state, width and theme, flags what broke, and gives you one contact sheet to approve or reject each screen. Approved screens become baselines, and `spine diff` fails CI when a screen drifts from what a person approved.
+
+Everything runs on your machine. No account, no upload, no per-snapshot bill.
+
+![Design Spine contact sheet](docs/images/contact-sheet.png)
+
+## Why
+
+Most UI gets built and checked in one state: the happy path, at desktop width, in light mode. AI coding agents make this worse, because they build screen by screen and never open the 390px dark-mode empty state. Design Spine makes the full matrix visible and makes "someone looked at it" a recorded fact instead of a hope.
+
+## Quick start
+
+Requires [Bun](https://bun.sh) 1.3+ and a running copy of your app.
+
+```bash
+npm install -D design-spine
+npx playwright install chromium
+
+npx spine plan        # reads app/ and drafts design-spine.json
+npx spine capture     # screenshots route x state x 390/1280 x light/dark
+npx spine review      # opens the contact sheet at http://localhost:4747
+```
+
+In the contact sheet, press `j`/`k` to move, `a` to approve, `r` to reject and `Enter` to inspect a screenshot at full size against its baseline.
+
+## What it checks on every screenshot
+
+- HTTP errors, redirects and failed captures
+- Console errors and uncaught page errors
+- Horizontal overflow (the classic mobile bug)
+- Near-blank regions, such as cards that rendered empty
+- Broken images and clipped text
+- Fixed overlays covering content, such as cookie banners and chat widgets
+- Optional: axe accessibility scan, repeat-capture stability, and a Claude vision critique
+
+Automatic checks never count as approval. Only a person approves.
+
+## Reach the states nobody opens
+
+Empty, loading and error states need data. Describe them in `design-spine.json` with mocked responses and interaction steps instead of seeding a database:
+
+```json
+{
+  "path": "/dashboard",
+  "states": [
+    { "name": "ideal", "storageState": "auth/populated.json" },
+    {
+      "name": "error",
+      "responses": [{ "url": "**/api/dashboard", "status": 503, "body": "Unavailable" }],
+      "ready": { "selector": "[role=alert]" }
+    }
+  ]
+}
+```
+
+`spine doctor` lists every state you have not made capturable yet, so missing coverage stays visible instead of silently passing.
+
+## Gate CI on approved screens
+
+```bash
+spine approve           # approved tiles become baselines
+spine diff              # exit 1 when a screen differs from its approved baseline
+spine diff --strict     # also require full coverage and a person's approval on this run
+spine report --out review.html   # portable offline record of what was approved and why
+```
+
+In CI, add the action after the step that starts your app, and commit `design-spine.json` and `.design-spine/baselines/`:
+
+```yaml
+- run: npm run build && (npm start &) && npx wait-on http://localhost:3000
+- uses: forbiddenlink/design-spine@main
+  with:
+    base-url: http://localhost:3000
+```
+
+The job fails when any screen changes from its approved baseline, and uploads the run as an artifact. To accept a change, download the artifact into `.design-spine/runs/`, run `spine review --run <id>`, approve, then `spine approve --run <id>` and commit the new baselines. Fonts render differently on macOS and Linux, so approve baselines from a CI (Linux) run.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `plan` | Drafts `design-spine.json` from `app/` or `src/app/` |
+| `doctor` | Validates the manifest and lists unfinished coverage, without a browser |
+| `capture` | Screenshots every route x state x viewport x theme and runs the checks |
+| `review` | Local contact sheet for approve, reject and notes |
+| `critique` | Optional Claude vision pass through the `claude` CLI |
+| `approve` | Promotes approved tiles to baselines |
+| `diff` | Compares a run with baselines; `--strict` requires complete approved evidence |
+| `report` | Self-contained HTML record of a review |
+| `lint` | Ratchet on arbitrary Tailwind values such as `w-[37px]` |
+| `status` | Writes `.design-spine/status.json` for dashboards |
+
+Full reference: [docs/USAGE.md](docs/USAGE.md).
+
+## How it compares
+
+| | Design Spine | Chromatic, Percy, Argos | Playwright `toHaveScreenshot` |
+|---|---|---|---|
+| Runs locally, no upload | Yes | No | Yes |
+| Plans the route x state matrix from your app | Yes | No | No |
+| Human approval ledger per screenshot | Yes | Yes, in the cloud | No |
+| Coverage gaps shown as unfinished | Yes | No | No |
+| Needs Storybook | No | Chromatic: mostly | No |
+| Pricing | Free | Per snapshot | Free |
+
+## Limits
+
+- Next.js App Router only for `plan`. Other apps can write the manifest by hand.
+- Chromium only. Tested on macOS, and the test suite runs on Linux in CI. Windows is not verified.
+- Requires Bun to run the CLI.
+
+## License
+
+MIT

package/bin/spine.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Thin launcher: Design Spine needs Bun (HTML imports, Bun.serve), so hand off to it.
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const MESSAGE = 'Design Spine runs on Bun 1.3+. Install: curl -fsSL https://bun.sh/install | bash'
+const cli = fileURLToPath(new URL('../src/cli.ts', import.meta.url))
+const version = spawnSync('bun', ['--version'], { encoding: 'utf8' })
+const [major = 0, minor = 0] = (version.stdout ?? '').trim().split('.').map(Number)
+if (version.error || version.status !== 0 || major < 1 || (major === 1 && minor < 3)) {
+  console.error(MESSAGE)
+  process.exit(1)
+}
+const result = spawnSync('bun', [cli, ...process.argv.slice(2)], { stdio: 'inherit' })
+process.exit(result.status ?? 1)

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "design-spine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Screenshot every route and state of your Next.js app, then approve each screen by eye. Local, no account.",
+  "license": "MIT",
+  "author": "Elizabeth Stein",
+  "homepage": "https://github.com/forbiddenlink/design-spine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forbiddenlink/design-spine.git"
+  },
+  "bugs": "https://github.com/forbiddenlink/design-spine/issues",
+  "keywords": [
+    "visual-regression",
+    "screenshot",
+    "nextjs",
+    "playwright",
+    "design-review",
+    "ui-testing",
+    "cli",
+    "claude-code"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "packageManager": "pnpm@12.6.0",
+  "engines": {
+    "node": ">=22.12",
+    "bun": ">=1.3.13"
+  },
+  "type": "module",
+  "bin": {
+    "spine": "bin/spine.js"
+  },
+  "scripts": {
+    "build": "bun build --compile src/cli.ts src/lib/comparison-worker.ts --external 'chromium-bidi/*' --external electron --define 'import.meta.spineWorker=\"./lib/comparison-worker.js\"' --outfile dist/spine",
+    "spine": "bun src/cli.ts",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "format": "biome format --write ."
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "commander": "^15.0.0",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.63.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@types/bun": "^1.4.2",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  }
+}

package/src/assets.d.ts

@@ -0,0 +1,3 @@
+interface ImportMeta {
+  readonly spineWorker?: string
+}