Reading Guide:
Intro | Principles | Composition | Design system | Imagery | Motion | Conclusion
What is a DESIGN.md file?
A DESIGN.md file is a portable design specification that helps AI understand how a design system should look, feel, and behave.
Most design systems contain much of the information needed to create an interface: typography, colors, spacing, components, and styles. In WordPress, theme.json can define these decisions with considerable precision.
But implementation is not the same as intent.
A color value can tell AI which color to use. It cannot explain why that color exists, how prominently it should appear, or when another color would be appropriate. A spacing scale can provide values without explaining which relationships should feel tight and which should feel expansive.
Design requires judgment.
DESIGN.md attempts to make some of that judgment explicit. It describes the principles, constraints, and visual language behind a design system so AI does not have to infer them entirely from code or screenshots.
There is no established standard for a DESIGN.md file. I am exploring what one might look like and how it might function as AI becomes increasingly capable of designing and building digital experiences.
I recently added one to Suede, the design system behind my WordPress work and creative explorations. The distinction is quite simple: theme.json defines implementation; DESIGN.md defines intent.
Principles
Suede begins with principles rather than tokens.
Before AI knows which font to use or how much space belongs between two elements, it should understand the broader ideas governing those decisions.
The DESIGN.md file establishes these rules:
Restraint does not mean minimalism. Suede should feel refined and intentional, never sparse, timid, or under-designed.
Prefer fewer, stronger ideas. Give important elements enough scale, space, contrast, and visual weight to establish presence.
Use typography, imagery, spacing, and contrast to create clear hierarchy before adding decoration.
Use generous space to create rhythm and focus, but do not create emptiness for its own sake.
Repetition creates coherence. Introduce variation when it serves the content, not simply to make sections look different.
Suede’s design capabilities are a vocabulary, not a checklist. Use them selectively.
These principles establish the character before its visual properties.
That matters because AI can follow specifications too literally. Giving it every capability without the underlying philosophy can result in technically correct design that still feels wrong.
The goal is not to use everything Suede makes available, but to understand what makes something feel like Suede.
Composition
A design system can easily become a collection of components.
Suede treats composition differently:
Every composition should have a clear visual priority. Establish what deserves attention first, then make supporting elements visibly subordinate.
Use controlled contrast to create tension and hierarchy. Pair large with small, dense with open, image with type, and dominant with quiet. Restraint should limit competing ideas, not their scale.
Design relationships rather than assembling components. Begin with the visual relationship the content should create, then introduce only the elements needed to construct it.
Let important elements carry meaningful visual weight. Typography and imagery may become architectural elements within a composition. When something deserves presence, give it sufficient scale and territory.
Create rhythm through repetition and change. Repeat structures within a composition to establish order, then vary composition between sections when the content calls for a change in emphasis, pace, or mode.
Prefer subtraction. Before adding an element, determine whether hierarchy, typography, space, imagery, or contrast can accomplish the same purpose.
“Design relationships rather than assembling components” may be the most important instruction in the file.
AI is already capable of assembling competent interfaces from familiar patterns. The harder problem is composition: understanding what deserves attention, establishing relationships between elements, and creating hierarchy without filling every available space.
That requires more than a component library.
Design system
Principles and composition establish intent. The design system translates that intent into a more concrete visual vocabulary.
This is where DESIGN.md begins to overlap with traditional design tokens, but with an important difference: values are accompanied by guidance about how they should be used.
Typography
Use Google Sans Flex as the primary typeface. Its variable width may be used expressively, with 110% expanded or 85% condensed treatments creating contrast while preserving typographic continuity. Use width selectively rather than as a default treatment.
A secondary or accent typeface may also be introduced when it strengthens the character, subject, or editorial quality of the design. Use it selectively and maintain clear typographic hierarchy rather than creating variety for its own sake.
Set body text at 18px, 400 weight, with generous line height. Headings use 500 weight with tight line height and no added letter spacing. Use 600 weight selectively for strong emphasis rather than as a default display weight.
Use Suede’s type scale as a controlled hierarchy: 12, 14, 16, 18, 20, 24, 30, 36, 48, and 60px. Sizes above 18px may scale fluidly with the viewport. Avoid arbitrary intermediate sizes when the existing scale can establish the relationship.
Large type should feel architectural when the composition calls for presence, but scale should always communicate hierarchy rather than decoration. Keep supporting copy visibly subordinate.
Use uppercase text, 0.05em letter spacing, and medium weight primarily for small navigational, label, metadata, and eyebrow treatments. Do not extend this treatment to long-form copy or prominent display typography.
This is more useful to AI than simply declaring a font family and type scale.
Google Sans Flex is the foundation, not a restriction. The system encourages variation within the typeface before introducing another one, while still allowing an accent typeface when the subject or identity benefits from it.
Color
Build primarily with black (#000000) and white (#ffffff). Use accent gold (#aa6600) as the default accent, applied deliberately for emphasis, interaction, rules, borders, and small moments of identity rather than as a dominant field color.
The accent color may be replaced when another color better serves the character, subject, or identity of the design. Prefer a single, purposeful accent that maintains strong contrast and preserves Suede’s restrained color system.
Use opacity variants of black (80%, 60%, 50%, 15%, 10%), white (80%, 60%, 50%, 15%, 10%), and accent (80%, 60%, 50%, 20%, 10%) to establish hierarchy while preserving the core palette. Prefer tonal variation within the system over introducing unrelated grays or secondary colors.
Maintain strong contrast for primary content. Softer opacity values are appropriate for secondary text, borders, backgrounds, overlays, and subtle depth, but should not weaken legibility.
Suede’s directional gradients are functional rather than decorative. Use Fade Down, Fade Up, Fade Right, or Fade Left when imagery needs contrast for overlaid content or when a composition benefits from controlled tonal depth. Avoid decorative gradients outside this vocabulary unless the concept clearly requires one.
#aa6600 tells a machine what Suede’s accent color is. DESIGN.md tells it that gold should be used deliberately, should not dominate the composition, and can be replaced when another accent better serves the identity.
Layout and spacing
Treat 640px as the primary reading width and 1280px as the wide composition width. Long-form text should generally remain within the reading measure, while imagery, covers, grids, and more expressive compositions may use the wider canvas.
Use the spacing scale 20, 30, 40, 60, 80, and 100px. Favor these values over arbitrary spacing so relationships remain coherent across the experience.
Use smaller values to connect related elements and larger values to separate sections, ideas, or changes in visual mode. Major sections should usually receive more space than the internal relationships within them.
Generous spacing is part of Suede’s character, but space must establish rhythm, focus, or hierarchy. Do not increase spacing merely to make a composition feel more luxurious or minimal.
The last rule is important.
“Use generous spacing” is easy for AI to interpret as “use more whitespace.” But whitespace without purpose can make a design feel empty.
The spacing values matter. The relationships they create matter more.
Responsive behavior
Responsive design should preserve the hierarchy of a composition rather than merely rearrange it.
Preserve hierarchy as the canvas narrows. Allow type, spacing, imagery, and composition to scale or simplify deliberately rather than treating responsive design as a mechanical collapse of the desktop layout.
Stack elements when necessary, but retain the intended visual priority and relationships between them. Reduce complexity before reducing clarity.
DESIGN.md does not need to prescribe every breakpoint or responsive behavior. Those belong in implementation; instead, it should explain the intent and relationships that must survive as implementation changes.
Accessibility
Maintain sufficient contrast, legible type, semantic hierarchy, and visible focus states throughout the experience. Accessibility should reinforce Suede’s clarity and restraint rather than be treated as a separate visual layer.
Respect reduced-motion preferences and ensure that meaning, navigation, and interaction never depend on animation alone.
Shape and depth
Favor square, direct geometry. Buttons, form controls, separators, and primary interface elements should generally feel crisp rather than soft or pill-shaped. Rounded corners are available when the content or concept benefits from them, but they should be an exception rather than a default visual signature.
Use borders and rules sparingly, typically at 1px, to define structure without creating visual noise.
Treat shadows as accents, not ambient decoration. Suede’s shadow vocabulary includes a soft neutral shadow, a solid offset accent shadow, and a subtle offset accent shadow. Use them selectively when an element needs separation or deliberate graphic emphasis; avoid routine card shadows across the interface.
These rules prevent another common failure of generated interfaces: reaching reflexively for rounded cards, soft shadows, and familiar visual conventions simply because they are available.
Suede can use those techniques. It just needs a reason.
Interaction
Text links should remain visibly identifiable, normally through an underline. Hover states may shift toward the accent color while preserving clarity and contrast.
Primary buttons use the accent color, strong rectangular geometry, uppercase small text, medium weight, and generous padding. Outline buttons should retain the same visual discipline rather than becoming visually lighter in hierarchy than intended.
Interactive feedback should be immediate but quiet. Prefer color, border, or restrained transform changes over elaborate effects. Focus states must remain visible and should not be removed for aesthetic reasons.
Interaction should reinforce the visual language rather than introduce a new one. The phrase I keep returning to is immediate but quiet: feedback should communicate state without becoming the experience itself.
Iconography
Use Google Material Symbols Sharp for interface and supporting iconography, with a 200 weight and 48px optical size to maintain Suede’s refined, restrained visual character.
Use icons selectively and at purposeful scale. They should clarify meaning, navigation, or interaction rather than serve as decoration. Prefer simple, recognizable symbols and maintain consistent weight and visual treatment throughout an experience.
Even a small choice like iconography can change the character and tone.
Imagery
Imagery carries substantial visual weight in Suede, so DESIGN.md gives it more direction than simply defining aspect ratios or image sizes.
Imagery should reinforce the subject, character, and purpose of the experience while carrying meaningful visual weight within the composition.
Prefer fewer, substantial images over small decorative imagery. When imagery is appropriate for homepage hero sections, prefer a full-width Cover block with a strong visual. When text overlays the image, consider Suede’s Fade Down gradient to support legibility and atmosphere.
When generating imagery, favor natural, refined visuals with restrained color and tonal qualities that complement Suede’s visual system rather than compete with it.
Choose imagery, cropping, focal point, scale, and positioning according to the composition. Crop for the composition, not merely to keep the subject visible. Do not use imagery merely to fill space.
This becomes increasingly important when AI is responsible for both generating imagery and designing the interface around it.
“Use a large image” is not enough.
The image, crop, focal point, typography, contrast, and surrounding space are all part of the same composition.
Motion
Motion presents the same problem.
Telling AI to “use subtle animation” leaves substantial room for interpretation. Suede instead defines both the intent and the vocabulary:
Motion should reinforce hierarchy, focus, and interaction without calling attention to itself.
Prefer subtle transitions and Suede’s existing motion vocabulary over decorative animation. Use motion to introduce content, clarify interaction, or add depth where appropriate.
Use 250ms for quick interface transitions and 500ms for larger visual movement. Favor ease-out timing so motion feels responsive and settles naturally.
For entrance motion, use a restrained travel distance of approximately 30px. For image zoom interactions, use a subtle scale of approximately 1.05. These values should feel barely perceptible rather than theatrical.
Animation should feel deliberate, restrained, and consistent across the experience. Avoid effects that compete with the content or exist only for novelty.
Respect reduced-motion preferences. Motion is an enhancement to hierarchy and interaction, never a requirement for understanding or navigation.
Application
The final section of Suede’s DESIGN.md may be the most important:
Treat these specifications as constraints, not templates. Use them to preserve Suede’s visual character across different subjects and media, but depart from them when the content, context, or medium clearly benefits from doing so. Any deviation should strengthen the composition rather than add novelty.
A useful design system should create coherence without producing sameness.
That becomes especially important with AI. If every instruction is interpreted as an absolute requirement, the system becomes a template. If every decision is optional, it stops being a system.
The goal is controlled freedom.
Suede establishes defaults, constraints, and principles while leaving enough room for a particular subject or identity to influence the result.
Design systems for humans and machines
Design systems have traditionally been expressed through artifacts created for humans and software. Designers use guidelines and libraries; developers use CSS, design tokens, components, and files like theme.json.
AI introduces another participant. It can read those artifacts, but reading an implementation and understanding the thinking behind it are different things.
That is the territory I am exploring with DESIGN.md: a lightweight layer that explains the design intelligence behind the system—what should dominate, what should remain quiet, and which relationships matter.
That is why DESIGN.md now lives at the root of Suede. The theme contains the implementation; DESIGN.md explains the intent.
Now Suede can tell AI not just what it is, but how it wants to be designed.