docs(tokens): comment sweep

Kept: the module contracts, the RESOLVED_BY_HAND source quotes, the
document-convention notes (brace inheritance, ellipsis stems, section
overlap dedup), and the branch-policy traps (exact-before-manual, prose-
mixed cells). Removed: a signature paraphrase, two notes duplicating the
module docs or per-entry reasons, and a CI step comment restating the step
name. Rewritten: the kebab docstring down to its invariant, a false claim
about apps/docs handling, and the two workflow trigger notes unified.

Author: librowski

.github/workflows/pr-check-docs.yml

@@ -16,7 +16,7 @@ on:
       # branches filter matches the base. Remove after the stack lands.
       - token-usage-guard
       - 'ds2-**'
-      # DS 2.0 integration branch — same feedback as PRs to main.
+      # Long-lived DS 2.0 integration branch; merges into main at the end.
       - ds-2.0
     paths:
       - 'apps/docs/**'

.github/workflows/pr-check.yml

@@ -16,8 +16,7 @@ on:
       # branches filter matches the base. Remove after the stack lands.
       - token-usage-guard
       - 'ds2-**'
-      # DS 2.0 integration branch — PRs targeting it need the same feedback
-      # as PRs to main (it all merges into main at the end of the migration).
+      # Long-lived DS 2.0 integration branch; merges into main at the end.
       - ds-2.0
 
 permissions:
@@ -158,8 +157,6 @@ jobs:
         run: pnpm lint:styles
 
       - name: Codemod map reproducibility
-        # codemod-map.json is a committed artifact; it must match what its
-        # generator produces from the checked-in designer changelog.
         run: |
           pnpm --filter @workflowbuilder/ui-tokens codemod:map
           git diff --exit-code -- packages/tokens/codemod-map.json

packages/tokens/scripts/build-codemod-map.mjs

@@ -114,7 +114,6 @@ function toCss(figmaName, prefix) {
 const oldCss = (name) => toCss(name, '--ax-');
 const newCss = (name) => toCss(name, '--wb-');
 
-/** Splits a markdown table row into trimmed cells. */
 function cells(row) {
   return row
     .replace(/^\|/, '')
@@ -192,8 +191,6 @@ for (const line of lines) {
   const [oldCell, newCell] = cells(line);
   if (oldCell === undefined || newCell === undefined) continue;
 
-  // A fully-written brace list becomes the inheritance context for `{…}`
-  // rows below it in the same table.
   const fullBrace = oldCell.match(/\{([^}…]+)\}/);
   if (fullBrace && fullBrace[1].includes(',')) {
     lastBraceList = fullBrace[1].split(',').map((part) => part.trim());
@@ -261,8 +258,6 @@ for (const line of lines) {
       removed.push(removedEntry(oldName, null, context));
     }
   } else {
-    // More candidates than a positional or clean-consolidation match allows
-    // — prose-mixed cell; do not guess.
     unparsed.push({ section, row: line.trim() });
   }
 }
@@ -283,7 +278,6 @@ const map = {
   // Primitives keep their names 1:1 under the new namespace; validated
   // against the real 2.0 export by the manifest when it lands.
   prefixRules: [{ oldCssPrefix: '--ax-colors-', newCssPrefix: '--wb-colors-' }],
-  // Not expressible as 1:1 renames — handled inside their component tasks:
   manual: [
     {
       pattern: '--ax-chips-*',

packages/tokens/scripts/codemod-usages.mjs

@@ -12,9 +12,8 @@
  * names that exist in today's token dist (a real gap that will dangle after
  * the pipeline switch) and component-local names that need no rewrite.
  *
- * Dry-run by default; pass --write to modify files. apps/docs is excluded
- * (not part of the shipped packages; its one usage is handled in the docs
- * workflow separately).
+ * Dry-run by default; pass --write to modify files. apps/docs is excluded —
+ * it is not part of the shipped packages.
  *
  * Usage: node scripts/codemod-usages.mjs [--write]
  */

packages/tokens/src/validate-collisions.ts

@@ -34,9 +34,8 @@ function collectLeaves(node: TokenNode, path: string[], out: { path: string; val
   }
 }
 
-/** The emitted CSS name: Style Dictionary's `name/kebab` transform runs
- * change-case's kebabCase over the space-joined token path — use the same
- * function so the two can never drift. */
+/** Must match Style Dictionary's `name/kebab` output — same function
+ * (change-case), same input shape, so the two cannot drift. */
 function toCssName(tokenPath: string): string {
   return `--${kebabCase(tokenPath.split('/').join(' '))}`;
 }