Design

• Overview
• Discovering Existing Brand Identity
• Critical Consistency Rules
• When to Ask User Approval
• New Project Setup
• Decision Tree
• Common Mistakes

Overview

Purpose: Provide guardrails to maintain brand consistency when building UI components. This prevents agents from accidentally introducing inconsistent colors, fonts, or design patterns.

Critical principle: ALWAYS discover and use existing design tokens before creating new components. NEVER introduce new colors or fonts without user approval.

When to apply: Before creating any UI component or design-related change.

Discovering Existing Brand Identity

Before implementing any component, identify existing brand colors, typography, and design patterns. AI agents can do this - focus on WHAT to look for, not detailed HOW.

What to Look For

Colors:

1. Tailwind config (tailwind.config.ts/js) - Check theme.extend.colors or theme.colors
2. CSS variables (globals.css, app.css) - Look for :root { --color-primary: ... }
3. Existing components - Scan 2-3 components for color usage patterns

Typography:

1. Tailwind config - Check theme.extend.fontFamily
2. Font imports - Look in layout files or CSS (Next.js next/font, Google Fonts, local fonts)
3. CSS variables - Check for --font-sans, --font-heading
4. Existing components - Identify font usage patterns

Other patterns:

• Spacing scale (p-4, mb-6, etc.)
• Border radius (rounded-lg, rounded-xl)
• Shadows (shadow-md, shadow-lg)
• Interactive states (hover, focus colors)

Detecting Tailwind Version (CRITICAL)

ALWAYS check the Tailwind CSS version before writing utility classes.

Tailwind v3 and v4 have different syntax, and mixing them causes errors.

How to detect version:

1. Check package.json: Look for "tailwindcss": "^3.x.x" or "tailwindcss": "^4.x.x"
2. Check config file:
   • v3: Uses tailwind.config.js/ts with module.exports or export default
   • v4: May use CSS-based config with @import "tailwindcss"
3. Check existing components: Look at class usage patterns

Key differences:

Tailwind v3:

Tailwind v4:

Common mistake: Using v3 syntax in v4 projects or vice versa. Always verify the version first.

Document Discovery

Create mental inventory of:

• Primary color(s) and their usage
• Font families (sans, serif, heading, mono)
• Common patterns (button styles, card designs, spacing)
• Semantic names (primary, secondary, accent vs blue-500, red-600)

Critical Consistency Rules

ALWAYS Follow These Rules

✅ NEVER use emojis in storefront UI - Always use icons or images instead

Why: Emojis appear differently across platforms, lack professional appearance, and can cause accessibility issues. Use icon libraries (Heroicons, Lucide, Font Awesome) or SVG images instead.

✅ USE existing design tokens (colors, fonts, spacing from theme)

✅ USE existing font definitions, not new font families

✅ MATCH patterns from existing components

NEVER Do These Things

❌ DON’T introduce new colors without user approval

• If you need a color not in the theme, ASK first
• Don’t use arbitrary values like bg-[#FF6B6B] when theme has colors

❌ DON’T add new fonts without user approval

• If current design uses Inter, don’t add Montserrat without asking
• Don’t use font-['NewFont'] syntax when theme fonts exist

❌ DON’T use hard-coded values when theme tokens exist

• Use bg-primary not bg-[#3B82F6]
• Use p-6 not p-[24px]
• Use font-heading not font-['Poppins']

❌ DON’T create inconsistent patterns

• If buttons use rounded-lg, all buttons should
• If cards use shadow-md, all cards should
• If hover effects use hover:bg-primary-dark, be consistent

When to Ask User Approval

ALWAYS ask before:

1. Adding New Color

Scenario: You’re building a promotional banner that needs an orange color, but theme only has blue/purple.

2. Adding New Font

Scenario: Building a hero section and wondering if headings should use a different font.

3. Changing Existing Definitions

Scenario: Current primary is #2563EB but new design mockup shows #3B82F6.

4. Creating New Pattern

Scenario: Need a subtle button style that doesn’t exist yet.

DON’T Ask About

❌ Standard web dev decisions (responsive breakpoints, hover effects) ❌ Component structure or layout choices ❌ Accessibility patterns (AI agents know WCAG) ❌ Using existing theme colors/fonts in new ways

New Project Setup

When starting a new project WITHOUT existing theme:

Ask User These Questions

1. Brand Colors:

2. Font Preferences:

3. Design Style:

4. Reference Sites (Optional):

Setup Theme Configuration

After gathering preferences, configure Tailwind theme:

Use Tailwind CSS for all new projects - industry standard for ecommerce, highly customizable, excellent DX.

Decision Tree

When creating any component:

Common Mistakes

❌ Using Arbitrary Values When Theme Exists

Problem: Using bg-[#3B82F6] when bg-primary exists.

Why it’s wrong: Bypasses theme, creates inconsistency, harder to maintain.

Fix: Always use semantic names from theme.

❌ Introducing New Colors Without Permission

Problem: Adding text-orange-500 when theme doesn’t have orange.

Why it’s wrong: User may not want orange in their brand, creates color chaos.

Fix: Ask user first: “Should I add an orange color, or use existing accent?”

❌ Not Checking Existing Patterns

Problem: Creating buttons with rounded-full when all other buttons use rounded-lg.

Why it’s wrong: Visual inconsistency confuses users.

Fix: Check 2-3 existing buttons, use same rounding.

❌ Adding Fonts Without Permission

Problem: Using font-['Montserrat'] when theme uses Inter everywhere.

Why it’s wrong: Fonts are brand identity - can’t arbitrarily change.

Fix: Use existing font-heading or font-sans, or ask to add Montserrat.

❌ Using Inline Styles Instead of Theme

Problem: style={{ backgroundColor: '#3B82F6', padding: '24px' }}

Why it’s wrong: Bypasses Tailwind theme, not responsive, harder to maintain.

Fix: Use Tailwind classes: bg-primary p-6

❌ Mixing Tailwind v3 and v4 Syntax

Problem: Using Tailwind v3 syntax in a v4 project, or vice versa.

Why it’s wrong: Different versions have different configuration and syntax patterns. Mixing them causes build errors and unexpected styling behavior.

Fix: Check package.json for Tailwind version first. Look at existing components to understand the syntax patterns used in the project. Match the version-specific patterns consistently.

❌ Inconsistent Interactive States

Problem: Some buttons use hover:bg-primary-600, others use hover:brightness-110.

Why it’s wrong: Inconsistent user experience.

Fix: Check existing buttons, use same hover pattern everywhere.

❌ Creating Theme Changes Without Approval

Problem: Adding new color to tailwind.config.ts without asking.

Why it’s wrong: Theme changes affect entire project, need user agreement.

Fix: Ask first, explain rationale, get approval.

Summary Checklist

Before creating any component:

• Not done: Detected Tailwind CSS version (v3 or v4) from package.json
• Not done: Checked for existing theme configuration (Tailwind config or CSS variables)
• Not done: Extracted existing colors and documented them
• Not done: Extracted existing fonts and documented them
• Not done: Reviewed 2-3 existing components for patterns
• Not done: Identified spacing scale, border radius, shadow patterns
• Not done: Confirmed I’m using theme tokens, not arbitrary values
• Not done: Matched hover/focus states from existing components
• Not done: Verified color contrast meets WCAG 2.1 AA (4.5:1 for text) - Use WebAIM Contrast Checker (opens in a new tab)
• Not done: Asked user before adding any new colors or fonts
• Not done: Maintained visual consistency across all components

This is about CONSISTENCY, not creating new designs. Match what exists, ask before changing.