SWAN's Stylelint package is a custom linting plugin built to enforce the Vista Design System's evolving design language across CSS and SCSS files. It helps teams maintain consistency and reduce variations by flagging deviations from SWAN's design principles.
Note: This plugin supports only CSS and SCSS files. CSS-in-JS and LESS are not supported.
Getting started
The Project validator already includes setup for this plugin in your repository. If you've already run the project validator across your project, you can skip this section.
Prerequisites
- A Stylelint setup in your project
- Peer dependencies
@vp/swan>= 3.18.1 < 4stylelint^15 || ^16
- Node.js >= 18
Installation
Usage
To enable the plugin in your project, simply extend it in your Stylelint config. This also enables the recommended rules with their respective severities.
To best align with SWAN's best practices, it's advised to use the recommended configuration (shown above). However, it's possible to enable, disable, or alter the severity of individual rules if required.
Rules included
| Rule ID | Description | Default Severity | Docs with examples | Suggestion available |
|---|---|---|---|---|
swan/no-classnamesIntroduced in v1.0 | Using SWAN classes for any use in your stylesheet is discouraged as it leads to a fragile UI, since SWAN may update or remove these classnames. Instead developers should create their own classes and use them instead. | error | README | No |
swan/no-deprecated-tokensIntroduced in v1.0 | Deprecated SWAN tokens should be avoided where possible as they will be removed in a future version of SWAN. If a replacement is recommended, developers should use that instead otherwise should remove usage of the token. The rule will flag any usage of deprecated tokens in either property names or values. | error | README | Partially |
swan/no-internal-tokensIntroduced in v1.0 | Internal tokens (prefixed with swan-internal-* or swan-comp-*) are implementation details of SWAN. They are subject to change without notice and should not be used directly by product teams. Instead, developers should rely on semantic tokens. If no suitable semantic token exists for the use case, use a base token or reach out to the design system team before considering alternatives. | error | README | No |
swan/no-raw-colorsIntroduced in v1.0 | Raw color values such as #fff, rgba(...), or hsla(...) are not allowed. Always use semantic color tokens provided by SWAN. Raw values are discouraged because they create inconsistencies across products and make maintenance harder when the design evolves. If a semantic token doesn't exist for your use case, reach out to the design system team. | error | README | No |
swan/no-token-overridesIntroduced in v1.0 | SWAN design tokens are the single source of truth for all visual styles and are managed centrally by the design system. Their values should never be changed or overridden within an application. This rule prevents developers from re-declaring a token variable, which would lead to style inconsistencies and make the application difficult to maintain. Instead of setting a token's value, developers should only ever consume them. | error | README | No |
Troubleshooting/FAQs
Update your stylelint package to latest. See peer dependencies above.
If your SWAN rule config changes (like severity overrides) aren ’t showing up right away in your IDE, try restarting the Stylelint server or just reload the IDE.
By default, Stylelint works out of the box for .css files in most editors like VSCode. However, when working with .scss files, you may need a small setup to enable syntax highlighting and real-time linting.
-
Install the Stylelint VSCode Extension Make sure you have the Stylelint extension installed in your editor.
-
Update your VSCode
settings.jsonto explicitly enable linting for both css and scss file types:{ "stylelint.validate": ["css", "scss"] }
Changelog
See complete Changelog
