Frontend Style & Layout Patterns

Tailwind v4 styling patterns for this project. Covers page structure, spacing, responsive images, and v3→v4 migration.

1. Section Compound Pattern

Express page layout structure explicitly using semantic HTML + Tailwind classes at the usage site.

// ✅ Layout structure visible at a glance
const OrderListPage = () => (
  <main className="min-h-screen flex flex-col">
    <header className="sticky top-0 z-10 bg-white border-b border-gray-200">
      <OrderListHeader />
    </header>

    <section className="flex-1 flex flex-col gap-4 px-4 py-6">
      <OrderFilterBar />
      <OrderList />
    </section>

    <footer className="sticky bottom-0 bg-white border-t border-gray-200 px-4 py-3">
      <OrderListFooterActions />
    </footer>
  </main>
)

What to Expose vs. Hide

| Expose at usage site | Hide in component | | --------------------------------------- | ---------------------------------- | | Layout structure (flex, grid, position) | Reusable styles (button variants) | | Page-specific spacing and sizing | Internal implementation details | | Semantic HTML structure | Complexity outside current concern |

• Reusable styles (buttons, cards) → abstract into components.
• Page layout → write directly at the usage site in screens/ pages.

2. Spacing Selection Guide

Three Methods

flex gap — Default for Flexbox containers:

<div className="flex flex-col gap-4">
  <OrderCard />
  <OrderCard />
</div>

space-y / space-x — Sibling elements with consistent spacing:

<ul className="space-y-3">
  <li>
    <ReviewItem />
  </li>
  <li>
    <ReviewItem />
  </li>
</ul>

Explicit spacer div — Single specific gap (e.g., from design spec):

<div>
  <OrderHeader />
  <div className="h-8" /> {/* 32px explicit gap */}
  <OrderContent />
</div>

Decision Flow

Need spacing?
├── Inside Flexbox container?  → flex gap
├── Repeating sibling spacing? → space-y / space-x
├── Single explicit gap (from design spec)? → spacer div
└── Complex conditional spacing? → individual margin/padding

Notes

• Use gap inside flex containers to avoid margin collapsing.

3. Responsive Images — CLS Prevention

Use aspect-ratio + relative container to maintain original ratio responsively.

// ✅ Basic responsive image
const Illustration = () => (
  <div className="flex justify-center">
    <div className="relative w-full aspect-[327/200]">
      <img
        src="/illustrations/order-complete.png"
        alt="Order complete"
        className="object-contain w-full h-full"
        loading="eager"
      />
    </div>
  </div>
)

// ✅ With max-width constraint
const Thumbnail = ({ src, alt }: { src: string; alt: string }) => (
  <div className="relative w-full max-w-sm aspect-square">
    <img src={src} alt={alt} className="object-cover w-full h-full rounded-lg" loading="lazy" />
  </div>
)

Key Properties

| Property | Purpose | | --------------------------------- | ------------------------------- | | relative | Positioning anchor for children | | aspect-[W/H] | Maintain ratio (prevents CLS) | | w-full | Fill parent width | | object-contain / object-cover | Image fit mode |

Loading Strategy

• loading="eager": Above-the-fold images (LCP optimization)
• loading="lazy": Below-the-fold images (initial load optimization)

4. Tailwind v4 Class Changes

This project uses Tailwind v4. Do NOT use v3 syntax.

Import Syntax

/* ❌ v3 (forbidden) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* ✅ v4 */
@import 'tailwindcss';

Class Migration Table

| v3 (forbidden) | v4 (use this) | | -------------- | ------------- | | shadow-sm | shadow-xs | | shadow | shadow-sm | | ring | ring-3 | | blur | blur-sm | | rounded | rounded-sm |

Reference: Tailwind v4 Upgrade Guide