Skip to content
Back to search

ui-craft

MarketplaceWorks with Claude CodeGitHub

UI Craft — the design-quality system for AI coding agents: anti-slop UI, spec-driven design, review agents, and MCP quality gates.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/educlopez/ui-craft with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/educlopez/ui-craft'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/educlopez-ui-craft/badge.svg)](/listings/educlopez-ui-craft)

HTML

<a href="/listings/educlopez-ui-craft"><img src="/api/listings/educlopez-ui-craft/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

CLI — recommended (cross-harness, installs the whole system)

A single static Go binary that detects your AI coding harness and wires skill+commands, MCP gates, review agents, and design-memory into its native config in one interactive pass. No Node required at install time.

**macOS / Linux:**

curl -fsSL https://ui-craft.smoothui.dev/install | bash

**Windows:**

irm https://ui-craft.smoothui.dev/install.ps1 | iex

The script detects your OS/arch, downloads the latest release, verifies its checksum, and installs the `ui-craft` binary — no brew/scoop required.

**Then run:**

ui-craft install

<details> <summary>Alternative installs (Homebrew, Scoop)</summary>

**macOS (Homebrew):**

brew install --cask educlopez/tap/ui-craft

**Windows (Scoop):**

scoop bucket add educlopez https://github.com/educlopez/scoop-bucket
scoop install educlopez/ui-craft

</details>

`ui-craft install` detects Claude Code / Cursor / Codex / Gemini / OpenCode, walks you through à-la-carte component selection (interactive TUI or `--yes` for CI), and writes each chosen component into that harness's native config. All writes are idempotent, backed up before they happen, and rolled back automatically on any failure.

**What rides which install?**

| Component | CLI | Claude Code plugin | `npx skills add` | |-----------|:---:|:------------------:|:----------------:| | Skill + commands | All harnesses | ✅ | All harnesses | | MCP gates (`check_anti_slop`, `tokens_lint`, `acceptance_bar`, `score_ui`) | All MCP-capable harnesses | ✅ auto-wired | Manual `.mcp.json` | | Review agents (`design-reviewer`, `a11y-auditor`) | All harnesses | ✅ | — | | Design memory (`.ui-craft/`) | ✅ (component opt-in) | — | — |

Platform support

Six binaries ship on every release. They are not equally exercised, and the difference is worth knowing before you rely on one.

| Platform | Binary | Go suite in CI | Installer end-to-end | Gatekeeper / fresh install | |---|:--:|:--:|:--:|:--:| | macOS Apple Silicon · `darwin/arm64` | ✅ | ✅ | ✅ | ✅ by hand, every release | | macOS Intel · `darwin/amd64` | ✅ | — | — | — | | Linux x86-64 · `linux/amd64` | ✅ | ✅ | ✅ Ubuntu · Fedora · Arch | n/a | | Linux arm64 · `linux/arm64` | ✅ | — | — | n/a | | Windows x86-64 · `windows/amd64` | ✅ | ✅ | ✅ | n/a | | Windows arm64 · `windows/arm64` | ✅ | — | — | n/a |

A dash means the binary is built and published but nothing runs on it. Those rows are honest gaps, not oversights we have quietly closed.

**Windows** has only been covered since v1.0.16. Before that the suite had never been green there, and five Windows-only bugs shipped as a result — one of them deleting files during rollback that it existed to protect. The suite now gates every pull request that touches the CLI.

**macOS on Intel** is the largest remaining gap: built and shipped, never tested, and not covered by the manual Gatekeeper check either — that one is Apple-Silicon-only.

Two conditions are untested on every platform: installing with the disk nearly full, and two `ui-craft install` runs racing against the same machine. See [`RELEASE_CHECKLIST.md`](RELEASE_CHECKLIST.md) for what each release actually verifies, and what a completed checklist does not promise.

**Full reference docs:** [ui-craft.smoothui.dev/docs](https://ui-craft.smoothui.dev/docs).

Claude Code plugin — alternative (skill + commands + agents + MCP, no CLI needed)

One command installs the skill, all 25 slash commands, the 2 review agents, and the MCP quality-gate server — auto-wired, no `.mcp.json` editing:

/plugin marketplace add educlopez/ui-craft
/plugin install ui-craft

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "ui-craft",
  4. "description": "UI Craft — the design-quality system for AI coding agents: anti-slop UI, spec-driven design, review agents, and MCP quality gates.",
  5. "owner": {
  6. "name": "Eduardo Calvo",
  7. "url": "https://github.com/educlopez"
  8. },
  9. "plugins": [
  10. {
  11. "name": "ui-craft",
  12. "source": "./",
  13. "description": "Design engineering skill + system for AI coding agents: anti-slop UI rules, outcome recipes, spec-driven design (/sddesign), design-review + a11y agents, and MCP quality gates.",
  14. "license": "MIT",
  15. "homepage": "https://ui-craft.smoothui.dev",
  16. "keywords": ["ui", "design", "accessibility", "css", "frontend", "design-system", "anti-slop"]
  17. }
  18. ]
  19. }
README.md · README · 813 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # UI Craft
  2. **Ship designer-grade UI by default.** A design engineering system for AI coding agents — install it as a skill or as the `ui-craft` CLI, and your agent starts designing like it has taste. Ask for a dashboard, get one you'd put in production. Not gradient cards and bounce animations.
  3. **Website:** [ui-craft.smoothui.dev](https://ui-craft.smoothui.dev)
  4. **Privacy:** [Plugin privacy notice](PRIVACY.md). Local quality tools process
  5. project files and return findings to your agent; UI Craft does not operate a
  6. backend that retains those inputs. Workflows can write local project artifacts.
  7. If your agent uses browsing or optional third-party integrations during a
  8. workflow, its queries and supplied content are handled by those providers under
  9. your agent's permissions and their policies, not by a UI Craft service.
  10. **Support:** [UI Craft issues](https://github.com/educlopez/ui-craft/issues).
  11. ![UI Craft](assets/og.png)
  12. ## Ask for a surface. Ship it.
  13. ```
  14. /craft dashboard
  15. ```
  16. Three questions (or none — the defaults are strong), a named composition, a production theme preset, and a build that must pass a **10-item acceptance bar** before it reports done: *"would a designer retouch this?"* If a box fails, it isn't done.
  17. For everything else — reviews, animations, forms, polish — the skill routes by intent: just describe what you're building.
  18. **New here?** Run `/start` — it reads your project (framework, tokens, brief, existing UI) and tells you what ui-craft can do right now, then points you at the right next step.
  19. ## What it does
  20. UI Craft gives AI coding agents the design knowledge they're missing. Not templates. Not component libraries. Actual craft knowledge — opinionated rules about how interfaces should look, move, and feel — plus the tooling to verify the result. Stack-agnostic by design.
  21. Every UI gets tested against a single question: *"Would someone believe AI made this?"* If yes, it starts over.
  22. ### The ladder — four rungs
  23. There is one thing to learn, and it's a ladder. Each rung is a real jump in what you get, and each costs a little more than the one below. **You only climb when you want the next thing.**
  24. | Rung | You want | You do | You get | Effort |
  25. |------|----------|--------|---------|--------|
  26. | **0 · Ask** | Better UI with zero effort | Install, then ask for UI the way you always do | Real hierarchy, your own tokens, no AI slop — same prompt, shippable result | none |
  27. | **1 · Direct** | Control over one pass | `/craft`, `/critique`, `/polish`, `/animate`, … | A focused pass on one surface, aimed by you | one command |
  28. | **2 · Persist** | Consistency across sessions | `/brief`, `/tokens`, `/remember` | Durable design context every future session reads | write once |
  29. | **3 · Enforce** | Proof it cannot regress | `/finalize`, review agents, MCP gates, `ui-craft-detect` | Gates in review and CI, plus a deterministic 0-100 score | wire once |
  30. **Start at rung 0.** Most people never leave it — that's the point. Rungs 1 to 3 are there the day you want them, and `/start` will tell you which rung your project is on right now.
  31. `/sddesign` is **not** a fifth rung. It's the express lane that walks rungs 1 to 3 in one guided run, for a single big surface.
  32. **What makes this different:** the only AI design system that produces a **scoreable, defensible critique** — Nielsen's 10 usability heuristics × 6 classic design laws (Fitts, Hick, Doherty, Cleveland-McGill, Miller, Tesler) × 5 persona walkthroughs, with every finding tagged by business impact (`blocks-conversion` / `adds-friction` / `reduces-trust` / `minor-polish`). Paste the scorecard straight into any issue tracker.
  33. ## Same prompt, different result
  34. <table>
  35. <tr>
  36. <td><strong>Without UI Craft</strong><br/><img src="assets/screenshots/hero-without.png" alt="Hero built without UI Craft" width="100%" /></td>
  37. <td><strong>With UI Craft</strong><br/><img src="assets/screenshots/hero-with.png" alt="Hero built with UI Craft" width="100%" /></td>
  38. </tr>
  39. <tr>
  40. <td><img src="assets/screenshots/dashboard-without.png" alt="Dashboard built without UI Craft" width="100%" /></td>
  41. <td><img src="assets/screenshots/dashboard-with.png" alt="Dashboard built with UI Craft" width="100%" /></td>
  42. </tr>
  43. </table>
  44. More before/after comparisons on the [landing page](https://ui-craft.smoothui.dev).
  45. ## Install
  46. ### CLI — recommended (cross-harness, installs the whole system)
  47. A single static Go binary that detects your AI coding harness and wires skill+commands, MCP gates, review agents, and design-memory into its native config in one interactive pass. No Node required at install time.
  48. **macOS / Linux:**
  49. ```bash
  50. curl -fsSL https://ui-craft.smoothui.dev/install | bash
  51. ```
  52. **Windows:**
  53. ```powershell
  54. irm https://ui-craft.smoothui.dev/install.ps1 | iex
  55. ```
  56. The script detects your OS/arch, downloads the latest release, verifies its checksum, and installs the `ui-craft` binary — no brew/scoop required.
  57. **Then run:**
  58. ```bash
  59. ui-craft install
  60. ```
  61. <details>
  62. <summary>Alternative installs (Homebrew, Scoop)</summary>
  63. **macOS (Homebrew):**
  64. ```bash
  65. brew install --cask educlopez/tap/ui-craft
  66. ```
  67. **Windows (Scoop):**
  68. ```powershell
  69. scoop bucket add educlopez https://github.com/educlopez/scoop-bucket
  70. scoop install educlopez/ui-craft
  71. ```
  72. </details>
  73. `ui-craft install` detects Claude Code / Cursor / Codex / Gemini / OpenCode, walks you through à-la-carte component selection (interactive TUI or `--yes` for CI), and writes each chosen component into that harness's native config. All writes are idempotent, backed up before they happen, and rolled back automatically on any failure.
  74. **What rides which install?**
  75. | Component | CLI | Claude Code plugin | `npx skills add` |
  76. |-----------|:---:|:------------------:|:----------------:|
  77. | Skill + commands | All harnesses | ✅ | All harnesses |
  78. | MCP gates (`check_anti_slop`, `tokens_lint`, `acceptance_bar`, `score_ui`) | All MCP-capable harnesses | ✅ auto-wired | Manual `.mcp.json` |
  79. | Review agents (`design-reviewer`, `a11y-auditor`) | All harnesses | ✅ | — |
  80. | Design memory (`.ui-craft/`) | ✅ (component opt-in) | — | — |
  81. ### Platform support
  82. Six binaries ship on every release. They are not equally exercised, and the difference is worth knowing before you rely on one.
  83. | Platform | Binary | Go suite in CI | Installer end-to-end | Gatekeeper / fresh install |
  84. |---|:--:|:--:|:--:|:--:|
  85. | macOS Apple Silicon · `darwin/arm64` | ✅ | ✅ | ✅ | ✅ by hand, every release |
  86. | macOS Intel · `darwin/amd64` | ✅ | — | — | — |
  87. | Linux x86-64 · `linux/amd64` | ✅ | ✅ | ✅ Ubuntu · Fedora · Arch | n/a |
  88. | Linux arm64 · `linux/arm64` | ✅ | — | — | n/a |
  89. | Windows x86-64 · `windows/amd64` | ✅ | ✅ | ✅ | n/a |
  90. | Windows arm64 · `windows/arm64` | ✅ | — | — | n/a |
  91. A dash means the binary is built and published but nothing runs on it. Those rows are honest gaps, not oversights we have quietly closed.
  92. **Windows** has only been covered since v1.0.16. Before that the suite had never been green there, and five Windows-only bugs shipped as a result — one of them deleting files during rollback that it existed to protect. The suite now gates every pull request that touches the CLI.
  93. **macOS on Intel** is the largest remaining gap: built and shipped, never tested, and not covered by the manual Gatekeeper check either — that one is Apple-Silicon-only.
  94. Two conditions are untested on every platform: installing with the disk nearly full, and two `ui-craft install` runs racing against the same machine. See [`RELEASE_CHECKLIST.md`](RELEASE_CHECKLIST.md) for what each release actually verifies, and what a completed checklist does not promise.
  95. **Full reference docs:** [ui-craft.smoothui.dev/docs](https://ui-craft.smoothui.dev/docs).
  96. ### Claude Code plugin — alternative (skill + commands + agents + MCP, no CLI needed)
  97. One command installs the skill, all 25 slash commands, the 2 review agents, and the MCP quality-gate server — auto-wired, no `.mcp.json` editing:
  98. ```
  99. /plugin marketplace add educlopez/ui-craft
  100. /plugin install ui-craft
  101. ```
  102. The plugin bundles a `.mcp.json` (`npx -y ui-craft-mcp@0.9.1`), so the deterministic gates register automatically on install. The exact package version is declared in [`distribution-manifest.json`](distribution-manifest.json), avoiding an implicit upgrade on first launch. This uses Claude Code's own plugin system, so it's not affected by the global-path issue noted below.
  103. ### Cursor plugin — alternative (skill + commands + agents + MCP + rules + hook)
  104. Clone this repository into Cursor's local plugin folder, then reload the window:
  105. ```bash
  106. git clone https://github.com/educlopez/ui-craft.git ~/.cursor/plugins/local/ui-craft
  107. ```
  108. The plugin is the repo itself (`.cursor-plugin/plugin.json`). It registers the `ui-craft` skill and its variants, the slash commands, the `design-reviewer` and `a11y-auditor` agents, the `.mdc` rules, the `ui-craft-mcp` quality-gate server, and a `preToolUse` hook that runs `ui-craft-detect` before every file write.
  109. Open **Customize** and confirm those components loaded. On Teams and Enterprise, local plugin imports must be allowed under Dashboard → Settings → Security & Identity → Marketplace and Plugins.
  110. ### Agent Skills — alternative (skill + commands only, any harness)
  111. ```bash
  112. npx skills add educlopez/ui-craft
  113. ```
  114. > [!warning]
  115. > This installs the **skill only** — no slash commands beyond the ones mirrored as sub-skills, no review agents, no MCP gates, no hooks. For the full system (MCP quality gates, review agents, design memory), use the [installer above](#cli--recommended-cross-harness-installs-the-whole-system).
  116. Works with any agent that supports the [Agent Skills](https://skills.sh) spec. Each agent gets a pre-built mirror under a dedicated folder (`.codex/`, `.cursor/`, `.gemini/`, `.opencode/`, `.agents/`). The main `ui-craft` skill lands as a peer skill; each slash command is materialized as its own sub-skill in non-Claude harnesses (other agents trigger them by intent: "audit my UI", "polish this page").
  117. > [!note]
  118. > **Using `npx skills add -g` with Claude Code?** The skills CLI installs global skills to `~/.agents/skills`, but Claude Code reads `~/.claude/skills` ([vercel-labs/skills#693](https://github.com/vercel-labs/skills/issues/693)). If the skill isn't picked up, use the CLI or plugin install above, install per-project (drop `-g`), or symlink it:
  119. > ```bash
  120. > ln -s ~/.agents/skills/ui-craft ~/.claude/skills/ui-craft
  121. > ```
  122. ### Other ways
  123. ```bash
  124. # Clone
  125. git clone https://github.com/educlopez/ui-craft.git ~/.skills/ui-craft
  126. # Git submodule
  127. git submodule add https://github.com/educlopez/ui-craft.git .skills/ui-craft
  128. ```
  129. ## CLI
  130. The `ui-craft` binary is a single static Go binary (see [Install](#install) above for the recommended install script, plus Homebrew/Scoop alternatives). It is the lifecycle and cross-harness wiring core for the system.
  131. Run `ui-craft` with no arguments to open the **interactive hub** — a full-screen menu with an async update check that routes into install, upgrade, backups, and uninstall. Every subcommand below also works directly for scripting/CI.
  132. ### Commands
  133. | Command | Does |
  134. |---------|------|
  135. | `ui-craft` *(no subcommand)* | Open the interactive TUI hub: welcome menu + update check → Start installation · Upgrade · Manage backups · Managed uninstall. |
  136. | `ui-craft install` | Detect harnesses, à-la-carte component selection, write configs. |
  137. | `ui-craft update [harness]` | Re-apply all installed components at the new embedded version. |
  138. | `ui-craft update [harness] --component <name>` | Re-apply one component only. |
  139. | `ui-craft uninstall [harness]` | Remove managed blocks and wired components. |
  140. | `ui-craft doctor` | Health check — verifies each harness install is coherent. |
  141. | `ui-craft backup` | Snapshot all harness configs without installing. |
  142. | `ui-craft backup list` | List existing snapshots. |
  143. | `ui-craft backup pin <id>` / `unpin <id>` | Protect or unprotect a snapshot from retention cleanup. |
  144. | `ui-craft rollback [harness]` | Restore latest backup for a harness. |
  145. | `ui-craft self-update` | Upgrade binary to latest GitHub release (or prints the correct package-manager command when installed via Homebrew/Scoop). |
  146. | `ui-craft version` | Print the binary version. |
  147. | `ui-craft version --json` | Print `{ "version": "…" }`; there is no separate mirror-version field. |
  148. | `ui-craft version --check-parity` | Verify the Claude Code install matches the expected surface. |
  149. ### Key flags for `install`
  150. | Flag | Effect |
  151. |------|--------|
  152. | `--harness <name>` | Target a specific harness (`cursor`, `codex`, `gemini`, `opencode`) instead of auto-detecting. |
  153. | `--components <list>` | Comma-separated components to install (`skill-commands`, `mcp-gates`, `review-agents`, `design-memory`). |
  154. | `--dry-run` | Preview all planned writes without touching any file. |
  155. | `--yes` | Non-interactive — skip TUI prompts and apply defaults. |
  156. ### Scripting flags (global)
  157. | Flag | Effect |
  158. |------|--------|
  159. | `--json` | Machine-readable JSON output. Implies non-interactive. |
  160. | `--quiet` | Suppress non-essential output; print only errors and a final one-line outcome. |
  161. ### Safety
  162. Every install snapshots existing configs to `~/.ui-craft/backups/` (tar.gz, SHA-256 deduped) before writing. Any mid-plan failure rolls back the whole plan. `rollback [harness]` restores from the latest snapshot at any time. State is persisted to `~/.ui-craft/state.json` so `update` can replay your choices at the new version without re-prompting.
  163. ## Discovery phase
  164. Before building anything, the skill analyzes your project for existing design decisions — CSS variables, Tailwind config, font imports, component themes. If your project already has a design system, it respects it. If not, it asks 4 quick questions (style, accent color, font, optional animation stack) so it never defaults to generic blue/Inter.
  165. ## Knobs
  166. Three numeric knobs (1-10) that the skill asks about during Discovery. They change behavior, not just tone.
  167. | Knob | 1 | 10 |
  168. |------|---|----|
  169. | **CRAFT_LEVEL** (default 7) | ships fast, skips Polish Pass | pixel-perfect, compound details applied |
  170. | **MOTION_INTENSITY** (default 5) | hover states only | scroll-linked, page transitions, magnetic cursor |
  171. | **VISUAL_DENSITY** (default 5) | whitespace-heavy editorial | dashboard-dense |
  172. At `MOTION_INTENSITY 8+` the skill loads [`references/stack.md`](skills/ui-craft/references/stack.md) only if the user opts into Motion / GSAP / Three.js during Discovery.
  173. ## Style variants
  174. Three opt-in sibling skills that pre-commit to a style and lock the knobs to matching values. Agents pick them when the user mentions a specific aesthetic or product reference.
  175. | Variant | Triggers on | Knobs locked | Style anchors |
  176. |---------|-------------|--------------|---------------|
  177. | `ui-craft-minimal` | "minimal", "Linear-like", "Notion-like", "whitespace-heavy" | CRAFT=8 / MOTION=3 / DENSITY=2 | Monochrome + one accent, Inter/Geist, hairline borders |
  178. | `ui-craft-editorial` | "editorial", "magazine", "Medium-like", "Substack-like", "long-form" | CRAFT=9 / MOTION=4 / DENSITY=3 | Serif display + humanist body, wide reading column, OpenType |
  179. | `ui-craft-dense-dashboard` | "dashboard", "admin panel", "Bloomberg-like", "Retool-like" | CRAFT=7 / MOTION=3 / DENSITY=9 | IBM Plex + mono numbers, semantic palette, 4/8px grid |
  180. Each variant defers to the main `ui-craft` skill for base rules and references — it only overrides knob defaults and adds style-specific guidance.
  181. ### Style presets
  182. For playful and brutalist aesthetics (Clay / Gumroad / Duolingo / Arc-playful, Nothing-phone / Swiss-print / brutalist), see `examples/presets/playful.md` and `examples/presets/brutalist.md`. The main `ui-craft` skill applies these preset knob values + style overrides on top of the base rules when the user asks for those aesthetics.
  183. ## Slash commands
  184. 25 commands. They are **not a flat list** — every one belongs to a rung, and the rung tells you what it costs you before you read what it does.
  185. **Front door — unsure where you are:**
  186. | Command | Does |
  187. |---------|------|
  188. | `/ui-craft:start` | **Run this first.** Reads the project (framework, tokens, brief, spec, existing UI), reports which rung you are on, and names the one command worth running next. Read-only — no code changes. |
  189. ### Rung 1 · Direct — one focused pass, session-local
  190. **Build a surface:**
  191. | Command | Does | Next step |
  192. |---------|------|-----------|
  193. | `/ui-craft:craft` | **One-shot surface build.** Outcome recipe pipeline — Craft Read + variance + signature bet → named composition → theme → build order → acceptance bar. Surfaces: `dashboard`, `landing`, `auth`; portfolios use the landing recipe at variance 8. | `/finalize` |
  194. | `/ui-craft:shape` | **Wireframe-first.** ASCII layout + content inventory + state list + open questions before any JSX. Run when starting a new screen. | `/craft` |
  195. | `/ui-craft:redesign` | **Redesign without regression.** Audits the existing surface first, classifies what to preserve (brand, IA/SEO, content, conversion paths), picks refresh/reskin/rebuild scope, then modernizes. | `/critique` |
  196. **Adjust one dimension:**
  197. | Command | Does | Next step |
  198. |---------|------|-----------|
  199. | `/ui-craft:animate` | Add / fix motion. Honors `MOTION_INTENSITY` + chosen stack. | `/polish` |
  200. | `/ui-craft:adapt` | Responsive pass — mobile, tablet, desktop, touch, safe areas. | `/audit` |
  201. | `/ui-craft:typeset` | Typography pass — fonts, scale, tracking, micro-typography. | `/polish` |
  202. | `/ui-craft:colorize` | Introduce color strategically — one accent, 3–5 placements, no decoration. | `/tokens` |
  203. | `/ui-craft:clarify` | UX copy — button labels, error messages, empty states, CTAs. | `/critique` |
  204. | `/ui-craft:extract` | Pull repeated patterns into shared components and tokens. | `/tokens` |
  205. | `/ui-craft:distill` | Strip to essence. Cut every section that doesn't earn its space. Absorbs visual-weight reduction (softer type, less motion). | `/polish` |
  206. | `/ui-craft:delight` | Add purposeful micro-interactions — copy first, animation last. | `/finalize` |
  207. | `/ui-craft:polish` | Final pass — the compound details that turn "done" into "crafted". | `/finalize` |
  208. | `/ui-craft:bolder` | Raise DESIGN_VARIANCE and motion amplitude — stronger composition, type, and signature without a full rebuild. | `/critique` |
  209. | `/ui-craft:quieter` | Lower variance and motion — more restrained grids, type, and color. Honors `prefers-reduced-motion`. | `/critique` |
  210. **Review a surface:**
  211. | Command | Does | Next step |
  212. |---------|------|-----------|
  213. | `/ui-craft:heuristic` | **Signature move.** Scored critique — Nielsen 10 + 6 design laws + persona walkthroughs. Markdown scorecard with impact tags. No code changes. | fix, then `/finalize` |
  214. | `/ui-craft:critique` | UX — hierarchy, clarity, anti-slop. No code changes. | `/polish` |
  215. | `/ui-craft:audit` | Technical — a11y, performance, responsive. Prioritized findings table. | `/harden` |
  216. | `/ui-craft:unhappy` | State-first pass — design every non-happy state (idle/loading/empty/error/partial/conflict/offline) before the happy path. | `/harden` |
  217. | `/ui-craft:harden` | Production readiness — loading/empty/error states, i18n, offline, edge cases. | `/finalize` |
  218. ### Rung 2 · Persist — written once, read by every future session
  219. | Command | Does | Next step |
  220. |---------|------|-----------|
  221. | `/ui-craft:brief` | Write or update the project's durable design brief at `.ui-craft/brief.md` — 5 required sections + principles workshop. Run before any net-new project. | `/tokens` |
  222. | `/ui-craft:tokens` | Audit or establish the 3-layer token spine (primitive → semantic → component). Light and dark both intentionally crafted, not just inverted. | `/craft` |
  223. | `/ui-craft:remember` | Record a learned design constraint into `.ui-craft/brief.md` — corrections that should persist across sessions. | keep working |
  224. ### Rung 3 · Enforce — wired once into review or CI
  225. | Command | Does | Next step |
  226. |---------|------|-----------|
  227. | `/ui-craft:finalize` | Pre-ship gate. Runs the detector + brief/token check + the 10-pass finish bar + feedback hierarchy filter. Output only — no auto-fix. | ship |
  228. The rest of rung 3 is not commands: the two review [agents](#agents), the MCP quality gates, the composite score, and `ui-craft-detect` in CI.
  229. ### Express lane
  230. | Command | Does | Next step |
  231. |---------|------|-----------|
  232. | `/ui-craft:sddesign` | **Full spec-driven pipeline.** brief → tokens → shape → craft → converge → ship. Writes `.ui-craft/spec.md`. Walks rungs 1 to 3 in one run — reach for it when a surface is big enough to deserve a spec. | ship |
  233. ## Rung 0 in practice — you ask, it routes
  234. There is no mode enum to learn. At rung 0 you describe the task and the skill's routing table decides which references to load and which pass to run.
  235. | You say | It runs |
  236. |---------|---------|
  237. | "Build a pricing page" | A build pass — layout, typography, color, spacing, a11y and responsive decided together, not one at a time |
  238. | "Add an entrance to this modal" | A motion pass — the right easing, duration and origin point |
  239. | "Review this component" | A review pass — generic AI patterns, a11y gaps, missed details |
  240. | "Polish this dashboard" | A polish pass — the twenty small things that turn "done" into "crafted" |
  241. Climb to rung 1 when you would rather name the pass yourself.
  242. ## 32 domain references
  243. | Domain | Covers |
  244. |--------|--------|
  245. | Craft intent | Craft Read, DESIGN_VARIANCE knob, signature bets, product + marketing build patterns, accent rotation when no brand. **Load before `/craft` or any full-surface build** |
  246. | Dashboard recipe | Outcome blueprint: 3 named compositions (Overview / Command / Analytics), exact shell spec, build order, shippable acceptance bar. Run via `/craft dashboard` |
  247. | Landing recipe | Marketing page compositions (product-forward / message-forward / proof-forward), section grammar, CTA hierarchy, acceptance bar. Run via `/craft landing` |
  248. | Auth recipe | Sign-in/sign-up compositions (split panel / centered card), form contract, trust signals, acceptance bar. Run via `/craft auth` |
  249. | Theme presets | 4 named production token stacks (Graphite, Porcelain, Carbon, Signal) — full OKLCH color, type, radius, shadow, motion; light + dark both intentional |
  250. | Motion | Decision ladder, duration + easing token scales, interaction rules, choreography, motion budget, reduced-motion contract. Rendering performance (compositor, FLIP, scroll timelines, will-change lifecycle) |
  251. | Layout | Spacing systems, optical alignment, layered shadows, visual hierarchy |
  252. | Typography | `text-wrap: balance`, tabular-nums, font scale, curly quotes |
  253. | Color | OKLCH, design tokens, dark mode, APCA contrast |
  254. | Accessibility | WAI-ARIA, keyboard nav, focus management, touch targets |
  255. | Modern CSS | View Transitions, Anchor Positioning, Popover, `<dialog>`, `interpolate-size`, `color-mix()`, scroll-driven, container queries |
  256. | Responsive | Fluid sizing, mobile-first, touch zones, safe areas |
  257. | Sound | Web Audio API, feedback sounds, appropriateness matrix |
  258. | UX Copy | Voice / tone matrix, reading level, terminology, locale-aware strings, inclusive language, error/empty/CTA tactics |
  259. | UI Review | Systematic critique methodology, anti-slop detection, Polish Pass |
  260. | Dashboard | Signal-to-noise hierarchy (hero / supporting / context / deep-dive), sidebar, metric cards, data tables |
  261. | Inspiration | Pattern archetypes from observed mature SaaS — hero archetypes, signature details by pattern type, what mature interfaces never do, reference token values |
  262. | Brief | Durable design brief format — product purpose, primary user, 3-5 ranked principles, success metric, out of scope. Persists across sessions at `.ui-craft/brief.md` |
  263. | Tokens | 3-layer token spine (primitive → semantic → component). Both modes intentional. 7 required categories with cross-refs |
  264. | Finish bar | 10-pass finishing protocol with measurable criteria. Hierarchy / type system / surface stack / spacing rhythm / iconography / states / motion / microcopy / pixel honesty / data formatting |
  265. | Principles catalog | 42 example principles across 8 product categories, seed material for the `/brief` workshop |
  266. | Stack | Motion, GSAP, Three.js — decision tree, patterns, perf gotchas, anti-patterns (opt-in) |
  267. | Heuristics | Nielsen's 10 + Fitts / Hick / Doherty / Cleveland-McGill / Miller / Tesler with 1-5 scoring rubric and impact framing |
  268. | Personas | 5 archetypes (first-timer, power user, low-bandwidth, screen-reader, one-thumb) with walkthrough checklists |
  269. | State design | Idle / loading / empty / error / partial / conflict / offline — design the unhappy path first |
  270. | Data viz | Cleveland-McGill perceptual hierarchy, chart selection matrix, ColorBrewer + Okabe-Ito palettes, direct labeling, Tufte |
  271. | AI / chat surfaces | Streaming contract, 7-state model, tool traces, citations, feedback affordances, generative UI, conversation layout |
  272. | Forms | Validation timing, progressive disclosure, multi-step wizards, autosave, optimistic submit, field-specific patterns |
  273. | Composition spec | `.ui-craft/spec.md` format — per-surface composition choice, layout skeleton, component inventory, state lattice, acceptance bar. Written by `/shape` Step 6, consumed by `/sddesign` and `/craft`. |
  274. ## Agents
  275. Two read-only Claude Code plugin agents form the ui-craft **parallel verify team**. They complement the slash commands — they do not replace them.
  276. | Agent | Invocation | Does |
  277. |-------|-----------|------|
  278. | **design-reviewer** | `ui-craft:design-reviewer` | Adversarial design critique — loads review rules, anti-slop signals, and Nielsen/design-law heuristics. Returns severity-tagged findings (Critical / Warning / Suggestion, `file:line`). No edits. |
  279. | **a11y-auditor** | `ui-craft:a11y-auditor` | Accessibility audit — keyboard, focus-visible, APCA contrast, ARIA, touch targets, reduced-motion. Returns severity-tagged findings. No edits. |
  280. Both agents are **read-only** (tools: Read, Grep, Glob) and run in a **fresh context**, making them suitable for dedicated review passes and PR audits where you want independent judgment uncontaminated by the build session.
  281. ### Parallel verify team
  282. Delegate both agents simultaneously on the same diff or file for a full design + a11y sweep in one pass:
  283. > Delegate `ui-craft:design-reviewer` and `ui-craft:a11y-auditor` together on [target]. Run both simultaneously. Each returns an independent severity-tagged findings table.
  284. **When to use agents vs. commands:**
  285. - **Agents** — fresh context, parallel, read-only. Best for final review passes, PR audits, and CI-style verification. Invoke as `ui-craft:design-reviewer` / `ui-craft:a11y-auditor`.
  286. - **Commands** (`/critique`, `/audit`) — inline in the caller's context, sequential. Best for interactive build sessions where you want a quick lens mid-work.
  287. ## When to use what
  288. UI Craft surfaces the same craft knowledge five ways. They don't compete — each fits a different moment. The two axes that decide: **does it write code?** and **is it judgment or a deterministic check?**
  289. | Surface | What it is | Reach for it when | Writes code? | Judgment / deterministic | Runs |
  290. |---------|------------|-------------------|:------------:|--------------------------|------|
  291. | **The skill** (passive) | Always-on design knowledge + anti-slop, triggered by intent | You're building or editing any UI — the default | ✅ | Judgment | Inline, every harness |
  292. | **Slash commands** | Focused single-lens passes (`/craft`, `/shape`, `/polish`, `/heuristic`, `/finalize`, …) | You want one specific pass, mid-work | Build/transform ✅ · review passes ❌ | Judgment | Inline, your session |
  293. | **Agents** (`design-reviewer`, `a11y-auditor`) | Read-only verify team, fresh context, parallel | Final review / PR audit — you want independent judgment uncontaminated by the build session | ❌ | Judgment | Claude Code |
  294. | **MCP tools** (`check_anti_slop`, `tokens_lint`, `acceptance_bar`, `score_ui`) | Deterministic checks an agent calls | A programmatic gate inside any MCP client, or a reproducible score | ❌ | Deterministic | MCP client / CI |
  295. | **CLI** (`ui-craft` binary, `ui-craft-detect`, `scripts/eval.mjs`) | Installer + zero-dep scanners + UICraftScore | Install/update the system across harnesses; run quality gates in CI or git hooks | ❌ | Deterministic | Terminal / CI |
  296. **The short version:** *taste that writes code* → the skill + commands. *Independent review, no edits* → the agents. *A check that must be identical every run* → MCP or the CLI. New to it or unsure? Run `/start` and it picks for you.
  297. ## Framework agnostic
  298. The skill detects your project's styling approach and adapts:
  299. - **Tailwind CSS** — uses utility classes, maps design rules to Tailwind equivalents
  300. - **CSS Modules** — writes scoped `.module.css` files
  301. - **styled-components / Emotion** — uses tagged templates
  302. - **Vanilla CSS** — uses custom properties and modern features
  303. - **SFC styles** (Vue, Svelte, Astro) — writes in `<style>` blocks
  304. ## Anti-slop
  305. The skill actively rejects patterns that scream "AI made this":
  306. - ~~Purple-cyan gradients~~
  307. - ~~Glassmorphism with neon accents~~
  308. - ~~Identical card grids~~
  309. - ~~Bounce and elastic easing~~
  310. - ~~Glow effects as affordances~~
  311. - ~~Colored accent borders on cards~~
  312. - ~~ALL CAPS headings~~
  313. - ~~Uniform border-radius everywhere~~
  314. - ~~Emoji as icons~~
  315. - ~~Background gradient blobs~~
  316. - ~~Bento grid abuse~~
  317. - ~~Stagger-animate everything on load~~
  318. - ~~Star ratings on testimonials~~
  319. - ~~Generic CTAs ("Learn more", "Click here")~~
  320. - ~~Walls of text on landing pages~~
  321. - ~~Pure black (#000) text~~
  322. ## Canonical pipeline
  323. Once the spine is in place, the workflow is:
  324. ```
  325. Discovery → /brief → /tokens → build → /finalize → ship
  326. ```
  327. The brief and tokens land as durable artifacts at `.ui-craft/brief.md` and the project's preferred token destination — they survive across sessions and anchor every subsequent design decision. Build proceeds with full reference loading via the routing table. `/finalize` runs the 10-pass finish bar before merge, gated on the brief existing.
  328. ## Project structure
  329. ```
  330. ui-craft/
  331. ├── agents/ # 2 Claude Code plugin agents (auto-discovered)
  332. │ ├── design-reviewer.md # Adversarial design critic — read-only, severity-tagged output
  333. │ └── a11y-auditor.md # Accessibility auditor — read-only, severity-tagged output
  334. ├── skills/
  335. │ ├── ui-craft/ # Main skill
  336. │ │ ├── SKILL.md # Slim entry — knobs, discovery, anti-slop, routing
  337. │ │ └── references/ # 32 domain references (accessibility, motion, layout,
  338. │ │ # typography, color, modern-css, responsive,
  339. │ │ # sound, copy, review, dashboard, inspiration, stack,
  340. │ │ # heuristics, personas, state-design, dataviz,
  341. │ │ # ai-chat, forms, brief, tokens,
  342. │ │ # finish-bar, principles-catalog, spec, agents)
  343. │ ├── ui-craft-minimal/ # Variant — Linear/Notion aesthetic
  344. │ ├── ui-craft-editorial/ # Variant — Medium/Substack aesthetic
  345. │ └── ui-craft-dense-dashboard/ # Variant — Bloomberg/Retool aesthetic
  346. ├── commands/ # 25 Claude Code slash commands (source of truth)
  347. ├── examples/
  348. │ ├── animation-storyboard.md # Multi-stage animation pattern template
  349. │ └── presets/
  350. │ ├── playful.md # Clay / Gumroad / Duolingo / Arc aesthetic preset
  351. │ └── brutalist.md # Swiss print / Nothing / terminal aesthetic preset
  352. ├── evals/ # Eval query sets for description optimizer
  353. │ └── presets/ # Playful + brutalist eval JSONs (reference material)
  354. ├── scripts/
  355. │ ├── detect.mjs # ui-craft-detect CLI (also shipped on npm)
  356. │ └── validate.mjs # Manifest + link checker
  357. ├── .codex/skills/ # harness mirror for `npx skills add` / submodule installs
  358. ├── .cursor/skills/ # harness mirror
  359. ├── .gemini/skills/ # harness mirror
  360. ├── .opencode/skills/ # harness mirror
  361. ├── .agents/skills/ # harness mirror (generic agent-skills spec)
  362. ├── cli/assets/<harness>/ # hand-authored per-harness assets the CLI embeds + installs
  363. ├── .github/workflows/
  364. │ └── validate.yml # Runs validator on PR + push
  365. ├── README.md
  366. ├── CONTRIBUTING.md
  367. ├── LICENSE
  368. └── VERSIONS.md
  369. ```
  370. ## Anti-slop detection
  371. [![npm version](https://img.shields.io/npm/v/ui-craft-detect?style=flat-square&label=ui-craft-detect)](https://www.npmjs.com/package/ui-craft-detect)
  372. Scan a codebase for common AI-generated UI anti-patterns — 43 rules covering AI slop (`transition: all`, bounce easing, purple gradients, ALL CAPS headings), dark patterns (confirmshaming, destructive actions without confirmation), a11y (icon-only buttons without labels, modal-without-`<dialog>`, `outline: none` without `:focus-visible` replacement, streaming without `aria-live`, heading-level skips), forms (placeholder-as-label, missing `autocomplete`), auth tells (caps "OR" dividers, full-bleed saturated brand panels), marketing copy tells (eyebrow floods, scroll cues, numbered section eyebrows, duplicate CTA intent, em-dash floods), perf (images without dimensions → CLS), tables (no overflow handling on mobile), dataviz (categorical rainbow palettes), state design (data fetching without empty/error branches), and placeholder copy shipped to prod (`Lorem ipsum`, `TODO`, `John Doe`). Zero dependencies, works out of the box.
  373. Published as a standalone CLI on npm — use it anywhere without cloning:
  374. ```bash
  375. npx ui-craft-detect ./src
  376. # or with JSON output:
  377. npx ui-craft-detect ./src --json
  378. ```
  379. Or from a clone of this repo:
  380. ```bash
  381. node scripts/detect.mjs ./src
  382. ```
  383. Exit code 0 when clean, 1 when findings — usable as a CI gate. Rules mirror the Anti-Slop Test in `skills/ui-craft/SKILL.md`.
  384. ### Diff-scoped scanning — `--scope`, `--base`, `--fail-on`
  385. Scope findings to what a branch actually changed, so CI only flags new anti-patterns instead of the entire pre-existing codebase.
  386. | Flag | Values | Default | What it does |
  387. |------|--------|---------|--------------|
  388. | `--scope` | `full` \| `files` \| `changed` | `full` | `full` scans everything (unchanged behavior). `files` reports all findings in any file touched vs the base ref. `changed` reports only findings whose line falls inside an actual diff hunk. |
  389. | `--base <ref>` | any git ref | merge-base of `HEAD` with the default branch | Overrides the comparison ref used for `--scope files`/`changed`. |
  390. | `--fail-on` | `none` \| `warning` \| `error` | `error` | Exit-code gate, evaluated on the scope-filtered findings only. `none` is always advisory (exit 0). `warning` fails on any surviving finding. `error` fails only on critical findings (matches pre-existing default behavior). |
  391. ```bash
  392. # Local pre-commit-style gate: only fail on new critical issues in changed lines
  393. npx ui-craft-detect --scope changed --fail-on error
  394. # Compare against a specific ref instead of the default branch
  395. npx ui-craft-detect --scope changed --base origin/develop
  396. # Advisory mode — see scoped findings without affecting the exit code
  397. npx ui-craft-detect --scope files --fail-on none --json
  398. ```
  399. If git is unavailable, the directory isn't a git repository, or the base ref can't be resolved (e.g. shallow clone), the tool falls back to `--scope full` automatically and prints a note on stderr — it never crashes or silently drops findings.
  400. ### Live URL scanning
  401. Point the detector at a deployed page instead of source files:
  402. ```bash
  403. npx ui-craft-detect https://your-site.com
  404. npx ui-craft-detect https://your-site.com --json --fail-on none
  405. ```
  406. Two engines, picked automatically:
  407. - **puppeteer** (optional — `npm install puppeteer`) loads the page in headless Chromium and scans the JS-rendered DOM, so SPA/client-rendered markup is covered.
  408. - **fetch** (zero-dep fallback) scans the server-rendered HTML as delivered. No JS execution.
  409. Force one with `--engine puppeteer` or `--engine fetch`. Findings report the URL as the file and line numbers within the fetched HTML document. The core detector stays zero-dependency — puppeteer is resolved via dynamic import only when present.
  410. ### Agent edit-time hooks — `hooks` subcommand
  411. Pre-commit and CI catch problems after the fact. Agent hooks catch them **while the agent is still working** — the detector runs after every agent file edit and feeds findings straight back into the loop:
  412. ```bash
  413. npx ui-craft-detect hooks install # both harnesses
  414. npx ui-craft-detect hooks install --harness claude # just one
  415. npx ui-craft-detect hooks status
  416. npx ui-craft-detect hooks uninstall
  417. ```
  418. | Harness | Manifest | Mechanism |
  419. |---------|----------|-----------|
  420. | **Claude Code** | `.claude/settings.json` | `PostToolUse` hook (matcher `Edit\|Write\|MultiEdit`). On critical/major findings the hook exits 2, so the findings summary is fed back to the model as actionable feedback — the agent fixes the slop before finishing. |
  421. | **Cursor** | `.cursor/hooks.json` | `afterFileEdit` hook (schema version 1). Findings appear in Cursor's Hooks output channel. Committed to the repo, project hooks load for the whole team — including Cloud Agents. |
  422. Install is merge-safe and idempotent: existing manifest entries are always preserved, re-running is a no-op, and `uninstall` removes only the detector's own entries. The hook runner scans just the edited file, stays silent on clean edits and warn-level findings, and fails open on internal errors so a broken hook can never stall an agent.
  423. ### Pre-commit hooks — `init-hook` subcommand
  424. `ui-craft-detect` can install its own pre-commit hook with zero config.
  425. ```bash
  426. # Auto-detect (uses husky if present, else native .githooks)
  427. npx ui-craft-detect init-hook
  428. # Pick explicitly
  429. npx ui-craft-detect init-hook --native # .githooks/pre-commit (no deps)
  430. npx ui-craft-detect init-hook --husky # .husky/pre-commit (assumes husky)
  431. npx ui-craft-detect init-hook --github-action # .github/workflows/ui-craft-detect.yml (deprecated; use `ci install`)
  432. npx ui-craft-detect init-hook --all # all three
  433. npx ui-craft-detect init-hook --dry-run # preview without writing
  434. ```
  435. The native hook scans only staged file content (via `git show :path`), so working-tree noise is ignored. Skip ad-hoc with `git commit --no-verify`. This repo's own `.githooks/pre-commit` also auto-bumps `marketplace.json` CalVer on every commit.
  436. ### CI integration — `ci install` / `ci config` / `ci upgrade`
  437. One command sets up a full PR-feedback loop as a GitHub Action — no YAML to hand-write, no octokit dependency (it's all `gh api` under the hood):
  438. ```bash
  439. npx ui-craft-detect@latest ci install
  440. ```
  441. This writes `.github/workflows/ui-craft-detect.yml`, wired to:
  442. - **Sticky PR summary comment** — one comment per PR, created on first push and edited (not duplicated) on every subsequent push, matched via a hidden marker.
  443. - **Inline review comments** — findings are posted directly on the diff-visible lines that introduced them, scoped to `--scope changed` so pre-existing issues elsewhere in the file don't get flagged.
  444. - **Commit status** — on pushes to the default branch (no PR context), posts a `ui-craft-detect` status with error/warning counts.
  445. - **Minimal permissions** — `pull-requests: write` and `statuses: write` are each granted only for the steps that need them, with a one-line comment explaining why (same convention as this repo's own CodeQL workflow).
  446. By default the workflow scans `--scope changed --fail-on error` on pull requests (`--scope full` on default-branch pushes, since a push has no PR diff to scope against).
  447. Change settings anytime without reinstalling:
  448. ```bash
  449. npx ui-craft-detect ci config --scope files # widen scope to whole changed files
  450. npx ui-craft-detect ci config --fail-on warning # stricter gate
  451. npx ui-craft-detect ci config --comment false # disable the sticky PR comment
  452. npx ui-craft-detect ci config --inline-comments false # disable inline review comments
  453. npx ui-craft-detect ci config --status false # disable the commit status
  454. ```
  455. `ci config` reads and rewrites a small config marker embedded in the workflow file, so only the settings you pass change — the rest of the file (steps, permissions) is left untouched.
  456. Bump the workflow to the latest template version while keeping your settings:
  457. ```bash
  458. npx ui-craft-detect ci upgrade
  459. ```
  460. `ci upgrade` compares the embedded version marker against the installed CLI version; if there's drift, it regenerates the template body and preserves your `ci config` settings exactly. If you're already current, it's a no-op.
  461. `init-hook --github-action` still works (it's the same code path `ci install` wraps) but is deprecated in favor of `ci install`.
  462. The `--scope`/`--fail-on` flags used above aren't CI-only — they work as plain CLI flags for local pre-commit-style gating too (see [Diff-scoped scanning](#diff-scoped-scanning---scope---base---fail-on) above).
  463. ## Design-quality score
  464. **UICraftScore** is a deterministic 0-100 composite that turns three static-analysis signals into a single defensible grade. It gives you objective, reproducible design-quality evidence — not vibes.
  465. **Formula:**
  466. ```
  467. score = 100
  468. − (antiSlop_critical × 8) − (antiSlop_major × 4) − (antiSlop_warn × 1)
  469. − (token_findings × 2)
  470. − (a11y_critical × 8) − (a11y_major × 4)
  471. clamped [0, 100] · A ≥ 90 · B ≥ 80 · C ≥ 70 · D ≥ 60 · F < 60
  472. ```
  473. Three dimensions, each with its own subscore:
  474. | Dimension | Source | Penalty |
  475. |-----------|--------|---------|
  476. | **anti_slop** | 43 rules from `ui-craft-detect` | critical −8 · major −4 · warn −1 |
  477. | **token_discipline** | Raw hex / off-scale radius / spacing / z-index | −2 per finding (flat) |
  478. | **a11y** | 5 new static checks (no overlap with detect.mjs): `img-no-alt`, `non-semantic-interactive`, `positive-tabindex`, `aria-invalid-no-describedby`, `no-reduced-motion` | critical −8 · major −4 |
  479. The formula, weights, and grade bands are published in `evals/quality/score.mjs` (`WEIGHTS`, `GRADE_BANDS`). Hand-authored fixtures in `evals/quality/fixtures/` and bands in `evals/quality/baselines.json` form the regression gate.
  480. **Run the CLI benchmark:**
  481. ```bash
  482. # Score a single file
  483. node scripts/eval.mjs src/components/Hero.tsx
  484. # Score a directory
  485. node scripts/eval.mjs src/components/
  486. # Run the full regression gate (8 fixtures — slop vs. designer separation)
  487. node scripts/eval.mjs --baseline
  488. # JSON output (CI-friendly)
  489. node scripts/eval.mjs src/components/Hero.tsx --json
  490. # Fail if score below threshold (default 70)
  491. node scripts/eval.mjs src/components/Hero.tsx --threshold 80
  492. ```
  493. Exit codes: `0` clean / in-band · `1` below threshold or out of band · `2` arg error.
  494. **Score via MCP tool (`score_ui`):**
  495. The `score_ui` tool in the MCP server exposes the same scorer to any MCP-compatible client:
  496. ```json
  497. // Call score_ui with inline code:
  498. { "code": "<your tsx source>" }
  499. // Or with a file path:
  500. { "path": "src/components/Hero.tsx" }
  501. ```
  502. Returns `{ overall: { score, grade }, dimensions: { anti_slop, token_discipline, a11y }, version }` — the same envelope as the CLI `--json` output.
  503. See [`evals/README.md`](evals/README.md) for how to run the regression gate, add fixtures, and regen baselines after rule changes.
  504. ### UsabilityScore — the judged companion
  505. UICraftScore is deterministic, which also bounds it: static analysis can't see *experience* friction (a confusing flow, a missing undo, a 2-second save with no feedback). **UsabilityScore** covers that axis — a 0-100 score + grade rolled up from the `/heuristic` scorecard (Nielsen's 10 + 6 design laws):
  506. ```
  507. heuristic_base = round( ((mean(nielsen_scores) − 1) / 4) × 100 ) # 10 scores, each 1–5
  508. UsabilityScore = clamp( heuristic_base − 5 × (failed design laws) , 0 , 100 )
  509. Same bands as UICraftScore: A ≥ 90 · B ≥ 80 · C ≥ 70 · D ≥ 60 · F < 60
  510. ```
  511. It is **judged, not deterministic** — computed by the host agent from the rubric (zero deps, no API key, works in any harness), so it may vary run to run. **Gate CI on UICraftScore; use UsabilityScore for review depth.** The two render side by side in an *extended report* and are deliberately **never averaged** — that would hide which number is reproducible. Run it with `/heuristic <path>`; rubric + formula live in [`heuristics.md`](skills/ui-craft/references/heuristics.md).
  512. ## MCP Server
  513. [![npm version](https://img.shields.io/npm/v/ui-craft-mcp?style=flat-square&label=ui-craft-mcp)](https://www.npmjs.com/package/ui-craft-mcp)
  514. The `ui-craft-mcp` package exposes seven deterministic tools over the [Model Context Protocol](https://modelcontextprotocol.io/) (stdio transport). Works with Claude Desktop, Cursor, and any MCP-compatible client.
  515. **Boundary:** the MCP server is the **checks layer** — deterministic, rule-based, identical output for identical input. The `SKILL.md` is the **taste layer** — judgment, aesthetics, architectural decisions. These never overlap.
  516. | Tool | What it does |
  517. |------|-------------|
  518. | `route_task` | Routes a natural-language prompt to the references, commands and tools that cover it, plus the first move — pointers only, never rules |
  519. | `check_anti_slop` | 43-rule anti-slop scanner via `scan()` from `ui-craft-detect` — in-process, no subprocess |
  520. | `tokens_lint` | Off-system token detector: raw hex colors, non-scale radius/spacing px, magic z-index |
  521. | `acceptance_bar` | Acceptance checklist for a UI surface (`dashboard`, `landing`, `auth`, `generic`) — data only, no scoring |
  522. | `score_ui` | Composite UICraftScore (0-100 + grade + per-dim subscores) via `evals/quality/score.mjs` — all three dimensions in one call |
  523. | `fold_candidates` | Draws landing-fold composition classes, preferring ones the project has not spent |
  524. | `check_fold` | Renders a URL and reports what its fold actually is — screenshot, class, drift, invariants |
  525. **Why `route_task` exists:** the routing table in `SKILL.md` only fires when your words match our filenames. Ask for "an analytics panel" and nothing points at `recipe-dashboard.md`, because that file never says analytics. A synonym map fixes a vocabulary mismatch a table cannot, and recipes are indexed by what they *contain*, so "pricing block" reaches the landing recipe.
  526. **Quick start:**
  527. ```bash
  528. # Wire the manifest-pinned release into your project's .mcp.json:
  529. { "mcpServers": { "ui-craft": { "command": "npx", "args": ["-y", "ui-craft-mcp@0.9.1"] } } }
  530. ```
  531. See [`mcp/README.md`](mcp/README.md) for full install, tool docs, and the `acceptance-data.json` regen note.
  532. ## Maintaining harness assets
  533. The canonical skill content lives in `skills/` (main skill + variants) and `commands/` (the slash-command lenses). Two consumers ship that content:
  534. - **CLI (`ui-craft install`)** — per-harness assets are hand-authored under `cli/assets/<harness>/` (claude, cursor, codex, gemini, opencode) and compiled into the binary via `go:embed`. Command-capable harnesses (Claude Code, OpenCode) receive real `commands/*.md`; skills-only harnesses (Cursor, Codex, Gemini) receive each lens as a flat depth-1 peer skill. The embedded tree is also the uninstall manifest — cleanup removes exactly what it installed.
  535. - **`npx skills add` / git submodule** — the repo-root mirror dirs (`.codex/`, `.cursor/`, `.gemini/`, `.opencode/`, `.agents/`) serve those install paths.
  536. ### Canonical quality gate
  537. Before publishing or opening a PR, install the MCP development dependencies once with `npm ci --prefix mcp`, then run:
  538. ```bash
  539. pnpm verify
  540. ```
  541. This non-fail-fast gate runs distribution-contract checks, plugin/link validation, every mirror drift guard, detector and quality suites, MCP source and bundled smoke tests, plus Go tests, vet, and formatting. `pnpm verify:list` prints the suite IDs; a focused rerun can use `pnpm verify -- --suite=<id>`. Component versions and immutable launch specs live in the machine-readable [`distribution-manifest.json`](distribution-manifest.json).
  542. When you change a skill or command, edit the canonical source under `skills/` + `commands/` and then regenerate every copy:
  543. ```bash
  544. npm run sync # skills/ + commands/ → cli/assets/ + repo-root mirrors
  545. npm run check:mirrors # the drift guard CI runs (fails on any stale mirror)
  546. ```
  547. CI does not regenerate mirrors — `scripts/check-mirror-copies.mjs` only fails the build when one drifts, so run the sync before you push.
  548. ## Tuning skill descriptions
  549. Every skill's `description` field is the primary trigger mechanism. The `evals/` folder holds query sets for `skill-creator`'s description optimizer (`run_loop.py`), which evaluates and iterates descriptions against realistic should-trigger / should-not-trigger prompts. See `evals/README.md` for the commands and how to add new eval sets.
  550. ## Roadmap
  551. Where ui-craft is heading. Not commitments with dates — a public list of the directions we consider worth building, roughly ordered by how much they'd raise output quality. Feedback and PRs on any of these welcome.
  552. **Design-tool integration**
  553. - **Figma spec compliance** — read component specs (spacing, type, color, variants) via Figma's Dev Mode / REST API and score an implementation against them, the same way the detector scores anti-slop today. "Does the built component match the design?" becomes a deterministic gate instead of eyeball review.
  554. - **Design-token import** — pull a token set from Figma variables / Tokens Studio / a `design-tokens.json` and emit the project's 3-layer spine (`/tokens`) from it, instead of hand-transcribing values.
  555. **Detector**
  556. - **Computed-style checks for URL scans** — the URL engine currently scans rendered markup; the next layer is computed styles via the browser engine: real contrast ratios (not class-name heuristics), effective tap-target sizes, actual font fallback chains.
  557. - **Screenshot-diff regression (exploratory)** — likely as a thin integration over existing visual-regression tooling (Playwright snapshots / Chromatic-style diffs) rather than a bespoke engine.
  558. - **More harnesses for edit-time hooks** — `hooks install` covers Claude Code and Cursor today; extend to other agents as their hook mechanisms stabilize.
  559. **Skill & pipeline**
  560. - **Reference-board step** — optional pre-build step that generates or collects visual references (mood board, type specimens, palette candidates) before the Craft Read, for briefs where the direction is genuinely open.
  561. - **Multi-page consistency** — today's recipes reason about one surface at a time; a site-level pass would enforce shared rhythm, type scale, and CTA vocabulary across pages.
  562. - **UsabilityScore trend tracking** — persist `/heuristic` and UICraftScore results per commit so quality is a curve you watch, not a snapshot.
  563. **Evals**
  564. - **Automated blind-build harness** — run the `evals/craft-quality/PROMPTS.md` tracks through an agent automatically and score the output, turning today's manual auditor pass into a repeatable regression suite.
  565. Have a strong opinion on priority, or something missing? [Open an issue](https://github.com/educlopez/ui-craft/issues).
  566. ## Contributing
  567. Spotted a new AI-generated pattern that should be in the anti-slop list? Have a craft rule from a product you admire? Want to add a new reference domain? PRs and issues welcome.
  568. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding rules, improving references, or proposing new domains.
  569. ## Author
  570. [Eduardo Calvo](https://x.com/educalvolpz)
  571. ## License
  572. [MIT](LICENSE) — use it however you want.
scripts/install.ps1 · Bundled script · 197 lines · 2 findings marked
  1. #Requires -Version 5.1
  2. <#
  3. .SYNOPSIS
  4. Install the ui-craft CLI binary on Windows.
  5. .DESCRIPTION
  6. Detects OS architecture, downloads the latest (or a pinned) ui-craft
  7. release from GitHub, verifies its sha256 checksum against the release's
  8. checksums.txt, and installs the binary into a per-user directory that is
  9. added to the user PATH.
  10. .EXAMPLE
  11. irm https://ui-craft.smoothui.dev/install.ps1 | iex
  12. .EXAMPLE
  13. $env:UI_CRAFT_VERSION = "v0.36.0"
  14. irm https://ui-craft.smoothui.dev/install.ps1 | iex
  15. #>
  16. [CmdletBinding()]
  17. param(
  18. [string]$Version = $env:UI_CRAFT_VERSION
  19. )
  20. $ErrorActionPreference = "Stop"
  21. $ProgressPreference = 'SilentlyContinue'
  22. [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
  23. $Repo = "educlopez/ui-craft"
  24. $BinaryName = "ui-craft.exe"
  25. # Undocumented overrides for offline/e2e testing only — not part of the
  26. # public interface, do not surface these in help text or README.
  27. $UiCraftBaseUrl = if ($env:UI_CRAFT_BASE_URL) { $env:UI_CRAFT_BASE_URL } else { "https://github.com/$Repo/releases/download" }
  28. $UiCraftApiUrl = if ($env:UI_CRAFT_API_URL) { $env:UI_CRAFT_API_URL } else { "https://api.github.com/repos/$Repo/releases/latest" }
  29. function Write-Info($Message) {
  30. Write-Host "[info] $Message" -ForegroundColor Cyan
  31. }
  32. function Write-Warn($Message) {
  33. Write-Host "[warn] $Message" -ForegroundColor Yellow
  34. }
  35. function Write-ErrorAndExit($Message) {
  36. throw $Message
  37. }
  38. # Fatals raised before the main try/finally (arch/version validation) land
  39. # here: print them cleanly and exit non-zero instead of dumping a raw
  40. # exception. Fatals inside the main block are handled by its own catch.
  41. trap {
  42. Write-Host "[error] $($_.Exception.Message)" -ForegroundColor Red
  43. exit 1
  44. }
  45. # --- architecture detection ------------------------------------------------
  46. $archRaw = $env:PROCESSOR_ARCHITEW6432
  47. if (-not $archRaw) {
  48. $archRaw = $env:PROCESSOR_ARCHITECTURE
  49. }
  50. switch ($archRaw) {
  51. "AMD64" { $arch = "amd64" }
  52. "ARM64" { $arch = "arm64" }
  53. default {
  54. Write-ErrorAndExit "Unsupported architecture '$archRaw'. Download a binary manually from https://github.com/$Repo/releases"
  55. }
  56. }
  57. # --- version resolution -----------------------------------------------------
  58. if (-not $Version) {
  59. Write-Info "Looking up the latest release..."
  60. try {
  61. $latest = Invoke-RestMethod -Uri $UiCraftApiUrl -UseBasicParsing
  62. } catch {
  63. Write-ErrorAndExit "Failed to query the GitHub releases API: $_"
  64. }
  65. $tag = $latest.tag_name
  66. if (-not $tag) {
  67. Write-ErrorAndExit "Could not parse the latest release tag."
  68. }
  69. } else {
  70. $tag = $Version
  71. }
  72. if ($tag -match "^v") {
  73. $archiveVersion = $tag.Substring(1)
  74. } else {
  75. $archiveVersion = $tag
  76. $tag = "v$tag"
  77. }
  78. Write-Info "Installing ui-craft $tag (windows/$arch)"
  79. $archiveName = "ui-craft_${archiveVersion}_windows_${arch}.zip"
  80. $baseUrl = "$UiCraftBaseUrl/$tag"
  81. # --- download ----------------------------------------------------------
  82. $tmpDir = Join-Path ([System.IO.Path]::GetTempPath()) ("ui-craft-install-" + [System.Guid]::NewGuid().ToString("N"))
  83. New-Item -ItemType Directory -Path $tmpDir -Force | Out-Null
  84. $exitCode = 0
  85. try {
  86. $archivePath = Join-Path $tmpDir $archiveName
  87. $checksumsPath = Join-Path $tmpDir "checksums.txt"
  88. Write-Info "Downloading $archiveName..."
  89. try {
  90. Invoke-WebRequest -Uri "$baseUrl/$archiveName" -OutFile $archivePath -UseBasicParsing
  91. } catch {
  92. Write-ErrorAndExit "Download failed. Check that $tag has a release asset for windows/$arch. $_"
  93. }
  94. try {
  95. Invoke-WebRequest -Uri "$baseUrl/checksums.txt" -OutFile $checksumsPath -UseBasicParsing
  96. } catch {
  97. Write-ErrorAndExit "Failed to download checksums.txt for verification: $_"
  98. }
  99. # --- verify ----------------------------------------------------------
  100. Write-Info "Verifying checksum..."
  101. $checksumPattern = "(?m)^([0-9a-fA-F]{64})\s+" + [regex]::Escape($archiveName) + "\s*$"
  102. $checksumMatches = [regex]::Matches((Get-Content -Path $checksumsPath -Raw), $checksumPattern)
  103. if ($checksumMatches.Count -eq 0) {
  104. Write-ErrorAndExit "No checksum entry found for $archiveName in checksums.txt."
  105. }
  106. if ($checksumMatches.Count -gt 1) {
  107. Write-ErrorAndExit "Multiple checksum entries found for $archiveName in checksums.txt."
  108. }
  109. $expectedSum = $checksumMatches[0].Groups[1].Value.ToLowerInvariant()
  110. $actualSum = (Get-FileHash -Path $archivePath -Algorithm SHA256).Hash.ToLowerInvariant()
  111. if ($expectedSum -ne $actualSum) {
  112. Write-ErrorAndExit "Checksum mismatch for ${archiveName}: expected $expectedSum, got $actualSum."
  113. }
  114. Write-Info "Checksum OK."
  115. # --- extract -----------------------------------------------------------
  116. $extractDir = Join-Path $tmpDir "extracted"
  117. Expand-Archive -Path $archivePath -DestinationPath $extractDir -Force
  118. $extractedBinary = Join-Path $extractDir $BinaryName
  119. if (-not (Test-Path $extractedBinary)) {
  120. Write-ErrorAndExit "Extracted archive did not contain $BinaryName."
  121. }
  122. # --- install -------------------------------------------------------
  123. $installDir = Join-Path $env:LOCALAPPDATA "ui-craft\bin"
  124. New-Item -ItemType Directory -Path $installDir -Force | Out-Null
  125. $installedBinary = Join-Path $installDir $BinaryName
  126. Copy-Item -Path $extractedBinary -Destination $installedBinary -Force
  127. # --- verify install ---------------------------------------------------
  128. try {
  129. & $installedBinary version | Out-Null
  130. } catch {
  131. Write-ErrorAndExit "Installed binary at $installedBinary did not run successfully: $_"
  132. }
  133. if ($LASTEXITCODE -ne 0) {
  134. Write-ErrorAndExit "Installed binary at $installedBinary did not run successfully (exit code $LASTEXITCODE)."
  135. }
  136. Write-Info "Installed ui-craft to $installedBinary"
  137. # --- PATH update (user scope) -------------------------------------------
  138. $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
  139. $pathEntries = @()
  140. if ($userPath) {
  141. $pathEntries = $userPath -split ";" | Where-Object { $_ -ne "" }
  142. }
  143. if ($pathEntries -notcontains $installDir) {
  144. $newPath = if ($userPath) { "$userPath;$installDir" } else { $installDir }
  145. [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
  146. Write-Warn "Added $installDir to your user PATH. Reopen your terminal for this to take effect."
  147. }
  148. Write-Host ""
  149. Write-Info "Run 'ui-craft' for the interactive hub, or 'ui-craft install' to wire your harnesses."
  150. Write-Info "Updates: 'ui-craft self-update'."
  151. } catch {
  152. Write-Host "[error] $($_.Exception.Message)" -ForegroundColor Red
  153. $exitCode = 1
  154. } finally {
  155. Remove-Item -Path $tmpDir -Recurse -Force -ErrorAction SilentlyContinue
  156. }
  157. exit $exitCode
scripts/install.sh · Bundled script · 222 lines · 3 findings marked
  1. #!/usr/bin/env bash
  2. # Install the ui-craft CLI binary for the current OS/arch.
  3. #
  4. # Usage:
  5. # curl -fsSL https://ui-craft.smoothui.dev/install | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 5 on GitHub
  6. # curl -fsSL https://ui-craft.smoothui.dev/install | bash -s -- --version v0.36.0
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 6 on GitHub
  7. #
  8. # Env overrides:
  9. # UI_CRAFT_VERSION release tag or version to install (e.g. v0.36.0 or 0.36.0)
  10. # UI_CRAFT_INSTALL_DIR directory to install the binary into
  11. #
  12. # Always downloads from GitHub Releases and verifies the sha256 against the
  13. # release's checksums.txt before installing. Never invokes sudo.
  14. set -euo pipefail
  15. REPO="educlopez/ui-craft"
  16. BINARY_NAME="ui-craft"
  17. VERSION="${UI_CRAFT_VERSION:-}"
  18. # Undocumented overrides for offline/e2e testing only — not part of the
  19. # public interface, do not surface these in --help or README.
  20. UI_CRAFT_BASE_URL="${UI_CRAFT_BASE_URL:-https://github.com/${REPO}/releases/download}"
  21. UI_CRAFT_API_URL="${UI_CRAFT_API_URL:-https://api.github.com/repos/${REPO}/releases/latest}"
  22. # Real GitHub URLs are pinned to https + TLS 1.2. Local fixture servers used
  23. # by e2e/installer/run-tests.sh serve plain http on 127.0.0.1, so relax the
  24. # pin only when a base-url override is in effect (test-only path).
  25. if [ "$UI_CRAFT_BASE_URL" = "https://github.com/${REPO}/releases/download" ]; then
  26. curl_tls_opts="--proto =https --tlsv1.2"
  27. else
  28. curl_tls_opts=""
  29. fi
  30. # --- arg parsing --------------------------------------------------------
  31. while [ "$#" -gt 0 ]; do
  32. case "$1" in
  33. --version)
  34. VERSION="${2:-}"
  35. shift 2
  36. ;;
  37. --version=*)
  38. VERSION="${1#*=}"
  39. shift
  40. ;;
  41. *)
  42. echo "unknown argument: $1" >&2
  43. exit 1
  44. ;;
  45. esac
  46. done
  47. # --- output helpers -------------------------------------------------------
  48. if [ -t 1 ]; then
  49. COLOR_RED=$'\033[31m'
  50. COLOR_YELLOW=$'\033[33m'
  51. COLOR_BLUE=$'\033[34m'
  52. COLOR_RESET=$'\033[0m'
  53. else
  54. COLOR_RED=""
  55. COLOR_YELLOW=""
  56. COLOR_BLUE=""
  57. COLOR_RESET=""
  58. fi
  59. info() { printf '%s[info]%s %s\n' "${COLOR_BLUE}" "${COLOR_RESET}" "$1"; }
  60. warn() { printf '%s[warn]%s %s\n' "${COLOR_YELLOW}" "${COLOR_RESET}" "$1" >&2; }
  61. err() { printf '%s[error]%s %s\n' "${COLOR_RED}" "${COLOR_RESET}" "$1" >&2; }
  62. fatal() {
  63. err "$1"
  64. exit 1
  65. }
  66. # --- OS / arch detection --------------------------------------------------
  67. uname_s="$(uname -s)"
  68. case "$uname_s" in
  69. Darwin) os="darwin" ;;
  70. Linux) os="linux" ;;
  71. MINGW* | MSYS* | CYGWIN*)
  72. fatal "Windows detected. Use scripts/install.ps1 instead: irm https://raw.githubusercontent.com/${REPO}/main/scripts/install.ps1 | iex"
  73. ;;
  74. *)
  75. fatal "Unsupported OS '${uname_s}'. Download a binary manually from https://github.com/${REPO}/releases"
  76. ;;
  77. esac
  78. uname_m="$(uname -m)"
  79. case "$uname_m" in
  80. x86_64 | amd64) arch="amd64" ;;
  81. arm64 | aarch64) arch="arm64" ;;
  82. *)
  83. fatal "Unsupported architecture '${uname_m}'. Download a binary manually from https://github.com/${REPO}/releases"
  84. ;;
  85. esac
  86. # --- checksum tool ---------------------------------------------------------
  87. if command -v sha256sum >/dev/null 2>&1; then
  88. sha256_cmd() { sha256sum "$1" | awk '{print $1}'; }
  89. elif command -v shasum >/dev/null 2>&1; then
  90. sha256_cmd() { shasum -a 256 "$1" | awk '{print $1}'; }
  91. else
  92. fatal "Neither sha256sum nor shasum found — cannot verify the download. Aborting."
  93. fi
  94. # --- version resolution ------------------------------------------------
  95. if [ -z "$VERSION" ]; then
  96. info "Looking up the latest release..."
  97. # The releases API allows 60 unauthenticated requests per hour per IP. That is generous
  98. # for one person and nothing at all behind shared egress — corporate NAT, a VPN, or a CI
  99. # runner — where the quota is spent by strangers and the install fails in under a second
  100. # with a 403. A token, when one is already in the environment, lifts it to 5000.
  101. auth_header=""
  102. if [ -n "${GITHUB_TOKEN:-}" ]; then
  103. auth_header="Authorization: Bearer ${GITHUB_TOKEN}"
  104. elif [ -n "${GH_TOKEN:-}" ]; then
  105. auth_header="Authorization: Bearer ${GH_TOKEN}"
  106. fi
  107. # shellcheck disable=SC2086 # curl_tls_opts is intentionally unquoted for word-splitting; contains no whitespace-bearing values
  108. if [ -n "$auth_header" ]; then
  109. # The header goes in over stdin (-H @-) rather than as an argument. A process's argv is
  110. # world-readable on Linux and visible to `ps` on macOS, so passing the token on the
  111. # command line exposes it to every other user on the machine for as long as the request
  112. # runs — and installers get run on shared boxes and build agents.
  113. latest_json="$(printf '%s\n' "$auth_header" | curl -fsSL $curl_tls_opts --connect-timeout 10 --max-time 60 -H @- "$UI_CRAFT_API_URL")" || latest_json=""
  114. else
  115. latest_json="$(curl -fsSL $curl_tls_opts --connect-timeout 10 --max-time 60 "$UI_CRAFT_API_URL")" || latest_json=""
  116. fi
  117. [ -n "$latest_json" ] \
  118. || fatal "Failed to query the GitHub releases API. This is usually a rate limit (60/hour per IP, shared on corporate networks and CI). Set GITHUB_TOKEN to raise it, or skip the lookup entirely with --version vX.Y.Z (or UI_CRAFT_VERSION)."
  119. tag="$(printf '%s' "$latest_json" | grep -m1 '"tag_name"' | sed -E 's/.*"tag_name": *"([^"]+)".*/\1/')"
  120. [ -n "$tag" ] || fatal "Could not parse the latest release tag."
  121. else
  122. tag="$VERSION"
  123. fi
  124. case "$tag" in
  125. v*) archive_version="${tag#v}" ;;
  126. *)
  127. archive_version="$tag"
  128. tag="v${tag}"
  129. ;;
  130. esac
  131. info "Installing ui-craft ${tag} (${os}/${arch})"
  132. archive_name="ui-craft_${archive_version}_${os}_${arch}.tar.gz"
  133. base_url="${UI_CRAFT_BASE_URL}/${tag}"
  134. # --- download --------------------------------------------------------------
  135. tmp_dir="$(mktemp -d)"
  136. cleanup() { rm -rf "$tmp_dir"; }
  137. trap cleanup EXIT
  138. info "Downloading ${archive_name}..."
  139. # shellcheck disable=SC2086 # curl_tls_opts is intentionally unquoted for word-splitting; contains no whitespace-bearing values
  140. curl -fsSL $curl_tls_opts --connect-timeout 10 --max-time 600 -o "${tmp_dir}/${archive_name}" \
  141. "${base_url}/${archive_name}" \
  142. || fatal "Download failed. Check that ${tag} has a release asset for ${os}/${arch}."
  143. # shellcheck disable=SC2086 # curl_tls_opts is intentionally unquoted for word-splitting; contains no whitespace-bearing values
  144. curl -fsSL $curl_tls_opts --connect-timeout 10 --max-time 60 -o "${tmp_dir}/checksums.txt" \
  145. "${base_url}/checksums.txt" \
  146. || fatal "Failed to download checksums.txt for verification."
  147. # --- verify ------------------------------------------------------------
  148. info "Verifying checksum..."
  149. expected_sum="$(grep " ${archive_name}\$" "${tmp_dir}/checksums.txt" | awk '{print $1}')"
  150. [ -n "$expected_sum" ] || fatal "No checksum entry found for ${archive_name} in checksums.txt."
  151. actual_sum="$(sha256_cmd "${tmp_dir}/${archive_name}")"
  152. if [ "$expected_sum" != "$actual_sum" ]; then
  153. fatal "Checksum mismatch for ${archive_name}: expected ${expected_sum}, got ${actual_sum}."
  154. fi
  155. info "Checksum OK."
  156. # --- extract -----------------------------------------------------------
  157. tar -xzf "${tmp_dir}/${archive_name}" -C "$tmp_dir" "$BINARY_NAME" \
  158. || fatal "Failed to extract ${BINARY_NAME} from ${archive_name}."
  159. # --- install dir ---------------------------------------------------------
  160. if [ -n "${UI_CRAFT_INSTALL_DIR:-}" ]; then
  161. install_dir="$UI_CRAFT_INSTALL_DIR"
  162. elif [ -w "/usr/local/bin" ]; then
  163. install_dir="/usr/local/bin"
  164. else
  165. install_dir="${HOME}/.local/bin"
  166. fi
  167. mkdir -p "$install_dir"
  168. install -m 0755 "${tmp_dir}/${BINARY_NAME}" "${install_dir}/${BINARY_NAME}" \
  169. || fatal "Failed to install the binary into ${install_dir}."
  170. # --- verify install ------------------------------------------------------
  171. if ! "${install_dir}/${BINARY_NAME}" version >/dev/null 2>&1; then
  172. fatal "Installed binary at ${install_dir}/${BINARY_NAME} did not run successfully."
  173. fi
  174. info "Installed ui-craft to ${install_dir}/${BINARY_NAME}"
  175. case ":${PATH}:" in
  176. *":${install_dir}:"*) ;;
  177. *)
  178. warn "${install_dir} is not on your PATH. Add this to your shell profile:"
  179. printf ' export PATH="%s:$PATH"\n' "$install_dir"
  180. ;;
  181. esac
  182. printf '\n'
  183. info "Run 'ui-craft' for the interactive hub, or 'ui-craft install' to wire your harnesses."
  184. info "Updates: 'ui-craft self-update'."

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.