chore(lint): modernize and unify linting configuration by caseyisonit · Pull Request #6004 · adobe/spectrum-web-components

caseyisonit · 2026-02-04T00:50:33Z

Description

Modernizes the repository's linting infrastructure by upgrading to ESLint 9 with flat config, centralizing all linting at the root, and adding unified commands for checking and fixing code across the entire codebase.

The RFC is stored temporarily in the style-guide in contributor docs: CONTRIBUTOR-DOCS/02_style-guide/temp_linting-RFC.md. It will be removed before merge and provides the context and reasoning for the changes. Start there for full background. This PR includes minor linting fixes in the Badge component across all systems as examples. A follow-up PR will apply linting to the entire repo (possibly phased in multiple PRs merged in sequence).

Motivation and context

The existing linting setup had several pain points:

ESLint was using the legacy .eslintrc format (deprecated in ESLint 9)
Linting dependencies were scattered across sub-packages
No unified commands for running all linters
Inconsistent behavior between local, lint-staged, and CI environments
Missing Prettier check in CI

This PR addresses these by consolidating all linting at the root with a single configuration per tool (eslint.config.js, stylelint.config.js, .prettierrc.yaml), so behavior is consistent wherever linting is run.

Related issue(s)

Related to ongoing DX improvements for contributor tooling

Summary of changes

ESLint modernization

Upgraded to ESLint 9 with flat config (eslint.config.js)
Added plugins: eslint-plugin-lit, eslint-plugin-wc, eslint-plugin-jsdoc, eslint-plugin-mdx, eslint-plugin-jsonc, eslint-plugin-notice
Centralized all rules at root with targeted overrides for tests, stories, scripts, and legacy patterns (icons/elements, react wrappers)
Inlined custom @spectrum-web-components/eslint-plugin rules; header enforced via eslint-plugin-notice with linters/HEADER.js

Stylelint enhancements

Root stylelint.config.js (ES module) with stylelint-config-standard, stylelint-order, and custom @spectrum-web-components/stylelint-header-plugin (swc/header) for CSS
Property order: Logical, idiomatic order via order/properties-order and linters/stylelint-property-order.js (recess-order style), enforced as errors (not alphabetical)
2nd-gen only: stylelint-declaration-strict-value as warning for design token enforcement
1st-gen: Overrides that relax vendor-prefix and specificity rules for 1st-gen/**/*.css

Unified commands

Command	Description
`yarn lint`	Check all (ESLint, Stylelint, Prettier)
`yarn format`	Fix all (ESLint, Stylelint, Prettier)
`yarn lint:eslint`	Check JavaScript/TypeScript only
`yarn lint:1st-gen`	ESLint for 1st-gen only
`yarn lint:2nd-gen`	ESLint for 2nd-gen only
`yarn lint:styles`	Check CSS only
`yarn lint:prettier`	Check formatting only
`yarn format:eslint`	Fix JavaScript/TypeScript only
`yarn format:styles`	Fix CSS only
`yarn format:prettier`	Fix formatting only

Pre-commit and CI

lint-staged (lint-staged.config.js): ESLint and Stylelint with --fix, Prettier; lit-analyzer for staged 1st-gen package source; package.json version generation, yarn constraints --fix, lockfile refresh; .changeset/*.md escape script
CI: Reviewdog for ESLint and Stylelint on changed files; Prettier check on changed files; all use the same root configs

Documentation

Updated CONTRIBUTOR-DOCS/02_style-guide/02_linting-tools.md with commands, config locations, import order, CSS property order, lit-a11y allow-lists, and IDE setup
RFC at CONTRIBUTOR-DOCS/02_style-guide/temp_linting-RFC.md with research and decision rationale (temporary; remove before merge)

Follow-up work

Run yarn format across the repo to fix pre-existing lint errors (separate PR, possibly phased)
Document or extend clickEventsAllowList in eslint.config.js for lit-a11y as needed

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed the Accessibility Practices for this feature, see: Aria Practices
I have added automated tests to cover my changes.
I have included a well-written changeset if my change needs to be published.
I have included updated documentation if my change required it.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
Automated tests cover all use cases and follow best practices for writing
Validated on all supported browsers
All VRTs are approved before the author can update Golden Hash

Manual review test cases

Verify yarn lint runs ESLint, Stylelint, and Prettier
1. Run yarn lint from the repo root
2. Observe that all three tools run and report issues
3. Expect no crashes or configuration errors
Verify yarn format fixes issues across all tools
1. Run yarn format from the repo root
2. Observe that fixable issues are corrected
3. Expect files to be modified with fixes applied
Verify lint-staged runs on commit
1. Stage a .ts or .css file with a fixable issue
2. Run git commit
3. Expect lint-staged to fix the issue and include it in the commit
Verify CI runs Prettier check
1. Push a branch with unformatted code
2. Observe CI lint job
3. Expect Prettier step to fail and report the issue

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

This reverts commit 6c95b04.

…om/adobe/spectrum-web-components into caseyisonit/typescript-exploration

- Add ESLint 9.x and related plugins to root package.json - Remove ESLint dependencies from 1st-gen/package.json - Remove ESLint dependencies from 2nd-gen/package.json - Remove ESLint dependencies from example-project-rollup - All linting dependencies now managed at root level

- Add eslint-plugin-mdx for linting .md and .mdx files - Remove CONTRIBUTOR-DOCS from ESLint ignore list - Disable code block linting (docs contain partial code snippets) - Update research doc with markdown/MDX linting recommendations - Align css-custom-vars-viewer with root typescript-eslint version

- Add eslint-plugin-lit@2.1.1 with 15 rules for Lit template validation - Add eslint-plugin-wc@3.0.1 with 9 rules for Web Component correctness - Add documented browser globals for DOM, events, observers, network APIs - Remove unused eslint-formatter-pretty dependency - Pin all ESLint dependencies to exact versions (no carets) - Update all packages to latest stable versions: - @eslint/js: 9.39.2 - @typescript-eslint/*: 8.54.0 - eslint: 9.39.2 - eslint-config-prettier: 10.1.8 - eslint-plugin-jsonc: 2.21.0 - eslint-plugin-lit-a11y: 4.1.4 - eslint-plugin-mdx: 3.6.2 - eslint-plugin-simple-import-sort: 12.1.1 - eslint-plugin-storybook: 10.2.1 - jsonc-eslint-parser: 2.4.2

@slot

- Add eslint-plugin-jsdoc@62.5.0 with minimal rule set - Configure custom tags for Custom Elements Manifest (CEM): @element, @slot, @csspart, @cssproperty, @fires, @attr, @Attribute, @internal - Add additional browser globals for HTML element types: HTMLSlotElement, HTMLInputElement, HTMLButtonElement, etc. - Rules focus on consistency, not requiring docs everywhere: - check-alignment (error): Consistent asterisk alignment - check-indentation (warn): Consistent description indentation - check-param-names (error): Param names match function signature - check-tag-names (error): Only valid JSDoc/CEM tags - check-types (warn): Prefer lowercase primitives - require-param-description (warn): Encourage param descriptions - require-returns-description (warn): Encourage return descriptions - valid-types (warn): Valid type expressions

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

stylelint

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "display" to come before "border-radius"

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 800 in dc6effd

display: grid;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "grid-template-columns" to come before "gap"

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 802 in dc6effd

grid-template-columns: 1fr auto;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "display" to come before "align-items"

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 823 in dc6effd

display: flex;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "display" to come before "border-left"

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 846 in dc6effd

display: flex;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "padding" to come before "overflow"

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 851 in dc6effd

padding: 16px;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "container-type" to come before "border-radius"

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 864 in dc6effd

container-type: inline-size;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "display" to come before "container-type"

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 865 in dc6effd

display: flex;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "width" to come before "height"

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 884 in dc6effd

width: 36px;

🚫 [stylelint] <selector-pseudo-element-colon-notation> _{reported by reviewdog 🐶}
Expected double colon pseudo-element notation

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 97 in dc6effd

docs-page:not(:defined):before {

🚫 [stylelint] <selector-pseudo-element-colon-notation> _{reported by reviewdog 🐶}
Expected double colon pseudo-element notation

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 184 in dc6effd

#logo:focus-visible:before {

🚫 [stylelint] <selector-pseudo-element-colon-notation> _{reported by reviewdog 🐶}
Expected double colon pseudo-element notation

spectrum-web-components/1st-gen/projects/documentation/src/components/styles.css

Line 733 in dc6effd

sp-tab-panel:not(.section):focus code-example:after {

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "margin" to come before "font-style"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/manager.css

Line 17 in dc6effd

margin: 0;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "font-family" to come before "color"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/manager.css

Line 40 in dc6effd

font-family: var(--swc-sans-font-family-stack);

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "line-height" to come before "letter-spacing"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/manager.css

Line 45 in dc6effd

line-height: var(--swc-detail-line-height);

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "margin-block-end" to come before "line-height"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/manager.css

Line 46 in dc6effd

margin-block-end: 0;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "margin-block-start" to come before "margin-block-end"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/manager.css

Line 47 in dc6effd

margin-block-start: 0;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "color" to come before "background-color"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/preview.css

Line 15 in dc6effd

color: var(--swc-neutral-content-color-default, rgb(34 34 34));

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "font-family" to come before "color"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/preview.css

Line 16 in dc6effd

font-family: var(--swc-sans-font-family-stack);

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "margin" to come before "font-style"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/preview.css

Line 19 in dc6effd

margin: 0;

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "color" to come before "background-color"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/preview.css

Line 31 in dc6effd

color: var(--swc-neutral-content-color-default);

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "-webkit-tap-highlight-color" to come before "color"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/preview.css

Line 32 in dc6effd

-webkit-tap-highlight-color: rgb(0 0 0 / 0%);

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected an empty line before property "-webkit-tap-highlight-color"

spectrum-web-components/2nd-gen/packages/swc/.storybook/assets/preview.css

Line 32 in dc6effd

-webkit-tap-highlight-color: rgb(0 0 0 / 0%);

🚫 [stylelint] <order/properties-order> _{reported by reviewdog 🐶}
Expected "font-family" to come before "background-color"

spectrum-web-components/2nd-gen/packages/swc/stylesheets/swc.css

Line 18 in dc6effd

font-family: token("sans-serif-font");

1st-gen/packages/accordion/src/AccordionItem.ts

5t3ph

Two minor suggestions!

CONTRIBUTOR-DOCS/02_style-guide/02_linting-tools.md

stylelint.config.js

eslint.config.js

package.json

CONTRIBUTOR-DOCS/02_style-guide/02_linting-tools.md

package.json

.prettierrc.yaml

linters/stylelint-header-plugin/index.js

stylelint.config.js

package.json

CONTRIBUTOR-DOCS/02_style-guide/02_linting-tools.md

scripts/publish.js

caseyisonit and others added 30 commits November 7, 2025 10:00

chore: update typescript version to 5.9.2 in 1st-gen

9178fb1

chore: unified tsconfigs to support ES2020

b61d1cb

Merge branch 'main' into caseyisonit/typescript-exploration

749a8b5

chore: update vite and build script targets

b585cc7

chore: made TS a root dev dep for easier maintenance

6c95b04

chore: reviewdog fixes

cc7f09b

Revert "chore: made TS a root dev dep for easier maintenance"

beab739

This reverts commit 6c95b04.

chore: remove carrots from react wrapper script

bdbffb9

Merge branch 'main' into caseyisonit/typescript-exploration

90dbf25

Merge branch 'main' into caseyisonit/typescript-exploration

54fe6fa

Merge branch 'caseyisonit/typescript-exploration' of https://github.c…

9c8a405

…om/adobe/spectrum-web-components into caseyisonit/typescript-exploration

Merge branch 'main' into caseyisonit/typescript-exploration

a0c37d5

chore: remove typescript contributor guide

865d941

Merge branch 'main' into caseyisonit/typescript-exploration

d235943

chore: typescript fixes for changing to bundler

6a2bfe0

chore: align vite with ts so output is unchanged

fdbfe43

chore: merge main

d7d3d2c

chore: export alert banner from core to build

04c23dc

chore: version header

424df47

chore: add changesets

cea77ae

Merge branch 'main' into caseyisonit/typescript-exploration

c16aed4

chore: clean up settings

c9e0bf9

chore: add reactive color controller changeset

93264b6

chore: remove alert banner changeset

f9071d0

chore: remove card keyboard changeset

a4e3a25

chore: research doc with recs

a57aed1

caseyisonit added 2 commits February 11, 2026 10:32

chore: tabs to 2 spaces and applied to badge across all systems

dc6effd

chore: 1st-gen docs css linted

c1d4b62

github-actions bot reviewed Feb 11, 2026

View reviewed changes

caseyisonit added 7 commits February 11, 2026 10:39

chore: preview, manager, and swc stylesheet linted

1335b41

chore: add lint ignore to 1st gen css tools script

6f5743c

chore: prettier ignore templates because we use handlebar partials

393a27a

chore: prettier only changed files in action

7930776

chore: remove --cache from lint action

016cb37

chore: continue on error for lint and format commands

1138108

chore: merge main

50b9bab

github-actions bot reviewed Feb 12, 2026

View reviewed changes

1st-gen/packages/accordion/src/AccordionItem.ts Show resolved Hide resolved

chore: prettier lint fixes for diff files

b4617ba

caseyisonit requested review from 5t3ph, aramos-adobe, cdransf and rubencarvalho February 12, 2026 19:10

5t3ph reviewed Feb 12, 2026

View reviewed changes

CONTRIBUTOR-DOCS/02_style-guide/02_linting-tools.md Outdated Show resolved Hide resolved

stylelint.config.js Outdated Show resolved Hide resolved

rubencarvalho reviewed Feb 12, 2026

View reviewed changes

eslint.config.js Outdated Show resolved Hide resolved

rubencarvalho reviewed Feb 12, 2026

View reviewed changes

eslint.config.js Show resolved Hide resolved

Rajdeepc reviewed Feb 13, 2026

View reviewed changes

rubencarvalho added 2 commits February 13, 2026 13:00

chore: merge main

da1713a

chore: address feedback

46f92c5

github-actions bot reviewed Feb 13, 2026

View reviewed changes

scripts/publish.js Show resolved Hide resolved

chore: remove conflicting sorting plugins

a3b2465

rubencarvalho requested review from 5t3ph, Rajdeepc and rubencarvalho February 13, 2026 14:21

Rajdeepc requested changes Feb 13, 2026

View reviewed changes

rubencarvalho added 2 commits February 13, 2026 21:11

chore: merge main

9eaa44c

chore: fix badge stories

942dd54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(lint): modernize and unify linting configuration#6004

chore(lint): modernize and unify linting configuration#6004
caseyisonit wants to merge 71 commits intomainfrom
caseyisonit/linting-poc

caseyisonit commented Feb 4, 2026 •

edited

Loading

Uh oh!

github-actions bot left a comment

Uh oh!

Uh oh!

5t3ph left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

caseyisonit commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Summary of changes

ESLint modernization

Stylelint enhancements

Unified commands

Pre-commit and CI

Documentation

Follow-up work

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

5t3ph left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

caseyisonit commented Feb 4, 2026 •

edited

Loading