The PR adds a primary button. It looks like Button. It is a <button className="rounded-md bg-blue-600 px-4 py-2 text-white"> with a slightly different focus ring. The design system already has Button variant="primary". The agent didn’t mention the fork.
I’ve started asking for a one-line citation in the PR body: which system component was reused, or an explicit “I didn’t use one, because….” Lookalike markup is not reuse.
Why forks sneak in
- The agent wasn’t given the import path or the story URL
- The system component’s API didn’t match the first prompt (
loadingvsisPending) - The model “just needed a button” and patterned after a screenshot
- A previous file in the repo already forked one, and the agent copied that
You cannot see the fork in the screenshot. You see it in the imports — or the lack of them.
What the citation should look like
In the PR body (or the agent’s summary), require one of:
Reused: `@acme/ui` <Button variant="primary" size="md">
from src/components/Button (story: Button/Primary)
or:
Did not reuse a system component. Reason: we need a native
<file> input trigger and Button doesn’t expose that slot yet.
Fork is local to ImportDialog, not a new shared Button.
That’s it. No essay. The point is to make the decision reviewable in thirty seconds.
What to put in the prompt
Paste the short list of components the task is likely to need — names, import paths, and the one prop pattern you actually use:
For actions, use `import { Button } from "@acme/ui"`.
Variants: primary | secondary | ghost. Do not recreate
equivalent markup with utility classes. If a system
component almost fits but a prop is missing, say so
and do not silently fork it. Cite the component you
used in the PR body, or admit the fork and why.
A link to the Storybook item helps; a 12-line API cheat sheet helps more than “follow the design system.”
Review checklist
- New interactive UI: is there an import from the system package or
src/componentsprimitives? - If not, is there a stated reason in the PR body?
- If the markup is 80% of an existing component, request a swap — don’t bikeshed the border radius
- If a real gap exists (missing slot, missing variant), file or link the system issue; don’t let the fork become the unofficial variant
A simple CI rule — flag new <button> / raw <input> in feature folders when the file doesn’t import the primitive — is noisy, but useful as a warning on the PR.
Reject / send back
Reject
- A restyled raw
<button>next to existingButtonusage in the same route - A local
PrimaryButtonwrapper that only copies classes - “I followed the design system” with no import and no citation
- A fork that should have been a
variantor aasChild/ slot on the existing primitive
Accept
- A real system import, cited (or obvious from the diff)
- A documented fork with a narrow reason and a local, not global, name
- A follow-up ticket when the system API is the actual blocker
Tiny habit
When you ask an agent to add a control, tell it to cite the system component it reused — or admit it forked one. Reviewers shouldn’t have to grep for bg-blue-600 to find out you grew a second button.
Top comments (0)