@financial-times/ft-sass-to-css v0.4.9

ft-sass-to-css

A CLI tool that reports on usage of Origami Sass functions, mixins and variables and provides a set of codemods to convert to o3 web tokens.

Installation

npm i -g @financial-times/ft-sass-to-css

Usage

Report

The report function can be used to view a breakdown of the component usage for a given path, broken down into mixins, functions and variables.

ft-sass-to-css report --path="./path/to/sass/**/*"

Example output:

Origami Sass Report:
┌────────────────────────┬────────┬───────────┬───────────┬───────┐
│        (index)         │ Mixins │ Functions │ Variables │ Total │
├────────────────────────┼────────┼───────────┼───────────┼───────┤
│        o-colors        │   5    │    20     │     1     │  26   │
│ o-editorial-typography │   5    │     0     │     0     │   5   │
│        o-fonts         │   0    │     1     │     0     │   1   │
│          ---           │        │           │           │       │
│         Total          │  10    │    21     │     1     │  32   │
└────────────────────────┴────────┴───────────┴───────────┴───────┘

The --path uses a glob pattern to capture scss files. Here's a few examples of the most common patterns:

ft-sass-to-css report --path="./**/*" # all scss files within active directory

ft-sass-to-css report --path="src/*" # all scss files within the src directory ONLY

ft-sass-to-css report --path="src/components/styles.scss" # single file

CSV

Like above, but more indepth, the CSV function runs a dryRun "modifying" all sass files with a given path and outputs all successes, warnings and errors into a CSV file. You might find this useful for using it to go through and use to do the migration manually.

ft-sass-to-css csv --path="src/*" --brand="core" --fileName="migration-report" # Checks scss against core branding and outputs a report file named "migration-report.csv"

ft-sass-to-css csv --path="src/*" --brand="core" --fileName="migration-report" --typeFilter="warning" # same as above but filter display only certain types warning, error or successs

Dryrun

The dryrun command will attempt to perform the available codemods against a given path and return the modified file's content to the console. It will not modify any files. To learn about which components are currently supported view the Support section below.

ft-sass-to-css dryrun --path="src/*" --component="component-name" --brand="brand-name"

You may get a lot of content back from this command, as it'll return the entire Sass file's contents. It might be easier to pipe the output from the command to a text file to validate the changes.

ft-sass-to-css dryrun --path="src/*" --component="component-name" --brand="brand-name" > output.txt

!IMPORTANT Supported Brands: core, internal, professional, whitelabel.

Modify

We recommend running the dryrun command before this step.

The modify command will perform the available codemods and overwrite your Sass files with the updated values. To learn about which components are currently supported view the Support section below.

ft-sass-to-css modify --path="./**/*" --component="component-name" --brand="brand-name"

!IMPORTANT Supported Brands: core, internal, professional, whitelabel.

Once the process is complete you'll see an output in the console breaking down how many files were modified.

Help

You can learn more about the usage commands by using the following help command

ft-sass-to-css help

Support

Please refer to the list below to see which components and their respective functions, mixins and variables are currently supported by the dryrun and modify commands. We're continually working on adding more components.

o-colors

Functions:

• oColorsByName()
• oColorsByUseCase()
• oColorsMix()
  • There is only some (~20%) support for oColorsMix. You may be mixing a color that doesn't exist as a new Origami variable token. Please refer to the o-colors Migration Guide for more info.

o-spacing

Funtions:

• oSpacingByName()
• oSpacingByIncrement()*

o-typography

Mixins:

• oTypographySans()
• oTypographySerif()
• oTypographyDisplay()

Functions:

• oTypographyMaxLineWidth()*

* These codemods replace the function with its compiled output, as they have no direct equivalent in o3-foundation.

Local Development

Installation and configuration

git clone git@github.com:Financial-Times/ft-sass-to-css.git
cd ft-sass-to-css
npm install
npm link

Execution

You can run the report, dryrun and modify CLI commands against the files within the demo directory with the following shortcuts:

npm run report-demo
npm run dryrun-demo
npm run modify-demo

Testing

The following command runs Jest and tests core functionality:

npm run test

These tests are executed as part of the CircleCI process; it will not deploy with failing tests.

Coding Standards

We drive secure maintainable code through the use of ESlint and Snyk via regular execution of the following commands:

npm run lint             # View linting errors
npm run lint:fix         # Attempt to fix linting errors automatically

Deploying the Application

You can release a new version to NPM by creating a Github release following semantic version numbering, preceeded by a v, e.g v0.0.1