Proposal: grid-guideline property for visualizing grid lines in development

[rezaei]

Proposal: grid-guideline property for visualizing grid lines in development

Problem

In CSS Grid, grid lines are conceptual and are not visually displayed on the page.
For developers and designers, being able to see the grid lines during design and debugging would be very helpful.

Current workarounds have limitations:

Using outline or border only affects items, so empty cells remain invisible.

For grids with variable row heights and column widths, manual calculations or JavaScript overlays are required.

Developers often rely on browser DevTools, which are not part of the standard CSS.

Proposed New Feature

Introduce a new property:

grid-guideline: <value>;

The value works similar to border, accepting standard border properties:

Color: green, rgba(0,0,0,0.3)

Thickness: 1px, 2px

Style: solid, dashed, dotted

Example

.container {
  display: grid;
  grid-template-columns: 100px 2fr 150px;
  grid-template-rows: 80px auto 60px;
  gap: 10px;

  grid-guideline: 1px dashed rgba(255,0,0,0.3);

}

Grid lines are visually displayed for all cells, including empty ones.

Intended for development/debugging purposes only; can be disabled in production.

Behaves similarly to border and is fully compatible with standard CSS syntax.

Grid lines should appear on top of all grid items, i.e., have the highest z-index within the grid.

Advantages

Provides visual guidance for all grid cells without external overlays or manual calculations.

Supports grids with variable column widths and row heights.

Useful for teaching and documentation of CSS Grid.

Simple and consistent with existing CSS conventions.

Notes

This feature does not affect layout or positioning of grid items.

Could be optionally scoped to @media (development) or similar approaches for production safety.

[astearns]

Can you go into more detail about why “Developers often rely on browser DevTools, which are not part of the standard CSS.” is a problem that needs to be solved?

[oSamDavis]

This looks like a use case for CSS Gap Decorations, which would allow styling the gap directly which makes it possible to draw track separators.

For your specific example, you could achieve the desired outcome with a rule like this:

rule: 1px dashed rgba(255,0,0,0.3);
column-rule-break: none;
row-rule-break: none;

One detail is that gap decorations are painted at container level and are not affected by z-index. For debugging purposes, you can temporarily set the items' opacity to less than 1 to see the decorations drawn behind items.

You can also refer to this blog post for more on CSS Gap Decorations. cc: @kbabbitt

[Crissov]

Although the use cases and possible solutions are a bit different, this is conceptually related to showing invisible characters: #8874

Making the presence of Dev Tools, discoverable with at-rules, i.e. introducing some kind of debug mode, has not been proposed here as a solution yet - and it isn’t one, because many authors would abuse it for obfuscation.

[rezaei]

In real-world design workflows, having visible gridlines or guidelines is a fundamental visual aid — much like the graph paper used by architects, engineers, or even children learning to draw.

Applications such as CorelDRAW, Photoshop, or even Microsoft Word include grid or guide overlays to help users align and organize elements visually.
If the goal of CSS is, in part, to simulate real-world design principles, then having a visual feature such as grid-guideline could be a natural and helpful addition.

This would not only assist web designers while creating layouts but could also enable browser-based design tools to evolve closer to traditional desktop design software.

As an optional behavior, the Working Group could even consider linking this feature to design contexts — for example, having gridlines visible only when document.designMode = 'on'.
This property is already part of the WHATWG HTML standard
and is supported across all major browsers, making it a logical place to expose design-oriented visual aids.

@astearns — Thank you for your question.
The problem is that developers currently rely on non-standard browser DevTools to visualize grid lines.
These implementations vary across browsers and are unavailable in many contexts (e.g., teaching environments, web-based editors, and design systems).
A standardized grid-guideline would ensure consistent visual behavior across all environments, making layout visualization predictable and accessible without DevTools.

@oSamDavis — I appreciate your reference to CSS Gap Decorations; that’s a fascinating proposal.
However, grid-guideline is not intended for styling content but for visual alignment and debugging.
While Gap Decorations can style spaces, guidelines would appear above all grid items (highest stacking context), providing an overlay similar to Figma’s layout grid.
Both concepts could complement each other well.

@Crissov — Thanks for pointing out the relation to invisible characters.
I agree that grid-guideline would be purely visual and non-rendering — it wouldn’t affect layout or user interaction.
It would simply visualize track boundaries, similar to design overlays in other creative tools.

Finally, I’d like to note that even if similar functionality can be approximated through non-standard or “hacky” solutions, that shouldn’t prevent official standardization.
Having a native, standardized, and interoperable feature ensures reliability and consistent user experience across all browsers — which is, ultimately, the spirit of the web platform.

[Crissov]

I totally forgot about document.designMode, but discovering this author-controlled state from CSS/Selectors – e.g. :root:read-write? – would be different from discovering the user-controlled state of Developer Tools being active.

Perhaps – and I’m not sure this is a good idea at all – a viable approach for some related use cases would be a couple of new system color keywords that would always compute to transparent. Only in “design mode”, ”debug mode ”, “edit mode” or “user input mode”, they would become a visible, implementation-dependent color:

• Invisible or InvisibleBackground
• InvisibleText or InvisibleCharacters for 8874
• InvisibleRule, InvisibleBorder or InvisibleFrame to solve this issue when used within rule

Optionally, new properties similar to accent-color could influence the looks at the behest of authors, cf. #11199.

Alas, I assume some authors would then also want to have lengths that compute to 0px unless in that special mode, and I don’t feel good alt handling that by special values.