{"id":13672302,"url":"https://github.com/css-modules/icss","last_synced_at":"2025-09-10T21:21:21.750Z","repository":{"id":66014330,"uuid":"37448605","full_name":"css-modules/icss","owner":"css-modules","description":"Interoperable CSS — a standard for loadable, linkable CSS","archived":false,"fork":false,"pushed_at":"2017-06-01T11:29:45.000Z","size":5,"stargazers_count":630,"open_issues_count":6,"forks_count":24,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-03-29T11:11:20.087Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"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/css-modules.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-15T06:53:59.000Z","updated_at":"2025-03-28T14:32:18.000Z","dependencies_parsed_at":"2023-03-27T23:11:35.809Z","dependency_job_id":null,"html_url":"https://github.com/css-modules/icss","commit_stats":{"total_commits":6,"total_committers":6,"mean_commits":1.0,"dds":0.8333333333333334,"last_synced_commit":"7bd4f6fb4e53c6617455a5176b7382814aaacd4a"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/css-modules%2Ficss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/css-modules%2Ficss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/css-modules%2Ficss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/css-modules%2Ficss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/css-modules","download_url":"https://codeload.github.com/css-modules/icss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332612,"owners_count":20921853,"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-08-02T09:01:31.701Z","updated_at":"2025-04-05T12:08:06.239Z","avatar_url":"https://github.com/css-modules.png","language":null,"readme":"\u003cimg src=\"https://raw.githubusercontent.com/css-modules/logos/master/css-modules-logo.png\" width=\"150\" height=\"150\" /\u003e\n\n# Interoperable CSS (ICSS)\n\nThis document describes the specification of the low-level file format that enabled CSS Modules. This is designed for loader-implementers, not for end-users. For the high-level specification, see the full [CSS Modules](https://github.com/css-modules/css-modules/blob/master/README.md) spec.\n\n## Rationale\n\nAs JavaScript workflows have trended towards building collections of components, CSS workflows have followed suit. However, any progress on the CSS front has been purely *conventional*, not supported by the language. The most visible example of this is the [BEM methodology](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/), but the argument is common to many approaches:\n\n- Styles should be scoped to a single component\n- All CSS selectors are global\n- ∴ Develop a convention for ensuring globally-unique selectors\n\nIn BEM, that takes the form `.block-name__element-name--modifier-name`, or `.BlockName__elementName--modifierName`.\n\n### Explicit cross-language dependencies\n\nOne of the fundamental features of the Webpack loader (which is also core to JSPM and easily possible with Browserify) is the ability to explicitly describe each file's dependencies **regardless of the type of source file**. For CSS in a component workflow, that takes the following form:\n\n```js\n// Marks the CSS as being a dependency of this JS.\n// Depending on the loader, the CSS is either injected\n// into the DOM or bundled into a separate CSS package.\nrequire( './my-component.css' );\nvar MyComponent = // component definition\nmodule.exports = MyComponent;\n```\n\nNow, whenever `my-component.js` is loaded or bundled, the corresponding CSS is guaranteed to be present, just like any other dependency. This convention leads us to a new capability, and necessitates a new specification.\n\n### CSS - JS interoperability\n\nBy treating the CSS as a dependency of our JS, we have the opportunity to do something hitherto impossible – **pass variables from CSS to JS**. For example, instead of this:\n\n```js\n// loads the CSS as a side-effect\nrequire( './my-component.css' );\n```\n\nwe can now pass arbitrary information to our loader:\n\n```js\n// loads the CSS as a side-effect and returns\n// something we can use in rendering our component.\nvar styles = require( './my-component.css' );\n// this might be a dynamically-generated classname:\nelem.addClass( styles.elemClass );\n```\n\nThis is the key capability that is new to modern multi-format loaders like Webpack, JSPM and Browserify, and the [CSS Modules Specification](https://github.com/css-modules/css-modules/blob/master/README.md) is an opinionated proposal of new CSS techniques this enables. However, at the fundamental level, we need a specification that describes the *mechanism* by which these symbols are passed around.\n\n## Specification\n\nInteroperable CSS (ICSS) is a superset of standard CSS, making use of two additional pseudo-selectors:\n\n```css\n:import(\"path/to/dep.css\") {\n  localAlias: keyFromDep;\n  /* ... */\n}\n:export {\n  exportedKey: exportedValue;\n\t/* ... */\n}\n```\n\n### :export\n\nAn `:export` block defines the symbols that are going to be exported to the consumer. It can be thought of functionally equivalent to the following JS:\n\n```js\nmodule.exports = {\n\t\"exportedKey\": \"exportedValue\"\n}\n```\n\nThe following restrictions are placed on the `:export` syntax:\n\n- It must be at the top level, but can be anywhere in the file.\n- If there is more than one in a file, the keys and values are combined and exported together.\n- If a particular `exportedKey` is duplicated, the last (in source order) takes precedence.\n- An `exportedValue` may contain any character valid for CSS declaration values (including spaces).\n- An `exportedValue` does not need to be quoted, it is already treated as a literal string.\n\nThe following are desirable for output readability, but not enforced:\n\n- There should be only one `:export` block\n- It should be located at the top of the file, but after any `:import` blocks\n\n### :import\n\nAn `:import` statement allows importing variables from other CSS files. It performs the following operations:\n\n- Fetch \u0026 process the dependency\n- Resolve the dependency's exports against the imported tokens, and match them up to a `localAlias`\n- Find and replace the usages of `localAlias` in certain places (described below) within the current file with the dependency's `exportedValue`.\n\nThe places within the CSS file that are checked for `localAlias` are:\n\n- In any declaration value:\ne.g. `border: 1px solid localAlias;`\n- In any selector:\ne.g. `.localAlias .MyComponent {}`\n- In a media query argument:\ne.g. `@media screen and localAlias`\n\nThis allows considerable flexibility about what can be imported and used in a file. It also demands that a particular local alias is distinct enough to not cause false positives during the replacement process. The following restrictions apply:\n\n- It must be at the top level\n- Each file can import from multiple dependencies, and import many symbols\n- A local alias must be a single term, consisting of only alphanumeric characters, underscores and dashes. It must also be unique for the file to avoid clashes.\n\nAnd the following properties are desirable for readability but not enforced:\n\n- There should be one import per dependency\n- All imports should be at the top of the file\n- Local aliases should be prefixed with double-underscore\n\n# Contributions\n\nEdit this file and make your change to the spec, then send a PR with your argument for why the change should be made. All contributions are welcome.\n\n# Acknowledgements\n\nWith thanks to:\n- Mark Dalgleish\n- Tobias Koppers\n- Ben Smithett\n- Guy Bedford\n\n---\n\nGlen Maddern, 2015.\n","funding_links":[],"categories":["Others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcss-modules%2Ficss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcss-modules%2Ficss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcss-modules%2Ficss/lists"}