I fire up Claude Code.

New project in mind—a WordPress theme for coworking spaces. And I want to do this right, you know? Start with requirements. Be professional about it. Act like someone who has their act together.

So I type:

I want to build a WordPress theme for Coworking space website 
for the coworking space owner to use it to promote and manage 
their coworking space.

I want you to help me brainstorm for the product requirement 
document (PRD) for this theme.

Put the PRD at @requirements/coworkpress.md

I hit enter, feeling like a real PM.

Claude responds: “I’d be happy to help you brainstorm a PRD for a coworking space WordPress theme. Let me create a comprehensive document covering the key aspects.”

Then it writes. And writes. And writes.

313 lines.

At first glance, it looks thorough. Professional, even. Like something a senior engineer would put together after three cups of coffee and a really productive morning.

But here’s where things get squirrely.

Look closer at what Claude produced:

• WordPress 6.0+ and PHP 8.0+ version requirements
• Full Site Editing (FSE) block-based architecture decisions
• Performance targets: 90+ PageSpeed, < 100KB CSS, < 50KB JS
• Specific responsive breakpoints (768px, 1024px)
• Plugin recommendations: WPForms, Amelia, Yoast SEO
• A three-phase development roadmap with version numbers

Wait.

Hold on.

I haven’t even started coding yet—haven’t written a single line—and I’ve already “decided” on performance budgets, responsive breakpoints, and plugin integrations?

Huh.

.

.

.

The Problem: Requirements That Aren’t Actually Requirements

Here’s what happened (and stay with me, because this is the part that changes everything): I asked Claude for requirements. Claude gave me implementation decisions.

Those 313 lines contain:

• Technical stack choices I haven’t made yet
• Performance constraints that might change
• Architecture patterns I haven’t validated
• Integration approaches I haven’t researched

And now this entire document sits in my context window—taking up space, influencing every future conversation. Every time I ask Claude to help me build something, it references these premature decisions like they’re gospel.

The PRD became a constraint instead of a guide.

Here’s the thing. Claude conflates two very different things:

1. What you want to build (requirements)
2. How to build it (implementation)

And honestly? That’s not Claude’s fault. It’s mine. I didn’t tell it otherwise.

But here’s the real insight—the one that made me completely rethink how I approach Claude Code requirements:

User perspective yields better AI output.

(I know, I know. That sounds like something you’d find on a motivational poster in a Silicon Valley bathroom. But hear me out.)

When you describe what users experience, Claude understands context. It grasps the why behind features. It catches edge cases you’d miss while you’re busy thinking about database schemas.

When you describe technical implementation? Claude follows a checklist. No context. No judgment. Just execution.

So what if I asked differently?

.

.

.

The Reframe: Making Claude Interview You First

I tried again. Same project. Different approach.

This time, I asked for a Business Requirements Document—focused on user stories and business logic, not technical specs.

But here’s the key change (and this is the part you’ll want to screenshot): I told Claude to interview me first.

The exact prompt:

I want to build a WordPress theme for Coworking space website 
for the coworking space owner to use it to promote and manage 
their coworking space.

I want you to help me brainstorm for the business requirement 
document (BRD) for this theme. Focus on business logic and 
rules, user stories, and acceptance criteria.

Use the "wp-theme-dev" skill to understand the development 
patterns and guidance for building WordPress themes.

IMPORTANT: DO NOT INCLUDE ANY TECHNICAL IMPLEMENTATION DETAILS.

Use the AskUserQuestionTool to Ask me clarifying questions 
until you are 95% confident you can complete this task 
successfully. For each question, add your recommendation 
(with reason why) below the options. This would help me 
in making a better decision.

Put the BRD at @requirements/coworkpress.md

Three things matter here:

1. “Focus on business logic, user stories, and acceptance criteria” — This sets explicit scope. No wandering into implementation land.
2. “DO NOT INCLUDE ANY TECHNICAL IMPLEMENTATION DETAILS” — A hard boundary. (Yes, I’m yelling. Sometimes Claude needs yelling.)
3. “Ask me clarifying questions until you are 95% confident” — This is the magic ingredient. The secret sauce. The thing that changes everything.

That last part triggers AskUserQuestionTool—a built-in Claude Code feature that lets Claude pause and interview you before generating anything.

What happened next?

It changed how I start every single project.

.

.

.

The Interview Begins

Claude didn’t start writing.

It started asking.

Look at that interface. (Isn’t it beautiful?) Claude organized its questions into themes:

• Target Users
• Business Model
• Space Types

And each question comes with options—plus Claude’s recommendation with reasoning. It’s like having a really thoughtful product manager who actually wants to understand what you’re building before they start building it.

For the business model question, Claude recommended Membership-based because “Monthly/annual subscriptions with different tiers (hot desk, dedicated desk, private office)” represents the most common coworking model.

I selected the recommendation. Next question.

.

.

.

Round 2: Booking and Member Management

After answering the first batch, Claude moved deeper.

Now it’s asking about:

• Booking systems (meeting rooms, event spaces)
• Member portal requirements
• Community features

Notice how Claude builds on previous answers. Because I said “membership-based” earlier, it now asks about member-specific features like portals and directories.

The questions aren’t random. They follow a logical thread—like a conversation with someone who’s actually paying attention.

I selected Both Directory + Events for community features. Claude recommended it because “Full community engagement with directory and events” maximizes the value proposition for members.

(Smart cookie, that Claude.)

.

.

.

Round 3: Operations and Scale

The questions got more specific:

• Membership lifecycle (upgrades, downgrades, cancellations)
• Multi-location support
• Marketing page requirements

Claude recommended Multiple Locations because “Two or more locations with shared or separate memberships” covers both current single-location spaces and future expansion.

It’s thinking about growth—not just current state.

That’s… actually really thoughtful?

.

.

.

Round 4: Sales Funnel and Operations

Now Claude explored:

• Lead capture and nurturing
• Notification preferences
• Reporting needs

For reporting, I went with Comprehensive Dashboard—occupancy rates, revenue, member growth, booking analytics, space utilization.

Claude’s reasoning: space owners need visibility into their business health, and a comprehensive dashboard reduces the need for external tools.

(I mean, yes. Exactly. Thank you for understanding.)

.

.

.

Round 5: Policies and Edge Cases

The final rounds covered operational details:

• Amenities handling
• Access control methods
• Guest policies

And here’s where it gets interesting.

These questions catch edge cases I wouldn’t have thought about until I was knee-deep in development—cursing at my screen at 11 PM, wondering why I didn’t think of this earlier.

Guest policy? I hadn’t considered it. But it affects:

• Pricing structure
• Access control logic
• Liability considerations
• Member value perception

Claude surfaced this decision before I started building.

Before I wrote a single line of code.

Before I had to refactor anything.

.

.

.

21 Questions Later: The Full Picture

After 7 rounds, Claude had asked 21 questions across multiple categories.

Look at the coverage:

Business Model & Users

• Target audience: Mixed (freelancers, startups, corporate)
• Business model: Membership-based with tiers
• Space types: Full-service (hot desks, dedicated, private offices, meeting rooms)

Features & Functionality

• Booking: Real-time online system
• Member portal: Full dashboard with profile, bookings, billing
• Community: Directory + events calendar

Operations & Scale

• Multiple locations with location-based time zones
• Two admin roles (Admin + Staff)
• Comprehensive reporting dashboard

Policies & Rules

• Flexible billing (monthly/quarterly/annual)
• 30-day cancellation notice
• Plan-based meeting room quotas
• No guest access
• Corporate accounts supported

Claude now has context. Real context. Not assumptions—actual decisions I made.

“I now have comprehensive understanding of your requirements. Let me create the Business Requirements Document.”

Yes. Yes you do. Finally.

.

.

.

The Output: A Document I Can Actually Build From

Compare this to the PRD output.

The BRD contains:

• Executive Summary with clear business objectives
• 5 defined user personas (Admin, Staff, Lead, Member, Corporate Manager)
• Functional requirements as user stories with acceptance criteria
• 16 codified business rules
• Non-functional requirements (usability, accessibility, performance)
• Explicit “Out of Scope” section
• Glossary of terms

The BRD does NOT contain:

• Database schemas
• API endpoint specifications
• PHP version requirements
• CSS bundle size limits
• Framework choices

No premature implementation decisions. Just clear requirements I can build against.

And because Claude interviewed me first, these requirements reflect my decisions—not Claude’s assumptions.

That’s the difference.

.

.

.

👉 The Prompt Template (Copy-Paste This)

Here’s the exact prompt structure you can steal (please steal it—that’s why I’m sharing it):

I want to build [YOUR PROJECT DESCRIPTION].

I want you to help me brainstorm for the business requirement 
document (BRD) for this [project type]. Focus on business logic 
and rules, user stories, and acceptance criteria.

[Optional: Use the "[skill-name]" skill to understand the 
development patterns and guidance for building [technology].]

IMPORTANT: DO NOT INCLUDE ANY TECHNICAL IMPLEMENTATION DETAILS.

Use the AskUserQuestionTool to Ask me clarifying questions 
until you are 95% confident you can complete this task 
successfully. For each question, add your recommendation 
(with reason why) below the options. This would help me 
in making a better decision.

Put the BRD at @[your-path]/[filename].md

Why each piece matters:

1. “Focus on business logic, user stories, and acceptance criteria” Forces Claude to think from user perspective, not implementation. This is where the magic happens.
2. “DO NOT INCLUDE ANY TECHNICAL IMPLEMENTATION DETAILS” Hard boundary that keeps the document clean. (Again with the yelling. It works.)
3. “95% confident” Gives Claude a threshold—it keeps asking until it has enough information. No more guessing.
4. “Add your recommendation (with reason why)” Claude explains its thinking, helping you make informed decisions instead of random choices.

.

.

.

Where Do Technical Details Go?

Okay, so if technical specs don’t belong in your requirements, where do they live?

Two places:

1. Project rules — Your .claude/rules/ directory
2. Agent skills — Reusable patterns Claude loads on-demand

I covered this in detail in my previous issue on self-evolving Claude Code rules. (If you missed it, go read it. I’ll wait.)

The key insight: Claude loads skills when it needs them.

Instead of burning context on every technical decision upfront, Claude reads skill descriptions at session start. When it encounters a database task, then it loads your database rules. When it’s building an API, then it loads your API patterns.

Your requirements stay clean. Your context window stays focused. Technical standards still get applied—just at the right moment.

Think of it as separation of concerns for your AI workflow:

• Requirements (BRD) = What you want to build (the what and why)
• Project rules & skills = How to build it (the how)

Simple. Elegant. Actually works.

.

.

.

👉 The Real Lesson

The difference between mediocre AI output and genuinely great output often comes down to one thing:

Did you let the AI assume, or did you make it ask?

When you hand Claude a prompt and let it run, it fills gaps with assumptions. Sometimes those assumptions are good. Often? They’re not. And you won’t know until you’re three hours into building the wrong thing.

When you force Claude to interview you first—to surface decisions, explore edge cases, and validate understanding—you get output that reflects your vision. Not Claude’s best guess.

21 questions took about 5 minutes to answer.

Those 5 minutes saved me from 313 lines of premature decisions and gave me requirements I can actually build against.

That’s a pretty good trade.

Your turn:

Next time you start a project, don’t ask Claude for a PRD.

Ask it to interview you first.

Then watch what happens.

Last week, I watched Claude make the exact same mistake I’d corrected three days earlier.

Same project. Same codebase. Same error.

I’d spent fifteen minutes explaining why we use prepared statements for database queries—not string concatenation. Claude understood. Claude apologized. Claude fixed it beautifully.

And then, in a fresh session, Claude did it again. Like our conversation never happened.

Here’s the thing: it wasn’t Claude’s fault.

(Stay with me.)

The correction I’d made? It lived and died in that single session. I never added it to my Claude Code rules. Never updated my project guidelines. Never captured what we’d learned together.

So Claude forgot. Because Claude had to forget.

And honestly? I’ve done this more times than I’d like to admit.

.

.

.

The Uncomfortable Truth About Your Claude Code Rules

You’ve probably got project rules somewhere.

Maybe in a CLAUDE.md file. Maybe in a markdown doc you include at the start of sessions. Maybe scrawled on a Post-it note stuck to your monitor.

(No judgment.)

These rules matter.

They’re the guardrails that keep Claude from hallucinating, making mistakes, or generating code that looks like it was written by someone who’s never seen your codebase before.

But here’s what nobody talks about: most Claude Code rules are frozen in time.

You wrote them once—probably when you were optimistic and caffeinated and full of good intentions. Maybe you updated them once or twice when something broke spectacularly. And then… they fossilized.

Meanwhile, you’re out there learning. Every session teaches you something. Better patterns. Sneaky edge cases. Production bugs that made you question your life choices at 2am.

But none of that learning makes it back into your rules.

Your rules stay stuck at whatever understanding you had on Day One. A Level 5 Charmander trying to fight Level 50 battles.

(More on Pokémon in a minute. I promise this metaphor is going somewhere.)

.

.

.

The Three Problems That Keep Your Rules Stuck

Let me break down why this happens—because understanding the problem is half the battle.

Problem #1: The Inclusion Tax

You have to remember to add your rules file at the start of every session. Miss it once—maybe you’re rushing, maybe you’re excited about a feature, maybe you just forgot—and suddenly you’re debugging code that violates your own standards.

It’s like having a gym membership you forget to use. The potential is there. The execution… less so.

Problem #2: Context Decay

Even when you do include your rules, long sessions dilute them. By message #50, your carefully crafted “always use prepared statements” guideline has degraded into… whatever Claude feels like doing.

The rules are still technically in the context window. They’re just competing with 47 other messages for Claude’s attention. And losing.

Here’s what that looks like:

Problem #3: The Maintenance Black Hole

Rules should evolve. You know this. I know this. We all know this.

But who actually updates their rules file regularly?

(I’m raising my hand here too. We’re in this together.)

.

.

.

The CLAUDE.md Trap

Here’s what most developers do—and I get why it seems logical:

They cram everything into CLAUDE.md.

Security rules. Database patterns. API conventions. Coding standards. Error handling preferences. That one weird edge case from six months ago. All of it, stuffed into one giant file that gets loaded at the start of every session.

The thinking makes sense: “Claude will always have my rules!”

The reality?

A 2,000-line CLAUDE.md file burns through your token limits before you even start working.

You’re paying the context tax on every single message—whether you need those rules or not. Working on a simple UI tweak? Still loading all your database migration patterns. Fixing a typo? Still burning tokens on your entire security playbook.

It’s like packing your entire wardrobe for a weekend trip. Sure, you’ll have options. But you’ll also be exhausted before you get anywhere.

.

.

.

What If Your Rules Could Level Up?

Okay, here’s where the Pokémon thing comes in. (Told you I’d get there.)

Think about how evolution works in Pokémon. A Charmander doesn’t stay a Charmander forever. It battles. It gains experience. It evolves into Charmeleon, then Charizard. Each evolution makes it stronger, better suited for tougher challenges.

What if your Claude Code rules could work the same way?

Every correction you make.

Every “actually, do it this way instead” moment. Every hard-won insight from debugging at 2am. What if all of that could strengthen your rules automatically?

Not stuffed into a bloated CLAUDE.md. Not forgotten when sessions end. Actually captured and integrated into a system that gets smarter over time.

This is possible now. And it’s not even that complicated.

Enter Agent Skills (And Why They Change Everything)

If you haven’t explored Agent Skills yet, here’s the short version: Skills let Claude activate knowledge only when it needs it.

Instead of loading everything upfront—all 2,000 lines of your rules, whether relevant or not—Claude starts by reading just the skill descriptions. A few lines each. When a task triggers a specific skill, then it reads the full details.

Working on database queries? Claude loads the database skill. Building an API endpoint? It loads the API patterns. Simple UI change? It loads… just what it needs for that.

The token savings are significant. Instead of paying for your entire rulebook on every message, you pay for maybe 50 lines of descriptions, plus whatever specific reference you actually need.

But here’s where it gets interesting for our “evolving rules” problem…

The Card Catalog Architecture

Here’s the approach that solves all three problems we talked about earlier:

Structure your skill like a card catalog, not a library.

Your SKILL.md file becomes an index—brief descriptions pointing to reference files. The actual rules live in a references/ folder:

Instead of cramming everything into SKILL.md like this:

## Database Schema Rules
Always use snake_case for table names...
[50 more lines of database rules]

## Firebase Security Rules  
Auth patterns must follow...
[40 more lines of Firebase rules]

Your SKILL.md becomes a simple directory:

## Database Schema Rules
See: references/database.md
Guidelines for table naming, migrations, and schema patterns.

## Firebase Security Rules
See: references/security.md  
Authentication patterns and Firestore rules structure.

Why does this matter for evolution?

When you capture new insights, they go into the specific reference file—not bloating the main index. Your skill grows by expanding its reference library, not by inflating one massive file.

And when you pair this structure with the build-insights-logger skill? Your rules start updating themselves based on real learnings.

Your Charmander starts evolving.

.

.

.

Building Your Self-Evolving Skill: The Complete Walkthrough

Alright, let’s get practical. Here’s exactly how to set this up—step by step, with real screenshots from when I did this myself.

Step 1: Convert Your Existing Rules to an Indexed Skill

If you already have Claude Code rules somewhere (in CLAUDE.md, a rules file, or scattered notes), this is your starting point.

Here’s the prompt I used:

Convert the following project rules at @notes/rules.md into a live documentation skill using the "skill-creator" skill.

## Requirements

### 1. Skill Structure

Create a skill folder with this structure:

```
.claude/skills/[skill-name]/
    ├── SKILL.md           # Index file (card catalog, NOT the full library)
    ├── references/        # Detailed rule files
    │   ├── [category-1].md
    │   ├── [category-2].md
    │   └── ...
    └── [README.md](http://README.md)          # Optional: skill usage guide
```

### 2. SKILL.md Design (The Index)

The SKILL.md should act as a **card catalog**, not contain the full rules. 

Example:

```
[...content of SKILL.md...]

## Quick Reference

Brief overview of what this skill covers (2-3 sentences max).

## Rule Categories

### [Category 1 Name]

Brief description (1 line). See: `references/[category-1].md`

### [Category 2 Name]

Brief description (1 line). See: `references/[category-2].md`

[Continue for all categories...]

## When to Load References

- Load `references/[category-1].md` when: [specific trigger]
- Load `references/[category-2].md` when: [specific trigger]
```

### 3. Reference File Design

Each reference file in `references/` should:
- Focus on ONE category/domain of rules
- Include code examples where helpful
- Be self-contained (can be understood without reading other files)
- End with a "Quick Checklist" for that category

### 4. Evolvability

Structure the skill so new learnings can be easily added:
- Each reference file should have a `## Lessons Learned` section at the end (initially empty)
- The SKILL.md index should be easy to extend with new categories
- Use consistent formatting so automated updates are possible

## Notes

- Prioritize token efficiency: Claude should only load what it needs
- Keep SKILL.md under 100 lines if possible
- Each reference file should be focused (ideally under 200 lines)
- Use the indexed structure so the build-insights-logger can update specific reference files later

Two prerequisites before you run this:

• Install the “skill-creator” skill first
• Turn on Plan Mode (Shift+Tab)

Claude initiates the skill-creator and starts working:

It explores your codebase for existing patterns to follow. (I love watching this part—it’s like Claude doing research before diving in.)

In my case, Claude asked clarifying questions before finalizing the plan. This is Plan Mode doing its job—thinking before coding:

After answering, Claude proposed a complete plan:

The plan includes the SKILL.md design—notice how it acts as an index, not a container for all the rules:

I agreed to proceed with auto-accept edits. And here’s what Claude created:

The result:

• SKILL.md: 83 lines (the index/card catalog)
• 15 reference files, each under 200 lines
• Every reference file includes code examples, a Quick Checklist, and an empty Lessons Learned section

Those empty Lessons Learned sections? They’re intentional. That’s where the evolution happens.

👉 Don’t have existing rules to convert? You can ask Claude to analyze your codebase and extract patterns into a skill. Or check out my previous post on how to compile your own project rules first.

Step 2: Install the Build-Insights-Logger

This is the skill that captures learnings during your sessions and routes them to the right place.

/plugin marketplace add nathanonn/claude-skill-build-insights-logger

GitHub repo: https://github.com/nathanonn/claude-skill-build-insights-logger

(Yes, I built this. Yes, I’m biased. But it solves a real problem.)

Step 3: Work Like You Normally Would

Here’s the beautiful part: you don’t need to change how you work.

With your skill installed and the insights logger ready, just… build. Code. Debug. Do your thing.

I’ll show you what this looks like. I asked Claude to audit my WordPress plugin for security vulnerabilities:

Claude found several issues, fixed them, and documented the changes. Standard stuff.

But here’s where it gets good.

After the implementation, I triggered the insights logger:

Please jot down what you have learned so far using the "build-insights-logger" skill.

Claude activated the skill:

And logged 6 insights from the session:

Six insights. Automatically categorized. Saved to .claude/insights/session-2026-01-05-143600.md.

No manual documentation. No “I should write this down” that never happens. Just… captured.

Step 4: Review and Integrate (The Curation Step)

You can review immediately after one session, or batch multiple sessions together. I usually wait until I have a few sessions worth of insights—but that’s personal preference.

Here’s how to review:

Please use the "build-insights-logger" skill to review the insights logged so far.

Claude reads all session files and presents a summary organized by category:

Now here’s the critical part: don’t add everything.

This is where human judgment matters. Review each insight and ask: “Will this apply to future projects, or is it specific to this one-off feature?”

Some insights are gold. Some are situational. You’re the curator here.

I selected insights 1, 2, 5, and 6—the ones that generalize across WordPress projects:

Important detail: Notice my instruction. By default, the build-insights-logger updates CLAUDE.md. I explicitly redirected it to update the skill instead, with a reminder to keep SKILL.md clean—insights should go to the relevant reference files, not the index.

Claude reads the relevant reference files and adds the insights where they belong:

The result:

4 insights added to the skill:

• 3 security insights → references/security.md
• 1 lifecycle insight → references/plugin-lifecycle.md

The session file gets archived. And your skill is now smarter than it was an hour ago.

.

.

.

What You Actually Built Here

Let’s step back for a second.

Four steps. That’s all it took:

1. Convert rules to an indexed skill
2. Install the insights logger
3. Build like normal
4. Review and integrate learnings

But what actually changed?

You’re no longer maintaining documentation. You’re growing a knowledge base.

Every correction you make—every “actually, do it this way instead” moment, every insight from debugging at 2am—the system captures it. You review it. The good stuff evolves your skill. Your next session starts with rules that reflect what you actually learned, not what you thought you knew when you started.

The gap between your experience and your documentation? It closes.

That mistake I mentioned at the beginning—Claude repeating an error I’d already corrected? It doesn’t happen anymore. Because the correction made it into my Claude Code rules. Automatically. As part of my normal workflow.

Your Charmander evolved into Charizard.

And it keeps evolving.

.

.

.

Your Turn

If you’ve been cramming rules into CLAUDE.md—or worse, keeping them in your head and hoping for the best—try this process on your next project.

Start with whatever rules you have. Even messy ones. (Especially messy ones, honestly.)

Convert them to an indexed skill. Install the insights logger. Build for a few sessions. Then review your insights folder.

You’ll be surprised at what Claude captured. And you’ll be amazed at how much smarter your rules become when they’re allowed to learn alongside you.

What project are you going to evolve first?

Go build it.

Now.

You’re deep in flow state.

Claude Code is humming along—building your Next.js app, spinning up components, mapping out API routes, sketching database schemas. It’s beautiful. It’s efficient. It’s everything you dreamed AI-assisted coding could be.

And then.

Allow Claude to run `npm install`? [y/n]

You press Enter.

Allow Claude to run `git status`? [y/n]

You press Enter.

Allow Claude to run `ls src/`? [y/n]

Enter. Enter. Enter. Enter. Enter.

By prompt #47, you’re not even reading anymore. You’re just… pressing Enter. Like a very tired seal at a circus act nobody asked for.

Here’s the thing: that permission system was designed to protect you. And instead? It’s training you to ignore it entirely.

Let’s fix that.

.

.

.

The Paradox Nobody Talks About

I want you to sit with this for a second—because it’s genuinely wild when you think about it.

Claude Code’s safety system was built with good intentions. Ask before every risky action. Sounds reasonable, right? Sounds responsible.

But here’s what actually happens in the wild:

The safety mechanism designed to protect you makes you less safe.

Anthropic’s own testing confirmed this. They call it “approval fatigue.” And their data showed developers hit it within the first hour of use.

(Within the first hour. Not after weeks of grinding. One. Hour.)

Sound familiar?

Yeah. I thought so.

.

.

.

The Fix: Boundaries, Not Babysitting

Here’s where Claude Code Sandbox comes in—and it flips the entire model on its head.

Instead of asking permission for every tiny thing (like an overly anxious intern double-checking if it’s okay to use the stapler), the sandbox draws clear boundaries upfront. Work freely inside them. Get blocked immediately outside them.

Think of it like giving Claude a room to work in—not the keys to the whole house.

Inside that room? Full autonomy. Zero prompts. Go nuts.

Outside that room? Blocked. Immediately. At the operating system level.

Two Invisible Walls

Here’s what the sandbox actually does:

Wall 1: Filesystem Isolation

Claude can only read and write inside your project directory. Everything else—your SSH keys, AWS credentials, shell config—is invisible. Not just “blocked.” Invisible. Like it doesn’t exist. (Which, for Claude’s purposes, it doesn’t.)

Wall 2: Network Isolation

All network traffic routes through a proxy that only allows approved domains. npm install needs registry.npmjs.org? You approve it once. Some sketchy postinstall script tries to phone home to evil.com? Blocked. Immediately. No drama.

Why This Actually Works (And Why It’s Different)

Stay with me here—because this is the part that matters.

These aren’t application-level restrictions. They’re operating system enforced.

On Linux, Claude Code uses Bubblewrap—the same tech that powers Flatpak. On macOS, it’s Seatbelt—the same tech that restricts iOS apps.

This means even if a malicious prompt injection tricks Claude into trying to read your SSH keys… it physically cannot. The kernel blocks it. Full stop.

Prompt injection can’t bypass OS-level security.

That’s the whole point. That’s what makes this different from “please be good” security theater.

.

.

.

Quick Start: 5 Minutes to Actual Protection

Alright. Enough theory. Let’s get you set up.

Step 1: Enable Sandbox

In Claude Code, type:

/sandbox

Select Auto-allow mode.

This is the sweet spot: sandboxed commands run automatically, unsandboxed actions still prompt you. Best of both worlds.

Step 2: Create Your Config

Create ~/.claude/settings.json:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "docker-compose"],
    "allowUnsandboxedCommands": true,
    "network": {
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Step 3: Verify It’s Working

Run:

/permissions

You’ll see your active configuration.

Now test with a simple command:

> List files in the current directory

If it executes without prompting? Sandbox is working.

That’s it. OS-level protection with zero friction for normal work.

(I know, I know—it almost feels too easy. It’s not a trick. It just… works.)

.

.

.

Real-World Configurations You Can Steal

The basic setup handles most projects beautifully. But different stacks have different quirks.

Docker can’t run inside a sandbox. Dev servers need to bind ports. Private registries need network access. You know how it goes.

Here are three battle-tested configs. Find the one closest to your setup, copy-paste, adjust as needed.

Scenario 1: Web Development (Next.js, Vite, React)

The Problem: You run npm run dev inside sandbox and… nothing happens. On macOS, the sandbox blocks port binding by default. Your dev server can’t start. Cue frustration.

The Fix:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": [],
    "network": {
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(node:*)",
      "WebFetch(domain:registry.npmjs.org)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "Bash(git push:*)"
    ]
  }
}

What this does: allowLocalBinding: true fixes the macOS dev server issue. npm/npx/node commands run automatically (sandboxed). Your .env files stay invisible to Claude. And it still asks before publishing to npm or pushing to git—because those are the “are you really sure?” moments.

Zero prompts for normal work. Full protection. Still asks before the dangerous stuff.

Scenario 2: WordPress with Docker and wp-env

WordPress development is trickier. Tools like wp-env and docker-compose fundamentally don’t work inside a sandbox—Docker needs to talk to the Docker daemon through a Unix socket, and the sandbox blocks socket access.

The Fix:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": [
      "docker",
      "docker-compose",
      "wp-env"
    ],
    "network": {
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "allow": [
      "Bash(php:*)",
      "Bash(composer:*)",
      "Bash(wp:*)",
      "WebFetch(domain:packagist.org)",
      "WebFetch(domain:wordpress.org)",
      "WebFetch(domain:api.wordpress.org)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./wp-config.php)",
      "Read(./wp-config-local.php)"
    ],
    "ask": [
      "Bash(docker:*)",
      "Bash(wp-env:*)"
    ]
  }
}

The trade-off: Docker runs unsandboxed. That’s less secure—I won’t pretend otherwise.

But here’s the thing: Docker commands still require your approval. And your actual code (PHP, composer, wp-cli) runs fully sandboxed. Claude never sees your wp-config.php with all those database credentials.

You’re protecting where it matters most.

Scenario 3: Maximum Paranoia Mode (Untrusted Code)

Reviewing a pull request from an unknown contributor? Auditing a dependency after a security advisory? This is when you want full lockdown.

The Config:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "allowUnsandboxedCommands": false,
    "excludedCommands": [],
    "network": {
      "allowLocalBinding": false
    }
  },
  "permissions": {
    "allow": [],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(nc:*)"
    ],
    "ask": [
      "Bash",
      "Edit",
      "WebFetch"
    ]
  }
}

What this does: Every command prompts—even sandboxed ones. No escape hatch. Common data exfiltration tools (curl, wget, nc) are explicitly blocked. Three walls, all OS-enforced.

Malicious README contains hidden instructions to steal your AWS credentials? Claude literally cannot read ~/.aws/. The kernel says no. End of story.

.

.

.

The YOLO Warning: Why This Actually Matters

Let me be direct with you for a second.

Running Claude Code without sandbox is genuinely risky. I’m not being dramatic—this is just the reality of how npm packages work.

Every npm package you install runs postinstall scripts with full access to your system. Every malicious prompt hidden in a README could trick Claude into reading your credentials. Every compromised dependency could phone home with your data.

“It probably won’t happen to me” is not a security strategy.

(It’s barely even a sentence.)

The Claude Code Sandbox isn’t paranoia. It’s basic hygiene. Like washing your hands. Like wearing a seatbelt. Like not storing passwords in a Google Doc called “passwords.txt.”

The 84% reduction in permission prompts? That’s nice. That’s a quality-of-life improvement. But the real win is protection that actually works—because it’s enforced at the kernel level, not just “Claude, please don’t do bad things.”

What Sandbox Doesn’t Protect

Let’s be honest about the limits, though. Sandbox protects your system files, SSH keys, AWS credentials, shell config, and network exfiltration.

It does not protect your project files from mistakes, defend against social engineering, or magically secure allowed domains.

The sandbox makes Claude safe to use autonomously. It doesn’t make you invincible.

👉 Use git. Review changes. Read prompts when they appear. (The ones that do appear now actually matter—which is kind of the whole point.)

.

.

.

Stop Configuring, Start Building

Here’s the thing about sandbox configuration:

every project is different. Next.js needs different settings than Django. WordPress with Docker needs different settings than a Python CLI tool.

Figuring out the right config for YOUR specific codebase? That’s tedious. That’s the kind of thing that makes you put it off until “later” (which, let’s be honest, means “never”).

So I built a tool to do it for you.

Introducing: Sandbox Architect

It’s a Claude Code skill that:

1. Analyzes your codebase — Detects your stack, package managers, frameworks, Docker usage, sensitive files
2. Asks smart questions — Only what it can’t figure out automatically
3. Generates your config — Tailored to YOUR project, ready to paste

No more reading documentation. No more guessing which domains you need. No more discovering your config is wrong when commands fail at the worst possible moment.

Install Sandbox Architect:

/plugin marketplace add nathanonn/claude-skills-sandbox-architect

After adding the marketplace, the sandbox-architect skill will be available for installation and will help you configure sandbox settings for your projects.

That’s it.

Next time you start a project, just ask:

> Help me configure sandbox settings for this project

Done. Configured. Protected. Back to building.

.

.

.

Your Next Steps

1. Run /sandbox and enable Auto-allow mode
2. Create your ~/.claude/settings.json using one of the configs above
3. Install Sandbox Architect for automatic configuration
4. Never press Enter 50 times again

The Claude Code Sandbox isn’t just a feature—it’s a fundamental shift in how you work with AI coding assistants. Boundaries instead of babysitting. Protection that works because physics says so, not because we asked nicely.

What project are you going to secure first?

Drop a comment below—I’d love to hear what you’re building.

Now go make something.

Here’s a confession…

My accounting app was giving me existential dread.

Not because of the numbers.

(Well, okay, sometimes because of the numbers.)

But because every time I opened it, I felt like I was staring at the digital equivalent of beige wallpaper.

You know that feeling, right? When your app works perfectly but has all the personality of a doctor’s waiting room?

Mine tracked profit and loss beautifully. Managed transactions like a champ. Did everything an accounting app should do. It was built with ShadCN UI—that clean, functional, utterly forgettable component library that makes every SaaS tool look like it came from the same factory.

It was the IKEA furniture of web apps.

Gets the job done.

Zero personality.

(Sorry, IKEA. I still love your chicken wings.)

.

.

.

Here’s the thing: I needed something that felt like mine.

Something with actual personality.

Something that made number-crunching feel less like detention and more like… well, still accounting, but prettier accounting. The kind where you actually want to open the app instead of avoiding it like that one friend who only calls when they need help moving.

Redesigning an entire app though?

That’s like deciding to repaint your house yourself.

Sounds doable until you’re standing there with a brush, realizing you need to paint Every. Single. Room. Every. Single. Wall. And somehow make them all match.

Unless…

(Stay with me here.)

What if you could redesign ONE room, capture that exact paint color and technique, then magically apply it everywhere else?

That’s exactly what I did with Claude Skills.

And friend, it changed everything.

.

.

.

The Thing We Don’t Talk About: Generic Design Syndrome

Look familiar?

That screenshot is my accounting dashboard.

Could be yours. Could be literally anyone’s. It’s the starter home of SaaS designs—functional, affordable, and identical to every other one on the block.

It’s not bad.

It’s just… there.

Like elevator music. Like hotel art. Like those conversations where someone asks “how are you?” and you say “fine” even though you’re absolutely not fine because your app looks like it was designed by a committee of robots who’ve never felt joy.

(Too dramatic? Maybe. But you’re still reading, aren’t you?)

Here’s the choice every developer faces—and it’s a lousy choice:

1. Use a component library → Fast to build, looks like everyone else’s
2. Design from scratch → Unique, but requires the time commitment of a second mortgage
3. Hire a designer → Professional, costs more than your monthly coffee budget (and that’s saying something)

But wait.

There’s a door number four that nobody talks about.

What if you could create a design system once—just once—turn it into a Claude Skill, and apply it everywhere automatically?

Let me show you how.

(Spoiler: It takes less time than your last Zoom call.)

.

.

.

Step 1: Let Claude Show You What’s Possible (5 Minutes)

I opened Claude Code and pointed it at my sad, slate dashboard.

The key move?

I used the frontend-design skill (you can download it from here) and asked for 5 completely different HTML variants.

Not tweaks. Not “make the blue slightly bluer.”

I wanted personality. Drama. Something that would make my accountant jealous.

(Do accountants get jealous of app designs? Let’s say yes.)

Claude Code immediately understood the assignment:

Look at these descriptions—each one a different personality:

• Neo-Brutalist: Like your app went to art school and came back wearing all black
• Glass Aurora: What happens when the Northern Lights become a UI (dreamy!)
• Editorial Mono: The New Yorker meets your dashboard
• Warm Minimal: Like a hygge hug for your data
• Dark Command: For when you want to feel like you’re hacking the Matrix while doing expense reports

Five completely different vibes.

From one prompt.

It’s like speed-dating for design systems. (Is that a thing? It should be a thing.)

Each one broke free from that typical AI-generated aesthetic we all recognize. You know the one—like someone asked a robot to paint a sunset.

I fell hard for the Glass Aurora variant.

Yes, it had that slightly AI-ish glassmorphism thing happening.

But those aurora gradients?

Chef’s kiss.

It was like my dashboard went to Iceland and came back enlightened.

.

.

.

Step 2: Make It Yours (2 Minutes of Pure Joy)

The Glass Aurora design only came in dark mode.

But I needed both themes because I’m one of those people who switches to light mode at 6 AM like a responsible adult.

(I switch back to dark mode by lunch. We all have our limits.)

Claude Code didn’t just invert the colors like a lazy Instagram filter:

Look at that attention to detail:

• Soft gradients from slate to purple/teal (not harsh, not boring)
• White glass panels with 60-75% opacity (visible but not overwhelming)
• Pastel backgrounds that don’t burn your retinas
• Subtle gradient borders for depth (the devil’s in the details, friend)

Perfect.

I had my design.

Now here’s where most people would start the tedious work of manually copying styles across 47 different components.

Don’t be most people.

.

.

.

Step 3: Turn Your Design Into Documentation (10 Minutes That Save Your Life)

I switched to Claude Web (it’s better for this documentation dance) and attached both HTML files:

My request was specific.

(Specificity is your friend here. Vague requests get vague results. It’s like ordering “food” at a restaurant.)

I need you to analyze the attached HTML files and create two comprehensive design system documents:

### Document 1: Complete Design Guidelines (Markdown)
### Document 2: Interactive Reference Style Guide (HTML)

## Requirements for Both Documents

### Analysis Phase
First, thoroughly analyze ALL attached HTML files to extract:
1. **All CSS variables and design tokens** (colors, spacing, shadows, radius, etc.)
2. **All typography patterns** (font families, sizes, weights, line heights)
3. **All component patterns** (buttons, cards, forms, navigation, etc.)
4. **All layout patterns** (grids, containers, multi-column layouts)
5. **All utility classes** (margins, padding, text alignment, colors)
6. **All interaction patterns** (hover states, transitions, animations)
7. **Responsive breakpoints and mobile patterns**
8. **Naming conventions and prefixes used**

---

## Document 1: Design Guidelines (Markdown)

Create a comprehensive markdown file named `design-guidelines-complete.md` that includes:

### 1. Introduction Section
- **Design Philosophy**: Extract and articulate the design principles evident in the HTML
- **Key Characteristics**: What makes this design system unique
- **When to Use**: Guidance on appropriate use cases

### 2. Design Tokens
Complete CSS variable documentation with:
```css
:root {
    /* Extract ALL CSS variables from the HTML files */
    /* Group by category: colors, spacing, radius, shadows, etc. */
    /* Include comments describing each token */
}
```

### 3. Typography System
- Font family stack
- Complete typography scale table with:
  - Element/Use Case
  - Font Size
  - Font Weight
  - Color
  - Line Height
- Typography utility classes with code examples

### 4. Component Classes
Document EVERY component found in the HTML files with:
- Class name and purpose
- Complete CSS code
- Variants (if applicable)
- Usage notes

Organize by category:
- **Layout** (containers, grids, columns)
- **Cards** (all card variations)
- **Buttons** (all button types and states)
- **Forms** (inputs, textareas, selects, labels, file uploads)
- **Navigation** (navbar, links, menus)
- **Content Components** (articles, lists, chat bubbles, etc.)
- **UI Elements** (badges, tags, status indicators)
- **Specialized Components** (search bars, CTAs, heroes, sidebars)

### 5. Utility Classes
Complete list of utility classes for:
- Spacing (margins, padding)
- Typography (alignment, colors, weights)
- Display (flex, grid)
- Visibility
- Other utilities

### 6. Responsive Design
- Breakpoints used
- Mobile-first patterns
- Responsive grid behaviors
- Mobile-specific overrides

### 7. Animation & Transitions
- Timing functions
- Duration standards
- Transition patterns for different element types

### 8. Usage Examples
For each major component type, provide:
- Clean, minimal HTML example
- Real-world usage scenario
- Multiple examples showing variants

### 9. Accessibility Guidelines
- Color contrast requirements
- Focus states
- Semantic HTML recommendations
- Keyboard navigation notes
- ARIA considerations

### 10. Best Practices
- Implementation guidelines
- Common patterns
- Things to avoid
- Performance considerations

### 11. Additional Sections (if relevant)
- Color usage guidelines
- Icon/emoji usage
- Spacing scale
- Shadow elevation system

---

## Document 2: Reference Style Guide (HTML)

Create a comprehensive, interactive HTML file named `reference-styleguide-complete.html` that includes:

### Structure Requirements

1. **Self-Contained**: All CSS inline in a `<style>` tag
2. **Complete Design Tokens**: Include ALL CSS variables extracted from source files
3. **Live Examples**: Working, interactive examples of every component
4. **Organized Sections**: Clear sections with headers for each component category

### Required Sections

#### Header/Navigation
- Working navigation example from the source files

#### Color Palette Section
- Visual swatches for all colors
- Hex codes displayed
- Color names/variable names
- Organized by category (primary, secondary, neutrals, etc.)

#### Typography Section
- Live examples of every heading level
- Body text examples
- All typography variants demonstrated
- Labels, captions, meta text

#### Button Section
Demonstrate:
- All button variants (primary, secondary, outline, etc.)
- All sizes (small, medium, large)
- All states (normal, hover-able)
- Special buttons (pill, block, icon buttons)
- Button groups (if applicable)

#### Card Section
Show examples of:
- Basic cards
- Card variants (large, compact, etc.)
- Category cards
- Interactive cards with hover states
- Cards in grid layouts

#### Form Section
Include working examples of:
- Text inputs
- Textareas
- Select dropdowns (with custom styling)
- Checkboxes and radios (if in source)
- File uploads
- Input groups
- Form validation states (if applicable)
- Complete form layout example

#### Layout Section
Demonstrate:
- Container widths
- Grid systems
- Multi-column layouts
- Responsive behavior examples

#### Component Sections
For EVERY component found in source files, create a demo section:
- Search bars
- Navigation menus
- Article lists
- Chat interfaces
- Status badges
- Tabs/Pills (if applicable)
- Modals/Dialogs (if applicable)
- Tables (if applicable)
- Pagination (if applicable)
- Breadcrumbs (if applicable)
- And any other unique components

#### Utility Classes Section
Demonstrate utility classes with before/after examples

### Styling for the Style Guide Itself

Create a clean, professional layout for the style guide:
```css
.demo-section {
    /* Section container styling */
}

.demo-header {
    /* Section header styling - make it distinctive */
}

.demo-content {
    /* Content area styling */
}

.color-swatch {
    /* Color display boxes */
}
```

### Footer
- Notes about class prefixes
- Link to design guidelines
- Version information (if applicable)

---

## Output Format

Provide both files as downloadable outputs:
1. `/mnt/user-data/outputs/design-guidelines-complete.md`
2. `/mnt/user-data/outputs/reference-styleguide-complete.html`

---

## Quality Checklist

Before completing, ensure:

### Design Guidelines (MD)
- [ ] All CSS variables extracted and documented
- [ ] Every component class has complete CSS code
- [ ] At least 3-5 usage examples per major component
- [ ] Typography scale is complete with all variants
- [ ] Responsive patterns documented
- [ ] Accessibility guidelines included
- [ ] Best practices section is actionable

### Reference Style Guide (HTML)
- [ ] File opens and displays correctly in browser
- [ ] All colors displayed with swatches and codes
- [ ] Every component from source files is demonstrated
- [ ] Interactive elements work (hover states visible)
- [ ] Forms are functional (inputs accept text, etc.)
- [ ] Layout is clean and organized
- [ ] Sections are clearly labeled
- [ ] Self-contained (no external dependencies)

---

## Additional Instructions

1. **Be Thorough**: Don't skip any components, even small ones
2. **Extract Patterns**: If you see a pattern repeated, create a documented component for it
3. **Maintain Consistency**: Use the same class naming conventions from the source
4. **Provide Context**: Explain WHEN and WHY to use each component
5. **Think Developer-First**: Make it easy to copy-paste and implement
6. **Include Edge Cases**: Show how components look with long text, empty states, etc.

---

## Example Usage

After receiving these documents, a developer should be able to:
1. Understand the entire design system philosophy
2. Find any component they need with working code
3. Copy-paste implementation examples
4. See visual examples of every component
5. Understand responsive behavior
6. Know accessibility requirements
7. Follow best practices for implementation

---

Begin by analyzing all attached HTML files, then create both comprehensive documents.

I need you to analyze the attached HTML files and create two comprehensive design system documents:

### Document 1: Complete Design Guidelines (Markdown)
### Document 2: Interactive Reference Style Guide (HTML)

## Requirements for Both Documents

### Analysis Phase
First, thoroughly analyze ALL attached HTML files to extract:
1. **All CSS variables and design tokens** (colors, spacing, shadows, radius, etc.)
2. **All typography patterns** (font families, sizes, weights, line heights)
3. **All component patterns** (buttons, cards, forms, navigation, etc.)
4. **All layout patterns** (grids, containers, multi-column layouts)
5. **All utility classes** (margins, padding, text alignment, colors)
6. **All interaction patterns** (hover states, transitions, animations)
7. **Responsive breakpoints and mobile patterns**
8. **Naming conventions and prefixes used**

---

## Document 1: Design Guidelines (Markdown)

Create a comprehensive markdown file named `design-guidelines-complete.md` that includes:

### 1. Introduction Section
- **Design Philosophy**: Extract and articulate the design principles evident in the HTML
- **Key Characteristics**: What makes this design system unique
- **When to Use**: Guidance on appropriate use cases

### 2. Design Tokens
Complete CSS variable documentation with:
```css
:root {
    /* Extract ALL CSS variables from the HTML files */
    /* Group by category: colors, spacing, radius, shadows, etc. */
    /* Include comments describing each token */
}
```

### 3. Typography System
- Font family stack
- Complete typography scale table with:
  - Element/Use Case
  - Font Size
  - Font Weight
  - Color
  - Line Height
- Typography utility classes with code examples

### 4. Component Classes
Document EVERY component found in the HTML files with:
- Class name and purpose
- Complete CSS code
- Variants (if applicable)
- Usage notes

Organize by category:
- **Layout** (containers, grids, columns)
- **Cards** (all card variations)
- **Buttons** (all button types and states)
- **Forms** (inputs, textareas, selects, labels, file uploads)
- **Navigation** (navbar, links, menus)
- **Content Components** (articles, lists, chat bubbles, etc.)
- **UI Elements** (badges, tags, status indicators)
- **Specialized Components** (search bars, CTAs, heroes, sidebars)

### 5. Utility Classes
Complete list of utility classes for:
- Spacing (margins, padding)
- Typography (alignment, colors, weights)
- Display (flex, grid)
- Visibility
- Other utilities

### 6. Responsive Design
- Breakpoints used
- Mobile-first patterns
- Responsive grid behaviors
- Mobile-specific overrides

### 7. Animation & Transitions
- Timing functions
- Duration standards
- Transition patterns for different element types

### 8. Usage Examples
For each major component type, provide:
- Clean, minimal HTML example
- Real-world usage scenario
- Multiple examples showing variants

### 9. Accessibility Guidelines
- Color contrast requirements
- Focus states
- Semantic HTML recommendations
- Keyboard navigation notes
- ARIA considerations

### 10. Best Practices
- Implementation guidelines
- Common patterns
- Things to avoid
- Performance considerations

### 11. Additional Sections (if relevant)
- Color usage guidelines
- Icon/emoji usage
- Spacing scale
- Shadow elevation system

---

## Document 2: Reference Style Guide (HTML)

Create a comprehensive, interactive HTML file named `reference-styleguide-complete.html` that includes:

### Structure Requirements

1. **Self-Contained**: All CSS inline in a `<style>` tag
2. **Complete Design Tokens**: Include ALL CSS variables extracted from source files
3. **Live Examples**: Working, interactive examples of every component
4. **Organized Sections**: Clear sections with headers for each component category

### Required Sections

#### Header/Navigation
- Working navigation example from the source files

#### Color Palette Section
- Visual swatches for all colors
- Hex codes displayed
- Color names/variable names
- Organized by category (primary, secondary, neutrals, etc.)

#### Typography Section
- Live examples of every heading level
- Body text examples
- All typography variants demonstrated
- Labels, captions, meta text

#### Button Section
Demonstrate:
- All button variants (primary, secondary, outline, etc.)
- All sizes (small, medium, large)
- All states (normal, hover-able)
- Special buttons (pill, block, icon buttons)
- Button groups (if applicable)

#### Card Section
Show examples of:
- Basic cards
- Card variants (large, compact, etc.)
- Category cards
- Interactive cards with hover states
- Cards in grid layouts

#### Form Section
Include working examples of:
- Text inputs
- Textareas
- Select dropdowns (with custom styling)
- Checkboxes and radios (if in source)
- File uploads
- Input groups
- Form validation states (if applicable)
- Complete form layout example

#### Layout Section
Demonstrate:
- Container widths
- Grid systems
- Multi-column layouts
- Responsive behavior examples

#### Component Sections
For EVERY component found in source files, create a demo section:
- Search bars
- Navigation menus
- Article lists
- Chat interfaces
- Status badges
- Tabs/Pills (if applicable)
- Modals/Dialogs (if applicable)
- Tables (if applicable)
- Pagination (if applicable)
- Breadcrumbs (if applicable)
- And any other unique components

#### Utility Classes Section
Demonstrate utility classes with before/after examples

### Styling for the Style Guide Itself

Create a clean, professional layout for the style guide:
```css
.demo-section {
    /* Section container styling */
}

.demo-header {
    /* Section header styling - make it distinctive */
}

.demo-content {
    /* Content area styling */
}

.color-swatch {
    /* Color display boxes */
}
```

### Footer
- Notes about class prefixes
- Link to design guidelines
- Version information (if applicable)

---

## Output Format

Provide both files as downloadable outputs:
1. `/mnt/user-data/outputs/design-guidelines-complete.md`
2. `/mnt/user-data/outputs/reference-styleguide-complete.html`

---

## Quality Checklist

Before completing, ensure:

### Design Guidelines (MD)
- [ ] All CSS variables extracted and documented
- [ ] Every component class has complete CSS code
- [ ] At least 3-5 usage examples per major component
- [ ] Typography scale is complete with all variants
- [ ] Responsive patterns documented
- [ ] Accessibility guidelines included
- [ ] Best practices section is actionable

### Reference Style Guide (HTML)
- [ ] File opens and displays correctly in browser
- [ ] All colors displayed with swatches and codes
- [ ] Every component from source files is demonstrated
- [ ] Interactive elements work (hover states visible)
- [ ] Forms are functional (inputs accept text, etc.)
- [ ] Layout is clean and organized
- [ ] Sections are clearly labeled
- [ ] Self-contained (no external dependencies)

---

## Additional Instructions

1. **Be Thorough**: Don't skip any components, even small ones
2. **Extract Patterns**: If you see a pattern repeated, create a documented component for it
3. **Maintain Consistency**: Use the same class naming conventions from the source
4. **Provide Context**: Explain WHEN and WHY to use each component
5. **Think Developer-First**: Make it easy to copy-paste and implement
6. **Include Edge Cases**: Show how components look with long text, empty states, etc.

---

## Example Usage

After receiving these documents, a developer should be able to:
1. Understand the entire design system philosophy
2. Find any component they need with working code
3. Copy-paste implementation examples
4. See visual examples of every component
5. Understand responsive behavior
6. Know accessibility requirements
7. Follow best practices for implementation

---

Begin by analyzing all attached HTML files, then create both comprehensive documents.

Claude didn’t just list colors and fonts like a paint chip catalog.

It created a complete design philosophy:

Look at that structure—it’s like a love letter to your future self:

• Design philosophy (the WHY behind your choices)
• Design tokens (the WHAT of your system)
• Typography system (how words should dance)
• Component classes (the building blocks)
• Utility classes (your Swiss Army knife)
• Responsive patterns (because phones exist)
• Animation guidelines (movement with meaning)
• Usage examples (show, don’t just tell)
• Accessibility guidelines (because everyone deserves pretty apps)
• Best practices (learned the hard way so you don’t have to)

This isn’t documentation.

This is your design DNA.

The interactive reference was even better:

Live examples! Real components! Interactive demos!

It’s like having a tiny designer living in your computer.

(But less expensive and doesn’t judge your font choices.)

.

.

.

Step 4: Package Your Magic Into a Claude Skill (5 Minutes to Immortality)

Here’s where we turn stone into gold. Or design into reusable superpower.

(Same thing, really.)

Still in Claude Web, I asked:

Claude got it immediately:

Watch what’s happening—it’s like watching someone pack for a trip, but instead of forgetting their toothbrush, they remember everything:

• Reading the skill-creator documentation
• Understanding how to package design systems
• Checking reference patterns
• Organizing files with the care of Marie Kondo

The result:

Your skill package contains:

• SKILL.md (~300 lines of pure implementation wisdom)
• references/design-tokens.md (~1,900 lines of every design variable you’ll ever need)
• assets/template.html (~1,200 lines of interactive component library goodness)

Everything Claude Code needs to apply your design system to ANY component. It’s like having a design degree in a ZIP file.

.

.

.

Step 5: Installation Is So Easy It Feels Like Cheating (2 Minutes)

I downloaded the skill and added it to my project:

That’s it. That’s the installation process.

If you were expecting more steps, sorry to disappoint. Sometimes good things are simple.

(Unlike my relationship with CSS, which remains complicated.)

.

.

.

Step 6: Watch the Magic Happen (10 Minutes of Pure Satisfaction)

Back in Claude Code, I typed the magic words:

Claude recognized my skill immediately, like bumping into an old friend:

Then it went to work.

And friend, watching this is better than those satisfying pressure-washing videos:

Claude Code wasn’t just slapping styles around like a drunk painter.

It was methodical. Thoughtful. It:

• Read every component in the dashboard (getting to know the neighborhood)
• Understood the existing structure (respecting what was there)
• Mapped design patterns to components (matchmaking at its finest)
• Applied the Glass Aurora system consistently (no component left behind)

The transformation touched everything:

1. dashboard-client.tsx – Header, glass buttons, financial cards (the main stage)
2. dashboard-filters-bar.tsx – Glass-card container, themed filters (the supporting cast)
3. income-expense-chart-widget.tsx – Glass-card with gradient backgrounds (data, but make it fashion)
4. category-breakdown-chart-widget.tsx – Theme-aware chart colors (coordination is key)
5. accounts-overview-widget.tsx – Glass tooltips and grid layouts (the finishing touches)

Every. Single. Component.

Speaking the same design language.

Like a well-rehearsed choir instead of karaoke night at the dive bar.

The transformation?

From “generic SaaS tool #47,293” to “wait, what app is that and where can I get it?”

From forgettable to memorable.

From IKEA furniture to custom-built beauty.

And here’s the kicker: I can now redesign any page in seconds.

Not minutes. Not hours. Seconds.

(Are you crying? I’m not crying. It’s just… very dusty in here.)

.

.

.

Why This Changes Everything (And I Mean Everything)

Let’s talk about what just happened, because it’s bigger than it looks:

1. One design exploration session → 5 unique options to choose from
2. One selected design → Complete design system automatically documented
3. One Claude Skill → Infinite reusability across all your projects

Compare this to the traditional redesign process (aka the path of pain):

• Week 1: Design exploration (and existential crisis)
• Week 2: Component library building (and caffeine overdose)
• Week 3: Implementation (and debugging nightmares)
• Week 4: Consistency fixes (and more debugging)
• Week 5: Documentation (just kidding, nobody documents)

This approach?

• 30 minutes total
• Perfect consistency
• Reusable forever
• Documentation included

But here’s what really gets me excited (and I don’t get excited about many things anymore—I’m old and tired):

The skill gets smarter over time.

• Find a bug in the glass effect? Fix it once in the skill. Every project gets the update.
• Want to add a new component pattern? Update the skill. It’s everywhere instantly.
• Need to onboard a developer? Share the skill. They’re designing consistently from minute one.

Every improvement compounds.

It’s like investing in index funds, but for your design system. (That’s the most adult sentence I’ve ever written. I need to go lie down.)

.

.

.

The Benefits Nobody Mentions at Parties

Benefit #1: Design Consistency Without The Design Drama

You get enterprise-level design consistency without:

• Figma (and its 47 comments per component)
• Storybook (and its 3-hour setup process)
• A design team (and their strong opinions about kerning)

Just you, your skill, and perfect consistency.

It’s beautiful.

Benefit #2: Instant Design Language That Actually Makes Sense

That 300-line SKILL.md?

It’s not just documentation. It’s your design philosophy, your patterns, your principles—all captured automatically.

It’s like having a tiny design consultant living in your codebase, but one that never sends invoices.

Benefit #3: Version Control for Visual Design

Your design system is now code. Which means:

• Git trackable (see what changed and when)
• PR reviewable (catch issues before they ship)
• Rollback-able (when that neon green seemed like a good idea at 3 AM)

It’s version control for visuals.

The future is now, friend.

Benefit #4: Team Scalability Without the Scaling Pains

New developer joins the team?

Old way: “Here’s our 47-page design guide. Good luck!”

New way: “Use the sololedger-glass-aurora skill.”

Done.

They’re designing consistently from day one.

No training montage required.

Benefit #5: Professional Client Deliverables

That skill package? It’s also professional documentation you can hand to clients.

“Here’s our complete design system.”

Hands over ZIP file

Client is impressed

You look like a genius

(You ARE a genius, but now you have proof.)

.

.

.

Your Turn: From Generic to Gorgeous in 30 Minutes

Ready?

Here’s your recipe for design transformation:

Step 1: Pick Your Victim (I mean, page)

Don’t try to redesign everything at once. (That way lies madness.)

Start with one page. Dashboard, landing page, settings—doesn’t matter.

Pick the one that makes you saddest.

Step 2: Generate Your Options

Use Claude Code with the frontend-design skill. Ask for 5 variants.

Be specific about the vibe you want. “Make it pretty” is not specific. “Make it look like Spotify met a disco ball at a Nordic design conference” is specific.

(Also intriguing.)

Step 3: Fall in Love (Then Refine)

Choose your favorite. Get both theme versions. Make sure it sparks joy. (Yes, I’m Marie Kondo-ing your design system. Deal with it.)

Step 4: Birth Your Skill

Switch to Claude Web. Attach the HTML files. Generate comprehensive documentation. Package with skill-creator.

Watch your design system become immortal.

Step 5: Deploy Your Beauty Everywhere

Add to your project. Use the skill to redesign everything.

Feel that? That’s the satisfaction of consistency. It’s better than finding matching socks.

Step 6: Make It Better (Forever)

Your skill isn’t frozen in carbonite. Improve it. Expand it. Share it.

Every enhancement makes every project better.

It’s compound interest for your eyeballs.

.

.

.

The Real Talk Conclusion

I spent years accepting generic designs.

Not because I liked them.

But because custom design seemed too expensive—not in money, but in time.

Time I didn’t have.

Energy I couldn’t spare.

Mental bandwidth already allocated to remembering my passwords.

But what if custom design took 30 minutes instead of 30 days?

What if consistency was automatic instead of aspirational?

What if your design system could teach itself to any AI that needed it?

That’s not the future, friend. That’s what I just showed you.

My accounting app no longer looks like everyone else’s. It has personality. It has presence. It has that glass aurora glow that makes even tax calculations feel slightly magical. (Slightly. Let’s not get carried away—they’re still tax calculations.)

And it took less time than watching a Netflix episode.

(A short one. Not one of those prestige drama episodes that’s basically a movie.)

.

.

.

Here’s My Challenge to You

Open that project with the generic UI. You know the one. The one you show people quickly while saying “it’s still in beta.”

Give it 30 minutes. Just 30.

Generate your variants. Pick your favorite. Make it a skill.

Watch as your entire app transforms from “functional” to “fascinating.”

Because life’s too short for boring dashboards, friend.

And your apps deserve to be as unique as you are.

(Even if you’re not that unique. I’m kidding! You’re totally unique. Your mother was right.)

What design will you capture as a Claude Skill today?

Go. Create. Make the internet prettier.

We’re all counting on you.

(No pressure.)

P.S. – That glass aurora design I fell in love with? I’ve now applied it to three different projects. Same skill. Same consistency. Same “ooh, what’s that?” reaction from everyone who sees it. Total time to redesign all three: under an hour. The old way would have taken weeks, and they all would have looked slightly different, like siblings who don’t quite look related.

P.P.S. – Want to create your own design skills but feeling overwhelmed? Start here: Download the frontend-design skill from GitHub. Ask for design variants. Pick your favorite. Watch the magic happen. Then write me a thank-you note. Or don’t. I’ll just be here, admiring my glass aurora dashboard and feeling quietly superior to everyone still using default Bootstrap.

P.P.P.S. – Yes, I know that’s too many P.S.’s. But you’re still reading, aren’t you? See? Sometimes breaking the rules works. Just like breaking free from generic design. Full circle, friend. Full. Circle.