Add editor-style.css to _s? #1019

Closed
mrwweb opened this Issue Sep 16, 2016 · 15 comments

Projects

None yet

8 participants

@mrwweb
Contributor
mrwweb commented Sep 16, 2016

The editor-style.css file is far and away one of the best ways to improve a site editor's experience (at least in my experience). It makes TinyMCE much WYSIWYGier(TM) and helps users understand the connection between a theme and typography styles.

So in that vein, I'd love to see _s add editor-style.css by default to the theme. Thinking through this, I believe that would involve doing the following:

  1. Add add_editor_style(); to functions.php
  2. Add an editor-style.css file to the theme's root and include a brief description and link to documentation in a comment.
  3. Add an editor-style.scss file to the /sass/ folder that includes the same comments as above AND @imports helpful partials including:
    • everything in /sass/typography/
    • everything in /sass/elements/
    • everything in /sass/modules/
    • normalize
    • all requires mixins and variables partials to make the above compile

I've taken the approach in #3 with my own themes on multiple sites and have found a lot of success in autogenerating a nearly-complete set of editor styles. I don't know the _s SASS setup that well, so some input on that would be useful.

I thought a discussion would be worthwhile before submitting a pull request, so please let me know what you think. As far as I can tell, this hasn't been considered before.

@josephfusco
Contributor

Looks like this was considered before but closed on the premise that there are no styles in this starter theme.

There was however no sass implementation when this PR was closed and believe that laying out the sass structure you mentioned could be beneficial as it is not adding in any new styles. I personally use approach 3 you mentioned and always end up manually creating editor-style.scss importing all partials related to themes post styles.

@mrwweb
Contributor
mrwweb commented Sep 16, 2016

@josephfusco Glad to hear that strategy works for more than just me. Can you find the previous discussions? My initial searching didn't turn up anything.

In theory, I guess a pull could include the same styles in the non-SASS style.css, my only concern there is that it would add a third place that CSS needs to be updated frequently which feels like a losing proposition. I'm also seen people just include their full-site stylesheet as the editor style, but I don't think that works well in practice (it's bloated, and styles often assume markup that isn't in the editor, such as styling .site-content h2).

And just to look at other precedents, every Twenty XXXX default WordPress theme has shipped with an editor-style.css, so this is a clearly a core-blessed best practice.

@josephfusco
Contributor

Ref: #225

@valleyspirit

I politely disagree with @mrwweb that there is a precedent. This is not a default WordPress theme designed to be loaded up and evaluated for style by hundreds of thousands of people, like a Twenty-[yearXX] theme. This is not even an end-user theme. For me personally, Underscores is no more supposed to improve a site editor's experience than it is to improve a site reader's experience, and I certainly don't want to start seeing readability/legibility styles, complete with fonts, put into the underscores templates. That's not what it is. It's wall framing for your house, not living room paint nor pre-packaged bathroom fixtures. It is not supposed to provide an idealized editor page, any more than it is supposed to provide an idealized full-width content presentation.

I like the current intent of this project, and I hope the team does not add anything else that (for instance...) I would have to rip out (whether entire sass files or sass fragments or css file fragments) to use bootstrap or another front-end aesthetic.

This is an awesome style-agnostic theme skeleton! Yay. Thanks, everyone, for the work. I am only here because I am actually pulling styles out of Underscores today. Don't put any more in, hehe. Pretty please.

@mrwweb
Contributor
mrwweb commented Sep 29, 2016

Just to clarify my thinking:

  1. I've always viewed _s as a set of best practices meant to create the best possible theme. I think the best possible theme includes an editor-style.css. Just like _s includes a blank screenshot.png, I think there is value in creating a placeholder that a theme author should deal with.
  2. The goal is to not add extra styles, only pull in existing styles from other SASS sheets. My gut says to leave the editor-style.css blank, even though that would mean it's inconsistent with the SASS branch.

Considering those two points together, I think that very much fits in with the "framing" metaphor.

@valleyspirit

@mrwweb placeholders would be a great way to propagate best practices. I learned how to style the editor recently from another project based on this one, and I could easily have been taught how to do it properly by Underscores. I think that's very much in line with the framing metaphor.

I agree with your first two (original) points. However, if you go so far as to pull in styles from elsewhere, then I would strongly disagree with your intent, which is styling a skeleton. This is why you see precedent where there is none.

I think the sass/css which is here, should be minimal to achieve a layout that isn't smashed together and that is readable enough to proceed to style. I don't think Underscores' styles should be some minimalist aesthetic that we should also apply to the editor. There should be no aesthetic intent. I think styles here should only exist to the extent that the architecture is defined in the best way. Which would be entirely contrary to pulling in styles from elsewhere to "style" something that is entirely present and usable.

I entirely support the first two thirds of your goals here, but the third pains me greatly as an architect. Why don't we just leave comments in the css/sass file clarifying intent? This would be similar to the internationalization guidance.

@msroberts

Could you create an editor-style.scss that just imports modules/alignments and media/media (and any necessary variables and mixins), so that WordPress' built-in image alignment classes and galleries will work the same way they do in the theme?

@josephfusco
Contributor
josephfusco commented Sep 29, 2016 edited

We decided not to include translations [#50] beyond the existing _s.pot file, a RTL stylesheet [#263], or editor styles [#225], as they are likely to change during development of an _s-based theme.

Seems like there are some inconsistencies with what is stated in CONTRIBUTING.md and what actually exists in the project.

There is a placeholder rtl in the project but no placeholder editor-styles.css/editor-styles.scss like what is being suggested.

@msroberts Yes something like this:

/* Used to style the TinyMCE editor. */

/*--------------------------------------------------------------
>>> TABLE OF CONTENTS:
----------------------------------------------------------------
# Normalize
# Typography
# Navigation
    ## Links
# Alignments
# Clearings
# Media
    ## Captions
    ## Galleries
--------------------------------------------------------------*/
@import "variables-site/variables-site";
@import "mixins/mixins-master";

/*--------------------------------------------------------------
# Normalize
--------------------------------------------------------------*/
@import "normalize";

/*--------------------------------------------------------------
# Typography
--------------------------------------------------------------*/
@import "typography/typography";

/*--------------------------------------------------------------
# Navigation
--------------------------------------------------------------*/
@import "navigation/links";

/*--------------------------------------------------------------
# Alignments
--------------------------------------------------------------*/
@import "modules/alignments";

/*--------------------------------------------------------------
# Clearings
--------------------------------------------------------------*/
@import "modules/clearings";

/*--------------------------------------------------------------
# Media
--------------------------------------------------------------*/
@import "media/media";
@mrwweb
Contributor
mrwweb commented Sep 29, 2016

That seems about right. Again, the main goal is to give developers a starting point but not make any decisions for them. (Hence probably the suggested differences between the SCSS and CSS versions.)

I want to take a closer look at @josephfusco's suggestion, but it's definitely headed in the direction I imagined

@karmatosed
Member

I would vote against this as the editor-style should heavily be generated from styles of the theme. As _s is meant to not be a styled theme just a starting point, it makes a lot of sense to not include one.

@karmatosed karmatosed closed this Dec 23, 2016
@mrwweb
Contributor
mrwweb commented Dec 25, 2016

@karmatosed, you write:

_s is meant to not be a styled theme just a starting point

The proposed solution in this issue was precisely that:

  1. It did not involve writing any new CSS. (Any output CSS would be duplicate CSS from existing styles that are already seen fit for inclusion in _s.)
  2. This was explicitly about providing a good "starting point" while not making decisions. (This is exactly like the inclusion of screenshot.png and rtl.css. Both files are included with no content but provided because they should be included in a good theme.)

It feels like you misunderstood what I was suggesting—which is understandable given previous Issues and PRs about editor-style.css—but could you please reconsider and respond to the ideas raised here?

Based on your comments, I do not understand why this issue was closed and how including an **empty ** editor-style.css (and skeleton .scss) is inappropriate for _s. The feedback up to this point was both constructive and positive.

@jrfnl
Contributor
jrfnl commented Dec 25, 2016

Please reconsider. I too believe that having a skeleton editor-style.css file will be a good thing as it draws attention to the fact that themes should provide one.

@David-Brown

+1 for reconsidering this. As noted above, this is an important (arguably critical) element for any custom theme, and placing it into _S is an important starting point for theme developers. What's been suggested here isn't opinionated, it's merely part of the overall architecture of a good theme, which is what _S is intended to be.

@mrwweb
Contributor
mrwweb commented Dec 28, 2016

Further reason for reconsideration: CONTRIBUTING.md says:

We decided not to include translations [#50] beyond the existing _s.pot file, a RTL stylesheet [#263], or editor styles [#225], as they are likely to change during development of an _s based theme.

A close reading of the above highlights a few things:

  1. "Editor styles" likely means CSS styles for the editor, not an empty/skeleton editor-style.css
    file
    .
  2. #225 was about adding CSS styles and was closed because those styles were rather opinionated and the ticket was veering off-topic.
  3. Underscores appears to have always had an empty rtl.css. This is exactly what I'm proposing for editor-style.css .

Either the proposed change is in scope or the stated reasons for not having an empty starter file need clarification. Either way, CONTRIBUTING.md needs clarification. I'm happy to get the ball rolling, but need confirmation that the PRs will be considered.

Reminder of the point: Including an empty starter file will teach people about Editor Styles, remind developers to include them by making it easier to start, and improve the UX for themes that wouldn't have otherwise had an editor-style.css file (of which I am sure there are many).

Since I can't re-open this issue, can someone with those powers do so? @karmatosed @kovshenin @davidakennedy @philiparthurmoore @obenland

@samikeijonen
Contributor

+1 from me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment