gh-xtone-ai-development-tools-frontend-nextjs-development/skills/figma-design-analyzer/references/layout-analysis-guide.md

Layout Analysis Guide

This guide provides criteria for determining the appropriate CSS layout method when converting Figma designs to React components.

Layout Method Decision Tree

1. Flexbox (Most Common)

Use Flexbox when:

• Elements are arranged in a single direction (row or column)
• Elements have consistent spacing (gap)
• Elements need to wrap
• Elements need dynamic sizing (flex-grow, flex-shrink)
• Vertical or horizontal centering is required

Figma Indicators:

• Auto Layout with single direction
• Consistent spacing between items
• "Hug contents" or "Fill container" settings
• Alignment properties (top, center, bottom, left, right)

Example:

<div className="flex flex-col gap-4">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

2. CSS Grid

Use Grid when:

• Elements are arranged in a two-dimensional layout (rows AND columns)
• Complex alignment is needed across multiple axes
• Explicit row/column sizing is required
• Elements span multiple rows or columns

Figma Indicators:

• Grid layout visible in design
• Elements aligned to both rows and columns
• Consistent grid structure across the design
• Elements with specific row/column positioning

Example:

<div className="grid grid-cols-3 gap-4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

3. Absolute Positioning

Use absolute positioning when:

• Elements overlap each other
• Elements have fixed positions relative to a container
• Elements need to be positioned independently of document flow

Figma Indicators:

• Overlapping layers
• Constraints set to specific distances from edges
• Elements floating above other content
• Fixed positioning relative to parent frame

Example:

<div className="relative">
  <div className="absolute top-4 right-4">
    Overlay content
  </div>
</div>

4. Float (Rare, Legacy)

Generally avoid float in modern React development. Use Flexbox instead.

Only consider float for:

• Text wrapping around images (though even this can be done with Grid)

5. Table (Rare, Semantic Only)

Use table layout only for actual tabular data, not for layout purposes.

When to use:

• Displaying data in rows and columns with headers
• Semantic table markup is needed for accessibility

Component Layout Patterns

Auto Layout → Flexbox Mapping

Figma Auto Layout	Tailwind CSS
Horizontal direction	flex-row
Vertical direction	flex-col
Spacing between items	gap-{size}
Padding	p-{size} or px-{size} py-{size}
Hug contents	(no specific class, use content-based sizing)
Fill container	flex-1 or w-full h-full
Align items (cross-axis)	items-{start|center|end|stretch}
Justify content (main-axis)	justify-{start|center|end|between|around}

Constraints → Positioning Mapping

Figma Constraint	CSS Approach
Left + Right	w-full or specific width with margins
Top + Bottom	h-full or specific height with margins
Left + Top	Default (top-left aligned)
Center	mx-auto (horizontal) or flexbox centering
Scale	w-full h-full object-contain or responsive units

Analysis Workflow

When analyzing a Figma node's layout:

1. Check for Auto Layout

   • If present: Use Flexbox
   • Direction → flex-row or flex-col
   • Spacing → gap-{size}
   • Alignment → items-{align} and justify-{justify}

2. Check for Grid Structure

   • If elements align to both rows and columns: Use CSS Grid
   • Count columns and rows
   • Measure gaps

3. Check for Overlapping Elements

   • If elements overlap: Use relative + absolute positioning
   • Measure distances from edges

4. Check for Responsive Behavior

   • Analyze constraints
   • Determine if width/height should be fixed or flexible
   • Consider breakpoints for responsive design

5. Nested Layouts

   • Analyze each nesting level separately
   • Parent might be Grid, children might be Flexbox
   • Apply layout methods independently at each level

Common Patterns

Card Component

// Typically Flexbox with column direction
<div className="flex flex-col gap-4 p-6 rounded-lg shadow">
  <h2>Title</h2>
  <p>Description</p>
</div>

Header with Logo and Navigation

// Flexbox with space-between
<header className="flex items-center justify-between px-8 py-4">
  <img src="logo.png" alt="Logo" />
  <nav className="flex gap-6">
    <a href="#">Link 1</a>
    <a href="#">Link 2</a>
  </nav>
</header>

Image Gallery

// CSS Grid for consistent layout
<div className="grid grid-cols-3 gap-4">
  <img src="1.jpg" />
  <img src="2.jpg" />
  <img src="3.jpg" />
</div>

Overlay Modal

// Absolute positioning for overlay
<div className="relative">
  <div className="absolute inset-0 bg-black/50">
    <div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2">
      Modal content
    </div>
  </div>
</div>

Tips

• Start with Flexbox: When in doubt, start with Flexbox. It's the most flexible and commonly used.
• Prefer Semantic Layout: Use Grid for grid-like structures, not Flexbox workarounds.
• Minimize Absolute Positioning: Use it only when necessary. It breaks document flow and makes responsive design harder.
• Analyze Nesting: Each nesting level can use a different layout method. Don't force a single method for the entire component.
• Consider Responsiveness: Think about how the layout should adapt to different screen sizes. Use Tailwind's responsive prefixes (sm:, md:, lg:, etc.) when needed.