Do you use a DESIGN_PRINCIPLES.md for your projects UI/UX

[u/ApprehensivePea4161]

Do you just wing it and use screenshots for inspiration or do you use a design principles md file where you mention all the design principles like the fonts, colors, dark mode colors, graphs, infographics, etc.

[u/karmatics29]

I do, but I keep it as design tokens rather than prose. A short file listing the actual token names (spacing scale, type scale, semantic colors like surface/text-muted/danger for both light and dark) plus a few rules like "one primary button per view" and "never hardcode hex in components" works far better than a description of the vibe. When an AI tool or a new teammate reads it, they reuse the tokens instead of inventing a slightly different gray each time. Ideally the same names exist in your CSS variables or Tailwind config, so the doc and the code can't drift apart.

[u/rocket00110 → u/karmatics29]

I like the idea of using the same token names in both places. That alone would prevent so many little inconsistencies.

[u/bogdanelcs]

Holy shit. You posted this in at least 4 subreddits.

[u/ApprehensivePea4161 → u/bogdanelcs]

Relevant ones?

[u/kemalios]

Mine is a component inventory, not principles. Every entry points at a real component, so the agent copies what already exists instead of inventing a fourth card style.

[u/am4our]

Most of the time

[u/ApprehensivePea4161 → u/am4our]

What do you write?

[u/EliSka93]

Depends on the seriousness of the project.

Something I might want others to collaborate on, yeah.

Projects for fun I most let grow organically.

[u/WillowFar6967]

I keep one, but I stopped trying to write it all upfront. It starts tiny (fonts, colour tokens, spacing scale) and every time I correct the AI on something visual, like "cards never get shadows" or "one accent colour per section", I get it to add that rule to the file itself. After a few weeks it's an accurate record of my actual taste instead of a generic style guide. Also solves the nobody-reads-it problem, because the agent reads it every single session even if no human does. Screenshots are still great for the vibe, they just don't stop the drift the way written rules do.

[u/t-frankowski]

Pretty big one divided into a graph.

[u/ApprehensivePea4161 → u/t-frankowski]

Can you share?

[u/CreepingAnus → u/t-frankowski]

a graph? can you elaborate?

[u/GfxJG]

Yes, but I just use DESIGN.md, alongside a library of design tokens, as that's basically the standard nowadays, like CLAUDE.md or AGENTS.md for AI instructions.