Ui Css Patterns

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: 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.

<button className="
  cursor-pointer 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.

Common Layout Patterns

Reference implementations for common RAPID frontend layouts.

Page Layout

<div className="container mx-auto px-4 py-8 max-w-7xl">
  <div className="mb-8">
    <h1 className="text-3xl font-bold text-aws-font-color-light dark:text-aws-font-color-dark mb-2">
      {t("page.title")}
    </h1>
    <p className="text-aws-font-color-gray">{t("page.description")}</p>
  </div>
  {content}
</div>

With action button:

<div className="mb-6 flex items-center justify-between">
  <div>
    <div className="flex items-center">
      <Icon className="mr-2 h-8 w-8 text-aws-font-color-light dark:text-aws-font-color-dark" />
      <h1 className="text-3xl font-bold text-aws-font-color-light dark:text-aws-font-color-dark">
        {t("page.title")}
      </h1>
    </div>
    <p className="mt-2 text-aws-font-color-gray">{t("page.description")}</p>
  </div>
  <Button variant="primary">{t("action.create")}</Button>
</div>

Responsive Grid

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {items.map((item) => <Card key={item.id} item={item} />)}
</div>

Form Layout

<form onSubmit={handleSubmit} className="space-y-6">
  <FormTextField label={t("form.name")} value={name} onChange={setName} error={errors.name} required />
  <FormTextArea label={t("form.description")} value={description} onChange={setDescription} rows={4} />
  <div className="flex justify-end gap-3">
    <Button variant="primary" outline onClick={onCancel}>{t("common.cancel")}</Button>
    <Button variant="primary" type="submit" disabled={isSubmitting}>{t("common.save")}</Button>
  </div>
</form>

State Handling (Loading, Error, Empty, Success)

{isLoading ? (
  <Skeleton count={5} height={80} />
) : error ? (
  <ErrorAlert error={error} title={t("error.loadFailed")} />
) : items.length === 0 ? (
  <div className="text-center py-12">
    <p className="text-aws-font-color-gray text-lg mb-4">{t("list.emptyState")}</p>
    <Button variant="primary" onClick={handleCreate}>{t("action.createFirst")}</Button>
  </div>
) : (
  <div className="grid grid-cols-1 gap-6">
    {items.map(item => <ItemCard key={item.id} item={item} />)}
  </div>
)}

Modal Workflow

const [isOpen, setIsOpen] = useState(false);

<>
  <Button variant="primary" onClick={() => setIsOpen(true)}>{t("action.open")}</Button>
  <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} title={t("modal.title")}>
    <form onSubmit={handleSubmit}>
      {/* Form fields */}
      <div className="flex justify-end gap-3 mt-6">
        <Button variant="primary" outline onClick={() => setIsOpen(false)}>{t("common.cancel")}</Button>
        <Button variant="primary" type="submit">{t("common.save")}</Button>
      </div>
    </form>
  </Modal>
</>

Toast Notifications

import { useToast } from '@/contexts/ToastContext';

const { addToast } = useToast();

try {
  await createChecklistSet({ name, description });
  addToast(t("success.message"), "success");
} catch (error) {
  addToast(t("error.message"), "error");
}