Property Use Logical stylelint

Property Use Logical is a stylelint rule to enforce the usage of Logical Properties and Values in CSS.

Physical dimensions and directions are described left to right and top to bottom, while their logical counterparts are described start to end and inline or block.

For example, to add spacing before the start of a paragraph, we might use the physical padding-left property.

p {
  padding-left: 2em;
}

Were the content Hebrew or Arabic — flowing right to left — then we might use alternating padding-left and padding-right properties.

p:dir(ltr) {
  padding-left: 2em;
}

p:dir(rtl) {
  padding-right: 2em;
}

Selector weight aside, we can instead use the logical padding-inline-start property.

p {
  padding-inline-start: 2em;
}

Similarly, physical horizontal and vertical dimensions are described more succinctly using their logical counterparts.

h1, h2, h3 {
  margin-top: 1em;
  margin-bottom: 1em;
}

blockquote {
  margin-left: 1em;
  margin-right: 1em;
}

/* becomes */

h1, h2, h3 {
  margin-block: 1em;
}

blockquote {
  margin-inline: 1em;
}

Usage

Add stylelint and Property Use Logical to your project.

npm install stylelint stylelint-use-logical-spec --save-dev

Add Property Use Logical to your stylelint configuration.

{
  "plugins": [
    "stylelint-use-logical-spec"
  ],
  "rules": {
    "liberty/use-logical-spec": ("always" || true) || ("ignore" || false || null)
  }
}

Options

always

The "always" option (alternatively true) requires logical properties and values to be used, and the following patterns are not considered violations:

.inset {
  inset: 0;
}

.margin {
  margin-inline-start: 0;
}

.padding {
  padding-inline: 0;
}

.float {
  float: inline-start;
}

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

.text-align-ignored:dir(ltr) {
  text-align: left;
}

While the following patterns are considered violations:

.inset {
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
}

.margin {
  margin-left: 0;
}

.padding {
  padding-left: 0;
  padding-right: 0;
}

.float {
  float: left;
}

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

ignore

The "ignore" option (alternatively false or null) disables the rule.

Secondary Options

except

The except option ignores reporting or autofixing properties and values matching a case-insensitive string or regular expression.

{
  "rules": {
    "liberty/use-logical-spec": ["always", { "except": ['float', /^margin/i] }]
  }
}

direction

The direction option controls whether left to right or right to left properties and values should be reported or autofixed.

{
  "rules": {
    "liberty/use-logical-spec": ["always", { "direction": "ltr" || "rtl" }]
  }
}

Property and Value Mapping

Assuming left to right directionality:

Positioning

margin

Padding

Logical Height and Logical Width

Border

border-start-start-radius border-top-left-radius border-start-end-radius border-bottom-left-radius border-end-start-radius border-top-right-radius border-end-end-radius border-bottom-right-radius

Special thanks

Codebase off https://github.com/csstools/stylelint-use-logical

Changes to Property Use Logical

5.0.0 (February 3rd, 2023)

New feature

• Add support for CSS in JS #35

  Fixes

• Fix shorthand properties that uses calc #28

4.1.0 (June 3rd, 2022)

22

The script loops through the maps listing of all properties and will make multiple replacements in a single string such as: transition: max-width 1s, padding-left 2s, margin-top 3s; will recommend (or change to): transition: max-inline-size 1s, padding-inline-start 2s, margin-block-start 3s; (for 'ltr' anyway)

I could only find 3 properties that would seem to fit this use case:

• transition
• transition-property
• will-change

If there are more, this is easy to update as the regex is stored in the maps.js file. By selecting only these nodes, I feel this one should run pretty lean instead of scanning all values for property names.

4.0.0 (May 31st, 2022)

New feature

• check shorthand properties and convert them to appropriate logical counterparts #12

• Skips over declaration if the shorthand property value is a single value - example margin: 0;

  Fixes

• Fixes bug with 2 prop mapping
• Alters 4 prop loop to only consolidate if all values are equal, and will output without the unsupported logical keyword

3.2.2 (July 26th, 2021)

• Update package-lock dependencies
• fix git workflow

3.2.1 (July 26th, 2021)

• Update stylelint peer dependency to use current version or late

3.2.0 (February 16th, 2021)

• Added: support for Logical height
• Added: support for Logical width

3.1.0 (November 3rd, 2020)

• Added: migration from version 2.0.0 to 3.1.0 removing none compliant code outlined in version 2.1.0
• Added: Documentation for border support
• Updated: peer-dependency of styleline to 13.7.2
• Fixed: repaired Except issues reported on original codebase - https://github.com/csstools/stylelint-use-logical/issues/3

3.0.* (November 3rd, 2020)

• Updated: Support for border logical values

2.1.0 (November 3rd, 2020)

• removed none compliant properties inset-start, inset-end margin-start margin-end padding-start padding-end (Breaking changes)

2.0.0 (May 12, 2018)

• Updated: peer stylelint to 10.0.1 (major)
• Updated: Node 8+ compatibility (major)

1.1.0 (September 29, 2018)

• Added: direction option to control whether properties and values are reported or autofixed using left to right or right to left counterparts
• Fixed: Physical properties and values within :dir(ltr) or :dir(rtl) are ignored

1.0.1 (September 28, 2018)

• Fix usage name

1.0.0 (September 26, 2018)

• Initial version