Logical Gradients

A Collection of Interesting Ideas,

This version:


The goal of this document is to specify a syntax for writing gradients with flow-relative directions in CSS.

1. Introduction

Because different writing systems are written in different directions, a variety of writing modes exist: left to right, top to bottom; right to left, top to bottom; bottom to top, right to left; etc. logical concepts like the “start” of a page or line map differently to physical concepts like the “top” of a line or “left edge” of a paragraph. Some aspects of a layout are actually relative to the writing directions, and thus will vary when the page is translated to a different system; others are inherently relative to the page’s physical orientation.

The module defines logical properties and values for the features defined in css-images. These properties are writing-mode relative equivalents of their corresponding physical properties.

1.1. Flow-Relative Values for linear-gradient()

The linear gradient syntax is:

linear-gradient() = linear-gradient(
  [ <angle> | to <side-or-corner> ]? ,
<side-or-corner> =
[ [left | right] || [top | bottom] ] |
[ [inline-start | inline-end] || [block-start | block-end ] ]
Name: side-or-corner
New values: [ inline-start | inline-end ] || [ block-start | block-end ]

The mapping on this property uses the writing mode of the element’s containing block.

Note: These properties are 1-dimensional in CSS2, but are planned to be expanded to two dimensions, and therefore are given unabbreviated flow-relative keywords.

1.1.1. Flow Relative Linear Gradient Examples

All of the following linear-gradient() examples are presumed to be backgrounds applied to a box that is 200px wide and 100px tall.

For example, the two rules are equivalent in left-to-right page progressions:
header {
  background-image: linear-gradient(to inline-end, yellow 0%, blue 100%);
header {
  background-image: linear-gradient(to right, yellow 0%, blue 100%);

This would also be equivalent in right-to-left page progressions as:

header {
  background-image: linear-gradient(to left, yellow 0%, blue 100%);


Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.


Terms defined by this specification

Terms defined by reference


Normative References

Elika Etemad. CSS Display Module Level 3. URL: https://www.w3.org/TR/css-display-3/
Tab Atkins Jr.; Elika Etemad; Lea Verou. CSS Image Values and Replaced Content Module Level 4. URL: https://www.w3.org/TR/css-images-4/
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. URL: https://www.w3.org/TR/css-values-3/
CSS Writing Modes Module Level 4 URL: https://drafts.csswg.org/css-writing-modes-4/
Elika Etemad; Tab Atkins Jr.. CSS Image Values and Replaced Content Module Level 3. 17 April 2012. CR. URL: https://www.w3.org/TR/css3-images/
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

Property Index

No properties defined.