design-system-compliance
Check that the UI you actually rendered uses the design system, by reading computed styles in the running app against the project's design tokens. Catches hardcoded hex colors, off-palette backgrounds, invisible or unusable controls, and animations that never ran. Use after building or restyling a component, when a design review is wanted, when a UI looks slightly off but nobody can say why, or when a design system exists and nothing checks whether the code follows it.
git clone --depth 1 https://github.com/reticlehq/reticle /tmp/design-system-compliance && cp -r /tmp/design-system-compliance/skills/design-system-compliance ~/.claude/skills/design-system-complianceSKILL.md
# Does the rendered UI actually use the design system?
Reading the source tells you what the component _asks_ for. It cannot tell you what the browser resolved: a token overridden three layers up, a hardcoded `#3b82f6` that happens to look close, a dark-theme scope that never applied. That answer only exists in the running page.
**Reticle** reads computed styles in the live app and compares them against the project's tokens. Not installed? `RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init`, then the [`install-and-verify`](https://github.com/reticlehq/reticle/blob/main/skills/install-and-verify/SKILL.md) skill.
## The check
```
reticle_snapshot({ sessionId, mode: "interactive" })
reticle_inspect({ sessionId, ref })
```
`inspect` returns a `theme` report per element:
| Field | What it tells you |
| --- | --- |
| `offTheme` | **the headline.** True when a set, opaque color matches no token in the palette: a violation worth fixing |
| `colorTokens` / `backgroundTokens` | every token whose resolved value is this color. Empty means off-palette |
| `colorToken` / `backgroundToken` | the _unambiguous_ match, or `null` when several tokens share the color. `null` here is an abstention, not a violation: read the plural field |
| `tokenCount` | how many tokens resolved under the active theme. **`0` means the app declares no palette**, and `offTheme` is never asserted: report that rather than a clean bill of health |
| `themeScope` | the theme active at capture (e.g. `.dark`), so two inspects taken minutes apart are comparable at all |
Read `tokenCount` first. Zero tokens means there is nothing to comply with, and every "pass" below it is vacuous.
## Beyond color: is the control actually usable?
The same call answers the questions a screenshot cannot:
- `occluded`: covered by an overlay. It renders, and no user can click it.
- `box`: `0×0` is present-but-invisible, the most common "it's there, I can see it in the DOM" bug.
- `styles.opacity` / `styles.cursor`: the difference between disabled-looking and disabled.
- `source: { file, line }`: where to go and fix it.
A design review that only compares colors passes a button nobody can press.
## Animations
```
reticle_animations({ sessionId })
```
Returns running and recently completed animations with their targets and timing. Two things worth checking after any motion work: an animation you added that **never appears here** did not run, and one whose duration does not match the token is off-spec. Both look identical in a screenshot.
## Report violations as locations, not opinions
For each element that failed, give the `file:line` from `inspect` and the specific fact: "background `#3b82f6` matches no token; the palette has `--color-primary` at `#2563eb`". A design-review comment without a location is a task someone else has to redo.
## What this is not
This checks **compliance with the tokens the project declares**. It is not an opinion about whether the design is good, and it is not an accessibility audit. Contrast ratios, focus order and screen-reader semantics are a different job, and claiming them here would be a false green of exactly the kind this repo exists to prevent.
---
Everything else, one page at a time: `curl https://docs.reticle.sh/llms.txt`. Design token check missing something you needed? `reticle_feedback` with `kind: "gap"`.Install, instrument and verify this running web app from the inside (DOM, network, routing, console and framework state) instead of screenshots or guessing. Drives one real flow end to end and returns a verdict with the file:line to fix. Use when the user asks to set up or install Reticle, when a user-facing change needs proving before you call it done, when a test passes but the UI is broken, or when the user types /reticle.
Test-driven development for behaviour a unit test cannot reach, by writing the expectation against the running app before writing the code. Declare the consequence first, watch it fail, implement, watch it pass. Use when building a user-facing feature, when the user asks for TDD on UI or full-stack work, when a unit test cannot express the outcome that matters, or when you want a red-green loop that runs against the real app instead of mocks.
Sweep a whole running web app for what is broken, without writing a script or knowing the codebase. Clicks every reachable control and reports dead buttons, console errors, failed requests, and places where the API and the screen disagree. Use on an unfamiliar codebase, before a release, after a big merge or dependency bump, when the user asks for a smoke test or a health check, or when someone says "just check everything still works".
Find out why something in a running web app does not work, when the console is empty and the code looks correct. Reads the click, the request, the store and the console together and returns the file:line to open. Use when a button does nothing, a form will not submit, data will not load, a page renders blank or stale, a modal will not close, or the user says "it's broken" and the code review says it is fine.
Drive and verify an Electron or Tauri desktop app from the inside, including the main-process and Rust IPC calls a browser tool cannot see. Use when a desktop app needs testing, when a feature works in the browser but not in the packaged app, when an IPC or invoke call needs proving, when a desktop screenshot or visual diff is wanted, or when you need a headless run of a desktop UI in CI.
Find out why the tests pass but the app is broken. Catches false greens: a green suite over a feature that does not work, a mocked API standing in for a real one, an assertion that holds no matter what the app does, a click handler wired to nothing. Use when the suite is green and the user says it is broken, when a test never fails, when coverage looks fine but bugs still ship, or before trusting a passing run you did not watch.
Pick up the bugs a human flagged by pointing at them in the running app, each arriving with the element, the note they typed, and the source file and line. Use when the user says they marked or flagged something, when starting a session on an app someone has been clicking through, when a designer or PM has left feedback in the UI, or when the user describes a problem as "that button there" without saying which file.