UI Preservation Protocol

When modifying ANY UI component, follow this protocol to avoid breaking existing layouts.

Before Touching UI (MANDATORY)

1. Context Loading

MUST READ before any UI change:
1. The TARGET component file (entire file)
2. The PARENT component that renders it
3. 2-3 SIBLING components in same directory
4. The layout/page that contains the component

2. Pattern Identification

Before writing, identify and document:

• • Grid system used (CSS Grid, Flexbox, custom)
• • Spacing pattern (gap-4, space-y-6, etc.)
• • Component structure (Card > CardHeader > CardTitle)
• • Responsive breakpoints (sm:, md:, lg:)
• • Animation patterns (if any)

3. Design Token Check

# Run mentally before adding styles:
grep -r "className=" src/components/ui/ | head -20
# What tokens do existing components use?

Rules for UI Changes

Extend, Don't Replace

// BAD: Replacing existing structure
<div className="flex gap-4">  // Your new layout
  {children}
</div>

// GOOD: Adding within existing structure
<ExistingLayout>
  <NewFeature />  // Fits the pattern
</ExistingLayout>

Match Siblings

If adding a new card to a grid of cards:

1. •Read an existing card component
2. •Match its: padding, border-radius, shadow, spacing
3. •Use the SAME component (don't create a new one)

Preserve Hierarchy

Page Layout
  └── Section Container
      └── Grid/Flex Container
          └── Card Components
              └── Content

DO NOT flatten this. Add at the appropriate level.

Use Existing Components

Before creating anything new:

# Check what exists:
ls src/components/ui/
ls src/components/

# Use existing:
import { Card, CardHeader, CardContent } from "@/components/ui/card"

Forbidden Actions

Never Do

• •Create new layout when parent already has one
• •Use different spacing than sibling components
• •Add new color tokens without checking theme
• •Ignore existing responsive breakpoints
• •Create a "similar but different" component
• •Add inline styles when Tailwind classes exist

Red Flags

If you're about to:

• •Add a <div> just for styling → Check if parent handles it
• •Create MyCustomCard → Use existing Card component
• •Write style={{}} → Use Tailwind classes
• •Add grid-cols-3 → Check what siblings use

Responsive Considerations

Check Existing Breakpoints

// Find the pattern in existing components:
className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3"

// Match it exactly, don't invent new breakpoints

Mobile-First

• •Base styles for mobile
• •Add complexity at larger breakpoints
• •Test your mental model: "What happens at 320px?"

Before Submitting UI Changes

Visual Verification Checklist

• • Does it look like it belongs? (Not obviously "new")
• • Same spacing as neighbors?
• • Same border/shadow treatment?
• • Responsive at all breakpoints?
• • Loading state matches other loading states?
• • Empty state matches other empty states?
• • Error state matches other error states?

Integration Check

• • Parent component still renders correctly?
• • Sibling components unaffected?
• • No layout shifts or jumps?
• • Animations consistent with existing?

Common Mistakes

The "Fresh Start" Trap

// You see messy code and think "I'll rewrite this properly"
// DON'T. The "messy" code probably handles edge cases you don't see.
// Extend it. Don't replace it.

The "Better Way" Trap

// You know a "better" way to do the layout
// DON'T change it unless asked. Consistency > Perfection.
// The codebase should look like ONE person wrote it.

The Orphan Component

// You create a component that doesn't match anything else
// It works, but it looks out of place
// DELETE IT. Use existing components or extend them.

Summary

1. •Read before write - Know the context
2. •Match, don't invent - Use existing patterns
3. •Extend, don't replace - Add to what's there
4. •Check siblings - Your component should look like family
5. •Test visually - Does it belong?