Findings and verdicts
Two verdicts and one fixed shape. Every finding names the value, then the token or component it should be, then the line it comes from.
Crocotaste comments only on what it can point at in your repository. If it cannot show you the line that makes something a rule, it says nothing.
Verdicts
Violation · a value that is exactly a token of yours written raw, a component of yours hand-rolled, or a recorded convention or decision broken.
Drift · a near miss. A color close to one of your tokens, a spacing value just off your scale, a token pair that does not reach the AA contrast floor, or a line that strays from a rule your team wrote as a preference. Drift of any kind, from the checks or the AI review, names what it should be and carries no suggestion to commit: the difference may be the one you meant (a true black beside an ink of #0A0A0A), so switching it is your call or your agent’s, never one click.
The difference is certainty, not severity. A violation turns the check neutral and drift leaves it green, and neither blocks anything: findings are posted as a comment review, never request-changes, and a neutral check passes branch protection, so what ships stays your call.
What a finding looks like
**Violation** · `#4ade80` is `--color-success`: use the token (tokens.css:18)
Source: `tokens.css:18`
```suggestion
<div className="bg-success" />
```
Under the suggestion, collapsed until someone opens it:
In "src/app/page.tsx" around line 12: Replace bg-[#4ade80] with the design token --color-success (tokens.css:18).
Four parts on a violation: the verdict and the message, the source line, a suggestion you can commit in one click, and a collapsed instruction for the agent that wrote the code. Drift has the same parts without the suggestion, from the checks and the AI review alike, and a check’s drift tells your agent to use the token unless the difference is intended, and then to record the exception in DESIGN.md.
A suggestion is always exactly one line. A suggestion block is a one-click commit, so a multi-line one would be a way for a reviewed repository to get code committed through us; anything that is not one safe line is dropped and the finding explains itself in words instead. Raw values are only ever reported by these checks: an AI finding that cites a rule against raw values in your DESIGN.md is removed before it posts, so a hex written as text in a code sample is never reported as a color. A raw value that is only the fallback inside var(--token, …) is never flagged, because the token is already there.
- When no suggestion is offered. When a raw color matches several of your tokens at once (white is often the page, the inverse text and the text on the brand), the finding names three of them and offers no suggestion, because which one you mean is the role the color plays, and a one-click guess would commit the wrong one. The three come first by your file’s own app, then by the role the property plays (a background names surface tokens first, text names foreground tokens, a border names border tokens), and the rest are counted as “N more equivalent tokens”, in the message and in the instructions for your agent alike. A color in an SVG
fillorstrokeattribute, or an HTMLbgcolor, is flagged the same way without a suggestion, sincevar()there does not work in every client, and so is a raw value inside a Sass or Less function such asdarken(),math.div()or one your team wrote, which runs when the stylesheet compiles, before anyvar()exists. A plain CSS function such ascalc()or a gradient keeps its suggestion. - Several values on one line. Every value a check reports on one line is one finding and one comment:
padding: "18px 22px"gets a single comment that lists both values, with one suggestion that fixes both and one prompt for your agent that covers both, and the same value repeated on a line is listed once. A line with a violation and drift on it suggests only the violation’s fix, and a line with only drift suggests nothing. Dismissing that comment dismisses the whole line, and it is marked fixed only when none of its values is left. On a pull request reviewed before, the comment that named one of those values is updated to name them all, and the others are collapsed as outdated. - Spacing between two steps. A spacing or radius value exactly halfway between two steps of your scale is drift named with both steps.
- In a Tailwind repository. A spacing value your DESIGN.md defines has no class of its own, so the suggestion is Tailwind’s default class for it when the value is one of its steps (16px is
p-4), and none when your theme sets its own spacing unit or steps, or the repository has a Tailwind config that could.
A suggestion from the AI review has a second test: it has to be a bounded edit of the line it replaces. At least half of that line survives, it adds no URL the line did not already carry, and it is never offered on an import line. One that fails the test is dropped, and the finding keeps its message and its prompt for your agent.
Where findings come from
Two sources, and you can tell them apart by what they cite.
Checks that need no model compare a literal your pull request added against a value already in your repository: a raw hex where you have a color token, a Tailwind palette class (bg-green-500, bg-white) whose color is a token of yours, a spacing value that is not on your scale, a font size that is not on your type scale (your --text-* or --font-size-* tokens), a bg-/text- pair from your own palette below 3:1. They cost nothing and they stay quiet unless they are certain.
A var(--token) with no fallback that nothing in your repository defines or uses, one or two letters from a token your stylesheets define, is a violation naming the real token, with it as the suggestion when only one is that close. A name that differs from yours only in its digits (--gray-12 beside --gray-1) is left alone, since a package’s scale often sits beside your own, and the check stands down when a stylesheet builds names at compile time.
A box-shadow or z-index value exactly equal to one of your tokens (a --shadow-* or --z-*) is flagged with the token as the suggestion. Nothing close but different is, and a value two tokens share is left alone, since the role it plays decides which one is meant.
3:1 is the WCAG AA floor for large text and interface components, and it is the level this check can stand behind: it reads two class names and never the type size, so holding every pair to the 4.5:1 body-text level would flag correct buttons. Both the message and its agent prompt name 4.5:1 for body text, so the last part of that call stays yours.
These checks refuse a place before they refuse a value. A token’s own definition is not a use of it, so a declaration line and a tailwind.config.* are not scanned for raw values at all. A value inside a comment or a content: string is not code. top, right, bottom, left and inset position one element against another rather than sitting on your spacing scale. A color matches a token only at the same alpha, so an 8% tint is never told to become the fill it is a tint of. And a variant like hover:bg-… is a different state, so it is never paired against the base text color.
A palette class is measured the way a hex is: exactly a token is a violation, close to one is drift, and a violation’s suggestion is the token’s own utility (bg-red-500 becomes bg-danger, a hover: prefix kept). One your theme defines itself (--color-red-500 in your @theme) is your token and is never flagged, and a tint (bg-red-500/20) is left alone, since no token shares its alpha. A white or black class is measured only as a background; as text, a border or a fill it plays a role a value check cannot see. The check runs only in a repository that uses Tailwind (a Tailwind config, or a stylesheet that imports it or declares an @theme block); a Bootstrap bg-white is never measured.
The AI review judges what is left against your DESIGN.md and the parsed system, and it may report only three kinds of thing: a semantic token used for the wrong role, a hand-rolled element where a listed component of yours exists, or a violation of a listed convention or decision. Aesthetics, naming and wording are out of scope. It holds no design opinions; the inventory of your system is all it works from. It reads the lines you removed beside the ones you added, so a rule a removed line satisfied and its replacement does not is a finding on the replacement.
Every AI finding must cite a line that defines something in your references, or it is deleted before it reaches the pull request. That is enforced in code after the model answers, not asked of it in a prompt.
At most three AI findings per pull request, ever, not three per push. When more survive, the summary says how many were withheld.
How many arrive at once
At most 12 findings are listed per push, violations first, and both the summary and that push’s review say how many are held back. They post on later pushes as the listed ones are fixed or dismissed (a dismissal frees room but posts nothing itself, so the next push posts them in one review), and the review that posts them says they were held back from an earlier push. A stylesheet that adds 200 raw hex values should get a readable review, not a wall of comments.
A finding is never posted twice. Each carries a stable marker that survives force-pushes and line shifts, so an unrelated edit above it does not turn one finding into two.
What happens to a finding’s comment after it posts:
- Fixed. Once the review can see the line is gone, the comment opens with
✅ Fixed inand a link to the commit, and collapses (the thread itself stays open for you to resolve); the check drops it and the summary counts it as fixed. - Edited, still wrong. A line you edit that still breaks the same rule gets a new comment, and the old one collapses as outdated.
- No longer reported. A finding the review stops reporting while its line is unchanged (a token renamed in your base branch, a check refined, or an AI finding the review read again and let go) is not a fix either: its comment opens with
No longer reported onand a link to the commit, collapses as outdated, and the summary counts it apart (12 no longer reported). Anything else that leaves without proof of a fix collapses as outdated with no line: outdated says nothing was fixed, only that the finding no longer stands. - Not checked this time. A finding the review could not check (a file it did not read in full, an incomplete set of references) stays open.
- Came back. If the code brings a closed finding back, its comment opens again.
- Dismissed. A finding you dismiss with
@crocotaste ignoreis marked resolved and stays in the summary as dismissed, counted by nothing the check decides.
GitHub’s “Resolve conversation” button stays yours to press: resolving a thread takes write access to your code, which Crocotaste never asks for. If your branch rules require conversation resolution before merging, resolve our collapsed threads with the rest.
To dismiss one instead of fixing it, reply with @crocotaste ignore <reason>. The same findings are published as JSON on the check run for agents: the check run and JSON.
Ready when you are
Install on GitHub