{"id":18376920,"url":"https://github.com/bbc/gel-sass-tools","last_synced_at":"2025-04-11T05:20:44.751Z","repository":{"id":3585538,"uuid":"41424379","full_name":"bbc/gel-sass-tools","owner":"bbc","description":"A collection of Sass Settings \u0026 Tools which align to key GEL values","archived":false,"fork":false,"pushed_at":"2024-07-26T12:51:48.000Z","size":75,"stargazers_count":27,"open_issues_count":0,"forks_count":2,"subscribers_count":24,"default_branch":"main","last_synced_at":"2024-09-26T14:48:38.858Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-26T12:31:16.000Z","updated_at":"2024-07-26T12:51:17.000Z","dependencies_parsed_at":"2022-08-03T15:09:49.204Z","dependency_job_id":"f2373110-b00e-442d-ae2b-d0c83f1c46a4","html_url":"https://github.com/bbc/gel-sass-tools","commit_stats":{"total_commits":65,"total_committers":8,"mean_commits":8.125,"dds":0.3384615384615385,"last_synced_commit":"cd8f48299bcc325fef02ef00abf00671298e37b8"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fgel-sass-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fgel-sass-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fgel-sass-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fgel-sass-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbc","download_url":"https://codeload.github.com/bbc/gel-sass-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248346047,"owners_count":21088394,"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-06T00:25:24.227Z","updated_at":"2025-04-11T05:20:44.729Z","avatar_url":"https://github.com/bbc.png","language":"SCSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eGEL Sass Tools\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    A collection of Sass Settings \u0026 Tools which align to key GEL values.\u003cbr /\u003e\n    Forms part of the \u003ca href=\"https://github.com/bbc/gel-foundations\" target=\"_blank\"\u003e\u003cb\u003eGEL Foundations\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Breaking Change: v4.0.0\n\nv4.0.0 of GEL Sass Tools implements the [@use](https://sass-lang.com/documentation/at-rules/use/) and [@forward](https://sass-lang.com/documentation/at-rules/forward/) approach and removes [@import](https://sass-lang.com/documentation/at-rules/import/).\n\nThis has a number of consequences; how modules are loaded, and how to access variables. Namespaces now come into play, so please read the sass documentation links above to learn more.\n\nIn addition there were a number of __browser prefixes__ used in versions prior to v4. Given how much the browser landscape has changed since they were added, it is __now time to remove them__.\n\nFor usage of GEL Sass Tools prior to v4.0.0 please reference the [v3.4.0 readme](https://github.com/bbc/gel-sass-tools/tree/3.4.0).\n\n\n## What is this?\n\nGEL Sass Tools is a collection of Sass variables, functions and mixins which allows you to work with GEL units consistently within your Sass. It is also used by other [GEL Foundations](https://github.com/bbc/gel-foundations) components.\n\nHere is how you could use these tools in your Sass:\n\n```scss\n@use 'gel-sass-tools/sass-tools';\n@use 'sass-mq/mq';\n\n.my-component {\n    margin-top: sass-tools.$gel-spacing-unit;\n\n    @include mq.mq($from: gel-bp-m) {\n        margin-top: sass-tools.double(sass-tools.$gel-spacing-unit);\n    }\n}\n```\n\nThis would compile to:\n\n```css\n.my-component {\n    margin-top: 8px;\n}\n\n@media (min-width: 37.50em) {\n    .my-component {\n        margin-top: 16px;\n    }\n}\n```\n\n## Installation\n\n### Install using NPM\n\n```bash\n$ npm install --save gel-sass-tools\n```\n\n```scss\n// your-app/main.scss\n@use 'gel-sass-tools/sass-tools';\n\n```\n\n### Install manually\n\nYou can install this component manually by downloading the content of this Git repo into your project and use a Sass @use to include it in your project.\n\n\u003e **Note:** you will manually need to manage the dependencies below, without these this component will fail to compile.\n\n\n### IMPORTANT: Specify a Loadpath\n\nBecause this module depends on other modules such as [Sass MQ](https://github.com/sass-mq/sass-mq), when compiling your Sass it needs to know where find the referenced modules. It does this via a [loadPath](https://sass-lang.com/documentation/at-rules/use/#load-paths).\n\nIf compiling from the command line you can specify:\n```\nsass --load-path=node_modules/ \u003coptions\u003e\n```\n\nWith nodejs you can call `compile` or `compileAsync`:\n```js\nawait sass.compileAsync(file, { loadPaths: ['./node_modules'] })\n```\n\nThis ensures the dependencies can be loaded correctly.\n\n## Usage\n\nUsage of the included tools is as follows:\n\n### Spacing units\n\nThe following spacing variables are made available:\n\n- `$gel-spacing-unit` - baseline spacing unit - `8px`\n- `$gel-alt-spacing-unit` - alternative baseline spacing unit - `12px`\n\n### Breakpoints\n\nThe following breakpoints are defined and added to the [Sass MQ](https://github.com/sass-mq/sass-mq) breakpoint list:\n\n- `gel-bp-xs` - 240px\n- `gel-bp-s` - 400px\n- `gel-bp-m` - 600px\n- `gel-bp-l` - 900px\n- `gel-bp-xl` - 1008px\n- `gel-bp-xxl` - 1280px\n\nThese can be called when using the `mq` mixin:\n\n```scss\n@use 'sass-mq/mq';\n\n.my-component {\n    ...\n\n    @include mq.mq($from: gel-bp-s) {\n        ...\n    }\n\n    @include mq.mq($from: gel-bp-m) {\n        ...\n    }\n\n    @include mq.mq($from: gel-bp-l) {\n        ...\n    }\n}\n```\n\n### Math functions\n\nThe following `math` functions are included:\n\n- `quarter($value)`\n- `third($value)`\n- `halve($value)`\n- `double($value)`\n- `triple($value)`\n- `quadruple($value)`\n\nThese functions can be used inline with any numerical CSS rule. E.g:\n\n```scss\n@use 'gel-sass-tools/sass-tools';\n\n.my-component {\n    margin-bottom: sass-tools.halve(sass-tools.$gel-spacing-unit);\n    padding-left: sass-tools.double(sass-tools.$gel-spacing-unit);\n    padding-right: sass-tools.double(sass-tools.$gel-spacing-unit);\n}\n```\n\nor functions can be nested within other Sass features such as mixins:\n\n```scss\n@use 'gel-sass-tools/sass-tools';\n\n.my-component {\n    @include sass-tools.toRem('margin-bottom', sass-tools.halve(sass-tools.$gel-spacing-unit));\n    @include sass-tools.toRem('padding-left', sass-tools.double(sass-tools.$gel-spacing-unit));\n    @include sass-tools.toRem('padding-right', sass-tools.double(sass-tools.$gel-spacing-unit));\n}\n```\n\n### REM mixin\n\nThe `rem` tool can be used in two ways. Either by directly calling the `toRem($value)` function, which will convert the supplied value and return a `rem` unit. E.g:\n\n```scss\n@use 'gel-sass-tools/sass-tools';\n\n.my-component {\n    margin-bottom: sass-tools.toRem(sass-tools.$gel-spacing-unit);\n}\n```\n\n\u003e Beware that [rem](http://caniuse.com/#feat=rem) units are not universal supported. IE8 and below do not support `rem` so require a `px` fallback.\n\nYou can also use the `@include toRem($value);` mixin, which by default returns a `px` fallback to allow support for older browsers which don't support `rem` units. E.g:\n\n**Sass**\n```scss\n@use 'gel-sass-tools/sass-tools';\n\n.my-component {\n    @include sass-tools.toRem('margin-bottom', 16px);\n}\n```\n\n**CSS**\n```css\n.my-component {\n    margin-bottom: 16px;\n    margin-bottom: 1rem;\n}\n```\n\n#### Options\n\nThe following options can be defined before the tools partial is included to customise the functionality and output. By default the following options are all set to `true`:\n\n- `$gel-tools-rem-enable--function` - enable/disable the rem conversion, if this option is disabled only `px` values will be returned\n- `$gel-tools-rem-enable--mixin` - disable the mixin if you only want to output the `px`, this can be useful for IE8 stylesheets who don't need `rem` values\n- `$gel-tools-rem-enable--fallback` - disable the automatic generation of a `px` fallback when the mixin in called, use this open if you want to remove all `px` values from your stylesheets\n\n### Right-to-Left (RTL)\n\nSupport for Right-to-Left language is offered via two methods to flip CSS styles: interpolated properties and the `flip()` function.\n\nInterpolation should be used for any property which has a direction (e.g. `padding-left`, `margin-right`, `border-right`, `left`, etc), `flip()`` should be used for all other properties.\n\n#### Which properties need to be flipped?\n\n- `background`\n- `background-position`\n- `border`\n- `border-radius`\n- `clear`\n- `cursor`\n- `direction`\n- `float`\n- `left/right`\n- `margin`\n- `padding`\n- `text-align`\n- `text-indent`\n\n#### Flip\n\nTaking the following CSS as an example:\n\n```scss\n// Original Sass\n.my-component {\n    float: left;\n}\n```\n\nFor a RTL layout, `float: left;` should be flipped to `float: right;`. We can use the `flip()` function to accomplish this.\n\n```scss\n@use 'gel-sass-tools/sass-tools';\n\n.ltr {\n    float: sass-tools.flip(left, right);\n}\n\nsass-tools.$rtl: true;\n\n.rtl {\n    float: sass-tools.flip(left, right);\n}\n```\n\nWhen Sass comes across the `flip()` function, it will check the value of the `$rtl` variable. If `$rtl` is `false`, the `flip()` function will take the first parameter. If `$rtl` is `true`, the `flip()` function will take the second parameter.\n\nThe Sass will compile out as follows:\n\n```css\n.ltr {\n    float: left;\n}\n\n.rtl {\n    float: right;\n}\n```\n\n#### Interpolation\n\nInterpolation is used to adjust CSS properties which contain a direction within their name. For example `padding-left` would need to change to `padding-right` in a RTL context. Our interpolation technique works by changing the value of variables based on the value of the `$rtl` variable.\n\nTaking the following CSS as an example:\n\n```scss\n@use 'gel-sass-tools/sass-tools';\n\n// Original Sass\n.my-component {\n    padding-left: sass-tools.$gel-spacing-unit; // 8px\n}\n```\n\nFor a RTL layout, `padding-left: 8px;` should be flipped to `padding-right: 8px;`.\n\nIn order to flip this, we have to interpolate the style property:\n\n```scss\n@use 'gel-sass-tools/sass-tools';\n\n.ltr {\n    #{sass-tools.$padding-left}: sass-tools.$gel-spacing-unit; // 8px\n}\n\nsass-tools.$rtl: true;\n\n.rtl {\n    #{sass-tools.$padding-left}: sass-tools.$gel-spacing-unit; // 8px\n}\n\n```\n\nThis will compile out to:\n\n```css\n.ltr {\n    padding-left: 8px;\n}\n\n.rtl {\n    padding-right: 8px;\n}\n```\n\n#### Best practices \u0026 Tips\n\n- Don't flip everything! Only flip what needs to be flipped. This will help keep the CSS as clean and predictable as possible.\n- Styles which are hiding elements by pushing them off the screen (e.g. `text-align: -320px;` or `right: 5000%;`) don't need to be flipped unless they are being transitioned or overridden.\n- If left and right properties have the same values in the same selector, they don't need to be flipped (e.g. `margin-left: 0;` `margin-right: 0;`)\n\n## Credits\n\n- [Shaun Bent](https://twitter.com/shaunbent)\n- [Al Jones](https://twitter.com/Itsaljones)\n\n## License\n\n\u003e The MIT License (MIT)\n\u003e\n\u003e Copyright 2016 British Broadcasting Corporation\n\u003e\n\u003e Permission is hereby granted, free of charge, to any person obtaining a copy of\n\u003e this software and associated documentation files (the \"Software\"), to deal in\n\u003e the Software without restriction, including without limitation the rights to\n\u003e use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\n\u003e the Software, and to permit persons to whom the Software is furnished to do so,\n\u003e subject to the following conditions:\n\u003e\n\u003e The above copyright notice and this permission notice shall be included in all\n\u003e copies or substantial portions of the Software.\n\u003e\n\u003e THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n\u003e IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\n\u003e FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\n\u003e COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\n\u003e IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\n\u003e CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fgel-sass-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbc%2Fgel-sass-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fgel-sass-tools/lists"}