css-specificity-map
v1.0.1
Published
CSS specificity mapper
Downloads
22
Readme
css-specificity-map
Maps CSS specificity data for creating a specificity graph. Based on experience of using specificity graphs.
Interactive example running in the browser.
Installation
Using node
Install using npm:
npm install css-specificity-map
Include in your code:
var cssSpecificityMap = require('css-specificity-map');
In the browser
There is a browserify build available in the src/
directory. When included it will make this module available as cssSpecificityMap
on the global object.
Include in your page:
Use in your code:
cssSpecificityMap.parse(/* CSS string */);
Usage
The main method is .parse()
which takes a CSS string and returns an array of data points.
There is also a second, shortcut, method .noID()
which can be used if you aren't using ID selectors in your CSS. This is equivalent to calling .parse()
with linear_scale
: false
and no_id
: true
.
parse(stylesheet, linear_scale, no_id, important_specificty)
stylesheet
[required]
- Type:
String
This is the CSS to parse. If the CSS can't be parsed it will throw an error.
linear_scale
- Type:
Boolean
- Default:
false
By default the specificity is mapped to a logarithmic scale. Setting this to true
will use a linear scale.
no_id
- Type:
Boolean
- Default:
false
If you aren't using IDs in your CSS then this will leave a gap of an order of magnitude in the specificty graph between classes and !important
annotations. By setting this to true
the parser will produce a graph that doesn't measure IDs.
If you set this to true and the parser finds an ID it will throw an error.
important_specificity
- Type:
Integer
- Default:
1000
The pseudo specificity assigned to a rule that contains an !important
annotation. If no_id
is true then this is reduced by a factor of 10.
Result
The parser produces a sequence of data points with the following keys:
position
(x axis)specificity
(y axis)selector
(annotation)
For example, the following CSS:
"*{} body{} .main{} #content{} .hidden{display:none !important;}"
Would produce the following result:
[
{
"specificity": -1,
"selector": "*",
"position": 1
},
{
"specificity": 0,
"selector": "body",
"position": 2
},
{
"specificity": 1,
"selector": ".main",
"position": 3
},
{
"specificity": 2,
"selector": "#content",
"position": 4
},
{
"specificity": 3.004,
"selector": ".hidden { !important }",
"position": 5
}
]
Known issues
Specificity is calculated as a decimal which will lead to 11 classes having higher specificity than an ID. Whilst this is technically incorrect it is still suitable for the purposes of this visualisation.
Release history
- 2015-02-09: v1.0.1 - Fix for comment only lines.
- 2014-11-28: v1.0.0 - First stable release.