pd-design-system

pd-design-team

English · Español

A product-design team for AI agents — 16 skills that work like a real design org: a lead who scopes and routes, specialists for research, information architecture, flows, screens, copy, visual design, design systems, mocks, prototypes, responsive, QA, handoff, and metrics, and one shared contract that makes their work interlock.

It follows the open Agent Skills format, so the same files run on Claude Code, Codex, Gemini CLI / Antigravity, Cursor, and any runtime that loads SKILL.md folders. It works with whatever your designers use — Figma, Pencil, Penpot, Sketch, Framer, a design system in code, or nothing but screenshots — and adapts to the tools and model capabilities each session actually has.

What it is, in one minute

You talk to an AI coding agent — Claude Code, Codex, Gemini CLI / Antigravity, or Cursor's agent — in plain language: "Use pd-design-lead to redesign our checkout." The skills turn that agent into a design team. It asks what it needs, proposes a plan, and waits for your OK. Then it produces real work:

• Design documents in your repo (docs/design/): research synthesis, sitemap and navigation, flows, screen specs with every state, copy, visual specs, QA reports, developer handoff.
• Screens in your design tool when the agent has a connection to it (Figma and Pencil today; Penpot, Sketch, and Framer when an MCP server for them is connected), or coded mocks built from your real components and tokens.

You only run the parts you need. A copy fix goes to one specialist; a new feature might use six.

What you need

• An agent that loads Agent Skills: Claude Code, Codex, Gemini CLI / Antigravity, or Cursor.
• Optional: a connection (MCP server) to your design tool, tracker, or analytics. Without one, the team works from files, screenshots, and exports, and tells you which checks it couldn't run.

See it work

examples/pantry-meal-planner is a complete effort produced by running the team with an AI agent on a fictional recipe app: the plan, research framed honestly as assumptions (no invented data), flows, screen specs with every state, copy, visual and component mapping, a coded hi-fi mock built only from design tokens, a QA report with real findings, the developer handoff, and the retro's learnings.

Why it's different

• Binds to your real design system. Specialists use your live type roles, tokens, and component variants and never invent names. When something is missing they log a gap, use the closest real part, and the system-ops loop decides whether to add it.
• Works through files, not chat. Every specialist reads declared input artifacts and writes one output artifact with a standard header in docs/design/. Any model can pick up where another left off.
• Honest by construction. Research separates findings from assumptions and needs dated sources for market claims. QA reports the checks it performed ("no failures found in the checks performed on 6 screens: automated scan, keyboard, contrast; screen readers not tested") instead of claiming conformance. Nobody reports an audit it couldn't run.
• Evaluates and adapts. Each effort starts with a session check (which tools are connected, whether the model has vision, subagents, web search) and plans around reality with open fallbacks. Each effort ends with a retro that writes project lessons to LEARNINGS.md, which every specialist reads next time.
• Accessibility is the floor. WCAG 2.2 AA by default, applied in every discipline rather than bolted on at the end; usability heuristics in every QA pass.
• Domain packs. Regulated domains plug in through packs (a healthcare pack ships; a template is included). Regulatory checks run only when the project declares them.
• Built to be tested against models. A 51-scenario behavioral eval suite lets you check whether a new model actually follows the contract; results go in evals/results/.

Install

git clone https://github.com/JuanColoradoV/pd-design-team.git
cd pd-design-team
scripts/install.sh            # symlinks into every runtime it finds on this machine

install.sh targets ~/.claude/skills, ~/.codex/skills, ~/.agents/skills (shared by Gemini CLI / Antigravity and others), and ~/.gemini/skills. Pass runtimes explicitly (scripts/install.sh claude codex), install into a project (--dir ./.claude/skills), copy instead of link (--copy), or remove (--uninstall). Symlinks mean one git pull updates every runtime.

Claude Code plugin:

/plugin marketplace add JuanColoradoV/pd-design-team
/plugin install pd-design-team@pd-design-team

Uploaded skills (e.g. claude.ai): scripts/package.sh builds one zip per skill plus an all-in-one zip in dist/. Every specialist loads pd-foundations, so upload it (and pd-design-lead) together with the specialists you want.

Use it

Start with the lead for anything bigger than one discipline:

Use pd-design-lead to redesign our checkout flow.

On a new project the lead first creates docs/design/PROJECT.md — product, users, where the design system lives, design tool, tracker, analytics, domain packs, compliance, locale — inferring what it can and asking only for the rest. Then it proposes the smallest pipeline that does the job and waits for your OK.

For a single-discipline task, call the specialist directly:

Use pd-ux-writing to rewrite the error messages on the signup form.

Use pd-ux-qa to audit these screens for accessibility.

The team