Comprehensive Rules for designing, implementing, and maintaining responsive, accessible grid layouts using CSS Grid, Flexbox, and popular CSS frameworks.
Your grid system shouldn't be a constant battle. Every time you need to adapt layouts across devices, debug alignment issues, or ensure accessibility compliance, you're losing hours that could be spent building features. These comprehensive Cursor Rules transform grid development from a tedious chore into a streamlined, predictable workflow.
You know this pain: You're halfway through implementing a complex layout when you realize your responsive breakpoints are inconsistent. Your CSS Grid fallbacks aren't working in older browsers. Your screen reader navigation is completely broken because visual order doesn't match DOM order. What should have been a 2-hour task becomes a full day of debugging.
The typical developer workflow:
The result: Inconsistent spacing, poor accessibility scores, brittle responsive behavior, and technical debt that compounds with every new feature.
These Cursor Rules establish a battle-tested, mobile-first grid system that eliminates common pitfalls before they happen. You get consistent spacing scales, bulletproof responsive patterns, and accessibility built-in from day one.
What you get immediately:
Instead of rebuilding grid patterns from scratch, you get proven templates:
/* Instant responsive card grid */
.cards {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(clamp(16rem, 25vw, 22rem), 1fr));
gap: var(--space-4);
}
Built-in fallbacks and browser support patterns mean your grids work everywhere:
@supports not (display: grid) {
.grid { display: flex; flex-wrap: wrap; }
}
Every grid pattern includes proper semantic structure and ARIA support:
<div class="grid" role="grid" aria-colcount="12" aria-rowcount="3">
<header class="col-span-full" role="gridcell">...</header>
</div>
Named grid areas and logical breakpoints that adapt naturally:
.page {
grid-template-areas:
"header"
"main"
"footer";
}
@media (min-width: 768px) {
.page {
grid-template-areas:
"header header"
"nav main"
"footer footer";
}
}
Before: 3 hours of trial-and-error with CSS Grid placement, multiple browser compatibility fixes, accessibility issues discovered in QA.
After: 45 minutes using pre-configured grid templates with built-in responsive behavior and accessibility:
.dashboard {
display: grid;
grid-template-columns: [full-start] minmax(1rem,1fr) [content-start] repeat(12, [col] minmax(0,1fr)) [content-end] minmax(1rem,1fr) [full-end];
grid-template-areas:
"sidebar main main"
"sidebar chart chart"
"sidebar footer footer";
}
Before: Inconsistent spacing, broken layouts on mobile, poor performance from layout thrashing.
After: Responsive card grid with consistent spacing and optimized performance:
.products {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(clamp(16rem, 25vw, 22rem), 1fr));
gap: var(--space-4);
/* Prevents layout shift */
container-type: inline-size;
}
Tailwind CSS Before: Manually composing utilities, inconsistent breakpoint usage, no systematic approach to spacing.
Tailwind CSS After: Streamlined utility composition with consistent patterns:
<div class="grid grid-cols-1 md:grid-cols-12 gap-4 page-grid">
<header class="col-span-full">...</header>
<main class="col-span-full md:col-span-8">...</main>
<aside class="col-span-full md:col-span-4">...</aside>
</div>
Copy the complete rule set into your Cursor configuration. The rules include comprehensive patterns for CSS Grid, Flexbox fallbacks, and framework integration.
:root {
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--gutter: calc(var(--space-2) * 2);
}
Start with the mobile-first approach:
.grid {
display: grid;
grid-template-columns: 1fr;
gap: var(--space-4);
}
@media (min-width: 768px) {
.grid {
grid-template-columns: repeat(12, 1fr);
}
}
For Bootstrap 5:
.row.gx-0 > [class^="col-"] {
display: grid;
grid-template-columns: subgrid;
}
For Tailwind CSS:
@layer utilities {
.page-grid {
grid-template-areas: "header" "main" "footer";
}
}
Add the visual debug overlay during development:
[data-debug="grid"] * {
background-clip: content-box;
outline: 1px solid rgba(0,0,0,.05);
}
Your grid system becomes a competitive advantage instead of a development bottleneck. Stop rebuilding layouts from scratch and start shipping features faster with bulletproof, accessible, responsive grids that work everywhere.
You are an expert in: CSS Grid, Flexbox, HTML5, TypeScript-strict JavaScript (ES2023), PostCSS, Sass/SCSS, Bootstrap 5, Tailwind CSS, automated testing (Playwright, Axe-core), performance tooling (Lighthouse, WebPageTest).
Key Principles
- Mobile-first: begin all layouts with a single-column flow, then enhance with media queries.
- Two-dimensional first: prefer CSS Grid for page scaffolding; use Flexbox for one-axis modules inside grid cells.
- Establish a 4-pt spacing scale (4 px base) and apply consistently via custom properties (e.g., --space-1:0.25rem, --space-2:0.5rem).
- Keep content order logical in the DOM; never rearrange solely for visual purposes—use grid-area for placement.
- Use relative units (rem, %, fr) to maximise adaptability and accessibility.
- Iterate with real content and user feedback; prototype early in Figma or CodePen.
CSS
- Declare grid containers with display:grid or display:inline-grid; avoid implicit grid growth—explicitly define grid-template-columns/rows.
- Name grid lines/areas descriptively: grid-template-columns:[full-start] minmax(1rem,1fr) [content-start] repeat(12, [col] minmax(0,1fr)) [content-end] minmax(1rem,1fr) [full-end];
Example usage: .page {grid-template-areas:"header" "main" "footer"}.
- Use repeat(auto-fit,minmax( clamp(16rem,25vw,22rem) ,1fr)) for responsive card grids.
- Provide Flexbox fallback: @supports not (display:grid) {.grid{display:flex;flex-wrap:wrap}}
- Organise styles with BEM-lite naming: .grid--12, .col--6@md; suffix @breakpoint for variants.
- Custom properties go at :root; use calc() for derived spacing (e.g., --gutter:calc(var(--space-2)*2)).
HTML
- Maintain semantic landmarks (<header>,<main>,<nav>,<footer>).
- Respect source order; use tabindex sequencing for custom interactive grids.
- Avoid empty grid children; group decorative nodes with aria-hidden="true".
JavaScript (when needed)
- Never use JS for layout calculation unless animating; query container-size via ResizeObserver to toggle CSS classes only when essential.
- Wrap DOM queries in utility: const $ = (sel,ctx=document)=>ctx.querySelector(sel);
Error Handling and Validation
- Fallback first: wrap grid features in @supports checks; provide flex or block fallback.
- Validate with stylelint-config-standard and stylelint-order; fail CI on unknown properties.
- Accessibility guardrails: every grid with role="grid" must expose aria-colcount & aria-rowcount when dynamic; run Axe-core in tests.
- Early exit pattern in JS helpers: if(!container?.matches('.grid')) return; prevents null errors.
Framework-Specific Rules
Bootstrap 5
- Use <div class="container-xl"> to anchor 12-col system; override by upgrading CSS variable --bs-gutter-x.
- For complex layouts, mix .row with CSS Grid: .row.gx-0 > [class^="col-"] {display:grid;grid-template-columns:subgrid}
Tailwind CSS
- Compose utilities: class="grid grid-cols-1 md:grid-cols-12 gap-4".
- Custom template areas via @layer utilities: .page-layout{grid-template-areas:...}. Expose as tw class page-grid.
Additional Sections
Accessibility
- Ensure focus order matches visual order; use :focus-visible for outline management.
- Provide min touch target of 44×44 px by padding grid items or setting min-block-size.
Testing
- Unit: Jest + @testing-library/dom for JS layout helpers.
- Integration: Playwright viewport matrix (375,768,1024,1440) with screenshots.
- Accessibility: Axe-core in CI, pa11y for WCAG 2.1 AA.
Performance
- Minimise repaint: avoid altering grid-template-* in JS on scroll; prefer transform animations.
- Purge unused CSS via PurgeCSS/Tailwind JIT.
- Audit with Lighthouse; ensure <200ms CLS shift by keeping image aspect-ratio in grid cells.
Security
- No inline JS in HTML grid templates; use CSP default-src 'self'.
- Sanitise content injected into grid cells (DOMPurify) if sourced from user input.
Tooling & Automation
- Use CSS Grid visual debug overlay: * {background-clip:content-box; outline:1px solid rgba(0,0,0,.05);} behind env(overlay-debug).
- Integrate Figma design tokens export -> PostCSS custom properties pipeline.
Directory Structure
src/
styles/
base/_variables.scss
layout/_grid.scss (all grid utilities)
components/_cards.scss
scripts/
utils/gridHelpers.ts
Checklist Before Merge
- [ ] All breakpoints tested
- [ ] Axe score ≥ 95
- [ ] Lighthouse performance ≥ 90
- [ ] No Stylelint errors
- [ ] Storybook stories updated for each grid variant