Add designing-for-agents skill + no-icon-name-switch rule contract

[ben-million]

What

Adds designing-for-agents — a skill that synthesizes our design-to-code skills (paper-flex, paper-to-code-components, reconcile-paper-sync, tailwind-token-consolidation) into generic, tool-agnostic lessons about how coding/design agents fail and how to turn each failure into a countermeasure that holds.

React Doctor already encodes the deterministic agent failures as rules. This skill is the layer above: the catalog of failure modes, the rule-vs-guidance decision for each, and the authoring techniques (RED/GREEN intent, pre-enumerated bugs, escape-hatch tables, completion gates) that make a rule diagnostic or skill actually change agent behavior.

Files

• .agents/skills/designing-for-agents/SKILL.md — the failure catalog + the rule-vs-guidance decision + authoring techniques + escape hatches + completion gate.
• docs/rule-research/no-icon-name-switch.md — stage-1 rule-research contract for the one genuinely new deterministic candidate: a component that switches on a prop to return ≥3 distinct inline <svg> bodies (not tree-shakeable; the antipattern paper-to-code-components §3 exists to stop).
• docs/rule-candidates-backlog.md — backlog entries for the above, a narrower re-open of the previously-dropped no-arbitrary-over-bare-value (sizing/spacing-on-scale only; default-off, must clear a noise sweep), and a lower-confidence no-state-for-static-variant note.
• .gitignore — allowlist the new skill dir (.agents/skills/* is ignore-by-default; each repo-owned skill needs two ! un-ignore lines).

Key finding

The deterministic design-rule surface is already mature (design / react-ui / a11y + the backlog), so most of the synthesis value is judgment-level guidance, not new rules. Only one genuinely new rule candidate fell out — captured here as a contract, not implemented.

Not included (follow-ups)

• rule-writing + rule-validate for no-icon-name-switch: the detector, adversarial tests, and the OSS eval sweep. It's a medium-FP heuristic, so per our own bar it must not ship without evals. The contract is written so stage 2 can pick it up directly.

Notes

• Docs / skills / tooling only — no published-package behavior change, so no changeset.
• The skill is deliberately generic (Paper stripped out) per the synthesis goal; concrete examples stay React-flavored to keep it actionable.

🤖 Generated with Claude Code

---

Note

Low Risk
Docs and agent skills only; no package or linter behavior changes.

Overview
Adds designing-for-agents — an agent skill that catalogs how coding/design agents fail, when to route fixes to rules vs guidance, and how to author countermeasures (escape hatches, completion gates). It argues most design-agent mistakes are already covered by existing rules and that new value is usually judgment-level guidance, not more linters.

Documents the deterministic fallout in docs/rule-candidates-backlog.md: no-icon-name-switch (prop-driven switch over ≥3 inline SVGs), a narrower no-on-scale-arbitrary-spacing revisit of a dropped rule, and a tentative no-state-for-static-variant. Adds a stage-1 docs/rule-research/no-icon-name-switch.md contract (detector scope, FP traps, OSS eval gate) without implementing the rule.

.gitignore is updated so the new skill directory is tracked like other repo-owned skills.

^{Reviewed by Cursor Bugbot for commit ac2a413. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/eslint-plugin-react-doctor@981

npm i https://pkg.pr.new/oxlint-plugin-react-doctor@981

npm i https://pkg.pr.new/react-doctor@981

commit: ac2a413