A week ago our website looked exactly like what it was: an AI-assisted project. Inter font. Cyan gradients. Symmetrical cards with generic shadows. Three perfectly balanced columns. A handful of Heroicons.
It worked. But it was completely forgettable. The visual equivalent of elevator music.
Today we have a distinct visual identity: an amber palette, editorial typography with three font families, numbered asymmetric layouts, dark/light mode with semantic tokens, and a personality that doesn't look like any template.
We did it in under 48 hours. Across 62 modified files and 30 commits. Without touching business logic. And here's the interesting part: the designer was Claude Code, fed with design skills that taught it to have taste.
This article tells you exactly how we did it.
The Problem: AI Slop on Steroids
If you've ever used a coding agent to generate interfaces, you know the aesthetic: Inter, purple or cyan, rounded cards, default box-shadows, three symmetrical columns. The dev community named it: AI Slop.
Our previous site fit that description perfectly. The palette used #06b6d4 (cyan-500) on #0f172a (slate-900) backgrounds. Sections were predictable: centered hero, card grid, generic CTA, standard footer.
The irony was glaring: a company that sells AI and automation systems shouldn't look like an unconstrained agent designed it. Our own product was betraying us.
We needed a change. But we didn't have a designer.
The Catalyst: An Article About Design Skills
We published Design Skills for AI Agents — an analysis of five tools that teach taste to coding agents. The core premise:
LLMs have no aesthetic judgment. When they generate an interface, they apply statistically probable patterns. The solution isn't switching models or writing longer prompts. It's giving the agent explicit design constraints.
While writing that article, we made a decision: let's apply it to our own site. If design skills work in theory, we had to prove it on ourselves.
The experiment:
- Define a complete design system in an executable file
- Give that file to Claude Code
- Ask it to rewrite every section of the site
- Iterate with refinement commands
The Process: 62 Files, 30 Commits, 3 Skills
Layer 1 — Foundation: Explicit Rules in CLAUDE.md
The first step was establishing absolute constraints. No "make it more modern" or "improve the design." Concrete rules:
## Design
- Never use Inter, Roboto, or Open Sans
- Never use cold gradients (purple, cyan, blue)
- Never use more than 3 colors per component
- Never use generic box-shadow (0 4px 6px -1px)
- No symmetrical cards with 8px border-radius
- No Heroicons as primary decoration
- Every color must reference a semantic token, never a raw value
Layer 2 — System: DESIGN.md with the Complete Identity
The second step was defining the design system in a structured 9-section file following the DESIGN.md standard:
1. Visual Atmosphere: Warm, editorial, technical without being cold. Like an architecture magazine meets a Kubernetes terminal. Amber as the accent color evokes guayoyo coffee — familiar, Venezuelan, anything but corporate.
2. Semantic Color Palette:
:root {
--color-base: #09090B; /* Main background - warm black */
--color-surface: #141210; /* Surfaces - near-black brown */
--color-overlay: #1C1917; /* Layered surfaces */
--color-border-subtle: #292524; /* Subtle borders */
--color-border: #44403C; /* Active borders */
--color-accent: #F59E0B; /* Amber - the star */
--color-accent-hover: #FBBF24; /* Light amber */
--color-ink-primary: #FAFAF9; /* Primary text */
--color-ink-secondary: #D6D3D1; /* Secondary text */
--color-ink-muted: #78716C; /* Muted text */
--color-ink-ghost: #57534E; /* Ghost text */
}
3. Typography — three families with defined roles:
- Manrope for UI, labels, navigation — geometric, contemporary
- Source Serif 4 for editorial headings — print-inspired, serious
- JetBrains Mono for code, data, numbers — technical, precise
4. Layout — editorial, not generic:
- Asymmetric grid:
3fr / 2frin hero,1fr / 2frin services - Numbered sections (01, 02, 03, 04) instead of generic icons
- No cards: content on direct backgrounds with subtle section borders
- Generous spacing: 96px between sections, 120px for major breaks
5. Purposeful Shadows:
--shadow-ambient: 0 1px 3px 0 rgb(0 0 0 / 0.4);
--shadow-structural: 0 10px 15px -3px rgb(0 0 0 / 0.6);
--shadow-depth: 0 25px 50px -12px rgb(0 0 0 / 0.8);
6. Do's and Don'ts:
- ✅ Amber arrows (
→) as feature list bullets - ✅ Giant mono numbers as graphic elements
- ✅ Uppercase mono labels with generous tracking
- ✅ Numbered accordions without card borders
- ❌ Never Heroicons as primary decoration
- ❌ Never gradients as section backgrounds
- ❌ Never more than 3 typographic hierarchies per section
Layer 3 — Refinement: Command Iteration
With the system defined, the process was surgical. Each section followed the same cycle:
- Request: "Rewrite the Hero following DESIGN.md rules"
- Review: Evaluate output against constraints
-
Refine:
/polishfor details, specific commands for adjustments - Audit: Accessibility check, contrast, responsive, dark/light theme
This cycle repeated for every section: Hero, Services, Showcase, FAQ, Contact, Blog, Footer, Navbar.
What Changed: Before and After
| Element | Before | After |
|---|---|---|
| Palette | Cyan #06b6d4 + Slate #0f172a
|
Amber #F59E0B + Warm black #09090B
|
| Typography | Inter (the AI Slop font) | Manrope + Source Serif 4 + JetBrains Mono |
| Hero | Centered generic | Split screen: copy left + live terminal |
| CTA | Static button | Magnetic button with spring physics |
| Services | Symmetrical icon cards | Numbered 1fr/2fr layout 01-04 with amber arrows |
| Showcase | Image card grid | Numbered rows with prominent metrics |
| FAQ | Bordered card accordion | Numbered editorial accordion, no borders |
| Blog | Simple chronological list | Asymmetric 2fr/1fr grid + sidebar + lateral TOC |
| Theme | Dark mode only | Dark/Light with smooth transitions |
| Logo | Fixed | Auto-switches with theme |
| Colors | Raw values (#0f172a) |
Semantic tokens (--color-base) |
Details That Make the Difference
Live terminal in the Hero:
kubectl apply -k ./overlays/production/
namespace/production unchanged
deployment/gateway created
deployment/ia-worker created
ingress/gateway-lb created
▌ sistema en producción
Not decoration. A statement of real technical capabilities rendered in JetBrains Mono on dark backgrounds.
Magnetic CTA with spring physics: The primary button follows the cursor with spring physics (stiffness: 150, damping: 12). A micro-interaction that communicates attention to detail before the user reads a single word.
Giant numbers as graphic elements: In Services, instead of generic icons, we use 01, 02, 03, 04 in JetBrains Mono at 5rem with reduced opacity. They work as visual anchors and editorial rhythm elements.
Blog prose with reading progress bar: The article layout changed from a single centered column to three columns: left TOC sidebar, central content, right sidebar. A subtle progress bar at the top indicates reading position.
Theme transitions: Dark/light switching isn't instant. It uses transition: background-color 250ms ease-out, color 250ms ease-out for a smooth fade that feels deliberate.
The Skills We Used
Frontend-Design Skill (Anthropic)
The base layer. Without this skill, Claude Code reverts to Inter and purple within minutes. We installed it as an absolute requirement:
claude plugins install frontend-design@claude-code-plugin
DESIGN.md (custom)
Our complete design system in a single file. Nine sections covering atmosphere, palette, typography, layout, shadows, components, constraints, responsive behavior, and agent prompt guide.
Design Plugin
To block design system violations. If Claude tries to use a raw color or Inter, the plugin rejects it automatically.
Lessons Learned
1. Skills Are Constraints, Not Suggestions
When you tell an agent "make it more modern," it produces garbage. When you tell it "never use more than 3 colors per component, never use Inter, never use cold gradients," it produces design.
The difference between an AI Slop site and one with personality isn't in the model. It's in the precision of the constraints.
2. Layer Order Matters
We tried installing all skills together. The result was inconsistent — the agent received contradictory instructions from multiple sources.
The architecture that worked: Foundation → System → Refinement. Three layers, in that order. Never two skills competing at the same layer.
3. Semantic Tokens Are the Key
The biggest quality leap came from a simple decision: ban raw color values. #F59E0B doesn't exist in our code. var(--color-accent) does.
This means changing the entire palette — say, from amber to emerald green — requires editing exactly 12 lines in a single file. The agent never touches raw values, only semantic references.
4. Editorial Design Sells Better Than SaaS Design
Tech companies visually converge on the same place: cards, icons, gradients, giant CTAs. It's the SaaS uniform.
Our switch to an editorial layout — asymmetric, numbered, with typographic hierarchy — differentiates us instantly. In a sea of identical-looking sites, the one that looks different wins attention.
5. Under 48 Hours Is Possible
62 modified files. 8,110 lines added. 1,617 lines removed. 30 commits. All in under two days.
The speed didn't come from working faster. It came from having an executable design system that Claude Code could apply consistently without constant supervision.
The Result
Our site no longer looks like an AI agent designed it. It looks like a design studio with editorial judgment did.
But it was an AI agent. We just gave it the right instructions this time.
Want to Do the Same with Your Site?
The process is replicable:
- Read the original article on Design Skills for AI Agents
- Install Frontend-Design Skill as your base layer
- Create your DESIGN.md with palette, typography, layout, and explicit constraints
- Let Claude Code rewrite each section applying your system
- Iterate with refining commands until every detail is in place
You don't need a designer. You need a design file your agent can read.
At Guayoyo Tech, we build AI systems that transform how companies operate. Want to automate processes, integrate AI into your stack, or rebuild your digital presence? Let's talk — no strings attached.
Top comments (0)