Solving Design Debt in AI Coding Tools with a Single Design.md File
makedreamMay 8, 2026
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
Throw a few prompts at an AI coding tool, and you'll get a decent-looking page. The problem comes next: the corner radius of a newly generated button differs from the adjacent page, and the brand color's saturation is subtly off. Development is fast, but the output is sloppy. This happens because AI defaults to common average values when it lacks context. To solve this, you must plant a Design.md file in your project root and enforce strict constraints on the AI.
Asking an AI to use a “sophisticated blue” is a waste of time. AI thrives on normalized data, not adjectives. Specify your design system by breaking it down into three layers: Primitive, Semantic, and Component.
blue-500: #3B82F6.bg-primary: var(--blue-500).[category]-[property]-[modifier] format to make it use names like $color-background-hover.According to a 2025 UI collaboration case study, teams using these structured tokens reduced UI bug rates from 14 to 4 per sprint. When AI starts choosing classes based on function rather than color codes, 70% of design revision time disappears. If you use Tailwind CSS, command the AI to map these tokens one-to-one with tailwind.config.js.
AI makes foolish choices when given too much freedom. To maintain consistent margins across pages, you must hammer the numbers into a table format within your specification.
| Property | Value | Application Rule |
|---|---|---|
| Button Radius | 8px | Fixed to rounded-lg, no arbitrary changes |
| Section Spacing | 64px | Vertical spacing between all major sections |
| Max Width | 1280px | Centering limit for main content |
Limit spacing units to multiples of 8px and fix card padding to 24px. Creating an “Anti-pattern” section is particularly effective. By including prohibitions like “Do not use more than 3 CTA buttons on one screen” or “Use a 1px border instead of shadows,” the AI filters out wrong candidates before starting the task. This simple table can cut manual fix counts by more than half.
An app looks cheap when the tone of voice varies by feature or icon styles are mixed. Explicitly state the brand persona in Design.md. You must pre-determine whether a success message should be “Update complete” or “You're all set!”
For icons, follow this protocol:
stroke-width of all icons to 1.5px.Dark mode follows the same logic. Simply inverting colors ruins readability. Specify a deep gray (#121212) instead of pure black for the background, as recommended by Google Material Design guidelines, and include a formula to maintain a contrast ratio of to automatically avoid accessibility bugs.
No matter how well you write the specification, it's meaningless if the AI doesn't read it. Create UI-specific rules in the .cursor/rules/ directory and force the AI to reference Design.md before every task. 2025 development data shows that teams adopting this routine shortened average feature development time from 12.5 hours to 8.1 hours.
Now, developers don't fix code; they change the impression of the entire service just by adjusting numbers in a document. Design gains speed when it's treated as a realm of precision engineering rather than just intuition. 30 minutes of documentation at the start prevents dozens of hours of trial and error later.