CSS Device Adaptation Module Level 1

1. Introduction

This section is not normative.

CSS 2.1 [CSS21] specifies an initial containing block for continuous media that has the dimensions of the viewport. Mobile/handheld device browsers have a viewport that is generally a lot narrower than a desktop browser window at a zoom level that gives a CSS pixel size recommended by CSS 2.1.

The narrow viewport is a problem for documents designed to look good in desktop browsers. The result is that mobile browser vendors use a fixed initial containing block size that is different from the viewport size, and close to that of a typical desktop browser window. In addition to scrolling or panning, zooming is often used to change between an overview of the document and zoom in on particular areas of the document to read and interact with.

Certain DOCTYPEs (for instance XHTML Mobile Profile) are used to recognize mobile documents which are assumed to be designed for handheld devices, hence using the viewport size as the initial containing block size.

Additionally, an HTML <META> tag has been introduced for allowing an author to specify the size of the initial containing block, and the initial zoom factor directly. It was first implemented by Apple for the Safari/iPhone browser, but has since been implemented for the Opera, Android, and Fennec browsers. These implementations are not fully interoperable and this specification is an attempt at standardizing the functionality provided by the viewport <META> tag in CSS.

This specification is written from an implementation centric point of view, making it arguably difficult to read. Significant editorial work may be needed to make it more understandable to different audiences. It also should clarify which viewport is referred to by various js APIs. See this blog post by ppk for a good discussion of these issues.

2. Values

This specification follows the CSS property definition conventions from [CSS3SYN].

Value types are defined in [CSS3VAL].

3. The viewport

In CSS 2.1 a viewport is a feature of a user agent for continuous media and used to establish the initial containing block for continuous media. For paged media, the initial containing block is based on the page area. The page area can be set through @page rules. Hence, @viewport applies to continuous media, and @page to paged media, and they will not interact or conflict.

This specification introduces a way of overriding the size of the viewport provided by the user agent (UA). Because of this, we need to introduce the difference between the initial viewport and the actual viewport.

initial viewport: This refers to the viewport before any UA or author styles have overridden the viewport given by the window or viewing area of the UA. Note that the initial viewport size will change with the size of the window or viewing area.
actual viewport: This is the viewport you get after the cascaded viewport descriptors, and the following constraining procedure have been applied.

When the actual viewport cannot fit inside the window or viewing area, either because the actual viewport is larger than the initial viewport or the zoom factor causes only parts of the actual viewport to be visible, the UA should offer a scrolling or panning mechanism.

It is recommended that initially the upper-left corners of the actual viewport and the window or viewing area are aligned if the base direction of the document is ltr. Similarly, that the upper-right corners are aligned when the base direction is rtl. The base direction for a document is defined as the computed value of the direction property for the first <BODY> element of an HTML or XHTML document. For other document types, it is the computed direction for the root element.

"dbaron: The question is, what does this do on the desktop browser? (And what’s a desktop browser)". Need to say that a "desktop" browser typically have no UA styles, as opposed to the UA stylesheet outlined for current mobile behaviour, and that no UA styles for @viewport will give "desktop" behaviour per default (actual viewport is initial viewport).

4. The @viewport rule

The @viewport at-rule consists of the @-keyword followed by a block of descriptors describing the viewport.

The descriptors inside an @viewport rule are per document and there is no inheritance involved. Hence declarations using the inherit keyword will be dropped. They work similarly to @page descriptors and follow the cascading order of CSS. Hence, descriptors in @viewport rules will override descriptors from preceding rules. The declarations allow !important which will affect cascading of descriptors accordingly.

@viewport rules apply to top level documents only.

This example sets the viewport to at least 320px, but otherwise match window width if it is wider than 320px. Note that it is enough to set the width as the height will be resolved from the width when auto.

@viewport {
    width: 320px auto;
}

4.1. Syntax

The syntax for the @viewport rule is as follows (using the notation from the Grammar appendix of CSS 2.1 [CSS21]):

viewport
  : VIEWPORT_SYM S* '{' S* declaration? [ ';' S* declaration? ]* '}' S*
  ;

with the new token:

@{V}{I}{E}{W}{P}{O}{R}{T} {return VIEWPORT_SYM;}

where:

V    v|\\0{0,4}(56|76)(\r\n|[ \t\r\n\f])?|\\v
W    w|\\0{0,4}(57|77)(\r\n|[ \t\r\n\f])?|\\w

The viewport non-terminal is added to the stylesheet production along with the ruleset, media, and page non-terminals:

stylesheet
  : [ CHARSET_SYM STRING ';' ]?
    [S|CDO|CDC]* [ import [ CDO S* | CDC S* ]* ]*
    [ [ ruleset | media | page | viewport ] [ CDO S* | CDC S* ]* ]*
  ;

It is also added to the nested_statement production defined in [CSS3-CONDITIONAL] to allow @viewport rules nested inside conditional group rules such as @media or @supports:

nested_statement
  : ruleset | media | page | font_face_rule | keyframes_rule |
    supports_rule | viewport
  ;

5. Viewport descriptors

This section presents the descriptors that are allowed inside an @viewport rule. Other descriptors than those listed here will be dropped.

Relative length values are resolved against initial values. For instance 'em’s are resolved against the initial value of the font-size property. Viewport lengths (vw, vh, vmin, vmax) are relative to the initial viewport.

5.1. The min-width and max-width descriptors

min- and max- functionality can be achieved with media queries, should these be removed?

Name:	min-width
For:	@viewport
Value:	<viewport-length>
Initial:	auto
Percentages:	Refer to the width of the initial viewport
Media:	visual, continuous
Computed value:	auto, an absolute length, or a percentage as specified

Name:	max-width
For:	@viewport
Value:	<viewport-length>
Initial:	auto
Percentages:	Refer to the width of the initial viewport
Media:	visual, continuous
Computed value:	auto, an absolute length, or a percentage as specified

Specifies the minimum and maximum width of the viewport that is used to set the size of the initial containing block where

<viewport-length> = auto | <length> | <percentage>

and the values have the following meanings:

auto: The used value is calculated from the other descriptors' values according to the constraining procedure.
The user-agent stylesheets recommended in the informative section don’t adequately represent current implementation behaviors. Should there be a more explicit mechanism for switching between UA default behavior and requesting the CSS pixel?
<length>: A non-negative absolute or relative length.
<percentage>: A percentage value relative to the width or height of the initial viewport at zoom factor 1.0, for horizontal and vertical lengths respectively. Must be non-negative.

The min-width and max-width descriptors are inputs to the constraining procedure. The width will initially be set as close as possible to the ''initial viewport'' width within the min/max constraints.

5.2. The width shorthand descriptor

Name:	width
For:	@viewport
Value:	<viewport-length>{1,2}
Initial:	See individual descriptors
Percentages:	See individual descriptors
Media:	visual, continuous
Computed value:	See individual descriptors

This is a shorthand descriptor for setting both min-width and max-width. One <viewport-length> value will set both min-width and max-width to that value. Two <viewport-length> values will set min-width to the first and max-width to the second.

5.3. The min-height and max-height descriptors

Name:	min-height
For:	@viewport
Value:	<viewport-length>
Initial:	auto
Percentages:	Refer to the height of the initial viewport
Media:	visual, continuous
Computed value:	auto, an absolute length, or a percentage as specified

Name:	max-height
For:	@viewport
Value:	<viewport-length>
Initial:	auto
Percentages:	Refer to the height of the initial viewport
Media:	visual, continuous
Computed value:	auto, an absolute length, or a percentage as specified

Specifies the minimum and maximum height of the viewport that is used to set the size of the initial containing block.

The min-height and max-height descriptors are inputs to the constraining procedure. The height will initially be set as close as possible to the ''initial viewport'' height within the min/max constraints.

5.4. The height shorthand descriptor

Name:	height
For:	@viewport
Value:	<viewport-length>{1,2}
Initial:	See individual descriptors
Percentages:	See individual descriptors
Media:	visual, continuous
Computed value:	See individual descriptors

This is a shorthand descriptor for setting both min-height and max-height. One <viewport-length> value will set both min-height and max-height to that value. Two <viewport-length> values will set min-height to the first and max-height to the second.

5.5. The zoom descriptor

Name:	zoom
For:	@viewport
Value:	auto \| <number> \| <percentage>
Initial:	auto
Percentages:	The zoom factor itself
Media:	visual, continuous
Computed value:	auto, or a non-negative number or percentage as specified

Specifies the initial zoom factor for the window or viewing area. This is a magnifying glass type of zoom. Interactively changing the zoom factor from the initial zoom factor does not affect the size of the initial or the actual viewport.