{"id":22379114,"url":"https://github.com/sky-uk/supercell","last_synced_at":"2025-07-31T01:31:47.340Z","repository":{"id":9209630,"uuid":"54385112","full_name":"sky-uk/supercell","owner":"sky-uk","description":"Grid-like Layout System","archived":false,"fork":false,"pushed_at":"2023-10-03T17:05:10.000Z","size":7667,"stargazers_count":14,"open_issues_count":13,"forks_count":2,"subscribers_count":121,"default_branch":"master","last_synced_at":"2024-11-04T05:27:33.612Z","etag":null,"topics":["grid","grid-system","scss"],"latest_commit_sha":null,"homepage":"http://sky-uk.github.io/supercell/","language":"CSS","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/sky-uk.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-21T12:00:40.000Z","updated_at":"2023-05-30T11:23:03.000Z","dependencies_parsed_at":"2024-06-21T05:47:02.738Z","dependency_job_id":"63ac72d5-b830-4d02-95e1-e83dc307977d","html_url":"https://github.com/sky-uk/supercell","commit_stats":{"total_commits":43,"total_committers":3,"mean_commits":"14.333333333333334","dds":"0.37209302325581395","last_synced_commit":"471ef41d163e70cbf01c8d894e6f28fdc6a8d74b"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky-uk%2Fsupercell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky-uk%2Fsupercell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky-uk%2Fsupercell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky-uk%2Fsupercell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sky-uk","download_url":"https://codeload.github.com/sky-uk/supercell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228054426,"owners_count":17862129,"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":["grid","grid-system","scss"],"created_at":"2024-12-04T23:09:00.633Z","updated_at":"2024-12-04T23:09:01.331Z","avatar_url":"https://github.com/sky-uk.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/supercell.svg)](https://badge.fury.io/js/supercell)\n\n# Supercell\n\n\u003e **Fluid, responsive, nestable, reorderable, mobile-first layouts.**\n\nSupercell is an [ITCSS-compatible](https://twitter.com/itcss_io) library for building grid-like structures in our\nUIs.\n\nIt can be consumed on its own, or as part of [Toolkit](https://github.com/sky-uk/toolkit).\n\n## Contents\n\n1. [Installation](#installation)\n2. [Configuration](#configuration)\n3. [Usage](#usage)\n4. [Responsive](#responsive)\n5. [Options](#options)\n6. [Example](#example)\n7. [Versioning](#versioning)\n8. [Contributing](#contributing)\n\n**N.B.** If you are using Supercell as part of [Toolkit](https://github.com/sky-uk/toolkit), you will not need to install or configure anything. Please ignore the first two sections.\n\n## Installation\n\nSupercell is split into two core files:\n\n- **`_tools.widths.scss`**, which contains a mixin which we need to call (i.e.\n  Supercell does not execute this mixin itself) in order to generate a suite of\n  (responsive) width classes in the format `.u-width-1/2`.\n- **`_objects.layout.scss`**, which is the actual grid-like structure that will\n  lay out our UI.\n\nThe classes from `_objects.layout.scss` are augmented by the classes generated\nby `_tools.widths.scss`’ mixin in order to create layout structures that are\nsized accordingly, for example:\n\n```HTML\n\u003cdiv class=\"o-layout\"\u003e\n  \u003cdiv class=\"o-layout__item  u-width-1/2\"\u003e\n    ...\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\nThe reason that the layout and the widths are kept in different\nfiles/suites-of-classes is simple: it allows us to use our width classes (e.g.\n`.u-width-1/2@small`) on non-layout related bits of UI, for example, making an\n`img` half of the width of its container in a blog post.\n\n## Configuration\n\nThere are only two parts of Supercell that might need configuring:\n\n1. **The size of the gutters between items.**  \n   To modify the size of the gutters in between layout items, simply predefine\n   the `$supercell-spacing-unit` variable _just before_ you `@import`\n   `objects.layout.scss`, like so:\n\n   ```SCSS\n   $supercell-spacing-unit: 20px;\n   @import \"objects.layout\";\n   ```\n\n2. **The method used to manage rogue whitespace between `inline-block` elements.**  \n   Because Supercell uses `inline-block` (which gives us a number of ways of\n   manipulating our layouts by using text-level CSS properties), we do have the\n   problem of needing to remove the whitespace that is left in between each\n   item.\n\n   There are [a number of ways of handling\n   this](https://jsfiddle.net/9dy6rwfz/), but they usually all require special\n   attention in the markup. These are the most reliable ways of removing the\n   whitespace, but are the least user-friendly.\n\n   By default, Supercell uses the `font-size: 0;` hack to remove the whitespace,\n   without authors needing to do anything in their HTML to combat the problem.\n   This hack is very author-friendly, but isn’t 100% always guaranteed to work.\n   If you would like to disable the `font-size: 0;` hack and are prepared to\n   implement a markup-based fix, predefine the `$use-markup-fix` just before you\n   `@import` `objects.layout`, like so:\n\n   ```SCSS\n   $use-markup-fix: true;\n   @import \"objects.layout\";\n   ```\n\n## Usage\n\nTo generate your width classes (e.g. `.u-width-1/2`) you need to call the\n`supercell()` mixin in your project, passing in the number of columns you would\nlike to create.\n\nTo create a 12 column layout system, simply call the mixin like\nso:\n\n```SCSS\n@include supercell(12);\n```\n\nTo generate a 12 and a 16 column layout system, call the mixin like so:\n\n```SCSS\n@include supercell(12 16);\n```\n\nTo generate a 3, a 4, and an 8 column layout system, call the mixin like so:\n\n```SCSS\n@include supercell(3 4 8);\n```\n\nSupercell will now generate a full suite of classes that will satisfy every\npossible width that falls into those boundaries.\n\n### Responsive\n\nIn the interests of being as unopinionated as possible, Supercell will not\nauto-generate any media queries or responsive classes. This is because the\nimplementor (i.e. _you_) should be able to decide where your breakpoints land,\nand what their values are. It also allows the implementor to use their media\nquery manager of choice (e.g. I like [Sass\nMQ](https://github.com/sass-mq/sass-mq)) or nothing at all.\n\nTo generate responsive variants, simply call the mixin again with two distinct\nadditions:\n\n1. The mixin must be called within a media query.\n2. You must provide a [Responsive\n   Suffix](http://csswizardry.com/2015/08/bemit-taking-the-bem-naming-convention-a-step-further/#responsive-suffixes)\n   parameter which denotes the point at which that class takes effect.\n\nTo generate a 12 column layout system for use on screens over 1200px wide:\n\n```SCSS\n@media screen and (min-width: 1200px) {\n  @include supercell(12, \\@large);\n}\n```\n\nThis will create a suite of classes—that only exist in scenarios over 1200px\nwide—that look like this:\n\n```CSS\n@media screen and (min-width: 1200px) {\n\n  .u-width-1/12@large {\n    width: 8.333333333% !important;\n  }\n\n  .u-width-2/12@large {\n    width: 16.666666667% !important;\n  }\n\n  ...\n\n  .u-width-11/12@large {\n    width: 91.666666667% !important;\n  }\n\n\n  .u-width-12\\/12@large {\n    width: 100% !important;\n  }\n\n\n}\n```\n\n## Options\n\nThere are a _lot_ of different options (and combinations of options) for\ndifferent styles of layout. Below is a rough summary, but please refer to the\ncomments in the Sass for a more complete description of what each option\nprovides.\n\n- **`.o-layout--[narrow|wide|flush]`**: Narrow, wide, or no gutters between\n  items.\n- **`.o-layout--[middle|bottom]`**: Align all items to the vertical middles or\n  bottoms of each other (top alignment is the default).\n- **`.o-layout--[center|right]`**: Begin filling up layout items from the\n  horizontal center or the right hand side of the layout context (filling from\n  the left is the default).\n- **`.o-layout--reverse`**: Completely reverse the displayed order of the layout\n  items.\n- **`.o-layout--spaced`**: Add vertical gutters to layout items (they do not\n  carry vertical spacing by default).\n\n## Example\n\n```HTML\n\u003cul class=\"o-layout  o-layout--reverse\"\u003e\n\n  \u003cli class=\"o-layout__item\n             u-width-1/1  u-width-1/4@medium  u-width-1/2@large\"\u003e\n    100% by default, then 25% width on medium screens, before finally being 50%\n    width on large screens and beyond. Displays last on-screen despite being\n    defined first in the markup.\n  \u003c/li\u003e\n\n  \u003cli class=\"o-layout__item\n             u-width-1/2  u-width-1/4@medium\"\u003e\n    50% width by default, then 25% width on medium screens and beyond. Displays\n    third on-screen despite being defined second in the markup.\n  \u003c/li\u003e\n\n  \u003cli class=\"o-layout__item\n             u-width-1/2  u-width-1/4@medium\"\u003e\n    50% width by default, then 25% width on medium screens and beyond. Displays\n    second on-screen despite being defined third in the markup.\n  \u003c/li\u003e\n\n  \u003cli class=\"o-layout__item\n             u-width-1/1  u-width-1/4@medium  u-width-1/1@large\"\u003e\n    100% by default, then 25% width on medium screens, before finally being 100%\n    width again on large screens and beyond. Displays first on-screen despite\n    being defined last in the markup.\n  \u003c/li\u003e\n\n\u003c/ul\u003e\n```\n\n## Versioning\n\nSupercell follows Semantic Versioning to help manage the impact of releasing new library versions.\n\n## Contributing\n\nWe appreciate **any** contribution to Supercell.\n\nWe keep a list of features and bugs in the [issue tracker](https://github.com/sky-uk/supercell/issues).\n\n### Maintainers\n\nSupercell is maintained by the [Toolkit Maintainers](https://github.com/sky-uk/toolkit#maintainers) and [Harry Roberts](https://github.com/csswizardry).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsky-uk%2Fsupercell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsky-uk%2Fsupercell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsky-uk%2Fsupercell/lists"}