"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", blockquote: "blockquote", code: "code", em: "em", h2: "h2", h3: "h3", h4: "h4", h5: "h5", li: "li", p: "p", pre: "pre", strong: "strong", ul: "ul", ...props.components }; return _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["For the last few months while at ", _jsx(_components.a, { href: "https://gatsbyjs.org", children: "Gatsby" }), " I've been working on ", _jsx(_components.a, { href: "https://www.gatsbyjs.org/blog/tags/themes", children: "Gatsby Themes" }), ".\nAs a result of this work I've been thinking about what the future of \"styling themes\" might look like. I.e., what's the best set of tools to use\nand how we can standardize around forward-thinking conventions. I don't think this necessarily requires us to predict the future but it's also\nimportant to find an approach that steers folks towards the pit of success, increases flexibility/interoperability, and minimizes tech debt."] }), "\n", _jsx(_components.p, { children: "Through this process I've done a large amount of research, experimentation, and analysis which I've (incompletely) documented below.\nThis was done for Gatsby Themes, but most of it should be applicable to other frameworks and tools as well." }), "\n", _jsx(_components.h3, { id: "-a-lay-of-the-land", children: _jsx(_components.a, { href: "#-a-lay-of-the-land", children: "📡 A lay of the land" }) }), "\n", _jsx(_components.p, { children: "To get started it's important to describe what questions I was seeking to answer:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "How can we standardize on a set of conventions that is both intuitive and productive for theme authors?" }), "\n", _jsxs(_components.li, { children: ["How can we make it ", _jsx(_components.em, { children: "simple" }), " to make theme modifications?"] }), "\n", _jsx(_components.li, { children: "What is an acceptable learning curve?" }), "\n", _jsx(_components.li, { children: "What's the best fit?" }), "\n"] }), "\n", _jsx(_components.p, { children: "It's important that theme styling is robust, flexible, and composable. After all, it's realistic to expect Gatsby sites to compose multiple\nthemes and we want that process to be the best that it can possibly be. Standardizing some type of convention or set of conventions will ensure\nthat themes which \"opt in\" will typically be composable with each other without issue." }), "\n", _jsx(_components.p, { children: "Another interesting thing is we need a way to allow users to productively build two types of component classes: application UI and content. Their\nconcerns are related, and in the perfect world, will draw from the same design system, but their implementations often diverge in practice." }), "\n", _jsx(_components.h2, { id: "bem-or-bem-like", children: _jsx(_components.a, { href: "#bem-or-bem-like", children: "BEM or BEM-like" }) }), "\n", _jsx(_components.p, { children: "I originally came to the scene during the Less/Sass and Bootstrap era and built numerous production apps with Bootstrap and custom themes (many of which I built from scratch).\nIt was wonderfully powerful how you could build UI quickly but always snowballed out of control. Always. Custom styling required complex\nconfiguration and inevitably required insane selectors. It was brittle and you were left feeling like you were fighting the framework." }), "\n", _jsx(_components.p, { children: "Not to mention, it often became difficult to keep things consistent. CSS often became riddled with magic numbers and one-off styles that\nmade entire components unable to be reused. With themes this style approach is untenable. It's impossible to know what themes will conflict\nwith each other and we need something that's more expressive." }), "\n", _jsx(_components.p, { children: "This style approach is also something that theme authors can pursue if they like, it doesn't make sense to be used as \"The Gatsby Way\"." }), "\n", _jsx(_components.h3, { id: "an-experiment", children: _jsx(_components.a, { href: "#an-experiment", children: "An experiment" }) }), "\n", _jsxs(_components.p, { children: ["Nevertheless, CSS has some powerful new features like ", _jsx(_components.a, { href: "https://developer.mozilla.org/en-US/docs/Web/CSS/--*", children: "custom properties" }), ", so we\nshould at least give it a shot."] }), "\n", _jsxs(_components.p, { children: ["So Brent Jackson and I began building a collection of blog themes that used them. The motivation was that\nif it's plain CSS it might be more accessible to folks. However, custom properties were difficult because they looked cryptic\nand we ended up with ", _jsx(_components.code, { children: "gatsby-theme-blog-dark" }), " that was essentially nothing more than an export of overridden variables:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-css", children: ":root {\n --background-color: black;\n --color: white;\n\n --p-line-height: 1.6;\n\n --table-th-border-top: thin solid;\n --table-th-border-bottom: thin solid;\n --table-th-border-color: #444;\n --table-th-background-color: #333;\n --table-th-font-size: inherit;\n --table-th-color: white;\n --table-th-font-weight: 600;\n --table-th-padding: 10px;\n\n --table-td-border-top: none;\n --table-td-border-bottom: thin solid;\n --table-td-border-color: #333;\n --table-td-font-size: inherit;\n --table-td-font-weight: inherit;\n --table-td-padding: 10px;\n\n --blockquote-font-size: 36px;\n --blockquote-color: #ccc;\n\n --pre-background-color: #333;\n --pre-padding: 20px;\n}\n" }) }), "\n", _jsx(_components.p, { children: "Not to mention this is susceptible to clashing with other themes.\nThemes can introduce their own variables that clash with others, and not to mention,\nthe load order can potentially affect the CSS order on the page.\nNon-determinism like this is problematic." }), "\n", _jsxs(_components.p, { children: ["The good part about this experiment is it did start to really\nbring home that themes can often boil down to key value pairs, and seemed to lend itself to something JS object-based.\nIt was also cool to be able to ", _jsx(_components.em, { children: "very" }), " quickly crank out multiple themes with drastically different styling in a matter of minutes."] }), "\n", _jsx(_components.h2, { id: "functionalatomicutility-css", children: _jsx(_components.a, { href: "#functionalatomicutility-css", children: "Functional/atomic/utility CSS" }) }), "\n", _jsxs(_components.p, { children: ["I rode the functional CSS bandwagon for quite some time\n(", _jsx(_components.a, { href: "https://github.com/stubbornella/oocss", children: "OOCSS" }), "/", _jsx(_components.a, { href: "https://suitcss.github.io/", children: "SuitCSS" }), "/", _jsx(_components.a, { href: "http://basscss.com", children: "Basscss" }), "/", _jsx(_components.a, { href: "https://tachyons.io", children: "Tachyons" }), ")\nand even co-authored a popular library. I had come to prefer it to other approaches for styling components. The lessons and\nconcepts that arose from this new styling approach were interesting (some even unexpected):"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Performance by default is important" }), "\n", _jsxs(_components.li, { children: ["Responsive design was ", _jsx(_components.em, { children: "fun" })] }), "\n", _jsx(_components.li, { children: "Many folks were very unhappy with existing approaches" }), "\n", _jsx(_components.li, { children: "Concepts were quick to grasp for newcomers to web development" }), "\n", _jsx(_components.li, { children: "Style composition is best at the component level and made prototyping in the browser unbelievably quick" }), "\n", _jsx(_components.li, { children: "Design system constraints are powerful (and developers love them)" }), "\n"] }), "\n", _jsx(_components.p, { children: "One of my favorite parts is the constraint-based system and the ability to rapidly design responsive components. Working with\nmedia queries when designing in the browser is high friction (IMO) and the colocation of markup, styles, and breakpoints creates\na workflow that's amazing." }), "\n", _jsx(_components.p, { children: "It removed a lot of the cognitive overhead when designing in the browser and everything fit a predictable pattern. No longer did\nI have to remember what the second step of my spacing scale is or how to change the padding for large viewports. No longer did I\nhave to open up a CSS file and develop with two files simultaneously." }), "\n", _jsx(_components.p, { children: "Of the approaches discussed so far I think it's the first that has potential. However, class composition feels really awkward with\ncomponents and there's a lot of duplication because making components a \"bag of props\" requires handwaving and indirection. Especially\nwhen a prop or variant causes multiple style changes. For example:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "import classNames from 'classnames'\n\nexport const ListItem = ({ variant, children }) => {\n const cx = classNames('pa3 bb b--light-silver', {\n 'o-80 strike mid-gray bg-near-white': variant === 'done'\n })\n\n return

\n}\n" }) }), "\n", _jsxs(_components.p, { children: ["Above, the ", _jsx(_components.code, { children: "variant" }), " property is a nice component API so when your list item is completed you can do something like\n", _jsx(_components.code, { children: "" }), ". However this prop results in multiple changes in styling that map to multiple utility\nclasses. And I know what a few of you are probably saying right now, \"use ", _jsx(_components.code, { children: "extend" }), "\", but you're going to bloat your stylesheet\nand have too much potential for namespace clashing."] }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "Functional CSS is a wonderful abstraction over the design system but it's not a great abstraction over CSS and the DOM." }), "\n"] }), "\n", _jsxs(_components.p, { children: ["Ultimately, it's an awesome approach, but it's making developers do what tooling should do. They have to think like compilers\nto overcome CSS's shortcomings. Not to mention, functional CSS doesn't lend itself well to content heavy websites. You're forced\nto write global styles, ", _jsx(_components.code, { children: "extend" }), ", or created custom rendered components for elements that end up looking like\n", _jsx(_components.code, { children: "

" }), "."] }), "\n", _jsx(_components.h3, { id: "theming", children: _jsx(_components.a, { href: "#theming", children: "Theming" }) }), "\n", _jsx(_components.p, { children: "When it comes to theming in functional CSS, things also get interesting. The powerful part is that classes can be dynamically\ngenerated based on your design system tokens, however, composing themes becomes problematic. It really only operates at the\npage level because it's global CSS, and combining Gatsby Themes can still suffer from namespace clashing." }), "\n", _jsxs(_components.p, { children: ["If two themes bring ", _jsx(_components.code, { children: "bg-red" }), ", who wins?"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Advantages" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Generally applicable to the web even outside the React ecosystem" }), "\n", _jsx(_components.li, { children: "Responsive design is intuitive" }), "\n", _jsx(_components.li, { children: "Forces consistent UI via constraints" }), "\n", _jsx(_components.li, { children: "Can be generated by a theme at build time" }), "\n", _jsx(_components.li, { children: "Low-likelihood of class collisions and specificity issues" }), "\n", _jsx(_components.li, { children: "Seeing widespread adoption (even in Bootstrap now)" }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Disadvantages" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Working with class composition in components is cumbersome" }), "\n", _jsx(_components.li, { children: "One-off styles (common in App UI) are difficult" }), "\n", _jsx(_components.li, { children: "Styles/classes are still global" }), "\n"] }), "\n", _jsx(_components.h2, { id: "css-modules", children: _jsx(_components.a, { href: "#css-modules", children: "CSS Modules" }) }), "\n", _jsx(_components.p, { children: "CSS Modules are an interesting candidate. It helps reduce a lot of issues with the global namespace in CSS and it works out\nof the box with Gatsby." }), "\n", _jsx(_components.p, { children: "It does make things unclear sometimes. For Gatsby in particular you're left wondering, should I shadow the CSS file or the component?\nIntroducing another state might even require you to shadow both files. Additionally, when it comes to handling dynamic styling, it's\ntypically achieved through adding and removing a particular class. This is relatively intuitive for web developers but feels like a\nbit of indirection in the React ecosystem." }), "\n", _jsx(_components.p, { children: "Having it be \"just CSS\" is a huge win, though. Entire collections of themes could be built by mostly writing new CSS files for standardized\ncomponents." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Advantages" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Small learning curve" }), "\n", _jsx(_components.li, { children: "Wealth of documentation because it's CSS" }), "\n", _jsx(_components.li, { children: "Solves issues with global namespacing" }), "\n", _jsx(_components.li, { children: "Built into Gatsby" }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Disadvantages" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Multiple files are required (but less of an issue with file colocation), makes component shadowing more cumbersome" }), "\n", _jsx(_components.li, { children: "Theming is more difficult and styling can quickly become inconsistent without rigorous code reviews or tooling" }), "\n", _jsx(_components.li, { children: "Composition of rulesets is handled in CSS" }), "\n", _jsx(_components.li, { children: "Class name dance is clunky" }), "\n", _jsx(_components.li, { children: "Doesn't lend itself well to a WYSIWYG" }), "\n"] }), "\n", _jsx(_components.h2, { id: "css-in-js", children: _jsx(_components.a, { href: "#css-in-js", children: "CSS in JS" }) }), "\n", _jsx(_components.p, { children: "CSS in JS is a controversial topic in web development, and for good reason, too. It's radically changed the way folks think about styling\nand removes some of the less desirable parts of CSS via tooling." }), "\n", _jsx(_components.p, { children: "I'm not going to go into defining what CSS in JS is since there are plenty of resources out there that do that. I'll be focusing on what it's\nimplications are for theming websites and apps." }), "\n", _jsxs(_components.p, { children: ["In a lot of ways CSS in JS is a better fit for React's compositional model since it abstracts away the ", _jsx(_components.code, { children: "

Styling themes