CSS Cleanup

Last updated on

6 October 2020

NOTE: The relatively small amount of unfinished work in this cleanup has stalled. A new effort to finish the CSS cleanup is underway over at #1921610: [Meta] Architect our CSS. Please join in!

NOTE #2: The instructions for naming and structure of the CSS files is out of date in this post. Please, refer to CSS file organization (for Drupal 8) for up-to-date instructions.

Overview of Goals
The CSS Clean-up Process
Core Issues in Progress
Following the Core Issues

Overview of Goals

Make it easy to remove unwanted design assumptions in the theme layer, while maintaining critical functionality (such as functional JavaScript widgets).
Prevent unneeded administrative styles from loading on the front end.
Give modules the ability to include a generic design implementation with their module, without burdening themers.
Make CSS and related markup more efficient and less intrusive to improve the themer experience.

The CSS Clean-up Process

Use the following guidelines when writing patches for the core issues listed below.

Put CSS is in the appropriate file: CSS should be moved to separate files, using the following name spacing conventions based on their purpose:

module.base.css

Should hold structural and behavior related styling. CSS should be coded against the Stark theme. The absolute bare minimum CSS required for the module to function should go here. If there is no CSS required, this file should be omitted.

module.theme.css

Should hold generic design-related styles that could be used with Stark and other themes. It's where all design assumptions like backgrounds, borders, colors, fonts, margins, padding, etc, would go.

module.admin.css

Should hold styles that are only applicable to administrative pages.

To see an example of this in practice, look at Drupal's system module.
Remove Assumptions: Styles that make too many assumptions, introduce superflous margins, padding and add things like font settings are not necessary and don't belong in core module CSS files. In cases where core themes depend on these properties, they should be moved to the CSS stylesheet of the respective theme.
Reduce Selector Specificity: CSS code that resides in modules should be written in a way that's easily overridable in the theme layer. To improve the Themer Experience and make core CSS more efficient, CSS selectors should be made as general and short as possible. For example:
- Use .style {} over div.style {} where possible.
- Use .module .style {} over div.module div.somenestedelement .style where possible.
Don't use IDs in selectors: Use of ID's in core CSS selectors requires more specificity in the theme layer, making it harder and more annoying to deal with. It makes achieveing consistency in complex design implementations much harder than it needs to be. We need to stop making life hard for theme developers.
Don't be afraid to change markup: There's lots of overlap between using proper and semantic markup and doing CSS right. If you come across a case where CSS is being applied where using a more semantic elements would solve the problem, then change the markup in your patch to make it right. For more information, see the Drupal 8 Markup Gate rules.
Start with Stark and cross-browser test.
1. "Design" markup and CSS for the Stark theme.
2. If applicable, adapt the styles to match the core themes afterward.
3. Finally, test the changes in all supported browsers and ensure no regressions are introduced.

Core Issues in Progress

The work to make this happen has been split into smaller tasks. There is currently an issue for each module as shown below:

Module Name	Actionable Issue
Aggregator	#1216948: Clean up the CSS for Aggregator module
Block	#1216950: Clean up the CSS for Block module
Book	#1216970: Clean up the CSS for Book module
Color	#1216972: Clean up the CSS for Color module
Comment	#1216976: Clean up the CSS for Comment module
Contextual	#1216978: Clean up the CSS for Contextual module
Dashboard	Removed from core ~~#1216980: Clean up the CSS for Dashboard module~~
Field	No Component
Field UI	#1216988: Clean up the CSS for Field UI module
File	#1216994: Clean up the CSS for File module
Filter	#1217000: Clean up the CSS for Filter module
Forum	#1217002: Clean up the CSS for Forum module
Help	#1217004: Clean up the CSS for Help module
Image	#1217006: Clean up the CSS for Image module
Locale	#1217008: Clean up the CSS for Locale module
Menu	#1217010: Clean up the CSS for Menu module
Node	#1217012: Clean up the CSS for the Node module
Open ID	#1217016: Clean up the CSS for Open ID module
Overlay	#1217030: Clean up the CSS for Overlay module
Poll	#1217032: Clean up the CSS for Poll module
Profile	#1217034: Clean up the CSS for Profile module
Search	#1217036: Clean up the CSS for Search module
Shortcut	#1217038: Clean up the CSS for the Shortcut module
Simpletest	#1217040: Clean up the CSS for Simpletest module
System (messages and menus)	#1217044: Clean up the CSS for System module
Taxonomy	#1217046: Clean up the CSS for Taxonomy module
Toolbar	#1217048: Clean up the CSS for Toolbar module
Tracker	#1217050: Clean up the CSS for Tracker module
Update	#1217052: Clean up the CSS for Update module
User	#1217054: Clean up the CSS for User module

Follow the Issues and Get Involved

Visit http://drupal.org/project/issues/subscribe-mail/drupal and
subscribe to "Own issues." This will ensure you get e-mail notifications
when replies are posted to the issues you're involved in.
Monitor issues in the CSS component tagged D8H5.
Follow @drupal8html5 for notification of all HTML5, markup and CSS new issues on Twitter.
To get help while working on these issues, join the #drupal-html5 IRC

channel.

Note: You must "follow" an issue to "subscribe" to it.