Aura Brand Implementation Guide

This guide provides specific implementation details for maintaining brand consistency in the Aura frontend codebase.

📁 File Structure

frontend/
├── docs/
│   ├── BRAND_GUIDELINES.md      # Comprehensive brand guidelines
│   └── BRAND_IMPLEMENTATION.md  # Implementation specifics (this file)
├── tailwind.config.ts           # Tailwind configuration with brand colors
├── src/
│   ├── app/
│   │   └── globals.css          # Global styles and brand utilities
│   └── components/
│       ├── ui/                 # UI component library
│       └── AgentConsole.tsx    # Main application component

🎨 Color Implementation

Tailwind Configuration

All brand colors are defined in tailwind.config.ts:

colors: {
  // Primary Brand Colors
  'cyberpunk-blue': '#00f2ff',
  'cyberpunk-purple': '#a855f7',
  'cyberpunk-pink': '#ec4899',
  
  // Neutral Colors
  'dark-bg': '#0a0a0a',
  'card-bg': '#1a1a1a',
  'gray-800': '#1f1f1f',
  'gray-700': '#373737',
  'gray-600': '#4b4b4b',
  'gray-500': '#6b6b6b',
  'gray-400': '#9ca3af',
  'gray-300': '#d1d5db',
  
  // Semantic Colors
  'success': '#10b981',
  'warning': '#f59e0b',
  'error': '#ef4444',
  'info': '#3b82f6',
}

Usage with Inline Classes

Aura follows Tailwind's utility-first philosophy by using inline classes rather than custom utility classes. This approach:

• Keeps styles explicit and visible in components

• Enables tree-shaking for unused styles

• Makes it easier to customize per-component

• Reduces CSS file size

Primary CTA Button:

<Button className="bg-cyberpunk-blue hover:bg-cyberpunk-blue/90 text-white font-semibold py-2 px-4 rounded-md transition-all duration-200">
  Submit
</Button>

Secondary Button:

<Button className="bg-cyberpunk-purple hover:bg-cyberpunk-purple/90 text-white font-semibold py-2 px-4 rounded-md transition-all duration-200">
  Cancel
</Button>

Card Component:

<Card className="bg-card-bg border border-gray-700 rounded-lg shadow-card">
  {/* Card content */}
</Card>

Input Field:

<Input className="bg-gray-800 border border-gray-600 text-white rounded-md py-2 px-3 focus:outline-none focus:border-cyberpunk-blue focus:ring-1 focus:ring-cyberpunk-blue" />

Error State:

<Alert className="bg-error/20 border-error">
  <AlertTitle className="text-error h4">Error</AlertTitle>
  <AlertDescription className="body-text">Something went wrong</AlertDescription>
</Alert>

📐 Typography Implementation

Font Families

The Inter font family is used as the primary typeface:

@layer base {
  body {
    @apply font-sans; /* Uses Inter font stack */
  }
}

Typography Classes

Semantic typography classes are defined in globals.css for consistent text hierarchy:

/* Heading Styles */
h1, .h1 {
  font-size: 3rem;
  line-height: 1.2;
  font-weight: 700;
  color: white;
}
h2, .h2 {
  font-size: 2.25rem;
  line-height: 1.2;
  font-weight: 600;
  color: white;
}
h3, .h3 {
  font-size: 1.875rem;
  line-height: 1.2;
  font-weight: 600;
  color: white;
}
h4, .h4 {
  font-size: 1.5rem;
  line-height: 1.2;
  font-weight: 600;
  color: white;
}

/* Body Text */
p, .body-text {
  font-size: 1rem;
  line-height: 1.5;
  color: #9ca3af;
}
.body-text-sm {
  font-size: 0.875rem;
  line-height: 1.5;
  color: #9ca3af;
}
.caption-text {
  font-size: 0.75rem;
  line-height: 1.4;
  color: #6b6b6b;
}

Note: These semantic classes use CSS properties directly rather than @apply directives due to Tailwind CSS v4 constraints with custom color references.

Usage Examples

Main Heading:

<h1 className="h1">Aura Agent Console</h1>

Section Heading:

<h3 className="h3 text-cyberpunk-blue">Search Inventory</h3>

Body Text:

<p className="body-text">Find items to negotiate</p>

Caption:

<span className="caption-text">ID: {item.itemId}</span>

🎯 Component Styles

Card Component

Use inline Tailwind classes for consistent card styling:

<Card className="bg-card-bg border border-gray-700 rounded-lg shadow-card">
  {/* Card content */}
</Card>

This applies:

• Background: bg-card-bg (#1a1a1a)

• Border: border-gray-700 (#373737)

• Border Radius: rounded-lg (0.5rem / 8px)

• Shadow: shadow-card (subtle card shadow)

Input Component

Use inline Tailwind classes for consistent input styling:

<Input className="bg-gray-800 border border-gray-600 text-white rounded-md py-2 px-3 focus:outline-none focus:border-cyberpunk-blue focus:ring-1 focus:ring-cyberpunk-blue" />

This applies:

• Background: bg-gray-800 (#1f1f1f)

• Border: border-gray-600 (#4b4b4b)

• Text: text-white

• Focus: cyberpunk-blue ring with outline removal

Button Components

Use inline Tailwind classes for consistent button styling:

// Primary button
<Button className="bg-cyberpunk-blue hover:bg-cyberpunk-blue/90 text-white font-semibold py-2 px-4 rounded-md transition-all duration-200">
  Submit
</Button>

// Secondary button
<Button className="bg-cyberpunk-purple hover:bg-cyberpunk-purple/90 text-white font-semibold py-2 px-4 rounded-md transition-all duration-200">
  Cancel
</Button>

// Destructive button
<Button className="bg-error hover:bg-error/90 text-white font-semibold py-2 px-4 rounded-md transition-all duration-200">
  Delete
</Button>

🎭 Animations & Transitions

Transitions

Use inline Tailwind classes for consistent transitions:

<div className="transition-all duration-200">
  {/* Content with smooth transitions */}
</div>

Common transition patterns:

// All properties
className="transition-all duration-200"

// Specific properties
className="transition-colors duration-200"
className="transition-transform duration-300"
className="transition-opacity duration-150"

Fade-in Animation

Use the animate-fade-in utility class for fade-in effects:

<div className="animate-fade-in">
  {/* Content that fades in */}
</div>

This animation is defined in globals.css using @keyframes:

@keyframes fadeIn {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.animate-fade-in {
  animation: fadeIn 0.3s ease-out forwards;
}

🌙 Dark Mode Implementation

Aura uses a dark-first approach with Tailwind's dark mode:

// tailwind.config.ts
darkMode: 'class',

<!-- In your layout -->
<html className="dark">
  <body className="bg-dark-bg text-white">
    {/* Content */}
  </body>
</html>

📱 Responsive Design

Breakpoints

Use Tailwind's built-in breakpoints:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* Responsive grid */}
</div>

Container Sizing

<div className="max-w-7xl mx-auto px-4">
  {/* Content with proper max-width and padding */}
</div>

🔒 Accessibility

Focus Styles

Global focus styles are defined in globals.css:

*:focus {
  outline: none;
  box-shadow: 0 0 0 2px #0a0a0a, 0 0 0 4px #00f2ff;
}

This creates a dual-ring focus indicator:

• Inner ring: dark-bg (#0a0a0a) - 2px offset

• Outer ring: cyberpunk-blue (#00f2ff) - 4px offset

For component-specific focus states, use inline Tailwind classes:

<Input className="focus:outline-none focus:border-cyberpunk-blue focus:ring-1 focus:ring-cyberpunk-blue" />

Semantic HTML

Always use semantic HTML elements:

// Good
<button onClick={handleClick}>Click me</button>

// Bad
<div onClick={handleClick}>Click me</div>

ARIA Attributes

Use proper ARIA attributes:

<button aria-label="Search" aria-disabled={isLoading}>
  <SearchIcon />
</button>

📋 Component Checklist

Creating New Components

1. Color: Use brand colors from Tailwind config (e.g., bg-cyberpunk-blue, text-gray-400)

2. Typography: Use semantic typography classes (.h1, .h2, .body-text, .caption-text)

3. Spacing: Use Tailwind's spacing scale (e.g., p-4, space-y-2, gap-4)

4. Borders: Use border-gray-700 for standard borders

5. Transitions: Add transition-all duration-200 for interactive elements

6. Accessibility: Ensure proper focus states and ARIA attributes

7. Responsive: Test on all breakpoints (use sm:, md:, lg: prefixes)

8. Dark Mode: Verify dark mode compatibility

Component Review

• Uses brand colors correctly

• Follows typography guidelines

• Has proper spacing

• Includes hover/focus states

• Is accessible (keyboard, screen reader)

• Works on mobile devices

• Supports dark mode

• Has consistent transitions

🔧 Development Workflow

Adding New Colors

1. Add to tailwind.config.ts

2. Document in BRAND_GUIDELINES.md

3. Update BRAND_IMPLEMENTATION.md with usage examples

4. Test contrast ratios

Adding New Typography

1. Define in globals.css

2. Add to typography table in guidelines

3. Document usage patterns

Creating New Components

1. Follow existing patterns

2. Use brand utility classes

3. Add to component library if reusable

4. Document component usage

🧪 Testing Brand Consistency

Visual Regression Testing

Use tools like:

• Storybook for component isolation

• Chromatic for visual regression testing

• BrowserStack for cross-browser testing

Automated Checks

// Example: Color contrast check (pseudo-code)
const checkContrast = (foreground, background) => {
  const contrastRatio = calculateContrast(foreground, background);
  if (contrastRatio < 4.5) {
    console.warn(`Low contrast: ${contrastRatio}`);
  }
}

📝 Common Patterns

Gradient Backgrounds

Use the bg-cyberpunk-gradient utility for gradient backgrounds:

<h1 className="bg-cyberpunk-gradient bg-clip-text text-transparent">
  Aura Agent Console
</h1>

The gradient is defined in tailwind.config.ts:

backgroundImage: {
  'cyberpunk-gradient': 'linear-gradient(135deg, #00f2ff 0%, #a855f7 100%)',
}

Status Badges

<Badge variant={score > 0.8 ? 'default' : 'secondary'} className="caption-text">
  {score}%
</Badge>

Loading States

<Button disabled={isLoading} className="bg-cyberpunk-blue hover:bg-cyberpunk-blue/90 text-white font-semibold py-2 px-4 rounded-md transition-all duration-200">
  {isLoading ? 'Processing...' : 'Submit'}
</Button>

Interactive Cards

<Card
  className="bg-card-bg border border-gray-700 rounded-lg shadow-card cursor-pointer hover:border-cyberpunk-blue transition-all duration-200"
  onClick={handleClick}
>
  {/* Card content */}
</Card>

🔗 Integration with Design Tools

Figma to Code

1. Use Figma's Tailwind plugin

2. Map Figma styles to Tailwind classes

3. Export assets with proper naming

4. Use Figma variables for brand colors

Design Token Management

// Example design tokens (conceptual)
{
  "colors": {
    "primary": {
      "value": "#00f2ff",
      "name": "cyberpunk-blue"
    }
  },
  "typography": {
    "h1": {
      "fontSize": "3rem",
      "fontWeight": "700",
      "lineHeight": "1.2"
    }
  }
}

📋 Maintenance

Updating Brand Guidelines

1. Update BRAND_GUIDELINES.md

2. Update BRAND_IMPLEMENTATION.md

3. Update Tailwind config

4. Update global CSS

5. Create migration guide if needed

6. Update all components

Versioning

Follow semantic versioning for brand changes:

• Patch: Minor tweaks, bug fixes

• Minor: New components, non-breaking changes

• Major: Complete redesign, breaking changes

🤝 Contributing

Reporting Brand Issues

1. Open GitHub issue

2. Tag with brand label

3. Include screenshots

4. Specify location

5. Suggest fix if possible

Brand Review Process

1. Design team review

2. Engineering team implementation

3. QA testing

4. Stakeholder approval

5. Documentation update

---

© 2024 Aura Platform. All rights reserved.