Or : How could I see what my colored variables look like


EDIT Friday 19 of June, 6:04pm

Just realized that SassDoc got an annotation trick that generates colors So you can see this post as a "SassDoc hack" to add custom images.


Hi, and welcome to my small codepen blog. Today I wanna cover a small but cool subject, but first let me told you about SassDoc, according to themselves :

SassDoc is to Sass what JSDoc is to JavaScript: a documentation system to build pretty and powerful docs in the blink of an eye

Well, in detail, SassDoc will read your sass files, find the needed "annotations" which is an other name for "comments". Annotations looks like this /// and can be followed by a collection of parameters, such as :

@access, @alias, @author, @content, @deprecated, @example, @group, @ignore, @link, @name, @output, @parameter, @property, @require, @return, @see, @since, @throw, @todo, @type.

I'm not here to write an other doc for sassdoc, but as a final example, here is one of my most complete annotation :

  /// SK-ICON-COLOR 
/// Create a complete icons mapping.
/// The icons used SVG images as background, you can change the color of the svg icon, without changing
/// the fill attribute.
/// @author Lucas Bonomi <lukyvj>
/// @todo Find a good fallback for IE
/// If the $icon-list returns a true parameter as value
/// @param  {Keyword} $type      - Icon type (ex: retweet, menu, cancel) 
/// @param  {Boolean} $haveColor - Could be true or false, depending if the icon have a color ( defined in $icon-list map )
/// @param  {String} $color - The color itself
/// @link   https://gist.github.com/LukyVj/8c6cfeee7b2cb59f15b3

And this will result into :


Now, the blog post point

The point of this blogpost is about one thing, one and only thing : Be able to see your colors variables in sassdoc So, for example, I want my $red variable, to output me a red square.

At this point, there is few options to do it, you can use a server side script, sent it a request with proper url parameters, like your-awesome-server.com/coloredImages?color=red&w=100&h=100, or you could have used an image directly, but wait, what a waste of time !?

In both case, the solution isn't optimal, the goal is to do it on an effortless way, and limiting any server requests that could occurs.

A better approach

To me, a better approach would have been to use data URI scheme, generating an image, with SVG, like this : data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><rect fill="#4BC57A" x="0" y="0" width="100%" height="100%"/></svg>, wich would result in :

In this pen, you can see that the data URI works on both src image attribute, and url of css background property, pretty rad huh ?

Final use

So now, we have everything in mind, to generate the best sassdoc ever !

In my case, I needed to visualize my color variables, so here is an extract of my _variables.scss file :

      /// Blue
    /// <img src='data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><rect fill="#415FD9" x="0" y="0"         width="100%" height="100%"/></svg>'>
    $c-blue: #415FD9;

    /// Yellow 
    /// <img src='data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><rect fill="#F3D567" x="0" y="0"         width="100%" height="100%"/></svg>'>
    $c-yellow: #F3D567;

    /// Green 
    /// <img src='data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><rect fill="#4BC57A" x="0" y="0"         width="100%" height="100%"/></svg>'>
    $c-green: #4BC57A;

    /// Orange 
    /// <img src='data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><rect fill="#FB9071" x="0" y="0"         width="100%" height="100%"/></svg>'>
    $c-orange: #FB9071;

    /// Red 
    /// <img src='data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><rect fill="#FB4537" x="0" y="0"         width="100%" height="100%"/></svg>'>
    $c-red: #FB4537;

You can see that I added a notation with an image tag inside, and the src attribute contains the DATA URI. And it works like a charm !

One thing is missing tho, the possibility to use a variable INSIDE a sassdoc notation, I've asked sassdoc if it was possible, and in a dry response, they said that it was out of the context, that using a variable in a comment had "nothing to do with sass"... But wait, according to the OFFICIAL SASS documentation :

Since multiline comments become part of the resulting CSS, interpolation within them is resolved.

So, sassdoc only uses inline comment, So, using a variable in it would be impossible, that was what the sassdoc team meant.

But they are wrong when they say that it had "nothing to do with sass", since sass explains you how to use variables in multiline comments.

So this is the next goal for me, tweaking the sassdoc code, to be able to use those variables, or at least, to generate an image, based on the color variable, automatically.

Thank you for reading ! And you better give a try to sassdoc !


1,992 2 7