AI Implementation Guide

Build brand-compliant UIs with visual verification and quality gates

For AI Agents

This guide is mandatory for any AI agent implementing UI/UX with Alterspective branding. It combines automated validation with vision-based analysis to ensure perfect brand compliance.

The 10 Critical Rules

These rules are non-negotiable and must always be followed:

LOGO-001 Logo

Logo must be LEFT or RIGHT aligned, NEVER centered

Brand identity consistency

COLOR-001 Color

NEVER use white text on Citrus (#ABDD65)

Contrast ratio 1.6:1 fails WCAG AA

ICON-001 Icons

Icons must be outlined style only, NEVER filled

Brand consistency with logo geometry

LOGO-002 Logo

No effects on logo (shadows, gradients, filters)

Maintain logo integrity and recognition

A11Y-001 Accessibility

Minimum 4.5:1 contrast ratio for all text

WCAG 2.2 Level AA compliance required

LOGO-003 Logo

Use reversed logo on dark backgrounds

Ensure logo visibility and contrast

TYPO-001 Typography

Chronicle Display for 36px+ headings, Montserrat for body

Brand typography consistency

TYPO-002 Typography

Chronicle Display: only Light (300), Roman (400), Semibold (600)

Limited weights maintain visual coherence

TYPO-003 Typography

Montserrat: only Regular (400), Medium (500), Semibold (600), Bold (700)

Limited weights maintain visual coherence

A11Y-002 Accessibility

Dark mode MUST have explicit styles for ALL text - never rely on inherited colors

Without overrides, text becomes invisible on dark backgrounds

LOGO-004 Logo

MUST use actual logo IMAGE file, NEVER text substitutes

Text like "ALTERSPECTIVE" is not brand compliant - use PNG/SVG assets

Required Brand Assets (Mandatory)

When building ANY Alterspective-branded interface, you MUST include these elements:

Logo Image (CRITICAL)

⚠️ Use the actual logo IMAGE file - NEVER substitute with text

The logo must be an <img> tag pointing to the logo asset, not styled text.

Dark Backgrounds (Navy, Marine)

Alterspective_Logo_reversed_FA.png

White logo for headers, dark sections

Light Backgrounds (White, Pale Blue)

Alterspective_Logo_FA.png

Standard logo for light sections

Asset Location: alterspective-ai-brand-guide/assets/logos/

Common AI Mistakes to Avoid

❌ WRONG <span class="logo">ALTERSPECTIVE</span>

Text is NOT a logo

❌ WRONG <div class="logo-text">Alterspective</div>

Styled text is NOT a logo

✅ CORRECT <img src="/assets/logo/reversed" alt="Alterspective" />

Actual image file

✅ CORRECT <img src="/logo.png" alt="Alterspective" />

Embedded or served image

Brand Implementation Checklist

Before considering a UI "brand compliant", verify:

  • Actual logo IMAGE is displayed (not text)
  • Correct logo variant for background colour
  • Logo is LEFT or RIGHT aligned (never centred)
  • Minimum logo width: 100px (screen)
  • No effects on logo (shadows, gradients, filters)
  • Brand fonts loaded (Chronicle Display, Montserrat)
  • Brand colours used via CSS variables
  • 4.5:1 minimum contrast ratio for all text

Visual Verification Workflow

Every UI/UX implementation must pass through these quality gates:

1

Build

Implement UI using design tokens and components following brand rules

  • Use CSS variables from design tokens
  • Apply correct typography scale
  • Ensure proper color combinations
2

Capture Screenshots

Use Playwright to capture visual evidence

  • Full page screenshot
  • Logo placement close-up
  • Color usage sections
  • Typography examples
  • Icon implementations
  • Dark mode variant
3

Vision Analysis

Analyze screenshots with AI vision capabilities

  • Verify logo alignment (left/right, never center)
  • Check no white on Citrus (#ABDD65)
  • Confirm outlined icons only
  • Validate no logo effects
  • Calculate contrast ratios (4.5:1 minimum)
  • Verify reversed logo on dark
  • Check font families and sizes
4

Automated Validation

Run brand-validator CLI for automated checks

npx brand-validator validate ./screenshots/*.png --rules all
5

Report & Fix

Document findings and fix any violations

  • Create verification report
  • List all issues found
  • Fix critical violations
  • Re-run verification
  • Commit screenshots as evidence

Quality Gates

All implementations must pass these gates before completion:

✓

Gate 1: Build & Tests

  • npm run build succeeds
  • npm test passes
  • Zero TypeScript errors
📸

Gate 2: Screenshots

  • All 6 required screenshots captured
  • Playwright test runs successfully
  • Images saved to repo
👁️

Gate 3: Visual Verification

  • All 10 critical rules verified
  • Vision analysis completed
  • Automated validator passes
  • Zero critical issues
📝

Gate 4: Documentation

  • Verification report created
  • All findings documented
  • Screenshots committed
  • Ready for QA review

This Page Demonstrates Perfect Implementation

This very page follows all 9 critical brand rules. Here's how:

✓ LOGO-001: Left Alignment

Logo in header is left-aligned using justify-content: flex-start (never centered)

✓ COLOR-001: No White on Citrus

All Citrus accent colors use Navy (#17232D) text, achieving 6.7:1 contrast ratio

✓ ICON-001: Outlined Icons

Step numbers and icons use outlined style with stroke="currentColor"

✓ LOGO-002: No Effects

Logo has zero filters, shadows, or gradients applied

✓ A11Y-001: 4.5:1 Contrast

Navy on White (15.97:1), Marine on White (9.05:1) - all exceed minimum

✓ LOGO-003: Reversed on Dark

Header uses Navy background with reversed white logo variant

✓ TYPO-001: Correct Fonts

Headings use Chronicle Display (self-hosted), body uses Montserrat. Only permitted weights are used.

✓ LOGO-004: Actual Logo Image

Header uses actual <img> tag with logo asset, not text like "ALTERSPECTIVE"

Typography Implementation

Typography is critical to brand identity. Here's how to implement fonts correctly:

Chronicle Display

For headings 36px and larger

Light (300) Roman (400) Semibold (600)
Download:
Light.otf Roman.otf Semibold.otf
var(--as-font-display)

Montserrat

For body text and headings under 36px

Regular (400) Medium (500) SemiBold (600) Bold (700)
Download:
Regular.ttf Medium.ttf SemiBold.ttf Bold.ttf
var(--as-font-body)

Typography Rules (MUST Enforce)

  • TYPO-001: Chronicle Display for 36px+ headings, Montserrat for everything else
  • TYPO-002: Chronicle Display weights: only 300, 400, 600 (never 700, 900)
  • TYPO-003: Montserrat weights: only 400, 500, 600, 700 (never 100, 200, 300, 800, 900)

CSS Implementation

/* Font Face Declarations */
@font-face {
  font-family: 'Chronicle Display';
  src: url('/api/assets/fonts/chronicle-display/Chronicle%20Display%20Roman.otf') format('opentype');
  font-weight: 400;
  font-display: swap;
}

/* CSS Variables */
:root {
  --as-font-display: 'Chronicle Display', Georgia, serif;
  --as-font-body: 'Montserrat', 'Helvetica Neue', Arial, sans-serif;
}

/* Usage */
h1 { font-family: var(--as-font-display); font-size: 48px; }
p { font-family: var(--as-font-body); font-size: 16px; }

Ready to Implement?

Start with the Playwright test template and verification report template from the repository:

demos/brand-verification/template.spec.ts Playwright test template
demos/brand-verification/VERIFICATION-TEMPLATE.md Report template
project/AI-BRAND-IMPLEMENTATION-GUIDE.md Complete guide

Additional Resources

Color Palette

View all brand colors and contrast requirements →

Typography

Font downloads, installation guides, and scale →

All Rules

Complete critical rules reference →

Components

Pre-built component specifications →

Assets

Download logos, icons, fonts and patterns →

MCP Server

Configure AI tools for brand compliance →
Style
Theme