📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,82 @@
|
||||
# Setup
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Node 18+** and **Python 3.x**
|
||||
- **Claude Code** with plugins enabled (run `/plugin` once to enable)
|
||||
|
||||
## 1. One-shot setup
|
||||
|
||||
```bash
|
||||
./scripts/setup.sh
|
||||
```
|
||||
|
||||
This installs the audit dependencies (Playwright + Chromium) and the `ui-ux-pro-max` skill,
|
||||
then prints the two steps that must happen inside Claude Code.
|
||||
|
||||
## 2. Install the taste plugin (inside Claude Code)
|
||||
|
||||
```
|
||||
/plugin install frontend-design@anthropics/claude-code
|
||||
```
|
||||
|
||||
## 3. Approve the MCP servers
|
||||
|
||||
Open Claude Code in this directory. It reads `.mcp.json` and prompts you to approve the project
|
||||
MCP servers (**playwright**, **chrome-devtools**, **shadcn**). Approve them. `.claude/settings.json`
|
||||
already sets `enableAllProjectMcpServers: true`, so they load on start. Verify with `/mcp`.
|
||||
|
||||
That's it — `CLAUDE.md` defines the design loop and loads automatically.
|
||||
|
||||
## Verify it works
|
||||
|
||||
```
|
||||
> /design-plan portfolio site for a photographer, editorial and minimal
|
||||
> Build the hero, then screenshot it at 375px and 1440px and fix anything that breaks.
|
||||
> /design-review http://localhost:3000
|
||||
```
|
||||
|
||||
You should see Claude pull tokens from `ui-ux-pro-max`, open a browser, screenshot, and return
|
||||
ranked findings.
|
||||
|
||||
## Standalone audit (no Claude needed)
|
||||
|
||||
```bash
|
||||
npm run audit -- --url http://localhost:3000
|
||||
npm run audit -- --file ./index.html
|
||||
```
|
||||
|
||||
Outputs `audit-output/report.md` + per-viewport screenshots. Exit code is non-zero when there
|
||||
are high-severity findings (useful for CI — see `.github/workflows/design-review.yml`).
|
||||
|
||||
---
|
||||
|
||||
## Optional add-ons
|
||||
|
||||
### Figma Dev Mode MCP
|
||||
Requires the Figma desktop app. Enable Dev Mode → toggle the MCP server on. Then add to
|
||||
`.mcp.json`:
|
||||
|
||||
```json
|
||||
"figma": { "url": "http://127.0.0.1:3845/mcp" }
|
||||
```
|
||||
|
||||
Guide: <https://help.figma.com/hc/en-us/articles/39888612464151-Claude-Code-and-Figma-Set-up-the-MCP-server>
|
||||
|
||||
### 21st.dev Magic MCP
|
||||
Generates React components from a prompt. Get an API key at <https://21st.dev>, then add:
|
||||
|
||||
```json
|
||||
"magic": { "command": "npx", "args": ["-y", "@21st-dev/magic@latest"], "env": { "API_KEY": "<your-key>" } }
|
||||
```
|
||||
|
||||
Keep keys out of git — prefer `.claude/settings.local.json` or your shell env, both gitignored.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **`/mcp` shows a server failed** — run its command manually to see the error, e.g.
|
||||
`npx -y @playwright/mcp@latest`. Usually a Node version or network/proxy issue.
|
||||
- **Audit can't find Chromium** — run `npx playwright install chromium`, or set
|
||||
`PW_EXECUTABLE_PATH` to your Chromium binary.
|
||||
- **ui-ux-pro-max command not found** — re-run `npx ui-ux-pro-max-cli init --ai claude` and
|
||||
check the printed skill path; use that path in the `python3 …/search.py` commands.
|
||||
@@ -0,0 +1,67 @@
|
||||
# The Stack — why each tool is here
|
||||
|
||||
AI design fails in three predictable ways. Each layer of this stack fixes one.
|
||||
|
||||
| Failure mode | Fix | Tool |
|
||||
|--------------|-----|------|
|
||||
| Generic, templated look ("AI slop") | Force an aesthetic commitment | `frontend-design` |
|
||||
| Vague, inconsistent tokens & patterns | Ground decisions in a real database | `ui-ux-pro-max` |
|
||||
| Never sees the result → ships broken UI | Give the agent eyes | Playwright / Chrome DevTools MCP |
|
||||
| Reinventing primitives | Pull proven components | shadcn MCP |
|
||||
| "Looks fine to me" self-assessment | Independent, rigorous review | `design-review` subagent |
|
||||
|
||||
## 🧠 Knowledge — `ui-ux-pro-max`
|
||||
|
||||
A searchable design-intelligence toolkit: **84 UI styles, 192 color palettes, 73 font
|
||||
pairings, 99 UX guidelines, 25 chart types, a Core Web Vitals dataset, and 22 tech stacks**,
|
||||
plus a design-system generator that turns a product brief into concrete tokens. It's the
|
||||
answer to "what should this actually look like, and what are the anti-patterns?"
|
||||
|
||||
- Repo: <https://github.com/nextlevelbuilder/ui-ux-pro-max-skill> · License: MIT
|
||||
- Install: `npx ui-ux-pro-max-cli init --ai claude`
|
||||
- Use: `python3 <skill>/scripts/search.py "<brief>" --design-system` and `--domain <domain>`
|
||||
|
||||
## 🎨 Taste — `frontend-design` (official Anthropic)
|
||||
|
||||
~50 lines of markdown that stop Claude from sampling the safe center of its training data. It
|
||||
forces four decisions — *purpose, tone, constraints, differentiation* — before any CSS, names
|
||||
three "AI-slop" defaults to avoid, and pushes boldness into a single signature element.
|
||||
|
||||
- Repo: <https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design>
|
||||
- Install: `/plugin install frontend-design@anthropics/claude-code`
|
||||
|
||||
`ui-ux-pro-max` decides *what's correct*; `frontend-design` decides *what's distinctive*. Use both.
|
||||
|
||||
## 🧩 Components — shadcn MCP
|
||||
|
||||
Browse, search, and install shadcn/ui components (and other registries) by natural language,
|
||||
instead of hand-rolling accessible primitives. Best for React/Next/Vue/Svelte projects.
|
||||
|
||||
- Docs: <https://ui.shadcn.com/docs/mcp> · Command: `npx shadcn@latest mcp`
|
||||
|
||||
## 👁️ Visual feedback — Playwright MCP + Chrome DevTools MCP
|
||||
|
||||
The single biggest lever. Claude connects to a **real Chromium**, navigates, clicks, resizes,
|
||||
screenshots, reads the console, and takes an accessibility snapshot — so it can catch and fix
|
||||
its own z-index bugs, animation-timing errors, overflow, and layout shift. Chrome DevTools MCP
|
||||
adds deep performance/network/CLS profiling.
|
||||
|
||||
- Playwright MCP: <https://github.com/microsoft/playwright-mcp> — `npx @playwright/mcp@latest`
|
||||
- Chrome DevTools MCP: <https://github.com/ChromeDevTools/chrome-devtools-mcp> — `npx chrome-devtools-mcp@latest`
|
||||
|
||||
## ✅ Automated review — `design-review` subagent
|
||||
|
||||
A senior-reviewer subagent (`.claude/agents/design-review.md`) that runs a 7-phase audit over a
|
||||
live page: interaction states, responsiveness across 6 viewport tiers, visual polish, WCAG 2.1
|
||||
AA, edge cases, and console health. Invoke with `/design-review <url>`. The heuristic subset
|
||||
also runs headless in CI via `scripts/design-audit.mjs`.
|
||||
|
||||
## Optional add-ons (not in default `.mcp.json`)
|
||||
|
||||
- **Figma Dev Mode MCP** — read a frame's tokens/layout to generate matching code, and push
|
||||
Claude-built UI back to the canvas as editable layers. Needs the Figma desktop app + Dev Mode.
|
||||
<https://help.figma.com/hc/en-us/articles/39888612464151-Claude-Code-and-Figma-Set-up-the-MCP-server>
|
||||
- **21st.dev Magic MCP** — generate React components from a prompt ("v0 in your editor"). Needs
|
||||
an API key. <https://github.com/21st-dev/magic-mcp>
|
||||
|
||||
Both are opt-in (see `docs/SETUP.md`) so the base stack runs with zero secrets.
|
||||
@@ -0,0 +1,84 @@
|
||||
# Workflow — the design loop, end to end
|
||||
|
||||
The stack is built around one loop: **plan → commit → build → see → review**. Skipping the
|
||||
"see" and "review" steps is exactly what makes AI design look like AI design. Here's the loop
|
||||
on a real task.
|
||||
|
||||
## Example: "Build a pricing section for a developer tool"
|
||||
|
||||
### 1. Plan with data (`/design-plan` → `ui-ux-pro-max`)
|
||||
|
||||
```
|
||||
> /design-plan developer tool pricing section, technical audience, trustworthy, high-contrast
|
||||
```
|
||||
|
||||
Claude runs the design-system generator and pulls the palette, a font pairing, and the relevant
|
||||
UX anti-patterns (e.g. "don't hide the total", "make the recommended plan obvious"). Output is a
|
||||
compact token set — 4–6 colors, 2 type roles, spacing scale.
|
||||
|
||||
### 2. Commit to a look (`frontend-design`)
|
||||
|
||||
Claude answers *purpose / tone / constraints / differentiation*, picks ONE tone (say
|
||||
"precise, engineered, monospace-accented"), and chooses a single signature element (a subtle
|
||||
grid-paper background behind the recommended plan). It explicitly rejects the cream+serif and
|
||||
acid-on-black defaults.
|
||||
|
||||
### 3. Build
|
||||
|
||||
Implements with the chosen tokens. On a React project it uses the **shadcn MCP** to add a
|
||||
`card`, `toggle`, and `badge` rather than hand-rolling them.
|
||||
|
||||
### 4. See it (Playwright MCP) — the step that matters
|
||||
|
||||
```
|
||||
> Open it at http://localhost:3000/pricing. Screenshot mobile (375) and desktop (1440).
|
||||
> Toggle monthly/annual and check the focus states.
|
||||
```
|
||||
|
||||
Claude opens the real page and catches what code review can't: the annual/monthly toggle has no
|
||||
visible focus ring, the "Most popular" badge overlaps the card border at 375px, and a price
|
||||
number animates in before the card scrolls into view. It fixes each and re-screenshots.
|
||||
|
||||
### 5. Review (`/design-review`)
|
||||
|
||||
```
|
||||
> /design-review http://localhost:3000/pricing
|
||||
```
|
||||
|
||||
The subagent drives all six viewport tiers, tabs through the whole section, checks contrast on
|
||||
the muted "per month" text, and returns:
|
||||
|
||||
```
|
||||
Verdict: Ship with fixes
|
||||
Blockers: none
|
||||
High: "per user / month" text is 3.9:1 on the card background (fails AA for body text)
|
||||
Medium: CTA tap target is 40px tall on mobile (<44)
|
||||
What's working: type scale is consistent; recommended-plan emphasis is clear
|
||||
```
|
||||
|
||||
Claude fixes the High + Medium and the section is done — distinctive, responsive, accessible,
|
||||
and actually verified.
|
||||
|
||||
## The same loop for an existing site
|
||||
|
||||
Point the tools at what's already deployed:
|
||||
|
||||
```
|
||||
> npm run audit -- --url https://your-site.com # fast heuristic pass + screenshots
|
||||
> /design-review https://your-site.com/pricing # full review with taste + flows
|
||||
```
|
||||
|
||||
## A worked audit on a production site
|
||||
|
||||
`examples/juniper-audit/` contains a real run of `scripts/design-audit.mjs` against a live
|
||||
marketing site — the generated `report.md`, the per-viewport screenshots, and notes on how to
|
||||
read the output. It's the fastest way to see what the heuristic layer catches before you wire
|
||||
the stack into your own project.
|
||||
|
||||
## Rules of thumb
|
||||
|
||||
- **Never report UI work "done" without step 4.** If you didn't look at it, it isn't finished.
|
||||
- **Let `ui-ux-pro-max` set tokens, `frontend-design` set attitude.** Data for correctness,
|
||||
taste for distinctiveness.
|
||||
- **Blockers/High gate merging; Medium/Nit don't.** Keep momentum; don't bikeshed nitpicks.
|
||||
- **Re-screenshot after every fix.** The loop is cheap; regressions are not.
|
||||
Reference in New Issue
Block a user