This module introduces logical properties and values that provide the author with the ability to control layout through logical, rather than physical, direction and dimension mappings. The module defines logical properties and values for the features defined in [CSS21]. These properties are writing-mode relative equivalents of their corresponding physical properties.
CSS is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, in speech, etc.
Status of this document
This is a public copy of the editors’ draft.
It is provided for discussion only and may change at any moment.
Its publication here does not imply endorsement of its contents by W3C.
Don’t cite this document other than as work in progress.
GitHub Issues are preferred for discussion of this specification.
When filing an issue, please put the text “css-logical-props” in the title,
preferably like this:
“[css-logical-props] …summary of comment…”.
All issues and comments are archived,
and there is also a historical archive.
See [CSS3-WRITING-MODES]Abstract Layout for details on how to map between logical and physical terms.
This mapping controls the interpretation of logical keywords and properties.
Properties that accept physical directional keyword values
(top, bottom, left, or right) are redefined
to also accept the appropriate logical directional keywords.
In such cases,
the logical values can be used in place of the corresponding physical values.
For properties that take multiple keywords, combinations of logical and
physical values are not allowed (unless otherwise specified in a future specification).
Properties can be either 1-dimensional or 2-dimensional.
When contextually constrained to one dimension,
the logical keywords are shortened.
The caption-side property is 1-dimensional in CSS2.1,
but was 2-dimensional in CSS2.0,
(and presumably will be 2-dimensional again in the next update to CSS tables).
It therefore accepts the full set of logical directions.
However, the inline-start and inline-end properties
(which correspond to the behavior of the left and right values in CSS2.0)
are only required to be supported by UAs that support left and right.
1.2. Logical Values for the float and clear Properties
In CSS, all pages are classified by user agents as either left pages
or right pages. [CSS21] Which page is first in a spread, however,
depends on whether the page progression is left-to-right or right-to-left.
To allow control of page breaking to the page that is on the earlier
or later side of a spread, rather than to the left or right side of a
spread, this module introduces the following additional keywords for the page-break-after and page-break-before properties [CSS21]:
recto
Equivalent to right in left-to-right page progressions
and left in right-to-left page progressions.
verso
Equivalent to left in left-to-right page progressions
and right in right-to-left page progressions.
Logical page selectors are also added to support logical page selection.
Authors typically place page numbers using physical placements,
but the contents of headers often follows conventions depending
on which page in the spread is earlier.
Following page
selectors are added to support this scenario:
:recto
Equivalent to ':right' in left-to-right page progressions
and ':left' in right-to-left page progressions.
:verso
Equivalent to ':left' in left-to-right page progressions
and ':right' in right-to-left page progressions.
The logical page selectors have specificity equal to the ':left'
and ':right' page selectors.
3. Logical Box Model Properties
This specification introduces new CSS properties
that are logical equivalents
of physical box model properties.
The specified values of these properties are separate from
the specified values of the parallel physical properties,
but the logical and physical properties share computed values.
Which pairs of properties share computed values
depends on the computed values of writing-mode and direction.
For a summary of these dependencies, see Abstract-to-Physical Mappings in [CSS3-WRITING-MODES].
A computed value that has logical and physical properties
is determined by applying the CSS cascade to declarations of both.
Overriding is not determined by whether a declaration is logical or physical,
but only by the rules of the CSS cascade [CSS3-CASCADE].
Note that this requires implementations to maintain
relative order of declarations within a CSS declaration block,
which was not previously required for CSS cascading.
For example, given the following rule:
p {margin-inline-start:1px;margin-left:2px;margin-inline-end:3px;}
How do computed value APIs, e.g., getComputedStyle() work?
Can they be used with either logical or physical properties,
or only with the physical ones?
The shorthand properties for margin, padding, and border set values
for physical properties by default. But authors can specify the logical keyword at the beginning of the property value to indicate that the values
map to the logical properties instead of the physical ones.
other candidates of the keyword are: relative, script, writing-mode, beas, or the value itself (e.g., vertical-lr-ltr)
The following [CSS21] shorthand properties accept the logical keyword:
[CSS3BG] is handled separately because it can fill an area with specified
images, and the area to fill can be rotated or flipped depending on the text
flow.
4.1. Background Image Transform: The background-image-transform property
is this the right default? we need to investigate which is more common
This property defines whether background images are transformed to match to
the value of writing-mode property, and whether background-size widths and
heights are logical or physical. Values have the following meanings:
logical
The values for the background-size property are logical.
The background images are transformed to match to the logical axis.
physical
The values for the background-size property are physical.
The background images remain unchanged.
rotate
Similar to logical, except that the inline direction is ignored.
The result is affected only by the block flow direction.
The repeat-x and repeat-y values are logical, but in CSS3 this
property can also accept double values to specify horizontal and vertical
behaviors separately. The double values are considered logical if the logical keyword is specified, otherwise physical.
should also add repeat-horizontal and repeat-vertical for the physical value?
This property defines whether border images are transformed to match to the
value of writing-mode property, with the reference writing mode being writing-mode: horizontal-tb; direction: ltr. Values have the following
meanings:
logical
The values for the border-image-* properties are logical.
The border images are transformed to match to the logical axis.
physical
The values for the border-image-* properties are physical.
The border images remain unchanged.
rotate
Similar to logical, except that the inline direction is ignored.
The result is affected only by the block flow direction.
The following properties use the value of this property to determine how
directional mappings are done:
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.
Advisements are normative sections styled to evoke special attention and are
set apart from other normative text with <strong class="advisement">, like
this: UAs MUST provide an accessible alternative.
Conformance classes
Conformance to this specification
is defined for three conformance classes:
A style sheet is conformant to this specification
if all of its statements that use syntax defined in this module are valid
according to the generic CSS grammar and the individual grammars of each
feature defined in this module.
A renderer is conformant to this specification
if, in addition to interpreting the style sheet as defined by the
appropriate specifications, it supports all the features defined
by this specification by parsing them correctly
and rendering the document accordingly. However, the inability of a
UA to correctly render a document due to limitations of the device
does not make the UA non-conformant. (For example, a UA is not
required to render color on a monochrome monitor.)
An authoring tool is conformant to this specification
if it writes style sheets that are syntactically correct according to the
generic CSS grammar and the individual grammars of each feature in
this module, and meet all other conformance requirements of style sheets
as described in this module.
Requirements for Responsible Implementation of CSS
The following sections define several conformance requirements
for implementing CSS responsibly,
in a way that promotes interoperability in the present and future.
Partial Implementations
So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid
(and ignore as appropriate)
any at-rules, properties, property values, keywords, and other syntactic constructs
for which they have no usable level of support.
In particular, user agents must not selectively ignore
unsupported property values and honor supported values in a single multi-value property declaration:
if any value is considered invalid (as unsupported values must be),
CSS requires that the entire declaration be ignored.
Implementations of Unstable and Proprietary Features
Once a specification reaches the Candidate Recommendation stage,
implementers should release an unprefixed implementation
of any CR-level feature they can demonstrate
to be correctly implemented according to spec,
and should avoid exposing a prefixed variant of that feature.
To establish and maintain the interoperability of CSS across
implementations, the CSS Working Group requests that non-experimental
CSS renderers submit an implementation report (and, if necessary, the
testcases used for that implementation report) to the W3C before
releasing an unprefixed implementation of any CSS features. Testcases
submitted to W3C are subject to review and correction by the CSS
Working Group.
Further information on submitting testcases and implementation reports
can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/.
Questions should be directed to the [email protected] mailing list.
All elements, except internal table elements when border-collapse is collapse
yes
n/a
visual
discrete
per grammar
as specified
Issues Index
Is this a 2-directional property? Should these just be start/end? ↵
float needs coordination with GCPM where it defines page floats ↵
How do computed value APIs, e.g., getComputedStyle() work?
Can they be used with either logical or physical properties,
or only with the physical ones? ↵
other candidates of the keyword are: relative, script, writing-mode, beas, or the value itself (e.g., vertical-lr-ltr) ↵
Should the shorthand also reset the physical properties to their initial
values? ↵
is this the right default? we need to investigate which is more common ↵
should also add repeat-horizontal and repeat-vertical for the physical value? ↵