@bassam.cz
Free guide · DESIGN

The 5 design rules I give my AI

Paste them in once, so every app starts from the same rules.

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

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.

copy this into your file

Copy this
## 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".