access4all / adg Goto Github PK

Add proper meta tags for sharing on Facebook, Twitter etc.

In the menu, the short title should be used.

Maybe the long title will be displayed as a tooltip; or even the lead text?

In #36, the example links look great already:

But they're produced using a lot of spaghetti code. They need to be refactored into components: one for the example links themselves, and one for an accordion (called by the example links).

I have created the basic file structure and their contents:

But I need support in making them work and replacing the current spaghetti things.

I don't think that removing the background colour adds to legibility.

Also, keeping the background needs less specific CSS declarations, like the following bug (?) demonstrates:

And after scrolling:

I added a lot of content to the master branch, so our internal testers can test it. It is (nearly) the full selection of the final content.

As such, re-processing all markdown files all the time is extremely time-intensive, and we should configure the project in such a way that only changed files are re-processed.

Line wrap looks bad:

For proper search engine indexing

For the time being, we stick to simple PNG backgrounds.

Before going live, we have to decide whether we use a sprites generator, or switch to SVG completely.

Momentan scheint das Dropdown-Menü nur 1-stufig zu sein, so dass man zu tiefer verschachtelten Inhalten gar nicht so einfach kommen kann.

Wie wäre es, wenn entweder das Dropdown-Menü verschachtelt würde (gar nicht so trivial, da Bootstrap dies nicht von Haus aus anbietet)?

Oder man könnte auf der linken Seite ein Sub-Menü mit ggf. verschachtelten Listen anbieten. (Allerdings habe ich aktuell bewusst nur 2 Verschachtelungs-Stufen benutzt bisher, also wenn das Menü oben ein Dropdown-Menü bleibt, dann bräuchte es auf der linken Seite bis auf weiteres keine Verschachtelung.)

Each part of the guide should have its dedicated background colour.

• Welcome: orange
  • Don't know whether orange is a good colour here...
• Setup: red
  • Red feels "technical" to me
• Knowledge: blue
  • Blue just feels right for me for knowledge
• Examples: green
  • As examples should resemble good ways to go, I think green gives a good signal

What do you think? Except green for examples I'm pretty open to other opinions.

I'm thinking of whether www.accessibility-developer-guide.com is too long. On the other hand it is very "self-speaking".

What about the following URLs?

• a11y-developer-guide.com
• a11y-dev-guide.com
• accessibility-developer.guide
• a11y-developer.guide
• a11y-dev.guide
• a11y.guide

While using .guide TLD feels nice and freaky to me, I'm pretty unsure whether those verbose TLDs are already present in the collective awareness of internet users?

Also the numeronym a11y doesn't feel very prominent to me, especially for people new to accessibility, and the double 1 could easily be misinterpreted as double l (L).

And somehow, accessibility-developer.guide feels a bit strange to me, accessibility-development.guide feels better.

What do you guys think?

We made a first attempt a while ago already:

https://github.com/Access4all/adg/tree/feature/template-engine

Would be really useful to have this running now.

https://github.com/blog/1184-contributing-guidelines

Probably including commit guidelines etc.

If possible, the examples should also be available in the ADG itself (not only Codepen), in a plain layout that doesn’t disturb (no headings, no special containers… just a visual frame for displaying the plain examples, maybe with a link "Back to the ADG" at the bottom).

While Codepen is a great service, it may not be ideal to run the examples in a screen reader easily (iframes, etc.).

https://deploy-preview-40--keen-galileo-2ca7df.netlify.com/setup/browsers/bookmarklets/contents-structured/

I think it's an escaping problem?

Use position meta data in README.md files.

At the time being, the code examples are written in Slim, Sass and CoffeeScript.

In our project's frontend, we're using Pug (formerly Jade), SCSS and JavaScript.

We should unify all of this for two main reasons:

1. To keep the code base uniform.
2. To show people who don't know about preprocessors yet the advantages of them (it's incredible how many source code problems result from using plain HTML).

I suggest converting everything (frontend, examples) to:

• Pug (formerly Jade)
• SCSS (I prefer Sass, but the official recommendation is to use the SCSS syntax, as it is closer to original CSS)
• CoffeeScript (though I'm not sure whether this would add dependencies we don't like?)

All of these should have support for automatic prettify, I guess?

There are several tools like http://html2jade.org/, sass-convert (http://sass-lang.com/documentation/file.SASS_REFERENCE.html), http://js2.coffee/ to help us with the conversion.

It would also be great to have the option to open examples on Codepen in either original version and compiled version (Codepen supports Pug, SCSS/Sass and CoffeeScript).

TODO: Proper styling

Find a way to extend Markdown support for more semantic HTML5 elements like

<samp>, <kbd>, <cite>, <q>, <dfn>, <abbr>, etc

Hint: https://www.npmjs.com/search?q=markdown-it

Also handle custom attributes as per #5

The heading levels in the README.md files need to be indented by 1, otherwise level 1 (the page’s main heading) and 2 (all sub titles) both are on the first level.

This is due to the fact that in my CMS, this happens automatically, and I don’t want the authors of content to need to worry about knowing on which level they should start.

If it’s not easy to fix that for the site generator, I could export everything so the headings start on level 2. What do you think, @backflip?

I think we should have the same visual attributes for both hover and focus states: underline for text links and borders for other elements.

The menu needs to be working.

For the currently active menu item, please set a visually hidden text (current page) like so: "Semantics provide meaning (active page)", and for its parents use "(active parent)".

I’m unsure whether aria-expanded and aria-current would be good options here, but let’s stick to fool-proof techniques for the time being.

Content added by CSS using content is announced by screen readers:

Instead of the >, we should either use a character that makes sense to be announced (for example an arrow to the right → or a bullet • or something like that), or even an emoji?

We decided to remove the title from the metadata, as it is redundant there.

We keep the title as h1 in the markdown file, and indent each title of the content by 1 when exporting.

As per https://github.com/gulpjs/gulp-util, the "gulp-util" package has been deprecated and should be replaced with suggested/recommended alternatives.

/cc @backflip

The sitemap is already available but it does not contain all the URLs.
It should be improved so that it could also be used for search indexing purposes.

Find a way to extend Markdown support for more semantic HTML5 elements like

<cite>, <q>, <dfn>, etc

Note: apparently these elements don't have a corresponding Markdown-IT plugin yet, so custom ones should be developed.

Here it does: https://deploy-preview-40--festive-mcnulty-536163.netlify.com/examples/tables/responsive/

Here it doesn't: https://deploy-preview-40--festive-mcnulty-536163.netlify.com/examples/tables/responsive/_examples/table-with-visually-hidden-headers-in-narrow-view/example.html

Possibly using the Google Search Widget Thingie

While creating screenshots on my Mac, i noticed that they are saved in retina resolution, which is too big for default websites.

Is it easily possible to implement both default and retina images? It would be a shame to have a crispy clean design for the ADG, but "smudged" low res images.

I use this a lot in Markdown, and it looks ugly:

It would be great if they were replaced with real ASCII arrows.

https://a11y-community.slack.com/

Invite link: https://join.slack.com/t/a11y-community/shared_invite/enQtMzMwOTkxNTI3NDYwLWI3MjRmZDQwOGMxOGVhNTI2NDg0ODhiMDUyZTQ4MDE4MzU1NmZiMTY2YmNjNjliYWEzODhjZDYwYjA1MDU4NmU

The :lead element from the metadata isn't displayed. It should be displayed between the title (h1) and the content. It is always a single line of text (rendered into a paragraph by Markdown).

It should render in a distinguished font variant (see design).

Im CMS habe ich es so gehandhabt, dass interne Links ohne Benennung im Markup autom. durch den Titel der referenzierten Seite ersetzt werden, z.B.:

Bitte lesen Sie dies: [](seite-xy)

Wird zu:

Bitte lesen Sie dies: <a href="...">Titel der Seite XY</a>

Und wenn man eine Benennung gab, dann wurde der tatsächliche Titel als title Attribut hinzugefügt:

Bitte lesen Sie [hier](seite-xy) weiter!

Wird zu:

Bitte lesen Sie <a href="..." title="Titel der Seite XY">hier</a> weiter!

Mittels JavaScript wird aus dem title dann ein Tooltip erstellt.

Damit wird die Anforderung an "self speaking links" automatisch optimiert:

(Natürlich muss der Tooltip zugänglich programmiert sein, aber das wir dann Severin's Aufgabe sein.)

Please remove.

Tasks

• add 2 pages with detailed documentation about how to use VMware Pro and VirtualBox in order to test accessibility in a separate virtual environment.

Current doc: http://adg.access4all.ch/en/pages/45

I don't know whether we ever need H5 or H6, but I found many H4 like this:

Wie hier bereits angetönt, wäre es sinnvoll, einzelnen Elementen per Markdown weitere Attribute hinzufügen zu können, etwa CSS-Klassen.

Für interne Links würde dann z.B. .page vergeben, für Code-Beispiele ein .code, für Grafiken ein .image, etc.

Momentan sieht das noch so aus:

{.page title="Hiding elements from all devices"}

Screenshot:

Currently on my Macbook Pro:

It seems, that next to sprite-1x.png there already exists a sprite-2x.png, but it's not yet properly configured:

https://github.com/Access4all/adg/ needs to be the master

Once the pages structure is stable, the Site Search 360 setup needs to be fine-tuned in order to have relevant search suggestions and results.

Also take into account this preliminary feedback: #37 (comment)

A next (and maybe previous) link at the bottom of each page would be great.

Remove all role-attributes and replace them with their respective semantic elements, e.g. role="main" should be a <main> container.

Don’t do redundant stuff like <button role="button">. See https://accessibility-developer-guide.netlify.com/knowledge/aria/safe-and-misuse/.

@jmuheim, could you create an "official" Netlify account and give it read access to this repository?

In the long term we'll need to add the proper domain there, too (if we keep using Netlify).

Should look a little more distinctive (https://accessibility-developer-guide.netlify.com/examples/widgets/autocomplete/):

Maybe with the codepen icon?

Make sure it displays the same in the example layout (https://accessibility-developer-guide.netlify.com/examples/widgets/autocomplete/_examples/autocomplete-with-radio-buttons/):

Interestingly, this doesn't happen in examples layout:

The Codepen links need to be working.

Display of HTML, CSS and JS isn’t necessary for the time being (it could be disturbing especially for screen reader users, if not done correctly, and I will have to investigate this a little deeper to know how to do it well).