Build a personal website from 0
AI Websites All Look the Same? Fix It With a Design Spec (2026)
AI-built sites default to purple gradients and emoji cards because they get no design decisions. Write a DESIGN.md spec the AI follows, with a template.
Kelvin Wang · · 17 min read
Key points
- AI sites look alike because the AI gets no design decisions and falls back on what it has seen most; switching tools likely won't change that.
- Purple gradients, a centered hero with two buttons, emoji cards, default fonts and stock copy are the easiest tells to spot.
- Put colors, type, spacing, motion and mobile rules in a DESIGN.md at the project root and have the AI read it before every visual change.
- Add reference images, your own copy, and screenshot checks at phone and desktop width, and the site starts to look like yours.
My site, kelvinwang.info, has run on a design spec called DESIGN.md since September 28, 2026, and every AI coding session has to read it before touching anything visible. By mid-November it was close to 600 lines long, with more than a hundred commits in its git history. AI-built sites look alike because the AI gets no design decisions; this site’s answer is to write those decisions into a DESIGN.md and have the AI read it first every time.
Why do AI-built websites all look the same?
An AI coding tool produces the most likely answer to your prompt. Ask for “a personal website” and the most likely answer is the kind of site it has seen most often. Anthropic described this pattern in its own models in November 2025: given no guidance, Claude almost always reaches for Inter, purple gradients on a white background and minimal animation, because safe design choices that work everywhere dominate the examples on the web, and the model samples from that center1.
In my judgment, a few things pull the output even closer to that center:
- Popular component libraries and CSS framework defaults get used everywhere. Lots of sites share the same components, default colors and corner radii, so that’s what a “normal website” looks like to the AI.
- Vague prompts. “Modern, clean, professional” describes nearly every site, so it rules nothing out.
- No reference images. From words alone, the AI can’t know which kind of “clean” you mean.
- No brand constraints. If you don’t name an accent color, a font, or whether gradients are allowed, it picks, and it picks the most common option.
- Every session starts from zero. The colors you agreed on last time are gone in a new session, so it slides back to the defaults.
I’d expect the same from any tool: Claude Code, Cursor, Codex, v0 or Lovable will all fill missing decisions with the most common choice.
Six signs a site came from an AI template
- Purple or indigo gradients. A purple-to-blue gradient headline or button on white is the one Anthropic itself names1. Instead, pick one accent color you can give a reason for, and if you want a gradient, confine it to one place. On November 11, 2026 I picked from six palette proposals and chose “warm paper and electric cyan”: off-white and warm-black backgrounds with cyan as the brand color. The only gradient text is the last line of the home page headline, and the spec says “gradient only here”.
- A centered hero with two buttons. One big tagline, one subline, “Get started” and “Learn more”. Instead, decide what the first screen has to tell people; it may not need a button at all. My home page is a field of animated dots that forms a circuit board, a signal eye diagram, a Wi-Fi antenna pattern and a candlestick chart in turn, and when you scroll the dots fly into the topic cards and become each topic’s icon. Since November 10, 2026 there have been no buttons under the headline.
- A row of emoji or stock-icon feature cards. Three columns, each with an emoji, a bold title and two lines of text. Instead, draw icons in the same visual language as the rest of the site, or leave them out. My topic and tool cards use the same dot icons as the home page.
- Identical radius, shadow and spacing on every card. When the whole page is one card style repeated, nothing stands out. Instead, use a spacing table that decides what sits close and what sits apart, and build hierarchy with type size and white space rather than shadows. My home topic cards and Lab cards have no shadow, just a 0.5px border that turns brand cyan on hover.
- A default font nobody chose. Inter for English and whatever the browser picks for Chinese. Instead, choose once and write it in the spec. I chose system fonts (SF Pro plus PingFang on Macs and iPhones) and load no web fonts. Chinese fonts cover thousands of characters and are large files, so if you do use a CJK web font, subset it so the browser downloads only the characters a page needs, and compress it as WOFF2; web.dev notes subsetting matters most for Asian languages with large glyph counts2.
- Stock copy. “Crafting exceptional digital experiences”, “Welcome to my website”: sentences that fit any site. Instead, write your own, about things only you can say, such as what you built, which tools you use and what went wrong. AI can tighten your sentences, but it can’t make up your experience. My writing rules also ban sentences that describe the page itself (“Below you’ll find my work”).
All six have one thing in common: the AI filled them in because nobody gave it a constraint. Writing the constraints down is what the design spec is for.
Why a file beats telling the AI in chat
Saying “make headings dark blue and round the buttons” in a chat works, for that chat. Switch tools or hand the project to someone else and there’s nothing at all.
A file fixes that. It lives in the repo next to the code, so every change to it is in version control. AI tools read a project instructions file automatically: Claude Code reads CLAUDE.md, Codex reads AGENTS.md before doing any work3, Cursor supports an AGENTS.md in the project root4, and Lovable has project-level Instructions that are included whenever it generates a response5. One line there pointing at DESIGN.md means every session sees it. It also holds you to your own decisions: three months later, when you want to add a color, you’ll see why you limited yourself in the first place.
The first rule in my CLAUDE.md is:
- **Design spec: read `DESIGN.md` before changing anything visible** (public site, `/app`, new pages or components).
It is binding for the whole repo; if you need to break a rule, update `DESIGN.md` first and say so.
The last sentence matters most. When the spec and the code disagree, the AI can’t tell which one to trust. “Change the spec first, then the code” keeps them in sync.
Go deeper Claude Code Tutorial 2026: Install, CLAUDE.md, Skills, and Your First Website Where CLAUDE.md goes, what to put in it, and how to make sure it's read every session.Five decisions to make before you write it
You don’t need a design background. Answer these and you have the skeleton of a spec:
- Who the site is for and how it should feel. Pick two or three sites you like and write down what you like about each.
- Dark mode or not. If yes, every color needs a light and a dark value. Decide now; retrofitting it later hurts.
- One accent color. Just one. Everything else is neutral.
- Fonts. System fonts are the least work and load instantly. If you want a web font, name the family and the weights, and if it’s a CJK font, plan for its file size.
- Whether phones come first. For most personal sites they do, so the spec needs a section just for mobile.
The seven sections every design spec needs
1. Colors in two layers: raw values and semantic names
The most common mistake is letting the AI write hex codes (#1a62c2) or framework color names (blue-600) straight into components. Thirty components later you want a new accent color and have thirty places to change.
Define semantic tokens instead, named by role: page for the background, ink for main text, edge for borders, link for links. Components may only use those names; the actual hex values live in one CSS file. The first rule of my color section says components use the semantic layer only, never hex or neutral-*. When I swapped the whole palette in November, components didn’t need touching one by one: the work was mostly the values in that CSS file, plus a few places that can’t read CSS (share images, the site icon), which the spec also lists.
Measure contrast for every text color. WCAG level AA asks for at least 4.5:1 between normal text and its background6. My spec says the contrast numbers are “measured, not guessed”: every text token has to pass 4.5:1 on every background it appears on. Any contrast checker will compute it from two hex codes.
2. One meaning per color
A palette isn’t enough. Write down what each color means. On my site:
- Indigo is for links in text. Article subheadings use a deeper indigo of the same hue, so links in articles keep a faint underline and the two never get confused.
- Cyan is the brand color. One filled button per screen; every other button is outlined.
- Red only marks danger or things that have been tampered with. Never decoration.
Without a rule like this, AI tends to use color as decoration, a different color per card, and the page ends up with no focal point. My spec also says categories are never color-coded; they get text labels. The old category color tokens were deleted with a note not to add them back.
3. A type scale
One table: each text style, its size, line height, and where it’s used. I use iOS’s default sizes: 17px body, 15px for secondary text, 13px for group headings and the footer. Article text went up to 18px with a 1.85 line height on November 10, 2026, because long Chinese text needs more size and leading. With the table in place, the AI stops inventing a new font size on every page.
4. Spacing and width
This section often gets skipped, yet much of whether a page looks tidy comes down to it. My spacing sits on a 4px grid and is set by how two elements relate, not by which page they’re on: two lines of the same item are 4px apart, a heading sits 12px above its content, paragraphs are 20px apart, and text sits 24px from blocks like cards and tables (articles have their own, looser reading scale). The reading column tops out at 680px, so a line of Chinese text stays under about 40 characters.
I only added this section on November 4, 2026. Before that, the breadcrumb on mobile sat 12px under the nav bar, nearly touching it, and paragraph spacing varied from page to page. Once it was a table, every new page picked its numbers from it.
5. Motion
Three things cover it: which easing and duration for which situation, which properties may animate, and what happens when the visitor has asked for reduced motion. My rules: animate only transform and opacity (the cheapest properties for the browser), 150ms for hover and color changes, decorative loops stop when they scroll off screen, and reduced motion shows a meaningful still frame instead of a blank.
6. Mobile
- Tap targets at least 44×44px.
- No horizontal scrolling at 390px wide.
- Full-screen heights use
dvh, notvh. Safari’s address bar throwsvhoff on iPhones. - Anything fixed to the top or bottom clears the notch and home indicator (safe area insets).
7. A checklist for after every change
This is how the AI checks its own work. Mine has eight items, such as: looked at both light and dark themes, measured contrast for any new color, every animation has a reduced-motion branch, actually viewed it at 390×844. One item is “write any new rule or deliberate exception back into this file”, which is how the spec grows with the site.
Free design spec template
The template follows the structure of my DESIGN.md, with generic starting values (the text colors are measured at 5:1 or better on both backgrounds), plus two extra sections: Components and Known gaps. Save it as DESIGN.md in your project root and replace everything in brackets with your own decisions.
# DESIGN.md: design spec for [site name]
Binding for the whole repo. Read this before changing anything visible.
If something conflicts with it, update this file first, then the code.
Priority: my explicit instructions in chat > this file > general design advice.
Status: unmarked rules are implemented; 🟡 = decided, not built yet.
## 0. Mobile
- Tap targets ≥ 44×44px.
- No horizontal scroll at 390px wide (check document.scrollWidth).
- Full-screen heights use dvh, not vh.
- Fixed top/bottom bars add env(safe-area-inset-*).
- Body text never below 16px.
## 1. Color tokens
Components use semantic tokens only, never hex or framework color names.
Actual values live only in [styles/global.css].
| token | role | light | dark |
|---------|-----------------------|------------|------------|
| page | page background | #ffffff | #0b0d10 |
| surface | cards, code blocks | #f5f6f8 | #15181d |
| ink | headings, main text | #111418 | #f2f4f7 |
| ink-2 | body text | #3a424d | #c3cad3 |
| ink-3 | captions, dates | #5f6b78 | #8e9aa7 |
| edge | borders, dividers | #dde2e8 | #262c34 |
| brand | accent: main button | [yours] | [dark ver] |
| link | links in text | #1f5fbf | #6aa8ff |
Contrast: every text token ≥ 4.5:1 on every background it appears on.
Recalculate before changing a value.
Before adding a color: can an existing role do the job? If not, add a new
role (not a new hue) with both light and dark values.
Gradients: [none / only in one named place].
## 2. What each color means
- link = links in text.
- brand = the brand. One filled button per screen; the rest are outlined.
- [error color] = error messages only.
- No color-coding for categories; use text labels.
## 3. Type
Font: [system font stack / named font and weights]. Components never set fonts.
| style | size / line height | weight | used for |
|--------------|--------------------|---------|-------------------|
| Page title | 34 / 41 | Bold | each page's title |
| Section | 22 / 28 | Bold | h2 |
| Body | 17 / 28 | Regular | article text |
| Secondary | 15 / 20 | Regular | second lines |
| Small | 13 / 18 | Regular | dates, footer |
## 4. Spacing and width
4px grid. Spacing is set by how two elements relate:
| relationship | value |
|----------------------------------|-------|
| two lines of the same item | 4px |
| label → the thing it labels | 8px |
| heading → its content | 12px |
| paragraph ↔ paragraph | 20px |
| text ↔ card / table / image | 24px |
Reading column max [680px]. Side padding: [20px] phone, [24px] desktop.
## 5. Motion
- Animate transform and opacity only.
- Hover/color 150ms; enter with ease-out; exits faster than entrances.
- prefers-reduced-motion: reduce → a still frame.
- No bounce. One focal point per screen.
## 6. Components
[List shared components and their rules, e.g. two button styles (filled /
outlined), card radius [16px], shadows or none, where icons come from
(drawn for this site / no emoji), tables become one card per row on phones.]
## 7. Checklist (after any UI change)
1. Checked light and dark themes.
2. Measured contrast for any new color.
3. No new hex values in components (grep).
4. Animations use transform/opacity only and have a reduced-motion branch.
5. Screenshots at 390×844 and desktop width: no horizontal scroll,
tap targets ≥ 44px.
6. New rules or deliberate exceptions written back here; unbuilt ones
marked 🟡 and listed under Known gaps.
## 8. Known gaps
| rule | current state | plan |
|------|---------------|------|
Getting the AI to follow it
- Point to it from your instructions file (
CLAUDE.md,AGENTS.mdor your tool’s project rules): “read DESIGN.md before changing anything visible.” - Make building the tokens the first task. For example: “Define the color tokens from DESIGN.md §1 in global.css, light and dark, and expose them to Tailwind by their semantic names.” Once the tokens exist, every page can only use those names.
- After every change, ask it to critique against the spec. “Check what you just changed against DESIGN.md §7 and report each item. Point out anything that breaks the spec or looks like a template.” Ask it to find problems, not whether it looks good.
- Turn the rules a machine can check into tests. My site has one test that fails if a component uses a raw Tailwind hue (
purple-400,indigo-500and so on) and another that fails if a public page uses vertical spacing outside the table. When the AI forgets the spec, the tests catch it. - Write adjustments back into the spec. The background glow on my site started at 10%/8% opacity in light mode. After seeing drafts I raised it to 22%/18%, because the same opacity over a near-white background is almost invisible. The numbers and the reason are in the spec, so nobody, human or AI, quietly changes them back.
- New colors come with a reason and a measurement. When I approved a red on October 23, 2026, the spec recorded its contrast on all three backgrounds and how far its hue sits from the brand and link colors.
It’s the same idea as writing a spec before writing a feature: write the decision down first, and the AI has something to follow.
Go deeper AI Built My Website and I Don't Understand the Code. How Do I Keep Maintaining It in 2026? Beyond the spec: the habits that keep an AI-built site changeable over time.What else keeps a site from looking like a template?
- Give reference images and say what you like about them. All five common tools take images. Claude Code accepts a pasted or dragged-in image or a file path7, Codex takes a pasted image or one passed with
--image8, Cursor’s agent reads image files in your project9, and v0 and Lovable both let you attach screenshots in chat; Lovable also lets you draw on a screenshot to circle what should change1011. A screenshot on its own gets copied wholesale, though: v0’s docs say it analyzes the layout, colors and components and generates code that closely replicates the design10. Add one sentence saying which part you want, such as “the big type and white space, not the colors”. - Ask for two or three versions and compare them side by side. My palette (six proposals) and the background glow opacity were both picked from several versions shown on one page, and the chosen values and reasons went back into the spec. Looking at one version at a time, it’s hard to tell whether you’re looking at the average.
- Write your own copy. However distinctive the layout, “Crafting exceptional digital experiences” still reads as a template. Write a few sentences only you could write, then let the AI tidy them.
- Check screenshots at phone and desktop width. When the AI says it’s done, have it screenshot the page at 390×844 and at desktop width, in both themes. A lot of template feel (cramped cards, buttons hugging the edge) only shows on a phone.
Pitfalls I hit
- The spec moves, the code doesn’t. A new rule doesn’t rewrite old pages. I mark rules that are decided but not built with 🟡 and keep a Known gaps table, and fix them whenever I touch the related files.
- A new component folder the CSS tool never sees. My public CSS only scans listed folders, so classes in a new folder silently didn’t get generated. That became a checklist item too.
- Checking only one theme. AI screenshot checks tend to look at the default theme only. The checklist says to flip the toggle and look at both.
Sources
- 1. Improving frontend design through Skills
- 2. Reduce web font size
- 3. Custom instructions with AGENTS.md
- 4. Rules
- 5. Instructions
- 6. Understanding SC 1.4.3: Contrast (Minimum)
- 7. Common workflows: Work with images
- 8. Codex CLI
- 9. Agent overview
- 10. Screenshots and Files
- 11. Work with Lovable in the project chat
Kelvin Wang
Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.
More about me