CSS Logical Properties and Values Level 1

1.Introduction

Note:See[css-writing-modes-4]for a proper introduction to writing modes; this module assumes familiarity with its terminology.

Because different writing systems are written in different directions, a variety ofwriting modesexist: 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.

For example, lists, headings, and paragraphs are typically left-aligned in English; but actually they are start-aligned, because in Arabic the same constructs are right-aligned, and a multilingual document will need to accommodate both writing systems accordingly.

The following code exemplifies how using logical syntax can help you write code that works across different writing systems:

<blockquotedir="auto">Quotation in English</blockquote>
<blockquotedir="auto">اقتباس في العربية</blockquote>

blockquote{
text-align:start;/* left in latin, right in arabic */
margin-inline-start:0px;/* margin-left in latin, margin-right in arabic */
border-inline-start:5pxsolid gray;/* border-left in latin, border-right in arabic */
padding-inline-start:5px;/* padding-left in latin, padding-right in arabic */
}

Documents might need both logical and physical properties. For instance the drop shadows on buttons on a page must remain consistent throughout, so their offset will be chosen based on visual considerations and physical directions, and not vary by writing system.

Since CSS was originally designed with only physical coordinates in its controls, this module introduces text-flow–relative equivalents so that declarations in a CSS style sheet can be expressed inflow-relativeterms. It defines the mapping and cascading of equivalent properties, some new properties and values equivalent to those in CSS2.1, and the principles used to derive their syntaxes. Future CSS specifications are expected to incorporate both sets of coordinates in their property and value definitions, so this module will not track the introduction offlow-relativevariants of newer CSS features.

CSS Writing Modes’Abstract Box Terminologysection defines how to map between flow-relative and physical terms. This mapping, which depends on theused valuesofwriting-mode,direction,andtext-orientation, controls the interpretation offlow-relativekeywords and properties.

Note:Due to its interaction withtext-orientation: upright, theuseddirectiondepends on thecomputed valuesofwriting-modeandtext-orientation.

1.1.Value Definitions

This specification follows theCSS property definition conventionsfrom[CSS2]using thevalue definition syntaxfrom[CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units[CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept theCSS-wide keywordsas their property value. For readability they have not been repeated explicitly.

2.Flow-Relative Values:block-start,block-end,inline-start,inline-end

Many CSS properties have historically accepteddirectional keywordvalues that arephysical(top,bottom,left,right). This specification introducesdirectional keywordvalues that areflow-relative:block-start,block-end,inline-start,inline-end.

A property’s effect can be either 1-dimensional or 2-dimensional. When contextually constrained to one dimension, the flow-relative keywords are abbreviated (tostartandend).

CSS Level 2 properties are here redefined to also acceptflow-relativedirectional keywords. Such values can be used in place of the corresponding physical values. For properties that take multiple keywords, combinations of flow-relative and physical values are not allowed (unless otherwise specified in a future specification).

Note:Newer CSS specifications are expected in most cases to defineflow-relativeorline-relativevalues instead of or in addition to anyphysicalones. In general, the mapping of such relative values are expected to use thewriting modeof thecontaining blockwhen affecting the box itself, and that of the box itself when affecting its contents. Regardless, whichwriting modesis used for the mapping needs to be explicitly defined.

2.1.Logical Values for thecaption-sideProperty

These two values are added only for implementations that supportleftandrightvalues forcaption-side. Theleftandrightvalues themselves are defined to beline-relative.

The existingtopandbottomvalues are idiosyncratically redefined as assigning to theblock-startandblock-endsides of the table, respectively.

The mapping on this property uses thewriting modeof the caption’scontaining block(that is, thetable wrapper box).

2.2.Flow-Relative Values for thefloatandclearProperties

The mapping on these properties uses thewriting modeof the element’scontaining block.

Note:These properties are 1-dimensional in CSS2, but are planned to be expanded to two dimensions, and therefore are given unabbreviatedflow-relativekeywords.

2.3.Flow-Relative Values for thetext-alignProperty

These values are normatively defined in[css-text-3].

3.Flow-Relative Page Classifications

In CSS, all pages are classified by user agents as either left pages or right pages.[CSS2]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 thepage-break-afterandpage-break-beforeproperties[CSS2]:

recto

Equivalent torightin left-to-right page progressions andleftin right-to-left page progressions.

verso

Equivalent toleftin left-to-right page progressions andrightin right-to-left page progressions.

These values are computed as specified and are further defined in[css-break-3].

Although authors typically place page numbers using physical placements, the contents of headers often follows conventions depending on which page in the spread is earlier. Therefore the following flow-relativepage selectorsare also added to support flow-relative page selection:

: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 flow-relative page selectors have specificity equal to the ':left' and ':right' page selectors.

4.Flow-Relative Box Model Properties

For many formatting effects, the axis or direction affected is encoded in the property name rather than in its value. The type of directional or axis mapping (flow-relativeorphysical) of each such property is called itsmapping logic. Historically, all properties have been encoded inphysicalterms; this specification introduces new CSS properties that areflow-relativeequivalents of CSS2’sphysicalbox model properties.

Note:Newer CSS specifications are expected in most cases to defineflow-relativeorline-relativeproperties instead of or in addition to anyphysicalones.

Each set of parallelflow-relativeproperties andphysicalproperties (ignoringshorthandproperties) related by setting equivalent styles on the various sides or dimensions of a box, forms alogical property group. For example, thepadding-*properties form a singlelogical property group, themargin-*properties form a separatelogical property group, theborder-*-styleproperties form anotherlogical property group, etc. (Eachlonghand propertycan belong to at most onelogical property group.)

Within eachlogical property group, correspondingflow-relativeandphysicalproperties are paired using the element’s owncomputedwriting mode. Although thespecified valueof each property remains distinct, paired properties share acomputed value. This shared value is determined bycascadingthe declarations of both properties together as one; in other words, thecomputed valueof both properties in the pair is derived from thespecified valueof the property declared with higher priority in the CSScascade.[CSS-CASCADE-3]

Note that this requires implementations to maintain relative order of declarations within a CSS declaration block, which was not previously required for CSS cascading. It also requires thatwriting-mode,direction,andtext-orientationbe computed as a prerequisite for cascading together theflow-relativeandphysicaldeclarations of alogical property groupto find theircomputed values.

p{
margin-inline-start:1px;
margin-left:2px;
margin-inline-end:3px;
}

[CSSOM]APIs that return computed values (such asgetComputedStyle()) must return the same value for each individual property in such a pair.

Note:Depending on the element’s ownwriting modefor mapping everyflow-relativeproperty to itsphysicalequivalent simplifies the cascading calculations and gives a straightforward model for authors to reason about. However, it is problematic in many cases, see for examplethis discussion. Authors may need to use nested elements to get the correct mapping behavior when changing an element’swriting modefrom its parent.

Inheritance of each property is from its corresponding property on the parent. For example, although theinline-startmargin of anrtlbox is its right margin,margin-inline-starton this box will inherit themargin-inline-startof anltrparent even though that happens to be the parent’sleftmargin.

Unless otherwise specified,shorthand propertiesthat encompass both logical and physical longhands (such as theallshorthand) set their physical longhands last. For example,all: inheritwill set all of themarginproperties toinherit, but since the physical longhands are set last, the child’s margins will inherit from their physical counterparts in the parent.

4.1.Logical Height and Logical Width: theblock-size/inline-size,min-block-size/min-inline-size, andmax-block-size/max-inline-sizeproperties

These properties correspond to theheightandwidthproperties. The mapping depends on the element’swriting-mode.

These properties correspond to themin-heightandmin-widthproperties. The mapping depends on the element’swriting-mode.

These properties correspond to themax-heightandmax-widthproperties. The mapping depends on the element’swriting-mode.

4.2.Flow-Relative Margins: themargin-block-start,margin-block-end,margin-inline-start,margin-inline-endproperties andmargin-blockandmargin-inlineshorthands

These properties correspond to themargin-top,margin-bottom,margin-left,andmargin-rightproperties. The mapping depends on the element’swriting-mode,direction,andtext-orientation.

These twoshorthand propertiesset themargin-block-start&margin-block-endandmargin-inline-start&margin-inline-end, respectively. The first value represents thestartedge style, and the second value represents theendedge style. If only one value is given, it applies to both thestartandendedges.

4.3.Flow-Relative Offsets: theinset-block-start,inset-block-end,inset-inline-start,inset-inline-endproperties andinset-block,inset-inline,andinsetshorthands

Thetop,left,bottom,rightphysical properties, theirinset-block-start,inset-block-end,inset-inline-start,inset-inline-endflow-relative correspondents, and theinset-block,inset-inline,andinsetshorthands, are collectively known as theinset properties.

These properties correspond to thetop,bottom,left,andrightproperties. The mapping depends on the element’swriting-mode,direction,andtext-orientation.

These twoshorthand propertiesset theinset-block-start&inset-block-endandinset-inline-start&inset-inline-end, respectively. The first value represents thestartedge style, and the second value represents theendedge style. If only one value is given, it applies to both thestartandendedges.

Thisshorthand propertysets thetop,right,bottom,andleftproperties. Values are assigned to itssub-propertiesas formargin.

4.4.Flow-Relative Padding: thepadding-block-start,padding-block-end,padding-inline-start,padding-inline-endproperties andpadding-blockandpadding-inlineshorthands

These properties correspond to thepadding-top,padding-bottom,padding-left,andpadding-rightproperties. The mapping depends on the element’swriting-mode,direction,andtext-orientation.

These twoshorthand propertiesset thepadding-block-start&padding-block-endandpadding-inline-start&padding-inline-end, respectively. The first value represents thestartedge style, and the second value represents theendedge style. If only one value is given, it applies to both thestartandendedges.

4.5.Flow-Relative Borders

4.5.1.Flow-Relative Border Widths: theborder-block-start-width,border-block-end-width,border-inline-start-width,border-inline-end-widthproperties andborder-block-widthandborder-inline-widthshorthands

These properties correspond to theborder-top-width,border-bottom-width,border-left-width,andborder-right-widthproperties. The mapping depends on the element’swriting-mode,direction,andtext-orientation.

These twoshorthand propertiesset theborder-block-start-width&border-block-end-widthandborder-inline-start-width&border-inline-end-width, respectively. The first value represents thestartedge width, and the second value represents theendedge width. If only one value is given, it applies to both thestartandendedges.

4.5.2.Flow-Relative Border Styles: theborder-block-start-style,border-block-end-style,border-inline-start-style,border-inline-end-styleproperties andborder-block-styleandborder-inline-styleshorthands

These properties correspond to theborder-top-style,border-bottom-style,border-left-style,andborder-right-styleproperties. The mapping depends on the element’swriting-mode,direction,andtext-orientation.

These twoshorthand propertiesset theborder-block-start-style&border-block-end-styleandborder-inline-start-style&border-inline-end-style, respectively. The first value represents thestartedge style, and the second value represents theendedge style. If only one value is given, it applies to both thestartandendedges.

4.5.3.Flow-Relative Border Colors: theborder-block-start-color,border-block-end-color,border-inline-start-color,border-inline-end-colorproperties andborder-block-colorandborder-inline-colorshorthands

These properties correspond to theborder-top-color,border-bottom-color,border-left-color,andborder-right-colorproperties. The mapping depends on the element’swriting-mode,direction,andtext-orientation.

These twoshorthand propertiesset theborder-block-start-color&border-block-end-colorandborder-inline-start-color&border-inline-end-color, respectively. The first value represents thestartedge color, and the second value represents theendedge color. If only one value is given, it applies to both thestartandendedges.

4.5.4.Flow-Relative Border Shorthands: theborder-block-start,border-block-end,border-inline-start,border-inline-endproperties andborder-blockandborder-inlineshorthands

These properties correspond to theborder-top,border-bottom,border-left,andborder-rightproperties. The mapping depends on the element’swriting-mode,direction,andtext-orientation.

These twoshorthand propertiesset theborder-block-start&border-block-endorborder-inline-start&border-inline-end, respectively, both to the same style.

4.6.Flow-Relative Corner Rounding: theborder-start-start-radius,border-start-end-radius,border-end-start-radius,border-end-end-radiusproperties

These properties correspond to theborder-top-left-radius,border-bottom-left-radius,border-top-right-radius,andborder-bottom-right-radiusproperties. The mapping depends on the element’swriting-mode,direction,andtext-orientation, with the first start/end giving the block axis side, and the second the inline-axis side (i.e. patterned as 'border-block-inline-radius').

4.7.Four-Directional Shorthand Properties: themargin,padding,border-width,border-style,andborder-colorshorthands

The shorthand properties for margin, padding, and border set values for physical properties by default. But authors can specify thelogicalkeyword at the beginning of the property value to indicate that the values map to the flow-relative properties instead of the physical ones.

The proposed syntax for this feature isunder discussionand is almost guaranteed to change from what is described here. This section remains in the draft to promote discussion of alternatives, to document the affected properties, and to specify the expected impact on the interpretation of whatever syntactic switch is ultimately chosen.

The following[CSS2]shorthand properties accept thelogicalkeyword:

• inset
• margin
• padding
• border-width
• border-style
• border-color
• scroll-padding
• scroll-margin

The syntax for these properties is effectively changed by replacing

<value-type>{1,4}

with

logical?<value-type>{1,4}

When thelogicalkeyword is present in the value, the values that follow are assigned to its flow-relative longhands as follows:

• If only one value is set, the value applies to all four flow-relativelonghands.
• If two values are set, the first is for block-start and block-end, the second is for inline-start and inline-end.
• If three values are set, the first is for block-start, the second is for inline-start and inline-end, and the third is for block-end.
• If four values are set, they apply to the block-start, inline-start, block-end, and inline-end sides in that order.

blockquote{
margin:logical1em2em3em4em;
}
blockquote{
margin-block-start:1em;
margin-inline-start:2em;
margin-block-end:3em;
margin-inline-end:4em;
}

5.Acknowledgements

Cameron McCormack, David Baron, Oriol Brufau, Shinyu Murakami, Tab Atkins

6.Changes

Changes since theprevious Working Draftinclude:

• Miscellaneous minor clarifications

Changes between the earlier Editors Drafts and the18 May 2017 First Public Working Draftinclude:

• Making all properties cascade using thewriting modespecified on the element, not on its parent.
• Making the ordering of longhands withinmargin-like shorthands put inline-start before inline-end.
• Adding the*-inlineand*-blockshorthand forms for margins/borders/padding.
• Renaming theoffset-*properties toinset-*and marking an issue for discussion.
• Adding an Introduction section.
• Updating to current terminology of CSS Writing Modes.
• Miscellaneous prose cleanup.

Privacy Considerations

No new privacy considerations have been reported on this specification.

Security Considerations

No new security considerations have been reported on this specification.