UI Standards Cleanup Guide¶

This guide documents the responsive design standards and cleanup applied to Campaign Brain (cbapp) based on the UI-STANDARDS framework.

Overview¶

The UI cleanup addresses WCAG accessibility compliance, responsive typography, and mobile touch targets across the cbapp frontend.

Compliance Target: WCAG 2.1 AA Estimated Improvement: 60% → 95%

Standards Applied¶

1. Fluid Typography¶

Typography now scales smoothly across all viewport sizes using CSS clamp():

/* Available CSS variables */
--text-xs:   clamp(0.75rem, 0.7rem + 0.25vw, 0.875rem)
--text-sm:   clamp(0.875rem, 0.8rem + 0.35vw, 1rem)
--text-base: clamp(1rem, 0.9rem + 0.5vw, 1.125rem)
--text-lg:   clamp(1.125rem, 1rem + 0.6vw, 1.25rem)
--text-xl:   clamp(1.25rem, 1.1rem + 0.75vw, 1.5rem)
--text-2xl:  clamp(1.5rem, 1.25rem + 1.25vw, 2rem)
--text-3xl:  clamp(1.875rem, 1.5rem + 1.875vw, 2.5rem)

Usage:

.my-heading {
    font-size: var(--text-2xl);
}

2. Touch Targets (WCAG 2.5.5)¶

All interactive elements meet the 44x44px minimum on mobile devices:

Element	Desktop	Mobile
`.btn`	As designed	44px min
`.btn-sm`	36px	44px min
`.btn-xs`	32px	44px min
`.btn-icon`	36px	44px min
`.contact-tool-btn`	36px	44px min
Form inputs	Standard	44px min

3. Focus States (WCAG 2.4.7)¶

All interactive elements now have visible focus indicators for keyboard navigation:

.btn:focus-visible {
    outline: 2px solid var(--primary-color);
    outline-offset: 2px;
}

4. Responsive Images¶

Images are constrained to prevent horizontal overflow:

img {
    max-width: 100%;
    height: auto;
}

Use .preserve-size class to opt-out if needed.

5. Readable Line Length¶

Body text is constrained to optimal reading width:

.prose, .card-body p, .modal-body p {
    max-width: 65ch;
}

Files Modified¶

CSS Files¶

File	Changes
`src/app/static/css/styles.css`	Fluid typography, focus states, responsive images, line length, `.btn-icon` class
`src/app/static/css/mobile-overrides.css`	44px touch targets, audience table constraints, touch device enhancements

Templates¶

File	Changes
`src/app/templates/work_queue.html`	Fixed contact tool buttons from 18-32px to 36-44px

Responsive Breakpoints¶

The app uses these standard breakpoints:

Breakpoint	Width	Description
Mobile	< 768px	Single column, drawer navigation, 44px touch targets
Tablet	768px - 1023px	Narrower sidebar, 2-column grids
Desktop	≥ 1024px	Full layout, multi-column grids

Using the Scanner¶

Run the responsive layout scanner to audit pages:

# Prerequisites
pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key

# Scan pages
cd docs/UI-STANDARDS
python scan.py https://your-app.com \
    --pages / /dashboard /audience /work-queue \
    --output ./scan-results

Output¶

report.md - Human-readable findings with screenshots
report.json - Structured data for CI/CD integration

Severity Levels¶

Level	Action
Critical	Must fix - breaks usability
Warning	Should fix - degrades UX
Suggestion	Nice to have

CSS Utility Classes¶

Visibility¶

<div class="hide-mobile">Hidden on mobile</div>
<div class="show-mobile-only">Shown only on mobile</div>
<div class="hide-tablet">Hidden on tablet</div>

Touch Targets¶

<button class="btn-icon" title="Edit">
    <i data-lucide="edit" class="w-4 h-4"></i>
</button>

Typography¶

<p class="prose">This text has optimal line length</p>
<p class="full-width">This text spans full width</p>

Checklist for New Components¶

When creating new UI components, verify:

Touch targets ≥ 44px on mobile
Focus states visible on keyboard navigation
Typography uses fluid variables
Images have max-width: 100%
Tables wrapped in .table-responsive
Body text constrained to 65ch
Tested at 375px, 768px, 1280px viewports

CI/CD Integration¶

Add scanner to your pipeline to catch regressions:

python scan.py https://staging.example.com --output ./qa

# Fail on critical issues
if grep -q '"severity": "critical"' ./qa/report.json; then
    echo "Critical responsive issues found!"
    exit 1
fi