I used to paste “follow our design system” into every agent prompt. The PR still arrived with !important , magic z-index: 9999 , and a one-off hex that matched nothing in the theme.
The agent wasn’t being rebellious. It just didn’t know which habits we had already decided were off-limits.
So I keep a short banned CSS patterns list next to the tokens file, and I paste it into UI prompts the same way I paste the ownership map.
What goes on the list
Not “write good CSS.” Specific patterns that keep showing up in agent diffs and keep failing review:
# banned-css.md (keep under ~30 lines)
Banned — do not introduce: - `!important` (except existing legacy files listed below) - hardcoded hex / rgb outside `tokens.css` / theme modules - `z-index` above 20 without a comment pointing at the stacking doc - `position: absolute` for layout that flex/grid already solves - `font-size` / `line-height` / spacing as raw px when a token exists - `outline: none` without a visible `:focus-visible` replacement - `overflow:…