Claude Design wrote DESIGN.md — why is the design still off?

Recently, while building a product, I had Claude Design put together a DESIGN.md.

It had colors, fonts, spacing, corner radii, components and responsive rules, and said the product should be “simple, professional, modern.”

Nothing obviously wrong.

But I always felt something was missing.

Only after building a few more pages did I realize:

it explained what the interface should look like, but not why the product should be designed that way.

DESIGN.md and a design system aren’t the same thing

Simply put:

a design system is the design framework the product actually runs on. DESIGN.md is the description and set of constraints that helps people and AI understand, use and maintain that framework.

A design system is closer to the real assets:

• design tokens
• the component library
• a Figma library
• the code implementation
• component states and usage rules

DESIGN.md, on the other hand, should explain:

• what the product’s most important experience goals are
• how information should be organized
• what principles the key flows should follow
• how AI output is presented and reviewed
• which design decisions agents mustn’t change at will

It can describe the design system, but it isn’t the design system.

Many DESIGN.md files only cover the last two layers of design

AI easily generates rules like:

Use an 8px spacing system. Use rounded cards. Keep the interface clean and modern. Buttons have primary and secondary variants.

These rules make an interface more consistent, but they can’t guarantee the product makes more sense.

If you roughly break design down, it goes:

product goals and user tasks

↓

information architecture and content hierarchy

↓

task flows and how pages relate

↓

interaction behavior and system states

↓

visual language and components

↓

consistency and implementation constraints

Many DESIGN.md files only cover the last two layers.

But when a page “just looks wrong,” the problem is often higher up.

Working this out isn’t only for the agent

A lot of the time, only once you’ve worked out for yourself:

• what the product is really helping users accomplish
• which information matters most
• how the pieces of information relate
• which judgments can be handed to AI
• which controls must stay with the user

can you guide an agent effectively.

An agent can help break problems down, spot omissions and propose different options.

But it can’t decide for the product owner:

what this product should really emphasize.

If you’re not clear yourself, even the most complete DESIGN.md may only help the agent guess more methodically.

When the design isn’t good, I check from the top down

1. The product task

First ask:

• what users come to this page to accomplish
• what the most important judgment is
• what the most important action is
• whether the page is displaying information or helping users decide

For example, the goal of a job-fit report shouldn’t just be:

displaying an AI-generated analysis.

It should be:

helping users judge whether this role is worth the effort, and how to position themselves.

The former easily turns into a very long report.

The latter needs to foreground the conclusion, the evidence, the risks and the next steps.

2. Information architecture and hierarchy

Check:

• whether the most important information appears first
• whether facts, inferences and suggestions are mixed together
• which content should sit side by side and which should be subordinate
• whether, because everything is important, nothing stands out in the end
• whether each card really represents an independent object

AI loves putting every section into a card.

The page ends up very tidy, but with no clear sense of what matters most.

A card is just a container; it doesn’t create information hierarchy by itself.

3. Flow

Information architecture answers “what goes on the page.”

Flow answers “how users get the task done.”

Check:

• where users come in
• where they go next
• whether they have to re-enter or reconfirm things
• what AI does and what users review
• whether the flow can continue when something goes wrong
• whether a single page is still needed once placed in the whole flow

Sometimes a page looks fine on its own, but within the whole task it seems redundant or out of order.

4. Interaction and states

AI products can’t only design the screenshot of “results generated successfully.”

You also need to consider:

• before generation
• during generation
• generation failure
• insufficient data
• user edits
• user rejection
• regenerating
• comparing results
• saving and undoing

Without these states designed, a product can usually only be demoed, not really used for work.

5. Visual hierarchy

Once the structure above holds up, then check:

• whether font sizes and weights express the right hierarchy
• whether white space aids understanding
• whether contrast highlights what really matters
• whether there are too many borders, backgrounds and containers
• whether every module is competing for attention
• whether the information density suits the task

Visual design isn’t a makeover for a messy structure.

It should express relationships that have already been thought through.

6. System and implementation

Finally, check:

• whether existing tokens and components were reused
• whether the same pattern is consistent across pages
• whether global styles were changed to fix one page
• whether a shared component was created for a one-off difference
• whether Figma, the code and the docs each say something different

If the product judgment above doesn’t hold, the more consistent the system, the more reliably the mistakes get copied.

A good DESIGN.md needs at least four kinds of content

Product experience principles

Don’t just write:

Clean, modern and intuitive.

More useful is:

• help users make judgments, rather than just displaying AI output
• separate facts, inferences and suggestions
• important conclusions must let users see the basis
• AI-generated changes must be reviewable
• don’t dress uncertain judgments up as precise answers

These rules really change the design.

Product-specific patterns

For example, common ones in AI products:

• recommendation + evidence
• AI output + human review
• original content + suggested changes
• confidence / uncertainty
• loading / failure / retry / approval

These patterns usually matter more than how many sizes a button comes in.

Visual and component rules

Including:

• tokens
• typography
• layout
• spacing
• responsive behavior
• component usage
• states such as loading, error and disabled

They’re still needed, but they aren’t everything.

Boundaries for agents and development

For example:

• reuse existing components first
• don’t write raw hex values directly
• don’t create shared components for one-off styles
• don’t change global rules to fix a local problem
• don’t invent business concepts on your own
• don’t change the information hierarchy without a basis
• don’t wrap every section in a card

The problem with coding agents often isn’t that they can’t do it.

It’s that they make locally reasonable-looking decisions that gradually make the whole product drift.

DESIGN.md isn’t better for being longer

To judge whether a rule is worth keeping, you can ask:

will it help a designer, developer or agent make a different decision?

If not, it may just be decoration.

If it can’t be executed or checked, it easily becomes a slogan too.

An early product doesn’t need a huge design system from the start.

What it needs more is a limited set of rules that are actually followed.

Only later did I understand that what I felt was missing from that DESIGN.md wasn’t a few more components.

What it lacked was the higher-level design judgment:

what task users are accomplishing, how information should be organized, what AI should do, and what control people should keep.

So when AI produces a design that isn’t good, don’t rush to ask it:

Make it cleaner. Make it more modern. Use better spacing.

Step back a few layers first.

Not to write a more complicated prompt, but to confirm first:

whether you’ve really thought it through yourself, and which design judgments you can’t leave the agent to guess.