Frontend UI/CSS Design Patterns

Quick reference for maintaining visual consistency across the RAPID frontend. Use this when implementing UI components or choosing styling approaches.

Related Skills:

• •For backend/frontend planning → use /plan-backend-frontend
• •For agent prompts → use /modify-agent-prompts

Core Design Principles

Action Hierarchy & Color Semantics

Decision Matrix (based on 200+ actual usage instances):

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

Color Mappings:

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

How to Determine Color Semantics

5-Step Decision Process:

1. •

   Identify Action Context

   • •Completing a task → Primary
   • •Abandoning a task → Cancel (outlined primary)
   • •Destroying data → Danger
   • •Viewing information → Secondary or text
   • •Toggling UI state → Text
2. •

   Assess Visual Hierarchy

   • •One main action + others → Main = filled primary, others = outlined or secondary
   • •Multiple equal actions → All outlined or secondary
   • •Inline/subtle actions → Text variant + small size
3. •

   Consider Consequences

   • •Irreversible destruction → Danger (red)
   • •Data mutation → Primary (blue)
   • •Reversible action → Secondary (aqua) or text
   • •No side effects → Text
4. •

   Follow the Pattern - Check similar features:

   bash

   grep -r "variant=" frontend/src/features/{similar-feature}/
   

   Observed patterns:

   • •Form submissions: 100% filled primary (11/11)
   • •Modal cancels: 100% outlined primary (16/16)
   • •Delete operations: Consistent danger variant
   • •Inline tree actions: 100% text + small
5. •

   Validate with Questions

   • •"Is this the ONE thing users came here to do?" → Filled primary
   • •"Could user want to cancel?" → Add outlined cancel button
   • •"Will this delete user data?" → Use danger variant
   • •"Is this a secondary workflow?" → Use secondary or outlined
   • •"Is this just UI manipulation?" → Use text variant

Anti-Patterns:

• •❌ Multiple filled primary buttons in same view
• •❌ Filled danger for reversible actions
• •❌ Primary for cancel/dismiss
• •❌ Text variant for important mutations

Status & Feedback Colors

For Operation Feedback (Toasts, Alerts):

• •Success → Green: addToast(message, "success")
• •Error → Red: addToast(message, "error") or <ErrorAlert>
• •Warning → Yellow: <InfoAlert variant="warning">
• •Info → Blue: <InfoAlert variant="info">

For Status Badges:

For Review Result Badges:

Spacing & Layout

Spacing System (8px base unit):

• •Common values: gap-2, gap-4, gap-6, p-4, p-6, mb-8
• •Page containers: max-w-7xl mx-auto px-4 py-8
• •Form spacing: space-y-6

Typography Hierarchy:

• •Page titles: text-3xl font-bold
• •Section headings: text-xl or text-2xl
• •Body text: text-sm or text-base
• •Metadata: text-xs text-aws-font-color-gray

Dark Mode Strategy:

• •Always pair backgrounds: bg-white dark:bg-aws-squid-ink-dark
• •Always pair text: text-aws-font-color-light dark:text-aws-font-color-dark
• •Consistent hover states: hover:bg-aws-paper-light dark:hover:bg-aws-ui-color-dark

Component Placement Principles

Logical Grouping - Actions Near Their Context

Rule: Action buttons should be placed NEAR what they affect, not right-aligned from unrelated labels.

Vertical Layout Pattern:

<div>
  {/* Label */}
  <span className="text-sm font-medium mb-3 block">
    {t("filter.label")}
  </span>

  {/* Content being acted upon */}
  <div className="flex flex-wrap gap-2">
    {items}
  </div>

  {/* Action - logically grouped below content */}
  <div className="mt-3">
    <Button variant="text" size="sm" onClick={handleClear}>
      {t("filter.clear")}
    </Button>
  </div>
</div>

Anti-Pattern - justify-between with conditional action:

// ❌ BAD - action appears far from content it affects
<div className="flex items-center justify-between mb-3">
  <span>{t("filter.label")}</span>
  {hasSelection && (
    <Button onClick={handleClear}>Clear</Button>  /* Far from filtered content */
  )}
</div>
<div className="flex gap-2">
  {items}
</div>

Why It Matters:

• •Users look for actions near the content they affect
• •Right-aligned buttons that appear suddenly are disorienting
• •Vertical flow is more predictable: Label → Content → Action
• •Especially important for actions that appear conditionally

Real-World Fix: TagFilter Clear button moved below tags instead of right-aligned next to label.

Component Composition

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

Interactive Element Patterns

Visual Affordance - "Make it Obviously Clickable"

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

Pattern: Use visible borders, distinct backgrounds, or shadows in default state.

Tag/Pill/Chip Pattern:

<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
  hover:bg-light-gray dark:hover:bg-aws-squid-ink-dark
">
  Interactive Tag
</button>

Key Indicators of Clickability:

1. •cursor-pointer - Changes cursor on hover
2. •border-2 with visible color - Shows it's an element you can interact with
3. •transition-all - Smooth feedback on interaction
4. •Hover state changes - Border and background color shift

Anti-Pattern:

• •❌ Using only cursor-pointer + subtle hover background change
• •❌ Making elements look like static labels/badges
• •❌ Relying on hover alone to indicate interactivity

Real-World Fix: TagFilter tags were not obviously clickable. Added border-2 with visible borders in default state, not just on hover.

Smooth Transitions for Conditional UI

Pattern: Always render, control with opacity + height transitions.

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

When to Use: Conditionally shown buttons, dropdown menus, expandable sections.

Why: No layout shift, smooth 300ms fade (matches Sidebar).

Component Quick Reference

Discover available components:

ls -la frontend/src/components/

Pattern: When a new component is added, add one row to this table.

Common Implementation Patterns

Page Layout

<div className="container mx-auto px-4 py-8 max-w-7xl">
  {/* Page header */}
  <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>

  {/* Page content */}
  {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);

// In render
<>
  <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();

// Success
addToast(t("checklist.createSuccess"), "success");

// Error
addToast(t("checklist.createError"), "error");

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