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:

Read an existing card component
Match its: padding, border-radius, shadow, spacing
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

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