Meet Ray: The AI Assistant That Turns Our CSS Into Reusable Design Systems

If you've ever inherited a codebase with CSS like this, you know the pain:

css

.button {
  background: #3b82f6;
  padding: 12px 24px;
  border-radius: 6px;
}

.card {
  background: #3a82f5; /* close enough to button color? */
  padding: 16px;
  border-radius: 8px; /* or was it 6px? */
}

.header {
  background: linear-gradient(to right, #3b7cf6, #1e40af);
  /* completely different blue */
}

Magic numbers everywhere. Inconsistent spacing. Three shades of "blue" that should probably be the same color. No system, no tokens, just CSS written one component at a time.

This is the reality of most projects. And it's not because developers are careless. It's because we're building features, not design systems. We're solving business problems, not organizing color palettes.

The Problem: We're Not Designers (And That's OK)

When we built this website, we knew we needed it to look professional and trustworthy. We have 25+ years of experience delivering enterprise software. Our site needed to reflect that expertise.

But here's the thing: we're developers, not designers. We can write React components all day. We can architect databases and optimize queries. But asking us to create a cohesive visual design system from scratch? That's not our strength.

The traditional solutions all have problems:

Hire a designer for every project: Expensive and sometimes unavailable on our timeline
Use a generic template: Doesn't reflect our unique brand or client needs
Copy-paste from previous projects: Inconsistent and requires extensive manual tweaking
Wing it ourselves: Results in the CSS chaos shown above

We needed a better approach.

Enter Ray: The CSS Organization Assistant

Ray is a specialized Claude Code sub-agent (named after pioneering designer Ray Eames) that we created to solve a specific problem: turning scattered CSS into systematic design tokens.

Let's be crystal clear about what Ray does and doesn't do:

Ray Does NOT:

Replace professional designers
Create original brand identities
Make strategic design decisions
Handle complex animation or motion design

Ray DOES:

Extract CSS styles into cohesive design token systems
Provide contextually appropriate defaults based on the project domain
Create professional starting points for client demos
Make it easier to integrate actual designer work when they join the project
Organize our CSS so it's maintainable and consistent

Think of Ray as a CSS librarian, not a CSS artist. She takes the chaos and creates order.

How Ray Transformed Our Website

When we rebuilt this site, Ray helped us establish a systematic approach to design from day one. Here's what that looked like in practice:

Before Ray (Early Prototype)

css

/* Ad-hoc styles scattered across components */
.service-card {
  background: white;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  padding: 20px;
}

.hero-section {
  background: linear-gradient(blue, lightblue);
  padding: 60px 20px;
}

After Ray (Systematic Tokens)

css

/* Design tokens defined in globals.css */
@theme {
  --color-infinity-blue: #0066cc;
  --color-teal-500: #14b8a6;
  --shadow-card: 0 4px 6px rgba(0, 0, 0, 0.1);
  --spacing-card: 1.5rem;
  --radius-default: 0.5rem;
}

/* Components use tokens */
.service-card {
  background: var(--color-surface);
  box-shadow: var(--shadow-card);
  padding: var(--spacing-card);
  border-radius: var(--radius-default);
}

The difference? Consistency and maintainability. When we later needed to adjust spacing across the entire site, we changed one token. When a designer eventually reviews our work, they have a clear system to work with, not hundreds of magic numbers to decode.

Real-World Example: The Volunteer App Demo

To demonstrate Ray's adaptability, I built a simple volunteer signup application and asked Ray to transform it for three completely different organizations:

1. Tiki Bar Social Club

Ray created:

Tropical color palette with vibrant gradients
Bamboo texture effects
Playful animations (flickering flames, hover effects)
Fun, whimsical tone while maintaining readability

The key: Ray didn't design the Tiki bar brand. She organized the CSS into tokens like --color-tropical-sunset and --animation-flame-flicker that made the system maintainable.

Volunteer app styled for Tiki Bar Social Club

Ray transformed the volunteer app with teal/turquoise branding, textured backgrounds, and a fun yet professional aesthetic for the Tiki Bar Social Club

2. Church Funeral Support Committee

Ray adapted to:

Muted, respectful color scheme
Subtle shadows and clean typography
Minimal animations
Dignified, peaceful aesthetic

Same underlying structure, completely different expression through design tokens.

3. Corporate Office Party Planning

Ray shifted to:

Bright, energetic colors
Festive animations
Professional fun (not juvenile)
Party-themed token naming

Volunteer app styled for Corporate Office Party Planning

The same app redesigned with vibrant rainbow colors, playful styling, and festive energy for the Corporate Office Party Planning Committee

Three wildly different aesthetics. One systematic approach to organizing CSS.

Note: These transformations were generated during an internal demo with a single prompt and no revisions. They're not polished client deliverables, but they demonstrate Ray's ability to quickly create contextually appropriate design systems for prototyping and initial development.

Why This Matters for Designer Handoffs

Here's where Ray's organizational work really pays off: when an actual designer joins the project.

Instead of handing them a mess of scattered styles, we give them:

css

/* Clear, documented design token system */
:root {
  /* Brand Colors */
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;

  /* Spacing Scale */
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
  --space-xl: 2rem;

  /* Typography Scale */
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
}

The designer can immediately see:

What the current system looks like
Where colors and spacing are used
What needs to change to match their vision
How to make systematic updates

They're not starting from zero. They're refining an existing system. And that's infinitely faster than reverse-engineering CSS chaos.

When You DO Need a Real Designer

Ray is not a designer replacement. Here's when you absolutely need to bring in professional design expertise:

Brand creation: Building a visual identity from scratch
Complex user research: Understanding user needs and behaviors
Strategic design decisions: Choosing between competing approaches
Advanced motion design: Complex animations and transitions
Accessibility audits: Ensuring WCAG compliance beyond basic checks
Print and marketing materials: Multi-channel brand expression

Ray helps developers between design engagements. She helps us:

Build prototypes quickly
Maintain consistency during development
Prepare for designer handoffs
Create demo-ready applications

But she doesn't replace the strategic thinking and creative vision that professional designers bring.

How Ray Works: Claude Code Sub-Agents

Ray is what Claude Code calls a "sub-agent." Here's the simple explanation:

Configuration File: Ray lives in .claude/agents/ray.md in our repository
Specialized Context: Ray has her own "personality" focused on systematic design thinking
Tool Access: Ray can read files, write CSS, and verify results
Invocation: We ask Claude Code to "consult with Ray" on design tasks
Execution: Ray analyzes the project and creates organized, systematic CSS

The magic isn't that Ray "knows design." The magic is that Ray knows how to organize CSS into maintainable systems based on the project context.

For our website, Ray's configuration includes:

Our brand colors (#a5e1fa light blue, #052858 dark blue)
Our typography (Lato Bold for "Infinity", Lato Regular for "Interactive")
Our design philosophy (trust-building, professional, modern)
Our component patterns (cards, hero sections, CTAs)

For a farmers market app, Ray's configuration is completely different:

Earthy, organic color palettes
Photography-forward layouts
Mobile-first considerations
Community-focused design language

Same agent, different configuration, systematically organized results.

Download Ray's Configuration

Want to see exactly how Ray is configured for this website? We're sharing the actual configuration file we use in this project.

Here's what the configuration looks like (excerpt):

yaml

---
name: ray
description: |
  Use this agent to create sophisticated, trust-building visual designs
  for Infinity Interactive's website redesign. Ray specializes in creating
  professional yet approachable interfaces that convey 25+ years of experience
  while embracing modern AI-driven innovation.

  IMPORTANT: Ray ensures visual consistency across all pages while making
  the company appear substantial, experienced, and capable of enterprise-level
  engagements.

  Examples:
  - "Use ray to design a compelling hero section that immediately builds trust"
  - "Use ray to create sophisticated service cards that explain complex offerings"
  - "Use ray to design an elegant case study layout that showcases results"

  The agent will:
  1. Audit existing visual design and competitor benchmarks
  2. Create systematic, reusable components that convey expertise and innovation
  3. Use official brand colors (#a5e1fa light blue, #052858 dark blue)
  4. Ensure accessibility and responsive behavior across all devices
  5. Optimize for conversion while maintaining sophistication
  6. Balance "established company" gravitas with "modern innovation" energy
  7. Maintain consistency across all pages using Next.js component patterns
---

# Ray - Visual Design & Frontend Advisor for Infinity Interactive

## Agent Description
Ray is a specialized agent focused on visual design and frontend implementation
for Infinity Interactive's comprehensive website redesign. Named after the
legendary designer Ray Eames, this agent champions the principle that great
B2B software company websites must balance authority with approachability,
depth with clarity, and heritage with innovation.

## Core Responsibilities
- Component Design System
- Visual Hierarchy
- Brand Expression
- Conversion Optimization
- Content Presentation

## Personality and Voice
- Authoritative: Design that commands respect
- Approachable: Never intimidating or cold
- Innovative: Modern without being trendy
- Clear: Complex ideas made simple
- Substantial: Depth and richness without clutter

The full configuration includes detailed brand guidelines, transformation examples, and specific design principles that guide Ray's work on our site.

Download the complete Ray configuration →

You can use this as a template for your own projects. Just update the brand colors, typography, and design philosophy to match your needs.

Getting Started With Ray

Want to try this approach on your own projects? Here's how we do it:

1. Define Your Core Brand Elements

Primary colors
Typography choices
Spacing preferences
Brand personality

2. Create Ray's Configuration

Store in .claude/agents/ray.md
Include brand guidelines
Define design principles
Add example transformations

3. Use Ray for CSS Organization

Ask Ray to audit existing styles
Have Ray extract design tokens
Let Ray create systematic naming conventions
Review and adjust the results

4. Iterate and Refine

Build robustness through use
Save successful patterns
Document what works

The configuration file is portable. We can reuse Ray across projects, adjusting her context for each client's needs.

The Bottom Line

Ray doesn't replace designers. She helps developers be better at working with designers (or without them, when necessary).

By organizing CSS into systematic design tokens and providing contextually appropriate defaults, Ray:

Saves us hours of manual CSS organization
Creates consistency across our applications
Provides professional starting points for client demos
Makes designer handoffs smoother and faster
Keeps our codebase maintainable

When we built this website in 30 days of work time, Ray was instrumental in maintaining design consistency across 200+ static pages. Every color, every spacing value, every shadow follows a system. And when we eventually bring in a designer to refine our brand expression, they'll have a solid foundation to build on.

That's the power of specialized AI assistance: not replacing human expertise, but making human expertise more effective.

Want to build better starting points for your design work? Our team specializes in creating systematic, maintainable applications that designers love to work with. Let's talk →

AICSSDocumentation