Skip to content

docs: add 1.x → 2.x upgrade notes #121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yuschick merged 3 commits into from
Feb 20, 2026
Merged

docs: add 1.x → 2.x upgrade notes #121

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
74c1557
docs: drop trailing whitespace from readme
wbolster Feb 17, 2026
f5b0c63
docs: add 1.x → 2.x upgrade notes
wbolster Feb 17, 2026
3bb84c3
Merge branch 'main' into docs
yuschick Feb 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ A Stylelint plugin to enforce the use of [logical CSS properties, values and uni

## Table of Contents

[Getting Started](#getting-started) | [Quickstart](#quickstart) | [Plugin Configs](#logical-css-configs) | [Plugin Rules](#logical-css-rules) | [Troubleshooting](#troubleshooting)
[Getting Started](#getting-started) | [Quickstart](#quickstart) | [Plugin Configs](#logical-css-configs) | [Plugin Rules](#logical-css-rules) | [Troubleshooting](#troubleshooting) | [Upgrading from 1.x → 2.x](#upgrading-from-1x--2x)

## Getting Started

Expand Down Expand Up @@ -117,14 +117,14 @@ type Severity = 'error' | 'warning';
interface SecondaryOptions {
fix?: boolean;
ignore?: PhysicalKeywordProperty[],
severity?: Severity
severity?: Severity
}
```

```json
{
"rules": {
"logical-css/require-logical-keywords": [true, {
"logical-css/require-logical-keywords": [true, {
"fix": true,
"ignore": ["caption-side", "offset-anchor"],
"severity": "error",
Expand Down Expand Up @@ -298,14 +298,14 @@ type Severity = 'error' | 'warning';
interface SecondaryOptions {
fix?: boolean;
ignore?: PhysicalProperty[],
severity?: Severity
severity?: Severity
}
```

```json
{
"rules": {
"logical-css/require-logical-properties": [true, {
"logical-css/require-logical-properties": [true, {
"fix": true,
"ignore": ["height", "scroll-margin-bottom", "width"],
"severity": "error",
Expand Down Expand Up @@ -687,14 +687,14 @@ type Severity = 'error' | 'warning';
interface SecondaryOptions {
fix?: boolean;
ignore?: PhysicalUnit[],
severity?: Severity
severity?: Severity
}
```

```json
{
"rules": {
"logical-css/require-logical-units": [true, {
"logical-css/require-logical-units": [true, {
"fix": true,
"ignore": ["vh", "dvw"],
"severity": "error",
Expand Down Expand Up @@ -846,3 +846,17 @@ div {
width: 100%;
}
```

---

## Upgrading from 1.x → 2.x

@yuschick yuschick Feb 20, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Upgrading from 1.x → 2.x

To upgrade from 1.x (v1 documentation) to 2.x, update your Stylelint configuration as follows:

1. Remove legacy rules

The rules have changed from v1.x to v2.x. Remove any legacy rules (plugin/use-logical-*) from your Stylelint configuration.

2a. Use the recommended configuration

Add the recommended preset to your extends array:

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

… or …

2b. Migrate custom rule configurations

In v2, several rules were renamed and separated for improved granularity. If you previously configured these rules manually, update them as follows:

v1 Rule v2 Replacement
plugin/use-logical-properties-and-values logical-css/require-logical-keywords
logical-css/require-logical-properties
plugin/use-logical-units logical-css/require-logical-units

If you relied on custom rule configuration in v1, you must explicitly configure the corresponding v2 rules.


To upgrade from 1.x [(documentation)](./V1-DOCUMENTATION.md) → 2.x, change your Stylelint configuration:

- Include the recommended config in the `extends` array
- To use the defaults, drop the `plugin/use-logical-*` entries from `rules`

If you had specific config that you want to keep, note that the rules have been split and renamed:

- `plugin/use-logical-properties-and-values` → `logical-css/require-logical-keywords` and `logical-css/require-logical-properties`
- `plugin/use-logical-units` → `logical-css/require-logical-units`