Pronounced « Alix ». Because it's fun.
This CSS file intends to warn developers about possible risks and mistakes that exist in HTML code. It can also be used to roughly evaluate a site's quality by simply including it as an external stylesheet.
This file is not a replacement to a complete tool such as OpQuast Reporting. It only intends to show possible weaknesses. You should obviously do some manual check by hand to know whether the code should or should not be fixed.
Many references helped me in the making of this stylesheet:
- https://github.com/redroot/holmes/blob/master/holmes.css
- https://github.com/karlgroves/diagnostic.css
- http://www.w3.org/TR/html5/obsolete.html#obsolete
- https://github.com/nternetinspired/debug-css
- https://yahoo.github.io/debugCSS/
- http://meyerweb.com/eric/tools/css/diagnostics/
- http://accessites.org/site/2006/07/big-red-angry-text/
- http://www.accessiweb.org/index.php/accessiweb-html5aria-liste-deployee.html
- https://github.com/Heydon/REVENGE.CSS
- https://code.google.com/p/qa-style-sheet/
- Mémento « Sites web — Les bonnes pratiques »
- « Intégration Web, les bonnes pratiques », pages 335/336
Although let's keep in mind the idea has nothing new (there is an article from Marco Battilana from 2006, and a proposal by Eric Meyer himself from 2007). I only tried to push things further. I suggest you read my article (in French) to learn more about the project.
In concrete terms, errors, warnings and advices are outlined by a 4px colored border:
- red for errors;
- yellow for warnings;
- blue for obsolete stuff;
- green for advices.
Those colors are obviously customisable through the configuration file. When hovering marked elements, a little banner should appear on top of your browser displaying what's going on.
Given the very long list of selectors to test, they are splitted across several files. Errors are in their own file, advices in their own, and so on.
Please notice that you can build a single level file (obsolete stuff only, for example), and adjust it to your very own issues. You may want to fix errors, or to learn from few advices.
Each test has its own message, trying to explain and guide you as much as possible. All messages are gathered in a Sass map, in both English and French. It should be quite easy for you to update the messages for internal use if you don't like them.
A full documentation with all test cases is now available on the dedicated site. This is made using Hologram and sseeeedd.
From now on, CSS counters are incremented on each error/advice/warning and results are displayed with html::after
. Since it is added through CSS, it is basically fake-content which is good since it is no more than visual indication for the user to see what's going on.
Note: this counter takes into account possible issues with elements within <head>
tag. Related messages are not displayed, but they do increment the counter correctly, as any other issues.
You can easily use the latest version of this stylesheet by adding this bookmarklet to your bookmarks:
javascript:(function(){a11ycss=document.createElement('LINK');a11ycss.href='https://rawgit.com/ffoodd/a11y.css/master/css/a11y-en.css';a11ycss.rel='stylesheet';a11ycss.media='all';document.body.appendChild(a11ycss);})();
New You can also generate your own bookmarklet (choosing language and minimum level) on the dedicated page then directly drag it to your bookmarks. Isn't it handy?
a11y.css currently exists in both English and French: you'll find both files in the css folder. If you want to contribute and add a new language, it is very easy to do:
- Add the name of the language in this list;
- Copy
_a11y-en.scss
, rename it_a11y-<your-language>.scss
and change the value passed to theset-locale
mixin; ". Update this map with your translations. '. Update this map to translate theme names. (. Runsass --update sass:css --style=compressed
to generate the new CSS file.
Done!
- Self-closing tags (a.k.a. void elements) do not allow generated content through pseudo-elements. Thus, errors or whatever will correctly be displayed, but not the message on hover. That being said, it should be available for consultation with any DOM reader (DevTools, Firebug or whatever). Here are affected self-closing tags:
<area />
<base />
<br />
<col />
<command />
<embed />
<hr />
<img />
<input />
<keygen />
<link />
<meta />
<param />
<source />
<track />
<wbr />
<textarea>
,<select>
,<svg>
,<audio>
,<video>
,<track>
and<iframe>
aren't void tags but can't contain pseudo-elements as they are replaced elements. Take a look at What The Heck Is A Replaced Element? by @dudleystorey.
Issue #7 opened by @7studio suggested a decent work-around to display messages for those tags, as long as they are followed by a non-self-closing element. Still better than nothing.
- Messages are generated through a fixed pseudo-element. However there could be a containing block issue if the parent is a transformed element (
transform
):
- Along the same lines, tests on elements that are contained within
<head>
cannot be displayed (since<head>
is a hidden element). I need to find a way to do this.
*Issue #66 opened by @7studio (again) helped with this point, thanks to an idea from Mathias Bynens.
- To avoid cases when outline could be hidden, the property outline-offset is being used in order to display it inside the element (rather than outside). Thanks to @7studio in #4.
You are now able to customize the file output by targeting a severity treshold. You just have to personalize the single parameter in set-minimum-level
mixin. Levels are cumulative, and reflect theme's names:
error
: only errors;warning
: warnings and errors;obsolete
: obsolete stuff, warnings and errors;advice
: every messages.
We are assuming that looking for advices means that you care about obsoletes, warnings and errors.
Credits to @HugoGiraudel in #69.
It is possible to disable some specific tests if you build your own a11y.css
file. Use the following mixins:
disable-errors($keys...)
disable-advices($keys...)
disable-warnings($keys...)
disable-obsoletes($keys...)
For instance, if you want to disable the errors about messing with tabindex and missing href, you can do:
@include disable-errors("tab-order, no-href");
Credits to @HugoGiraudel in #69.
With global SassDoc install:
$ npm install sassdoc -g
$ sassdoc sass/ docs/ --verbose --config .sassdocrc
With local SassDoc install:
$ npm install
$ node_modules/sassdoc/bin/sassdoc sass/ docs/ --verbose --config .sassdocrc
They helped a lot:
And they took time to open a few issues:
Thank you all!
PS: CSS best practices do not belong to this CSS file. Some selectors are ugly as hell, but we need them in order to select what we need to select.
This project is distributed under MIT license and CC BY 3.0 FR. Copyright (c) 2013 Gaël Poupard