feat(shared): use American English spelling in public APIs and JSDoc

.changeset/american-spelling-jsdoc.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/expo': patch
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+---
+
+Use American English spelling in JSDoc comments, such as "canceled", "toward", and "customize". There are no runtime changes.

.changeset/american-spelling-messages.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': patch
+'@clerk/mosaic': patch
+'@clerk/shared': patch
+'@clerk/electron': patch
+'@clerk/upgrade': patch
+---
+
+Use American English spelling in user-facing text. The `en-US` strings for a canceled Directory Sync run and canceled passkey prompts now read "Canceled" and "canceled", as do the reverification, Electron OAuth, and upgrade CLI messages. Error codes and localization keys are unchanged.

.changeset/american-spelling-reverification-canceled.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': minor
+'@clerk/react': minor
+'@clerk/nextjs': minor
+'@clerk/react-router': minor
+'@clerk/tanstack-react-start': minor
+---
+
+Add `isReverificationCanceledError()`, the American English spelling of `isReverificationCancelledError()`. `isReverificationCancelledError()` still works and is now deprecated; it will be removed in a future major version. The error code it checks for, `reverification_cancelled`, is unchanged.

.claude/skills/clerk-monorepo/SKILL.md

@@ -46,8 +46,8 @@ The ~10 packages people touch most. Full 25-package table, the dependency pyrami
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@clerk/shared`        | Utilities used everywhere (storage, events, React helpers). Most-depended-on; changes fan out to ~20 packages. Types live here too (`@clerk/shared/types`). |
 | `@clerk/backend`       | Server-side: JWT verification, the Backend API REST client, webhooks. Used by every framework adapter.                                                      |
-| `@clerk/clerk-js`      | ⚠️ The browser runtime loaded via script tag. **Backwards-compat sensitive** (see rules).                                                                   |
-| `@clerk/ui`            | ⚠️ The React components powering the hosted sign-in / sign-up UI. **Backwards-compat sensitive**.                                                           |
+| `@clerk/clerk-js`      | ⚠️ The browser runtime loaded via script tag. **Backward-compat sensitive** (see rules).                                                                    |
+| `@clerk/ui`            | ⚠️ The React components powering the hosted sign-in / sign-up UI. **Backward-compat sensitive**.                                                            |
 | `@clerk/mosaic`        | Experimental next-generation components (`UserButton` today). Independently releasable; reads Clerk context from the host SDK.                              |
 | `@clerk/react`         | Shared React hooks/context (`useAuth`, `useUser`, ...) consumed by the React-based adapters.                                                                |
 | `@clerk/nextjs`        | Next.js SDK: middleware, route handlers, server components.                                                                                                 |
@@ -155,7 +155,7 @@ Each rule below restates `AGENTS.md`; the parenthetical is how it is enforced.
   `commit-msg` hook. Valid `scope` = any `packages/*` short name **and** its `clerk-`-stripped form
   (so `clerk-js` accepts `clerk-js` or `js`), plus `repo`, `release`, `e2e`, `ci`, `*`. `docs` is a
   valid **type**, not a scope. Source of truth: `commitlint.config.ts`.
-- **`clerk-js` and `ui` must stay backwards-compatible across non-major releases.** A new `clerk-js`
+- **`clerk-js` and `ui` must stay backward-compatible across non-major releases.** A new `clerk-js`
   runtime loads into apps still pinned to an _older_ framework SDK (`@clerk/nextjs`, etc.), so
   removing or renaming anything an older SDK calls breaks those apps in production. (`break-check`
   flags API-surface changes in `api-changes.yml`, but that check is informational; shipping such a

.claude/skills/clerk-monorepo/references/breaking-changes.md

@@ -57,7 +57,7 @@ If you need to ship something that is not yet stable:
 
 All three are described in `docs/CONTRIBUTING.md` (the "Experimental and internal APIs" section),
 which states the SemVer carve-out explicitly for the `/experimental` subpath; the `__internal_` /
-`__experimental_` prefixes are conventions signalling the same no-guarantee expectation. All are
+`__experimental_` prefixes are conventions signaling the same no-guarantee expectation. All are
 exempt from the breaking-change rules above.
 
 ## What CI enforces

.claude/skills/clerk-monorepo/references/changesets.md

@@ -59,7 +59,7 @@ package. The whole file is exactly two delimiters and nothing else:
 
 Write it with the Write tool like any other file. If you must use the shell,
 `printf -- '---\n---\n' > .changeset/<name>.md` produces the same bytes, but there is no reason to
-verify it with `cat -A` or `od -c` afterwards. The format has no hidden characters.
+verify it with `cat -A` or `od -c` afterward. The format has no hidden characters.
 
 ## Which packages to list
 

.claude/skills/clerk-monorepo/references/package-map.md

@@ -14,14 +14,14 @@ The 25 active, git-tracked packages, the dependency shape, and the full "change
 Categories: **foundational** (depended on by most others), **browser-runtime** (ships to the
 browser directly), **adapter** (framework SDK), **ui/i18n**, **tooling**. The "BC" column marks the
 two packages whose runtime is pushed into apps pinned to older SDKs, so they carry the strict
-backwards-compatibility contract (see `breaking-changes.md`).
+backward-compatibility contract (see `breaking-changes.md`).
 
 | Package                       | Category        | BC  | Purpose                                                                                                                                                                                                                                                            |
 | ----------------------------- | --------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `@clerk/shared`               | foundational    |     | Internal utilities used by all SDKs (storage, events, React helpers). Hosts the shared types as `@clerk/shared/types`. Most-depended-on package.                                                                                                                   |
 | `@clerk/backend`              | foundational    |     | Backend API REST client, JWT verification, webhook helpers. Used by every server adapter.                                                                                                                                                                          |
-| `@clerk/clerk-js`             | browser-runtime | ⚠️  | The browser runtime (script tag). Backwards-compat sensitive.                                                                                                                                                                                                      |
-| `@clerk/ui`                   | ui              | ⚠️  | React components for the hosted sign-in / sign-up flows (`packages/ui/src/components`). Consumed by the react/astro/vue/chrome-extension adapters. Backwards-compat sensitive.                                                                                     |
+| `@clerk/clerk-js`             | browser-runtime | ⚠️  | The browser runtime (script tag). Backward-compat sensitive.                                                                                                                                                                                                       |
+| `@clerk/ui`                   | ui              | ⚠️  | React components for the hosted sign-in / sign-up flows (`packages/ui/src/components`). Consumed by the react/astro/vue/chrome-extension adapters. Backward-compat sensitive.                                                                                      |
 | `@clerk/mosaic`               | ui              |     | Experimental next-generation React components. Public ESM package (`UserButton` + `styles.css`). Ships unstyled, accessible primitives (dialog, menu, popover, ...) internally under `src/primitives/`. Reads Clerk context from the host SDK via `@clerk/shared`. |
 | `@clerk/react`                | adapter (core)  |     | React hooks and context (`useAuth`, `useUser`, `useOrganization`, ...). Shared by the React-based adapters.                                                                                                                                                        |
 | `@clerk/nextjs`               | adapter         |     | Next.js SDK: middleware, route handlers, server components.                                                                                                                                                                                                        |
@@ -82,7 +82,7 @@ error traces back to it, rebuild shared: `pnpm turbo build --filter=@clerk/share
 - **The hosted sign-in / sign-up UI (components, layout)**: `packages/ui/src/components` (`@clerk/ui`).
   Strings live in `packages/localizations/src`. `@clerk/ui` is consumed by the
   `react`/`astro`/`vue`/`chrome-extension` adapters; its compiled runtime is delivered alongside
-  `clerk-js` (both are backwards-compat sensitive), though `clerk-js` does not declare it as a package
+  `clerk-js` (both are backward-compat sensitive), though `clerk-js` does not declare it as a package
   dependency. Watch with `pnpm dev:fe-libs`. For the theming/appearance system specifically, read the
   repo-root `references/theming-architecture.md` (not this skill's own `references/` dir).
 - **Backend token verification / JWT / Backend API client**: `packages/backend/src` (JWT logic under

.claude/skills/mosaic/SKILL.md

@@ -86,7 +86,7 @@ get wrong:
 produced it.** No "not a `size`, because…", no rejected alternatives, no history
 of what the prop used to be. A reader is there to learn what the thing does, and
 every sentence of rationale is a sentence they have to skim past to find it.
-State the behaviour plainly and briefly, then stop.
+State the behavior plainly and briefly, then stop.
 
 ```mdx
 <!-- no -->

.github/workflows/ci.yml

@@ -85,6 +85,9 @@ jobs:
       - name: Check Dashboard links
         run: pnpm lint:dashboard-links
 
+      - name: Check American spelling
+        run: pnpm lint:american-spelling
+
       - name: Verify localizations are generated
         run: |
           pnpm --filter @clerk/localizations generate
@@ -360,6 +363,7 @@ jobs:
         run: pnpm --filter @clerk/mosaic test:feature
 
       - name: Upload failure artifacts
+        # american-spelling-ignore-next-line: cancelled -- GitHub Actions status function
         if: ${{ cancelled() || failure() }}
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
@@ -586,6 +590,7 @@ jobs:
           VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
 
       - name: Sanitize artifact name
+        # american-spelling-ignore-next-line: cancelled -- GitHub Actions status function
         if: ${{ cancelled() || failure() }}
         id: sanitize
         run: |
@@ -595,6 +600,7 @@ jobs:
           TEST_NAME: ${{ matrix.test-name }}
 
       - name: Upload test-results
+        # american-spelling-ignore-next-line: cancelled -- GitHub Actions status function
         if: ${{ cancelled() || failure() }}
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:

.github/workflows/e2e-staging.yml

@@ -35,7 +35,7 @@ concurrency:
   # Key on the clerk_go commit being validated rather than the (effectively always "main")
   # ref, so distinct staging deploys no longer cancel each other and each commit can report
   # its own result. Duplicate dispatches for the SAME commit still de-dupe; manual dispatches
-  # without a commit SHA fall back to the unique run_id and are never cancelled.
+  # without a commit SHA fall back to the unique run_id and are never canceled.
   group: ${{ github.workflow }}-${{ github.event.inputs.clerk-go-commit-sha || github.event.client_payload.clerk-go-commit-sha || github.run_id }}
   cancel-in-progress: true
 
@@ -304,6 +304,7 @@ jobs:
           NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/integration/certs/rootCA.pem
 
       - name: Upload test-results
+        # american-spelling-ignore-next-line: cancelled -- GitHub Actions status function
         if: ${{ cancelled() || failure() }}
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
@@ -318,6 +319,7 @@ jobs:
       # integration/playwright-report/. Keep that prefix here. `warn` (not `ignore`)
       # so a future path regression surfaces in the logs instead of failing silently.
       - name: Upload Playwright JSON report
+        # american-spelling-ignore-next-line: cancelled -- GitHub Actions status function
         if: ${{ !cancelled() }}
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:

.github/workflows/release.yml

@@ -261,6 +261,7 @@ jobs:
 
       - name: Generate notification payload
         id: notification
+        # american-spelling-ignore-next-line: cancelled -- GitHub Actions status function
         if: ${{ !cancelled() && steps.changesets.outputs.published == 'true' }}
         env:
           PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }}
@@ -275,6 +276,7 @@ jobs:
 
       - name: Send commit log to Slack
         id: slack
+        # american-spelling-ignore-next-line: cancelled -- GitHub Actions status function
         if: ${{ !cancelled() && steps.changesets.outputs.published == 'true' && steps.notification.outcome == 'success' }}
         uses: slackapi/slack-github-action@fcfb566f8b0aab22203f066d80ca1d7e4b5d05b3 # v1.27.1
         with:

.typedoc/README.md

@@ -75,9 +75,9 @@ The `.typedoc/docs` folder is inside the `.gitignore` on purpose. Its contents w
 
 ### Adding a package to the Typedoc output
 
-Make sure that the package directory is listed inside [`typedoc.config.mjs`](../typedoc.config.mjs) `config.entryPoints`. Afterwards Typedoc will inspect the `exports` map and `main` key inside `package.json` to determine the entrypoints for the package.
+Make sure that the package directory is listed inside [`typedoc.config.mjs`](../typedoc.config.mjs) `config.entryPoints`. Afterward Typedoc will inspect the `exports` map and `main` key inside `package.json` to determine the entrypoints for the package.
 
-If for some reason this doesn't work, spend time investigating it. If afterwards it still doesn't work, you can add a `typedoc.json` file to the package and define the `entryPoints` there.
+If for some reason this doesn't work, spend time investigating it. If afterward it still doesn't work, you can add a `typedoc.json` file to the package and define the `entryPoints` there.
 
 > [!IMPORTANT]
 > If you're generating documentation for files/APIs that are not exported/accessible to a user, it's an error. Unless you want to limit the entry points (e.g. a package exports internal functionality) or modify things like the `compilerOptions`, you probably should not define a custom `typedoc.json` file inside a package.

AGENTS.md

@@ -4,7 +4,7 @@ Clerk's JavaScript SDK and library monorepo.
 
 ## Rules
 
-- Non-major releases in `packages/clerk-js` and `packages/ui` are pushed out to consuming applications without requiring explicit package updates. This means a new `clerk-js` runtime can load into an app pinned to an older `@clerk/nextjs` (or any other framework SDK) version, so changes must remain backwards-compatible with SDK versions already in the wild, not just the current monorepo state. Removing or renaming anything an older SDK still calls will break production for those users. Extra care must be put into any changes to these packages.
+- Non-major releases in `packages/clerk-js` and `packages/ui` are pushed out to consuming applications without requiring explicit package updates. This means a new `clerk-js` runtime can load into an app pinned to an older `@clerk/nextjs` (or any other framework SDK) version, so changes must remain backward-compatible with SDK versions already in the wild, not just the current monorepo state. Removing or renaming anything an older SDK still calls will break production for those users. Extra care must be put into any changes to these packages.
 - The API exposed from the core Clerk class in `packages/clerk-js/src/core/clerk.ts` is a contract that is depended on by internal and external consumers (including older SDK versions still loading the latest `clerk-js`). Changes to this API must be done in a major version to avoid breakage.
 - Unless specifically instructed to do so by the user, _do not write any code comments_. The only permissible time to edit existing comments is when the behavior they describe has been modified in such a way that the comment is no longer accurate. When another rule instructs you to write a JSDoc comment, specifically call out the content of the comment to the user for review.
 - Use `pnpm` only. `npm` and `yarn` are blocked by `preinstall`. Node `>=24.15`, pnpm `>=10.33`.

docs/CONTRIBUTING.md

@@ -96,14 +96,16 @@ If you want to run the `dev` script of an individual package, navigate to the fo
 
 The repo ships configuration for AI coding agents, picked up automatically from the checkout with no setup:
 
-- [`AGENTS.md`](../AGENTS.md) holds the hard rules (package manager, changesets, commit conventions, backwards compatibility) and is read by most agents.
+- [`AGENTS.md`](../AGENTS.md) holds the hard rules (package manager, changesets, commit conventions, backward compatibility) and is read by most agents.
 - Claude Code also loads the `clerk-monorepo` skill from [`.claude/skills/`](../.claude/skills/README.md). It activates on its own for monorepo questions, or explicitly via `/clerk-monorepo`. The README in that directory explains how skills work and how to maintain them.
 - Cursor reads the rules in `.cursor/rules/`.
 
 ### Documenting your changes
 
 Updating documentation is an important part of the contribution process. If you are changing existing behavior or adding a new feature, make sure [Clerk's documentation](https://github.com/clerk/clerk-docs) is also updated.
 
+Write in American English (`color`, `canceled`, `toward`), in code as well as prose. `pnpm lint:american-spelling` flags British spellings in CI, and `pnpm lint:american-spelling --fix` rewrites them. To keep a direct quotation or a name you don't own, put an `american-spelling-ignore-next-line` comment on the line above it that lists the words to allow after a colon, with an optional `--` reason.
+
 To improve the in-editor experience when using Clerk's SDKs, we do our best to add [JSDoc comments](https://jsdoc.app/about-getting-started.html) to our package's public exports. The JSDoc comments should not attempt to duplicate any existing type information, but should provide meaningful additional context or references. If you are adding a new export, make sure it has a JSDoc comment. If you are updating an existing export, make sure any existing comments are updated appropriately.
 
 There are some styleguide decisions you should follow when authoring JSDoc comments:
@@ -190,7 +192,7 @@ As explained in [documenting your changes](#documenting-your-changes), we use JS
 
 For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this guide](https://www.notion.so/clerkdev/Typedoc-JSDoc-1df2b9ab44fe808a8cf2c9cca324ea89?source=copy_link).
 
-To review your changes locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typedoc/docs`. But if you want to preview how the Typedoc output will look in Clerk Docs, there's a few things you need to do first:
+To review your changes locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterward, you can inspect the MDX files inside `.typedoc/docs`. But if you want to preview how the Typedoc output will look in Clerk Docs, there's a few things you need to do first:
 
 Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, the release workflow automatically opens a PR in Clerk's docs repository with the Typedoc changes.