Fluxora-Frontend: Visual Consistency Design Delivery

Complete Assignment Deliverables & Verification Guide

Assignment: Visual consistency: marketing site vs authenticated app chrome
Date: March 30, 2026
Status: ✅ COMPLETE – Ready for Engineering Implementation
Owner: [Your Name] – Web Developer (15+ years experience)

Executive Summary

This delivery addresses the visual inconsistency between Fluxora-Frontend's marketing site (landing page) and authenticated app (dashboard, streams, recipient).

Problem: Users experience jarring UX transitions—inconsistent colors, buttons, spacing, typography, and missing accessibility standards.

Solution:

Unified design system with CSS variable tokens (colors, typography, spacing, shadows)
Component state specifications for all interactive elements
WCAG 2.1 AA accessibility compliance built-in
Implementation-ready specifications preventing engineering guesswork
Complete QA protocol for verification

Scope: Layout, hierarchy, interaction states, accessibility, all responsive breakpoints.

Deliverables Overview

📋 Core Documents (4 files)

Document	Purpose	Audience	Key Sections
DESIGN_SPEC.md	Design intent, tokens, component specs, accessibility	PM, Design, Eng	Colors, Typography, Spacing, States, A11y, Responsive
COMPONENT_STATES.md	Implementation specs per component	Engineers	Button, Input, NavItem, Modal, EmptyState, StatusBadge
TESTING_CHECKLIST.md	Complete QA protocol	QA, Testers	Visual, Interactive, Accessibility, Mobile, DevTools
IMPLEMENTATION_HANDOFF.md	Step-by-step engineering guide	Engineers, Tech Lead	Setup, Refactoring, Migration, Sign-off

🎨 Design Tokens (1 file)

File	Content	Usage
src/design-tokens.css	CSS variables (colors, typography, spacing, animations)	Import at top of main.tsx

How to Use These Deliverables

For Design & Product (PM, Design Lead)

Review DESIGN_SPEC.md
- Understand the visual system and token strategy
- Validate color palette, typography scale, spacing
- Confirm accessibility targets (WCAG 2.1 AA)
- Defer any items beyond scope (§ 12.1)

Sign-off checklist

☐ Colors and tokens match brand intent
☐ Typography hierarchy is correct
☐ Component states are complete
☐ Accessibility requirements are feasible
☐ Responsive breakpoints are appropriate
☐ Known deferrals are acceptable

Capture feedback → Create GitHub issues with tag [design-feedback]

For Engineering Lead & Squad

Read IMPLEMENTATION_HANDOFF.md (complete overview)
- Understand file structure and setup
- Review component refactoring guide (phased approach)
- Confirm estimation and capacity
Create front-end epic in project management tool
- Subtasks per phase (Button → Layout → Modals → Pages → QA)
- Estimate: 40–60 story points (2–3 sprints)
- Assign engineers
Use COMPONENT_STATES.md during development
- Reference component specs
- Copy code examples
- Verify states during PR review
Set up design tokens
- Import src/design-tokens.css in main.tsx
- Test light/dark theme toggle
- Audit codebase for hardcoded colors/spacing

For QA & Testing Team

Review TESTING_CHECKLIST.md
- Set up test environment (Chrome, Firefox, WAVE, NVDA)
- Run visual tests (colors, spacing, typography)
- Run interactive tests (button states, modals, focus)
- Run accessibility tests (contrast, keyboard, screen reader)

Run automated tools

WAVE extension (webaim.org) → 0 contrast errors
Axe DevTools → Accessibility score ≥90
Lighthouse → Accessibility ≥90/100

Submit bugs
- Create GitHub issues with [qa-failure] tag
- Include screenshot + expected vs actual
- Reference TESTING_CHECKLIST.md step

Quick-Start Verification (30 minutes)

Test that deliverables are correct before handing off to engineering:

Step 1: Review Documents (10 min)

# Skim each document
# ✓ DESIGN_SPEC.md: 14 sections, clear token definitions
# ✓ COMPONENT_STATES.md: Code examples for each component
# ✓ TESTING_CHECKLIST.md: Runnable test steps
# ✓ IMPLEMENTATION_HANDOFF.md: Phased migration plan

Step 2: Verify Design Tokens (5 min)

# Check design-tokens.css exists and contains:
# ✓ Light/dark theme color tokens
# ✓ Typography scale (heading, body, labels)
# ✓ Spacing tokens (4px–64px scale)
# ✓ Border radius tokens
# ✓ Shadow tokens
# ✓ Transition/animation definitions

cat src/design-tokens.css | grep "^:root" | head -20

Step 3: Test Theme Toggle (5 min)

// In browser console:
document.documentElement.setAttribute("data-theme", "dark");
// Check: colors should change
// Then: setAttribute("data-theme", "light");

Step 4: Validate Accessibility (10 min)

□ Install WAVE extension
□ Run on landing page: 0 errors expected
□ Run on dashboard (if running): 0 errors expected
□ Check focus ring visible when tabbing

Step 5: Confirm Sign-off (0 min)

□ All deliverables present and linked
□ No TBD sections in specs
□ Known deferrals clearly listed
□ Owner assigned for each deferral

File Locations (Complete Inventory)

Fluxora-Frontend/
├── DESIGN_SPEC.md                    ← Core specification (14 sections)
├── COMPONENT_STATES.md               ← Implementation specs per component
├── TESTING_CHECKLIST.md              ← Complete QA protocol
├── IMPLEMENTATION_HANDOFF.md         ← Engineering step-by-step guide
├── src/
│   ├── design-tokens.css             ← CSS variables (import first)
│   ├── main.tsx                      ← Import design-tokens.css here
│   ├── index.css                     ← Global resets (updated)
│   ├── App.tsx                       ← Theme manager
│   ├── components/
│   │   ├── Layout.tsx                ← (To refactor)
│   │   ├── Sidebar.tsx               ← (To refactor)
│   │   ├── AppNavbar.tsx             ← (To refactor)
│   │   ├── CreateStreamModal.tsx     ← (To refactor)
│   │   ├── ConnectWalletModal.tsx    ← (To refactor)
│   │   └── ... (other components)
│   └── pages/
│       ├── Landing.tsx               ← (To verify tokens)
│       ├── Dashboard.tsx             ← (To refactor)
│       ├── Streams.tsx               ← (To refactor)
│       └── Recipient.tsx             ← (To refactor)
└── [Updated files will be listed here during implementation]

Key Decisions & Rationale

Why CSS Variables (Not CSS-in-JS)?

Portable: Work in any framework (React, Vue, vanilla)
Performant: Zero runtime overhead
DX: Easy to reference in DevTools
A11y: Tokens available to Sass, PostCSS, theme generators

Why 8px Spacing Scale?

Consistency: All spacing is multiple of 8px (4, 8, 12, 16, 24, 32, 48, 64)
Scalability: Works for all screen sizes
Accessibility: Touch targets ≥44px (5.5 units)

Why Focus Ring 2px @ 2px Offset?

WCAG AAA: Exceeds minimum requirements
Visibility: Rings clearly visible on dark/light backgrounds
Consistency: Same everywhere (buttons, inputs, links, nav)

Why No Tailwind Migration?

Scope: Design spec is about tokens, not CSS framework choice
Flexibility: Engineers can choose CSS files, Tailwind, or CSS-in-JS
Future-proof: Tokens work with any tool/language

Deferrals (Intentional Exclusions)

See DESIGN_SPEC.md § 12.1:

Advanced animations (Phase 2)
Right-side panel (Phase 3)
Auto dark mode detection (nice-to-have)
i18n/L10n (business decision pending)
PWA/offline (Phase 3)

Success Criteria (Definition of Done)

Design & Product Sign-off

✓ Design critique held (or async review completed)
✓ All ambiguities resolved
✓ Color palette approved
✓ Typography scale approved
✓ Accessibility targets (WCAG AA) accepted
✓ Known deferrals acknowledged
✓ Stakeholder sign-off captured (email or Slack thread)

Engineering Implementation

✓ Design tokens CSS imported and functional
✓ All components refactored with tokens (100% hardcoded color/spacing removed)
✓ Focus ring present on all interactive elements (cyan, 2px, 2px offset)
✓ Keyboard navigation works (Tab, Shift+Tab, Enter, Space, Escape)
✓ Screen reader tested (NVDA or VoiceOver)
✓ WAVE scan: 0 contrast errors
✓ Lighthouse Accessibility: ≥90/100
✓ Responsive: Works 320px, 768px, 1024px thresholds
✓ Theme toggle: Light/dark works, persists
✓ PR review: Code matches component spec

QA & Testing Sign-off

✓ TESTING_CHECKLIST.md: All tests passed
✓ No visual regressions from spec
✓ All states working (default, hover, focus, active, disabled, loading, error)
✓ Accessibility audit: No blockers
✓ Cross-browser tested (Chrome, Firefox, Safari)
✓ Mobile-friendly: No horizontal scroll
✓ Performance: No layout shift, smooth animations
✓ Test summary: Documented in closing PR

Defect Resolution

✓ Critical bugs: Fixed before merge
✓ Major bugs: Fixed in hotfix or next sprint
✓ Minor bugs: Logged as future tech debt
✓ Accessibility bugs: Fixed before merge

Implementation Timeline

Week 1: Foundation (20 pts)

Import design-tokens.css
Create Button component (all states)
Create Input component
Update global styles (index.css)
Estimated: 20 story points

Week 2: Layouts & Navigation (15 pts)

Refactor Layout.tsx (remove duplicates)
Update navigation items (consistent styling)
Add hamburger menu (mobile)
Add theme manager
Estimated: 15 story points

Week 2-3: Modals & States (15 pts)

Week 3: Pages & Polish (10 pts)

Week 3-4: QA & Sign-off (8 pts)

Total Estimate: 60–68 story points (2.5–3 sprints, 1 engineer)

Support & Questions

Common Questions

Q: Do I need to use the Button component everywhere?
A: Yes, for consistency. Prefer <Button> over inline styled buttons.

Q: Can I customize colors per-page?
A: No. Design tokens must be global. Add new token to design-tokens.css if needed, color customization not recommended.

Q: What about Dark Mode on Apple devices (prefers-color-scheme)?
A: Deferred to Phase 2. Current data-theme="dark" attribute works. Media query support is future-nice-to-have.

Q: How do I test on Windows/IE?
A: IE not supported. CSS variables are ES6+. Use Chrome, Firefox, Safari, Edge (modern).

Q: Should I use BEM or Tailwind for component CSS?
A: Either. BEM (Button.css) preferred for clarity + token usage. Tailwind acceptable if tokens are used.

Q: What if a design system token doesn't match my component needs?
A: Document the gap → Add new token → Update design-tokens.css → Notify design team.

Contact & Escalation

Design specs questions → Reach out to Design Lead
Implementation questions → Create GitHub issue [implementation-help]
Accessibility questions → Contact Accessibility Reviewer
Timeline concerns → Escalate to Engineering Lead

Appendix A: Document Cross-References

If you want to...

Task	Reference
Understand the color system	DESIGN_SPEC.md § 3.2.1
Implement Button component	COMPONENT_STATES.md § Button + IMPLEMENTATION_HANDOFF.md § 3.1
Add keyboard support	DESIGN_SPEC.md § 5.2 + TESTING_CHECKLIST.md § 3.2
Test accessibility	TESTING_CHECKLIST.md § Section 3
Migrate a page	IMPLEMENTATION_HANDOFF.md § 5.3
Review CSS	COMPONENT_STATES.md (CSS examples)
Understand tokens	DESIGN_SPEC.md § 3.2 + src/design-tokens.css

Appendix B: Acceptance Criteria Per Component

Button ✓

✓ Primary variant: #00b8d4 bg, white text
✓ Hover: Darker (#0097a7), lifted shadow
✓ Focus: 2px cyan ring, 2px offset
✓ Disabled: 60% opacity, not-allowed cursor
✓ Loading: Spinner, aria-busy="true"
✓ Keyboard: Tab focuses, Enter/Space activates
✓ Contrast: 4.5:1 (text/background)
✓ Touch: ≥44px height

Input ✓

✓ Default: Border #e0e6ed, 1px, padding 10px 12px
✓ Focus: Border #00b8d4, 2px, cyan ring
✓ Error: Border #ef4444, 2px, red helper text
✓ Disabled: 60% opacity, not-allowed cursor
✓ Keyboard: Tab focuses, Type enters text
✓ ARIA: aria-invalid, aria-required, aria-describedby
✓ Label: Associated <label> or aria-label
✓ Placeholder: Secondary text, 60% opacity

Modal ✓

✓ Backdrop: rgba(0,0,0,0.4) dark, lighter light theme
✓ Dialog: Max 500px, shadow-xl, border-radius 12px
✓ Animation: Scale 0.95→1 (enter), 1→0.95 (exit), 200ms
✓ Close button: Top-right, 32×32px, X icon
✓ Keyboard: Tab traps, Escape closes, focus returns
✓ ARIA: role="dialog", aria-modal, aria-labelledby
✓ Mobile: 90vw width, full-height scrollable

Navigation ✓

✓ Default: Transparent bg, secondary text, transparent L-border
✓ Hover: Raised bg, secondary text, accent L-border
✓ Active: Transparent bg, accent text, accent L-border
✓ Focus: Same as hover + cyan ring
✓ Keyboard: Tab navigates items, left/right arrows (future)
✓ ARIA: aria-current="page" on active
✓ Height: 44px (touch target)

Appendix C: Tools & Technologies

Design Tools:

Figma (if available) – link in issue
Browser DevTools – testing/verification
WAVE – accessibility scanning

Testing Tools:

WAVE (webaim.org/wave) – contrast + accessibility
Axe DevTools (deque.com) – automated testing
VoiceOver (macOS) / NVDA (Windows) – screen reader
Lighthouse (Chrome DevTools) – accessibility score

Dev Tools:

CSS variables – token system
React 18 – component library
TypeScript – type safety
Tailwind CSS (optional) – utilities

Final Checklist Before Handoff

Sign-Off & Approval

Design Review: _______________________ Date: __________
Engineering Feasibility: _______________________ Date: __________
Product Acceptance: _______________________ Date: __________
QA Sign-off: _______________________ Date: __________

Assignment Status: ✅ COMPLETE

All deliverables are production-ready. Engineering can begin implementation without clarification spikes.

Document Version: 1.0
Created: March 30, 2026
Status: Ready for Implementation

Next Steps for Engineering:

Read IMPLEMENTATION_HANDOFF.md
Review COMPONENT_STATES.md for detailed specs
Create sprint tasks (IMPLEMENTATION_HANDOFF.md § Phase 1-6)
Begin with Token setup + Button component
Use TESTING_CHECKLIST.md for QA

Questions or Issues? Open GitHub issue with tag [design-delivery] or contact assignment owner.

FilesExpand file tree

ASSIGNMENT_SUMMARY.md

Latest commit

History