Génération de rapports de synthèse pour le suivi et l’amélioration de l’accessibilité web.

FRAGO : French governmental Reports for Accessibility compliance with goHugo

Présentation

Le thème Frago a pour objectif d’aider à la génération de synthèses pour la documentation du suivi d’amélioration des démarches en ligne du gouvernement français.

Le thème a été conçu pour être multi-projets. Pourquoi ? Parce que dans le cadre d’un défi de mise en conformité, l’équipe peut être amenée à travailler sur des sujets connexes, des interfaces intermédiaires/liées sur lesquelles il est nécessaire de fournir un audit en particulier… de plus le projet peut aider à suivre aussi plusieurs défis en parallèle.

Attention, goHugo est très sensible à l’architecture des contenus. Si les contenus sont absents ou présentent des erreurs le site peut planter. Si l’architecture du thème change, de même, il n’est plus possible d’utiliser les dernières versions du thème (sans modifier l’architecture de contenu).

Démarrage (Configuration simplifiée)

Architecture de contenu

.
├── config.toml
└── content
    ├── _index.md // Page d’accueil
    └── audits
         ├── projet1
         │     ├── _index.md // Pour lister les pages sur l’accueil et avoir la page intermédiaire qui liste tous les rapports :: ajouter une entête
         │     ├── accessibility.md
         │     └── accessibility
         │          ├── 2020-10-15.csv
         │          └── 2020-11-15.csv
         └── projet2
                ├── _index.md // Pour lister les pages sur l’accueil et avoir la page intermédiaire qui liste tous les rapports :: ajouter une entête
                ├── accessibility.md
                └── accessibility
                    ├── 2020-10-15.csv
                    └── 2020-11-15.csv

Configuration

Ajouter le fichier : `config.toml`

[module]
  [[module.imports]]
    path = "github.com/disic/frago"

title = "Mon administration"
theme = "frago"

[params]
  organisation = "Le nom complet de mon administration"

Appeler le thème Hugo (avec le système de module `Go`)

Créer le fichier `go.mod` (commande dans le terminal)

hugo mod init github.com/disic/frago

Modifier le contenu du fichier go.mod (Ajouter https://) :
module github.com/DISIC/frago => module https://github.com/DISIC/frago

Créer le fichier `go.sum` (commande dans le terminal)

hugo mod get -u https://github.com/disic/frago

Appeler le thème Hugo (avec un submodule)

git submodule add https://github.com/disic/frago.git/ themes/frago && git submodule update --init --recursive

Génération du site (mise en ligne)

Ligne de commande pour construire les pages du site.

hugo --buildFuture --gc --minify

--buildFuture permet de publier des éléments avec une date future dans la partie phase (optionnel).
--gc permet de remettre à jour le répertoire de génération du code (au cas ou du code d’une précédente génération serait encore présent).
--minify permet de compresser le code HTML en ligne.

Héberger avec Github

Consulter la page Host on GitHub pour plus d‘informations.

Github utilise son système interne GitHub Action. Un exemple de fichier de configuration est disponible : gh-pages.yml.

Héberger avec Gitlab

Consulter la page Host on Gitlab pour plus d‘informations

Github utilise son système interne Gitlab CI. Un exemple de fichier de configuration est disponible : .gitlab-ci.yml.

Audits

Accessibilité

Le thème interprète un fichier d’audit csv avec une structure fixe. Les intitulés de colonnes doivent respecter un nommage précis (Thématiques, Critères, Tests,… puis le titre de chaque page).

Le titre d’une page peut être suivi de l’URL de la page ; titre et URL séparés par le caractère |.

Exemple d’un tableau avec uniquement la prise en compte des critères

Thématiques	Critères	Accueil।https://monsite.fr
1	1	nc
1	2	c
1	3	na
1	4	nt
…	…	…
13	12	nc

Liste des fichiers exemples à télécharger

Dans chacun des ces fichiers figurent des numéros qui correspondent aux notions d’audit rapide (25 critères), intermédiaire (50 critères), complémentaire (81 critères).
Exemple, Pour un audit rapide, ne traiter que les cases avec le numéro 25.

API

Pour exposer l’API, le fichier config.toml doit être compléter, voici un exemple de fichier pour avoir un fichier index.json ainsi que des déclarations pour chaque page d’audit (un fichier de contenu brut, et une page HTML liée à chaque page accessibility.md).

[outputs]
 home    = ["HTML","JSON"]
 page    = ["HTML","JSON","declaration","declarationpage"]

Configuration détaillée

Architecture de contenu

Les différents types de contenus servent à la publication d’audits, l’analyse de résultats ou la présentation de la démarche UX. L’objectif est de synthétiser de l’information technique pour des personnes éloignées du développement de sites web.

Arborescence

Architecture simplifiée

.
├── config.toml
└── content
    ├── _index.md // page d’accueil du site :: ⚠️ Ajouter `type: projects` dans l'entête du fichier en cas de mono projet => va afficher directement la page de synthèse de tous les audits
    ├── audits // Les pages pour afficher les audits (accessibilité, qualité, performance…) pour chaque projet
    │     ├── projet1
    │     │      ├── _index.md // ⚠️  pour avoir lister les pages sur l’accueil et avoir la page intermédiaire qui liste tous les rapports
    │     │      ├── accessibility.md
    │     │      ├── quality.md
    │     │      ├── performance.md
    │     │      ├── accessibility
    │     │      │   ├── 2020-10-15.csv
    │     │      │   └── 2020-11-15.csv
    │     │      ├── lighthouse
    │     │      │   ├── 2020-10-15.csv
    │     │      │   └── 2020-11-15.csv
    │     │      └── quality
    │     │          ├── 2020-10-15.csv
    │     │          └── 2020-11-15.csv
    │     │
    │     └── projet2
    │          ├── _index.md
    │          ├── accessibility.md
    │          ├── quality.md
    │          ├── performance.md
    │          ├── accessibility
    │          │   ├── 2020-10-15.csv
    │          │   └── 2020-11-15.csv
    │          ├── lighthouse
    │          │   ├── 2020-10-15.csv
    │          │   └── 2020-11-15.csv
    │          └── quality
    │              ├── 2020-10-15.csv
    │              └── 2020-11-15.csv
    ┋
    ┋ ⚠️ Autre choix d’arborescence avec un seul projet ⚠️
    ┋
    └── audits // Les pages pour afficher les audits (accessibilité, qualité, performance…) 
          ├── accessibility.md
          ├── quality.md
          ├── performance.md
          ├── accessibility
          │   ├── 2020-10-15.csv
          │   └── 2020-11-15.csv
          ├── lighthouse
          │   ├── 2020-10-15.csv
          │   └── 2020-11-15.csv
          └── quality
              ├── 2020-10-15.csv
              └── 2020-11-15.csv

Architecture complète (⚠️ Ancienne présente une architecture alternative, elle doit évoluer pour correspondre à tous les types de contenus)

Attention dans ce cas de figure: ⚠️ Le nom des pages projets content/projects/projets1.md, des répertoires projets static/projet1/ et des répertoires des pages d’audits content/audits/projets1/accessibility.md doivent bien comporter la même clef ou slug, ici : projet1. ⚠️
Un script devrait permettre de créer ces fichiers automatiquement à partir du moment un répertoire dans static est créé, mais il n’existe pas encore. La création doit se faire manuellement.

.
├── config.toml
├── content
│   ├── _index.md // page d’accueil du site :: ⚠️ Ajouter `type: projects` dans l'entête du fichier en cas de mono projet => va afficher directement la page de synthèse de tous les audits
│   ├── audits // Les pages pour afficher les audits (accessibilité, qualité, performance…) pour chaque projet
│   │    ├── projet1 // Doit reprendre le nom du répertoire donné au projet dans `static`
│   │    │     ├── _index.md // ⚠️  pour avoir lister les pages sur l’accueil et avoir la page intermédiaire qui liste tous les rapports
│   │    │     ├── accessibility.md
│   │    │     ├── quality.md
│   │    │     └── performance.md
│   │    └── projet2 // Doit reprendre le nom du répertoire donné au projet dans `static`
│   │          ├── _index.md
│   │          ├── accessibility.md
│   │          ├── quality.md
│   │          └── performance.md
│   ├── meetings
│   │    ├── _index.md // liste les réunions
│   │    └── 2020-10-22-reunion1.md // On indique la date dans le nom de fichier pour ranger les fichiers visuellement, il faut la répéter dans l’entête YML du fichier pour afficher les réunions sur la page dans un ordre par date.
│   ├── personas // ⚠️ Ne fonctionne pas en mono projet
│   │    ├── _index.md // Liste tous les personas
│   │    ├── simon.md
│   │    ├── annie.md
│   │    └── projet1
│   │         ├── _index.md // liste tous les personas
│   │         ├── simon.md
│   │         └── annie.md
┋   ┋
┋   ┋ ⚠️ Autre choix d’arborescence avec un seul projet ⚠️
┋   ┋
│   ├── audits // Les pages pour afficher les audits (accessibilité, qualité, performance…) 
│         ├── accessibility.md
│         ├── quality.md
│         └── performance.md
└── static
    ├── projet1
    │    ├── accessibility
    │    │    ├── 2020-10-15.csv
    │    │    └── 2020-11-15.csv
    │    ├── lighthouse
    │    │    ├── 2020-10-15.json
    │    │    └── 2020-11-15.json
    │    ├── quality
    │    │    ├── 2020-10-15.yml
    │    │    └── 2020-11-15.yml
    │    ├── usertests
    │    │    ├── test1.json
    │    │    └── test2.json
    │    ├── backlinks.json
    │    ├── personas.json
    │    └── similary.json
    ├── projet2
    │    └── accessibility
    │         ├── 2020-10-15.csv
    │         └── 2020-11-15.csv
    ┋
    ┋ ⚠️ Autre choix d’arborescence avec un seul projet ⚠️
    ┋
    ├── accessibility
    │    ├── 2020-10-15.csv
    │    └── 2020-11-15.csv
    ├── quality // Ne fonctionne pas complètement en mono projet
    │    ├── 2020-10-15.yml
    │    └── 2020-11-15.yml
    ├── usertests // Ne fonctionne pas en mono projet
    │    ├── test1.json
    │    └── test2.json
    ├── directory.json // Annuaire de contacts
    └── images
         ├── projet1 // Doit reprendre le nom du répertoire donné au projet dans `static`
         │    ├── benchmark
         │    │    ├── titresiteweb-titreelementacomparer.png // nommage précis disponible sur la page rapport générée par Hugo
         │    │    ├── ojdcourtsepay.tylerhost.net-navigation-step.png
         │    │    ├── pages.fivepointpayments.com-navigation-step.png
         │    │    └── finepayment.saskatchewan.ca-navigation-step.png
         │    └── quality
         │         └── 2020-10-16 // Les titre formant les noms d‘images doivent correspondre à des termes existant dans le fichier `.yml`
         │             ├── titrepage-[before ou after].png
         │             ├── titrepage-titrebloc-titreerreur-[before ou after].png
         │             ├── accueil-before.png
         │             ├── accueil-after.png
         │             ├── accueil-banniere-titres-before.png
         │             └── accueil-banniere-titres-after.png
         ├── projet2
         └── personas

Configuration

Exemple de fichier de configuration : config.toml

title = "Mon administration"
theme = "fargo"

[params]
  organisation = "Le nom complet de mon administration"
  [params.strategy]
    schema = "https://www.monadministration.gouv.fr/schema_pluriannuel_2020-2022.pdf" // Optionnel
    plan = "https://www.monadministration.gouv.fr/plan_annuel_2020.pdf" // Optionnel

Personnalisation du thème

Hugo permet de surcharger les fichiers présents dans le thème, la condition est de respecter la même arborescence. Ainsi pour surcharger un thème avec :

Sa police
Son logo
Ses couleurs *…

Il suffit de créer tout ces fichiers dans le répertoire static. Le thème appelle automatiquement les polices contenus dans le répertoire static/assets/fonts (à la place de la police Marianne).

static
└── assets
    ├── css
    │   ├── fonts.css
    │   └── main.css
    ├── favicons
    │   ├── android-chrome-192x192.png
    │   ├── android-chrome-512x512.png
    │   ├── apple-touch-icon.png
    │   ├── favicon-16x16.png
    │   ├── favicon-32x32.png
    │   ├── favicon.ico
    │   └── site.webmanifest
    ├── fonts
    │   ├── open-sans-bold.woff2
    │   └── open-sans-regular.woff2
    └── images
        ├── logo.svg
        └── logodark.svg

Contenus

Accueil

La page d’accueil présente la liste de tous les projets existants dans content/projects. Si le défi ne présente qu’un seul projet, et que la type de la page d'accueil est type: "projects", alors la page affiche la page de résumé du projet.

Projets

La page de projets doit servir à présenter l’état de la démarche, puis le planning d’avancée du commando et enfin lister éventuellement des liens vers des billets de types : réunions ou actions (à insérer dans dans content/meetings et content/actions).

Audit

L’audit d’accessibilité peut être de conformité ou d’accompagnement. L’audit de conformité peut-être unique (évoluera au cours du projet) ou daté (ex: 2021-03-12.csv) et présent dans le répertoire static/accessibility/.

L’audit d’accompagnement a pour but de lister tous les types d’erreurs afin de faire un suivi des éléments à corriger avec une équipe de développement.

Accessibilité

Éditer : static/nomdelademarche/accessibility/YYYY-MM-JJ.csv

L'audit accessibilité est généré à partir d‘un .csv (fichier à plat). Les données relatives au test (optionnelles) peuvent être indiquées dans l’entête du fichier .md de l’audit dans content/audits/nomdelademarche/accessibility.md.

---
type: accessibility // appel le gabarit accessibility :: static/nomdelademarche/accessibility/YYYY-MM-JJ.csv (fichier le plus récent)
accessibility:
  website: "amendes.gouv.fr"
  guidelines: "RGAA 4.0"
  condition: "Auto-évaluation" // ou audit externe avec le nom de la structure qui a procédé à l’audit
  technologies: ["HTML", "CSS", "JS"]
  tools: ["Wave", "AXE", "MOZ DevTools"]
  environment: ["MacOS", "Chrome", "ChromeVox"]
  contact:
    email: [email protected]
    address : 139 rue de Bercy, 75572 Paris, Cedex 12
---

Qualité

---
type: quality // appelle le gabarit quality :: avec les données du fichier plus récent dans static/nomdelademarche/quality/YYYY-MM-JJ.yml
datafilename: YYYY-MM-JJ // appel le fichier avec la date correspondante
---

Annuaire

Lister les personnes contactées pendant la durée du défi de mise en conformité. Cet annuaire permet de partager les contacts dans le temps de l’amélioration de la démarche.

Éditer : static/directory.json

Recueil de tests utilisateurs

Les tests utilisateurs de type quantitatifs consistent à poser des questions similaires à un panel important d’usagers. Pour le service usertests, il existe une mise en forme pour l’analyse rapide de ces résultats.

Fonctionne à partir d'une JSON, mais pourrait marcher avec du CSV directement (Ici, penser à convertir le CSV en JSON).

Éditer : static/nomdelademarche/usertests/nometude.json (à faire évoluer)

Ajouter à l'entête du fichier de contenu :

---
type: usertests // appel le gabarit usertests
datafilename: etudiants // appelle le fichier nommé etudiants :: dans static/nomdelademarche/usertests/etudiants.json
---

Performance

L’audit de performance apporte une complémentarité à l’audit d’accessibilité en listant de manière automatique des éléments à optimiser. Il peut être reproduit de manière régulière. Le dernier test vient surcharger les autres sur la page projet. Il n'existe pas encore de gabarits d'analyse graphique dans le temps.

Éditer : static/nomdelademarche/lighthouse/YYYY-MM-JJ.json

Personas

Définir des personas et les afficher sur une même page pour les partager à l’équipe projet. On peut sélectionner les profils retenus pour les tests.

Hugo nécessite de créer les pages correspondantes pour chaque personas ; si on veut afficher les personas en détail. Créer les pages dans content/personas/nomdelademarche/prenom-nom.md.

Éditer : static/nomdelademarche/personas.json

Parcours

Ajouter un parcours type par personas pour fournir une base visuelle à l’équipe projet de ce qui est testé. Le gabarit permet de partir d’un élément parent unique puis de développer autant de sous branches possibles dans la limite de 4 niveaux de profondeur (compatible mobile).

Éditer : static/nomdelademarche/personas.json

Composants

Scores

Phases

Nécessite d’ajouter un type de catégorie dans le config.toml ; et d’ajouter le tag dans chacun des contenus qu’on souhaite voir afficher dans une phase.

Les contenus listés sont donc hétérogènes.

Shortcodes

Galerie de capture écrans

Afficher une liste de captures d’écran pour illustrer une étude comparative.

{{< benchmark datafile="amendes" src="-explications" >}}{{< /benchmark >}}

Sites similaires

Afficher la liste des sites similaires à la démarche (action de benchmarking). Les sites sont rangés par pays.

Éditer : static/nomdelademarche/similary.json

{{< similary project="amendes" >}}{{< /similary >}}

Diagrammes

Appel de la librairie mermaid.JS. Ajouter la syntaxe Mermaid dans le contenu du shortcode.

{{< mermaid >}}
    graph TD
      A(Je reçois un avis)
      A --> B{Je paye une amende}
      B --> |Carte Bancaire| C(Site web)
      B --> |Carte Bancaire| D(Application)
      B --> |Chèque| E(Courrier)
      B --> |Chèque/Espèce/CB| F(Buraliste)
      B --> |Carte Bancaire| G(Téléphone)
      B --> |Chèque/Espèce/CB| H(Trésor Public)
      B --> |Virement pour étrangers| I(Site web)
{{< /mermaid >}}

Graphiques

Petit aide pour l’affichage de graphiques. Passer les données dans le contenu du shortcode. Choisir le titre et le type de graphique à afficher : bar, line, donut…

{{< graphic title="Ventilation des paiements dans l’année (en milliers)" type="bar">}}
{
    labels: ["Vitesse", "PV électronique", "Feux rouges"],
    datasets: [
      {
        name: "Internet",
        values: [3351, 2482, 85],
      },
      {
        name: "Smartphone",
        values: [492, 497, 12]
      }
    ]
}
{{< /graphic >}}

Personas

Afficher les personas sur la page de son choix en fonction du projet de son choix.

{{< personas project="amendes" >}} {{< /personas >}}

Parcours

Afficher les parcours sur la page de son choix en fonction du projet de son choix.

{{< parcours project="amendes" >}} {{< /parcours >}}

Utiliser ce module comme thème d'un projet

Site officiel : https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme

Initialiser votre projet pour utiliser les modules hugo : $ hugo mod init [MON_GESTIONNAIRE_DE_DEPOT]/[MON_COMPTE]/[MON_PROJET] par exemple : $ hugo mod init github.com/disic/frago
Importer ce module dans le fichier config.toml:

[module]
  [[module.imports]]
    path = "github.com/disic/frago"

C’est installé ?

En mode dev, lancer hugo server. Mais préférer : HUGO_ENV=production hugo server --buildFuture, pour le mode production.
Mettre à jour le thème, lancer: hugo mod get -u github.com/disic/frago/ ou juste hugo mod get -u.
L’appel de thème n'est pas possible avec Netlify, il est nécessaire d’indiquer cette commande dans l’interface git submodule add https://github.com/disic/frago.git/ themes/frago -f && git submodule update --init --recursive && hugo --gc --minify --buildFuture --templateMetrics

Licence

Le code source de ce dépôt est publié sous licence MIT.

La marque d'État est à usage exclusif des acteurs de la sphère étatique. En particulier, la typographie Marianne© est protégée par le droit d'auteur.
Lire les explications sur le site de la marque d’État.

Le thème Frago utilise cette liste de bibliothèques :

Frappe Charts (MIT) : https://github.com/frappe/charts - https://github.com/frappe/charts
Mermaid (MIT) : https://github.com/mermaid-js/mermaid
Highlight.js (MIT) : https://github.com/highlightjs/highlight.js
simplelightbox (MIT) : https://github.com/andreknieriem/simplelightbox
Van11y accessible tabs panel system (MIT) : https://github.com/nico3333fr/van11y-accessible-tab-panel-aria
Checka11y.css (MIT) : https://github.com/jackdomleo7/Checka11y.css

Auteur

2020-2021, Bertrand Keller pour le ministère de l’économie, des finances et de la relance.

Name		Name	Last commit message	Last commit date
Latest commit History 448 Commits
assets		assets
content		content
data		data
exampleSite		exampleSite
i18n		i18n
images		images
layouts		layouts
static		static
.editorconfig		.editorconfig
.gitignore		.gitignore
LICENSE.md		LICENSE.md
README.md		README.md
config.toml		config.toml
go.mod		go.mod
netlify.toml		netlify.toml
package.json		package.json
postcss.config.js		postcss.config.js
theme.toml		theme.toml

License

PhilGim/frago

Folders and files

Latest commit

History

Repository files navigation

Génération de rapports de synthèse pour le suivi et l’amélioration de l’accessibilité web.

Présentation

Démarrage (Configuration simplifiée)

Architecture de contenu

Configuration

Ajouter le fichier : config.toml

Appeler le thème Hugo (avec le système de module Go)

Créer le fichier go.mod (commande dans le terminal)

Créer le fichier go.sum (commande dans le terminal)

Appeler le thème Hugo (avec un submodule)

Génération du site (mise en ligne)

Héberger avec Github

Héberger avec Gitlab

Audits

Accessibilité

API

Configuration détaillée

Architecture de contenu

Arborescence

Architecture simplifiée

Architecture complète (⚠️ Ancienne présente une architecture alternative, elle doit évoluer pour correspondre à tous les types de contenus)

Configuration

Personnalisation du thème

Contenus

Accueil

Projets

Audit

Accessibilité

Qualité

Annuaire

Recueil de tests utilisateurs

Performance

Personas

Parcours

Composants

Scores

Phases

Shortcodes

Galerie de capture écrans

Sites similaires

Diagrammes

Graphiques

Personas

Parcours

Utiliser ce module comme thème d'un projet

Licence

Auteur

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Ajouter le fichier : `config.toml`

Appeler le thème Hugo (avec le système de module `Go`)

Créer le fichier `go.mod` (commande dans le terminal)

Créer le fichier `go.sum` (commande dans le terminal)

Packages