Added the glossary page by G0dwin · Pull Request #53 · act-rules/act-tools

G0dwin · 2026-03-31T15:42:01Z

Adds the tools necessary to generate a glossary page and add it to the nav.

Dependent PR in act-rules to be published shortly.

Note: much of this was generated using Co-pilot, be on the lookout for code that doesn't meet standards.

Because we probably will not be able to preview this until after we merge the packages, I have a preview available on my personal site here.

Related PR: act-rules/act-rules.github.io#2395

daniel-montalvo

Hi @G0dwin .

thanks for putting this together.

I think the act-tools repo should be the place to have this conversation, as this is were the logic lives.

I have a couple of thoughts based on previous work, especially act-rules/act-rules.github.io#2377 and w3c/wcag-act-rules#387

The URIs we settled on for these examples were: /act/rules/terms/accessible-name/examples/

This is because on the WAI website we have the pattern that every URI needs to be meaningful in itself.

If we include this work as-is, we would leave /act/rules/terms/ with no meaningful content, and we would be adding yet another pattern /act/rules/glossary/ which wouldn't meet user expectations.

I propose we rename /act-rules/glossary/ to /act/rules/terms/, just to avoid having two patterns repeated throughout.

In addition, I'd request review from @remibetin because these code updates are intended to push content to the WAI website, so he needs to be aware as the WAI website maintainer.

G0dwin · 2026-04-06T15:26:20Z

Hi @G0dwin .

thanks for putting this together.

I think the act-tools repo should be the place to have this conversation, as this is were the logic lives.

I have a couple of thoughts based on previous work, especially act-rules/act-rules.github.io#2377 and w3c/wcag-act-rules#387

The URIs we settled on for these examples were: /act/rules/terms/accessible-name/examples/

This is because on the WAI website we have the pattern that every URI needs to be meaningful in itself.

If we include this work as-is, we would leave /act/rules/terms/ with no meaningful content, and we would be adding yet another pattern /act/rules/glossary/ which wouldn't meet user expectations.

I propose we rename /act-rules/glossary/ to /act/rules/terms/, just to avoid having two patterns repeated throughout.

In addition, I'd request review from @remibetin because these code updates are intended to push content to the WAI website, so he needs to be aware as the WAI website maintainer.

Thanks Daniel, I updated the URL and committed the change. You can preview it here.

remibetin · 2026-04-14T13:37:26Z

Thanks @daniel-montalvo and @G0dwin. I'll review the use of the WAI theme, and I've asked @kfranqueiro if he could review the Typescript updates. We plan to coordinate next week on this.

remibetin

Hi @G0dwin,

Thanks for your work on this. I've started the review and added some suggestions and questions.

To help with the review, I'm interested in more information on who the glossary page is intended for, and examples of use cases. AFAIK, each rule already includes a list of glossary terms with their definition. Will there be links to the glossary page somewhere else?

I also think the scope and purpose of the glossary page is important to convey to the end-users. For example, users may wonder how this relates to section 4.12 Glossary of ACT Rules Format 1.1. To that end, I suggest adding a "Summary" box at the top that provide this information. I can help refine the wording.

cc @daniel-montalvo @kfranqueiro

remibetin · 2026-04-21T10:08:45Z

+    lines.push("### Used in rules");
+
+    const rules = [...(usedInRules.get(key) || new Set())].sort((a, b) =>
+      a.id.localeCompare(b.id),
+    );
+    if (rules.length === 0) {
+      lines.push("- None");
+    } else {
+      rules.forEach((rule) => {
+        lines.push(
+          `- [${rule.name}](/standards-guidelines/act/rules/${rule.id}/proposed/)`,
+        );
+      });
+    }


The "Used in Rules" list can become quite big and require a lot of scrolling from users. For example, the list for the "Outcome" term consists of 94 items.

Before considering possible solutions, could you clarify who this section is intended for?

I agree, this adds a large amount of visual space. I think embedding this content in summary and details elements is probably the best solution but I that would be assuming use cases myself. This came from the issue requirements:

In scope: New glossary index (and/or per-term pages), navigation entry, working anchors and links on WAI, “used in rules” lists with correct WAI rule URLs, full definition bodies as above.

I think it may also be a good option to move forward with the page as it is and adjust this later if it holds us up.

@WilcoFiers , do you have any context or suggestions to add here?

Hi.

I am not even sure if we should have this "used in rules" at all.

I think the primary use case for a dedicated (self-contained) terms page is for rule authors to know whether or not something is or is not currently defined by ACT.

If you want to know which rules use which terms, you could get to the specific rule pages and see the terms at the bottom. I see this as a secondary need that is not worth the extra clutter.

If folks think strongly about keeping this, then I would support the details/summary alternative, but that should be done in alignment with how the expand/collapse single and expand/collapse multiple currently work on the wai website theme

I think we should keep this section. Yeah it's more for rule authors than other people, but this page is mostly for rule authors anyway. I'm okay with using a details / summary thing here.

I second (or third?) keeping the "used in rules" section. It is a common use case for me to search all rules using a given definition, typically to assess which rules will be impacted by changes in the definition. I'm currently doing that somewhat manually through grep, which is not perfect due to transitive definition inclusion, … (and going through all rules pages is not a real possibility).

A details/summary is perfect for that, indeed.

(for a recent case: searching all rules that use "marked as decorative" to evaluate impact of "whitespace alt is decorative")

Co-authored-by: Rémi Bétin <github@remibetin.fr>

WilcoFiers

Looks good. Couple nitpicks.

WilcoFiers · 2026-04-29T12:44:53Z

Would you mind adding some tests for this?

Tests for src/utils/glossary.ts were added in commit 6aa3ade, covering getGlossaryHeading, normalizeHeadingLevels, and getGlossaryBody (both rule and full modes).

WilcoFiers · 2026-04-29T12:50:57Z

+export const getFullGlossary = (glossary: DefinitionPage[]): string => {
+  const glossaryTexts = glossary.map(getFullGlossaryMarkdown);
+  return joinStrings(`## Glossary`, ...glossaryTexts);
+};


Are getFullGlossary and getFullGlossaryMarkdown just for testing? Seems unnecessary if that's the case. If we want to test the mode of getGlossaryBody we should test that function directly.

Great catch, I'll remove it.

getFullGlossary and getFullGlossaryMarkdown were removed in commit 6aa3ade.

G0dwin · 2026-04-30T22:47:05Z

@copilot resolve the merge conflicts in this pull request

Co-authored-by: G0dwin <1109252+G0dwin@users.noreply.github.com>

Copilot · 2026-04-30T22:50:16Z

@copilot resolve the merge conflicts in this pull request

Resolved the merge conflict with origin/main in commit 0b17c67. The conflict was in yarn.lock due to the pre-commit → @fastify/pre-commit change on main. The lockfile was regenerated and all 270 tests pass.

Ready for another review

remibetin · 2026-06-04T15:09:52Z

Following today's ACT Task Force meeting, I'm providing an example where the definition of a term differs between the approved version of a rule and the proposed version.

The exception in the definition of "focusable" was updated on November 2024. See act-rules/act-rules.github.io@f9eace3

The term is used in numerous rules, including “Text has enhanced contrast”.

The proposed version of this rule, last updated on January 2026, uses the new definition.

The approved version of this rule, last updated on August 2023, uses the previous definition.

I haven't checked if some approved rules use the new definition.

Added the glossary page

69f4051

G0dwin mentioned this pull request Mar 31, 2026

Added the glossary page act-rules/act-rules.github.io#2395

Open

G0dwin self-assigned this Mar 31, 2026

G0dwin requested review from Jym77, WilcoFiers and daniel-montalvo March 31, 2026 15:43

Fixed an issue with the Glossary nav link

d8787e6

daniel-montalvo previously requested changes Apr 3, 2026

View reviewed changes

Updated URL

31cfb5a

Reused code between get-glossary and generate-glossary

1f3b836

remibetin suggested changes Apr 28, 2026

View reviewed changes

G0dwin and others added 5 commits April 28, 2026 15:13

Update src/cli/generate-glossary.ts

d6387cc

Co-authored-by: Rémi Bétin <github@remibetin.fr>

Update src/cli/generate-glossary.ts

91f0816

Co-authored-by: Rémi Bétin <github@remibetin.fr>

Update src/cli/generate-glossary.ts

82f624f

Co-authored-by: Rémi Bétin <github@remibetin.fr>

Update src/cli/generate-glossary.ts

61dea9c

Co-authored-by: Rémi Bétin <github@remibetin.fr>

Update src/cli/generate-glossary.ts

037816c

Co-authored-by: Rémi Bétin <github@remibetin.fr>

WilcoFiers requested changes Apr 29, 2026

View reviewed changes

Removed unused function and added tests

6aa3ade

Copilot started work on behalf of G0dwin April 30, 2026 22:47 View session

Merge origin/main into feature/glossary - resolve yarn.lock conflict

0b17c67

Co-authored-by: G0dwin <1109252+G0dwin@users.noreply.github.com>

Copilot finished work on behalf of G0dwin April 30, 2026 22:51

WilcoFiers approved these changes May 7, 2026

View reviewed changes

WilcoFiers requested a review from daniel-montalvo May 7, 2026 14:33

Conversation

G0dwin commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

daniel-montalvo left a comment

Choose a reason for hiding this comment

Uh oh!

G0dwin commented Apr 6, 2026

Uh oh!

remibetin commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

remibetin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

WilcoFiers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

G0dwin commented Apr 30, 2026

Uh oh!

Copilot AI commented Apr 30, 2026

Uh oh!

remibetin commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

G0dwin commented Mar 31, 2026 •

edited

Loading

remibetin commented Apr 14, 2026 •

edited

Loading

remibetin commented Jun 4, 2026 •

edited

Loading