Frontend UI/CSS Design Patterns

Quick reference for maintaining visual consistency across the RAPID frontend.

Action Hierarchy & Color Semantics

Key Pattern: Outlined primary = cancel/dismiss. Filled primary = submit/create.

Color Mappings:

• Primary: aws-sea-blue-light / aws-sea-blue-dark
• Secondary: aws-aqua
• Success: aws-lab (brand green), green-500 (icons), green-100/800 (badges)
• Danger: red (buttons), red-500 (icons), red-100/800 (badges)
• Warning: yellow-400 (borders), yellow-100/800 (badges)
• Info: aws-font-color-blue (links), blue-100/800 (badges)

5-Step Color Decision Process

1. Identify Action Context: Completing -> Primary, Abandoning -> Cancel (outlined), Destroying -> Danger
2. Assess Visual Hierarchy: One main action = filled primary, others = outlined/secondary
3. Consider Consequences: Irreversible -> Danger, Mutation -> Primary, Reversible -> Secondary
4. Follow Existing Patterns: grep -r "variant=" frontend/src/features/{similar-feature}/
5. Validate: "Is this the ONE thing users came here to do?" -> Filled primary

Anti-Patterns:

• Multiple filled primary buttons in same view
• Filled danger for reversible actions
• Primary for cancel/dismiss

Status & Feedback Colors

Toasts: Success -> "success", Error -> "error"

Status Badges: PENDING=Yellow, PROCESSING=Blue, DETECTING=Purple, COMPLETED=Green, FAILED=Red

Review Results: UNDERREVIEW=Blue, PASS=Green, NOTPASS=Red, LOWCONFIDENCE=Yellow, USEROVERRIDE=AWS Blue

Spacing & Typography

• Spacing: 8px base (gap-2, gap-4, p-4, p-6)
• Page containers: max-w-7xl mx-auto px-4 py-8
• Titles: text-3xl font-bold, Sections: text-xl/text-2xl, Body: text-sm/text-base
• Dark mode pairs: bg-white dark:bg-aws-squid-ink-dark, text-aws-font-color-light dark:text-aws-font-color-dark

Component Placement Principles

Logical Grouping

Rule: Actions near their context, not right-aligned from unrelated labels.

{/* Vertical: Label -> Content -> Action */}
<div>
  <span className="text-sm font-medium mb-3 block">{t("filter.label")}</span>
  <div className="flex flex-wrap gap-2">{items}</div>
  <div className="mt-3">
    <Button variant="text" size="sm" onClick={handleClear}>{t("filter.clear")}</Button>
  </div>
</div>

Interactive Element Affordance

Critical: cursor-pointer alone is NOT enough. Elements must LOOK interactive before hovering.

{/* Use the shared Button (never a native <button>); it accepts className
    for affordance styling on top of the variant. */}
<Button
  variant="text"
  size="sm"
  className="
    border-2 transition-all
    border-light-gray dark:border-aws-ui-color-dark
    hover:border-aws-sea-blue-light dark:hover:border-aws-sea-blue-dark
    bg-aws-paper-light dark:bg-aws-paper-dark
  ">
  Interactive Tag
</Button>

Smooth Transitions for Conditional UI

<div className={`transition-all duration-300 ${
  isVisible ? 'opacity-100 max-h-10' : 'opacity-0 max-h-0 pointer-events-none'
}`}>

Component Rules

• Check src/components/ before creating new components
• Never use native <button> -> use Button component
• Never use native alert()/confirm() -> use useAlert hook
• Always use react-icons (SVG prohibited)
• Always pair color with icon/text for accessibility

Component Quick Reference

For common layout implementations (page layout, grids, forms, modals, toasts), see [references/LAYOUT-PATTERNS.md](references/LAYOUT-PATTERNS.md).