2.2.1

Close #183 and close #165
ffoodd · Dec 16, 2015 · 6cb161f · 6cb161f
1 parent 5b292f2
commit 6cb161f
Show file tree

Hide file tree

Showing 14 changed files with 210 additions and 44 deletions.
diff --git a/README-fr.md b/README-fr.md
@@ -28,6 +28,8 @@ De nombreuses références m’ont inspiré et aidé pour élaborer cette feuill
 
 Je tiens à signaler que l’idée n’est ni neuve, ni de moi (la proposition d’Eric Meyer date de 2007, et l’article de Marco Battilana de Juillet 2006 !). J’ai simplement pensé qu’il était possible d’aller beaucoup plus loin, alors je l’ai fait. Je vous invite à lire [mon article](http://www.ffoodd.fr/a11y-cssun-credo/) pour en apprendre plus sur la genèse de ce projet.
 
+## Architecture technique
+
 ### Code couleur
 
 Concrètement, les éléments en erreur, en alerte, obsolètes ou pouvant être améliorés seront cernés d’un contour de quatre pixels colorés:
@@ -52,7 +54,7 @@ Quand le sélecteur de négation ne permet pas un ciblage suffisamment précis,
 
 Les sélecteurs génériques comme `[class]` peuvent également cibler des éléments remplacés et des balises auto-fermantes (voir la section « Cas particuliers et problèmes connus »). Certains sélecteurs sont étendus grâce au mixin `@void-tags`, qui reprend le sélecteur en ciblant plus particulièrement les éléments incongrus, et répète le message en y ajoutant l’argument `$self-closing: true`.
 
-### Sélecteur en quarantaine
+#### Sélecteur en quarantaine
 
 Quand un sélecteur n’est pas supporté par certains navigateurs, il est possible de le mettre en quarantaine afin qu’il n’invalide pas les autres sélecteurs.
 
@@ -64,17 +66,15 @@ Chaque test dispose de son propre message, afin d’informer et guider au maximu
 
 *Nouveauté* : il est désormais possible d’utiliser le fonction CSS `attr()` dans les messages afin de remonter la valeur réelle d’un attribut.
 
-## Documentation et cas de test
-
-Une documentation complète ainsi que des cas de test sont désormais disponibles [sur le site dédié](http://ffoodd.github.io/a11y.css/). Le tout est généré en utilisant [Hologram](https://github.com/trulia/hologram) et [sseeeedd](https://github.com/ffoodd/sseeeedd).
-
-## Compteurs
+### Compteurs
 
 Désormais des compteurs `CSS` ont incrémentés par chaque erreur, et les résultats sont affichés dans le `body::after`. C’est donc du faux-contenu, son intérêt est purement visuel afin de simplement indiquer au développeur l’étendue du chantier qui l’attend :) .
 
 *À noter :* ce nouveau compteur permet d’obtenir des indications sur l’éventuelle présence de messages incriminant les balises du `<head>`. Ils n’ont toujours pas d’affichage mais ils sont désormais mentionnés dans ce compteur qu’ils incrémentent bien gentimment.
 
-## Bookmarklet
+## Portabilité, langues et trous dans la raquette
+
+### Bookmarklet
 
 Vous pouvez utiliser facilement la dernière version à jour en ajoutant ce *bookmarklet* à vos favoris :
 ```
@@ -84,7 +84,7 @@ Vous pouvez également l’ajouter en allant sur [la page dédiée](http://ffood
 
 Pratique, n’est-ce pas ?
 
-## À propos des langues
+### À propos des langues
 
 a11y.css existe désormais en français et en anglais : vous trouverez tous les fichiers dans le répertoire [css](https://github.com/ffoodd/a11y.css/tree/master/css). ISi vous souhaitez contribuer en ajoutant une nouvelle langue, c’est très simple :
 
@@ -96,7 +96,7 @@ a11y.css existe désormais en français et en anglais : vous trouverez tous les
 
 Et voilà !
 
-## Cas particuliers et problèmes connus
+### Cas particuliers et problèmes connus
 
 1. Les balises « auto-fermantes » n’autorisent pas la génération de contenu. Ainsi les erreurs ou alertes seront marquées, mais aucun message n’apparaitra au survol. Il sera en revanche consultable dans la plupart des inspecteurs de `DOM` : la limite est la création du pseudo-élément pour l’affichage (cf [la spécification](http://www.w3.org/TR/CSS2/generate.html#before-after-content). Voici la liste exhaustive des balises `HTML5` auto-fermantes :
 
@@ -130,7 +130,9 @@ Et voilà !
 
 4. Pour éviter les cas dans lesquels le contour pourrait être masqué, la propriété [outline-offset](https://developer.mozilla.org/en-US/docs/Web/CSS/outline-offset "Définition sur le MDN") est utilisée afin d’afficher le contour à l’intérieur de l’élément marqué. Amélioration suggérée par @7studio dans l’issue #4.
 
-## Compiler une version nivelée
+## Personnaliser son a11y.css
+
+### Compiler une version nivelée
 
 Vous pouvez désormais adapter le fichier de sortie au niveau d’erreur que vous souhaitez. Vous n’avez qu’à modifier le seul paramètre du mixin `set-minimum-level`. Les niveaux sont cumulatifs, et sont fidèles au nomage des thèmes :
 * `error`: seulement les erreurs;
@@ -142,7 +144,7 @@ Nous partons du principe que si vous êtes intéressés par les conseils, vous l
 
 Merci à [@HugoGiraudel](https://twitter.com/HugoGiraudel) dans l’issue [#69](https://github.com/ffoodd/a11y.css/issues/69).
 
-## Désactiver des tests
+### Désactiver des tests
 
 Il est possible de désactiver des tests au cas par cas si vous compilez votre propre version de `a11y.css`. Utilisez les mixins suivants :
 
@@ -159,7 +161,9 @@ Par exemple, si vous voulez désactiver les erreurs à propos des mauvais `tabin
 
 Merci à [@HugoGiraudel](https://twitter.com/HugoGiraudel) dans l’issue [#69](https://github.com/ffoodd/a11y.css/issues/113).
 
-## Construire la SassDoc
+## Documentation
+
+### Construire la SassDoc
 
 Avec une installation globale SassDoc :
 
@@ -175,6 +179,31 @@ $ npm install
 $ node_modules/sassdoc/bin/sassdoc sass/ --dest docs/ --verbose --config .sassdocrc
 ```
 
+### Générer la documentation Hologram
+
+C’est très facile. En ligne de commande, placez-vous dans le répertoire `a11y.css` et lancez `hologram`.
+Et voilà !
+
+Pour en savoir plus sur Hologram, jetez un œil à [leur répertoire GitHub](https://github.com/trulia/hologram)).
+
+## Automatisation
+
+Parce qu’il faut bien se mettre à la page un jour, un fichier de configuration [Gulp](http://gulpjs.com/) a été ajouté.
+Quelques tâches bien pratique ont donc été prévues.
+
+Si vous lancez `gulp` — qui par défaut joue `gulp build` — vous allez compiler les fichiers Sass et
+(en incluant les *sourcemaps*) optimiser les CSS générés.
+
+Vous pouvez aussi lancer `gulp docs`, qui va générer les documentations *via* SassDoc et Hologram.
+
+Chacune de ses tâches est disponible isolément :
+* `gulp sass`
+* `gulp minify`
+* `gulp sassdoc`
+* `gulp hologram`
+
+Et vous pouvez lancer une surveillance sur la compilation Sass et la minification des CSS avec `gulp watch`.
+
 ## Crédits et remerciements
 
 ### Contributeurs

diff --git a/README.md b/README.md
@@ -28,6 +28,8 @@ Many references helped me in the making of this stylesheet:
 
 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](http://www.ffoodd.fr/a11y-cssun-credo/) (in French) to learn more about the project.
 
+## Technical structure
+
 ### About colors
 
 In concrete terms, errors, warnings and advices are outlined by a 4px colored border:
@@ -53,7 +55,7 @@ When the `:not()` selector cannot be precise enough, you may add a second select
 
 Generic selector like `[class]` may targetself-closing tags and replaced elements (see "Edge cases and known issues" section). Some selectors are now extended with `@void-tags` mixin, that improve selector to target those weird tags, and repeat the associated message (adding `$self-closing: true`).
 
-### Quarantine
+#### Quarantine
 
 When a selector is not cross-browser, you may send it to quarantine as it won't invalidate other selectors.
 
@@ -65,17 +67,15 @@ Each test has its own message, trying to explain and guide you as much as possib
 
 *New* : You are now able to use the `attr()` CSS function in messages to show the real value of an attribute.
 
-## Test cases and documentation
-
-A full documentation with all test cases is now available on [the dedicated site](http://ffoodd.github.io/a11y.css/). This is made using [Hologram](https://github.com/trulia/hologram) and [sseeeedd](https://github.com/ffoodd/sseeeedd).
-
-## Counters
+### Counters
 
 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.*
 
-## Bookmarklet
+## Portability, languages and known limitations
+
+### Bookmarklet
 
 You can easily use the latest version of this stylesheet by adding this *bookmarklet* to your bookmarks:
 
@@ -86,7 +86,7 @@ javascript:(function(){a11ycss=document.createElement('LINK');a11ycss.href='http
 *New*
 You can also generate your own bookmarklet (choosing language and minimum level) on [the dedicated page](http://ffoodd.github.io/a11y.css/) then directly drag it to your bookmarks. Isn't it handy?
 
-## About languages
+### About languages
 
 a11y.css currently exists in both English and French: you'll find both files in the [css](https://github.com/ffoodd/a11y.css/tree/master/css) folder. If you want to contribute and add a new language, it is very easy to do:
 
@@ -98,7 +98,7 @@ a11y.css currently exists in both English and French: you'll find both files in
 
 Done!
 
-## Edge cases and known issues
+### Edge cases and known issues
 
 1. 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:
@@ -133,7 +133,9 @@ Here are affected self-closing tags:
 
 4. To avoid cases when outline could be hidden, the property [outline-offset](https://developer.mozilla.org/en-US/docs/Web/CSS/outline-offset) is being used in order to display it inside the element (rather than outside). Thanks to [@7studio](https://twitter.com/7studio) in [#4](https://github.com/ffoodd/a11y.css/issues/4).
 
-## Building leveled file
+## Build a custom a11y.css
+
+### Building leveled file
 
 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;
@@ -145,7 +147,7 @@ We are assuming that looking for advices means that you care about obsoletes, wa
 
 Credits to [@HugoGiraudel](https://twitter.com/HugoGiraudel) in [#69](https://github.com/ffoodd/a11y.css/issues/69).
 
-## Disabling tests
+### Disabling tests
 
 It is possible to disable some specific tests if you build your own `a11y.css` file. Use the following mixins:
 
@@ -162,7 +164,9 @@ For instance, if you want to disable the errors about messing with tabindex and
 
 Credits to [@HugoGiraudel](https://twitter.com/HugoGiraudel) in [#69](https://github.com/ffoodd/a11y.css/issues/113).
 
-## Building docs
+## Documentation
+
+### Building SassDoc
 
 With global SassDoc install:
 
@@ -178,6 +182,31 @@ $ npm install
 $ node_modules/sassdoc/bin/sassdoc sass/ --dest docs/ --verbose --config .sassdocrc
 ```
 
+### Build Hologram
+
+This one is easy. Usign command line, just cd` to `a11y.css` then run `hologram`.
+Et voilà !
+
+To learn more about Hologram, take a look at [their GitHub repository](https://github.com/trulia/hologram)).
+
+## Automatisation
+
+We all have to stay up-to-date, so you'll find a [Gulp](http://gulpjs.com/) configuration file.
+Some useful tasks are ready-to-run.
+
+If you run `gulp` — which runs `gulp build` behind the scene — you'll compile Sass files (including *sourcemaps*)
+and optimize the CSS output.
+
+You can also launch `gulp docs`, which will generate the whole documentation *via* both SassDoc and Hologram.
+
+Each task can be run individually:
+* `gulp sass`
+* `gulp minify`
+* `gulp sassdoc`
+* `gulp hologram`
+
+And of course you can watch for changes to automatically compile Sass and optimize the CSS output using `gulp watch`.
+
 ## Credits and Acknowledgements
 
 ### Contributors

diff --git a/bower.json b/bower.json
@@ -1,6 +1,6 @@
 {
   "name": "a11y.css",
-  "version": "2.2",
+  "version": "2.2.1",
   "homepage": "https://github.com/ffoodd/a11y.css",
   "description": "This file aims to warn front-end devs about mistakes and potential accessibility failures - but it also helps to rate client-side code and to spot its weaknesses.",
   "main": "a11y.css",
@@ -27,6 +27,9 @@
     "selectors",
     "messages",
     "config.rb",
-    "bower_components"
+    "bower_components",
+    "node_modules",
+    "tests",
+    "docs"
   ]
 }
diff --git a/css/a11y-en.css b/css/a11y-en.css
diff --git a/css/a11y-en_error.css b/css/a11y-en_error.css
diff --git a/css/a11y-en_obsolete.css b/css/a11y-en_obsolete.css
diff --git a/css/a11y-en_warning.css b/css/a11y-en_warning.css
diff --git a/css/a11y-fr.css b/css/a11y-fr.css
diff --git a/css/a11y-fr_error.css b/css/a11y-fr_error.css
diff --git a/css/a11y-fr_obsolete.css b/css/a11y-fr_obsolete.css
diff --git a/css/a11y-fr_warning.css b/css/a11y-fr_warning.css
diff --git a/gulpfile.js b/gulpfile.js
@@ -0,0 +1,73 @@
+'use strict';
+
+// Requires
+var gulp       = require('gulp'),
+    sassdoc    = require('sassdoc'),
+    sass       = require('gulp-ruby-sass'),
+    sourcemaps = require('gulp-sourcemaps'),
+    csso       = require('gulp-csso'),
+    hologram   = require('gulp-hologram');
+
+// Paths
+var source      = './sass',
+    destination = './css';
+
+
+// Sass w sourcemaps
+gulp.task('sass', function () {
+  return sass(source + '/**/*.scss', {sourcemap: true, style: 'compressed'})
+    .on('error', sass.logError)
+    .pipe(sourcemaps.write('maps', {
+      includeContent: false,
+      sourceRoot: source
+    }))
+    .pipe(gulp.dest(destination));
+});
+
+// Minify CSS
+gulp.task('minify', function () {
+  return gulp.src(destination + '/*.css')
+    .pipe(csso());
+});
+
+// Generate SassDoc
+gulp.task('sassdoc', function () {
+  var options = {
+    dest: 'docs',
+    theme: 'default',
+    display: {
+      access: ['public'],
+      alias: false,
+      watermark: true,
+    },
+    groups: {
+      "undefined": "Configuration",
+      "languages": "Translation"
+    },
+    basePath: 'https://github.com/ffoodd/a11y.css/tree/master/sass',
+  };
+
+  return gulp.src(source + '/**/*.scss')
+    .pipe(sassdoc(options));
+});
+
+// Generate Hologram
+gulp.task('hologram', function() {
+  gulp.src('./hologram_config.yml')
+    .pipe(hologram());
+});
+
+
+// Build a11y.css
+gulp.task('build', ['sass', 'minify']);
+
+// Generate doc
+gulp.task('docs', ['sassdoc', 'hologram']);
+
+// Default: build
+gulp.task('default', ['build']);
+
+// Watch: build
+gulp.task('watch', function () {
+  gulp.watch(source + '/**/*.scss', ['build']);
+});
diff --git a/package.json b/package.json
@@ -1,12 +1,28 @@
 {
-    "title": "a11y.css",
-    "name": "a11y.css",
-    "description": "This file aims to warn front-end devs about mistakes and potential accessibility failures - but it also helps to rate client-side code and to spot its weaknesses.",
-    "version": "2.2",
-    "license": "MIT",
-    "homepage": "http://ffoodd.github.io/a11y.css",
-    "repository": "https://github.com/ffoodd/a11y.css",
-    "devDependencies": {
-        "sassdoc": "^2.1.16"
-    }
+  "title": "a11y.css",
+  "name": "a11y.css",
+  "description": "This file aims to warn front-end devs about mistakes and potential accessibility failures - but it also helps to rate client-side code and to spot its weaknesses.",
+  "version": "2.2.1",
+  "author": {
+    "name": "Gaël Poupard",
+    "url": "http://www.ffoodd.fr",
+    "email": "gael@ffoodd.fr"
+  },
+  "license": "MIT",
+  "homepage": "http://ffoodd.github.io/a11y.css",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ffoodd/a11y.css"
+  },
+  "bugs": {
+    "url": "https://github.com/ffoodd/a11y.css/issues"
+  },
+  "devDependencies": {
+    "sassdoc": "^2.1.18",
+    "gulp": "latest",
+    "gulp-ruby-sass": "latest",
+    "gulp-sourcemaps": "latest",
+    "gulp-csso": "latest",
+    "gulp-hologram": "latest"
+  }
 }
diff --git a/test-assets/static/ffoodd.png b/test-assets/static/ffoodd.png