CSS Backgrounds and Borders Module Level 4

1. Introduction

This module is currently maintained as a diff against Level 3. We will fold in the text once it’s all formatted up and in CR again, as this will reduce the effort of keeping them in sync (source diffs will be accurate in reflecting the differences).

2. Backgrounds

2.1. Background Positioning: the background-position shorthand property

Name:	background-position
Value:	<bg-position>#
Initial:	see individual properties
Applies to:	see individual properties
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

See [CSS3BG] for definition.

Where

<bg-position> = [  [ left | center | right | top | bottom | start | end | <length-percentage> ]
|
  [ left | center | right | x-start | x-end | <length-percentage> ]
  [ top | center | bottom | y-start | y-end | <length-percentage> ]
|
  [ center | [ left | right | x-start | x-end ] <length-percentage>? ] &&
  [ center | [ top | bottom | y-start | y-end ] <length-percentage>? ]
|
  [ center | [ start | end ] <length-percentage>? ]
  [ center | [ start | end ] <length-percentage>? ]  ]

Values have the following meanings:

One value: If only one value is given, and that value is start or end, then the keyword is duplicated; otherwise the second keyword defaults to center. The resulting value is treated as a two-component value.
More than one value: If the value contains a start or end keyword, then the shorthand sets background-position-inline and background-position-block to the specified values. Otherwise the shorthand sets background-position-x and background-position-y to the specified values.
Specify the value assignment in more detail. Should expand just like Level 3.

Specify what happens to set of properties that are not set. Maybe they’re just not set?

2.1.1. Background Positioning Longhands: the background-position-x, background-position-y, background-position-inline, and background-position-block properties

This section is still being worked out. The tricky thing is making all the start/end keywords work sanely.

Name:	background-position-x
Value:	[ center \| [ [ left \| right \| x-start \| x-end ]? <length-percentage>? ]! ]#
Initial:	0%
Applies to:	all elements
Inherited:	no
Percentages:	refer to width of background positioning area minus width of background image
Computed value:	A list, each item consisting of: an offset given as a computed <length-percentage> value, plus an origin keyword
Canonical order:	per grammar
Animation type:	repeatable list
Logical property group:	background-position

This property specifies the background position’s horizontal component. An omitted origin keyword is assumed to be left.

Name:	background-position-y
Value:	[ center \| [ [ top \| bottom \| y-start \| y-end ]? <length-percentage>? ]! ]#
Initial:	0%
Applies to:	all elements
Inherited:	no
Percentages:	refer to height of background positioning area minus height of background image
Computed value:	A list, each item consisting of: an offset given as a computed <length-percentage> value, plus an origin keyword
Canonical order:	per grammar
Animation type:	repeatable list
Logical property group:	background-position

This property specifies the background position’s vertical component. An omitted origin keyword is assumed to be top.

Name:	background-position-inline
Value:	[ center \| [ start \| end ]? <length-percentage>? ]#
Initial:	0%
Applies to:	all elements
Inherited:	no
Percentages:	refer to inline-size of background positioning area minus inline-size of background image
Computed value:	A list, each item consisting of: an offset given as a computed <length-percentage> value, plus an origin keyword
Canonical order:	per grammar
Animation type:	repeatable list
Logical property group:	background-position

This property specifies the background position’s inline-axis component. An omitted origin keyword is assumed to be start.

Name:	background-position-block
Value:	[ center \| [ start \| end ]? <length-percentage>? ]#
Initial:	0%
Applies to:	all elements
Inherited:	no
Percentages:	refer to size of background positioning area minus size of background image
Computed value:	A list, each item consisting of: an offset given as a computed <length-percentage> value, plus an origin keyword
Canonical order:	per grammar
Animation type:	repeatable list
Logical property group:	background-position

This property specifies the background position’s block-axis component. An omitted origin keyword is assumed to be start.

2.2. Painting Area: the background-clip property

Name:	background-clip
Value:	<bg-clip>#
Initial:	border-box
Applies to:	all elements
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	repeatable list

Determines the background painting area, which determines the area within which the background is painted. The syntax of the property is given with

<bg-clip> = <box> | border | text

Or should this be defining the -webkit-background-clip property, saying that all the values are identical, with this additional text value?

<box>: The background is painted within (clipped to) the specified box of the element.
text: The background is painted within (clipped to) the intersection of the border box and the geometry of the text in the element and its in-flow and floated descendants.
border: The background is clipped to the area painted by the border, taking border-width and border-style into account but ignoring any transparency introduced by border-color.

3. Borders

3.1. Line Colors: the border-color properties

Name:	border-top-color, border-right-color, border-bottom-color, border-left-color
Value:	<color> \| <image-1D>
Initial:	currentcolor
Applies to:	all elements
Inherited:	no
Percentages:	n/a
Computed value:	the computed color and/or a one-dimensional image function
Canonical order:	per grammar
Animation type:	see prose
Logical property group:	border-color

Name:	border-color
Value:	[ <color> \| <image-1D> ]{1,4}
Initial:	see individual properties
Applies to:	see individual properties
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

These properties set the foreground color of the border specified by the border-style properties.

The stripes defined by <image-1D> follow the shape of the border on the side to which they apply, and are drawn in bands starting from the padding edge and progressing outwards. The border width at each point defines the total width of the stripes at that point.

border-color is a shorthand for the four border-*-color properties. The four values set the top, right, bottom and left border, respectively. A missing left is the same as right, a missing bottom is the same as top, and a missing right is also the same as top. This is resolved individually for each list item.

Using multiple colors for each side:

.foo {
  border: 30px solid;
  border-color: stripes(dodgerblue, skyblue) stripes(yellow, gold) stripes(lightgreen, limegreen) stripes(indianred, orange);
}

Sample rendering:

The same border colors with border-style: dotted:

The syntax for comma-separated multiple colors is still under active discussion in the CSS WG.

4. Corners

4.1. Corner Sizing: the border-radius and border-*-radius shorthand properties

4.1.1. Sizing The Corners Of One Side: The border-top-radius, border-right-radius, border-bottom-radius, border-left-radius, border-block-start-radius, border-block-end-radius, border-inline-start-radius, border-inline-end-radius shorthands

Name:	border-top-radius, border-right-radius, border-bottom-radius, border-left-radius, border-block-start-radius, border-block-end-radius, border-inline-start-radius, border-inline-end-radius
Value:	<length-percentage [0,∞]>{1,2} [ / <length-percentage [0,∞]>{1,2} ]?
Initial:	0
Applies to:	all elements (but see prose)
Inherited:	no
Percentages:	Refer to corresponding dimension of the border box.
Computed value:	see individual properties
Canonical order:	per grammar
Animatable:	see individual properties

The border-*-radius shorthands set the two border-*-*-radius longhand properties of the related side. If values are given before and after the slash, then the values before the slash set the horizontal radius and the values after the slash set the vertical radius. If there is no slash, then the values set both radii equally. The two values for the radii are given in the order top-left, top-right for border-top-radius, top-right, bottom-right for border-right-radius, bottom-left, bottom-right for border-bottom-radius, top-left, bottom-left for border-left-radius, start-start, start-end for border-block-start-radius, end-start, end-end for border-block-end-radius start-start, end-start for border-inline-start-radius, and start-end, end-end for border-inline-end-radius. If the second value is omitted it is copied from the first.

4.1.2. Sizing All Corners At Once: The border-radius shorthand

Name:	border-radius
Value:	<length-percentage [0,∞]>{1,4} [ / <length-percentage [0,∞]>{1,4} ]?
Initial:	0
Applies to:	all elements, except table element when border-collapse is collapse
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	see individual properties

See [CSS3BG].

4.2. Corner Shaping: the corner-shape property

Name:	corner-shape
Value:	[ round \| angle ]{1,4}
Initial:	round
Applies to:	all elements, except table element when border-collapse is collapse
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	discrete

By default, non-zero border-radii define a quarter-ellipse that rounds the affected corners. However in some cases, other corner shapes are desired. The corner-shape property specifies a reinterpretation of the radii to define other corner shapes.

round: Border radii define a convex elliptical curve at the corner.
angle: Border radii define a diagonal slice at the corner.

For example, the following declarations create a right-pointing next button.

a {
  border-radius: .3em .8em .8em .3em / .3em 50% 50% .3em;
  corner-shape: round angle angle round;
  padding: .5em 1em .5em .5em;
}

As a fallback in UAs that don’t support border-radius, the right side would be rounded rather than pointy:

How to allow custom corners? Perhaps a path() function? Or a cubic-bezier()? Something else?

4.3. Corner Shape and Size: the corners shorthand

Name:	corners
Value:	<'corner-shape'> \|\| <'border-radius'>
Initial:	see individual properties
Applies to:	see individual properties
Inherited:	see individual properties
Percentages:	see individual properties
Computed value:	see individual properties
Animation type:	see individual properties
Canonical order:	per grammar

The corners shorthand sets corner-shape and border-radius in the same declaration. If either is omitted, it is reset to its initial value.

For example, the following declaration creates a diamond shape.

corners: angle 50%;

In UAs that don’t support corner-shape, the declaration is ignored (falls back to a rectangle).

In this example, the first declaration creates tabs with vertical sides and rounded corners using border-radius, while the second example makes them trapezoid-shaped in UAs that support corners.

border-radius: 0.25em 0.25em 0 0;
corners: angle 0.25em 0.25em 0 0 / 50% 50% 0 0;

5. Partial borders

CSS borders traditionally cover an entire border edge. Sometimes, however, it can be useful to hide some parts of the border.

Here are two proposals for doing this: the second one is from GCPM, the first one is an attempt to recast it more readably. The names are terrible, known problem, proposals accepted. There is a problem with conceiving this as clipping: if you have dotted borders, you want whole dots always, not parts of dots. So it should be a drawing limit, not a clip.

5.1. Partial Borders: the border-limit property

Name:	border-limit
Value:	all \| [ sides \| corners ] <length-percentage [0,∞]>? \| [ top \| right \| bottom \| left ] <length-percentage [0,∞]>
Initial:	all
Applies to:	all elements, except table element when border-collapse is collapse
Inherited:	no
Percentages:	relative to border-box
Computed value:	as specified
Canonical order:	per grammar
Animation type:	discrete

By default, the entire border is drawn. However, border rendering can be limited to only part of a border. The keyword specifies which part, and the length or percentage specifies how much.

all: The entire border is drawn.
sides: The sides are drawn up to but not including the corners (as defined by the border radii). A length or percentage is measured from the center of each side: 50% draws the middle 50% of the border; by default the entire side is drawn.
corners: The corners are drawn plus the specified distance into the sides if specified. A length is measured from the closest edge of the corner area. A percentage is measured from the absolute corner of the border box.
left
right: For the left and right (vertical) sides, draws the entire side and corner. For the top and bottom (horizontal) sides, draws the left/right portion, as specified. Distances are measured as for corners.
top
bottom: For the top and bottom (horizontal) sides, draws the entire side and corner. For the left and right (vertical) sides, draws the top/bottom portion, as specified. Distances are measured as for corners.

The following example draws only the middle 50% of the sides.

box { border: solid; border-parts: sides 50% }

The following example draws only the curved parts of the corners.

box { border: solid; border-radius: 1em 2em; border-parts: corners; }

The following example draws only the left 4em of the top border.

box { border-top: solid; border-parts: left 4em; }

The following example draws only the first 10px of each corner:

box { border: solid; border-parts: corners 10px; }

The following example draws the curved part of the corner plus 5px along the sides:

box { border: solid; border-radius: 5px; border-shape: round; border-parts: corners 5px; }

The following example draws the curved part of the corner and all of the side except the middle 40%.

box { border: solid; border-radius: 5px; border-shape: round; border-parts: corners 30%; }

5.2. The border-clip properties

Name:	border-clip, border-clip-top, border-clip-right, border-clip-bottom, border-clip-left
Value:	normal \| [ <length-percentage [0,∞]> \| <flex> ]+
Initial:	normal
Applies to:	all elements
Inherited:	no
Percentages:	refer to length of border-edge side
Computed value:	normal, or a list consisting of absolute lengths, or percentages as specified
Canonical order:	per grammar
Animation type:	by computed value

Should these properties be simplified to only accept normal | <length-percentage>+?

These properties split their respective borders into parts along the border edge. The first part is visible, the second is invisible, the third part is visible, etc. Parts can be specified with lengths, percentages, or flexible lengths (expressed by the fr unit, as per [CSS3GRID]). The normal value means that the border is not split, but shown normally.

border-clip is a shorthand property for the four individual properties.

If the listed parts are shorter than the border, any remaining border is split proportionally between the specified flexible lengths. If there are no flexible lengths, the behavior is as if 1fr had been specified at the end of the list.

If the listed parts are longer than the border, the specified parts will be shown in full until the end of the border. In this case, all flexible lengths will be zero.

For horizontal borders, parts are listed from left to right. For vertical borders, parts are listed from top to bottom.

The exact border parts are determined by laying out the specified border parts with all flexible lengths initially set to zero. Any remaining border is split proportionally between the flexible lengths specified.

border-clip: 10px 1fr 10px;

border-clip-top: 10px 1fr 10px;
border-clip-bottom: 10px 1fr 10px;
border-clip-right: 5px 1fr 5px;
border-clip-left: 5px 1fr 5px;

By making the first part have zero length, the inverse border of the previous example can easily be created:

border-clip-top: 0 10px 1fr 10px;
border-clip-bottom: 0 10px 1fr 10px;
border-clip-right: 0 5px 1fr 5px;
border-clip-left: 0 5px 1fr 5px;

border: thin solid black;
border-clip: 0 1fr; /* hide borders */
border-clip-top: 10px 1fr 10px; /* make certain borders visible */
border-clip-bottom: 10px 1fr 10px;

border-top: thin solid black;
border-bottom: thin solid black;
border-clip-top: 10px;
border-clip-bottom: 10px;

border-top: thin solid black;
border-clip: 10px;

This rendering:

A sentence consists of words¹.

¹ Most often.

can be achieved with this style sheet:

@footnote {
  border-top: thin solid black;
  border-clip: 4em;
}

border: 2px solid black;
border-top-parts: repeat(10px 10px);

In this example, the repeat pattern is shown five times and there is, by coincidence, no remaining border.

border: 2px solid black;
border-top-parts: repeat(10px 10px);

In this example, the repeat pattern is shown five times. The box in this example is slightly wider than the box in the previous example. The remaining border is taken up by a flexible length, as if this code had been specified:

border: 2px solid black;
border-top-parts: repeat(10px 10px) 1fr;

The fragment is shown in red for illustrative purposes; it should be shown in black by a compliant UA.

border: 4px solid black;
border-top-parts: 40px 20px 0 1fr repeat(20px 20px) 0 1fr 40px;

In this example, there will be a visible 40px border part on each end of the top border. Inside the 40px border parts, there will be an invisible border part of at least 20px. Inside these invisible border parts, there will be visible border parts, each 20px long with 20px invisible border parts between them.

The fragments are shown in red for illustrative purposes; they should not be visible in compliant UAs.

border: 4px solid black;
border-top-parts: 40px 20px 0 1fr 20px 20px 0 1fr 40px;

The fragments are shown in red for illustrative purposes; they should not be visible in compliant UAs.

border: 4px solid black;
border-clip-top: 3fr 10px 2fr 10px 1fr 10px 10px 10px 1fr 10px 2fr 10px 3fr;

All but one of the visible border parts are represented as flexible lengths in this example. The length of these border parts will change when the width of the element changes. Here is one rendering where 1fr ends up being 10px:

Here is another rendering where 1fr ends up being 30px:

The fragments are shown in red for illustrative purposes; they should be black in compliant UAs.

6. Drop Shadows

6.1. Coloring shadows: the box-shadow-color property

Name:	box-shadow-color
Value:	<color>#
Initial:	currentcolor
Applies to:	all elements
Inherited:	no
Percentages:	N/A
Computed value:	list, each item a computed color
Canonical order:	per grammar
Animatable:	by computed value

The box-shadow-color property defines one or more drop shadow colors. The property accepts a comma-separated list of shadow colors.

See the section “Layering, Layout, and Other Details” for how box-shadow-color interacts with other comma-separated drop shadow properties to form each drop shadow layer.

6.2. Offsetting shadows: the box-shadow-offset property

Name:	box-shadow-offset
Value:	[ none \| <length>{2} ]#
Initial:	none
Applies to:	all elements
Inherited:	no
Percentages:	N/A
Computed value:	either none or a list, each item a pair of offsets (horizontal and vertical) from the element‘s box
Canonical order:	per grammar
Animatable:	by computed value

The box-shadow-offset property defines one or more drop shadow offsets. The property accepts a comma-separated list of horizontal and vertical offset pairs, where both values are described as <length> values.

1st <length>: Specifies the horizontal offset of the shadow. A positive value draws a shadow that is offset to the right of the box, a negative length to the left.
2nd <length>: Specifies the vertical offset of the shadow. A positive value offsets the shadow down, a negative one up.

See the section “Layering, Layout, and Other Details” for how box-shadow-offset interacts with other comma-separated drop shadow properties to form each drop shadow layer.

6.3. Blurring shadows: the box-shadow-blur property

Name:	box-shadow-blur
Value:	<length [0,∞]>#
Initial:	0
Applies to:	all elements
Inherited:	no
Percentages:	N/A
Computed value:	list, each item a <length>
Canonical order:	per grammar
Animatable:	by computed value

The box-shadow-blur property defines one or more blur radii for drop shadows. The property accepts a comma-separated list of <length> values.

Negative values are invalid. If the blur value is zero, the shadow’s edge is sharp. Otherwise, the larger the value, the more the shadow’s edge is blurred. See Shadow Blurring, below.

See the section “Layering, Layout, and Other Details” for how box-shadow-blur interacts with other comma-separated drop shadow properties to form each drop shadow layer.

6.4. Spreading shadows: the box-shadow-spread property

Name:	box-shadow-spread
Value:	<length>#
Initial:	0
Applies to:	all elements
Inherited:	no
Percentages:	N/A
Computed value:	list, each item a <length>
Canonical order:	per grammar
Animatable:	by computed value

The box-shadow-spread property defines one or more spread distances for drop shadows. The property accepts a comma-separated list of <length> values.

Positive values cause the shadow to expand in all directions by the specified radius. Negative values cause the shadow to contract. See Shadow Shape, below.

Note that for inner shadows, expanding the shadow (creating more shadow area) means contracting the shadow’s perimeter shape.

See the section “Layering, Layout, and Other Details” for how box-shadow-spread interacts with other comma-separated drop shadow properties to form each drop shadow layer.

6.5. Spreading shadows: the box-shadow-position property

Name:	box-shadow-position
Value:	[ outset \| inset ]#
Initial:	outset
Applies to:	all elements
Inherited:	no
Percentages:	N/A
Computed value:	list, each item one of the keywords
Canonical order:	per grammar
Animatable:	by computed value

The box-shadow-position property defines one or more drop shadow positions. The property accepts a comma-separated list of outset and inset keywords.

outset: Causes the drop shadow to be an outer box-shadow. That means, one that shadows the box onto the canvas, as if it were lifted above the canvas.
inset: Causes the drop shadow to be an inner box-shadow. That means, one that shadows the canvas onto the box, as if the box were cut out of the canvas and shifted behind it.

See the section “Layering, Layout, and Other Details” for how box-shadow-position interacts with other comma-separated drop shadow properties to form each drop shadow layer.

6.6. Drop Shadows Shorthand: the box-shadow property

Name:	box-shadow
Value:	<spread-shadow>#
Initial:	none
Applies to:	all elements
Inherited:	no
Percentages:	N/A
Computed value:	either the keyword none or a list, each item consisting of four absolute lengths plus a computed color and optionally also a inset keyword
Canonical order:	per grammar
Animatable:	by computed value, treating none as a zero-item list and appending blank shadows (transparent 0 0 0 0) with a corresponding inset keyword as needed to match the longer list if the shorter list is otherwise compatible with the longer one

The box-shadow property attaches one or more drop-shadows to the box. The property accepts either the none value, which indicates no shadows, or a comma-separated list of shadows, ordered front to back.

Each shadow is given as a <spread-shadow>, outlining the box-shadow-offset, and optional values for the box-shadow-blur, box-shadow-spread, box-shadow-color, and box-shadow-position. Omitted lengths are 0; omitted colors default to the currentcolor value.

<spread-shadow> = <'box-shadow-color'>? && [ <'box-shadow-offset'> [ <'box-shadow-blur'> <'box-shadow-spread'>? ]? ] && <'box-shadow-position'>?

7. Changes

7.1. Additions Since Level 3

Additions are a work in progress... here’s what we’re planning to add. :)

logical background-position values (start, end)
the extend keyword of background-repeat
corner-shape
<image-1D> as value for border-color and its longhands
multiple border colors per border
logical border properties
Partial Borders (make part of border shorthand as well!)
More border-radius shorthands for doing both corners on a side at once.
Splitting horizontal / vertical spread radius for box-shadow, if we can come up with a sane syntax for it.

8. Acknowledgments

In addition to the many contributors to the [CSS1], [CSS21], and [CSS3BG] predecessors to this module, the editors would like to thank Tab Atkins, and Håkon Wium Lie for their suggestions and feedback specifically for this Level 4.

Conformance

Document conventions

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:

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

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

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.

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 component 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

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

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 public-css-testsuite@w3.org mailing list.