CSS module support, @extend support, and more

.gitignore

@@ -1,5 +1,7 @@
 node_modules
 
-# Don't commit this for libraries :)
+# Don't commit these for libraries :)
 yarn.lock
 package-lock.json
+
+/test/output

CHANGELOG.md

@@ -1,3 +1,34 @@
+## [v0.3.0.rc.1]
+
+> Unreleased
+
+v0.3.0 is an almost-full rewrite. It now supports more PostCSS setups. Use it as CSS modules, functional selectors (`@extend`), or custom property sets (`@apply`).
+
+- **Breaking change:** The filenames have been changed. Since responsive-modular-scale now comes in 3 flavors, you'll need to specify the variant you want. The old default is available as `modularscale.apply.css`.
+
+  ```css
+  /* Before (v0.2.0) */
+  @import 'responsive-modular-scale.css';
+
+  /* After (v0.3.0) */
+  @import 'responsive-modular-scale.css/defaults.css';
+  @import 'responsive-modular-scale.css/modularscale.apply.css';
+  ```
+
+- **Breaking change:** The classnames have been changed. `--font-size-X` is now `--ms-font-size-X` to prevent potential name clashes.
+
+  ```css
+  /* Before (v0.2.0) */
+  @apply --font-size-2;
+
+  /* After (v0.3.0) */
+  @apply --ms-font-size-2;
+  ```
+
+- **New:** Responsive-modular-scale is now available as a CSS module with `modularscale.module.css`. See [README.md](./README.md) for info.
+
+- **New:** Responsive-modular-scale now works as functional selectors (aka, `@extend`) with `modularscale.extend.css`. See [README.md](./README.md) for info.
+
 ## [v0.2.0]
 
 > Jan 17, 2019

README.md

@@ -6,6 +6,9 @@ This implements a basic [Modular Scale](http://www.modularscale.com/) system usi
 
 [postcss-cssnext]: https://www.npmjs.com/package/postcss-cssnext
 [postcss-import]: https://www.npmjs.com/package/postcss-import
+[postcss-custom-media]: https://yarnpkg.com/en/package/postcss-custom-media
+[postcss-custom-properties]: https://yarnpkg.com/en/package/postcss-custom-properties
+[postcss-preset-env]: https://github.com/csstools/postcss-preset-env
 
 ## Installation
 
@@ -19,12 +22,40 @@ npm install --save --save-exact responsive-modular-scale.css
 
 ## Usage
 
-Simply import it, assuming you're using [postcss-import] and [postcss-cssnext].
+`responsive-modular-scale.css` can be used in 3 different ways:
+
+### Functional selectors (`postcss-extend-rule`)
+
+See [§ Usage as functional selectors](#usage-as-functional-selectors).
+
+```css
+.title {
+  @extend %ms-font-size-2;
+}
+```
+
+### Property sets (`postcss-apply`)
+
+See [§ Usage as property sets](#usage-as-property-sets).
+
+```css
+.title {
+  @apply --ms-font-size-2;
+}
+```
+
+### CSS modules
+
+See [§ Usage as a CSS module](#usage-as-a-css-module).
 
 ```css
-@import 'responsive-modular-scale.css';
+.title {
+  composes: msFontSize2 from 'responsive-modular-scale.css/modularscale.module.css';
+}
 ```
 
+## How it works
+
 To use it, use any of the provided `--font-size-#` custom property sets:
 
 ```css
@@ -35,35 +66,34 @@ div {
 
 This applies a `font-size: 2.0736rem` declaration for desktops—the default ratio is 1.2, so that's `1rem * 1.2 ^ 4`. For mobiles and tablets, it will use a different ratio (1.15 and 1.17 by default).
 
+<details>
+<summary><em>View sample output</em></summary>
+
 ```css
-div { font-size: 1.74901rem; }
+div {
+  font-size: 1.74901rem;
+}
 
 @media (min-width: 481px) {
-  div { font-size: 1.87389rem; }
+  div {
+    font-size: 1.87389rem;
+  }
 }
 
 @media (min-width: 769px) {
-  div { font-size: 2.0736rem; }
+  div {
+    font-size: 2.0736rem;
+  }
 }
 ```
 
-It gives you the following custom property sets:
-
- - `@apply --font-size--1` (negative 1)
- - `@apply --font-size-0` (applies to base font size)
- - `@apply --font-size-1`
- - `@apply --font-size-2`
- - ... `@apply --font-size-20`
+</details>
 
+## Configuring settings
 
-## Configuration
-
-It's recommended you include this in a "common" file included in most of your project's files; usually, that's something like `variables.css`. You can change these ratios and breakpoints like so:
+Set up a `variables.css` with your configuration. Consider placing this wherever you put your common variables (eg, color palettes and font names). See: [`defaults.css`](./defaults.css).
 
 ```css
-/* variables.css */
-@import 'responsive-modular-scale.css';
-
 :root {
   --ms-ratio-sm: 1.15;
   --ms-ratio-md: 1.17;
@@ -78,19 +108,152 @@ It's recommended you include this in a "common" file included in most of your pr
 @custom-media --ms-viewport-lg (width > 768px);
 ```
 
+## Usage as functional selectors
+
+To use this as functional selectors (ie, `@extend`), you'll need these PostCSS plugins:
+
+- [**postcss-prepend-imports**](postcss-prepend-imports)
+- [**postcss-extend-rule**](postcss-extend-rule)
+- [**postcss-preset-env**](postcss-preset-env)
+
+Configure PostCSS to load these plugins and import your variables. Here's an example config:
+
+```js
+/* postcss.config.js */
+module.exports = ctx => {
+  return {
+    plugins: [
+      // ...
+      require('postcss-prepend-imports')({
+        files: [
+          require.resolve(
+            'responsive-modular-scale.css/responsive-modular-scale.css'
+          )
+        ]
+      }),
+      require('postcss-preset-env')({
+        importFrom: [require.resolve('./your/path/to/variables.css')],
+        insertBefore: {
+          'all-property': [require('postcss-extend-rule')()]
+        }
+      })
+      // ...
+    ]
+  }
+}
+```
+
+You'll then be able to use them with `@extend` in your CSS.
+
 ```css
-/* your-other-styles.css */
-@import './variables.css';
+.title {
+  @extend %ms-font-size-2;
+}
+```
 
-body {
-  @apply --font-size-0;
+These selectors will become available:
+
+- `@extend %ms-font-size--1` (negative 1)
+- `@extend %ms-font-size-0` (applies the base font size)
+- `@extend %ms-font-size-1`
+- `@extend %ms-font-size-2`
+- ...
+- `@extend %ms-font-size-20`
+
+## Usage as property sets
+
+You can also apply modular scale font sizes using CSS property sets (aka, `@apply`). You'll need these PostCSS plugins:
+
+- [**postcss-prepend-imports**](postcss-prepend-imports)
+- [**postcss-apply**](postcss-apply)
+- [**postcss-preset-env**](postcss-preset-env)
+
+Configure PostCSS to load these plugins and import your variables. Here's an example config:
+
+```js
+/* postcss.config.js */
+module.exports = ctx => {
+  return {
+    plugins: [
+      // ...
+      require('postcss-prepend-imports')({
+        files: [
+          require.resolve(
+            'responsive-modular-scale.css/responsive-modular-scale.css'
+          )
+        ]
+      }),
+      require('postcss-apply')(),
+      require('postcss-preset-env')({
+        importFrom: [require.resolve('./your/path/to/variables.css')]
+      })
+      // ...
+    ]
+  }
 }
+```
 
-div {
-  @apply --font-size-4;
+You'll then be able to use them with `@apply` in your CSS.
+
+```css
+.title {
+  @apply --ms-font-size-2;
 }
 ```
 
+These property sets will become available:
+
+- `@apply --font-size--1` (negative 1)
+- `@apply --font-size-0` (applies the base font size)
+- `@apply --font-size-1`
+- `@apply --font-size-2`
+- ...
+- `@apply --font-size-20`
+
+## Usage as a CSS module
+
+:warning: `Experimental` - You can apply modular scale font sizes using CSS modules.
+
+To use this as functional selectors (ie, `@extend`), you'll need these PostCSS plugins:
+
+- [**postcss-preset-env**](postcss-preset-env)
+
+Configure PostCSS to load these plugins and import your variables. Here's an example config:
+
+```js
+/* postcss.config.js */
+module.exports = ctx => {
+  return {
+    plugins: [
+      // ...
+      require('postcss-preset-env')({
+        importFrom: [require.resolve('./your/path/to/variables.css')]
+      })
+      // ...
+    ]
+  }
+}
+```
+
+You'll then be able to use them with `composes` in your CSS.
+
+```css
+.myButton {
+  composes: msFontSize2 from 'responsive-modular-scale.css/modularscale.module.css';
+}
+```
+
+These CSS classes are available:
+
+- `msFontSizeMinus1` (negative 1)
+- `msFontSize0` (applies the base font size)
+- `msFontSize1`
+- `msFontSize2`
+- ...
+- `msFontSize20`
+
+Learn more about the `composes:` property from the [CSS modules documentation](https://github.com/css-modules/css-modules#composition).
+
 ## Prior art
 
 - [postcss-modular-scale](https://www.npmjs.com/package/postcss-modular-scale) is a PostCSS plugin. However, it doesn't support responsive ratios, and the syntax is non-standard CSS.
@@ -112,5 +275,9 @@ Authored and maintained by Rico Sta. Cruz with help from contributors ([list][co
 > GitHub [@rstacruz](https://github.com/rstacruz) &nbsp;&middot;&nbsp;
 > Twitter [@rstacruz](https://twitter.com/rstacruz)
 
-[MIT]: LICENSE.md
+[mit]: LICENSE.md
 [contributors]: http://github.com/rstacruz/responsive-modular-scale.css/contributors
+[css-modules]: https://github.com/css-modules/css-modules
+[postcss-apply]: https://yarnpkg.com/en/package/postcss-apply
+[postcss-extend-rule]: https://github.com/csstools/postcss-extend-rule
+[postcss-prepend-imports]: https://www.npmjs.com/package/postcss-prepend-imports

defaults.css

@@ -0,0 +1,12 @@
+@custom-media --ms-viewport-md (width > 480px);
+@custom-media --ms-viewport-lg (width > 768px);
+
+:root {
+  --ms-ratio-sm: 1.15;
+  --ms-ratio-md: 1.17;
+  --ms-ratio-lg: 1.2;
+  --ms-base: 1rem;
+  --ms-base-sm: var(--ms-base);
+  --ms-base-md: var(--ms-base-sm);
+  --ms-base-lg: var(--ms-base-md);
+}