CSS Masonry Layout

[fantasai]

こんにちは TAG-さん!

I'm requesting an early TAG design review of masonry layout in CSS.

Masonry layout creates grid-based tracks in a single axis, and stacks items tightly in the other, creating rows or columns but not both. It is currently drafted into https://www.w3.org/TR/css-grid-3/ with two possible syntax options: a grid-based syntax that uses a keyword to relax alignment in the stacking axis, and an independent syntax that uses a blend of flex and grid concepts with a new set of properties. The arguments in the debate center over a) which is easier to learn for authors and b) how might this decision impact possible future developments in one or both models (or CSS in general).

I'm opening this issue to ask the TAG to schedule a review of the spec in general and of the syntax question specifically. We are currently collecting feedback, and are hoping to have a CSSWG discussion on this question in late October / early November. We will update this issue as input comes in.

• Explainer¹: See spec introduction for a basic intro and Jen's blog post for more extensive examples
• User research: See other links.
• Security and Privacy self-review²: Nothing interesting to report
• GitHub repo: CSSWG repo
• Primary contacts:
  • Elika J Etemad (@fantasai), Apple, editor
  • Tab Atkins-Bittner (@tabatkins), Google, editor
• Organization/project driving the design: Mozilla, Apple, Google
• Multi-stakeholder feedback³:
  • Chromium comments: Positive in general; started implementation. See also:
    • Proposal for alternative model and in particular this comment from Tab
    • https://developer.chrome.com/blog/masonry-syntax
  • Mozilla comments: Positive in general; prototyped initial draft. No position posted yet (afaik) on the open syntax debate, but they proposed the original grid-based syntax in 2020.
  • WebKit comments: Positive in general; usable experimental implementation in progress. See also:
    • https://webkit.org/blog/16026/css-masonry-syntax/
  • Developer/designer comments:
    • See comments in [css-grid-3] Designer/developer feedback on masonry layout w3c/csswg-drafts#10233 ; Alternative masonry path forward w3c/csswg-drafts#9041 ; note there's some bias in where authors posted comments, since one was linked from the WebKit post and the other from the Chrome team post.
    • This blog post does a deep dive into examples: https://ishadeed.com/article/css-grid-masonry/

Further details:

• I have reviewed the TAG's Web Platform Design Principles
• The group where the incubation/design work on this is being done (or is intended to be done in the future): CSSWG
• The group where standardization of this work is intended to be done ("unknown" if not known): CSSWG
• Existing major pieces of multi-implementer review or discussion of this design:
  • Index of individual issues grouped under Chrome's uber-issue
  • CSSWG resolution adopting mixed track sizing
• Major unresolved issues with or opposition to this design: Syntax and direction of future development being integrated with, or segregated from, CSS Grid Layout.
• This work is being funded by: Mozilla, Apple, Google.

You should also know that...

• Some of the key arguments in the early syntax debate were resolved by the above-linked resolution to adopt mixed track sizing under both options, with some notes/restrictions wrt performance, so if you're doing archaeology keep that in mind.
• We're hoping to schedule CSSWG discussion of the syntax and overall direction of this module in 2-4 weeks or so. Let us know how we can accommodate the TAG.

[jyasskin]

This comment is just from me, without having consulted the rest of the TAG yet.

I see that we have a compelling description of the use case (Yay for solving this problem!) and a pair of documents advocating for the alternative syntaxes. It's not clear whether both sides agree with the claims in each document and just weigh them differently, or also disagree about some of the factual claims. I'm not confident that the TAG will know enough about the design space to figure out what facts are true, although we may be able to help weigh tradeoffs.

Would it be possible for the two sides to get together and produce a consensus document that describes the disagreement and points out the different values that the TAG should be weighing?

[rachelandrew]

As the author of the two Chrome posts on the subject, I'd be happy to help create a consensus document. I also have collected developer feedback on the issue.

[fantasai]

I'm happy to work with @rachelandrew on this.

[fantasai]

Masonry Syntax Debate Overview

Introduction

The CSSWG has published a consensus FPWD of a masonry layout feature for CSS. See CSS Masonry Layout TAG Review Request for an overview of this specification and the discussions leading up to it. There is fundamental disagreement over the syntax model for this new layout mode, thus the FPWD includes two competing proposals.

The disagreements center around two key concerns: usability for authors, and extensibility into the future. The best way to understand these points would be to read these blog posts advocating for each:

• Chrome Blog: How should we define CSS masonry?
• WebKit Blog: Help us choose the final syntax for Masonry in CSS
• Ahmad Shadeed: Should masonry be part of grid?
• Rachel Andrew: Masonry and good defaults
• Keith J. Grant: Weighing in on CSS masonry [published before the merged FPWD]

We summarize the high-level disagreements below. For examples, please refer to the blog posts.

Usability for Authors

Learnability

• Chrome argues that a separate display type is easier to learn because a dedicated syntax and mental model can be tailored more closely to the characteristics of the layout, and because segregating layout into separate modules makes them easier to understand. They assert that Grid syntax would be interpreted differently or would otherwise be confusing when re-used for masonry layout.

• WebKit argues that an integrated display type is easier to learn, because it re-uses exactly an existing syntax and mental model, leaving minimal syntax and concepts to learn, even if there are slight differences in behavior in the two modes—allowing authors to easily switch between them mentally as well as in code.

Defaulting

• Chrome argues that using a separate display type allows for better default behavior, leaving fewer things to configure for common cases.
• WebKit argues that Chrome's proposed default values are not actually usable for most of the common cases; and therefore aren't better defaults. They assert that relying on automatic behavior at the container level just pushes down the need for configuration to the items, which is less understandable/performant/powerful.

Redundancy

• Chrome argues that re-using Grid's 2D properties means nearly every Grid feature has some syntax that is ignored or reinterpreted in Masonry's 1D layout; therefore re-using patterns rather than properties is better.
• WebKit argues that creating a separate display type with its own dedicated properties introduces a lot of slightly divergent duplicated syntax into CSS, where CSS usually re-uses properties across contexts wherever they can reasonably apply, ensuring a consistent and minimal interface to shared concepts.

Extensibility

Masonry layout and Grid layout have some key differences:

• Masonry layout imposes sizing consistency on all items in the same track in one dimension; regular grid layout imposes it in two dimensions.
• Masonry layout requires track sizing before auto-placement can occur (because auto-placement needs to know the sizes of already-placed items to determine where to place the next item), whereas regular grid layout requires placement before track sizing (because track sizes depend on what items were placed into them). We were able to introduce auto-sized tracks into masonry by sizing them with the assumption that all auto-placed item are placed into all tracks.

These differences mean that some layout operations are easier or more reasonable in masonry than in grid and vice versa.

• Chrome argues that by making masonry a separate display type it allows the feature set of masonry and grid layout to diverge, making it easier to introduce a feature in one without entangling it with the other. They cite the example of asking the UA to calculate how many auto-sized columns could fit in a masonry container, which would require heuristics in both but likely have more convoluted behavior in Grid.
• WebKit argues that by integrating masonry and grid, authors are guaranteed a consistent syntax and feature set, and this is worth the extra effort and complication to make a given feature work in both modes. They cite the example of mixing different track size types in a given masonry container, which Chrome had asserted was impossible to do performantly, but which the CSSWG has solved and specced in the FPWD.

Question

The CSSWG is seeking the TAG's input into this question, to help inform the debate.

[jyasskin]

Overall, we think masonry, grid, and wrapping-flexbox should be incorporated into a unified set of properties. Chrome's proposal splits apart property sets too eagerly, but even the WebKit proposal seems to miss a chance to develop more-general properties.

Examining the arguments put forward from either side, we found some compelling and some less so:

1. It was argued that a separate set of properties is necessary for sensible defaults. However, there is precedent for using "smart" defaults that are different based on other property values. Perhaps the masonry shorthand can be used to set grid-integrated properties.
2. It was argued that the grid-integrated syntax makes it easier to convert from grid syntax to grid-integrated masonry syntax, however we don't optimize for the transition period unless it's going to derail adoption.
3. It was argued that the grid-integrated syntax makes it easier to switch between grid and masonry at a breakpoint or switch between row and column tracks, however we don't expect this to be a common enough use case to be worth optimizing for.
4. It was argued that the grid-independent syntax makes things easier if the properties need to diverge in the future. We think that is a drawback of that syntax, not a feature. Even if the WG selects a syntax like the grid-independent one, it should work hard to ensure that the properties diverge as little as possible in the future, even if some masonry properties initially appear not to have an obvious behavior for other display modes. It would be even worse to evolve subtle variations in patterns that otherwise appear to match, for example by forgetting to apply a new grid keyword to the parallel masonry property.
5. It was argued that the grid-independent syntax would also push future layout modes towards becoming separate property sets, which would be detrimental for the overall learnability of the language. We do think this has some basis, given the principle of consistency, but there are also enough differences between pillar and masonry to justify different design decisions.
6. We appreciated the argument that historically in graphic design grids were actually one-dimensional until relatively recently, although this doesn't prove that such grids fit into display:grid.
7. It was argued that because most masonry use cases are simpler than Grid, developers should be able to learn it without having to first learn Grid. This is an important goal. Can you instead achieve it by simplifying a subset of Grid that works for these types of simple cases? For example, multicol makes it easy to define several equal columns, optionally with constraints about their total number, min/max dimensions, or both. Can you share the track definitions between multicol and masonry? This need also arises fairly often with a 2-d grid: can the WG port this simplicity to Grid layout, and share the required properties across all three layout modes?

We also noticed some larger issues with the space of CSS layout modes:

• CSS currently has 3 layout modes all of which basically generate a 2d arrangement of children, with different rules for which dimensions line up and what order the available layout slots are filled: grid, multicol, and wrapping-flexbox. This is already causing a lot of author confusion, and Masonry attempts to add a 4th mode. As a general principle, having vastly different ways to accomplish slightly different things is a usability antipattern. We urge the WG to explore ways to unify these so that authors can port more knowledge from one to the other (even if they are implemented as separate code paths internally). For example grid-auto-flow, flex-direction, masonry-direction, and masonry-fill all control the same stylistic aspect from an author pov and it seems that they could be more unified to some degree.
• While sometimes inevitable, having properties specify things that get ignored is also an antipattern. It is particularly damaging to DX if from an author perspective it seems that these properties really ought to work together, but they don't. As specified, grid-auto-flow in the grid-integrated proposal falls in that category: we should not require authors to specify a flow axis that is then ignored.
• There's a wider space of layout patterns, including the Flickr-style grid and layouts derived from magazines and newspapers, which CSS should eventually be able to represent. It's unfortunate to add a whole new layout mode without showing how it contributes toward the rest of the needed layouts. If we think of multicol as being a grid with just one row, many of these patterns, including Masonry and "pillar", seem to involve the ability to instruct the browser to stack the next child into one or more cells with some existing content. These patterns blur the line we've been assuming between 1-d and 2-d layout, and the WG may need to solve the problem by leaning into a continuum between those two options. It would be ideal to find a set of properties that can be used to build all of these layout patterns, instead of potentially overfitting to just masonry layouts.

We recognize that it's important to make incremental progress and that it's impossible to break backward-compatibility with the existing properties. We hope there's a way to imitate the way gap was backported, but even if there's not, we think the new features' designs would benefit from a sense of what we would have done if we had a time machine.

[nt1m]

It was argued that the grid-integrated syntax makes it easier to convert from grid syntax to grid-integrated masonry syntax, however we don't optimize for the transition period unless it's going to derail adoption.

I disagree this doesn't matter fwiw, I think it's a feature that grid-integrated masonry nicely degrades to a CSS grid. Whereas grid-independent masonry would need to duplicate the set of properties for that degradation to be possible. Graceful degradation doesn't seem mentioned in this TAG review, but I think it is an important point.

[jyasskin]

@nt1m [Trying to channel the rest of the TAG, but I haven't checked this with them, so it could be wrong.] There are two ideas here:

1. The Webkit blog that we linked to in that point argues that "it’s an easy transition to go from thinking about CSS Grid to thinking about packed masonry-style layouts". That seems like an argument that you don't have to change the code much when you have a grid layout and want to adopt masonry, or that it's easy for people who already know grid to start using masonry. That doesn't seem like a great argument, since most future code will be written directly into either grid or masonry, and by people who had the option of learning either grid or masonry first.
2. The point you're making in this comment, that it's good for code to gracefully degrade in browsers that don't support masonry. All things equal, code absolutely should degrade gracefully. But if other things aren't equal, it's probably better to prioritize some of the other considerations like (for example) learnability and the coherence of the whole space of properties. Graceful degradation would be more important if @supports didn't exist, if there were going to be a years-long gap between the different engines shipping this, or if pages written to use this in evergreen browsers are likely to be completely unusable in older browsers, but I didn't find an argument that that's the case for either masonry syntax.

Keep in mind that this review isn't guaranteed to be correct: it's just the TAG's opinion with maybe a wider view but less context and study than the CSSWG.