From 75ca0fc4e9fac3053aef78e65effd334e19c053f Mon Sep 17 00:00:00 2001 From: Estelle Weyl Date: Tue, 19 Dec 2023 06:27:47 -0800 Subject: [PATCH] CSS syntax module and error handling (#31076) * New page: CSS syntax error handling * deprecate @charset and list as a rule not at-rule * Define character encoding * New page: error handling * New page: css syntax module * delete charset module. move to syntax module * still supported * table of contents * better grammar * better grammar * better grammar * better grammar * Apply suggestions from code review Co-authored-by: Dipika Bhattacharya * added a few more notes - prefixes * edits per review * change h2 to h3 * Apply suggestions from code review Co-authored-by: Dipika Bhattacharya * add guide to module page. * change UA to browser * address https://github.com/mdn/content/pull/30793#discussion_r1421245493 * hyphens to underscores * rewrote the at-rule section * rewrite grammar section * fixing linter suggestions Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * final tweaks * Update files/en-us/web/css/css_syntax/error_handling/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/css/css_syntax/error_handling/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * fix flaws * closed comments * borked so fixed * trailing spaces Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/css/css_syntax/error_handling/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/css/css_syntax/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Small punctuation fixes * Apply suggestions from code review Co-authored-by: Chris Mills * header for at-rule * updates based on review feedback * link to display property * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/css/css_syntax/error_handling/index.md * Update files/en-us/web/css/css_syntax/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Fix broken links * typo fix --------- Co-authored-by: Dipika Bhattacharya Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Chris Mills --- files/en-us/_redirects.txt | 1 + files/en-us/_wikihistory.json | 8 +- files/en-us/web/css/@charset/index.md | 13 +- files/en-us/web/css/css_charsets/index.md | 24 --- .../css/css_syntax/error_handling/index.md | 201 ++++++++++++++++++ files/en-us/web/css/css_syntax/index.md | 105 +++++++++ files/en-us/web/css/custom-ident/index.md | 21 +- 7 files changed, 340 insertions(+), 33 deletions(-) delete mode 100644 files/en-us/web/css/css_charsets/index.md create mode 100644 files/en-us/web/css/css_syntax/error_handling/index.md create mode 100644 files/en-us/web/css/css_syntax/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 75fd70e55bbc2fc..ad11fd934dbd4cb 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -11472,6 +11472,7 @@ /en-US/docs/Web/CSS/CSS_User_Interface /en-US/docs/Web/CSS/CSS_basic_user_interface /en-US/docs/Web/CSS/CSS_Variables /en-US/docs/Web/CSS/CSS_cascading_variables /en-US/docs/Web/CSS/CSS_Viewport /en-US/docs/Web/CSS +/en-US/docs/Web/CSS/CSS_charsets /en-US/docs/Web/CSS/CSS_syntax /en-US/docs/Web/CSS/CSS_descriptor_definition /en-US/docs/Web/CSS /en-US/docs/Web/CSS/CSS_flex-wrap /en-US/docs/Web/CSS/flex-wrap /en-US/docs/Web/CSS/CSS_grid_layout/Layout_using_line-based_placement /en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_line-based_placement diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index 6790b11fabc39ca..ae2efb4d23d96f6 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -77125,10 +77125,6 @@ "modified": "2020-07-07T12:03:44.891Z", "contributors": ["wbamberg", "mfluehr"] }, - "Web/CSS/CSS_charsets": { - "modified": "2020-10-15T21:38:35.251Z", - "contributors": ["wbamberg", "fscholz", "mfluehr", "Sebastianz", "teoli"] - }, "Web/CSS/CSS_colors": { "modified": "2020-12-02T11:04:05.642Z", "contributors": ["peterbe", "wbamberg", "fscholz", "Sheppy", "mfluehr"] @@ -78501,6 +78497,10 @@ "modified": "2020-04-27T22:31:21.929Z", "contributors": ["ExE-Boss", "mfuji09", "rachelandrew"] }, + "Web/CSS/CSS_syntax": { + "modified": "2020-10-15T21:38:35.251Z", + "contributors": ["wbamberg", "fscholz", "mfluehr", "Sebastianz", "teoli"] + }, "Web/CSS/CSS_table": { "modified": "2020-07-07T12:26:58.542Z", "contributors": ["wbamberg", "fscholz", "mfluehr", "Sebastianz", "teoli"] diff --git a/files/en-us/web/css/@charset/index.md b/files/en-us/web/css/@charset/index.md index 1dc70ae3725a5e2..f27fb1cfbb13cc1 100644 --- a/files/en-us/web/css/@charset/index.md +++ b/files/en-us/web/css/@charset/index.md @@ -7,7 +7,14 @@ browser-compat: css.at-rules.charset {{CSSRef}} -The **`@charset`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/At-rule) specifies the character encoding used in the style sheet. It must be the first element in the style sheet and not be preceded by any character; as it is not a [nested statement](/en-US/docs/Web/CSS/Syntax#nested_statements), it cannot be used inside [conditional group at-rules](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). If several `@charset` at-rules are defined, only the first one is used, and it cannot be used inside a `style` attribute on an HTML element or inside the {{ HTMLElement("style") }} element where the character set of the HTML page is relevant. +The **`@charset`** [CSS](/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. Although the first character in `@charset` is the `@` symbol, it is not an [at-rule](/en-US/docs/Web/CSS/At-rule). The [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module deprecates this rule, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked, but it is [fully supported in all browsers](#browser_compatibility). + +The following assertions apply to valid `@charset` usage: + +- The `@charset` rule must be the first element in the style sheet and not be preceded by any character. +- `@charset` is not a [nested statement](/en-US/docs/Web/CSS/Syntax#nested_statements) and therefore cannot be used inside [conditional group at-rules](/en-US/docs/Web/CSS/At-rule#conditional_group_rules). +- If several `@charset` at-rules are defined, only the first one is used. +- `@charset` cannot be used inside a `style` attribute on an HTML element or inside the {{ HTMLElement("style") }} element where the character set of the HTML page is relevant. ```css @charset "utf-8"; @@ -15,13 +22,13 @@ The **`@charset`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/At-r This at-rule is useful when using non-{{Glossary("ASCII")}} characters in some CSS properties, like {{ cssxref("content") }}. -As there are several ways to define the character encoding of a style sheet, the browser will try the following methods in the following order (and stop as soon as one yields a result) : +As there are several ways to define the character encoding of a style sheet, the browser will try the following methods in the following order (and stop as soon as one yields a result): 1. The value of the [Unicode byte-order](https://en.wikipedia.org/wiki/Byte_order_mark) character placed at the beginning of the file. 2. The value given by the `charset` attribute of the `Content-Type:` HTTP header or the equivalent in the protocol used to serve the style sheet. 3. The `@charset` CSS at-rule. 4. Use the character encoding defined by the referring document: the `charset` attribute of the {{ HTMLElement("link") }} element. This method is obsolete and should not be used. -5. Assume that the document is UTF-8 +5. Assume that the document is UTF-8. ## Syntax diff --git a/files/en-us/web/css/css_charsets/index.md b/files/en-us/web/css/css_charsets/index.md deleted file mode 100644 index d730e25dc51d1ca..000000000000000 --- a/files/en-us/web/css/css_charsets/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: CSS charsets -slug: Web/CSS/CSS_charsets -page-type: css-module -browser-compat: css.at-rules.charset ---- - -{{CSSRef}} - -The **CSS charsets** module lets you specify the character set used in the style sheet. - -## Reference - -### At-rules - -- {{cssxref("@charset")}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md new file mode 100644 index 000000000000000..1390a8fd8364749 --- /dev/null +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -0,0 +1,201 @@ +--- +title: CSS syntax errors +slug: Web/CSS/CSS_syntax/Error_handling +page-type: guide +--- + +{{CSSRef}} + +When an error exists in CSS, such as an invalid value or a missing semicolon, instead of [throwing an error like in JavaScript](/en-US/docs/Web/JavaScript/Reference/Errors), the browser (or other user agent) will gracefully recover. Browsers don't provide CSS-related alerts or otherwise indicate errors have occurred in styles. They just discard invalid content and parse subsequent valid styles. This is a feature of CSS, not a bug. + +This guide discusses how CSS {{glossary("parser", "parsers")}} discard invalid CSS. + +## CSS parser errors + +When a CSS error is encountered, the browser's {{glossary("parser")}} ignores the line containing the errors, discarding the minimum amount of CSS code before returning to {{glossary("parse", "parsing")}} the CSS as normal. The "error recovery" is just the ignoring or skipping of invalid content. + +The fact that browsers ignore invalid code enables the use of new CSS features without worrying about anything being broken in older browsers. A browser may not recognize a new feature, but that is okay. The discarding of invalid content without throwing an error allows both old and new syntaxes to coexist in the same ruleset, although bear in mind that they should be specified in that order. For example: + +```css +div { + display: inline-flex; + display: inline flex; +} +``` + +The {{cssxref("display")}} property accepts both legacy single value and [multi-keyword syntax](/en-US/docs/Web/CSS/display/multi-keyword_syntax_of_display). Browsers will render the old syntax until they recognize the new syntax as valid, at which point the new syntax will override the old. If a user has an old browser, the valid fallback won't get overwritten by the new CSS, because the browser perceives it as invalid. + +The type and amount of CSS that a browser ignores due to an error depends on the type of error. Some common error situations are listed below: + +- For [errors in at-rules](#at-rule_errors), whether a single line or the entire at-rule is ignored (fails) depends on the at-rule and the type of error. +- If the [error is an invalid selector](#errors_in_selector_lists), the entire declaration block is ignored. +- An [error due to a missing semi-colon](#errors_within_css_declaration_blocks) between property declarations causes an invalid value, in which case, multiple property-value declarations are ignored. +- If the [error is a property name or value](#errors_within_css_declaration_blocks), such as an unrecognized property name or invalid data type, the property-value declaration is ignored. +- If the [error is due to a missing end-bracket](#errors_with_auto-closed_endings), the extent of what is ignored depends on the browser's ability to parse the error as nested CSS. + +After parsing each declaration, style rule, at-rule, and so on, the browser checks the parsed content against its expected [grammar](#grammar_check) for that construct. If the content does not match the expected grammar for that construct, the browser considers it invalid and ignores it. + +### At-rule errors + +The `@` symbol, known in CSS specifications as an ``, indicates the beginning of a CSS {{cssxref("at-rule")}}. Once an at-rule begins with the `@` symbol, nothing is considered invalid from the parser's standpoint. Everything up to the first semi-colon (`;`) or the opening curly brace (`{`) is part of the at-rule's prelude. The content of each at-rule is interpreted according to the grammar rules for that particular at-rule. + +Statement at-rules, such as {{cssxref("@import")}} and {{cssxref("@namespace")}} declarations, contain just a prelude. The semicolon ends the at-rule immediately for [regular at-rules](/en-US/docs/Web/CSS/At-rule#regular). If the contents of the prelude are invalid according to the grammar for that at-rule, the at-rule is ignored, with the browser continuing to parse CSS after it encounters the next semi-colon. For example, if an `@import` at-rule occurs after any CSS declaration other than `@charset`, `@layer` or other `@import` statements, the `@import` declaration is ignored. + +```css +@import "assets/fonts.css" layer(fonts); +@namespace svg url(http://www.w3.org/2000/svg); +``` + +If the parser encounters a curly brace (`{`) before a semi-colon is encountered, the at-rule is parsed as a block at-rule. Block at-rules, also called [nested at-rules](/en-US/docs/Web/CSS/At-rule#nested), like {{cssxref("@font-face")}} and {{cssxref("@keyframes")}}, contain a block of declarations surrounded by curly braces (`{}`). The opening curly brace informs the browser where the at-rule prelude ends and the at-rule's body starts. The parser looks forward, seeking matching blocks (content surrounded by `()`, `{}`, or `[]`) until it finds a closing curly brace (`}`) that isn't matched by any other curly braces: this closes the body of the at-rule. + +Different at-rules have different grammar rules, different (or no) descriptors, and different rules for what, if anything, will invalidate the entire at-rule. The expected grammar for [each at-rule](/en-US/docs/Web/CSS/At-rule) and how errors are handled are documented on the respective at-rule page. The handling of invalid content depends on the error. + +For example, the `@font-face` rule requires both a [`font-family`](/en-US/docs/Web/CSS/@font-face/font-family) and [`src`](/en-US/docs/Web/CSS/@font-face/src) descriptor. If either of these is omitted or invalid, the entire `@font-face` rule is invalid. Including an unrelated descriptor, any other valid font descriptor with an invalid value, or a property style declaration within the `@font-face` nested block will not invalidate the font declaration. As long as the font name and font source are included and valid, any invalid CSS within the at-rule is ignored, but the `@font-face` block is still parsed. + +While the grammar of the `@keyframe` at-rule is very different from the `@font-face` rule grammar, the type of error still impacts what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated are ignored in keyframe rules, but they don't impact other styles declared in the same keyframe selector block. Including an invalid keyframe selector (such as a percentage value less than `0%` or greater than `100%`, or a {{cssxref("number")}} omitting the `%`) invalidates the keyframe selector list and therefore the style block is ignored. An invalid keyframe selector only invalidates the invalid selector's style block; it does not invalidate the entire `@keyframe` declaration. Including styles between two keyframe selector blocks, on the other hand, will invalidate the entire `@keyframe` at-rule. + +Some at-rules are almost always valid. The {{cssxref("@layer")}} at-rule comes in both regular and nested forms. The `@layer` statement syntax contains just the prelude, ending with a semi-colon. Alternatively, the nested syntax has layer styles nested between curly braces coming after the prelude. Omitting a closing curly brace may be a logic error but is not a syntax error. In the case of a missing closing brace in `@layer`, any styles coming after where the closing brace should have been are parsed as being in the cascade layer defined in the at-rule's prelude. The CSS is valid as there are no syntax errors; nothing is discarded. A syntax error may cause the named or anonymous layer to be empty, but the layer is still created. + +### Errors in selector lists + +There are many ways you might make a mistake writing a selector, but only invalid selectors cause a selector list to be invalid (See [invalid selector list](/en-US/docs/Web/CSS/Selector_list#invalid_selector_list)). + +If you include a {{cssxref("class_selectors", "class")}}, {{cssxref("id_selectors", "id")}}, or {{cssxref("type_selectors", "type")}} selector for a class, id, or element (or custom element) that doesn't exist, it may be a logic error but it's not a syntax error. However, if you have a typo in a pseudo-class or a pseudo-element, it might create an invalid selector, which is an error the parser needs to address. + +If a selector list contains any invalid selectors, then the entire style block is ignored. There are exceptions: if the invalid selector is within an {{cssxref(":is")}} or {{cssxref(":where")}} pseudo-class (which accept [forgiving selector lists](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list)) or if the unknown selector is a [`-webkit-` prefixed pseudo-element](#-webkit-_exception), only the unknown selector is ignored as not matching anything. The selector list is not invalidated. + +Outside of these exceptions, a single invalid or unsupported selector in the selector list will invalidate the entire rule and the entire selector block will be ignored. The browser will then look for the closing curly brace and continue parsing from that point onwards. + +#### `-webkit-` exception + +Due to legacy issues from the overuse of browser-specific prefixes in selectors and [property names (and values)](#vendor-prefixes), browsers avoid excessive invalidation of selector lists by treating all [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) that start with a case-insensitive `-webkit-` prefix and don't end with `()` as valid. + +This means that a pseudo-element like `::-webkit-works-only-in-samsung` will not invalidate a selector list, regardless of which browser the code is running in. In such cases, the pseudo-element may not be recognized or supported by the browser, but it will not cause the entire selector list and its associated style block to be ignored. On the other hand, an unknown prefixed selector with a function notation of `::-webkit-imaginary-function()` will invalidate the entire selector list, and the browser will ignore the entire selector block. + +### Errors within CSS declaration blocks + +When it comes to CSS properties and values within a declaration block, if either the property or the value is invalid, that property-value pair is ignored and discarded. When a user agent parses or interprets a list of declarations, unknown syntax at any point causes the browser's parser to discard only the current declaration. It then continues parsing CSS after the next semicolon or closing curly bracket is encountered, whichever comes first. + +This example contains an error. The parser ignores the error (and the comments), seeks forward until it encounters a semi-colon, then restarts parsing: + +```css-nolint bad +p { +/* Invalid syntax due to missing semi-colon */ + border-color: red + background-color: green; + +/* Valid syntax but likely a logic error */ + border-width: 100vh; +} +``` + +The reason the first declaration in this selector block is invalid is because the semi-colon is missing and the declaration is not the last one in the selector block. The property missing the semi-colon is ignored, as is the property-value pair following it because the browser only continues parsing after a semi-colon or closing bracket is encountered. Specifically, the `border-color` value is parsed as `red background-color: green;` which is not a valid {{cssxref("<color>")}} value. + +The {{cssxref("border-width")}} value of `100vh` is likely a mistake, but it's not an error. As it is syntactically valid, it will be parsed and applied to the elements matching the selector. + +#### Vendor prefixes + +Vendor-prefixed property names and property values, when not understood by a browser, are treated as invalid and ignored. Only the individual rules containing an invalid property or value are ignored. The parser looks for the next semi-colon or closing curly brace and then continues parsing from there. + +You may come across legacy CSS that looks like the following: + +```css example-bad +/* Prefixed values */ +.wrapper { + display: -webkit-box; + display: -webkit-flex; + display: -ms-flexbox; + display: flex; + display: block flex; +} +/* Prefixed properties */ +.rounded { + -webkit-border-radius: 50%; + -moz-border-radius: 50%; + -ms-border-radius: 50%; + -o-border-radius: 50%; + border-radius: 50%; +} +``` + +In this example, the last declaration in each block is valid in all browsers — `display: flex;` and `border-radius: 50%;`. Because of the [cascade](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance#source_order) [order of appearance](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) rule, browsers will apply any prefixed declarations they understand, and then override those values with the standard unprefixed version. + +> **Note:** Avoid including prefixed properties or property values where possible. If you must use them, declare the prefixed versions before the non-prefixed version as shown above. + +### Errors with auto-closed endings + +If a stylesheet ends while a rule, declaration, function, string, or comment is still open, the parser will automatically close everything that was left unclosed. + +> **Note:** This is true of external style sheets, selector blocks within an HTML {{HTMLElement("style")}} element, and inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. + +If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out a `@keyframe` declaration before closing your {{htmlelement("style")}}, the animation is still valid. + +```html-nolint example-bad + +``` + +Here the `move` animation is valid. Failing to properly close CSS statements doesn't necessarily make the statements invalid. That said, do not take advantage of CSS's forgiving nature. Always close all of your statements and style blocks. It makes your CSS easier to read and maintain and ensures that the browser parses the CSS as you intended. + +#### Unclosed comments + +Unclosed comments are logic errors, not syntax errors. If a comment starts with `/*` but is not closed, all CSS code until a closing delimiter (`*/`) in a subsequent comment or the end of the stylesheet, whichever comes first, is part of the comment. While an unclosed comment does not invalidate your CSS, it causes the CSS following the opening delimiter (`/*`) to be ignored. + +```html example-bad + +

Parsed as HTML.

+``` + +In this example, the two CSS comments are not closed, but the closing `` tag closes the first comment and the `style` attribute's close quote closes the second comment. + +## Grammar check + +After parsing each declaration, style rule, at-rule, etc., the user agent checks to make sure the grammar follows the rules for that declaration. For example, if a property value is of the wrong data type or a descriptor is not valid for the at-rule being described, the content that does not match the expected grammar is deemed invalid and gets ignored. + +Each CSS property accepts specific data types. For example, the {{cssxref("background-color")}} property accepts either a valid {{cssxref("<color>")}} or a CSS global keyword. When the value assigned to a property is of the wrong type, such as `background-color: 45deg`, the declaration is invalid and therefore ignored. + +### Invalid custom properties + +Custom properties are generally considered valid when declared, but may create invalid CSS when accessed, i.e. they may be used as a value (via the {{cssxref("var")}} function) for a property that does not accept that value type. The browser parses each custom property when encountered without regard to where the property is consumed. + +Generally, when a property value is invalid, the declaration is ignored and the property falls back to the last valid value. Invalid computed custom property values, however, work slightly differently. + +When a `var()` substitution is invalid, the declaration is not ignored and the [initial](/en-US/docs/Web/CSS/initial_value) or [inherited](/en-US/docs/Web/CSS/Inheritance) value of the property is used instead. The property is set to a new value, but possibly not the expected one. + +Let's look at an example to illustrate this behavior: + +```css example-bad +:root { + --theme-color: 45deg; +} +body { + background-color: var(--theme-color); +} +``` + +In the above code, the custom property declaration is valid. The `background-color` declaration is also valid at compute time. However, when the browser substitutes the custom property in `var(--theme-color)` with `45deg` as a value of the `background-color` property, the grammar is invalid. An {{cssxref("angle")}} is not a valid `background-color` value. In this case, the declaration is not ignored as invalid. Rather, when a custom property is of the wrong type, if the property is inheritable, the value is inherited from its parent. If the property is not inheritable, the default initial value is used. In the case of `background-color`, the property value is not an inherited value, so the inital value of `transparent` is used. + +To better control the way custom properties fall back, use the {{cssxref("@property")}} at-rule to define the initial value of the property: + +```css example-good +@property --theme-color { + syntax: ""; + inherits: false; + initial-value: rebeccapurple; +} +``` + +## See also + +- [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module +- [Syntax](/en-US/docs/Web/CSS/Syntax) guide +- [Value definition syntax](/en-US/docs/Web/CSS/Value_definition_syntax) diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md new file mode 100644 index 000000000000000..254d3455c84f903 --- /dev/null +++ b/files/en-us/web/css/css_syntax/index.md @@ -0,0 +1,105 @@ +--- +title: CSS syntax +slug: Web/CSS/CSS_syntax +page-type: css-module +spec-urls: https://drafts.csswg.org/css-syntax +--- + +{{CSSRef}} + +The **CSS syntax** module describes, in general terms, the structure and syntax of cascading stylesheets, or CSS. It defines CSS as the language for describing the rendering of structured documents (such as HTML and XML), on the web and elsewhere. + +This module doesn't define any properties, [data types](/en-US/docs/Web/CSS/CSS_Types), [functions](/en-US/docs/Web/CSS/CSS_Functions), or [at-rules](/en-US/docs/Web/CSS/At-rule). Rather, it elaborates on how all of these features should be defined and how user agents should parse CSS. + +## At-rules + +- none + +> **Note:** The module explicitly states that {{cssxref("@charset")}} is not an actual at-rule, but rather an unrecognized legacy rule that should be omitted when a stylesheet is grammar-checked. + +## Reference + +### Key concepts + +- {{cssxref("at-rule")}} +- [character escaping](/en-US/docs/Web/CSS/custom-ident#escaping_characters) +- [CSS comments](/en-US/docs/Web/CSS/Comments) +- [CSS declaration](/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration) +- [CSS declaration block](/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration_Block) +- [CSS function](/en-US/docs/Web/CSS/CSS_Functions) +- [invalid](/en-US/docs/Web/CSS/CSS_syntax/Error_handling) +- [style rule](/en-US/docs/Web/API/CSSStyleRule) + +### Glossary terms + +- {{glossary("CSS_Descriptor", "CSS descriptor")}} +- {{glossary("parse")}} +- {{glossary("stylesheet")}} +- {{glossary("whitespace")}} + +## Guides + +- [Syntax](/en-US/docs/Web/CSS/Syntax) + + - : Overview of CSS syntax, including CSS declarations, declaration blocks, rulesets, and statements. + +- [Value definition syntax](/en-US/docs/Web/CSS/Value_definition_syntax) + + - : Explains the formal grammar for defining valid values for CSS properties and functions, along with semantic constraints. A guide for understanding CSS component value types, combinators, and multipliers. + +- [CSS syntax error handling](/en-US/docs/Web/CSS/CSS_syntax/Error_handling) + + - : Overview of how the user agent handles invalid CSS. + +- [Learn CSS first steps: CSS syntax](/en-US/docs/Learn/CSS/First_steps/What_is_CSS#css_syntax) + + - : Introductory guide to CSS, including an introduction to CSS syntax. + +## Related concepts + +[CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) module: + +- [CSS specificity](/en-US/docs/Web/CSS/Specificity) + +[CSS cascade](/en-US/docs/Web/CSS/CSS_cascade) module: + +- {{cssxref("@import")}} at-rule +- {{cssxref("important")}} flag +- [Initial values](/en-US/docs/Web/CSS/initial_value) +- [Computed values](/en-US/docs/Web/CSS/computed_value) +- [Used values](/en-US/docs/Web/CSS/used_value) +- [Actual values](/en-US/docs/Web/CSS/actual_value) +- [CSS inheritance](/en-US/docs/Web/CSS/Inheritance) +- {{Glossary("Property/CSS", "CSS property")}} + +[CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module: + +- [custom property (`--*`)](/en-US/docs/Web/CSS/--*) +- {{cssxref("var")}} function + +[CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) module: + +- {{cssxref("@media")}} at-rule +- {{cssxref("@supports")}} at-rule + +[CSS Object Model (CSSOM)](/en-US/docs/Web/API/CSS_Object_Model) API: + +- {{domxref("CSSValue.cssText", "cssText")}} property +- {{domxref("CSSStyleSheet.insertRule()", "insertRule(rule)")}} method +- {{domxref("CSSStyleSheet.replace()", "replace(text)")}} method + +[WHATWG](/en-US/docs/Glossary/WHATWG) specification: + +- {{HTMLElement("style")}} element +- {{HTMLElement("link")}} element +- [`class`](/en-US/docs/Web/HTML/Global_attributes/class) attribute +- [`rel`](/en-US/docs/Web/HTML/Attributes/rel#stylesheet) attribute + +## Specifications + +{{Specifications}} + +## See also + +- [CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) module +- [CSS values and units](/en-US/docs/Web/CSS/CSS_Values_and_Units) module diff --git a/files/en-us/web/css/custom-ident/index.md b/files/en-us/web/css/custom-ident/index.md index a6261b6ee58ffe6..5315f24ed79b1ca 100644 --- a/files/en-us/web/css/custom-ident/index.md +++ b/files/en-us/web/css/custom-ident/index.md @@ -21,10 +21,27 @@ The syntax of `` is similar to CSS identifiers (such as property n - any decimal digit (`0` to `9`), - a hyphen (`-`), - an underscore (`_`), -- an escaped character (preceded by a backslash, `\`), +- an [escaped character](#escaping-characters) (preceded by a backslash, `\`), - a [Unicode](https://en.wikipedia.org/wiki/Unicode) character (in the format of a backslash, `\`, followed by one to six hexadecimal digits, representing its Unicode code point) -Note that `id1`, `Id1`, `iD1` and `ID1` are all different identifiers as they are [case-sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). On the other hand, as there are several ways to escape a character, `toto\?` and `toto\3F` are the same identifiers. +Note that `id1`, `Id1`, `iD1`, and `ID1` are all different identifiers as they are [case-sensitive](https://en.wikipedia.org/wiki/Case_sensitivity). + +### Escaping characters + +Any Unicode code point can be included as part of a `` or quoted {{cssxref("string")}} by escaping it. + +In CSS, there are several ways to escape a character. Escape sequences start with a backslash (`\`), and continue with: + +- One to six hex (`ABCDEF0123456789`) digits. The hex digits can optionally be followed by white space. The hex escape sequence gets replaced by the Unicode code point whose value is given by those digits. The whitespace allows the sequences to be followed by actual hex digits (versus replaced ones). +- Any Unicode code point that is not a hex digit or a newline character. + +Examples: + +- "&B" can be written as `\26 B` or `\000026B`. +- "hi.there" can be written as `hi\.there` or `hi\002Ethere`. +- "toto?" can be written as `toto\?`, `toto\3F`, or `toto\00003F`. + +To include actual white space after an escape sequence, include two white spaces in the escape sequence. ### Forbidden values