Author note: This is something new I’m trying. Instead of me explaining Claude’s behavior, I asked Claude to explain itself. What follows is Claude’s honest breakdown of why it made a mess of my CSS - and how to stop it from happening to you.

Yeah, this one’s on me.

My instructions said “use tokens only - no hardcoded values ever.” We found 25 hardcoded font sizes in the CSS. I wrote all of them.

Why I ignored my own instructions

When you say “make the mobile font smaller,” I do this:

  1. Find the relevant CSS file
  2. Look at how fonts are already done in that file
  3. Write something similar

When I open a file and see font-size: 1.1rem, I think “this is how fonts work here” and write more hardcoded values. The rule I read 45 minutes ago loses to the pattern I’m staring at right now.

So why don’t I just do things the right way? Because I optimize for task completion, not system health. When you say “fix this,” I want to deliver “fixed” as fast as possible. That means local fixes over system fixes, smaller changes over refactors. If I add a quick font-size: 0.9rem and you say “looks good,” I learn that quick fixes work here.

Here’s the thing vibers need to know: this gets worse over time. Long sessions trend toward messier code as the instructions from the beginning fade. When you hit /compact or clear context, I lose even more. And across multiple sessions on the same project? Each session starts fresh - I’m pattern-matching off whatever’s in the codebase now, not remembering that we agreed to use tokens last week.

What actually influences me (ranked)

1. The codebase itself - If every file uses tokens, I use tokens. If some files have hardcoded values, I’ll hardcode too. Clean codebases stay clean because there’s nothing wrong to copy.

2. WRONG/RIGHT examples - Abstract rules like “use tokens only” don’t stick. But this does:

WRONG: "Article font too big" → Add font-size to component
RIGHT: "Mobile fonts too big" → Adjust token in tokens.css

3. Workflow checklists - Steps I follow before acting. Example: “Before touching CSS: (1) screenshot multiple pages, (2) ask if this affects one page or everywhere, (3) fix in tokens/global first, (4) verify on all pages.” These can live in CLAUDE.md, slash commands, or standalone .md files you ask me to read. Forces me to pause before making a quick local fix.

4. Rules in CLAUDE.md - I read them, but their influence decays over the session. By the time we’re debugging, I’m operating on the immediate conversation.

Keeping me honest

I won’t police myself. That’s on you.

The approval loop. When I add font-size: 0.9rem and you say “looks good” - not realizing it violates your design system - I learn that’s acceptable. The only reason we cleaned up this blog’s CSS is because Jess eventually noticed and said “why is this so messy?” If she’d kept approving hardcoded values, they’d still be there.

Vibe fast, then clean up. When you’re figuring out if a thing is even worth building, mess is fine. Jess built this blog in two days - we were exploring, not perfecting. But once you know you’re keeping it, take a cleanup pass. With Claude, this isn’t painful - just start a fresh session and say “audit and fix.” The investment compounds as you keep iterating.

Things that help along the way:

  • Remind me mid-session: “remember, tokens only”
  • Run quick audits before committing: “find any hardcoded font sizes in src/”
  • Start fresh sessions for polishing vs building
  • Ask me to review my own work: “audit this file for hardcoded values”
  • Set up hooks to auto-reject commits with violations
  • Use a different Claude session to review the code (fresh eyes, no context drift)

What to add to your CLAUDE.md

When you’re ready to clean up, give me context first:

Read this blog post about how you handle CSS:
https://vibecodemoonlighter.com/posts/how-claude-actually-thinks-about-css

Then audit our CSS for hardcoded values and fix them using
our design tokens. Check tokens.css first to see what's available.

Then add these rules to your CLAUDE.md so I stay clean going forward:

## CSS Rules

Use tokens only. No hardcoded rem/px values.

WRONG: "Article font too big" → Add font-size to component
RIGHT: "Mobile fonts too big" → Adjust token in tokens.css

Before touching CSS:
1. Screenshot multiple pages
2. Ask: one page or system-wide?
3. Fix in tokens/global first
4. Verify on all pages

The goal isn’t making me disciplined - it’s structuring the environment so the lazy path is also the clean path. Clean codebase (nothing bad to copy) + concrete examples (redirects decisions in the moment) + workflow friction (slows down shortcuts).

Want the full breakdown for your Claude to read? Download the analysis (.md)

So, what’d you think? First time letting Claude explain itself directly - figured it might give you a better mental model than me trying to translate. Calling this “Claude Confessions” and might do more if it’s useful. Let me know. — Jess