Usage¶

You need a CSS manifest to describe your styleguide references then you will parse the manifest with a Python script to parse and serialize your references.

Note

This document does not explain the reference rules syntax in detail, you will find them in Manifest.

Create a manifest¶

You may write directly a CSS manifest but this is better to build it from a Sass source that will be able to use your project Sass settings, so manifest can be automatically updated on each build.

Usage samples in this documentation will only demonstrate this process using Sass sources.

So in the same directory than your Sass manifest you will copy the Sass mixin library file to _styleguide_helpers.scss. It contains some Sass helpers to ease writing manifest from Sass maps.

Hint

You can use the command Manifest parser to check your CSS manifest.

Demonstration settings¶

We will use some Sass settings for demonstration which Sass manifest will use to create manifest references.

You will create a file _settings.scss in your Sass directory with this content:

$pycssstyleguide-compiler-support: "libsass";

$black: #000000;
$white: #ffffff;
$grey: #404040;

// Palette
// ---------
$palette: (
    "black": $black,
    "white": $white,
    "grey": $grey,
);

// Schemes colors
// ---------
$schemes-colors: (
    "black": (
        "background": $black,
        "font-color": $white,
    ),
    "grey": (
        "background": $grey,
        "font-color": $white,
    ),
    "white": (
        "background": $white,
        "font-color": $black,
    ),
    "grey-gradient": (
        "background": linear-gradient($white, $white 85%, $grey),
        "font-color": $black,
    ),
    "with-image": (
        "background": url("foo/bar.png"),
        "font-color": $black,
    ),
);

$borders: (
    "thin": (
        "size": rem-calc(1px),
        "style": solid,
        "color": white,
    ),
    "normal": (
        "size": rem-calc(3px),
        "style": solid,
        "color": white,
    ),
    "bold": (
        "size": rem-calc(5px),
        "style": solid,
        "color": black,
    ),
);

// Some background gradients
// ---------
$gradients: (
    "yellow-to-blue-linear": linear-gradient(#f69d3c, #3f87a6),
    "yellow-to-blue-radial": radial-gradient(#f69d3c, #3f87a6 50px),
);

// Grid cell sizes
// ---------
$grid-cell-sizes: 5 25 33.3333 75 100;
$grid-cell-total: 5;

// Space names
// ---------
$spaces: tiny short normal large wide;

// Library version
// ---------
$version: "42.0";

This is basic Sass settings for demonstration purpose and obviously for a real project you will use your own (like from Bootstrap, Foundation or a totally custom one) depending your project.

Manifest loader¶

Once you have a CSS manifest you will need to load it as a Manifest model through PyCssStyleguide library. There is a commandline script Manifest parser to do it but for integration in a project you may prefer to use your own script.

The following Python snippet is a sample of a custom script you can start from:

from pathlib import Path

from py_css_styleguide.model import Manifest

manifest = Manifest()

manifest.load(Path("styleguide_manifest.css").read_text())

print(manifest.to_json())

When executed this basic script will output JSON datas from your manifest.

Note

This sample use Manifest.to_json() for simplicity but you could also use manifest object attributes to reach references rules.

Samples¶

For the following samples, you will use the _settings.scss, the Sass mixin library and the manifest parser commandline script from Manifest parser.