Design decisions
dwic
An MCP server and CLI that audits design systems from inside Claude Code. Below are the interaction decisions behind it: what I chose, what I chose it over, and why. Including the one I have not settled.
designwithclaude.com(opens in a new tab)Findings cite evidence, not verdicts
- Chose
- Every finding carries the specific artifact behind it: the token name, the computed contrast ratio, the off-grid pixel value, or the offending selector.
- Over
- Returning a severity label and a short description, the way most linters and most AI reviewers do.
- Because
- A designer cannot act on "violates best practice," and cannot verify it either. When a tool runs inside an AI coding session, every unverifiable claim it makes is something the human has to take on trust. Evidence is what makes a finding checkable, and checkable is what makes it safe to act on quickly.
A skip is not a pass
- Chose
- Every audit category has an explicit skip condition. Form is skipped when there is no form markup, motion when nothing animates. The dashboard renders a skip differently from a clean pass.
- Over
- Reporting a clean pass for categories with nothing to audit, which is simpler to build and produces a friendlier looking report.
- Because
- Returning a green when there was nothing to check is a false negative the user has no way to detect. An empty design system is a signal, not a win. This is the decision that most affects whether someone trusts the second run as much as the first.
Cold CLI run before the install funnel
- Chose
- A public npx dwic-audit that needs no token, no account, and no config, and runs cold against any project.
- Over
- Gating every capability behind the token and install funnel: mint a token, then set up the MCP server, then audit.
- Because
- The funnel works for designers who were already convinced. Skeptics are the larger audience, and they need a 30 second proof that the tool finds real problems in their real code. The cold run is the moment that turns curiosity into a trial.
What it deliberately is not
- Not a canvas tool. It does not generate screens, prototypes, or mockups. It audits the system that generated screens will render against.
- Not a linter. Prettier and ESLint handle code style. Findings never cite indentation, semicolons, or import order.
- Not a generic AI design assistant. There is no chat interface and no prompt box. The CLI is zero prompt: it reads the code and reports what it found.
Still open
Whether the CLI should gain a --fix flag for mechanical findings, like adding a reduced-motion guard or replacing transition: all with an explicit property list. Shortening that loop is worth a lot. But once the tool writes source files the trust bar rises sharply, and a single false positive stops being a bad suggestion and becomes "dwic broke my CSS." Deferred until audit coverage is stable and there is data on which findings people actually fix.