Frontend UI/CSS Design 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
- Identify Action Context: Completing -> Primary, Abandoning -> Cancel (outlined), Destroying -> Danger
- Assess Visual Hierarchy: One main action = filled primary, others = outlined/secondary
- Consider Consequences: Irreversible -> Danger, Mutation -> Primary, Reversible -> Secondary
- Follow Existing Patterns:
grep -r "variant=" frontend/src/features/{similar-feature}/
- 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"
</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.
1---2name: ui-css-patterns3description: UI/CSS design patterns and component reference for the RAPID frontend, covering color semantics, button variant selection, status badge colors, dark mode, spacing, and component inventory. Use when implementing UI components, choosing button variants or colors, styling with Tailwind CSS, or checking available shared components.4---56# Frontend UI/CSS Design Patterns78Quick reference for maintaining visual consistency across the RAPID frontend.910## Action Hierarchy & Color Semantics1112| **Action Type** | **Button Variant** | **Outline** | **Examples** |13|-----------------|-------------------|-------------|--------------|14| **Submit/Create** | `primary` | `false` | "Create", "Save", "Compare" |15| **Cancel/Back** | `primary` | **`true`** | "Cancel", "Back" |16| **Delete/Remove** | `danger` | `false` (strong) / `true` (soft) | "Delete Checklist" / inline delete |17| **Alternative** | `secondary` | `false` | "Duplicate", "Retry" |18| **UI Toggle** | `text` | n/a | "Show More", "Expand Tree" |19| **Inline Action** | `text` + `size="sm"` | n/a | Edit/Delete in tree nodes |20| **Table Action** | varies | **`true`** | "View", "Download" |2122**Key Pattern**: Outlined primary = cancel/dismiss. Filled primary = submit/create.2324**Color Mappings**:25- Primary: `aws-sea-blue-light` / `aws-sea-blue-dark`26- Secondary: `aws-aqua`27- Success: `aws-lab` (brand green), `green-500` (icons), `green-100/800` (badges)28- Danger: `red` (buttons), `red-500` (icons), `red-100/800` (badges)29- Warning: `yellow-400` (borders), `yellow-100/800` (badges)30- Info: `aws-font-color-blue` (links), `blue-100/800` (badges)3132### 5-Step Color Decision Process33341. **Identify Action Context**: Completing -> Primary, Abandoning -> Cancel (outlined), Destroying -> Danger352. **Assess Visual Hierarchy**: One main action = filled primary, others = outlined/secondary363. **Consider Consequences**: Irreversible -> Danger, Mutation -> Primary, Reversible -> Secondary374. **Follow Existing Patterns**: `grep -r "variant=" frontend/src/features/{similar-feature}/`385. **Validate**: "Is this the ONE thing users came here to do?" -> Filled primary3940**Anti-Patterns**:41- Multiple filled primary buttons in same view42- Filled danger for reversible actions43- Primary for cancel/dismiss4445### Status & Feedback Colors4647**Toasts**: Success -> `"success"`, Error -> `"error"`4849**Status Badges**: PENDING=Yellow, PROCESSING=Blue, DETECTING=Purple, COMPLETED=Green, FAILED=Red5051**Review Results**: UNDER_REVIEW=Blue, PASS=Green, NOT_PASS=Red, LOW_CONFIDENCE=Yellow, USER_OVERRIDE=AWS Blue5253### Spacing & Typography5455- Spacing: 8px base (`gap-2`, `gap-4`, `p-4`, `p-6`)56- Page containers: `max-w-7xl mx-auto px-4 py-8`57- Titles: `text-3xl font-bold`, Sections: `text-xl`/`text-2xl`, Body: `text-sm`/`text-base`58- Dark mode pairs: `bg-white dark:bg-aws-squid-ink-dark`, `text-aws-font-color-light dark:text-aws-font-color-dark`5960## Component Placement Principles6162### Logical Grouping6364**Rule**: Actions near their context, not right-aligned from unrelated labels.6566```tsx67{/* Vertical: Label -> Content -> Action */}68<div>69 <span className="text-sm font-medium mb-3 block">{t("filter.label")}</span>70 <div className="flex flex-wrap gap-2">{items}</div>71 <div className="mt-3">72 <Button variant="text" size="sm" onClick={handleClear}>{t("filter.clear")}</Button>73 </div>74</div>75```7677### Interactive Element Affordance7879**Critical**: `cursor-pointer` alone is NOT enough. Elements must LOOK interactive before hovering.8081```tsx82{/* Use the shared Button (never a native <button>); it accepts className83 for affordance styling on top of the variant. */}84<Button85 variant="text"86 size="sm"87 className="88 border-2 transition-all89 border-light-gray dark:border-aws-ui-color-dark90 hover:border-aws-sea-blue-light dark:hover:border-aws-sea-blue-dark91 bg-aws-paper-light dark:bg-aws-paper-dark92 ">93 Interactive Tag94</Button>95```9697### Smooth Transitions for Conditional UI9899```tsx100<div className={`transition-all duration-300 ${101 isVisible ? 'opacity-100 max-h-10' : 'opacity-0 max-h-0 pointer-events-none'102}`}>103```104105## Component Rules106107- Check `src/components/` before creating new components108- Never use native `<button>` -> use `Button` component109- Never use native `alert()`/`confirm()` -> use `useAlert` hook110- Always use `react-icons` (SVG prohibited)111- Always pair color with icon/text for accessibility112113## Component Quick Reference114115| Use Case | Component | Key Props |116|----------|-----------|-----------|117| Actions | `Button` | `variant` `outline` `size` |118| Text input | `FormTextField` | `label` `error` `required` |119| Textarea | `FormTextArea` | `label` `rows` |120| File upload | `FormFileUpload` | `onFilesSelected` `accept` |121| Modals | `Modal` | `isOpen` `onClose` `title` |122| Confirmations | `useAlert` hook | `showAlert` `showConfirm` |123| Page header | `PageHeader` | `title` `description` `actions` |124| Data tables | `Table` | `columns` `data` `loading` |125| Status badges | `StatusBadge` | `status` |126| Loading | `Skeleton` | `count` `height` |127| Pagination | `Pagination` | `currentPage` `totalPages` |128| Errors | `ErrorAlert` | `error` `title` |129| Info | `InfoAlert` | `message` `variant` |130| Breadcrumbs | `Breadcrumb` | `items` |131| Segmented control | `SegmentedControl` | `options` `value` `onChange` |132| Tooltips | `Tooltip` | `content` `position` |133134For common layout implementations (page layout, grids, forms, modals, toasts), see [references/LAYOUT-PATTERNS.md](references/LAYOUT-PATTERNS.md).
aws-samples