Can some/all core description review checklist items related to casing be automatically tested?

[samreid]

Many core description review checklist items relate to casing of accessibleHelpText, accessibleParagraph etc. I would like to check the feasibility of automating these checks with assertions, to simplify the manual checklist.

[samreid]

During today's developer meeting, @jessegreenberg said it could be possible to distinguish object vs context responses in the a11y view, and there was some agreement that testing casing would be nice.

[samreid]

Running this patch shows a lot of errors in number pairs, even before I exercise the object and context responses:

Details

Subject: [PATCH] Initialize selection with last value, if any, see https://github.com/phetsims/circuit-construction-kit-common/issues/1058
---
Index: perennial-alias/js/browser-and-node/affirm.ts
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/perennial-alias/js/browser-and-node/affirm.ts b/perennial-alias/js/browser-and-node/affirm.ts
--- a/perennial-alias/js/browser-and-node/affirm.ts	(revision ff332d80b9406a11677826e7428f56dc1a4c8ab5)
+++ b/perennial-alias/js/browser-and-node/affirm.ts	(date 1764990225261)
@@ -44,7 +44,7 @@
     affirmationHooks.forEach( hook => hook() );
 
     if ( debuggerMode ) {
-      debugger; // eslint-disable-line no-debugger
+      // debugger; // eslint-disable-line no-debugger
     }
 
     // Check if Error.stackTraceLimit exists and is writable
@@ -56,7 +56,8 @@
       Error.stackTraceLimit = 20;
     }
 
-    throw new Error( affirmPrefix + messages.join( '\n ' ) );
+    // throw new Error( affirmPrefix + messages.join( '\n ' ) );
+    console.log( affirmPrefix + messages.join( '\n ' ) );
   }
 }
 
Index: scenery/js/accessibility/pdom/ParallelDOM.ts
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/scenery/js/accessibility/pdom/ParallelDOM.ts b/scenery/js/accessibility/pdom/ParallelDOM.ts
--- a/scenery/js/accessibility/pdom/ParallelDOM.ts	(revision e061f0cc28be8ee7667878bda53106e48dac2b11)
+++ b/scenery/js/accessibility/pdom/ParallelDOM.ts	(date 1764989786223)
@@ -164,6 +164,7 @@
 import PDOMUtils from './PDOMUtils.js';
 import { PEER_CONTAINER_PARENT } from './PEER_CONTAINER_PARENT.js';
 import { PEER_PRIMARY_SIBLING } from './PEER_PRIMARY_SIBLING.js';
+import { validateAccessibleName, validateAccessibleHelpText, validateAccessibleParagraph, validateAccessibleObjectResponse, validateAccessibleContextResponse } from './PDOMCasingValidation.js';
 
 const INPUT_TAG = PDOMUtils.TAGS.INPUT;
 const P_TAG = PDOMUtils.TAGS.P;
@@ -973,6 +974,12 @@
         accessibleName.lazyLink( this._onPDOMContentChangeListener );
       }
 
+      // Validate casing for English locale
+      const resolved = isTReadOnlyProperty( accessibleName ) ? accessibleName.value : accessibleName;
+      if ( resolved !== null ) {
+        validateAccessibleName( resolved );
+      }
+
       this._accessibleNameDirty = true;
 
       this.onPDOMContentChange();
@@ -1016,6 +1023,12 @@
 
       this._accessibleParagraph = accessibleParagraph;
 
+      // Validate casing for English locale
+      const resolved = isTReadOnlyProperty( accessibleParagraph ) ? accessibleParagraph.value : accessibleParagraph;
+      if ( resolved !== null ) {
+        validateAccessibleParagraph( resolved );
+      }
+
       // Run the behavior function for accessible paragraph. If the returned options only changes
       // the accessibleParagraphContent, then we can optimize by only setting the content directly.
       // Otherwise, we assume that a full PDOM update is needed.
@@ -1147,6 +1160,12 @@
         accessibleHelpText.lazyLink( this._onPDOMContentChangeListener );
       }
 
+      // Validate casing for English locale
+      const resolved = isTReadOnlyProperty( accessibleHelpText ) ? accessibleHelpText.value : accessibleHelpText;
+      if ( resolved !== null ) {
+        validateAccessibleHelpText( resolved );
+      }
+
       this._accessibleHelpTextDirty = true;
 
       this.onPDOMContentChange();
@@ -3312,6 +3331,12 @@
    * @param [providedOptions]
    */
   public addAccessibleObjectResponse( alertable: TAlertable, providedOptions?: DescriptionResponseOptions ): void {
+
+    // Validate casing for English locale
+    if ( typeof alertable === 'string' ) {
+      validateAccessibleObjectResponse( alertable );
+    }
+
     this.addAccessibleResponse( alertable, providedOptions );
   }
 
@@ -3323,6 +3348,12 @@
    * @param [providedOptions]
    */
   public addAccessibleContextResponse( alertable: TAlertable, providedOptions?: DescriptionResponseOptions ): void {
+
+    // Validate casing for English locale
+    if ( typeof alertable === 'string' ) {
+      validateAccessibleContextResponse( alertable );
+    }
+
     this.addAccessibleResponse( alertable, providedOptions );
   }
 
Index: scenery/js/accessibility/pdom/PDOMCasingValidation.ts
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/scenery/js/accessibility/pdom/PDOMCasingValidation.ts b/scenery/js/accessibility/pdom/PDOMCasingValidation.ts
new file mode 100644
--- /dev/null	(date 1764990053739)
+++ b/scenery/js/accessibility/pdom/PDOMCasingValidation.ts	(date 1764990053739)
@@ -0,0 +1,147 @@
+// Copyright 2025, University of Colorado Boulder
+
+/**
+ * Validation utilities for accessible string casing conventions based on the
+ * Core Description Review Checklist.
+ *
+ * Casing rules:
+ * - accessibleName: Title Case, no punctuation
+ * - accessibleHelpText: Sentence case, with punctuation
+ * - accessibleObjectResponse: No sentence case required, no period at end
+ * - accessibleContextResponse: Sentence case, with punctuation
+ * - accessibleParagraph: Sentence case, full sentences with punctuation
+ *
+ * @author Sam Reid (PhET Interactive Simulations)
+ */
+
+import affirm, { isAffirmEnabled } from '../../../../perennial-alias/js/browser-and-node/affirm.js';
+import stripEmbeddingMarks from '../../../../phet-core/js/stripEmbeddingMarks.js';
+import scenery from '../../scenery.js';
+
+// Opt-out set - strings that are allowed to violate casing rules
+const casingOptOuts = new Set<string>();
+
+/**
+ * Add a string to the opt-out list. Call this from sim main files
+ * for strings that legitimately violate casing rules.
+ */
+export function addCasingOptOut( str: string ): void {
+  casingOptOuts.add( str );
+}
+
+/**
+ * Returns true if the current locale is English (casing rules only apply to English)
+ */
+function isEnglishLocale(): boolean {
+  // phet.chipper.locale is the global locale string like 'en', 'en_US', 'es', etc.
+  const locale = phet?.chipper?.locale;
+  return typeof locale === 'string' && locale.startsWith( 'en' );
+}
+
+/**
+ * Check if first letter is uppercase (ignoring leading numbers/symbols and embedding marks)
+ */
+function startsWithUppercase( str: string ): boolean {
+  const cleaned = stripEmbeddingMarks( str );
+  const match = cleaned.match( /[a-zA-Z]/ );
+  return match !== null && match[ 0 ] === match[ 0 ].toUpperCase();
+}
+
+/**
+ * Check if string ends with sentence-ending punctuation (after stripping embedding marks)
+ */
+function endsWithPunctuation( str: string ): boolean {
+  const cleaned = stripEmbeddingMarks( str ).trim();
+  return /[.!?]$/.test( cleaned );
+}
+
+// Title case small words that can be lowercase (except when first word)
+const TITLE_CASE_SMALL_WORDS = new Set( [
+  'a', 'an', 'the', 'and', 'but', 'or', 'for', 'nor',
+  'on', 'at', 'to', 'by', 'of', 'in', 'with'
+] );
+
+/**
+ * Validate accessibleName: Title Case, no punctuation
+ */
+export function validateAccessibleName( str: string ): void {
+  if ( !isAffirmEnabled() || !isEnglishLocale() || !str || casingOptOuts.has( str ) ) { return; }
+
+  const cleaned = stripEmbeddingMarks( str );
+
+  // Should not end with punctuation
+  affirm( !/[.!?]$/.test( cleaned.trim() ),
+    `accessibleName should not end with punctuation: "${str}"` );
+
+  // Check title case (first word uppercase, other words uppercase unless small)
+  const words = cleaned.split( /\s+/ );
+  words.forEach( ( word, i ) => {
+    const firstLetter = word.match( /[a-zA-Z]/ );
+    if ( firstLetter ) {
+      const isSmallWord = TITLE_CASE_SMALL_WORDS.has( word.toLowerCase() );
+      const shouldBeUpper = i === 0 || !isSmallWord;
+      if ( shouldBeUpper ) {
+        affirm( firstLetter[ 0 ] === firstLetter[ 0 ].toUpperCase(),
+          `accessibleName should be Title Case: "${str}" (word "${word}" should start uppercase)` );
+      }
+    }
+  } );
+}
+
+/**
+ * Validate accessibleHelpText: Sentence case, with punctuation
+ */
+export function validateAccessibleHelpText( str: string ): void {
+  if ( !isAffirmEnabled() || !isEnglishLocale() || !str || casingOptOuts.has( str ) ) { return; }
+
+  affirm( startsWithUppercase( str ),
+    `accessibleHelpText should start with uppercase: "${str}"` );
+  affirm( endsWithPunctuation( str ),
+    `accessibleHelpText should end with punctuation: "${str}"` );
+}
+
+/**
+ * Validate accessibleObjectResponse: No sentence case required, no period at end
+ */
+export function validateAccessibleObjectResponse( str: string ): void {
+  if ( !isAffirmEnabled() || !isEnglishLocale() || !str || casingOptOuts.has( str ) ) { return; }
+
+  const cleaned = stripEmbeddingMarks( str ).trim();
+
+  // Should NOT end with a period (can end with ! or ?)
+  affirm( !cleaned.endsWith( '.' ),
+    `accessibleObjectResponse should not end with period: "${str}"` );
+}
+
+/**
+ * Validate accessibleContextResponse: Sentence case, with punctuation
+ */
+export function validateAccessibleContextResponse( str: string ): void {
+  if ( !isAffirmEnabled() || !isEnglishLocale() || !str || casingOptOuts.has( str ) ) { return; }
+
+  affirm( startsWithUppercase( str ),
+    `accessibleContextResponse should start with uppercase: "${str}"` );
+  affirm( endsWithPunctuation( str ),
+    `accessibleContextResponse should end with punctuation: "${str}"` );
+}
+
+/**
+ * Validate accessibleParagraph: Sentence case, full sentences
+ */
+export function validateAccessibleParagraph( str: string ): void {
+  if ( !isAffirmEnabled() || !isEnglishLocale() || !str || casingOptOuts.has( str ) ) { return; }
+
+  affirm( startsWithUppercase( str ),
+    `accessibleParagraph should start with uppercase: "${str}"` );
+  affirm( endsWithPunctuation( str ),
+    `accessibleParagraph should end with punctuation: "${str}"` );
+}
+
+scenery.register( 'PDOMCasingValidation', {
+  addCasingOptOut: addCasingOptOut,
+  validateAccessibleName: validateAccessibleName,
+  validateAccessibleHelpText: validateAccessibleHelpText,
+  validateAccessibleObjectResponse: validateAccessibleObjectResponse,
+  validateAccessibleContextResponse: validateAccessibleContextResponse,
+  validateAccessibleParagraph: validateAccessibleParagraph
+} );

The errors are like this:

• accessibleName should not end with punctuation: "Welcome to Number Pairs. It has 5 interactive screens that you can explore. Choose a screen to start exploring."
• accessibleName should be Title Case: "Welcome to Number Pairs. It has 5 interactive screens that you can explore. Choose a screen to start exploring." (word "has" should start uppercase)
• accessibleParagraph should start with uppercase: "three can be decomposed into two and one"
• accessibleParagraph should end with punctuation: "three can be decomposed into two and one"
• accessibleName should be Title Case: "No item selected" (word "item" should start uppercase)
• accessibleName should be Title Case: "No item selected" (word "selected" should start uppercase)
• accessibleParagraph should start with uppercase: "three can be decomposed into two and one"
• accessibleParagraph should end with punctuation: "three can be decomposed into two and one"
• accessibleParagraph should end with punctuation: "Right now, equation shows 3 = 2 + 1"
• accessibleName should be Title Case: "Count On, Switch to Count from Zero" (word "from" should start uppercase)
• accessibleName should be Title Case: "Count On, Switch to Count from Zero" (word "from" should start uppercase)
• accessibleName should be Title Case: "No item selected" (word "item" should start uppercase)
• accessibleName should be Title Case: "No item selected" (word "selected" should start uppercase)
• accessibleParagraph should start with uppercase: "eleven can be decomposed into ten and one"
• accessibleParagraph should end with punctuation: "Right now, equation shows 11 = 10 + 1"
• accessibleName should be Title Case: "No item selected" (word "item" should start uppercase)
• accessibleParagraph should start with uppercase: "two plus one equals some number"
• accessibleParagraph should end with punctuation: "two plus one equals some number"
• accessibleParagraph should end with punctuation: "Right now, equation shows 2 + 1 = a mystery total"
• accessibleName should be Title Case: "Level 1: Missing addend in a number bond (2-10)" (word "addend" should start uppercase)
• accessibleName should be Title Case: "Level 8, 0 stars" (word "stars" should start uppercase)
• accessibleHelpText should end with punctuation: "Create groups of 5 Kittens"
• accessibleParagraph should end with punctuation: "Right now, equation shows 1 + a mystery number = 7"

@jessegreenberg @terracoda @catherinecarter @arouinfar can we discuss if there is a way forward here?

[samreid]

Let's also check with @brettfiedler since he committed that section of the core description review checklist.

[samreid]

Also co-assigning @marlitas since I saw this note in the previous developer meeting:

Proposal - Find out from designers if we could reasonably add an affirmation to check the casing of the two types? MS will check in with designers on this.

[jessegreenberg]

Thanks for looking into this!

First, I think we should make sure that this is really what the team wants. This will reduce flixebility and add cost. In my opinion, this is not a meaningful improvement for our users. Guidelines for this are helpful, but enforcing it is too restrictive.

However, if the team agrees it is important, enforcing programmatically is the way to go. I think we should discuss this at next core description meeting.

Here is an example of how this would be too restrictive:
In membrane-transport, we enjoyed combining the "object response" and "name response" into the accessibleName for the grabbed protein because it sounded best with other context responses, worked best in the implementation, and integrated best with Voicing. I wouldn't want to disallow this or change its punctuation just because it is assigned to an accessibleName.

accessibleName: 'Slot 3 of 7, above empty slot'

EDIT: I added it to the agenda for our next meeting.

[marlitas]

I asked the question to designers in the Core Description channel: https://phetsims.slack.com/archives/C08BYFR1JTG/p1765304369519389