I Gave Claude Code a Design System (Refero + DESIGN.md)

· Experiments

I built the same app twice — raw prompts vs Refero + DESIGN.md. The before/after output and why giving Claude a design system matters.

Last updated: August 20, 2025 · 6-minute read

Claude Code built me a dashboard last week. Three components: a sidebar, a data table, and a stats card row. The code worked. The design looked like it was made by someone who has never seen a good dashboard.

Default blue primary. Random border radiuses — 8px on the cards, 12px on the buttons, 4px on the inputs. A font stack of system-ui and nothing else. Spacing that had no consistent rhythm. It was functional in the way a wireframe is functional.

Then I gave it a DESIGN.md file pulled from Refero Styles and rebuilt the same three components. The difference was not subtle.

What Refero Styles Actually Is

Refero Styles is a library of 2,000+ design systems extracted from real product websites and formatted as DESIGN.md files — structured markdown that AI coding agents can read and follow. Each file includes color tokens, typography scales, spacing systems, border radius rules, shadow definitions, and component-specific notes.

The viral Instagram reel selling the concept was straightforward: "Comment 'MD' and I'll send you the link. Here's how to design better than 99% of people building with AI." The engagement loop worked — but the product underneath is real.

Mike Bespalov's team crawled 2,000+ product websites, extracted their design systems, and structured them as markdown files that Claude Code, Cursor, Codex, v0, and Lovable can consume directly. No Figma. No CSS variables to set up manually. Paste the file, start building.

The Experiment: Same App, Two Builds

I built a simple task management mini-app in Claude Code twice. Same prompt structure, same feature set (add tasks, mark complete, filter by status, dark mode).

Build A — No design system. Standard Claude Code with a generic prompt: "Build a task management app with dark mode."

Build B — Refero DESIGN.md. Same prompt, but with a Linear-inspired design system pasted into the project root as DESIGN.md and referenced in CLAUDE.md: "Follow the design rules in DESIGN.md for all UI decisions."

Before (Build A)

The output was technically correct. React components, state management, localStorage persistence — all working. But the visual output was what I'd call "AI default":

  • Colors: Tailwind's default blue-600 as primary. No secondary color. Background was slate-900 with no nuance.
  • Typography: System font stack. Everything the same weight. No hierarchy.
  • Spacing: Inconsistent. Some sections had p-4, others p-6, the card grid had gaps that didn't align with the outer padding.
  • Components: The "complete task" button was the same visual weight as "delete task." The sidebar was wider than the content area. The filter chips looked like default HTML buttons.

It looked like every other Claude Code output I've seen — functional, but immediately recognizable as AI-generated.

After (Build B)

The same app, same features, same Claude Code session. But with the design system active, the output changed in specific ways:

  • Colors: The primary shifted to a muted indigo from the Linear design system. Background used a two-tone dark scheme (darker sidebar, lighter content area). Status colors (green for complete, amber for in-progress) were predefined.
  • Typography: Inter as the UI font, with defined weight mappings — semibold for headings, medium for body, regular for secondary text. Line heights were consistent at 1.5.
  • Spacing: Everything snapped to a 4px grid. Card padding was consistently p-5 (20px). Gaps in the grid were gap-4 (16px). The layout felt intentional.
  • Components: The "complete" action was a checkbox with a green check animation. The "delete" action was a red icon button — lower visual weight, accessible but not prominent. The sidebar was fixed-width. The filter chips had defined active/inactive states with proper border and background tokens.

The code was also more consistent. Since the design system defined component patterns, Claude didn't invent a new button style for every instance.

What Didn't Improve

I want to be honest about the limitations because the hype around Refero Styles is getting out of hand.

Layout logic didn't change. The design system handles visual tokens — colors, fonts, spacing. It doesn't help Claude decide where elements go or how the page flows. Build A and Build B had nearly identical component structure and layout. If you have a bad layout prompt, a good design system won't save you.

The DESIGN.md has to match your intent. I tried a Linear-inspired system for the task app and it worked because both are productivity tools. When I used the same system to build a creative portfolio, the result was too rigid — the muted indigo and tight spacing didn't fit the context. You need to pick a design system that matches what you're building.

Claude sometimes ignores it. In longer sessions, as the context window fills up, Claude starts falling back to default patterns. The design system works best in the first 30-40 minutes of a session. After that, you may need to re-paste the relevant tokens.

The Knowledge Graph Connection

There's a parallel tool that solves the context problem from the code side. Graphify — "Graphify — Open-Source Knowledge Graph Skill for AI Coding" — maps your entire codebase into a knowledge graph so the AI agent can navigate structure instead of guessing. A YouTube video by Soumil Shah titled "Graphify vs. Caveman: Two Clever Tools That Make Your AI Coding Assistant Way Smarter" breaks down how both tools reduce unnecessary context loading.

Graphify hit 58,000+ GitHub stars in its first two months. The founder posted on r/ClaudeAI: "On April 5th I shipped a Claude Code skill called graphify. Type /graphify and it reads every file in your repo, builds a knowledge graph." It works alongside design systems — Graphify handles the code structure, DESIGN.md handles the visual structure.

TL;DR

  • Refero Styles gives AI agents a real design blueprint instead of letting them default to generic Tailwind.
  • The before/after difference in visual quality is significant — consistent tokens, intentional color choices, proper spacing grids.
  • It doesn't fix layout logic. A bad prompt with a good design system still produces a bad layout.
  • Pick a design system that matches your project type. Linear-inspired for productivity, Vercel-inspired for dev tools, etc.
  • Works best in the first 30-40 minutes of a Claude Code session before context degrades.
  • Pair with Graphify for code-side context and you get a pretty complete agent setup.

This experiment sits alongside the other agent tooling I've been testing — the Google Antigravity 2.0 deep dive covers the orchestration layer, and the Lab section has live demos of what these agent setups actually produce.

---

Not affiliated with Refero Styles or Graphify. Experiment conducted with Claude Code in August 2025. Tools used: Refero Styles (free tier), Claude Code, Graphify skill.