{"id":24568994,"url":"https://github.com/zicht/zss","last_synced_at":"2025-04-22T17:24:21.538Z","repository":{"id":47162562,"uuid":"70049781","full_name":"zicht/zss","owner":"zicht","description":"Library - 📐 Sass for design systems","archived":false,"fork":false,"pushed_at":"2025-01-14T11:42:52.000Z","size":321,"stargazers_count":21,"open_issues_count":9,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-14T12:50:01.857Z","etag":null,"topics":["css","design-systems","functional-css","responsive-design","sass"],"latest_commit_sha":null,"homepage":"","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/zicht.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-05T10:18:57.000Z","updated_at":"2025-01-14T11:42:55.000Z","dependencies_parsed_at":"2024-09-14T00:22:53.040Z","dependency_job_id":"19cf1afd-8a6a-4dad-8b4e-ee9369bf5760","html_url":"https://github.com/zicht/zss","commit_stats":{"total_commits":173,"total_committers":14,"mean_commits":"12.357142857142858","dds":"0.34104046242774566","last_synced_commit":"9e06297305163ab0f9e7d1f9fc2c27882f288c14"},"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zicht%2Fzss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zicht%2Fzss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zicht%2Fzss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zicht%2Fzss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zicht","download_url":"https://codeload.github.com/zicht/zss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235300321,"owners_count":18967738,"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","design-systems","functional-css","responsive-design","sass"],"created_at":"2025-01-23T14:55:56.135Z","updated_at":"2025-01-23T14:55:56.963Z","avatar_url":"https://github.com/zicht.png","language":"SCSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📐 ZSS – Sass for design systems\n\nZSS is a Sass framework that helps you build design systems with configurable design scales.\n\n---\n- [Documentation](#documentation)\n- [Background](#background)\n  - [What it does](#what-it-does)\n  - [What it doesn’t do](#what-it-doesnt-do)\n  - [Principles](#principles)\n- [Setup](#setup)\n- [Structure](#structure)\n  - [Class names](#class-names)\n  - [Source order](#source-order)\n  - [Responsive](#responsive)\n- [How to use](#how-to-use)\n  - [Configuration and variables](#configuration-and-variables)\n    - [Design scales](#design-scales)\n    - [Other variables](#other-variables)\n  - [Development checks](#development-checks)\n  - [Helpers](#helpers)\n  - [Generic](#generic)\n  - [Base](#base)\n  - [Abstract objects](#abstract-objects)\n  - [Utility classes](#utility-classes)\n- [Add-ons and tools](#add-ons-and-tools)\n  - [Third party](#third-party)\n---\n## Documentation\n\nThis overview provides an in depth view of all of the available properties/classes in ZSS.\n- [Property-index](docs/property-index.md) \n\n## Background\n\n### What it does\n\n- Provides a simple base for your typography.\n- Provides abstractions of common UI patterns, so you can focus on the specific design details.\n- Functional CSS: generates immutable, configurable, and responsive utility classes.\n- Provides a flexible and configurable flexbox grid.\n- Provide compile time checking of your configuration for design smells.\n\n### What it doesn’t do\n\n- No pre-defined colors.\n- Unlike Bootstrap, ZSS does not contain pre-made components or JavaScript.\n\n### Principles\n\nZSS is built on a few principles.\n\n- **Composition over repetition**   \n  The `class` attribute is perfect for composing your design with multiple classes. It leads to better re-usability of your design and smaller CSS stylesheets.\n- **Configurable and optional**   \n  In ZSS, generated utility classes have configurable values. Need an extra value, or don’t like the default values? Just override a variable in your project. Don’t need the button abstraction class? Just don’t import it.\n- **Responsiveness**   \n  All utility classes have responsive equivalents, so you can use different values on different screens.\n- **Design scales**   \n  ZSS uses scales to limit the number of available values for certain properties, like `color` and `margin`.\n\n## Setup\n\nInstall:\n\n```cli\nnpm install zss --save\n```\n\nAfter that, import the files you need into your Sass stylesheet.\n\n```sass\n@import \"../node_modules/zss/src/utilities/background-color\";\n``` \n\nℹ️ Please note that some utility classes make use of the responsive helper mixins. To make sure ZSS compiles correctly import these before you import the utility classes:\n\n```sass\n@import \"../node_modules/zss/src/helpers/responsive\";\n@import \"../node_modules/zss/src/utilities/margin\";\n```\n\nℹ️ You can use the accompanying file [`zss.scss`](src/zss.scss) as a starting point for your project's stylesheet. It imports all files that are available in ZSS.\n\n## Structure\n\n### Class names\n\nZSS uses namespaces, similar to the system [CSS Wizardry](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/) wrote about.\n\n- `o-` prefix for abstract objects.\n- `u-` prefix for utility classes.\n\n### Source order\n\nZSS advocates importing sources files in the way [ITCSS](http://itcss.io/) prescribes, with an inverted specificity.\n\n1. Settings and variables\n2. Mixins and other Sass helpers\n3. Generic: common resets\n4. Base: unclassed HTML and page setup\n5. Abstract objects\n6. Components\n7. Scopes\n8. Theming\n9. Visual classes\n10. Utility classes\n\n### Responsive\n\nZSS uses an `@breakpoint` suffix to indicate if a class only works on a certain breakpoint, e.g. `u-black@md`.\n\n---\n\n## How to use\n\n### Configuration and variables\n\nAll ZSS variables are defined in [variables/_zss-defaults.scss](src/variables/_zss-defaults.scss). Override them at will in your project.\n\n```sass\n@import '../node_modules/zss/src/variables/zss-defaults';\n@import 'variables/zss-overrides';\n```\n\n#### Design scales\n\nVariable     | Explanation\n------------ | ----------\n`$zss--opacity-scale` | Limited set of values for opacity utility classes.\n`$zss--border-radius-scale` | Limited set of values for border-radius utility classes.\n`$zss--border-width-scale` | Limited set of values for border-width classes.\n`$zss--spacing-scale` | Limited set of values for margin and padding utility classes. \n`$zss--type-scale` | Limited set of values for font-size utility classes.\n`$zss--line-height-scale` | Limited set of values for line-height utility classes.\n`$zss--width--scale` | Limited set of values for width utility classes.\n`$zss--width--percentage-scale` | Limited set of values for width utility classes, in percentages.\n`$zss--max-width--scale` | Limited set of values for max-width utility classes.\n`$zss--height--scale` | Limited set of values for height utility classes.\n`$zss--height--percentage-scale` | Limited set of values for height utility classes, in percentages.\n\n#### Other variables\n\nVariable     | Explanation\n------------ | ----------\n`$zss--colors` | Sass map with color definitions for text, backgrounds and borders utility classes.\n`$zss--grid-max-widths` | Sass map containing the max width of the grid on each breakpoint.\n`$zss--grid-columns` | The number of columns a grid row can have.\n`$zss--grid-gutter` | The amount of whitespace between grid column.\n`$zss--breakpoints` | Sass map containing breakpoint names and screen sizes.\n`$zss--border-colors` | Sass map containing color definitions for border utility classes.\n`$zss--base-font-size` | Font size used a base for `rem` values.\n`$zss--base-line-height` | Base line-height applied to the BODY element.\n`$zss--media-margin` | The margin between the image and text of media objects.\n\n### Development checks\n\nZSS provides compile time checking of the configuration. Import `dev/strict` if you want to:\n   \n   - Check if the design scales are properly ordered.\n   - Check if there are any so called design smells, like too many font sizes in your scales.\n\nSee [the documentation](docs/tools/strict.md) for more details.\n\n### Helpers\n\nHelpers are mixins, functions, and similar programmatic constructs in Sass that help with code re-use. ZSS provides these helpers:\n\n- [color](docs/tools/color.md): function for accessing pre-defined colors.\n- [grid](docs/tools/grid.md): mixin for generating grid classes.\n- [hover](docs/tools/hover.md): mixin for generating flexible hover effects.\n- [responsive](docs/tools/responsive.md): mixin for dealing with responsive declarations.\n- [units](docs/tools/units.md): functions for dealing with units and values.\n\n### Generic\n\nThe [generic](src/generic) folder contains CSS applied at a global level:\n\n- [border-box](docs/global/border-box.md)\n- [hard-reset](docs/global/hard-reset.md)\n- [normalize.css](docs/global/normalize.css.md)\n\n### Base\n\nThe [base](src/base) folder contains CSS applied to specific elements:\n\n- [typography](docs/global/typography.md)\n\n### Abstract objects\n\nObjects are classes that define the structure of a common UI pattern, like the popular media object. ZSS provides these objects:\n\n- [button](docs/layout/button.md): a gathering of properties most used in buttons.\n- [grid](docs/layout/grid.md): a grid structure to create a layout with rows and columns.\n- [list-reset](docs/layout/list-reset.md): resets ordered and unordered lists.\n- [media](docs/layout/media.md): image next to text.\n\n### Utility classes\n\nUtility classes have a single responsibility. In other words, they affect the value of just one single CSS property. (This\nconstruct is also known as functional CSS.) The most common CSS properties are available in ZSS and are listed\nin the [**property index** 📇](docs/property-index.md).\n\n## Add-ons and tools\n\nThese tools and add-ons make working with ZSS even easier.\n\n### Third party\n\n- [**color-name**](https://github.com/joppe/color-name)   \nCLI that parses the output of http://www.color-blindness.com/color-name-hue/ for easy converting of a hexadecimal color value to a name that can be used in ZSS to generate class names (e.g. `u-yellow--tangerine`).\n\n## Maintainer\n\n- Annemieke van der Hoek ([@avanderhoek](https://github.com/avanderhoek/)) – [Zicht](https://github.com/zicht)\n- Jurg Roessen ([@Hangloozz](https://github.com/Hangloozz/)) – [Zicht](https://github.com/zicht)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzicht%2Fzss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzicht%2Fzss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzicht%2Fzss/lists"}