Re: [csswg-drafts] [css-grid-3][masonry] item-flow row vs. column in masonry layouts (#12803)

Okay, I have a new proposal for how we slice up these properties. I think this sidesteps some of the conflicts we've been having, uses fairly reasoanble generic names, and imo has better forward-compatibility for unknown future designs. I've talked this over with @alisonmaher @kbabbitt @fantasai and gotten rough approval on it, so hopefully we can start from this proposal in the discussion on Thursday.

-------

# Proposal

* flow-direction: `<'flow-track'> || <'flow-direction-primary'> || <'flow-direction-secondary'>`
 * flow-track: `normal | row | column`
 * flow-direction-primary: `normal | flow-reverse`
 * flow-direction-secondary: `normal | cross-reverse`
* flow-wrap: `normal | wrap | nowrap`
* flow-pack: `normal | dense | balance`
* flow-tolerance: `normal | <length-percentage> | infinite`
* flow: `<'flow-track'> || <'flow-direction-primary'> || <'flow-direction-secondary'> || <'flow-wrap'> || <'flow-pack'> || <'flow-tolerance'>`

# Existing property shorthanding:

* `flex-direction` -> `flow-track` + `flow-direction-primary`
* `flex-wrap` -> `flow-direction-secondary` + `flow-wrap`
* `grid-auto-flow` -> `flow-track` + `flow-direction-primary` + `flow-pack`
* `grid-lanes` -> (all of `flow` except for `flow-wrap`, + `grid-template-rows/columns`) <small>assuming that we go with `display: grid-lanes`</small>

# Value Meanings

* `flow-track: row` in Flexbox is `flex-flow: row`. In Grid it's `grid-auto-flow: row`. In Masonry it's "brick layout", using `grid-template-rows`/etc.
* `flow-direction-primary` controls whether your "primary flow direction" is normal or reversed. In Flexbox, it's `flex-direction:row` vs `row-reverse`. In Grid it's `grid-auto-flow: row` vs `row-reverse`. In Masonry it's the tie-breaking / direction of flow - for waterfall, left-to-right vs right-to-left placement.
* `flow-direction-secondary` is "the other one". In Flexbox, it's how flex lines stack. In Grid, currently no meaning, but we could define it fills from bottom. In Masonry, it's how items fill a track - for waterfall, top-to-bottom vs bottom-to-top.
* `flow-wrap` only has meaning in Flexbox. Ignored in Grid and Masonry.
* `flow-pack: dense` in Flexbox puts items in the earliest line they can fit in. (Already defined for Grid and Masonry.)
* `flow-pack: balance` does line balancing in Flexbox. Does nothing in Masonry. (Masonry *always* balances.) Does nothing in Grid? (For Grid, "balance across rows" is achieved *exactly* by instead using `grid-auto-flow: column`.)
* `flow-tolerance` in Flexbox allows line overflow by up to tolerance length (triggering `flex-shrink`). (Or allows squishing each item by up to tolerance length?) Does nothing in Grid. Masonry already has a definition.

# Design Notes

* Need to split `flow-direction` into longhands due to how Flexbox has sliced its properties, but don't expect authors to actually set those properties. `flow-direction` (or just `flow`, the uber-shorthand) is easier and much shorter.
* The two `*-reverse` values **must be different** so they're distinguishable in the shorthands (both `flow-direction` and the bigger `flow`). I have *absolutely no opinion* on what we actually use for the keywords, but the presented keywords are my best idea so far.
* All the `normal` values are initial values, so they're just no-ops; we ignore them when parsing the `item-flow` shorthand.
* We have to use `normal` for these magic initial values, not `auto`, because `auto` is a track size as well; Masonry wants to mix those together, maybe Grid, and possibly other future layout modes.
* `flow-wrap` is split out from the `flow-direction` longhands because (a) so far it *only* has meaning in Flexbox, and (b) it means we don't need to generically decide on whether wrapping is a "primary" or "secondary" axis thing. It's just ignored in Masonry and Grid. Future layout modes can decide whether they want it or not.
* I decided that `dense` and `balance` packing are mutually exclusive. Is this a reasonable assumption to make? It certainly is today, in the only layout mode that could support both of them (Flexbox). We can always relax parsing to `dense || balance` in the future if we end up needing it. (*In theory* I could see a way to have `dense balance`, where you allow arbitrary reordering to achieve optimal balance, but that's super expensive and probably never something we want to do anyway.)
* We'll need to decide whether `flow-direction-secondary` does something in Grid or is ignored; that's not something we can decide later.

-- 
GitHub Notification of comment by tabatkins
Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/12803#issuecomment-3519260414 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Wednesday, 12 November 2025 00:01:46 UTC