Wordnerds Grid System

Version: 0.1
Last updated: 2026-05-18
Status: Phase 0d complete — grid utilities live in site.css
Next: Phase 0e — imported into wordnerds-site/CLAUDE.md; referenced by design-orchestrator/SKILL.md

1. Grid Foundation

The Wordnerds grid is a 12-column CSS Grid with Utopia fluid gutters, centred at a maximum content width.

Property	Value	Token
Columns	12	—
Gutter	27→30px (fluid)	`--space-m`
Max content width	1280px	`--wn-content-max`
Horizontal edge padding	36→40px (fluid)	`--space-l`
Editorial max width	1180px	`--wn-container--narrow`

Why 1180px for editorial? The DESIGN.md §8 rationale: the product UI sidebar-plus-content layout was calibrated to 1280px, but marketing pages without a sidebar benefit from a narrower column (1120–1180px) for better line length. New templates that are text-heavy should use .wn-container--narrow.

2. Section Anatomy

Every section on a marketing page follows this nesting pattern:

.wn-section            ← full-bleed background + vertical padding
  .wn-container        ← max-width centred + horizontal edge padding
    .wn-grid           ← 12-column CSS Grid
      .wn-col-*        ← column spans per pattern

This is the authoritative pattern for all new templates. The legacy homepage uses .section + .container (1180px) until the Phase 2 renderer migration.

3. Section Vertical Padding

Class modifier	Token	Mobile → Desktop	When to use
(default)	`--space-2xl`	72→80px	Most content sections — the standard enterprise premium rhythm
`--generous`	`--space-2xl-3xl`	72→120px	Hero, primary CTA, key conversion sections
`--hero`	`--space-3xl`	108→120px	Hero section only — maximum breathing room

Use --space-2xl (standard) as the starting point. Only upgrade to --generous or --hero when there's a specific reason (high-stakes CTA, hero visual needs room).

4. Column-Span Patterns

These are the named layout patterns. Each maps to specific template types. Use only these patterns — do not invent one-off column spans.

Pattern table

Pattern	Span notation	CSS classes	Used by
Full bleed	12	`.wn-col-12`	`HeroTemplate` (dark/centred), `CTABand`, `PromoBand`
Even split	6 + 6	`.wn-col-6` × 2	`ProblemStatement`, `SplitTemplate`
Asymmetric	7 + 5	`.wn-col-7` + `.wn-col-5`	`HeroTemplate` (split variant), `ProofOutcome`
Wide + narrow	8 + 4	`.wn-col-8` + `.wn-col-4`	`IntegrationCallout`, `ContentAside`
3-up grid	4 + 4 + 4	`.wn-col-4` × 3	`FeaturePillars`, `PathwayCards` (3-up)
4-up grid	3 + 3 + 3 + 3	`.wn-col-3` × 4	`StepCards`, `FeatureGrid`
2-up grid	6 + 6	`.wn-col-6` × 2	`PathwayCards` (2-up), `TestimonialPair`
10-col centred	offset 1 + 10 + 1	`.wn-col-10-centred`	Section intros, pull quotes, narrow headers
8-col centred	offset 2 + 8 + 2	`.wn-col-8-centred`	Editorial sections, long-form copy blocks

Pattern rationale

The 3-up grid is the workhorse. Layout audit found it on all 10 reference sites. Build FeaturePillars first, build it well; every other 3-up reuses the same structure.

Even split and asymmetric serve different content weights. 6+6 is for balanced content (two equally important things). 7+5 is for primary-secondary relationships where the left side carries more weight (hero text vs supporting visual, outcome stat vs context).

Wide + narrow (8+4) is for component + sidebar-style layouts — a main feature explanation on the left, a supporting panel or callout on the right. IntegrationCallout uses this pattern.

Centred columns are for text-heavy sections where the full 1280px width produces lines too long for comfortable reading. 10-col centred is good for section intros; 8-col centred for editorial content.

5. Responsive Behaviour

All multi-column grids collapse to a single column at ≤768px. Vertical rhythm is preserved — sections maintain their padding.

Viewport	Behaviour
> 768px	Full 12-column grid, all patterns as specified
≤ 768px	All `.wn-col-*` collapse to full width (12 cols)
≤ 768px	`.wn-container` edge padding reduces to `--space-s` (18→20px)
≤ 768px	6+6 splits also collapse — no 2-column grids at mobile

Exception: the site nav collapses separately (handled by site-nav.ts fragment CSS, not the grid utilities).

6. CSS Utility Classes

These classes live in design-system/site.css (Phase 0d section). Use them for all new templates.

/* Section wrapper */
.wn-section               padding-block: --space-2xl (72→80px)
.wn-section--generous     padding-block: --space-2xl-3xl (72→120px)
.wn-section--hero         padding-block: --space-3xl (108→120px)
.wn-section--alt          background: --wn-light-grey
.wn-section--dark         background: --wn-off-black, color: white
.wn-section--yellow       background: --wn-brand-yellow, color: --wn-off-black
.wn-section--yellow-tint  background: --wn-section-yellow-tint (#FEF4DC)
.wn-section--blue-tint    background: --wn-section-blue-tint (#E1F4FB)

/* Content container */
.wn-container           max-width: 1280px, centred, padding-inline: --space-l
.wn-container--narrow   max-width: 1180px (editorial)

/* 12-column grid */
.wn-grid                display: grid; grid-template-columns: repeat(12, 1fr); gap: --space-m

/* Column spans */
.wn-col-3               span 3  (4-up pattern)
.wn-col-4               span 4  (3-up pattern)
.wn-col-5               span 5  (asymmetric narrow side)
.wn-col-6               span 6  (even split)
.wn-col-7               span 7  (asymmetric wide side)
.wn-col-8               span 8  (wide+narrow wide side)
.wn-col-10              span 10 (wide content)
.wn-col-12              span 12 (full bleed)

/* Centred columns (offset within the grid) */
.wn-col-10-centred      grid-column: 2 / 12  (10 cols, 1-col margin each side)
.wn-col-8-centred       grid-column: 3 / 11  (8 cols, 2-col margin each side)

7. Internal Card Spacing

Card spacing is not handled by the grid — it's handled by the component. Standard values:

Use	Token	Value
Card internal padding	`--space-l`	36→40px
Card gap within a grid	`--space-m` (inherited from `.wn-grid`)	27→30px
Tight card padding (compact)	`--space-s-m` pair	18→30px

8. Known Migration Notes

Phase 2 work (not blocking Phase 0d):

Name conflict — --space-xs and --space-xl in site.css: site.css defines these names in its legacy layout helpers :root block, shadowing the Utopia values from tokens.css. Fix in Phase 2: rename the legacy aliases to --legacy-space-xs / --legacy-space-xl, or remove the block entirely once dependent code is migrated.
Legacy .section + .container on the homepage: The current homepage uses these legacy classes (1180px container, --space-xl: 7rem padding) rather than the new .wn-section + .wn-container utilities. These co-exist until the Phase 2 renderer migration.
--max-w: 1180px in site.css: Superseded by --wn-content-max (1280px) and .wn-container--narrow (1180px). Remove in Phase 2.