アクセシビリティガイド

文書をアクセシブルにするということは、全ての人がその文書を使用し理解できるようにすることを意味します。それには、恒久的または一時的な障害を持つ人々だけでなく、さまざまなデバイスや好みを持つ人々も含まれます。アクセシビリティが重要な理由を強調するために、人々があなたの想定以上にさまざまな状況で文書を読む可能性があることを考えてみてください。

ユーザーが文書を紙に印刷するかもしれない
ユーザーがPDFリーダーのリフロー機能を有効にして、携帯電話で文書を読むかもしれない
ユーザーが自身のコンピューターに文書を読み上げさせるかもしれない
ユーザーが人工知能に文書の要約を依頼するかもしれない
ユーザーが文書をHTMLなどの、よりアクセシブルなファイル形式に変換するかもしれない

これら全ての人々とシナリオに対応するために、ユニバーサルアクセスを考慮して文書を設計するべきです。ユニバーサルアクセスは、シンプルでありながら強力な原則です。後からアクセシビリティ対応を付け足すのではなく、最初から、できるだけ幅広いユーザーと利用状況に対応できるように設計します。これにより、全ての読者の体験が向上します！

Typstは、スクリーンリーダーで読み取りやすく、異なる画面サイズ向けにリフローされても見栄えがよく、自動アクセシビリティチェッカーにも合格しやすいアクセシブルなファイルの作成を支援できます。ただし、アクセシブルなファイルを作成するには、いくつかのルールを意識する必要があります。このガイドでは、アクセシビリティに影響する要因、ユニバーサルアクセスのための設計方法、そしてそれを実現するためにTypstが提供するツールを学べます。ここで述べる指針の多くは、全てのエクスポート形式に当てはまりますが、本ガイドはPDFエクスポートに焦点を当てています。HTMLエクスポートとの重要な違いも記載します。

アクセシビリティの基礎

アクセシブルなファイルは、ソフトウェアが単にファイルを描画する以上のことを行えるようにします。すなわち、コンピューターが文書の各要素が何を表しているかを理解し、その情報を用いてユーザーに文書を提示できるようになるのです。

この情報はアクセスを提供するためにさまざまなソフトウェアによって利用されます。TypstからPDFをエクスポートすると、PDFビューアー（リーダーとも呼ばれます）が、Typstのプレビューでデザインした通りに文書のページを表示します。なかには、スクリーンリーダーや点字ディスプレイ、画面拡大鏡などの支援技術（Assistive Technology、AT）に頼ってPDFを利用する人もいます。その場合、ファイルに含まれるセマンティック情報が使われ、内容は音声や文字、あるいは別の視覚表現へと変換されます。また、PDFビューアーのリフロー機能を使い、Webページに似たレイアウトで閲覧するユーザーもいます。コンテンツは表示領域の幅にあわせて再配置され、連続的にスクロールできるようになります。さらに、別のユーザーはPDFを別の形式に再利用します。例えば大規模言語モデル（Large Language Model、LLM）に取り込むためのプレーンテキストやHTMLなどです。再利用の特殊な形としてコピー＆ペーストがあり、ユーザーはクリップボードを使ってファイルから内容を抽出し、別のアプリケーションで利用します。

アクセシビリティ対応はビューアーとATによって異なります。組み合わせによっては、他よりもうまく動作するものもあります。私たちのテストでは、WindowsではAdobe AcrobatとNVDAの組み合わせ、macOSではVoiceOverが最も充実したアクセシビリティ対応を提供しました。またHTMLエクスポートと組み合わせた場合、ブラウザーはPDFリーダーと比べて、より一貫したアクセシビリティの基準を提供します。

アクセシブルなファイルを生成できるのは、PDFとHTMLのエクスポートだけです。PNGとSVGは、どちらも単体ではアクセシブルではありません。どちらの形式も、テキストによる表現を用意することで、アクセシブルなより大きな成果物の中で利用できます。

セマンティクスの保持

ATによる利用や再利用のために正しいセマンティック情報をファイルに付与するためには、ファイル中の各部分がどのようなセマンティック上の役割を果たすのかをTypstが把握する必要があります。例えば、これはコンパイルされたPDFの見出しが単なる大きく太い文字のテキストであってはならないということを意味します。代わりに、その特定のテキストが見出しを構成することを示す明示的な情報（タグとして知られます）を含めるべきです。そうするとスクリーンリーダーはそれを見出しとして読み上げ、ユーザーが見出し間を移動できるようになります。

Typstの慣用的な使い方、すなわち組み込みのマークアップや要素を用いている場合、Typstは自動的にリッチなセマンティック情報を持つタグをファイルへ付与します。次の2つのコード例を見てみましょう。

// ❌ Don't do this
#text(
  size: 16pt,
  weight: "bold",
)[Heading]

// ✅ Do this
#show heading: set text(size: 16pt)
= Heading

どちらの例も、見た目は同じです。どちらも"Heading"というテキストが太字で、サイズは16ptになっています。しかしながら、アクセシブルなのは例のうち2つ目のみです。見出し用のマークアップを使うことで、Typstはこのテキストのセマンティックな意味が「見出し」であることを理解し、その情報を最終的なPDFに反映できます。1つ目の例では、Typstは通常のテキストに対して太字と大きめの文字を適用すべきだということしかわかりません。そのため、それが見出しを意図したものなのか、スタイル上の選択なのか、あるいは引用のような別の要素なのかを推測することはできません。

セマンティクスの利用は見出しに限りません。以下はセマンティクスを利用すべき要素のさらなる例です。

テキストを強調する場合はtext関数の代わりにアンダースコア/emphを使用する
テキストに強い強調を与える場合はtext関数の代わりにアスタリスク/strongを使用する
アイテム化された内容や順序のある内容を扱う場合は、改行を伴う通常のテキストの代わりにリスト（list、enum、terms）を使用する
インライン引用やブロック引用にはquoteを使用する
文献を手動で記述するのではなく、組み込みのbibliographyとcite関数を使用する
文書の他の部分を参照する場合は、単に参照をタイプするのではなく、ラベルとrefまたは@referencesを使用する
キャプションを提供する場合は、テキストを関数呼び出しの下に追加するのではなく、figure要素のcaption引数を使用する

要素のデフォルトのスタイルを調整したい時であっても、独自のカスタム関数で置き換えるのではなく、setルール、show-setルール、そしてshowルールを使用して外観をカスタマイズしてください。以下は、文書内の強い強調の見た目を変更する方法の例です。

// Change how text inside of strong emphasis looks
#show strong: set text(tracking: 0.2em, fill: blue, weight: "black")

When setting up your tents, *never forget* to secure the pegs.

show-setルールはstrong要素のデフォルトの見た目を完全に変更しますが、そのセマンティックな意味は保持します。さらにカスタマイズが必要な場合は、完全に独自のレイアウトコードを持つshowルールを指定できますが、それでもTypstはその要素のセマンティックな目的を保持します。

読み上げ順序

ATが文書中のコンテンツを正しい順序で読み上げられるようにするため、また再利用アプリケーションのためにも、アクセシブルなファイルは読み上げ順序を明示しなければなりません。これは、論理的な読み上げ順序がレイアウト順序とは異なる可能性があるためです。こうした差異の典型的な例がフロート図表です。図表がページ中央の段落に関連するものであっても、ページの上端や下端に配置されることがあります。アクセシブルでないファイルでは、PDFリーダーやATはレイアウト順序と論理的な読み上げ順序が同一であると推測せざるを得ず、その結果ATユーザーに混乱を招くことがよくあります。読み上げ順序が適切に定義されていれば、スクリーンリーダーは脚注やフロート図表を、意味が通る位置で直ちに読み上げます。

幸い、Typstのマークアップは既に単一の読み上げ順序を暗黙的に含んでいます。Typst文書は、マークアップ内で内容を配置した順に読み上げられると考えてよいでしょう。ほとんどの文章ではそれで十分です。ただし、place関数やmove関数、あるいはフロート図表を使用する場合は、たとえレイアウトに影響しなくても、マークアップ上の論理的な読み上げ順序として適切な位置に関数呼び出しを置くよう、特に注意が必要です。配置しようとしている内容をスクリーンリーダーにどの位置で読み上げてほしいかを自問してみてください。

レイアウトコンテナ

Typstはコンテンツを視覚的に配置するための、grid、stack、box、columns、blockなどのレイアウトコンテナを提供します。これらのコンテナにはセマンティックな意味は付与されません。TypstはPDFリフローの際にこれらのコンテナの一部を保持しますが、他のコンテナは破棄されます。

ユニバーサルアクセスのための設計の際、ATユーザーはコンテナが作り出す視覚的なレイアウトを閲覧できないことが多い、という点を認識しておく必要があります。代わりに、ATはその内容をただ読み上げるだけなので、アクセシビリティの観点ではこれらのコンテナは透過的なものと考えるのが最善です。例えば、グリッドの内容は、ソースコード内でセルを追加した順番通りに、ただ平坦に読み上げられるだけです。あなたが作成したレイアウトが単に視覚的・装飾的なものであれば、それで問題ありません。しかし、もしそのレイアウトが通常のPDFリーダーを用いてファイルを閲覧する、目の見える人にとっては明らかなセマンティックな意味を持つ場合は、それはアクセシブルではありません。その代わりに、テキストを活用した代替表現を作成するか、あるいは代替となるテキストによる表現を提供するために、figure要素で包んでください。

グリッドコンテナを表形式データの表現に使用してはいけません。代わりにtableを使用してください。表はATユーザーにとってアクセシブルであり、ユーザーはATによって表を2次元的に移動して参照できます。表はリフローや再利用の際にも保持されます。表を作成する際にはtable.headerとtable.footer要素を使用して、個々の行のセマンティックな役割をマークアップしてください。表のドキュメントには、表をアクセシブルにする方法について詳しく説明したアクセシビリティセクションがあります。また、ATユーザーが表にアクセスできるとはいえ、それがしばしば負担になることにも留意してください。表は視覚的な閲覧に最適化されているためです。セル群の内容を読み上げられながら、その行と列を思い出し続けなければならない状況は、追加の認知負荷を生みます。表の要点を、別の箇所でテキストやキャプションとしてアクセシブルに提供することを検討してください。

同様に、rotate、scale、skewのような関数を使用する場合は、この変換がセマンティックな意味を持たないか、あるいは意味がATユーザーに他の場所、つまり図の代替テキストやキャプションなどで利用可能であることに注意してください。

アーティファクト

ページ上の一部のものには、セマンティックな意味がなく、文書の内容にも関係しないものがあります。これらの項目をアーティファクトと呼びます。アーティファクトはATや再利用からは隠され、リフローの際には消失します。以下はアーティファクトの例です。

行末に自動ハイフネーションによって挿入されるハイフン
各ページのヘッダーおよびフッター
純粋に装飾目的のページ背景画像

一般に文書がアクセシブルと見なされるためには、ページ上の全ての要素が、ATが読み上げられる何らかの方法を持つか、またはアーティファクトである必要があります。

Typstは、ヘッダー、フッター、ページの背景・前景、自動ハイフネーションなど、多くのレイアウト上のアーティファクトを自動的にアーティファクトとしてタグ付けします。ただし、文書に純粋に装飾的な内容を追加したい場合は、pdf.artifact関数を使用して、コンテンツの一部をアーティファクトとしてマークできます。要素をアーティファクトとしてマークすべきかどうか迷った場合は、自問してみてください。スクリーンリーダーがその要素を読み上げるとしたら、単に邪魔になるだけでしょうか？それならば、それはアーティファクトかもしれません。逆に、読み上げられると便利なものであれば、それはアーティファクトではありません。

技術的な理由により、いったんアーティファクトの中に入ると、コンテンツは再びセマンティックになることはできません。アーティファクトとセマンティックな内容を重ねるには、placeを使用してそれぞれを独立した要素として重ねあわせてください。

Typstは、squareやcircleのような形状やパスをアーティファクトとしてマークしますが、その内容はセマンティックに関連し、ATにアクセス可能なままになることに留意してください。形状にセマンティックな意味がある場合は、代替のテキスト説明を提供するために、figure要素でそれらを包んでください。

色の使用とコントラスト

ユニバーサルアクセスとは、文書がAT、リフロー、再利用に対応していることのみを意味するのではありません。視力が低下している人も含め、全ての人が視覚的にアクセス可能であることを意味します。加齢にはしばしば視力の低下が伴うだけでなく、かなりの割合の人が色の識別に困難を抱えています。具体的には、男性の約8%、女性の約0.5%が色覚異常です。

種類別のドイツのエネルギー生産量（テラワット時）を横軸、年を縦軸に取った棒グラフ。各棒は最大4区画で、原子力（紫）、再生可能エネルギー（緑）、化石燃料（赤）、その他（青）を表す。右上に各色とラベルを対応付けた凡例がある。

同じ棒グラフを色を変えて示したもの。原子力とその他の区画は非常に近い濃い青で、隣接する再生可能エネルギーと化石燃料の区画も、ほとんど見分けがつかない黄系の2色になっている。

これは、文書内の情報を目の見える人にアクセシブルにする方法として、色を唯一の手段にしてはならない、ということを意味します。例として、1本の棒が複数の色分けされた区画で構成される積み上げ棒グラフを考えてみましょう。この例では、ドイツ国内のエネルギー生産量を種類別に示したグラフ¹を扱います。この図には、グラフの通常の見え方と、2型色覚の人にはどのように見えるかをシミュレートした画像が示されています。最初と最後の区画の2組はどちらも青っぽく見え、中央の2区画は黄色っぽく見えることがわかります。したがって、色覚異常の利用者にとって最初の課題は、「Renewable」と「Fossil Fuels」の区画の境界を見分けることです。さらに、どの区画がどれに対応するかを順序だけで追跡しなければならず、認知負荷が増します。このグラフをさらにアクセシブルでなくする方法としては、区画の順序を凡例の順序と一致させないことが挙げられます。

では、どうすればこのグラフを改善できるでしょうか。まず、どの情報も色の使用だけで伝えられないようにしてください。その方法のひとつは、各区画にパターンを追加することです。さらに、各区画の境界を見分けやすくするために、高コントラストの境界線を追加できます。すると、グラフは例えば次のようになります。

同じ棒グラフを元の配色で示したもの。今回は各区画の周囲に黒い輪郭線が追加され、さらに各区画に固有のパターンが付けられている。

一般的な色覚異常の人にも識別しやすい色を選ぶことで、このグラフはさらに改善できます。また、2色パターンを選ぶ、棒にあわせてそれらを整列させる、あるいはフォントの使い方を変えることで、デザインをさらに調整していくこともできます。

Webアプリでは、内蔵の色覚異常シミュレーターを使ってデザインを確認できます。利用するには、「View」メニューを開き、「Simulate color blindness」メニューで目的のモードを選択してください。Webアプリを使用していない場合でも、Web上の他のツールを使って、さまざまな種類の色覚異常における色の見え方をシミュレーションできます。

背景と前景の間の色のコントラストにも注意してください。例えば、脚注に薄いグレーの文字を使うと、読みにくくなることがあります。低コントラストを招きやすいもう1つの状況として、画像の上に文字を重ねる場合があります。

「注意。作動中のホチキスに手を近づけないでください」という文言を含む、デザインの異なる2つの注意喚起ボックス。各ボックスの下には文字と図形要素のコントラスト指標がある。左は薄い赤の背景に通常の赤文字で、文字コントラストは2.8:1、図形コントラストは1.4:1。右は白地に赤い枠線と濃い赤文字で、文字コントラストは5.9:1、図形コントラストは3.9:1。

この例では、注意喚起ボックスの2つのデザインを比較できます。これらのボックスはユーザーが危険を回避するのを助けることを目的としているため、ユーザーが実際にその内容を読めることがきわめて重要です。しかし、最初のボックスでは背景がかなり明るく、ボックス自体の輪郭を見分けにくくなっています。さらに悪いことに、薄い赤の背景上では赤い文字が読みにくくなっています。文字のコントラスト比は2.8:1で、Web Content Accessibility Guidelines（WCAG）が定める4.5:1の基準を満たしていません。同様に、ボックスの白いページ背景に対するコントラスト比も1.4:1で、グラフィカルオブジェクトに対する3:1の閾値を下回っています。

2つ目の例では、WCAG AAの色コントラスト閾値を満たすように色が調整されています。視力に問題がない場合でも、ボックス内の文字は明らかに読みやすくなっているはずです！

前景色と背景色として使う2色の組み合わせがどの程度のコントラストを持つかを比較するためのツールがあります。最も一般的なのは、WCAGの色コントラスト比です。フォントサイズが決まると、色の組み合わせは、基準を満たさないか、AAレベルに達するか、あるいはより高いAAAレベルに達するかのいずれかになります。全ての色の組み合わせについて、少なくともAAコントラストを目指してください。

コンテンツ	AA比率	AAA比率
大きい文字（18pt以上、または太字で14pt以上）	3:1	4.5:1
小さい文字	4.5:1	7:1
非テキストコンテンツ	3:1	3:1

WCAGのような一般的なアクセシビリティフレームワークでは、純粋に装飾目的の文字やロゴは例外扱いとなる点に注意してください。これらはグラフィックとしての性質を持つため、AAのコントラスト比基準を満たさないコントラスト比であっても許容される場合があります。

テキストによる表現

ATの利用や一部の再利用ワークフローをサポートするためには、セマンティックな意味を持つ全ての要素にテキストによる表現が必要です。これをユニバーサルアクセスの観点で考えてみてください。ある項目がアーティファクトでないなら、それはセマンティックな意味を持っています。しかし、ATがその項目を取り込めない場合、文書の持つセマンティックな意味をATユーザーは完全には受け取れません。したがって、ユニバーサルアクセスを実現するために、代替表現を提供するためのTypstの組み込み機能を利用してください。

画像を追加する際は、画像内で見えている内容を説明するために、必ずimage関数のalt引数を使用してください。この代替説明（altテキストとも呼ばれます）は、画像の要点を説明するものにすべきです。電話で友人にその画像を説明するとしたら、どのように説明するかを考えてみてください。良い代替説明を書くためには、その画像が現れる文脈を考慮してください。

#image("heron.jpg", alt: "?")

Herons have feet with interdigital
webbing, allowing for good mobility
when swimming, and wings that span
up to 2.3 m.

この画像には、どのような代替説明が適切でしょうか？避けるべき例をいくつか見てみましょう。

"サギの画像"
❌ スクリーンリーダーは画像であることをすでに自動で読み上げるため、「画像」と言うのは冗長です。この例では、ATユーザーには「画像、サギの画像」と聞こえます。
"鳥"
❌ この代替説明は十分に具体的ではありません。例えば、この画像がサギを描いていること、そして足と翼の両方が見えていることは、ユーザーにとって重要な情報です。
"飛行中のアオサギ。Wikimedia CommonsのMakasch1966による写真。CC Attribution 4.0 Internationalライセンス"
❌ 代替説明には、帰属情報・ジョーク・メタデータのような、画像に見えていない情報を含めるべきではありません。その情報は目の見えるユーザーにはアクセシブルでないことを念頭に置いてください。そうした情報は別の場所に記載すべきです。
"低空を右から左へ飛ぶアオサギ。足は伸びており、やや下向きで、暗い森が見え始めるぼやけた地平線に触れている。鳥の翼は広がって上向きに弧を描いている。画像の左下には、ピントの合っていない枝が見える。"
❌ この代替説明は冗長すぎます。画像が内容にとってどの程度重要かを判断してください。目の見えるユーザーが現実的にどのくらいその画像を見るかを考えてください。altテキストも、読むのにかかる負担がだいたい同程度になるようにするべきです。例えば、上の説明に含まれる解剖学的な記述は、動物学の教科書でより長い説明をする場合には適切かもしれません。一方、構図に関する情報は、写真について書く場合に有用です。この例の画像に付随する文脈は比較的短いため、より簡潔な説明にしてください。

代わりに、この例では次のような代替テキストを使うことができます。

"足と翼を広げて飛ぶサギ"
✅ この代替説明は画像を説明しており、文脈にも関連していて、求められる簡潔さにも合っています。

良い代替説明の書き方をさらに学ぶためのWeb上のリソースがあります。画像に代替テキストを追加するという要件は、全ての画像形式に適用されます。Typstは現在、PDF画像ファイル単体がアクセシブルであっても、コンパイル後の文書内ではそのPDF画像のタグを保持しません。

文字を画像にしたものは使わないでください。同様に、パス操作を使って文字を手動で描画しないでください。Typstは、画像内の文字をネイティブなテキストと同じようにアクセシブルにするために処理できません。このルールには1つだけ例外があります。文字の見た目が文書の意味にとって本質的であり、かつTypstのネイティブ機能では再現できない場合に限って、文字の画像を使用してください。その場合は、代替説明の中で、文字としての内容と本質的な視覚的特徴の両方を記述しなければなりません。

image関数と同様に、figure関数もalt属性を持ちます。この属性を使用すると、多くのスクリーンリーダーやその他のATはfigure内部の内容を読み上げず、代わりに代替説明のみを読み上げます。代替説明は、AT利用者がfigure本体にアクセスする必要がないよう、十分に包括的でなければなりません。代替説明は、figureの内容にほかの方法ではアクセスできない場合にのみ使用してください。例えば、figureにtable要素が含まれている場合は、そのfigureのalt属性を使用しないでください。一方、セマンティックな意味を持つ図形をfigure内で使用している場合は、alt属性を使用してください。altとcaptionの両方を指定すると、その両方がATによって読み上げられます。figureに画像が含まれている場合、代替説明はfigureではなく画像自体に設定してください。両方への設定は行わないでください。画像の説明がfigureの説明によって上書きされてしまうためです。

#figure(
  alt: "Star with a blue outline",
  curve(
    stroke: blue,
    curve.move((25pt, 0pt)),
    curve.line((10pt, 50pt)),
    curve.line((50pt, 20pt)),
    curve.line((0pt, 20pt)),
    curve.line((40pt, 50pt)),
    curve.close(),
  ),
)

最後に、math.equationを使って数式に代替説明を指定できます。数式は、自然言語で声に出して読み上げる場合を想定して記述してください。現時点では、全てのエクスポート形式で数式をアクセシブルにするために、代替説明の追加が必要です。数式に代替説明を追加しなかった場合、PDF/UA-1としてのエクスポートは失敗します。将来的には、TypstはMathML技術を活用し、HTMLおよびPDF 2.0における数式を自動的にアクセシブルにする予定です。

#math.equation(
  alt: "a squared plus b squared equals c squared",
  $ a^2 + b^2 = c^2 $,
)

テキストとして表現されるもう1つの要素はリンクです。hereやgoのような、説明的でないリンクテキストは避けるのが望ましいです。こうしたリンクテキストは、文書において検索エンジン最適化（Search Engine Optimization、SEO）を考慮する場合にも悪影響を及ぼします。代わりに、リンク先がわかるテキストを、リンク自体に含めるようにしてください。なお、最高レベルのアクセシビリティを目指しているのでなければ、リンク自体の文言が説明的でなくても、その目的が直近の周辺の文脈から理解できるのであれば問題ありません。

自然言語

スクリーンリーダーが文書を正しく読み上げ、翻訳ソフトウェアが適切に動作するためには、文書がどの自然言語で書かれているかを明示する必要があります。文書の冒頭で#set text(lang: "..")ルールを使用するか、テンプレート側の言語設定機能を使用してください。そうしない場合、Typstはその内容を英語で書かれているものとみなします。選択した自然言語は、アクセシビリティだけでなく、Typstがどのようにハイフネーションを適用するか、どの組版規則が適用されるか、図や参照のラベル、そしてWebアプリではスペルチェックにどの言語が使われるかにも影響します。

中国語や英語のように地域差が大きい言語を使用する場合は、region引数も使用してください。例えば、香港で話される中国語は次のように指定します。

#set text(lang: "zh", region: "HK")

言語を指定するには、ISO 639コードを使用します。地域については、ISO 3166-1 alpha-2コードを使用します。ISO 639には3種類の規格があり、ドイツ語の"de"のような2文字の言語コード用のものが1つ（ISO 639-1）、"deu"のような3文字の言語コード用のものが2つ（ISO 639-2とISO 639-3）あります。使用する言語に2文字のISO 639-1コードがある場合は、常にそちらを使用してください。ISO 639-2と639-3はほとんどのコードを共有していますが、いくつかの違いがあります。言語コードが両規格で異なる場合は、PDF 1.7（Typstのデフォルト）およびそれ以下へのエクスポートにはISO 639-2を、PDF 2.0とHTMLへのエクスポートにはISO 639-3を使用してください。

通常の言語コードを提供するのが難しい場合に使用できる、ISO 639-2とISO 639-3の両方で定義されている3つの特別な言語コードがあります。

zxxは自然言語でないテキスト用
undは自然言語を特定できないテキスト用
misは言語コードが割り当てられていない言語のテキスト用

文書に複数言語のテキストが含まれている場合は、text関数やスコープ付きのtext setルールを使用して、他の言語のインスタンスを囲むことができます。

This is #text(lang: "fr")[français].

#[
  #set text(lang: "es")
  Este es un fragmento más largo
  del texto en español.
]

文書タイトルと見出し

文書にタイトルを付けると、ATユーザーにとっても、通常のPDFビューアーのユーザーにとっても、その文書を見つけたり、ほかの文書との間を移動したりしやすくなります。このため、WCAGやPDF/UAなどのアクセシビリティ規格では、文書に機械可読なタイトルを設定することが求められています。

Typstでこれを行うには、以下のsetルールを、文書内のどのコンテンツよりも前に配置してください。

#set document(title: "GlorboCorp Q1 2023 Revenue Report")

これにより、文書メタデータ内のタイトルと、PDFビューアーやWebブラウザーのタイトルバーのタイトルが設定されます。テンプレートを使用していてこれがエラーになる場合は、テンプレート側で文書タイトルを設定する別の方法が用意されていないか確認してください。

おそらく、文書内にもタイトルを目に見える形で示したくなるでしょう。そのためには、title要素を使用します。title要素を引数なしで呼び出すと、文書タイトルとして設定したコンテンツがそのまま出力されます。あるいは、コンテンツを位置引数のbodyとして渡して、タイトルをカスタマイズすることもできます。文書内でtitle要素を複数回使用しないでください。

文書タイトルに見出しを使ってはいけません。代わりにtitle要素を使用してください。HTMLの経験がある場合は、Typstにおけるheading要素のセマンティクスがHTMLの見出しとは異なることを覚えておくことが重要です。Typst文書では、セクション見出しとして複数の第1レベルの見出しを使用することが推奨されます。HTMLにエクスポートする際、titleはh1タグとしてシリアル化される一方、第1レベルの見出しはh2タグとしてシリアル化されます。PDFエクスポートでは、対象とするPDFバージョンに基づいて、タイトルと見出しが正しくタグ付けされます。

使用する見出しの階層は、順番通りであることが重要です。より深い階層に進むときに、見出しレベルを飛ばしてはいけません。つまり、第3レベルの見出しの次には、レベル4以下の見出しが続く必要がありますが、レベル5以上の見出しが続いてはいけません。

// ❌ Don't do this:
= First level heading
=== Third level heading

Adobe Acrobatの自動アクセシビリティチェックを通過するためには、21ページ以上の文書にはアウトライン化された見出しが必要であることに注意してください。

アクセシビリティ規格と法令

Typstは、あなたの文書を国際規格に照らしてチェックすることで、その文書がアクセシブルであると主張することを支援できます。PDFエクスポートに関しては、アクセシブルなファイルのための複数の規格があり、特にPDF/UA規格が有名です。その第1部（PDF/UA-1）はすでにTypstでサポートされており、第2部（PDF/UA-2）のサポートは将来に向けて計画されています。以下に、関連する全ての規格についての説明を示します。

Tagged PDF: Tagged PDFには、ATが解析できる、文書のセマンティックな構造に関する機械可読なデータが含まれています。TypstはデフォルトでTagged PDFを書き出しますが、Typstは文書のセマンティックな構造について知っている場合にのみ適切なタグを付けることができることに注意してください。Typstの要素を使用してセマンティクスを伝える方法については、セマンティクスの保持セクションを参照してください。ユニバーサルアクセスを提供するためには、非テキストコンテンツのテキスト表現も自分で提供する責任があります。
PDF/UA-1: PDF/UA-1規格は、ユニバーサルアクセスに最適化されたPDF 1.7ファイルの書き方を説明しています。Tagged PDFを前提とし、画像や数式の代替説明を強制し、文書タイトルを要求し、表などの文書内容の構造に関するルールを導入します。このガイドに従っていれば、PDF/UA-1エクスポート中に発生する可能性のあるほとんどのコンパイルエラーをすでに回避しています。
PDF/UA-2: PDF 2.0ファイルを対象とした、より新しいPDF/UA-2という規格もあります。これは、数式やいくつかのセマンティックな要素のアクセシビリティを改善します。PDF/UA-2のサポートはまだTypstでは利用できませんが、計画されています。
Well Tagged PDF (WTPDF): これは、PDF/UA-2に非常によく似た業界規格です。PDF/UA-2と同様に、現在Typstではサポートされていません。もともとは、PDF/UA仕様の両方の部分が国際標準化機構から高額でしか入手できなかったために策定されました。そのため、WTPDFは全ての適合するファイルがPDF/UA-2への適合も宣言できるように設計されました。現在では、PDF/UA仕様の両方の部分が無料で利用可能になっているため、WTPDFの関連性は低下しています。
PDF/A-1a: PDF/A規格は、アーカイブに適したPDFファイルの作成方法を説明しています。PDF/A規格の第1部から第3部には複数の適合レベルがあります。最も厳しい適合レベルAにはアクセシビリティのルールが含まれており、そのルールを満たすファイルだけが将来の幅広い人々にとって利用可能な状態を保てます。レベルAはTagged PDFへの適合を前提とし、画像の代替説明を提供することを強制します。アクセシビリティに関連しない他のPDF/Aルール（例：透明性、色など）も適用されます。PDF/A規格のこの部分は、古いPDF 1.4仕様に基づいています。提出先がそれを要求する場合や、非常に互換性の高いファイルが必要な場合にのみ使用してください。それ以外の場合は、PDF/UA-1とPDF/Aの第2部と第3部がより良い代替手段を提供します。
PDF/A-2aとPDF/A-3a: PDF/Aの第1部と同様に、これらの規格はアーカイブや長期保存に適したファイルの作成に焦点を当てています。これらの両方の規格は、PDF 1.4ではなく新しいPDFバージョン1.7を対象としています。ここでも、最も厳しい適合レベルAにはアクセシビリティのルールが含まれています。PDF/A-1aのルールに加えて、これらの規格では、意味が普遍的に定義されていないUnicode Private Use Areaの文字の使用が禁止されています。PDF/A-1に対する改善点には、透明性の使用やより良いリフローが可能になることが含まれます。PDF/A規格のこの2つの部のどちらを選ぶかについては、他のファイルを添付する必要がない限り、PDF/A-2aを選択してください。適合レベルAは専用のPDF/UA規格を優先するため、PDF/A-4からは削除されたことに注意してください。

PDFリファレンスページには、サポートされている各規格に関する詳細な情報が含まれています。PDF/UA、PDF/A-2a、またはPDF/A-3aのいずれかを有効にするには、CLIの適切なフラグを使用するか、Webアプリでエクスポートのドロップダウンを使用してPDFをクリックしてください。現時点では、PDF/AとPDF/UAのどちらかを選択する必要があります。アクセシビリティに焦点を当てた文書の場合は、後者をおすすめします。

PDFエクスポート用にこれらの規格のいずれかを選択すると、Typstはあなたがそのルールに違反しているかどうかを検出し、違反している場合は説明付きのエラーメッセージを表示してエクスポートを失敗させます。現時点で利用可能な最も厳格なアクセシビリティチェックを行うには、PDF/UA-1を選んでください。タグは、エクスポートする全ての文書に対してアクセシビリティのベースラインを提供するため、正当な理由がない限りタグ付けを無効にしないでください。

ユニバーサルアクセスを構成する要素の中には、自動的なチェックが難しいものがあることにすでにお気づきかもしれません。例えば、Typstは現時点では、色のコントラストが十分かどうか、あるいは設定された自然言語が実際の自然言語と一致しているかどうかを自動的にはチェックしません（ただし、Webアプリを使っている場合はスペルチェックエラーの数が手掛かりになるはずです）。これらの人間的な要素のいくつかをより詳細に扱う国際規格が2つあります。

Web Content Accessibility Guidelines (WCAG): インターネットを支える技術の背後にある大規模な国際コンソーシアムであるW3Cによって策定されたWCAGは、Webサイトをアクセシブルにする方法を示しています。これらのルールは全てTypstのHTML出力に適用可能であり、その多くはTypstのPDF出力にも適用されます。WCAGはそのルールをA、AA、AAAの3つのレベルに分けています。通常の文書はAAを目指すことが推奨されます。ユニバーサルアクセスに高い基準を求めるのであれば、AAAの達成基準も検討できます。ただし、TypstはまだAAA準拠に必要な全てのPDF機能を公開しているわけではありません。例えば、略語の展開をATがアクセスできる方法で定義することなどです。
European Norm EN 301 549: 第9節は、アクセシブルなWebサイトの作成方法を説明し、第10節は、Typstで作成されたPDFを含む非Web文書に適用されるルールを説明しています。この規格は、どのWCAG条項がPDFにも適用されるかを指摘しています。この規格への適合は、EUおよび各国のアクセシビリティ法に準拠するための良い出発点です。

EN 301 549および関連するWCAGの規定に適合するためには、文書がタグ付けされていなければならないことに留意してください。適合を目指すのであれば、それらに含まれる達成基準に関する多くのチェックを自動化するために、PDF/UA-1をエクスポートに使用することを強くおすすめします。

多くの地域には、一定の状況下でアクセシブルなファイルの作成を要求するアクセシビリティ法があります。以下はその一部です。

European Accessibility Act (EAA, EU 2019/882): この規則は、電子書籍、消費者向け銀行サービス、電子商取引サービスなどに適用されます。これらのアプリケーションで配布されるファイルがアクセシブルであることを要求します。
Americans with Disabilities Act (ADA): 米国司法省は、2026年までにADA第II編の下で、公的機関に対してWCAGに準拠したファイルの提供を要求する予定です。同様に、民間組織もADAおよび州法の下でアクセシブルでないデジタルサービスに対して責任を問われる可能性があります。

このガイドの使用は、どちらの規則への準拠に近づくのにも役立ちます。

アクセシビリティのテスト

PDF文書がアクセシブルかどうかをテストするには、自動ツールと手動テストを利用できます。PDF/UAやPDF/Aのような一部の規格は自動ツールだけでチェックできますが、WCAGやその他の規格のいくつかのルールは手動チェックが必要です。自動化可能なチェックの多くは、Tagged PDFが有効になっていればTypstによって自動的に通過します。さらに多くの自動化可能なチェックについては、PDF/UA-1エクスポートを有効にすると、Typstが代わりにそれらを実行します。自動化ツールはアクセシビリティの基準を提供することしかできません。真のユニバーサルアクセスのためには、ATを使って自分で文書を試すのが最善です。

適合性の確認に使える自動チェッカーの一覧は以下の通りです。

veraPDF: このオープンソースツールは、あなたのPDFファイルが、PDF/AおよびPDF/UA規格のうち、そのファイルが適合を宣言している部分に準拠しているかどうかを確認できます。エクスポート時にこれらの規格のいずれかを選択した場合は、このツールを使用してください。失敗はTypstのバグと見なされるため、GitHubで報告してください。
PDF Accessibility Checker (PAC): フリーウェアのPACは、あなたの文書がPDF/UAやWCAGのルールに準拠しているかどうかをチェックします。PDF/UAタブで重大なエラーが表示された場合、これはTypstのバグと見なされるため、GitHubで報告してください。PDF/UAとQualityタブの警告は、バグ、文書の問題、またはいずれでもない可能性があります。わからない場合は、フォーラムやDiscordで確認してください。WCAGタブのエラーと警告は、あなたの文書に問題があることを示しています。
Accessibility Check in Adobe Acrobat Pro: 有償版Adobe Acrobatに搭載されているアクセシビリティチェッカーは、全てのPDF文書について問題がないかを確認します。よく知られた国際規格や業界規格への準拠を確認するのではなく、Adobeは独自のテスト群を作成しています。これらのテストの判定基準が、PDF/UAのような国際規格と矛盾することがあるため、Acrobatの一部のチェックはTypst文書では失敗することが想定されます²。コントラストチェックなどの他のチェックは有用であり、あなたの文書に問題があることを示します。

手動チェックを行う際は、まずチェックリストを使って始めることができます。あなたの組織がアクセシビリティを重視している場合、独自のチェックリストを持っていることがあります。そのようなリストがない場合は、ブレーメン大学（英語）やカナダ政府、米国社会保障局などの大学や政府のリストを試してみることができます。これらのチェックリストは記述の詳しさが異なりますが、全て最も重要な手動チェックをカバーしています。TypstでPDF/UA-1エクスポートを選択していれば、それらに含まれる技術的なチェックの多くはスキップできます。どのチェックリストを使用するか迷った場合は、自分の組織と文化的に近い組織のものを選んでください。

しかしながら、広く流通する文書で最高水準のアクセシビリティを目指すのであれば、ATを用いて文書をチェックすることを検討してください。AT製品やPDFビューアーは多数ありますが、通常は1つの組み合わせをテストするだけで十分です。どれが最適かは、使用しているオペレーティングシステムによって異なります。

Windows: Adobe AcrobatとNVDAでテストしてください。NVDAは無料のオープンソースソフトウェアです。Acrobatの無料版も利用可能です。
macOS: Adobe AcrobatとVoiceOverでテストしてください。VoiceOverはmacOSやその他のAppleプラットフォームに組み込まれているスクリーンリーダーです。
Linux: EvinceまたはOkularとOrcaでテストしてください。これらの3つのツールは全て無料のオープンソースソフトウェアです。ただし、Linuxプラットフォーム全体でのATサポートは、WindowsやmacOSで利用可能なものよりも遅れています。同様に、EvinceやOkularはAcrobatほどアクセシビリティサポートが充実していません。代わりにAcrobatでテストすることを強くおすすめします。

テストを始めたばかりのときは、使っているスクリーンリーダーに対話型のトレーニングプログラムがある場合は、それを完了することを検討してください。スクリーンリーダーに慣れることは、常時スクリーンリーダーを使うユーザーのように文書を体験する助けになります。文書を確認する際は、目の見えるユーザーが利用できるものと同じ情報の全てにアクセスできるようになっていることだけでなく、ナビゲーションしやすいことも確認してください。ユーザーが得る体験は、使用するPDFビューアーとATの組み合わせによって異なります。

エクスポート形式に関する制限事項と留意点

アクセシビリティを意識して文書を設計した場合でも、エクスポート形式の制限を理解しておく必要があります。基本的に、PDFファイルに対するATのサポートは、HTMLのようなほかの形式に比べて実装が難しいものです。PDFは1993年に、印刷文書をコンピューター上で正確に表示するために考案されました。アクセシビリティ機能は2001年のPDF 1.4で初めて追加され、その後PDF 1.5（2003年）とPDF 2.0（2017年）で改善されました。対照的に、HTMLはより豊富なセマンティックモデルと柔軟性を提供するため、ブラウザーにおけるATのサポートは一般にPDFビューアーで可能なものを上回っています。

また、PDFファイルは基本的に静的なものであることも覚えておいてください。このため、インタラクティブなコンテンツやマルチメディア向けに設計されたWCAGやEN 301 549のルールの多くは無視することができます。ただし、インタラクティブ性がないことによって、ユーザーが自分のニーズにあわせて文書のレイアウトを調整することは、かえって難しくなります。

例えば、WCAG達成基準1.4.12（EN 301 549の第10.1.4.12項に明文化されています）は、ユーザーが文字・字間・行間・段落間隔を非常に大きい値まで拡大できなければならないと規定しています。これは、弱視のあるユーザーやディスレクシアのあるユーザーに有益です。この達成基準は、文書をこれらのレイアウトパラメーターで設計することまでは要求していません。その代わりに、この達成基準が求めているのは、ユーザーが文書を読む際にこれらのパラメーターを増やせる仕組みだけです。HTMLファイルでは、ブラウザーがページ上のこれらの間隔パラメーターをユーザー側で上書きできるようにしているため、この達成基準に準拠するには容易です。PDFの場合は、事情がもう少し複雑です。理論上は、Typstはリフロー用に設計されたタグと属性をファイルに追加します。PDFリーダーはリフロー時に、これらのタグで規定されている範囲を超えて間隔を広げられるよう、ユーザーに許可できる可能性があります。しかし実際には、私たちはこの機能を備えたPDFビューアーを把握していません。その代わりに、この達成基準はPDFをHTMLとして再利用し、ブラウザーで開くことで満たすことができます。

実際には、たとえあなたのファイルが技術的には準拠していても、ユーザーがこうした回避策を知っていることを期待することはできません。したがって、ユニバーサルアクセスの最高水準を満たすことを目指すのであれば、PDFとあわせて文書のHTMLバージョンを配布することを検討してください。TypstのHTMLエクスポート（プレビュー中）を直接使用してこのファイルをエクスポートしてください。HTMLエクスポートは視覚的なレイアウトの多くの側面を保持しませんが、セマンティックなHTMLやDigital Publishing ARIAなどの技術を活用してユニバーサルアクセスを提供するファイルを生成します。PDFファイルをHTMLに再利用したものよりも高品質になります。

最後に、PDFはもともと印刷を目的として設計された形式であることを忘れないでください。したがって、あなたの文書を印刷して読むことを選んだユーザーに対して、リンクのようなインタラクティブ機能が利用できるものだと想定してはいけません。

前述の通り、PNGおよびSVGエクスポートで作成されたファイルはアクセシブルではありません。

ドイツ連邦統計局（Statistisches Bundesamt, Destatis）のデータセット。"Bruttostromerzeugung nach Energieträgern in Deutschland ab 1990"。2025年。Data licence Germany – attribution – version 2.0.の下で利用可能です。

例えば脚注を使用する場合、「List」セクションにある「Lbl and LBody must be children of LI」というチェック項目が失敗（不合格）になることが想定されます。