CSS Flexbox & Grid
debt(d5/e3/b5/t5)
Closest to 'specialist tool catches' (d5). Stylelint and Chrome DevTools (per detection_hints.tools) can identify float-based layouts and legacy patterns, but detecting whether Grid vs Flexbox is the appropriate choice requires visual inspection and understanding of layout intent. Not a compiler error, not a default linter rule.
Closest to 'simple parameterised fix' (e3). The quick_fix indicates replacing float/clearfix hacks with Grid or Flexbox, which is a pattern replacement within CSS files. Typically requires refactoring one component's styles at a time, not architectural rework, but more than a one-line patch since you're restructuring how elements relate.
Closest to 'persistent productivity tax' (b5). Layout decisions affect every future component's styling approach. Using legacy float patterns means every new layout feature fights the existing system. Applies broadly to web context (per applies_to), and layout is foundational — but it's CSS-scoped, not full architectural debt that defines the entire system.
Closest to 'notable trap' (t5). The misconception explicitly states developers think Flexbox and Grid are interchangeable when they serve different dimensional purposes. Confusing main axis vs cross axis (per common_mistakes) is a documented gotcha most developers eventually learn through experience. Not catastrophic, but a real learning curve.
Also Known As
TL;DR
Explanation
Flexbox (display: flex) aligns items along a main axis (row/column). Key properties: flex-direction, justify-content (main axis alignment: space-between, center), align-items (cross axis), gap, flex-grow/shrink/basis. Ideal for: navigation bars, centering, distributing items in a row, component-level layout. CSS Grid (display: grid) creates a two-dimensional coordinate system. Key properties: grid-template-columns (e.g. repeat(3, 1fr)), grid-template-rows, gap, grid-column/row span, grid-template-areas. Ideal for: page layout, card grids, complex asymmetric layouts. They compose: a grid container can have flex items inside cells. Use grid-template-areas for named semantic layout regions. Container queries (@container) allow grid/flex behaviour to respond to the parent element's size rather than the viewport.
Common Misconception
Why It Matters
Common Mistakes
- Using float for layout instead of Flexbox or Grid — floats need clearfix hacks and break document flow.
- Using absolute positioning for layout that should be flexbox — elements become unresponsive to content changes.
- Not understanding Flexbox axis direction — confusing main axis and cross axis leads to unexpected alignment.
- Using table-based layout — semantically wrong and inflexible.
Code Examples
/* Float-based layout — requires clearfix, fragile:
.sidebar { float: left; width: 25%; }
.content { float: left; width: 75%; }
.container::after { content: ''; display: table; clear: both; } /* Clearfix hack */
/* Flexbox — clean, responsive:
.container { display: flex; gap: 1rem; }
.sidebar { flex: 0 0 25%; }
.content { flex: 1; }/* Flexbox — single axis, component level */
.nav {
display: flex;
align-items: center;
gap: 1rem;
justify-content: space-between;
}
/* Grid — two-dimensional, page layout */
.page {
display: grid;
grid-template-columns: 250px 1fr;
grid-template-rows: auto 1fr auto;
grid-template-areas:
'sidebar header'
'sidebar main'
'sidebar footer';
min-height: 100vh;
}
.sidebar { grid-area: sidebar; }
.main { grid-area: main; }
/* Responsive grid — no media queries needed */
.card-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
gap: 1.5rem;
}