Merge pull request #411 from freee/develop

Release Ver. 202510.0 (production)

Author: shikakun

CLAUDE.md

@@ -0,0 +1,218 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the **freee Accessibility Guidelines** repository - a comprehensive documentation project for web and mobile accessibility guidelines. The project generates multi-language (Japanese/English) HTML documentation using Sphinx, with content sourced from YAML files and converted to reStructuredText.
+
+**Main branch:** `develop`
+
+**Published documentation:** https://a11y-guidelines.freee.co.jp/
+
+## Core Architecture
+
+### Build System
+
+The project uses a **two-stage build process**:
+
+1. **YAML → RST conversion** (`yaml2rst` tool)
+   - Converts YAML guideline/check/FAQ data to reStructuredText
+   - Generates category pages, reference tables, and cross-references
+   - Runs before Sphinx build
+
+2. **RST → HTML generation** (Sphinx)
+   - Builds Japanese docs in `ja/` directory
+   - Builds English docs in `en/` directory
+   - Supports both multi-page HTML and single-page HTML output
+
+### Data Structure
+
+```
+data/
+├── json/
+│   ├── guideline-categories.json    # Category definitions
+│   ├── wcag-sc.json                  # WCAG success criteria mapping
+│   ├── faq-tags.json                 # FAQ tag definitions
+│   ├── info.json                     # Reference link definitions
+│   └── schemas/                      # JSON schemas for validation
+│       ├── guideline.json
+│       ├── check.json
+│       └── faq.json
+└── yaml/
+    ├── gl/                           # Guidelines by category
+    ├── checks/                       # Accessibility checks
+    └── faq/                          # FAQ articles
+```
+
+### Custom Python Libraries
+
+**`tools/lib/freee_a11y_gl`** - Core library for accessibility guideline management
+- Models: Category, Guideline, Check, FAQ, WCAG mappings
+- YAML processing and validation
+- Relationship management between entities
+- Multi-language support
+
+**`tools/scripts/yaml2rst`** - RST content generator
+- Template-based content generation using Jinja2
+- Converts YAML data to Sphinx-compatible RST files
+- Generates category pages, indexes, and cross-references
+
+## Common Commands
+
+### Building Documentation
+
+```bash
+# Build both Japanese and English HTML
+make html
+
+# Build specific language
+cd ja && make html
+cd en && make html
+
+# Build single-page HTML (singlehtml)
+make singlehtml
+
+# Clean build artifacts
+make clean
+
+# Check that all include files are referenced
+make check-includes
+```
+
+### Testing and Validation
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+npm install
+
+# Run Python tests (yaml2rst)
+cd tools/scripts/yaml2rst
+python run_tests.py
+python run_tests.py --coverage
+
+# Run Python tests (freee_a11y_gl)
+cd tools/lib/freee_a11y_gl
+python -m pytest tests/
+
+# Validate YAML against JSON schemas
+ajv validate --spec=draft2020 -s data/json/schemas/guideline.json -r data/json/schemas/common.json -d data/yaml/gl/form/label.yaml
+
+# Lint reStructuredText files
+sphinx-lint --enable all --disable line-too-long ja/**/*.rst
+
+# Lint Japanese text (textlint)
+npx textlint ja/source/**/*.rst
+
+# Code quality (Python)
+black tools/
+isort tools/
+flake8 tools/
+mypy tools/
+```
+
+### Development Workflow
+
+The build process for each language (ja/en) follows:
+
+1. `yaml2rst` generates RST files from YAML data into `source/inc/` and `source/faq/`
+2. `incfiles.mk` tracks dependencies
+3. Sphinx builds HTML from RST sources in `source/` directory
+4. Output goes to `build/html/` (or `build/singlehtml/`)
+
+### Working with Guidelines
+
+Each guideline YAML file structure:
+```yaml
+id: gl-category-name          # Unique ID with gl- prefix
+sortKey: 1901                  # Integer 1001-2199 for ordering
+category: form                 # Category identifier
+title:
+  ja: "日本語タイトル"
+  en: "English Title"
+platform:
+  - web                        # web and/or mobile
+  - mobile
+guideline:
+  ja: "ガイドライン本文"
+  en: "Guideline text"
+sc:                            # WCAG success criteria
+  - 1.1.1
+  - 1.3.1
+intent:
+  ja: "意図の説明"
+  en: "Intent explanation"
+checks:                        # Related check IDs
+  - '0931'
+info:                          # Related info links
+  - exp-form-labeling
+```
+
+### Pre-commit Hooks
+
+The repository uses **Husky + lint-staged** for pre-commit validation:
+- JSON schema validation for YAML files
+- Sphinx linting for RST files
+- Runs automatically on `git commit`
+
+Configuration in `.lintstagedrc.mjs`
+
+## Version Management
+
+Version information is stored in `version.py`:
+- `guidelines_version` - Main version (e.g., 'Ver. 202508.0')
+- `checksheet_version` - Checksheet version
+- `publishedDate` - Publication date
+
+This file is imported by Sphinx configuration to set document version.
+
+## Internationalization
+
+The project supports **Japanese (ja)** and **English (en)**:
+
+- Both languages share the same data structure
+- YAML files contain i18n strings with `ja:` and `en:` keys
+- Template directory symlink: `en/source/_templates → ja/source/_templates`
+- Each language has its own Sphinx `conf.py` with locale settings
+
+## Build Environment Notes
+
+- **Locale required:** `ja_JP.UTF-8` must be installed for Japanese date formatting
+- **Python version:** 3.9+ (see requirements)
+- **Sphinx:** ~7.0 (specified in requirements.txt)
+- **Theme:** sphinx_rtd_theme ~3.0
+
+## GitHub Actions
+
+The repository uses reusable workflows for building:
+- `.github/workflows/reusable-build-doc.yml` - Main build workflow
+- Builds for specific tags/versions with configurable Python/Sphinx/theme versions
+- Supports artifact reuse to avoid rebuilding unchanged content
+- Environment variables: `BASE_URL`, `GTM_ID`, build flags
+
+## Common Tasks
+
+**Adding a new guideline:**
+1. Create YAML file in appropriate `data/yaml/gl/{category}/` directory
+2. Follow the guideline schema (see `data/json/schemas/guideline.json`)
+3. Run `make clean` and `make html` to rebuild
+4. Validate with `ajv validate` command
+
+**Modifying templates:**
+1. Templates are in `yaml2rst` package (Jinja2 format)
+2. Export with: `yaml2rst --export-templates`
+3. Customize in `~/.config/freee_a11y_gl/templates/`
+4. Template resolution: custom → user → built-in
+
+**Testing a single component:**
+```bash
+# Test yaml2rst
+cd tools/scripts/yaml2rst
+pytest tests/unit/test_specific.py -v
+
+# Test freee_a11y_gl
+cd tools/lib/freee_a11y_gl
+pytest tests/ -k "test_name"
+```

data/yaml/checks/design/0002.yaml

@@ -8,12 +8,12 @@ check:
   ja: |-
     テキストおよび画像化されたテキストの表示色と背景色には、充分なコントラスト比が確保されている。
 
-    *  文字サイズが29px（22pt）以上の場合：3:1以上
-    *  文字サイズが24px（18pt）以上で太字の場合：3:1以上
+    *  文字サイズが24px（18pt）以上の場合：3:1以上
+    *  文字サイズが19px（14pt）以上で太字の場合：3:1以上
     *  その他の場合：4.5:1以上
   en: |-
     Sufficient contrast ratios are ensured for the display colors and background colors of text and images of text.
 
-    *  For text size 29px (22pt) or larger: at least 3:1
-    *  For bold text size 24px (18pt) or larger: at least 3:1
+    *  For text size 24px (18pt) or larger: at least 3:1
+    *  For bold text size 19px (14pt) or larger: at least 3:1
     *  In other cases: at least 4.5:1

data/yaml/checks/design/1141.yaml

@@ -8,8 +8,12 @@ platform:
 check:
   ja: |-
     法的行為、経済的取引、データの変更や削除を生じる機能については、取り消し、送信前の確認・修正、または送信時のエラー・チェックと修正が可能な設計になっている。
+
+    ここで「データの変更や削除」とは、ユーザーが簡単な操作により元の状態を完全に復元できないものを指す。簡単な操作とは、ボタン操作や、少しの文字入力などである。
   en: |-
     For functions that involve legal actions, financial transactions, or the modification and deletion of data, the design allows for cancellation, pre-submission confirmation and modification, or error checking and correction at the time of submission.
+
+    Here, "modification and deletion of data" refers to cases where users cannot fully restore the original state through simple operations. Simple operations include button clicks or minimal text input.
 conditions:
 - platform: web
   type: or
@@ -20,8 +24,12 @@ conditions:
     procedure:
       ja: |-
         チェック対象の画面には、法的行為、経済的取引、データの変更や削除を生じる機能が存在しない。
+
+        ここで「データの変更や削除」とは、ユーザーが簡単な操作により元の状態を完全に復元できないものを指す。簡単な操作とは、ボタン操作や、少しの文字入力などである。
       en: |-
         There are no functions that involve legal actions, financial transactions, or the modification and deletion of data on the screen to be checked.
+
+        Here, "modification and deletion of data" refers to cases where users cannot fully restore the original state through simple operations. Simple operations include button clicks or minimal text input.
   - type: simple
     id: 1141-content-01
     tool: misc

data/yaml/checks/product/0021.yaml

@@ -27,10 +27,6 @@ conditions:
         ただし、ガイドラインを満たしていない状態であっても、以下の場合は問題として表示されませんので注意が必要です。
 
         *  マウスオーバーなどで背景色やテキスト色が変化する場合の、変化後のコントラスト比が不足する場合
-        *  大きいテキストのコントラスト比が3:1以上4.5:1未満の場合
-
-           -  freeeの場合日本語テキストを想定しているため、「大きいテキスト」を29px（22pt）以上または24px（18pt）以上の太字としているが、WCAGでは欧文テキストを想定して18pt以上または14pt以上の太字としているため、18pt以上22pt未満（太字の場合は14pt以上18pt未満）の日本語のテキストについて、Axe DevToolsはコントラスト不足を検知できない
-
         *  テキスト以外のコントラスト比が不足している場合
 
            -  アイコン、画像、画像化されたテキスト、ボタンや入力フィールドの枠線など
@@ -41,10 +37,6 @@ conditions:
         Note that no issue is reported in the following cases, even when the guidelines are not met.
 
         *  When the contrast ratio is insufficient after the text and/or background color change, e.g. after mouse hover
-        *  When the contrast ratio of large-scale text is 3:1 or more and less than 4.5:1
-
-           -  While large-scale text is defined as 29px(22pt) or larger font, or 24px(18pt) or larger bold font within freee's product as the primary text is assumed to be in Japanese, WCAG defines it as 18pt or larger font, or 14pt or larger bold font assuming euro-languages.  As Axe DevTools is based on the requirements set by the WCAG, it cannot detect insufficient color contrast of Japanese text whose font size is between 18pt and 22pt (14pt and 18pt if bold).
-
         *  When the contrast ratio of non-text content is insufficient.
 
            -  icons, images, images of text, outlines of buttons and input fields, etc.
@@ -58,12 +50,12 @@ conditions:
       ja: |-
         WebAIM Contrast Checkerで、以下の基準を満たしていることを確認した：
 
-        *  文字サイズが29px（22pt）以上の場合：3:1以上
-        *  文字サイズが24px（18pt）以上で太字の場合：3:1以上
+        *  文字サイズが24px（18pt）以上の場合：3:1以上
+        *  文字サイズが19px（14pt）以上で太字の場合：3:1以上
         *  その他の場合：4.5:1以上
       en: |-
         Verified that the content meets the following color contrast requirement using the WebAIM Color Contrast Checker:
 
-        *  Font Size: 29px（22pt）or larger; 3:1 or higher
-        *  Font Size: 24px（18pt）or larger and bold; 3:1 or higher
+        *  Font Size: 24px (18pt) or larger; 3:1 or higher
+        *  Font Size: 19px (14pt) or larger and bold; 3:1 or higher
         *  In other cases：4.5:1 or higher

data/yaml/checks/product/0441.yaml

@@ -33,9 +33,9 @@ conditions:
       id: "0441-content-00"
       procedure:
         ja: |-
-          チェック対象の画面に存在する画像は、装飾目的のもののみである。
+          チェック対象の画面に画像が存在しない、または装飾目的のもののみである。
         en: |-
-          The images on the target screen are only for decorative purposes.
+          There are no images on the target screen, or the images are only for decorative purposes.
     - type: and
       conditions:  
       - type: or

data/yaml/gl/form/errors-cancel.yaml

@@ -10,15 +10,23 @@ platform:
 guideline:
   ja: |-
     法的行為、経済的取引、データの変更や削除を生じる機能については、取り消し、送信前の確認・修正、または送信時のエラー・チェックと修正を可能にする。
+
+    ここで「データの変更や削除」とは、ユーザーが簡単な操作により元の状態を完全に復元できないものを指す。簡単な操作とは、ボタン操作や、少しの文字入力などである。
   en: |-
     For functions involving legal commitments, financial transactions, or the alteration or deletion of data, enable cancellation, pre-submission confirmation and modification, or error checking and correction at the time of submission.
+
+    Here, "alteration or deletion of data" refers to cases where users cannot fully restore the original state through simple operations. Simple operations include button clicks or minimal text input.
 sc:
 - 3.3.4
 intent:
   ja: |-
     誤操作による影響を少なくする。
+
+    データの変更や削除については、ユーザーが簡単な操作で完全に復元できない場合に確認などが必要となる。これは、操作にかかる時間は人によって異なるため、時間ではなく操作の簡易性と手数で判断する。
   en: |-
     Minimize the impact of misoperation.
+
+    For data alteration or deletion, confirmation is required when users cannot fully restore the original state through simple operations. This criterion is based on the simplicity and number of operations rather than time, as the time required for operations varies from person to person.
 checks:
 - '1141'
 info:

data/yaml/gl/image/mobile-text-contrast.yaml

@@ -14,21 +14,21 @@ guideline:
     -  テキストの文字サイズが19px（14pt）以上で太字の場合：3:1以上
     -  その他の場合： 4.5:1以上
 
-    注：モバイル・アプリケーションにおいては、デスクトップのWebと比較して文字サイズの変更方法が広く知られていると推測されること、各プラットフォームのガイドライン [#]_ [#]_ においてもWCAG 2.1に準じた基準を用いていることから、上記の基準としています。
+    参考：
 
-    .. [#] `アクセシビリティ | Apple Developer Documentation <https://developer.apple.com/jp/design/human-interface-guidelines/accessibility>`__
-    .. [#] `Accessibility – Material Design 3 <https://m3.material.io/foundations/accessible-design/patterns#f72f3851-5184-4132-b871-bc8224e062e2>`__
+    -  `アクセシビリティ | Apple Developer Documentation <https://developer.apple.com/jp/design/human-interface-guidelines/accessibility>`__
+    -  `Accessibility – Material Design 3 <https://m3.material.io/foundations/accessible-design/patterns#f72f3851-5184-4132-b871-bc8224e062e2>`__
   en: |-
     Ensure sufficient contrast between the colors of text within images and key visual elements conveying important information, and their background colors.
 
     -  For text size 24px (18pt) or larger: a contrast ratio of at least 3:1.
     -  For bold text 19px (14pt) or larger: a contrast ratio of at least 3:1.
     -  In other cases: a contrast ratio of at least 4.5:1.
 
-    Note: In mobile applications, it is assumed that methods for changing text size are more widely known compared to desktop web, and the guidelines of each platform [#]_ [#]_ also use standards in line with WCAG 2.1, hence the above criteria are set.
+    References:
 
-    .. [#] `Accessibility | Apple Developer Documentation <https://developer.apple.com/design/human-interface-guidelines/accessibility>`__
-    .. [#] `Accessibility – Material Design 3 <https://m3.material.io/foundations/accessible-design/patterns#f72f3851-5184-4132-b871-bc8224e062e2>`__
+    -  `Accessibility | Apple Developer Documentation <https://developer.apple.com/design/human-interface-guidelines/accessibility>`__
+    -  `Accessibility – Material Design 3 <https://m3.material.io/foundations/accessible-design/patterns#f72f3851-5184-4132-b871-bc8224e062e2>`__
 sc:
 - 1.4.3
 - 1.4.6

data/yaml/gl/image/text-contrast.yaml

@@ -10,25 +10,19 @@ guideline:
   ja: |-
     画像内のテキストや、重要な情報を伝える視覚的要素の色と背景の色に、十分なコントラストを確保する。
 
-    -  テキストの文字サイズが29px（22pt）以上の場合： 3:1以上
-    -  テキストの文字サイズが24px（18pt）以上で太字の場合： 3:1以上
+    -  テキストの文字サイズが24px（18pt）以上の場合： 3:1以上
+    -  テキストの文字サイズが19px（14pt）以上で太字の場合： 3:1以上
     -  その他の場合： 4.5:1以上
 
-    注：freeeのプロダクトやWebサイトにおいては、主に日本語が用いられているため、Understanding WCAG 2.1 [#]_ の日本語訳 [#]_ 中の訳注で示されている基準を用いています。
-
-    .. [#] `Understanding Success Criterion 1.4.3: Contrast (Minimum) <https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html>`__
-    .. [#] `達成基準 1.4.3: コントラスト (最低限)を理解する <https://waic.jp/translations/WCAG21/Understanding/contrast-minimum.html>`__
+    参考： `達成基準 1.4.3: コントラスト (最低限)を理解する <https://waic.jp/translations/WCAG21/Understanding/contrast-minimum.html>`__
   en: |-
     Ensure sufficient contrast between the colors of text within images and key visual elements conveying important information, and their background colors.
 
-    -  For text size 29px (22pt) or larger: a contrast ratio of at least 3:1.
-    -  For bold text 24px (18pt) or larger: a contrast ratio of at least 3:1.
+    -  For text size 24px (18pt) or larger: a contrast ratio of at least 3:1.
+    -  For bold text 19px (14pt) or larger: a contrast ratio of at least 3:1.
     -  In other cases: a contrast ratio of at least 4.5:1.
 
-    Note: In freee products and websites, Japanese is mainly used, so the criteria indicated in the translation notes in Understanding WCAG 2.1 [#]_ [#]_  are used.
-
-    .. [#] `Understanding Success Criterion 1.4.3: Contrast (Minimum) <https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html>`__
-    .. [#] `達成基準 1.4.3: コントラスト (最低限)を理解する <https://waic.jp/translations/WCAG21/Understanding/contrast-minimum.html>`__
+    Reference: `Understanding Success Criterion 1.4.3: Contrast (Minimum) <https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html>`__
 sc:
 - 1.4.3
 - 1.4.6