spec: WAI-ARIA role syntax

MurakamiShinyu commented 3 years ago

https://github.com/vivliostyle/vfm/blob/master/docs/vfm.md#wai-aria-role

VFM

# Table of Contents {@toc}

HTML

<nav id="table-of-contents" role="doc-toc">
  <h1>Table of Contents</h1>
</nav>

The doc- prefix of Digital Publishing WAI-ARIA roles should not be ommited in the VFM syntax. We should use {@doc-toc} for role="doc-toc" because:

for consistency with CSS rules, [role="doc-toc"]. Using same role name is better to understand
for extensibility to be able to specify roles other than doc-*

MurakamiShinyu commented 3 years ago

WAI-ARIA role syntax の見直し案

Summary

https://github.com/vivliostyle/vfm/issues/5#issuecomment-768119623 の「role 属性について」から:

role 属性のための @ をプレフィックスする記法（例: @appendix）は廃止したい
クラス名に DPUB-ARIA で定義された語彙を使うことを推奨し、そのようなクラス名が指定されたら自動的に role 属性も付加するようにする
- 例: ::: appendix または {.appendix} → <section class="appendix" role="doc-appendix">
スタイルシートでは role 属性ではなくクラス名を使う（[role="doc-appendix"] ではなく .appendix を使うこと）
- role 属性はアクセシビリティ用途、クラス名はスタイルシート用途、と区別
role 属性によって自動的に生成する HTML 要素を変えるようにはしない
- ある role 属性値を指定するのに適切な HTML 要素はひとつと限らない
- HTML 要素名を明示的に指定できるしくみがあったほうがよい → https://github.com/vivliostyle/vfm/issues/5#issuecomment-768119623 の「HTML 要素名を明示的に指定可能にする拡張案」

詳しい説明

DPUB-ARIA で定義された role 属性に指定できる語彙は、文書の要素の論理的な意味を表すものとして標準となるもので、これをサポートすることは作られるWeb文書のアクセシビリティの向上のために有用である。

しかし、この role 属性は、クラス名とは違い、スタイルの指定に使いやすいようにはなっていない。スタイルの指定にはクラス名のほうが便利である（[role="doc-appendix"] {…} より .appendix {…} のほうがシンプル）。また、role 属性のために定義されている語彙は限られており、そこにないものはクラス名を使う必要があるため、スタイルシート内で role 属性とクラス名の両方を使い分ける必要があり、それもめんどう。したがって role 属性を指定しても、クラス名にも同じ名前を指定するようにして、スタイルシートではもっぱらクラス名を使う方が便利。

それならば、VFM でのクラス名を指定する構文（例: ::: appendix や {.appendix}）で、DPUB-ARIA で定義された語彙と一致する名前に対しては <section class="appendix" role="doc-appendix"> のようにクラス名と role 属性の両方を出力するのがよいだろう。

HTML/CSS のクラス名は、文書構造で論理的に意味のある名前を使うことが推奨されており、また、DPUB-ARIA で定義されているのはそのような語彙を集めたものなので、それをクラス名にも使うのは理にかなっている。そしてクラス名とともに role 属性が HTML に出力されることは、VFM の利用者が意識しなくても出力されるWeb文書のアクセシビリティの向上につながるというメリットがある。

role 属性によって自動的に生成する HTML 要素を変える機能は、ある role 属性値を指定するのに適切な HTML 要素は一種類と限らないし、期待される適切な HTML 要素が生成されると限らないという問題がある。それよりも HTML 要素名を明示的に指定できるしくみがあったほうがよいだろう。その提案 → https://github.com/vivliostyle/vfm/issues/5#issuecomment-768119623 の「HTML 要素名を明示的に指定可能にする拡張案」

akabekobeko commented 3 years ago

昨日の開発者会議を受けた #67 のとおり、本機能は v2 へ見送ります。

vivliostyle / vfm