maykinmedia/microscope-sass

Sass microframework for building scoped user interfaces.

🔬 Microscope

Sass microframework for building scoped user interfaces.

• Changelog.
• Documentation on github pages.

Microscope is a microframework with a light footprint (0kb by default) which only applies styling to explicitly selected elements* (by you) based on highly configurable defaults.

0kb footprint

Microscope only exposes functions, mixins and variables (so no default styling*). CSS is only generated if needed.

Explicitly selected elements

Because no default styling is present, Microscope works well in combination with existing styling or other libraries.

Highly configurable

Microscope contains a large amount of settings (with sane defaults) which configure the created CSS code. Many settings have variations and/or optional breakpoint specific overrides which allow for more specific configurations. The settings can be specified in a settings file which acts as a digital representation of your style guide.

* With the exception of the wysiwyg and table mixins, which applies formatting to children automatically (only if called).

Install

Install with npm

npm i microscope-sass --save

Webpack

To use Microscope with webpack, install and configure sass-loader.

Webpack style import:

@import '~microscope-sass/lib/<library>';  // Import single library (recommended).
@import '~microscope-sass';                // Import everything at once.

Eyeglass

For historic reasons, the Eyeglass import is referenced as "microscope" insead of "microscope-sass".

Microsope supports Eyeglass in which case it can be referenced as "microscope".

Eygeglass style import:

@import 'microscope/lib/<library>';  // Import single library (recommended).
@import 'microscope';                // Import everything at once.

includePaths

Add "node_modules/" to the includePaths setting of you sass environment.

...
includePaths: ["node_modules/"],
...

includePaths style import:

@import 'microscope-sass/lib/<library>';  // Import single library (recommended).
@import 'microscope-sass';                // Import everything at once.

Note: Further documentations assumes a webpack installation and webpack style imports.

Usage

Configuration

Adjust settings_sample.scss based on your needs, note that all options are optional and unnecessary options can be omitted and removed.

Save the settings file and make sure to include it as the first file in you main .scss entrypoint.

@import 'settings';

Libraries

Microscope exposes the following libraries, please refer to their documentation functions, mixins and variables are exposed.

• animation
• browser
• color
• grid
• responsive
• transform
• typography
• util

Importing a single library (preferred)

In any of your (nested) .scss files, import the libraries you need. The libraries will use your custom settings if set.

@import '~microscope-sass/lib/grid';

Import everything at once

It's also possible to import all libraries at once.

@import '~microscope-sass';

Applying styles

Microscope is designed to help styling isolated bits of HTML. The recommended use is to target class selectors so styles are remain scoped and don't leak out to other places.

@import '~microscope-sass/lib/color';
@import '~microscope-sass/lib/typography';

.header__title {
    @include h1;
    @include color-primmary;
}

A special wysiwyg mixin is availabe (via the typography library to automatically apply elements based on their tag name. It's recommended to only use this when the internal structure is unknown (for instance when styling the output of a wysiwyg editor).

@import '~microscope-sass/lib/typography';

.wysiwyg {
    @include wysiwyg;
}

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Author

Maykin Media

• maykinmedia.nl
• github/maykinmedia
• twitter/maykinmedia

License

Copyright © 2019 Maykin Media Licensed under the MIT license.

microscope-sass's Issues

Grid: Support arbitrary amount of container configurations.

Add SassDoc docstrings.

Add BEM mixin(s)

Add documentation (after completing writing docstrings).

Transform: support right and bottom in absolute positioning.

Grid: increase the amount of arguments for container mixin(s).

Grid: Support CSS grid.

(global) default variables machinery does not work with @use

Sass has introduced @use and @forward to deal with modules, and are planning on phasing out @import. On major side-effect of this is that @use/@forward apply namespaces. The mixins in microscope-sass do not properly work with this, as the default variables can no longer be globally overridden.

It seems that the whole architecture of using sass-module level 'global' defaults for variables and defining overrides in your own project will no longer work when @import is no longer supported.

See:

• https://sass-lang.com/blog/the-module-system-is-launched#future-plans
• https://stackoverflow.com/questions/60012955/how-to-use-a-sass-variable-across-multiple-pages-using-use

Responsive: Add media screen to media queries.

Remove "!default" flags from _settings_sample.scss.

Animation: animate mixing with default properties is broken.

Typography: support letter-spacing.

Grid: support multiple $properties for rows mixin