mdn-data

In the mdn/mdn/data repository, CSS selectors are represented as JSON objects. Each selector object contains information about its syntax, the CSS modules it belongs to, and its standardization status. This data is useful for building tools that need to programmatically understand or list CSS selector capabilities.

Each selector object must include the following properties:

• syntax (string): The literal syntax of the selector (e.g., A ~ B, ::after, or :hover).
• groups (array of strings): The names of the CSS modules where the selector is defined.
• status (enum string): The standardization status. Valid values are standard, nonstandard, experimental, or obsolete.

An optional property is:

• mdn_url (string): A direct link to the selector's MDN documentation page. Note that this URL must omit localization segments (e.g., use /docs/Web/CSS/... instead of /en-US/docs/Web/CSS/...).

"General sibling selectors": {
  "syntax": "A ~ B",
  "groups": [
    "Selectors"
  ],
  "status": "standard"
}

The mdn-data CSS properties are represented as JSON objects. The structure of these objects differs depending on whether the property is a long-hand property or a short-hand property.

Long-hand properties

Long-hand properties typically use single values (strings or enums) for fields like animationType, percentages, initial, and computed.

Short-hand properties

Short-hand properties use arrays for fields like animationType, percentages, initial, and computed to list the constituent long-hand properties that the short-hand property controls or derives from.

// Example Long-hand property
"background-color": {
  "syntax": "<color>",
  "media": "visual",
  "inherited": false,
  "animationType": "color",
  "percentages": "no",
  "groups": ["CSS Background and Borders"],
  "initial": "transparent",
  "appliesto": "allElements",
  "computed": "computedColor",
  "order": "uniqueOrder",
  "alsoAppliesTo": ["::first-letter", "::first-line", "::placeholder"],
  "status": "standard"
}

// Example Short-hand property
"background": {
  "syntax": "[ <bg-layer> , ]* <final-bg-layer>",
  "media": "visual",
  "inherited": false,
  "animationType": [
    "background-color",
    "background-image",
    "background-clip",
    "background-position",
    "background-size",
    "background-repeat",
    "background-attachment"
  ],
  "percentages": [
    "background-position",
    "background-size"
  ],
  "groups": ["CSS Background and Borders"],
  "initial": [
    "background-image",
    "background-position",
    "background-size",
    "background-repeat",
    "background-origin",
    "background-clip",
    "background-attachment",
    "background-color"
  ],
  "appliesto": "allElements",
  "computed": [
    "background-image",
    "background-position",
    "background-size",
    "background-repeat",
    "background-origin",
    "background-clip",
    "background-attachment",
    "background-color"
  ],
  "order": "orderOfAppearance",
  "alsoAppliesTo": ["::first-letter", "::first-line", "::placeholder"],
  "status": "standard"
}

The syntaxes.json file defines the formal syntax for CSS properties. In the MDN data structure, CSS properties (found in properties.json) use a syntax key to reference these definitions.

Syntaxes can be simple keyword lists, combinations of CSS types (defined in types.md), or references to other syntaxes within syntaxes.json.

Common syntax patterns include:

• Keywords: Separated by a pipe (|), e.g., scroll | fixed | local.
• Type references: Referencing CSS types like <number> or <percentage>.
• Syntax nesting: Referencing other defined syntaxes, e.g., <length> | <percentage>.
• Repetition: Using the # symbol to indicate that the preceding syntax can be repeated (e.g., <attachment>#).

/* Example: background-attachment property definition */
// In properties.json:
"background-attachment": {
  "syntax": "<attachment>#"
}

/* Example: attachment syntax definition */
// In syntaxes.json:
"attachment": {
  "syntax": "scroll | fixed | local"
}

Releases for mdn-data are published to both GitHub and the npm registry. The publishing process is automated using release-please and GitHub Actions. To trigger a new release, you must follow these requirements:

1. Commit Convention: All commits must adhere to conventional commits. Only commits prefixed with fix: or feat: are recognized by the release automation.
2. Release Pull Request: The release-please tool monitors the main branch. If it detects relevant fix: or feat: commits since the last release, it automatically opens a release pull request.
3. Merging and Deployment: Once the release pull request is merged, the publish-release.yml workflow triggers. This workflow creates a GitHub release and publishes the updated package to npm.

After the process completes, verify the release by checking the mdn-data package on npm.