{"id":19312158,"url":"https://github.com/bigcommerce/sass-style-guide","last_synced_at":"2026-03-11T15:33:19.601Z","repository":{"id":141667120,"uuid":"45710731","full_name":"bigcommerce/sass-style-guide","owner":"bigcommerce","description":"Sass coding guidelines for BigCommerce themes","archived":false,"fork":false,"pushed_at":"2017-05-23T04:46:43.000Z","size":16,"stargazers_count":281,"open_issues_count":1,"forks_count":28,"subscribers_count":79,"default_branch":"master","last_synced_at":"2025-03-31T13:05:38.516Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bigcommerce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-11-06T22:12:23.000Z","updated_at":"2025-03-08T10:55:00.000Z","dependencies_parsed_at":"2024-01-22T04:52:28.038Z","dependency_job_id":null,"html_url":"https://github.com/bigcommerce/sass-style-guide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigcommerce%2Fsass-style-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigcommerce%2Fsass-style-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigcommerce%2Fsass-style-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigcommerce%2Fsass-style-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigcommerce","download_url":"https://codeload.github.com/bigcommerce/sass-style-guide/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252940883,"owners_count":21828766,"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":[],"created_at":"2024-11-10T00:33:16.776Z","updated_at":"2026-03-11T15:33:19.549Z","avatar_url":"https://github.com/bigcommerce.png","language":"CSS","funding_links":[],"categories":["Style Guides"],"sub_categories":["Miscellaneous"],"readme":"# Sass Coding Guidelines\n\nBigcommerce uses [Sass](http://sass-lang.com/) for style generation.\n\nBigcommerce's naming conventions are heavily influenced by the SUIT CSS framework\nand align closely to [Medium](https://medium.com/@fat/mediums-css-is-actually-pretty-fucking-good-b8e2a6c78b06)'s\nthoughts on CSS. Which is to say, it relies on _structured class names_ and\n_meaningful hyphens_ (i.e., not using hyphens merely to separate words). This\nhelps to work around the current limits of applying CSS to the DOM (i.e., the\nlack of style encapsulation), and to better communicate the relationships between\nclasses.\n\n\n**Table of contents**\n\n* [General Principles](#principles)\n* [Specificity](#specificity)\n  * [Performance](#performance)\n* [Formatting](#formatting)\n  * [Indentation](#indentation)\n  * [Commenting](#commenting)\n  * [Spacing](#spacing)\n  * [Quotes](#quotes)\n  * [Value Declaration](#value-declaration)\n  * [Declaration Order](#declaration-order)\n* [Pseudo Elements and Classes](#pseudo)\n* [Units](#units)\n* [Nesting](#nesting)\n* [@extend or @inlcude](#extendorinclude)\n* [Components](#components)\n  * [componentName](#componentName)\n  * [componentName--modifierName](#componentName--modifierName)\n  * [componentName-descendantName](#componentName-descendantName)\n  * [componentName.is-stateOfComponent](#is-stateOfComponent)\n* [Utilities](#utilities)\n  * [u-utilityName](#u-utilityName)\n* [Variables and Mixins](#variables-and-mixins)\n  * [Variables](#variables)\n  * [Component / Micro app variables](#component-variables)\n  * [Maps](#variable-maps)\n  * [colors](#colors)\n  * [z-index](#zindex)\n  * [font-weight](#fontweight)\n  * [line-height](#lineheight)\n  * [Animations](#animations)\n  * [Mixins](#mixins)\n* [Polyfills](#polyfills)\n* [JavaScript](#javascript)\n* [Folder Structure](#folders)\n\n\n\n\u003ca name=\"principles\"\u003e\u003c/a\u003e\n## General Principles\nStrictly adhere to the agreed-upon style guide listed below. The general\nprinciple is to develop DRY (Don't Repeat Yourself) SCSS, built around reusable\ncomponents and patterns.\n\n* All code should look like a single person has typed it.\n* Don't try to prematurely optimize your code; keep it readable and understandable.\n* When building a component, always start by looking at existing patterns.\n* Break down complex components until they are made up of simple components.\n* Save your complex components as patterns so they can be easily reused.\n* Build your component as a mixin which outputs _optional_ css.\n\n\n\u003ca name=\"specificity\"\u003e\u003c/a\u003e\n## Specificity\n\nOn large code bases, it's preferable and a tonne more maintainable if the\nspecificity of selectors are all as equal and as low as humanly possible.\n\n\n\u003e **Do:**\n\u003e Use classes in your SCSS for styling.\n\n```css\n.component {\n    ...\n}\n```\n\n\n\u003e **Don't:**\n\u003e Use ID's for styling. There is literally no point in using them.\n\n```css\n#component {\n    ...\n}\n```\n\n\n\u003e **Do:**\n\u003e Style the base elements (such as typography elements).\n\n```css\nh1 {\n    ...\n}\n```\n\n\u003e **Don't:**\n\u003e Reference or style descendent elements in your class selectors.\n\n```css\n.component h1 {\n    ...\n}\n```\n\n\n\u003e **Don't:**\n\u003e Use overqualified selectors in your CSS. Do not prepend a class or ID with an element.\n\n```css\ndiv.container {\n    ...\n}\n```\n\n\u003ca name=\"performance\"\u003e\u003c/a\u003e\n#### Performance\nOverly specific selectors can also cause performance issues. Consider:\n\n```css\nul.user-list li span a:hover {\n    color: red;\n}\n```\n\nSelectors are resolved right to left, exiting when it has been detected the\nselector does not match. This requires a lot of DOM walking and for large\ndocuments can cause a significant increase in the layout time. For further\nreading checkout: https://developers.google.com/speed/docs/best-practices/rendering#UseEfficientCSSSelectors\n\nIf we know we want to give all `a` elements inside the `.user-list` red on\nhover we can simplify this style to:\n\n```css\n.user-list-link:hover {\n    color: red;\n}\n```\n\n\n\u003ca name=\"formatting\"\u003e\u003c/a\u003e\n## Formatting\n\nThe following are some high level page formatting style rules.\n\n* Remove all trailing white-space from your file, Sublime Text can even do this upon saving.\n  * Tip: set your editor to show white-space.\n* Leave one clear line at the bottom of your file.\n\n\u003ca name=\"indentation\"\u003e\u003c/a\u003e\n#### Indentation\n\n* Don't mix spaces with tabs for indentation.\n* Use a soft-tab of 4 spaces.\n* Use white-space to improve readability.\n* Feel free to use indentation to show hierarchy.\n\n\u003e **Do:**\n\n```css\n.component {\n    ...\n}\n\n.component-child {\n    ...\n}\n\n.component-childSecond {\n    ...\n}\n```\n\n\u003ca name=\"commenting\"\u003e\u003c/a\u003e\n#### Commenting\n* Separate your code into logical sections using standard comment blocks.\n* Leave one clear line under your section comments.\n* Leave two clear lines above comment blocks.\n* Annotate your code inside a comment block, leaving a reference # next to the line.\n\n\u003e **Do:**\n\u003e Comment your code\n\u003e No really, comment your code\n\n```css\n// =============================================================================\n// FILE TITLE / SECTION TITLE\n// =============================================================================\n\n\n// Comment Block / Sub-section\n// -----------------------------------------------------------------------------\n//\n// Purpose: This will describe when this component should be used. This comment\n// block is 80 chars long\n//\n// 1. Mark lines of code with numbers which are explained here.\n// This keeps your code clean, while also allowing detailed comments.\n//\n// -----------------------------------------------------------------------------\n\n.component {\n    ... // 1\n}\n\n```\n\n\u003ca name=\"spacing\"\u003e\u003c/a\u003e\n#### Spacing\n\n* CSS rules should be comma separated but live on new lines.\n* Include a single space before the opening brace of a rule-set.\n* Include a single space after the colon of a declaration.\n* Include a semi-colon at the end of every declaration in a declaration block.\n* Include a space after each comma in comma-separated property or function values.\n* Place the closing brace of a rule-set on its own line.\n* CSS blocks should be separated by a single clear line.\n* Add two blank lines between sections and one between sub-sections.\n\n\u003e **Do:**\n\n```css\n.content,\n.content-edit {\n    padding: 0;\n    margin: 0;\n    font-family: \"Helvetica\", sans-serif;\n}\n\n\n.newSection {\n    ...\n}\n\n.newSection-edit {\n    ...\n}\n```\n\n\u003e **Don't:**\n\n```css\n.content, .content-edit{\n    padding:0; margin:0;\n    font-family: \"Helvetica\",sans-serif}\n.newSection {\n    ...\n}\n.newSection-edit {\n    ...\n}\n```\n\n\u003ca name=\"quotes\"\u003e\u003c/a\u003e\n#### Quotes\n\n\u003e **Do:**\n\u003e Always use double quotes when available.\n\u003e Quote attribute values in selectors\n\n```css\ninput[type=\"checkbox\"] {\n    background-image: url(\"/img/you.jpg\");\n    font-family: \"Helvetica Neue Light\", \"Helvetica Neue\", Helvetica, Arial;\n}\n```\n\n\u003e **Don't:**\n\n```css\ninput[type=checkbox] {\n    background-image: url(/img/you.jpg);\n    font-family: Helvetica Neue Light, Helvetica Neue, Helvetica, Arial;\n}\n```\n\n\u003ca name=\"value-declaration\"\u003e\u003c/a\u003e\n#### When declaring values\n* Use lower-case and shorthand hex values\n* Use unit-less line-height values\n* Where allowed, avoid specifying units for zero values\n* Never specify the height property unless it's specifically needed (`min-height` is cool)\n* Never use `!important` (Utility classes are an exception but still should be\navoided)\n* Try to only style the property you are explicitly concerned with to reduce\nover zealously resetting something you might want to inherit\n  * `background-color: #333` over `background: #333`\n  * `margin-top: 10px` over `margin: 10px 0 0`\n  * Use shorthand if you can, be sensible\n\n\u003e **Do:**\n\n```css\n.component {\n    background-color: #ccc;\n    color: #aaa;\n    left: 0;\n    line-height: 1.25;\n    min-height: 400px;\n    padding: 0 20px;\n    top: 0;\n}\n```\n\n\u003e **Don't:**\n\n```css\n.component {\n    background: #ccc;\n    color: #AAAAAA;\n    left: 0px;\n    line-height: 24px;\n    height: 400px !important; //jerk #yolo FUUUUUU\n    padding: 0px 20px 0px 20px;\n    top: 0px;\n}\n```\n\n\n\u003ca name=\"declaration-order\"\u003e\u003c/a\u003e\n#### Declaration order\nThere are a millions opinions and thoughts on logical ordering and grouping.\nDon't force someone to learn your opinion, ordering doesn't matter, consistency\ndoes. Just use the alphabet, _everyone_ knows it.\n* @extend\n* @include\n* Alphabetical, always.\n\n\u003e **Do**\n\n```css\n.component {\n    @extend %a-placeholder;\n    @include silly-links;\n    color: #aaa;\n    left: 0;\n    line-height: 1.25;\n    min-height: 400px;\n    padding: 0 20px;\n    top: 0;\n    width: 150px;\n}\n```\n\n\u003e **Don't:**\n\n```css\n.component {\n    min-height: 400px;\n    left: 0;\n    @include silly-links;\n    top: 0;\n    width: 150px;\n    color: #aaa;\n    @extend %a-placeholder;\n    line-height: 1.25;\n    width: 200px;\n    padding: 0 20px;\n}\n```\n\n\u003ca name=\"pseudo\"\u003e\u003c/a\u003e\n## Pseudo Elements and Classes\nPseudo elements and classes are very different things, as is the syntax used to\ndeclare them. Declare pseudo _**classes**_ with a single colon. Declare pseudo\n_**elements**_ with a double colon.\n\n\u003e **Do**\n\n```css\n.component:focus {\n    ...\n}\n\n.component:hover {\n    ...\n}\n\n.component::before {\n    ...\n}\n\n.component::after {\n    ...\n}\n```\n\n\u003e **Don't**\n\n```css\n.component:after {\n    ...\n}\n```\n\n\n\u003ca name=\"units\"\u003e\u003c/a\u003e\n## Units\n\n\u003e **Do:**\n\n* Use `rem` units as primary unit type. This includes:\n    * Positioning (`top`, `right`, `bottom`, `left`)\n    * Dimensions (Such as `width`, `height`, `margin`, `padding`)\n    * Font size\n* Use `px` units as primary unit type for the following properties:\n    * Border widths (`border: 1px solid #bada55;`)\n* Use `%` units only if necessary, where `rem` will not suffice:\n    * Positioning (`top`, `right`, `bottom`, `left`)\n    * Dimensions (`width`, `height`)\n* Line-height should be kept unit-less. If you find you're using a line-height\nwith a set unit type, try to think of alternative ways to achieve the same outcome.\nIf it's a unique case which requires a specific `px` or `rem` unit, outline the\nreasoning with comments so that others are aware of its purpose.\n\n\u003e **Don't:**\n\n* Avoid all use of magic numbers. Re-think the problem. (`margin-top: 37px;`)\n\n\n\n\u003ca name=\"nesting\"\u003e\u003c/a\u003e\n## Nesting\n\nNesting is handy, _sometimes_, but will quickly conflict with our\n[Specificty](#specificity) and [Performance](#performance) guidelines.\n\nAs we follow conventions and thoughts from popular and widely accepted\nmethodologies such as BEM, SMACSS and SUIT, the use of the Suffix can help immensely though.\n\n* Just because you can, doesn't mean you should.\n* [Parent Selector Suffixes](http://thesassway.com/news/sass-3-3-released#parent-selector-suffixes)\nare neat, but not very searchable\n* Watch your output, be mindful of [Specificty](#specificity) and\n[Performance](#performance)\n* Aim for a maximum depth of just 1 nested rule\n\n\u003e **Do:**\n\n```css\n.panel-body {\n    position: relative;\n}\n\n.panel-sideBar {\n    z-index: 10;\n}\n\n.panel-sideBar-item {\n    cursor: pointer;\n}\n\n.panel-sideBar-item-label {\n    color: #AEAEAE;\n\n    \u0026.has-smallFont {\n        font-size: 13px;\n    }\n}\n```\n\nAt its worst, this produces:\n```css\n.panel-sideBar-item-label.has-smallFont {\n    font-size: 13px;\n}\n```\n\n\u003e **Don't:**\n\n```css\n.bc-tab-panel {\n\n    .panel-body {\n        position: relative;\n        ...\n\n        .panel-side-bar {\n            z-index: 10;\n            ...\n\n            .panel-side-item {\n                cursor: pointer;\n                ...\n\n                .panel-side-item-label {\n                    color: #AEAEAE;\n\n                    \u0026.small-font {\n                        font-size: 13px;\n                    }\n                }\n            }\n        }\n    }\n}\n```\n\nAt it's worst, this produces:\n```css\n.bc-tab-panel .panel-body .panel-side-bar .panel-side-item .panel-side-item-label.small-font {\n    font-size: 13px;\n}\n```\n\n\u003ca name=\"extendorinclude\"\u003e\u003c/a\u003e\n## @extend or @include\n\n* Excessive use of `@include` can cause unnecessary bloat to your stylesheet, but\ngzip should help with that.\n* Excessive use of `@extend` can create large selector blocks (not helpful in web inspector)\nand hoisting of your selector can cause override and inheritance issues.\n* We advise to `@include` over `@extend` generally, but use common sense. In situations where it's better to  `@extend` it's safer to do so on a placeholder selector.\n\n\u003e **Do:**\n\u003e Make use of placeholder selectors to separate repeated local styles\n\n```css\n%placeholderSelector {\n    background-color: #eee;\n}\n\n.component1 {\n    @extend %placeholderSelector;\n    color: red;\n}\n\n.component2 {\n    @extend %placeholderSelector;\n    color: blue;\n}\n```\n\n\u003ca name=\"components\"\u003e\u003c/a\u003e\n## Components\n\nSyntax: `\u003ccomponentName\u003e[--modifierName|-descendantName]`\n\nThis component syntax is mainly taken from [Suit CSS](http://suitcss.github.io/)\nwith minor modifications.\n\nComponent driven development offers several benefits when reading and writing\nHTML and CSS:\n\n* It helps to distinguish between the classes for the root of the component,\ndescendant elements, and modifications.\n* It keeps the specificity of selectors low.\n* It helps to decouple presentation semantics from document semantics.\n\nYou can think of components as custom elements that enclose specific semantics,\nstyling, and behaviour.\n\n**Do not choose a class name based on its visual presentation or its content.**\n\nThe primary architectural division is between components and utilities:\n\n* componentName (eg. `.dropdown` or `.buttonGroup`)\n* componentName--modifierName (eg. `.dropdown--dropUp` or `.button--primary`)\n* componentName-descendantName (eg. `.dropdown-item`)\n* componentName.is-stateOfComponent (eg. `.dropdown.is-active`)\n* u-utilityName (eg. `.u-textTruncate`)\n* `[\u003cnamespace\u003e-]\u003ccomponentName\u003e[--modifierName|-descendentName]`\n\n\n\n\u003ca name=\"componentName\"\u003e\u003c/a\u003e\n#### ComponentName\n\nThe component's name must be written in camel case. Use class names that are as\nshort as possible but as long as necessary.\n\n* Example: `.nav` not `.navigation`\n* Example: `.button` not `.btn`\n\n```css\n.myComponent { /* ... */ }\n```\n\n```html\n\u003carticle class=\"myComponent\"\u003e\n  ...\n\u003c/article\u003e\n```\n\n\u003ca name=\"componentName--modifierName\"\u003e\u003c/a\u003e\n#### componentName--modifierName\n\nA component modifier is a class that modifies the presentation of the base\ncomponent in some form. Modifier names must be written in camel case and be\nseparated from the component name by two hyphens. The class should be included\nin the HTML _in addition_ to the base component class.\n\n```css\n/* Core button */\n.button {\n    ...\n}\n\n.button--primary {\n    ...\n}\n```\n\n```html\n\u003cbutton class=\"button button--primary\"\u003e...\u003c/button\u003e\n```\n\u003ca name=\"componentName-descendantName\"\u003e\u003c/a\u003e\n#### componentName-descendantName\n\nA component descendant is a class that is attached to a descendant node of a\ncomponent. It's responsible for applying presentation directly to the descendant\non behalf of a particular component. Descendant names must be written in camel case.\n\n```html\n\u003carticle class=\"tweet\"\u003e\n  \u003cheader class=\"tweet-header\"\u003e\n    \u003cimg class=\"tweet-avatar\" src=\"{$src}\" alt=\"{$alt}\"\u003e\n    ...\n  \u003c/header\u003e\n  \u003cdiv class=\"tweet-body\"\u003e\n    ...\n  \u003c/div\u003e\n\u003c/article\u003e\n```\n\nYou might notice that `tweet-avatar`, despite being a descendant of `tweet-header`\ndoes not have the class of `tweet-header-avatar`. Why? Because it doesn't necessarily\n**have** to live there. It could be adjacent to `tweet-header` and function the same\nway. Therefore, you should **only** prepend a descendant with its parent if must\nlive there. Strive to keep class names as short as possible, but as long as necessary.\n\nWhen building a component, you'll often run into the situation where you have a\nlist, group or simply require a container for some descendants. In this case, it's\nmuch better to follow a pattern of pluralising the container and having each\ndescendant be singular. This keeps the relationship clear between descendant levels.\n\n\u003e **Do:**\n\n```html\n\u003cnav class=\"pagination\"\u003e\n  \u003cul class=\"pagination-list\"\u003e\n    \u003cli class=\"pagination-listItem\"\u003e\n      ...\n    \u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/nav\u003e\n```\n\n```html\n\u003cul class=\"breadcrumbs\"\u003e\n  \u003cli class=\"breadcrumb\"\u003e\n    \u003ca class=\"breadcrumb-label\" href=\"#\"\u003e\u003c/a\u003e\n  \u003c/li\u003e\n\u003c/ul\u003e\n```\n\n\u003e **Don't:**\n\u003e Avoid verbose descendant names\n\n```html\n\u003cnav class=\"pagination\"\u003e\n  \u003cul class=\"pagination-pages\"\u003e\n    \u003cli class=\"pagination-pages-page\"\u003e\n      ...\n    \u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/nav\u003e\n```\n\n```html\n  \u003cul class=\"breadcrumbs\"\u003e\n    \u003cli class=\"breadcrumbs-breadcrumb\"\u003e\n      \u003ca class=\"breadcrumbs-breadcrumb-label\" href=\"#\"\u003e\u003c/a\u003e\n    \u003c/li\u003e\n  \u003c/ul\u003e\n```\n\n\u003ca name=\"is-stateOfComponent\"\u003e\u003c/a\u003e\n#### componentName.is-stateOfComponent\n\nUse `is-stateName` for state-based modifications of components. The state name\nmust be Camel case. **Never style these classes directly; they should always be\nused as an adjoining class.**\n\nJS can add/remove these classes. This means that the same state names can be used\nin multiple contexts, but every component must define its own styles for the state\n(as they are scoped to the component).\n\n```html\n\u003carticle class=\"tweet is-expanded\"\u003e\n  ...\n\u003c/article\u003e\n```\n\n```css\n.tweet {\n    ...\n}\n\n.tweet.is-expanded {\n    ...\n}\n```\n\n\u003ca name=\"utilities\"\u003e\u003c/a\u003e\n## Utilities\n\nUtility classes are low-level structural and positional traits. Utilities can\nbe applied directly to any element; multiple utilities can be used together;\nand utilities can be used alongside component classes.\n\nUtility classes should be used sparingly, lean towards component level styling\nto make for as reusable HTML patterns as possible.\n\n\n\u003ca name=\"u-utilityName\"\u003e\u003c/a\u003e\n#### u-utilityName\n\nSyntax: `u-\u003cutilityName\u003e`\n\nUtilities must use a camel case name, prefixed with a `u` namespace.\n\n\n\u003ca name=\"variables-and-mixins\"\u003e\u003c/a\u003e\n## Variables and Mixins\n\nVariables and Mixins should follow similar naming conventions.\n\n\u003ca name=\"variables\"\u003e\u003c/a\u003e\n#### Variables\n\nSyntax: `[\u003ccomponentName\u003e[--modifierName][-descendentName]-]\u003cpropertyName\u003e-\u003cvariablename\u003e[--\u003cmodifierName\u003e]`\n\nVariables should be named as such, things that can change over time.\n\nVariables should also follow our component naming convention to show context\nand be in camelCase. If the variable is a global, generic variable, the property\nname should be prefixed first, followed by the variant and or modifier name for\nclearer understanding of use.\n\n\u003e **Do:**\n\u003e Abstract your variable names\n\n```CSS\n$color-brandPrimary:  #aaa;\n$fontSize:            1rem;\n$fontSize--large:     2rem;\n$lineHeight--small:   1.2;\n```\n\n\u003e **Don't:**\n\u003e Name your variables after the color value\n\n```css\n$bigcommerceBlue:     #00abc9;\n$color-blue:          #00ffee;\n$color-lightBlue:     #eeff00;\n```\n\n\u003ca name=\"component-variables\"\u003e\u003c/a\u003e\n#### Component / Micro App level variables\n\nMicro apps must base their local variables on the global variables primarily.\nYou may add your own specific variables as required if no global variable is available.\n\nFor portability, your component should declare it's own set of variables inside\nit's own settings partial, inside the settings folder. Even if at the time, your\ncomponent only uses globally available variables from Bigcommerce's Library,\nyou should reassign the global variable to a local one.\nIf your component styles change from those global variables at all in the future,\nless of your SCSS will have to change, as you only change the local variable value.\n\nIf your variable is scoped to your component, it should be namespaced as such following\nour component naming conventions.\n\n\u003e **Do:**\n\n```css\n$componentName-fontSize:                                fontSize(\"small\");\n$componentName-decendantName-backgroundColor:           #ccc;\n$componentName-decendantName-marginBottom:              fontSize(\"large\");\n$componentName-decendantName--active-backgroundColor:   #000;\n```\n\n```css\n.componentName {\n    font-size: $componentName-fontSize;\n}\n\n.componentName-decendantName {\n    background-color: $componentName-decendantName-backgroundColor;\n    margin-bottom: $componentName-decendantName-marginBottom;\n}\n\n.componentName-decendantName--active {\n    background-color: $componentName-decendantName--active-backgroundColor;\n}\n```\n\n\u003ca name=\"variable-maps\"\u003e\u003c/a\u003e\n#### Maps, maps are cool\n\nVariable maps with a simple getter mixin, can help simplify your variable names\nwhen calling them, and help better group variables together using their\nrelationship. [More info](http://erskinedesign.com/blog/friendlier-colour-names-sass-maps/)\n\n\u003e **Do:**\n\n```scss\n// Setting variables and mixin\n// -----------------------------------------------------------------------------\n\n$colors: (\n    primary: (\n        base: #00abc9,\n        light: #daf1f6,\n        dark: #12799a\n    ),\n    secondary: (\n        base: #424d55,\n        light: #ccc,\n        lightest: #efefef,\n        dark: #404247\n    ),\n    success: (\n        base: #bbd33e,\n        light: #eaf0c6\n    )\n);\n\n@function color($color, $tone: \"base\") {\n    @return map-get(map-get($colors, $color), $tone);\n}\n```\n\n\n```scss\n// Usage\n// -----------------------------------------------------------------------------\n\nbody {\n    color: color(\"secondary\");\n}\n\nh1,\nh2,\nh3 {\n    color: color(\"secondary\", \"dark\");\n}\n\n.alert {\n    background-color: color(\"primary\", \"light\");\n}\n\n.alert-close {\n    color: color(\"primary\");\n}\n\n.alert--success {\n    background-color: color(\"success\", \"light\");\n\n    \u003e .alert-close {\n        color: color(\"success\");\n    }\n}\n```\n\n**Every variable used in the core architecture must be based off the global\nvariables.**\n\n\u003ca name=\"colors\"\u003e\u003c/a\u003e\n#### Colors\n\nPlease only use the globally available colors from the Bigcommerce Library.\nYour Micro app or component shouldn't really have a need for a *new* color.\nThis creates consistency and sanity.\n\nAvoid using the `darken(color, %)` and `lighten(color, %)` mixins for similar reasons.\n\nUse the color maps available to you:\n```css\n.component {\n    background-color: color(\"brand\", \"primary\");\n}\n```\n\n\u003ca name=\"zindex\"\u003e\u003c/a\u003e\n#### z-index scale\n\nPlease use the z-index scale defined in the Bigcommerce Library under global settings.\n\n`zIndex(\"lowest\")` or `zIndex(\"high\")` for example.\n\n\n\u003ca name=\"fontweight\"\u003e\u003c/a\u003e\n#### Font Weight\n\nBigcommerce apps share a strict set of font weights. Never declare a new font weight,\nonly use the available font settings from the Bigcommerce Library. e.g.\n\n```css\nfontWeight(\"light\");\nfontWeight(\"semibold\");\n```\n\n\n\u003ca name=\"lineheight\"\u003e\u003c/a\u003e\n#### Line Height\n\nThe Bigcommerce Library also provides a line height scale. This should be used for blocks\nof text. e.g.\n\n```css\nlineHeight(\"smallest\");\nlineHeight(\"large\");\n```\n\nAlternatively, when using line height to vertically centre a single line of text,\nbe sure to set the line height to the height of the container - 1.\n\n```CSS\n.button {\n  height: remCalc(50px);\n  line-height: remCalc(49px);\n}\n```\n\n\u003ca name=\"animations\"\u003e\u003c/a\u003e\n#### Animations\n\nAnimation delays, durations and easing should be taken from the global framework\n\n\u003ca name=\"mixins\"\u003e\u003c/a\u003e\n#### Mixins\n\nMixins follow regular camel case naming conventions and do not require namespacing. If you are creating a mixin for a utility, it will need to match the utility name (including `u` namespacing).\n\n* `@mixin buttonVariant;`\n* `@mixin u-textTruncate;`\n\n\u003ca name=\"polyfills\"\u003e\u003c/a\u003e\n## Polyfills\n\nAt Bigcommerce, we try not to replicate CSS polyfills that auto-prefixer can\nsupply in a Grunt or Gulp task. This keeps our SCSS code base lean and future proof.\n\n\u003e **Do:**\n\n```css\n.button {\n    border-radius: 3px;\n}\n```\n\n\u003e **Don't:**\n\u003e Add vendor prefixes at all.\n\n```css\n.button {\n    @include border-radius(3px);\n}\n```\n```css\n.button {\n    -ms-border-radius: 3px;\n    -o-border-radius: 3px;\n    -webkit-border-radius: 3px;\n    border-radius: 3px;\n}\n```\n\n\u003ca name=\"javascript\"\u003e\u003c/a\u003e\n## JavaScript\n\nsyntax: `js-\u003ctargetName\u003e`\n\nJavaScript-specific classes reduce the risk that changing the structure or theme\nof components will inadvertently affect any required JavaScript behaviour and\ncomplex functionality. It is not necessary to use them in every case, just\nthink of them as a tool in your utility belt. If you are creating a class, which\nyou don't intend to use for styling, but instead only as a selector in JavaScript,\nyou should probably be adding the `js-` prefix. In practice this looks like this:\n\n```html\n\u003ca href=\"/login\" class=\"btn btn-primary js-login\"\u003e\u003c/a\u003e\n```\n\n**Again, JavaScript-specific classes should not, under any circumstances, be styled.**\n\n\u003ca name=\"folders\"\u003e\u003c/a\u003e\n## Folder Structure\n\n#### General principle\nThe Sass folder structure we're proposing, will have two slight differences\nbetween the core framework and micro apps, however the bulk of the structure is\nidentical between the two.\n\nThe idea is to have the least amount of folders as possible, but as many as we\nneed to define clear, structured patterns in your Sass.\n\n#### Core Folder Structure\n\n```\n.\n├── sass\n|   ├── settings/\n|   └── tools/\n|   └── vendor/\n|   └── components/\n|   └── utilities/\n```\n\n\n**/settings:** Contains all of your SCSS variables for your framework. Within\nthis folder is 1 primary file `_settings.scss`, which imports all other variable\nfiles that have been broken into logical files such as `_colors.scss`,\n`_typography.scss`, `_z-index.scss` and your chosen frameworks variables, for\nexample `_foundation.scss`.\n\n**/tools:** Contains all of your Sass mixins. Within this folder is 1 primary\nfile `_tools.scss`, which imports all other mixin files that have been broken into\nlogical files. No framework mixins should appear in this folder as they can be\nconsumed from their own respective `/vendor` or `/components` folder.\n\n**/vendor:** Contains all of your vendor files, such as normalize, bootstrap,\nfoundation, animate.css, etc. All readily consumable third party files belong\nhere, and can be imported in the framework base file as required. No file in\nthe /vendor folder should ever be modified.\n\n**/components:** Contains all of your components. This folder will make up the\nvast majority of your compiled CSS. All custom components simply live inside\nthis folder, for example `/components/component/_component.scss`. It also contains\nthe consumed version of your chosen /vendor framework's components, which will be\nreworked to adhere to the Naming Conventions and Style Guide. They will live\ninside a subfolder of the framework's name, for example `/components/foundation/`.\n\n**/utilities:** Contains all CSS snippets which can be applied to your HTML for\nquick prototyping, or a case by case basis where a unique, yet repeatable style\nis required. Every utility found within this folder will have both a class and a\nmixin. An example being, truncatedText. You can utilise it by applying the class\n`.u-truncatedText` or by applying a mixin, `@include truncatedText;`.\n\n\n#### Micro App Folder Structure\n\n```\n.\n├── sass\n|   ├── settings/\n|   └── tools/\n|   └── vendor/\n|   └── layouts/\n|   └── components/\n|   └── utilities/\n|   └── shame/\n```\n\nThere are only two minor differences in a micro app, when compared to the core\nframework. Firstly you'll notice that the /framework folder has been replaced by\na /layouts folder, as well as the addition of the /shame folder.\n\n**/layouts:** Contains your micro app \"layouts\" and page specific styling.\nEssentially creating the wrapping sections and grids for your app, where the\ncore framework's components will live inside. For example, a layout file could\npotentially be your micro app's navigation. It is important to note that the\nstyling for individual navigation items and all other inner components styling\ndo not live in the layout file. There purpose is purely for the containing\nelements that set up your app.\n\n**/shame:** This interestingly named folder has one goal: to remain empty. It's\npurpose is the place for all of those hot fixes or quick hacks in throwing\nsomething together. Any code which you don't feel is \"complete\" can also live\nhere. It creates clear visibility on less than perfect code, especially when it\ncomes to code reviews, and creates a trail for your dodgy code that if left\nsomewhere in your component/layout code could be forgotten about and left.\n\n**A note on: /components \u0026 /utilities:** Within your micro app, these folders should\nonly house your app's unique code. Any repeatable component or utility that could\nbe re-used across other micro apps should be flagged and a PR opened for adding\nit into the core framework.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigcommerce%2Fsass-style-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigcommerce%2Fsass-style-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigcommerce%2Fsass-style-guide/lists"}