SFUMATO SCSS

Get started

How do you want to use SFUMATO?

SFUMATO is simply a folder with SCSS files that you can modify for use with your own web application project. There are a couple ways you can use the framework.

  1. Add the SFUMATO SCSS folder to your project and build your SCSS locally before you deploy or test. This is a standard pattern for using Less/Sass/SCSS.
  2. Add the SFUMATO SCSS folder to your project and let your web server build the SCSS. This requires additional technology, like Carbide (if you're using Umbraco CMS), SharpScss, etc. 

If you're going to build SFUMATO locally and you're not familiar with or setup to build SCSS, continue reading. The information below will get you set up.

Style guide...

The repository contains a style guide page that shows you how SFUMATO can be used. It's standard HTML so you can open it in a browser without a web server.


Install node-sass to compile SCSS

If you're compiling SCSS locally, you'll need software to do it. We recommend node-sass. It's the fastest SCSS compiler out there, and works on Microsoft Windows, Apple macOS, and Linux. It not only builds the CSS, it also watches for changes as you work and compiles on-the-fly.

Here are the steps to get the project up and running:

  1. Install node.js. Visit https://nodejs.org to get node.js. SFUMATO has been built with node.js version 6.11.1, but newer versions should work as well.
  2. Download and extract SFUMATO. Then open a terminal/command prompt and change directory to the SFUMATO root.
    cd sfumato
  3. Install node.js dependencies. Just run package manager to create the node_modules folder.
    npm install
    If you're switching platforms, like from macOS to Windows it's best to delete the node_modules folder in the root, and run `npm install` so it can build native resources.

Customize

Once you get the standard SFUMATO package to build, you can clone the SFUMATO project folder and rename it for use with your own project. You may also need to:

  1. ...change the name, version, description, author, repository URL, SCSS paths, etc. to tailor the package.json file to your project.
  2. ...run `npm install` in the new project folder, to make sure you have the node.js dependencies. If you have issues, especially when switching from one OS to another, delete the node_modules folder before running an npm install.

Configuration

You can edit the _config.scss file to set various defaults, like font sizes, screen breakpoints, etc. The file is fairly well documented so it should be easy enough to follow.

Folder structure

Below is a brief explanation of the folder structure for a SFUMATO project.

/ styleguide /                          <--- Style guide sample root

/ styleguide / images /
/ styleguide / scss /                   <--- SFUMATO lives here

/ styleguide / scss / core /            <--- Core SFUMATO SCSS; do not edit
/ styleguide / scss / custom /          <--- Your SCSS partial files go here
/ styleguide / scss / vendor /          <--- Third party SCSS libraries

/ styleguide / scss / _config.scss      <--- Edit this config file
/ styleguide / scss / _manifest.scss    <--- Core SFUMATO manifest; do not edit
/ styleguide / scss / styleguide.scss   <--- One or more of your scss files

/ styleguide / stylesheets /            <--- Generated CSS files go here

/ styleguide / styleguide.html          <--- Style guide page or your own files

----------------------------------------------------------------------------

/ package.json         <--- Node package manager configuration
                            used to set up your machine to watch
                            and compile SCSS

                            Three ways to build/watch for release
                            using Windows, macOS, or Linux
                            ------------------------------------------------
/ watch-release.bat    <--- Build, minify, and watch for changes
/ watch-release.ps1    <--- Build, minify, and watch for changes
/ watch-release.sh     <--- Build, minify, and watch for changes;

                            Three ways to build/watch for debugging
                            using Windows, macOS, or Linux
                            ------------------------------------------------
/ watch.bat            <--- Build and watch for changes
/ watch.ps1            <--- Build and watch for changes
/ watch.sh             <--- Build and watch for changes

Build scripts

If you use a tool like Carbide, which has features for dynamic SCSS compilation, you can modify your website to compile server-side. We do that on this site :) But if you want to work locally and upload compiled CSS, use the build scripts.

Included in the root of the project are both macOS bash scripts, Windows batch files, and Windows PowerShell scripts. They delete all files in the /stylesheets folder and then call node-sass to watch for changes and build the CSS on-demand.

macOS

Watch for changes and build in development mode. This creates a larger, documented CSS file and associated map so you can debug your Sass code in the browser.

cd sfumato
sh watch.sh

Watch for changes and build in release mode. This creates a small, compressed CSS file and deletes the associated map so you can deploy to production.

cd sfumato
sh watch-release.sh

Windows cmd.exe

Watch for changes and build in development mode. This creates a larger, documented CSS file and associated map so you can debug your Sass code in the browser.

cd sfumato
watch.bat

Watch for changes and build in release mode. This creates a small, compressed CSS file and deletes the associated map so you can deploy to production.

cd sfumato
watch-release.bat

Windows PowerShell

Watch for changes and build in development mode. This creates a larger, documented CSS file and associated map so you can debug your Sass code in the browser.

cd sfumato
./watch.ps1

Watch for changes and build in release mode. This creates a small, compressed CSS file and deletes the associated map so you can deploy to production.

cd sfumato
./watch-release.ps1

Host the sample site

If you want to run the sample website that comes with the project, you'll need a web server that can handle .shtml files and which supports server-side includes.

macOS Server

Apple offers a server product that can be installed on any Mac. Once installed, point the site at your SFUMATO project folder and turn on "Server Side Includes" in Advanced Settings.

Windows IIS

In Windows IIS, follow the instructions on Microsoft's site, then set up a site, set the default document to index.shtml and point the site at the SFUMATO project folder.