dsh-design

dsh-design

English | 中文

Design taste your agent can be held to.

Every design plugin in this ecosystem is a prompt: a list of rules handed to the model, with nothing checking whether the model followed them. dsh-design ships the rules and the check — design_audit renders the page and measures what it actually did, so "it looks good" becomes a number you can argue with.

What it measures

Rule	What it reports
contrast	Every text element failing WCAG AA, with its measured ratio and the ratio it needed. Text alpha is composited against the real backdrop, so faded grey-on-white is caught.
type-scale	How many distinct text sizes the page actually rendered, and which. More than a handful means the hierarchy was improvised.
spacing-grid	Padding, margin, and gap values that miss the spacing scale, listed by value and element.
palette	Distinct non-neutral colors. A grey ramp is free; nine accents is drift.
tap-target	Interactive elements below the 44px floor, with their measured size.
line-length	Running text past the comfortable measure, with the longest line found.
default-font	Whether most text fell back to the browser default, meaning no family was ever chosen.
purple-gradient	Violet-to-fuchsia gradients, detected by hue rather than by string — Tailwind's violet-500 sits at 258°, so a naive 260° band would miss the most common offender.
emoji-icons	Emoji standing in for iconography inside controls.

Findings name the element and the number. p.muted at 1.62:1 (needs 4.5:1) is actionable; "improve contrast" is not.

The other half: the skill

Measuring only catches drift from a system you already decided on. The bundled design-system skill is how the agent decides one — and it is written around the actual cause of generated-looking UI, which is not bad taste but unlimited choice: a fresh hex per element, a new size whenever something should look bigger, whatever margin the moment suggested.

So the skill front-loads the constraints: commit to one direction, fix the palette and type scale before writing components, lead with hierarchy, space on a scale, then audit. It ends with the concrete tells to avoid, and tells the agent to run design_audit before claiming the work is done.

Install

dsh plugin --profile web add dsh-design

Uses your installed Chrome or Edge; otherwise npx playwright install chromium once and set browserChannels: [chromium]. Requires Node ^22.19 || >=24.

Use

design_audit { target: "http://localhost:3000/pricing" }
design_audit { target: "dist/index.html", viewportWidth: 390 }

Takes a URL (localhost always allowed) or a local HTML file. Pass viewportWidth to measure a breakpoint — mobile is where tap targets and line length usually fail.

Configuration

- id: design
  name: dsh-design
  config:
    headless: true
    browserChannels: [chrome, msedge, chromium]
    viewportWidth: 1280
    viewportHeight: 900
    navigationTimeoutMs: 15000
    spacingBasePx: 4        # spacing must be a multiple of this
    maxTypeSizes: 6         # distinct font sizes before the hierarchy is unplanned
    maxPaletteColors: 8     # distinct non-neutral colors before it is drift
    neutralSaturation: 0.15 # saturation below which a color counts as neutral
    minTapTargetPx: 24     # WCAG 2.2 AA; raise to 44 for a touch-first product
    maxCharsPerLine: 75
    allowedHosts: []        # extra hostnames the audit may load
    registerSkill: true

Every threshold is a deployment choice, because a dense operator console and a marketing page do not want the same limits.

Design notes

• The browser measures, Node decides. The in-page collector only gathers computed styles; every rule is a pure function over that snapshot, which is why the thresholds, the WCAG math, and the cliche detection are unit-tested without a browser.
• Unmodelled color syntax is skipped, not guessed. A page using oklch() loses those elements from the contrast count rather than getting a fabricated ratio.
• Contrast resolves a real backdrop. The collector walks ancestors to the first opaque background, because a ratio against rgba(0,0,0,0) is meaningless.
• Neutrals are excluded from the palette count. A grey ramp is structure; saturated colors are choices, and only choices should be rationed.

Calibrated against a real application

Auditing dsh's own Web UI — a professionally designed product — was the check that mattered, because every earlier fixture had been written to trigger the rules. Two thresholds passed cleanly on it (4 type sizes against a limit of 6, five non-neutral colors against eight), which is the evidence that those limits are not arbitrary. Two rules were wrong and were fixed:

• Hairlines are not rhythm. 1px and 2px values are borders, focus rings, and optical nudges; holding them to the spacing scale was noise. Values below the base are now exempt, and when every off-grid value fits a finer scale the report says so and names it rather than asking a consistent project to abandon its own system.
• 44px is the touch guideline, not the AA bar. Flagging 28x28 desktop icon buttons applied a mobile standard to a mouse interface. The default is now WCAG 2.2 AA (2.5.8, 24px); touch-first deployments raise it.

On that same UI the report went from three violations to two, and the one that remained — two muted labels at 3.55:1 — is a real accessibility finding.

What the plugin's own review changed

dsh-review audited this source and found six defects, all fixed. The one that mattered: the backdrop walk used to treat a gradient as "nothing painted here" and fall through to white, so white text on a dark gradient hero — the most common landing-page pattern there is — was reported as a contrast failure that did not exist. A linter that cries wolf on the commonest layout gets switched off, so this was the difference between a useful tool and a liability. The backdrop now reports "unmeasurable" and those elements are skipped, holding to the same rule the foreground path already followed: measure it or say nothing.

The others: unparsed color syntax in a background is now skipped rather than assumed white; local targets are canonicalized and confined to the workspace and to HTML files, because the renderer executes what it loads; cancellation is observed across the browser launch, not only after it; the host policy is re-checked after redirects; and ancestor opacity: 0 no longer counts as visible.

Known limitations

• Measures one viewport per call; run it again at a mobile width rather than assuming.
• Samples the first 400 visible elements, enough for a page and not for an entire app shell.
• Line length is estimated from an average glyph advance, so treat it as a signal rather than a typographic measurement.
• It judges what is measurable. A layout can pass every rule and still be awkward — pair it with dsh-preview so the agent can look at the page too.

Family

Plugin	What it gives your agent
dsh-preview	👁 Eyes — verify what it builds: open, read, screenshot, self-check
dsh-pilot	✋ Hands — operate any page by accessibility refs, with a native permission model
dsh-review	🔍 Judgement — find defects, then try to refute each one before reporting it
dsh-design (this repo)	🎨 Taste — constrain the choices, then measure whether the result kept them

License

MIT © Viger1