The event card passed the visual checks I ran. I had rebuilt it from scratch that morning. A teammate rejected it two hours later. The checks were not useless; they were incomplete for the intended design and surrounding layout.

The card was not broken in any obvious way. It rendered, it loaded without errors, and it used the right component names. The composition was wrong. The icon appeared twice: once from the card template, and once from a prior render pass I had not cleaned up. Title height was unconstrained, so event names of different lengths pushed the price block to different vertical positions depending on the string. The color tokens for tier badges were close to the design but not exact. Four hex values were off. Content density was too loose. The whole thing looked like something built from a description of the intended card, not from the card itself.

That distinction is the whole story.

the problem with plausible

I gave Claude the existing markup, the ticket description, and a directive: rebuild the card to match the new pricing structure. The output was coherent. It followed the existing patterns. It built something that resembled the designer’s mockup the way a cover band resembles the original: same structure, same approximate timing, missing the details that made the original worth covering.

The title-height invariant is a good example of what I mean. The design has a rule: the title breaks at two lines maximum, and the price block sits at a fixed vertical position regardless of title length. That constraint is not in the ticket. It is not derivable from the existing markup. It lives in the designer’s head, in a Figma annotation I did not pass to the agent, in the visual grammar of the product that accumulated over years before I touched it.

Claude built what the ticket said. The ticket did not say enough. My mistake, not the agent’s.

the rebuild, not the tweak

The fix required revisiting the card structure: unify the icon path so only one source was active, constrain title behavior to the intended design, correct the color tokens against the design reference, adjust spacing, and remove the duplicate template fragment.

Five changes. Each one small. Each requiring knowledge of the exact design, not an approximation of it.

the constraint no one told the agent

Once the card was correct, the page was still broken.

A shell-template wrapper carried a legacy max-width rule. At a wide viewport the card grid looked fine, but at an intermediate viewport the right column clipped. The defect was not in the card itself; it was in the surrounding layout constraint.

The initial task did not include the shell template or a multi-viewport review. An AI assistant can inspect broader context when it is given that scope, but it cannot infer an undocumented wrapper constraint from a component-only ticket. I was testing at a wide desktop viewport and did not see the intermediate-width failure.

The CSS change was small. Finding it required the review to include the page shell and representative viewport widths. A colleague surfaced the issue in code review, which was exactly the control the initial component check had missed.

what would have closed the gap

I keep circling the same question: what review artifact would have forced the model toward the exact card structure on the first pass?

The strongest review artifact would have been an annotated design reference: not “looks like this,” but explicit constraints such as title behavior, price alignment, color tokens, icon source, and duplicate-content rules. An AI assistant can apply a supplied specification; a screenshot and existing markup alone may not expose every intended invariant.

There is also a version of this problem that tighter prompting alone cannot fix. The shell constraint was a scope problem. The ticket covered the component, while the defect lived in the wrapper. A precise card specification still needs a page-level review that includes its real containers and representative viewport widths.

Both failure modes appeared in the same review cycle. One improved with a more explicit design specification; the other improved with broader layout scope and multi-viewport verification.

AI assistance can make a plausible first pass quickly. Correctness still depends on an explicit specification and verification at the boundary between the component, its container, and the real user environment.