ui-css-patterns

Quick reference for maintaining visual consistency across the RAPID frontend.

Action Hierarchy & Color Semantics

| Action Type | Button Variant | Outline | Examples | |-----------------|-------------------|-------------|--------------| | Submit/Create | primary | false | "Create", "Save", "Compare" | | Cancel/Back | primary | true | "Cancel", "Back" | | Delete/Remove | danger | false (strong) / true (soft) | "Delete Checklist" / inline delete | | Alternative | secondary | false | "Duplicate", "Retry" | | UI Toggle | text | n/a | "Show More", "Expand Tree" | | Inline Action | text + size="sm" | n/a | Edit/Delete in tree nodes | | Table Action | varies | true | "View", "Download" |

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: UNDER_REVIEW=Blue, PASS=Green, NOT_PASS=Red, LOW_CONFIDENCE=Yellow, USER_OVERRIDE=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

| Use Case | Component | Key Props | |----------|-----------|-----------| | Actions | Button | variant outline size | | Text input | FormTextField | label error required | | Textarea | FormTextArea | label rows | | File upload | FormFileUpload | onFilesSelected accept | | Modals | Modal | isOpen onClose title | | Confirmations | useAlert hook | showAlert showConfirm | | Page header | PageHeader | title description actions | | Data tables | Table | columns data loading | | Status badges | StatusBadge | status | | Loading | Skeleton | count height | | Pagination | Pagination | currentPage totalPages | | Errors | ErrorAlert | error title | | Info | InfoAlert | message variant | | Breadcrumbs | Breadcrumb | items | | Segmented control | SegmentedControl | options value onChange | | Tooltips | Tooltip | content position |

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