Stylelint Plugin Logical Css

A Stylelint plugin to enforce the use of logical CSS properties, values and units for adaptive, i18n-first styles.

[!TIP] V1 documentation can be found here

Table of Contents

Getting Started | Quickstart | Plugin Configs | Plugin Rules | Troubleshooting | Upgrading from 1.x → 2.x

Getting Started

[!IMPORTANT] The plugin requires Stylelint v14.0.0 or greater.

To get started using the plugin, it must first be installed.

npm i stylelint-plugin-logical-css --save-dev

yarn add stylelint-plugin-logical-css --dev

With the plugin installed, it must be added to the plugins array of your Stylelint config.

{
  "plugins": ["stylelint-plugin-logical-css"],
}

After adding the plugin to the configuration file, you now have access to the various rules and options it provides.

Quickstart

After installation, add this to your .stylelintrc.json:

{
  "plugins": ["stylelint-plugin-logical-css"],
  "extends": ["stylelint-plugin-logical-css/configs/recommended"]
}

Logical CSS Configs

For quick setup, the plugin provides preset configurations that enable commonly used rules.

Recommended

The recommended preset enables core logical CSS rules with sensible defaults, suitable for most projects.

Usage:

{
  "extends": ["stylelint-plugin-logical-css/configs/recommended"]
}

Equivalent to:

{
  "plugins": ["stylelint-plugin-logical-css"],
  "rules": {
    "logical-css/require-logical-keywords": [
      true,
      { "ignore": ["caption-side", "offset-anchor", "offset-position"], "severity": "error" },
    ],
    "logical-css/require-logical-properties": [true, { "severity": "error" }],
    "logical-css/require-logical-units": [true, { "severity": "error" }],
  },
}

Logical CSS Rules

The plugin provides multiple rules that can be toggled on and off as needed.

1. Require Logical Keywords
2. Require Logical Properties
3. Require Logical Units

---

Require Logical Keywords

[!NOTE] Read about current browser support for logical CSS properties.

Physical CSS directional keywords like left, right, top, bottom, horizontal, and vertical reference absolute directions that don't adapt to writing modes or text direction. Logical keywords like start, end, inline-start, block-end, inline, and block automatically adjust based on the document's writing mode, supporting internationalization and adaptive layouts.

Enable this rule to: Enforce the use of logical CSS directional keywords (start, end, inline-start, block-end, inline, block, etc.) over their physical equivalents (left, right, top, bottom, horizontal, vertical) in property values, ensuring your styles adapt properly to different writing modes and text directions.

{
  "rules": {
    "logical-css/require-logical-keywords": true,
  }
}

Require Logical Keywords Options

type Severity = 'error' | 'warning';

interface SecondaryOptions {
  fix?: boolean;
  ignore?: PhysicalKeywordProperty[],
  severity?: Severity
}

{
  "rules": {
    "logical-css/require-logical-keywords": [true, {
      "fix": true,
      "ignore": ["caption-side", "offset-anchor"],
      "severity": "error",
    }]
  }
}

Require Logical Keywords Map

The following table shows how physical CSS directional keywords are mapped to their logical equivalents. When this rule detects a physical keyword, it will suggest (or automatically fix, if enabled) the corresponding logical keyword.

<details> <summary>🚀 View Physical to Logical Keyword Mappings</summary> <table> <thead> <tr> <th>Property</th> <th>Physical Keyword(s)</th> <th>Logical Keyword(s)</th> </tr> </thead> <tbody> <tr> <td><code>box-orient</code></td> <td><code>horizontal</code>, <code>vertical</code></td> <td><code>inline-axis</code>, <code>block-axis</code></td> </tr> <tr> <td><code>caption-side</code></td> <td><code>top</code>, <code>bottom</code>, <code>left</code>, <code>right</code></td> <td><code>block-start</code>, <code>block-end</code>, <code>inline-start</code>, <code>inline-end</code></td> </tr> <tr> <td><code>clear</code></td> <td><code>left</code>, <code>right</code></td> <td><code>inline-start</code>, <code>inline-end</code></td> </tr> <tr> <td><code>float</code></td> <td><code>left</code>, <code>right</code></td> <td><code>inline-start</code>, <code>inline-end</code></td> </tr> <tr> <td><code>offset-anchor</code></td> <td><code>top</code>, <code>bottom</code>, <code>left</code>, <code>right</code></td> <td><code>block-start</code>, <code>block-end</code>, <code>inline-start</code>, <code>inline-end</code></td> </tr> <tr> <td><code>offset-position</code></td> <td><code>top</code>, <code>bottom</code>, <code>left</code>, <code>right</code></td> <td><code>block-start</code>, <code>block-end</code>, <code>inline-start</code>, <code>inline-end</code></td> </tr> <tr> <td><code>resize</code></td> <td><code>horizontal</code>, <code>vertical</code></td> <td><code>inline</code>, <code>block</code></td> </tr> <tr> <td><code>text-align</code></td> <td><code>left</code>, <code>right</code></td> <td><code>start</code>, <code>end</code></td> </tr> <tr> <td><code>text-align-last</code></td> <td><code>left</code>, <code>right</code></td> <td><code>start</code>, <code>end</code></td> </tr> </tbody> </table> </details>

Require Logical Keywords Examples

<details> <summary>✅ Passing Examples</summary>

.text {
  text-align: start;
  text-align-last: end;
}

.layout {
  float: inline-start;
  clear: inline-end;
}

.box {
  resize: inline;
}

.table {
  caption-side: block-start;
}

.legacy {
  box-orient: inline-axis;
}

.positioned {
  offset-anchor: block-end inline-start;
  offset-position: block-start inline-end;
}

</details> <details> <summary>❌ Failing Examples</summary>

.text {
  text-align: left;
  text-align-last: right;
}

.layout {
  float: left;
  clear: right;
}

.box {
  resize: horizontal;
}

.table {
  caption-side: top;
}

.legacy {
  box-orient: vertical;
}

.positioned {
  offset-anchor: bottom left;
  offset-position: top right;
}

</details>

---

Require Logical Properties

[!NOTE] Read about current browser support for logical CSS properties.

Physical CSS properties like width, height, left, and margin-top reference absolute dimensions and directions that don't adapt to writing modes or text direction. Logical properties like inline-size, block-size, inset-inline-start, and margin-block-start automatically adjust based on the document's writing mode, supporting internationalization and adaptive layouts.

Enable this rule to: Enforce the use of logical CSS properties (inline-size, block-size, margin-inline, padding-block, etc.) over their physical equivalents (width, height, margin-left, padding-top, etc.), ensuring your styles adapt properly to different writing modes and text directions.

{
  "rules": {
    "logical-css/require-logical-properties": true,
  }
}

Require Logical Properties Options

Configuration: By default, this rule validates all CSS declarations for any use of physical properties (width, height, top, left, margin-left, padding-top, etc.). Use the rule options to exclude specific physical properties from validation, automate physical-to-logical property fixing, or adjust the severity level as needed.

type Severity = 'error' | 'warning';

interface SecondaryOptions {
  fix?: boolean;
  ignore?: PhysicalProperty[],
  severity?: Severity
}

{
  "rules": {
    "logical-css/require-logical-properties": [true, {
      "fix": true,
      "ignore": ["height", "scroll-margin-bottom", "width"],
      "severity": "error",
    }]
  }
}

Require Logical Properties Map

The following table shows how physical CSS properties are mapped to their logical equivalents. When this rule detects a physical property, it will suggest (or automatically fix, if enabled) the corresponding logical property.

<details> <summary>🚀 View Physical to Logical Properties Mappings</summary> <table> <thead> <tr> <th>Physical Property</th> <th>Logical Property</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>border-bottom</code></td> <td><code>border-block-end</code></td> <td>Bottom border → Block end border</td> </tr> <tr> <td><code>border-bottom-color</code></td> <td><code>border-block-end-color</code></td> <td