Explicit reference names

With this way, we don’t use automatic description and instead explicitely define every references we want for description. Obviously you will have to maintain correctly the name list to ensure they exists in references.

Write a Sass file that will use the helpers and settings to build a CSS manifest:

@charset "UTF-8";

@import "settings";

@import "libsass_styleguide_helpers";

.styleguide-metas-compiler {
    --support: "#{$pycssstyleguide-compiler-support}";
}

.styleguide-metas-references {
    --names: "palette version";
}

.styleguide-reference-palette {
    --structure: "flat";
    --keys: "#{get-names($palette)}";
    --values: "#{get-values($palette)}";
}

.styleguide-reference-schemes {
    --structure: "nested";
    --splitter: "object-list";
    --keys: '#{get-names-to-json($schemes-colors)}';
    --selector: '#{get-names-to-json($schemes-colors, '.bg-')}';
    --background: '#{get-props-to-json($schemes-colors, 'background')}';
    --font_color: '#{get-props-to-json($schemes-colors, 'font-color')}';
}

.styleguide-reference-borders {
    --structure: "nested";
    --keys: "#{get-names($borders)}";
    --size: "#{get-props($borders, 'size')}";
    --style: "#{get-props($borders, 'style')}";
    --color: "#{get-props($borders, 'color')}";
}

.styleguide-reference-gradients {
    --structure: "object-complex";
    --object: '["#{to-string(map-values($gradients), $glue: '", "')}"]';
}

.styleguide-reference-grid_cell_sizes {
    --structure: "flat";
    --keys: "#{floor-number-items($grid-cell-sizes)}";
    --values: "#{to-string($grid-cell-sizes, $glue: ' ')}";
}

.styleguide-reference-spaces {
    --structure: "list";
    --items: "#{to-string($spaces, $glue: ' ')}";
}

.styleguide-reference-version {
    --structure: "string";
    --value: "#{$version}";
}

Note

From styleguide-metas-references we explicitely define the allow reference names to serialize within rule --names: "...".

Build CSS manifest with your Sass compiler and you should get:

/* Helper functions from py-css-styleguide==1.2.0 */
.styleguide-metas-compiler {
  --support: "libsass";
}

.styleguide-metas-references {
  --names: "palette version";
}

.styleguide-reference-palette {
  --structure: "flat";
  --keys: "black  white  grey";
  --values: "#000000  #ffffff  #404040";
}

.styleguide-reference-schemes {
  --structure: "nested";
  --splitter: "object-list";
  --keys: '["black", " grey", " white", " grey-gradient", " with-image"]';
  --selector: '[".bg-black", " .bg-grey", " .bg-white", " .bg-grey-gradient", " .bg-with-image"]';
  --background: '["#000000", " #404040", " #ffffff", " linear-gradient(#ffffff, #ffffff 85%, #404040)", " url(\u0022foo/bar.png\u0022)"]';
  --font_color: '["#ffffff", " #ffffff", " #000000", " #000000", " #000000"]';
}

.styleguide-reference-borders {
  --structure: "nested";
  --keys: "thin  normal  bold";
  --size: "rem-calc(1px)  rem-calc(3px)  rem-calc(5px)";
  --style: "solid  solid  solid";
  --color: "white  white  black";
}

.styleguide-reference-gradients {
  --structure: "object-complex";
  --object: '["linear-gradient(#f69d3c, #3f87a6)", " radial-gradient(#f69d3c, #3f87a6 50px)"]';
}

.styleguide-reference-grid_cell_sizes {
  --structure: "flat";
  --keys: "5  25  33  75  100";
  --values: "5  25  33.3333  75  100";
}

.styleguide-reference-spaces {
  --structure: "list";
  --items: "tiny  short  normal  large  wide";
}

.styleguide-reference-version {
  --structure: "string";
  --value: "42.0";
}

/*# sourceMappingURL=sample_names.css.map */

Then load this manifest with command Manifest parser and it will return this JSON:

{
    "metas": {
        "compiler_support": "libsass",
        "references": [
            "palette",
            "version"
        ],
        "created": "2012-10-15T10:00:00"
    },
    "version": "42.0",
    "palette": {
        "black": "#000000",
        "white": "#ffffff",
        "grey": "#404040"
    }
}