default styles have too many styles, styling doesn't match docs

[joyously]

According to https://wordpress.org/gutenberg/handbook/extensibility/theme-support/
there are some styles that come with blocks. "By default, blocks provide their styles".

Then the list of "Opt-in features" is

• wide alignment
• Wide Alignments and Floats
• Block Color Palettes
• Block Font Sizes
• Disabling custom font sizes
• Disabling custom colors in block Color Palettes

These last ones seem to contradict each other. How do you opt-in to disable something that is opt-in?

This is the real problem:

Core blocks include default styles. The styles are enqueued for editing but are not enqueued for viewing unless the theme opts-in to the core styles.

This is not what happens. There are styles in build/block-library/style.css that contain colors and font sizes that are shown in the editor and on the front end. They override my theme styles, and the theme does not opt-in to any of the new things.
Searching for 'color' in the style.css file shows at least 100 matches (a bunch of which are the definitions of classes for colors). There are 38 font-size matches. Some are the definitions of font sizes, and those should not be defined in pixels.

There should be no colors, no font sizes, no padding or margin, no text alignment, no text transform that affects blocks. I understand that the editor elements should be styled, but the blocks themselves should not be styled.

I am seeing colors for table striping, button background, pull quote text, figcaption, code background, cover image text, download button text, comment date, post date.
I see font-sizes for figcaption, button text, cover image text, download button, comment text, comment date, post date, paragraph text, pull quote text.

[DarinkaDesign]

I fully support this. Right now I must override block styles with !important and this is a mess. It is !important that the blocks have the least styles, if any. My theme provides styles that simply cascade into the blocks.

[joyously]

Joen said:

elaborate on what the harm is to the user or developer based on the current system

The harm is the thousands of existing themes that are styling HTML elements, not blocks, will not look right as soon as the user updates and creates a new post. Their site will not be consistent in itself.
For instance, if my theme uses a purple background color with yellow text, and I add a table with striping, the style uses a gray background color for the row, but you can't read my yellow text with that.

The theme should not have to be updated to play nice with a new editor. The editor is outputting HTML just like the old editor did. The theme is styling the HTML. The new styles should not override what the theme is already doing.

If the project has to have styles with colors, font sizes, etc. then it should all be in one style sheet that can be opt-in. As it stands now, a theme has to try to opt out, but the styles are so mixed in the theme has to override too much. At the very least, the separation of styles between block styles and editor element styles should be complete (two separate files).

[jasmussen]

Thanks for the followup. (For others readon, Joy is referring to a conversation we had in Slack here).

I asked for elaboration because I too want to make sure editor styles, theme styles and frontend styles play nicely with WordPress themes, new and old. I have made countless pull request to fix issues and bugs around this, to make sure the theme developer is empowered to make something great.

So I think we strongly agree on the overall goal, which is to make sure themers have control. And I volunteer my services to help improve this situation.

However in order to be able to submit pull requests, I need to act on specific issues.

For example, you mention "new styles should not override what the theme is already doing". To address issues around this there are a number of issues around CSS specificity:

• Front-end style.css specificity audit #11779
• CSS should not use :not #11677
• Custom editor styles on element selectors effect block control styles.  #10178
• Editor stylesheet CSS specificity issues #10067

To the larger issue around what is the role of Gutenberg and what is the role of the WordPress theme, there's also this meta ticket: #9534

As a blanket statement, I do not agree that Gutenberg should provide zero CSS at all, unless the user opts in. There are a number of reasons for this:

• The Cover block is entirely new and custom, no WordPress theme is aware of it. Without some structural CSS, it's not going to work at all.
• You mention "I am seeing colors for table striping" — this is a table variation, which means that only if the user selects that variation, will the table show up striped. The default table should be fully styled by the theme. If this striped variation is moved to theme.scss, a user might expect a striped table on the front-end to match what they are seeing in the backend, and be confused when the stripes are not present. The solution here is not to remove those stripes, but to offer theme developers more control over the variations present. See 🖍 A Block Style System #9534 for that.
• The figcaption element has not traditionally been used for styling captions in WordPress themes. Because of this, it's essentially new markup, which means that we style the captions to match that of the vanilla stylesheet in the editor. Otherwise the caption would, in most themes, just look like a broken paragraph that follows after an image. More context here.

As with all things Gutenberg, things will evolve and be revisited as we go, and as we learn what works and what didn't. But the above is context for why it's not as simple as it might sound on the face of it.

The way we improve this is by pull requests, and the best pull request is small and specific and as noted, I'd love to help here. What issues are not yet ticketed separately, that I may start to address?

[joyously]

I do not agree that Gutenberg should provide zero CSS at all

Well, I never said that. I said that it should not style the common things that themes style like colors, font size, padding, margin. It should use whatever the environment provides for how the HTML looks. I'm referring to blocks, not editor UI elements.

The Cover block is entirely new and custom, no WordPress theme is aware of it. Without some structural CSS, it's not going to work at all.

That's not true. I started by looking at GB posts in 4,9,8 without GB. I wanted the users of my theme to be able to try GB and have blocks, but if they decided to not use GB, it would still look okay. So even before I added styles, the cover blocks were okay, because the background image is in a style attribute and the text is on top of it. I can add padding and min-height and font-size, but it isn't necessary.
Besides, structural CSS is for style.css. The other should be in theme.css.

table striping — this is a table variation

Yes, but I had a block with that in order to test, and it was styling it with colors that have nothing to do with my theme colors. If it's there at all, it should be in theme.css, not style.css. And it should be faint rgba gray, not plain gray. But my theme already stripes the tables by default, so it should be opt-in because it's the new thing. Existing themes can already have that.

If this striped variation is moved to theme.scss, a user might expect a striped table on the front-end to match what they are seeing in the backend

It makes no sense to say that "what you see is what you get", but only if your theme opts-in to the front end. If theme.css is optional, it should apply to both back and front. So it should not be loaded unless the theme opts-in. How else can the theme make it match? Does it make sense for the theme to have to overcome theme.css styles in the editor, to match the front where they aren't loaded? Why make it so hard? The editor is just the place to enter content. It shouldn't be concerned at all with how it looks.

The solution here is not to remove those stripes, but to offer theme developers more control over the variations present.

I disagree with this. The solution is for the editor to stick with adding and removing classes, and letting the themes and plugins supply the CSS for those classes.

The figcaption element has not traditionally been used for styling captions in WordPress themes.

This is untrue. I have reviewed a lot of themes. Most style every HTML element, especially if they use some sort of reset CSS. The editor isn't doing something new. It's just HTML. It looks fine even if unstyled. But that is not the concern of the editor!

What issues are not yet ticketed separately, that I may start to address?

As I said in the original post, the biggest problem is that what the docs say doesn't match what happens. I think it's because the styles ended up in style.css instead of theme.css. So if they are to remain, they should be separated. I would urge you to consider that theme.css should be consistently applied. Whether it is opt-in or opt-out, it should be the same on front and back end. I would vote for opt-in, so that people that start creating posts with blocks won't have a quirky mixture of styles on their sites that they can't control. They might have to change themes or modify their child theme, but they shouldn't be forced to do that just to get rid of those styles.

[CalumChilds]

My editor-style.css file for my custom theme contains the same rules as my main style.css file but it contains !important at the end of each line. Why?

[prodancer2015]

I am going to inject some comment here about this, because I think it has merit to what everyone is experiencing and saying. See my current post at WordPress.org about the annoyance of Gutenberg / WordPress 5.0 on image captions.

https://wordpress.org/support/topic/image-caption-poorly-placed-on-page-gutenberg-annoyance/

With the response of the moderator in that post string, saying that the image caption and image are, by default, centered per Gutenberg's specs. That by default, it render the same way on a published page.

My post includes screenshots, where I created a new page, inserted a title, basic text then an image below it with a caption "image caption", using No additional styling.

The image was aligned left, the caption was middle of the page which was really offset and not aligned with the image.

Based on what the moderator said about the WordPress 5.0/Gutenberg default, the image and caption are apparently to be center on the page. If that is the case, then the "defaults" for Gutenberg/WordPress 5.0 are over-riding the standards & defaults of CSS3. By over-riding the CSS3 standard defaults for elements, Gutenberg is essentially acting in place of the theme when it shouldn't.

Example, these are the CSS3 alignment / styling standards-defaults of the following elements,

• DIV's - width is 100% on the page,
• Figure tag - width is 100% & has margins
• Image is aligned left, width is per the image width.
• Figcaption - width is 100%, has no margins, text inside a figcaption tag are align left,
• P tag text is align left, width of P tag is 100% per its parent, in this case the figcaption tag.

Per the CSS3 standard, the image and text are never aligned center by default. To align text and images to center requires CSS styling added to the mix.

What does this say?

It says that WordPress 5.0 is creating a huge headache by stepping over the CSS3 standard/defaults. This will create a huge issue with countless WordPress sites where the content was published using CSS3 default alignments and styling because now Gutenberg is acting in place of a theme which it should never do.

The concept of a block page builder is an attempt by WordPress to compete with the growing popularity of Page builders like WP Bakery, Elementor, etc. In doing so, they have completely lost sight of what a WordPress editor is suppose to be and do.

At no time should the WordPress editor start adding different styling, automatically, that supersedes or ignores CSS3 defaults. Any styling beyond the CSS3 defaults is done by the user or theme developer.

This means, taking the image and caption example, the editor has to provide, by default, both image and caption to show per CSS3 defaults, which means align left. Then a WordPress user or theme developer can work from that base-line standard to make changes to element styling using the editor (WordPress user) or using the theme (theme developer).

... but they can't now because WordPress 5.0 has screwed with the CSS3 standard. The headaches and extra work this injects into using WordPress is astounding, all because WordPress wanted to compete against page builders.

What should WordPress do to make Gutenberg work?

Rewrite all of it, get back to the standard and don't screw with the standard. Leave the extra styling to the user to how they want the image to appear on the page and let the developers work their theme, but all of them will be working from the SAME standard, the CSS3 standard.

[m-e-h]

Per the CSS3 standard, the image and text are never aligned center by default. To align text and images to center requires CSS styling added to the mix.

Excellent point and it goes along with a suggestion I've been wanting to open a discussion on.
Styles like this should be "opt-in" via add_theme_support( 'wp-block-styles' ).

The "default" styles should only include those needed for function and layout. Opinionated styles should be used only when necessary so that older themes don't have a broken layout.

text-align: center is about as unnecessary and opinionated as it gets. If it needs to exist at all it should probably be in theme.css.

[pattonwebz]

I also vote that only structural elements of a block, that are particular components of a specific block layout, be styled by default.

Any overrides of expected defaults, such as formatting tables with visible styles or centring text because it looks better, should be opt-in. The new editor is not a place to put opinionated style rules because those opinions should, in almost all cases, be decided by the users and not enforced on them by the editor.

[joyously]

Actionable: start by removing the color styles, especially for caption text.

See this forum topic: https://wordpress.org/support/topic/edit-wp-with-white-on-white-and-black-on-black-text/

[m-e-h]

A simple solution to most issues related to specificity or opinionated styles will be CSS Custom Properties.

There's no <=IE11 support but I see no reason why we couldn't go ahead and have the variables in place. Browsers that don't support Custom Properties will just ignore them and use the fallbacks we have there now.

I'm currently doing something like this in my CSS:

:root {
    --color-text-muted: #868e96;
}
.wp-block-image figcaption {
    color: #868e96;
    color: var(--color-text-muted);
}

To override that you would just do something like:

.site {
    --color-text-muted: #eee;
}

Specificity and opinionated styles become a non-issue. (for non-IE browsers)

[joyously]

@m-e-h I would love to see Custom Properties used! But it doesn't quite solve the problem for styling things that shouldn't be styled by the editor (think of legacy themes displaying new block posts). If the opinionated styles were moved from style.css to theme.css, though, it would help a lot. That's what this issue is about.
Can you submit a PR?

[CalumChilds]

About the Custom Properties. It isn't supported in IE11. Also, I thought we were meant to be minimising the amount of CSS that we used.

[jasmussen]

Thanks for the suggestion. I had gone to weekend when the tip came in, but I'm back in my seat and there's a PR in #14366.

[m-e-h]

You're right @joyously. Custom properties would do nothing to help existing themes. Or any theme really since it's browser support is still around just 90%.
I have too many similar tickets. I'm starting mix up solutions 😄

@jasmussen That's awesome! Hopefully similar moves to theme.css can be made for other opinionated styles.

[benlk]

Agreed with the suggestions to separate structural/layout styles from styles about font/color/line-height/. Can we go a step further and break up wp-includes/css/dist/block-library/style.min.css into per-block stylesheets that can be enqueued/dequeued as necessary?

The use case I see is a theme that has its own styles for the Cover block, and so wants to dequeue Core's styles for that block, but doesn't have custom styles yet for the Gallery block, and so wants to keep using Core's styles for that block.

Right now, the theme's options are:

• Don't enqueue Core's stylesheet — leaves blocks potentially unstyled
• Enqueue and selectively override Core's stylesheet — mass style duplication, but at least blocks are styled
• Don't enqueue Core's stylesheet, but somehow incorporate Core's style source files in the theme's stylesheet build process (assuming that the two are of a compatible language), and then piecemeal remove the included Core files from the theme's dev process — not a realistic scenario for most theme devs

[idea--list]

Just modernized a theme i bought on *****forest by making a child theme to be compatible with GB. Used the latest Theme Unit Test data to compare the looks in back-end and in front-end.
First i was bit confused why the looks of some block parts simply do not match up as i styled everything as usual. Then i noticed this deeply buried wp-includes/css/dist/block-library/style.min.css file that simply overrides some parts.
Among other things it also overrides the text color set for a cover image block by defining this css rule:
.wp-block-cover p {color:inherit}
Also the cite size of the large styled quote block is overridden by .wp-block-quote.is-style-large cite{font-size: 18px;text-align: right;}

[idea--list]

What if WP would watch in the background and in case a new theme gets activated a server-side script would parse through any .css file of the theme to evaluate which html tags and GB classes have defined rules in the theme/child theme and in such cases copy those rules.

Then also evaluate style.min.css and take from that file only rules for such elements, that have not been styled within the theme.

As a last step build a new .css file that is a merged output of the 2 above described processes and add_theme_support( 'wp-block-styles' ); should enqueue this individualized .css file?

I also could imagine going one step even further and do something similar for the editor styles in the back-end and ultimatively get rid of the need for a separate add_theme_support( 'editor-styles' ); command as if a theme needs to opt-in for front-end chances are about 100% it also needs to opt-in for back-end. So why not simplify it with also 1 line of add_theme_support that combines all these features in the background?

I know it is probably quite different from that what is currently implemented but that way we could avoid css rule duplicates, unwanted and unexpected overrides, and also an opt-in that is currently splitted up in 2 steps.

[joyously]

What if WP would watch in the background and in case a new theme gets activated a server-side script would parse through any .css file of the theme to evaluate ...

Because that's hard to do and there are rules added dynamically, depending on the page and depending on the options the user chooses.

[joyously]

Does this project use a linter for CSS? If so, could there be rules to disallow certain properties in the style.scss files, like color, font-size, text-align, background-color, maybe even padding and margin? These would all be allowed in theme.scss.
If not, can we add this?

One of the other specific rules that needs moving is .wp-block-calendar table { font-family: xxxx}. The calendar block also has a white header and white borders and black text. This would all be fine, but it doesn't specify the background color, so all those color styles need to move to theme.scss.

thead tr, tr:nth-child(2n) {
    background-color: rgba(120,120,120, 0.04);
}
.wp-block-calendar table th {
    font-weight: 400;
    background: #edeff0;
}
.wp-block-calendar th, .wp-block-calendar tbody td {
    padding: 4px;
    border: 1px solid #e2e4e7;
}
.wp-block-calendar th, .wp-block-calendar tbody td {
    padding: 4px;
    border: 1px solid #e2e4e7;
}
.wp-block-calendar table tbody, .wp-block-calendar table caption {
    color: #40464d;
}

There is a color style and font-size style on the Latest Posts date.

.wp-block-latest-comments__comment-date {
    color: #8f98a1;
    display: block;
    font-size: 12px;
}

There are margins on the figcaption.

.wp-block-image figcaption {
    margin-top: 0.5em;
    margin-bottom: 1em;
}

The button styles are so difficult! Why was round made the default? The outline button style has colors and a particular border style.

.is-style-outline {
    color: #32373c;
}
.is-style-outline .wp-block-button__link {
    background-color: transparent;
    border: 2px solid;
}

But that only overrides part of the "default" button style. Imagine that the theme has a dark background and light text and an outset border style. The problematic part is the color and border and radius and font size and padding and margin and text-align. I still don't think there should be a Button block because that is bad semantics. Links should be identifiable as links, leaving buttons for scripts to use in forms.

.wp-block-button {
    color: #fff;
}
.wp-block-button__link {
    background-color: #32373c;
    border: none;
    border-radius: 28px;
    box-shadow: none;
    color: inherit;
    cursor: pointer;
    display: inline-block;
    font-size: 18px;
    margin: 0;
    padding: 12px 24px;
    text-align: center;
    text-decoration: none;
    overflow-wrap: break-word;
}

OMG! Cover block styles! This is a nightmare to override. What if the theme just uses text-shadow, and the color doesn't matter? Why does the editor have to interfere?

.wp-block-cover-image, .wp-block-cover {
    background-color: #000;
    min-height: 430px;
    align-items: center;
}
section.wp-block-cover-image h2, 
.wp-block-cover-image-text, .wp-block-cover-text {
    color: #fff;
}
section.wp-block-cover-image > h2, 
.wp-block-cover-image .wp-block-cover-image-text, 
.wp-block-cover .wp-block-cover-text {
    font-size: 2em;
    line-height: 1.25;
    z-index: 1;
    margin-bottom: 0;
    max-width: 580px;
    padding: 14px;
    text-align: center;
}
.wp-block-cover-image p:not(.has-text-color), .wp-block-cover-image h1:not(.has-text-color),
 .wp-block-cover-image h2:not(.has-text-color), .wp-block-cover-image h3:not(.has-text-color),
 .wp-block-cover-image h4:not(.has-text-color), .wp-block-cover-image h5:not(.has-text-color),
 .wp-block-cover-image h6:not(.has-text-color), .wp-block-cover-image .wp-block-subhead:not(.has-text-color), 
.wp-block-cover p:not(.has-text-color), .wp-block-cover h1:not(.has-text-color), 
.wp-block-cover h2:not(.has-text-color), .wp-block-cover h3:not(.has-text-color), 
.wp-block-cover h4:not(.has-text-color), .wp-block-cover h5:not(.has-text-color), 
.wp-block-cover h6:not(.has-text-color), .wp-block-cover .wp-block-subhead:not(.has-text-color)
 {
    color: inherit;
}

Gallery block captions are very opinionated. In my theme, I don't even attempt to restyle. But it shouldn't be that way. The figcaption style should apply equally across images and galleries. Please move the whole gallery figcaption style from style.css to theme.css. The selector is very specific: .wp-block-gallery .blocks-gallery-image figcaption, .wp-block-gallery .blocks-gallery-item figcaption, .blocks-gallery-grid .blocks-gallery-image figcaption, .blocks-gallery-grid .blocks-gallery-item figcaption

Media and Text block has width:100% on the image, which causes blurry images when small images are used. This shouldn't be moved to theme.scss, but removed entirely. See #17787.

The drop cap style has a font properties, that should be moved.

.has-drop-cap:not(:focus)::first-letter {
   font-size: 8.4em;
   line-height: 0.68;
   font-weight: 100;
   margin: 0.05em 0.1em 0 0;
}

The Quote block now has a class for default (didn't used to). The cite part is gray and small in the editor and not on the front end, so that should be moved.

The pull quote has some text-align and border and background:none and margin and padding.
This is in both editor.scss and style.scss: .wp-block-pullquote blockquote p { font-size: 28px; line-height: 1.6; }
And even though this is in theme.scss, it makes it obvious that the theme.css should be applied equally to editor and front end. Since my theme didn't opt in, I see it only in the editor, which means that the text can't be read since it's dark on dark (like the cite previously mentioned).
.wp-block-pullquote {color: #40464d;}

These are just the blocks that I have in the Theme Unit Test data. I'm sure there are others and will be more as we go along. That's why I am asking about some linting rules that could be applied to the project, so that these things are caught automatically.

[CreativeDive]

@joyously This is definitively a very big headage of the WordPress default styles for blocks like the button or cover block. But it seems there is nothing happened in the past. For example the outlined button can't have custom text color or background color, because the WordPress default style .wp-block-button.is-style-outline .wp-block-button__link, .wp-block-button__link.is-style-outline {} is still overrides the .has-x-color or .has-x-background-color. It's really a nightmare.

I think it's time for the gutenberg team to rethink this.

A solution especially for the outlined button default styles could be:

.wp-block-button.is-style-outline .wp-block-button__link, 
.wp-block-button__link.is-style-outline {
border: 2px solid;
}

.wp-block-button.is-style-outline .wp-block-button__link:not(.has-text-color), 
.wp-block-button__link.is-style-outline:not(.has-text-color) {
color: #32373c;
}

.wp-block-button.is-style-outline .wp-block-button__link:not(.has-background), 
.wp-block-button__link.is-style-outline:not(.has-background) {
background-color: transparent;
}

Instead of the current style:

.wp-block-button.is-style-outline .wp-block-button__link, 
.wp-block-button__link.is-style-outline {
color: #32373c;
background-color: transparent;
border: 2px solid;
}

This approach in the WordPress default block style would also solve other issues.

[kraftner]

I've personally come to the point where there really is no way around completely removing all core styles. It's already bad enough when you need to use !important but as soon as media queries come into play (like with the columns block) not even that will help. The simple use case of moving the breakpoints for the columns block is practically impossible.

But then you manually need to maintain all block styles on your own keeping them in sync with version updates which is hard.

What would be great is if those styles would be broken into pieces that can then be removed individually. So e.g. I can just remove the styles for anything related to the column block which is much less work to maintain.

(On a sidenote since I looked into building the /wp-includes/css/dist/block-library/style.css style myself with some changes - any pointers on how to do that? The build setup in https://github.com/WordPress/wordpress-develop confuses the hell out of me)

[kraftner]

Since I just came across this issue again - I've blogged about this some weeks ago:

https://kraftner.com/en/blog/understanding-wordpress-block-css/
https://kraftner.com/en/blog/building-your-own-wordpress-core-block-css/

Also something new has happened recently that might offer another angle to approach this - loading styles for blocks separately.
For this feature WordPress now includes separate stylesheets for core blocks. Maybe this can be used to at least selectively remove core styles for some blocks so when you're unhappy with them it isn't an all-or-nothing approach any more.

[joshlmaxwell]

Can we talk about everything changing with every update. HTML structure changing among other things. Gutenberg was meant for non-programmers to use, like my clients, but I fight to keep my clients out of Gutenberg because if they see broken blocks (broken because the markup changed in an update) they will blame me, and think my work is shoddy. If they click "attempt block recovery" and the front end breaks even a tiny bit, again, they blame me.

Seems like weekly there is a mysterious problem like cover backgrounds suddenly stretch to fit on mobile, that's new. I actually tell all my coworkers. never ever ever use covers, just make a group and give a it background with CSS, because covers can't be trusted. They have changed 3 times in the last 2 years, and I don't want to go though fixing them again.

I guess should I give constructive criticism.
Create an absolute opt-out for ALL boilerplate CSS

[CreativeDive]

@joshlmaxwell I'm all with you. It's very hard to keep up to date when a website is based on the Gutenberg editor. Things that break after every Gutenberg release, and the list of Github problems keeps getting longer. I think the Gutenberg project is too complex and it is very difficult for the Gutenberg team to keep track of everything.

We can only hope that things will get better quickly and that a stable basis will be found that is not constantly being reconsidered.