{"id":13630542,"url":"https://github.com/joe-bell/smoothie","last_synced_at":"2025-04-17T17:31:25.883Z","repository":{"id":57161156,"uuid":"135911653","full_name":"joe-bell/smoothie","owner":"joe-bell","description":"A deliciously scalable and adaptable stylesheet methodology 🍹","archived":true,"fork":false,"pushed_at":"2022-09-17T05:30:43.000Z","size":385,"stargazers_count":29,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-08T22:36:41.262Z","etag":null,"topics":["css","css-in-js","scss","style-guide","stylesheets"],"latest_commit_sha":null,"homepage":"https://smoothie-css.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joe-bell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2018-06-03T14:33:21.000Z","updated_at":"2024-05-08T15:38:46.000Z","dependencies_parsed_at":"2022-08-27T08:30:29.907Z","dependency_job_id":null,"html_url":"https://github.com/joe-bell/smoothie","commit_stats":null,"previous_names":["joebell93/smoothie"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joe-bell%2Fsmoothie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joe-bell%2Fsmoothie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joe-bell%2Fsmoothie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joe-bell%2Fsmoothie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joe-bell","download_url":"https://codeload.github.com/joe-bell/smoothie/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249359978,"owners_count":21257143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","css-in-js","scss","style-guide","stylesheets"],"created_at":"2024-08-01T22:01:46.543Z","updated_at":"2025-04-17T17:31:25.499Z","avatar_url":"https://github.com/joe-bell.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eSmoothie 🍹\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eA deliciously scalable and adaptable stylesheet methodology\u003c/strong\u003e\u003c/p\u003e\n\n\u003chr class=\"c-hr--large\"/\u003e\n\n\u003eNote: This methodology is still in its early days and may be subject to big changes\n\nThe current CSS landscape is **thriving** and overflowing with new concepts and\ntools, but this often leads to two scenarios:\n\n1. Where on earth do I start?\n2. How can I regularly experiment with new tools without having to completely refactor my existing project styles?\n\nSmoothie's high-level 3-layered architecture gives you the freedom to easily build and experiment with the CSS tool/s that **you** want to use.\n\n## Contents\n\n1. [Why?][why]\n2. [Architecture][arch]\n    1. [Tokens][tokens]\n    2. [Global][global]\n    3. [Components][components]\n3. [Recipes][recipes]\n4. [Standards][standards]\n5. [Tools][tools]\n6. [Built with Smoothie][built-with]\n7. [Resources][resources]\n\n---\n\n## Why? 🤷‍\n\nThe passionate debate around latest CSS tools/techniques can at times feel hostile and overwhelming. Certain methods may offer more advanced features but it mostly boils down to a matter of preference. \n\nSmoothie came about after feeling fed up with being told what is \"right\" or \"wrong\" when it comes to using CSS tools. Just because one method feels right for your project, it doesn't justify putting down the solutions of others.\n\nWhat I hope to bring with Smoothie is a middle-ground; the freedom and encouragement to experiment with tools/techniques to figure out what's right for **you**.\n\n## Architecture 🏗\n\nSmoothie splits your design into **3** key layers, imported in\nthe following cascade order:\n\n1. [**Tokens**][tokens]\n2. [**Global**][global]\n3. [**Components**][components]\n\nLet's break that down into more detail…\n\n### 1. Tokens\n\nTokens, or \"Design Tokens\" are an intrinsic collection of values that define\nyour project/Design System's visual language. This could include information\nsuch as:\n\n* Colours\n* Spacing\n* Typography - *e.g. font-size, line-height, scale*\n* Animation - *e.g. speed, easing*\n* Breakpoints\n* *etc…*\n\n**Tokens are preferably platform-agnostic and human-readable, stored in YAML/JSON.**\n\nHowever, for smaller projects, if you'd prefer to store your tokens in a single format that compliments your build process, that's totally fine. For example; if you're using SCSS you could use traditional variables/maps ([just be careful when it comes to CSS variables](https://medium.com/@stowball/css-variables-are-a-sometimes-food-f01dd24f51e8)), or if you're using a CSS-in-JS library you could store in a JS module. Choose a solution that works best for **your** needs.\n\nIf you're stumped on build processes, check out the [recipes][recipes].\n\n#### Examples\n\n* [Polaris Tokens](https://github.com/Shopify/polaris-tokens) - @Shopify\n* [Design Tokens](https://github.com/opentable/design-tokens) - @opentable\n* [Photon Design Tokens](https://github.com/FirefoxUX/design-tokens) - @FirefoxUX\n\n### 2. Global\n\nCSS is heavily criticised for its global scope—with common pain points including\nclashing selectors and specificity battles—but is it *actually* that bad?\n\n\u003cdetails\u003e\n  \u003csummary\u003eNo, it's really not that bad.\u003c/summary\u003e\n\n  For a start, we've been doing alright for 2 decades.\n\n  Global styles can be an incredibly powerful and efficient way of styling your\n  application; browser default styles can be reset or \"normalized\", base styles\n  can be defined (fonts, vertical rhythm etc.) and common patterns can be reused\n  with complete flexibility of markup. However, there's one crucial key to its\n  success: **strategy**.\n\n  Global styles aren't that bad if you treat them with thought and care.\n\u003c/details\u003e\n\n\u003c/br\u003e\n\u003c!--\n    I know I know, I'm sorry, this is the only way I can add a margin after the `\u003cdetails\u003e` block in GitHub-flavoured Markdown 😢\n--\u003e\n\nSmoothie's recommended global architecture borrows from [Harry Roberts's](https://github.com/csswizardry)\nsuccessful [ITCSS](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/), with some minor adjustments.\n\n\u003e Note: Don't necessarily feel obligated to use this specific strategy, the best strategy is to have one.\n\nThis layer _should_ be kept as slim as possible and treated as [critical CSS](https://www.smashingmagazine.com/2015/08/understanding-critical-css/); defined through a single inline `\u003cstyle\u003e` tag at the very top of your document.\n\nSo, consider grouping your global styles and defining in the following order:\n\n1. ~~Settings~~ **Config** (Optional)\n    * If you're using any third-party packages, this is where you'll want to tie any variables to your previously-defined Tokens. If you're **not** using any third-party packages you can discard this layer.\n    * *For example* - for example, you may want to tie breakpoints in your Tokens to a Sass-powered media query library such as Sass MQ.\n2. **Tools**\n    * Mixins, Functions etc.\n3. **Generic**\n    * The first layer that actually outputs CSS, containing high-level styling.\n    * *For example* - Resets, Normalize etc.\n4. **Elements**\n    * Base styling for your HTML elements.\n    * *For example* - Page, Basic Links, Tables etc.\n5. **Objects**\n    * Common structural and non-cosmetic design patterns.\n    * *For example* - your grid system, media object, flag object, lists etc.\n    * *Implementation*\n      * Objects should use **class selectors** for complete markup flexibility.\n      * Consider prefixing your object classes with `.o-` for extra clarity.\n6. ~~Trumps~~ **Utilities**\n    * Helper classes that have the power to override any other styles.\n    * *For example* - spacing, typography, hiding content etc.\n    * *Implementation*\n        * Utilities have a narrower focus and carry higher specificity thanks to its use of `!important`. For this reason, ITCSS refers to the layer as \"Trumps\", but with recent updates to the political climate, it felt best to be agnostic.\n        * Consider prefixing your utility classes with `.u-` for extra clarity.\n\n#### Examples\n\nIf you're still stuck, check out these great ITCSS examples:\n\n* [Toolkit - *@sky-uk*](https://github.com/sky-uk/toolkit)*\n* [Supercell - *@sky-uk*](https://github.com/sky-uk/supercell)\n* [Pantsuit (Medium Article) - *hillaryclinton.com*](https://medium.com/git-out-the-vote/pantsuit-the-hillary-clinton-ui-pattern-library-238e9bf06b54)\n* [inuitcss - *@inuitcss*](https://github.com/inuitcss/inuitcss)\n* [Blaze - *@blaze-ui*](https://github.com/BlazeUI/blaze)\n\n\u003csmall\u003e* Shameless [self-promotion][joebell/github] of previous work.\u003c/small\u003e\n\nJust remember, in Smoothie the \"settings\" and \"components\" layer are handled differently (as described above).\n\n### 3. Components\n\nBy definition, components are the individual building blocks that form your user-interface; such as buttons, forms, user icons and so much more.\n\nThere is a growing need–especially in large-scale web apps–to create components that are fully encapsulated and less susceptible to leaking CSS; in other words, components that can be lifted and shifted anywhere with ease.\n\n### What are the options?\n\nNow that your components are kept separate from your tokens and global styles, you have complete freedom to explore a range of options to build them! H*ck, you could even test different tools for different components.\n\nThe choice is **yours**.\n\nYou could use:\n\n* [CSS][tools]\n    * Contrary to popular belief, you can still write component styles in a standard stylesheet. You could even use a [processor][tools] to make your life a little easier.\n    * Similarly to the Global layer, have a **strategy** to ensure consistency and prevent clashing selectors.\n      \u003e ProTip: Use BEM, and prefix your component classes with `.c-` for extra clarity.\n* [CSS-in-JS][tools]\n* [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)\n    * Defining your styles inside the Shadow DOM will scope them to the Shadow Root and [fully encapsulate](https://www.html5rocks.com/en/tutorials/webcomponents/shadowdom-201/) your component styles.\n\n---\n\n## Recipes 📖\n\nUnsure where to start? Check out some of these example projects:\n\n1. JSON, SCSS and Emotion (WIP)\n2. [JSON, SCSS and Styled Components](recipes/json-scss-and-styled-components/) - [Live Demo](https://smoothie-css.com/recipes/json-scss-and-styled-components/)\n3. [SCSS][recipes/scss] - [Live Demo  (Project Docs)](https://smoothie-css.com)\n\nWant to run these recipes locally? See the [recipes/README][recipes/README].\n\n---\n\n## Standards ✍️ \n\n### Linting\n\nKick-start your project's stylesheet linting with Smoothie's [Stylelint][stylelint] configs:\n\n* [@smoothie-css/stylelint-config][packages/stylelint-config]\n* [@smoothie-css/stylelint-scss-config][packages/stylelint-scss-config]\n\nLinting is a great way to automate maintaining coding standards and readability, with [Stylelint][stylelint] being one of the most well-known tools.\n\nAs always, feel free to customise/extend these or use your own project's config to meet\nyour specific needs.\n\n---\n\n## Tools 🛠\n\n### Token Tools\n\n* [Theo - *@salesforce-ux*](https://github.com/salesforce-ux/theo)\n\n    A tool that transforms Design Tokens into a huge range of different consumable formats.\n\n### Build Tools\n\nThere are a bunch of great tools to make your life even easier when it comes to writing CSS:\n\n* Pre-processors *(Ideal for Global, Components)*\n    * [Less](http://lesscss.org/features/)\n    * [Sass](https://sass-lang.com/guide)\n    * [Stylus](https://github.com/stylus/stylus/)\n* Post-processors *(Ideal for Global, Components)*\n    * [PostCSS](https://postcss.org/)\n* [CSS Modules](https://github.com/css-modules/css-modules) *(Ideal for Components)*\n* CSS-in-JS *(Ideal for Components)*.\n    * [Emotion](https://emotion.sh/)\n    * [Styled Components](https://www.styled-components.com/)\n    \n    Note: Some libraries offer an `injectGlobal` feature but this is discouraged\n    and can often cause issues with the cascade\n\n---\n\n## Built with Smoothie 🍹\n\n* [LADbible](https://github.com/TheLADbibleGroup/) (WIP)\n\nUsing Smoothie in your project? Feel free to raise a PR and add yourself to this list.\n\n---\n\n## Resources 📚\n\n### Tokens\n\n* [\"Design Tokens for Dummies\"](https://uxdesign.cc/design-tokens-for-dummies-8acebf010d71) - [*@chuckn0risk*](https://github.com/chuckn0risk)\n* [\"Tokens in Design Systems\"](https://medium.com/eightshapes-llc/tokens-in-design-systems-25dd82d58421) - [*@nathanacurtis*](https://github.com/nathanacurtis)\n* [\"Creating Themeable Design Systems\"](http://bradfrost.com/blog/post/creating-themeable-design-systems/) - [*@bradfrost*](https://github.com/bradfrost)\n\n### Global\n\n* [\"Managing CSS Projects with ITCSS\"](https://www.youtube.com/watch?v=1OKZOV-iLj4) - [*@csswizardry*](https://github.com/csswizardry)\n* [\"Object Oriented CSS\"](https://github.com/stubbornella/oocss/wiki) - [*@stubbornella*](https://github.com/stubbornella)\n\n### Components\n\n* \"A Unified Styling Language\" - [*@markdalgleish*](https://github.com/markdalgleish)\n  * [CSSconf EU 2017 Talk (YouTube)](https://www.youtube.com/watch?v=X_uTCnaRe94)\n  * [Article (Medium)](https://medium.com/seek-blog/a-unified-styling-language-d0c208de2660)\n* [\"All You Need to Know About CSS-in-JS\"](https://hackernoon.com/all-you-need-to-know-about-css-in-js-984a72d48ebc) - [*@wesharehoodies*](https://github.com/wesharehoodies)\n\n---\n\n## License ©\n\nLicensed under the Apache 2.0 License, Copyright © 2018-Present [Joe Bell][joebell/twitter].\n\nSee [LICENSE][LICENSE] for more information.\n\n\u003c!----------------------- References ----------------------\u003e\n\n\u003c!---- Anchors ----\u003e\n[why]: #why?\n[arch]: #architecture-\n[tokens]: #1-tokens\n[global]: #2-global\n[components]: #3-components\n[recipes]: #recipes-\n[standards]: #standards-\n[tools]: #tools-\n[built-with]: #built-with-smoothie-\n[resources]: #resources-\n\n\u003c!---- Temporary hard-coded links until Markdown transformed in docs build ----\u003e\n[license]: https://github.com/joebell93/smoothie/tree/master/LICENSE\n[recipes/README]: https://github.com/joebell93/smoothie/tree/master/recipes/README.md\n[recipes/scss]: https://github.com/joebell93/smoothie/tree/master/docs\n[packages/stylelint-config]: https://github.com/joebell93/smoothie/tree/master/packages/stylelint-config/README.md\n[packages/stylelint-scss-config]: https://github.com/joebell93/smoothie/tree/master/packages/stylelint-scss-config/README.md\n\n\u003c!---- Personal ----\u003e\n[joebell/github]: https://github.com/joebell93\n[joebell/twitter]: https://twitter.com/joebell_\n\n\u003c!---- External ----\u003e\n[stylelint]: https://stylelint.io/","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoe-bell%2Fsmoothie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoe-bell%2Fsmoothie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoe-bell%2Fsmoothie/lists"}