wagtail/stylelint-config-wagtail

Shareable stylelint config for CSS and SCSS, following Wagtail’s code style.

Wagtail is an open source content management system built on Django, with a strong community and commercial support. It's focused on user experience, and offers precise control for designers and developers.

Join the Community at Wagtail Space! 🚀

Wagtail Space is coming in June 2024! Don't miss your chance to meet other Wagtailers in person. The Call for Participation and registration for both Wagtail Space 2024 events is open. We'd love to have you give a talk, contribute to a sprint, or join us as an attendee in June.

• Wagtail Space NL, Arnhem, The Netherlands. 2024-06-12 - 2024-06-14
• Wagtail Space US, Philadelphia, PA. 2024-06-20 to 2024-06-22

🔥 Features

• A fast, attractive interface for authors
• Complete control over front-end design and structure
• Scales to millions of pages and thousands of editors
• Fast out of the box, cache-friendly when you need it
• Content API for 'headless' sites with decoupled front-end
• Runs on a Raspberry Pi or a multi-datacenter cloud platform
• StreamField encourages flexible content without compromising structure
• Powerful, integrated search, using Elasticsearch or PostgreSQL
• Excellent support for images and embedded content
• Multi-site and multi-language ready
• Embraces and extends Django

Find out more at wagtail.org.

👉 Getting started

Wagtail works with Python 3, on any platform.

To get started with using Wagtail, run the following in a virtual environment:

pip install wagtail
wagtail start mysite
cd mysite
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

For detailed installation and setup docs, see the getting started tutorial.

👨‍👩‍👧‍👦 Who’s using it?

Wagtail is used by NASA, Google, Oxfam, the NHS, Mozilla, MIT, the Red Cross, Salesforce, NBC, BMW, and the US and UK governments. Add your own Wagtail site to madewithwagtail.org.

📖 Documentation

docs.wagtail.org is the full reference for Wagtail, and includes guides for developers, designers and editors, alongside release notes and our roadmap.

For those who are new to Wagtail, the Zen of Wagtail will help you understand what Wagtail is, and what Wagtail is not.

For developers who are ready to jump in to their first Wagtail website the Getting Started Tutorial will guide you through creating and editing your first page.

Do you have an existing Django project? The Wagtail Integration documentation is the best place to start.

📌 Compatibility

(If you are reading this on GitHub, the details here may not be indicative of the current released version - please see Compatible Django / Python versions in the Wagtail documentation.)

Wagtail supports:

• Django 4.2.x and 5.0.x
• Python 3.8, 3.9, 3.10, 3.11 and 3.12
• PostgreSQL, MySQL and SQLite (with JSON1) as database backends

Previous versions of Wagtail additionally supported Python 2.7, 3.7 and earlier Django versions.

---

📢 Community Support

There is an active community of Wagtail users and developers responding to questions on Stack Overflow. When posting questions, please read Stack Overflow's advice on how to ask questions and remember to tag your question "wagtail".

For topics and discussions that do not fit Stack Overflow's question and answer format we have a Slack workspace. Please respect the time and effort of volunteers by not asking the same question in multiple places.

Our GitHub discussion boards are open for sharing ideas and plans for the Wagtail project.

We maintain a curated list of third party packages, articles and other resources at Awesome Wagtail.

🧑‍💼 Commercial Support

Wagtail is sponsored by Torchbox. If you need help implementing or hosting Wagtail, please contact us: [email protected]. See also madewithwagtail.org/developers/ for expert Wagtail developers around the world.

🔐 Security

We take the security of Wagtail, and related packages we maintain, seriously. If you have found a security issue with any of our projects please email us at [email protected] so we can work together to find and patch the issue. We appreciate responsible disclosure with any security related issues, so please contact us first before creating a GitHub issue.

If you want to send an encrypted email (optional), the public key ID for [email protected] is 0xbed227b4daf93ff9, and this public key is available from most commonly-used keyservers.

🕒 Release schedule

Feature releases of Wagtail are released every three months. Selected releases are designated as Long Term Support (LTS) releases, and will receive maintenance updates for an extended period to address any security and data-loss related issues. For dates of past and upcoming releases and support periods, see Release Schedule.

🕛 Nightly releases

To try out the latest features before a release, we also create builds from main every night. You can find instructions on how to install the latest nightly release at https://releases.wagtail.org/nightly/index.html

🙋🏽 Contributing

If you're a Python or Django developer, fork the repo and get stuck in! We have several developer focused channels on the Slack workspace.

You might like to start by reviewing the contributing guidelines and checking issues with the good first issue label.

We also welcome translations for Wagtail's interface. Translation work should be submitted through Transifex.

🔓 License

BSD - Free to use and modify for any purpose, including both open and closed-source code.

👏 Thanks

We thank the following organisations for their services used in Wagtail's development:

BrowserStack provides the project with free access to their live web-based browser testing tool, and automated Selenium cloud testing.

Squash provides the project with free test environments for reviewing pull requests.

Assistiv Labs provides the project with unlimited access to their remote testing with assistive technologies.

stylelint-config-wagtail's Issues

Enforce declarations order with stylelint

Initially mentioned in wagtail/wagtail#5246 (comment), and discussed again in a UI team meeting.

We want to use stylelint-order for this, we want to enforce mixins are first in declarations, and I think that’s about it.

Update to support Stylelint 16

https://stylelint.io/migration-guide/to-16/

Reconsider declaration-block-no-redundant-longhand-properties

Follow-up to wagtail/wagtail#10719 / wagtail/wagtail#11151 – where I’ve disabled this rule for now.

I’m not sure how much I like the idea of enforcing this rule for margin / padding properties. The main annoyance from my side is that when you want to set both properties with a similar-enough values, it’s nice to have them both side by side on the same line.

But when the values are quite complex, it would be nice to split into separate lines. Though this can be worked around with variables.

It’s also a bit annoying when you want to add one new longhand property in a situation where a shorthand would be possible – and the diff of the change becomes muddled up between "new" changes and refactorings due to the enforcement of a rule like this.

---

Not something I’d feel strongly about but I’d like to hear what others think?

Linting rule to prevent forced-color-adjust usage

Follow-up to the Contrast Themes GSoC project. There are a number of cases where we started using forced-color-adjust in Wagtail’s stylesheets.

In all but one of those cases, the property is used incorrectly, leading to issues for end users in high-contrast mode. I believe we should disallow all usage of forced-color-adjust, as there are very few cases where it’s the correct approach (the only one being if the exact color being used is so important that it should always be used, at the expense of the legibility / contrast of the content).

Add a linting rule to block additional usage of `text-transform`

Adding text-transform: uppercase (or others) creates added friction for translated content.

While it may not be critical we want to ensure that our stylelint config makes it simple to make things translatable and usable.

Originally posted by @lb- in wagtail/wagtail#7624 (comment)

stylelint config additions to consider

Follow-up to wagtail/wagtail#5246. This config is working quite well as-is, but there are a few things we discussed adding:

• Selector ordering, wagtail/wagtail#5246 (comment)
• Sass imports, pixels vs ems, specificity, class naming conventions, wagtail/wagtail#5246 (comment)
• Cross-browser support linting with https://github.com/ismay/stylelint-no-unsupported-browser-features
• Accessibility-related checks with https://github.com/YozhikM/stylelint-a11y
• This kind of "everything must be variables" enforcement: https://github.com/AndyOGo/stylelint-declaration-strict-value

Feel free to edit this comment or add more if there is more we should discuss and consider for inclusion.

---

Here is a config I worked on recently which includes some of the above, for consideration: https://github.com/torchbox/stylelint-config-torchbox.

Add scss/at-rule-no-unknown in this config

Based on the stylelint configuration for Wagtail. I think this should be the default directly in this package:

'scss/at-rule-no-unknown': [
      true,
      {
        ignoreAtRules: [
          'tailwind',
          'apply',
          'variants',
          'responsive',
          'screen',
          'layer',
        ],
      },
    ],

Add ability to block union classes (via parent selector)

Problem

The ITCSS guide recommends that nesting be limited and that full selectors provides a more ergonomic way to scan through and search code.

https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/

Limit nesting to 2 levels. Many developers think that using the parent selector (&) is a requirement just because they use Sass. There’s nothing wrong with flat structure with full selectors expanded, either. Often it’s easier to scan and search the code.

.c-teaser {
   padding: 2em;
}

.c-teaser--small {
  padding: 1em;
}

.c-teaser__title {
  font-size: 2em;
}

Use the style you prefer, but avoid deep nesting, which results in overqualified selectors. Those are against the spirit of ITCSS.

Details

• With the Stylelint SCSS library we can enforce no union class, this makes it easier for us to adopt less nesting in the future and makes it easier to read through and search for classes as they are in the styles.
• https://github.com/stylelint-scss/stylelint-scss/blob/master/src/rules/selector-no-union-class-name/README.md
• ❌ .w-header { &__subtitle { background-color: green; } }
• 👍 .w-header { .w-header__subtitle { background-color: green; } }

Upgrade dependencies

• stylelint to 15*
• stylelint-config-recommended to 13*
• Others

See wagtail/wagtail#10671

Introduce selector-max-combinators, selector-max-specificity & max-nesting-depth

Problem

• Currently in Wagtail there are issues with very nested CSS making it hard for other CSS to override it, this will also create problems as we add Tailwind utilities here and there.
• Stylelint provides two ways to restrict the nesting & specificity.

Details

Assessment of selector-max-combinators & selector-max-specificity on current Wagtail codebase.

level	errors
** Level 1 **	148 problems found
'selector-max-combinators': 3,	21
'selector-max-specificity': '0,3,3',	127
---------------------------------------	------------------
** Level 2 **	161 problems found
'selector-max-combinators': 3,	21
'selector-max-specificity': '0,3,2',	140
---------------------------------------	------------------
** Level 3 **	269 problems found
'selector-max-combinators': 2,	129
'selector-max-specificity': '0,3,2',	140
---------------------------------------	------------------
** Level 4 **	301 problems found
'selector-max-combinators': 2,	129
'selector-max-specificity': '0,3,1',	172
---------------------------------------	------------------

Assessment of max-nesting-depth

• Adding at level 2 only introduces 106 errors, depth 3 introduces zero errors.

Recommendation

• To have a balance between adding strictness and ensuring we do not have to rebuild all the styles;
• 'selector-max-specificity': '0,3,3'
• 'max-nesting-depth': 2'
• 'selector-max-combinators': 2'

Links

• wagtail/wagtail#7689

Add ability to enforce BEM classes with prefix

Problem

• Wagtail's code is meant to use BEM classes, however this has never been enforced and only really partially adopted.
• Enforcing this at the stylelint level will help the project align with this standard

Details

• It is unclear if this should be in the base stylelint config or as a separate plugin also exported by this package.
• It will be important to be able to set a prefix (e.g. w-header w-header--merged OR wx-header wx-header--merged ).

Links

• https://github.com/simonsmith/stylelint-selector-bem-pattern which uses https://github.com/postcss/postcss-bem-linter
• http://getbem.com/naming/
• wagtail/wagtail#7689

Potential issue with sorting

I just started to resolve wagtail/wagtail#10719 and have realised that our sorting rules could be causing some issues.

When I run the stylelint formatter / fixer on the Wagtail codebase I see that it's moving all our @include mixins to the top of the selector block.

stylelint-config-wagtail/index.js

Lines 36 to 43 in b5986bb

	// Mixins should always be first in declarations
	'order/order': [
	{
	name: 'include',
	type: 'at-rule',
	},
	'declarations',
	],

From my understanding, this will actually cause a few problems where the styles will not be overridden at breakpoints.

Context of this change.

• #14
• #17

I know I merged this in but just wondering if there are some nuances for how mixins can be used that we should be allowing.

declaration-property-value-blacklist is deprecated

• Deprecation Warning: 'declaration-property-value-blacklist' has been deprecated. Instead use 'declaration-property-value-disallowed-list'

Allow all CSS system colors in stylesheets without variables usage

See wagtail/wagtail#8945

The approach to block all non-variable usage is a bit too strict - allow system colors to be used.

v1.0.0 release

Our config has been pretty stable over the last year and a half – I think it might be time for a v1.0.0 release?

We’d still be as able to make configuration changes as currently, breaking or not. The only difference in using the major version number will be:

• Communicating this is stable software, no longer experimental
• Being able to do minor upgrades without breaking changes and communicating that with the version number (in SemVer, v0.5.0 -> v0.6.0 makes no guarantee on compatibility).

Add ability to block selectors that select data attributes

Overview

• The Wagtail development documentation advises that classes should be used for styles and data attributes should be used for JS. https://docs.wagtail.org/en/latest/contributing/ui_guidelines.html#html-guidelines
• As the CSS side of this is not enforced it means that it is up to any core contributor to remember this when reviewing new code, it would be much easier if this was flagged as a linting error instead.

Proposed solution

Add 'selector-max-attribute': [0, { ignoreAttributes: ['/^(?!data-).*/'] }], - which only blocks the use of data-* attributes when applying styles to components.

All other usage should still be allowed, such as hidden, aria-hidden, disabled, type etc.

Additional details

• https://stylelint.io/user-guide/rules/list/selector-max-attribute/

Issues in Wagtail Core

The following 11 issues will be flagged in Wagtail core if this rule is applied.

• data-tabs-animate on the tabs can be resolved by using classes instead (or just drop this feature as it is unused)
• tippy styles - probably would be left as is and this rule would be ignored in the overrides folder as we have no control over these components
• Wagtail bird 'parts' can be resolved using BEM classes

client/scss/components/_tabs.scss
 69:3  ✖  Expected ".w-tabs[data-tabs-animate] .w-tabs__panel" to have no more than 0 attribute selectors             selector-max-attribute
 72:5  ✖  Expected ".w-tabs[data-tabs-animate] .w-tabs__panel.animate-in" to have no more than 0 attribute selectors  selector-max-attribute

client/scss/overrides/_vendor.tippy.scss
  8:1  ✖  Expected ".tippy-box[data-placement^='top'] > .tippy-arrow::before" to have no more than 0 attribute selectors     selector-max-attribute
 12:1  ✖  Expected ".tippy-box[data-placement^='bottom'] > .tippy-arrow::before" to have no more than 0 attribute selectors  selector-max-attribute
 16:1  ✖  Expected ".tippy-box[data-placement^='left'] > .tippy-arrow::before" to have no more than 0 attribute selectors    selector-max-attribute
 20:1  ✖  Expected ".tippy-box[data-placement^='right'] > .tippy-arrow::before" to have no more than 0 attribute selectors   selector-max-attribute
 25:1  ✖  Expected ".tippy-box[data-theme='dropdown']" to have no more than 0 attribute selectors                            selector-max-attribute
 28:3  ✖  Expected ".tippy-box[data-theme='dropdown'] .tippy-content" to have no more than 0 attribute selectors             selector-max-attribute

client/src/components/Sidebar/modules/WagtailBranding.scss
 54:7  ✖  Expected ".sidebar-wagtail-branding--wagging:hover [data-part='tail']" to have no more than 0 attribute selectors         selector-max-attribute
 60:7  ✖  Expected ".sidebar-wagtail-branding--wagging:hover [data-part='eye--open']" to have no more than 0 attribute selectors    selector-max-attribute
 64:7  ✖  Expected ".sidebar-wagtail-branding--wagging:hover [data-part='eye--closed']" to have no more than 0 attribute selectors  selector-max-attribute