if you build with ai, you know this one. every new app gets new buttons, new cards, new spacing. nothing looks like it came from the same person.
my fix is a short design section in the file your agent reads first (CLAUDE.md for claude code, AGENTS.md for codex). the agent reads it before it builds a screen, so you stop repeating the same notes by hand.
these are the rules i use for apps, dashboards and settings screens. my portfolio follows a different look, so this is for tools, not showcase pages.
what you need
- claude code, codex, or both
- a CLAUDE.md or AGENTS.md at the root of your project. no file yet? make one, it can start with just this section
the 5 rules
01one surfaceone main surface per workspace, with thin dividers between sections. not a floating card for every section. navigation, page header and toolbars stay outside it.
02one main buttonone clear primary action. secondary controls are outlined, so the next step is obvious.
03equal spacingpadding inside a box is the same on all sides. gaps between boxes are the same. page margins are the same on all sides, and no width limit leaves empty space stranded on one side.
04title firstevery screen has a clear hierarchy, and an action is never bigger than the title it belongs to.
05matching dropdownsevery dropdown popup matches the app's theme and works with the keyboard. no grey system popup.
the numbers i use
these are my defaults. swap in your own colours, keep the structure.
- background #09090b, surface #18181b, borders #27272a
- each product brings its own accent colour and icon
- controls 40px tall on desktop, touch targets 44px
- visible focus, readable contrast, reduced motion respected
copy this into your file
## design - one continuous main surface per workspace, sections split by thin dividers, not a floating card for every section - navigation, page header and toolbars stay outside the main surface - one clear primary action, secondary controls outlined - padding inside a box is equal on all sides, gaps between boxes are equal, page margins are equal, no width cap strands empty space on one side - every screen has a clear hierarchy; an action is never bigger than the title it belongs to - every dropdown popup matches the theme and works with the keyboard - background #09090b, surface #18181b, borders #27272a; each product supplies its own accent and icon - 40px controls on desktop, 44px touch targets - visible focus, contrast, reduced motion respected
check it
open a new chat and ask: "what are the design rules in this project?"
if it lists them, it's reading the file. if it doesn't, check the file sits at the root of the project first.
then ask it to build one screen and hold it against the 5 rules. if it breaks one, name the rule, not "make it look better".