feat: #3631526 Polish the generator form: AI label, example buttons, disclosure and cost line

Issue: #3631526 "Initialize the AI Media module"

Chunk 8 of the UX and integration plan (20 October 2026): generator form polish (plan sections 4 and 6.4).

Depends on !14 (closed) (3631526-safety-tab), which depends on !13 (closed), !12 (closed), !11 (closed), !10 (closed), !9 (closed), !8 (closed) and !6 (merged). Until those merge, this diff includes them; the change of this MR is its last commit.

What changed

Top to bottom, in the Media Library tab and on the Add media page (one shared builder):

1. AI label: the field title reads "Describe the image" (SVG, video, document) followed by an "AI" label with a decorative sparkle, in the admin theme's badge class (Gin and Default Admin new flag, AI Media's outline pill in Claro). Text, not color alone.
2. Help, one line: "Say the subject, the setting and the style." The help is no longer hyphenated mid-word (hyphens: manual).
3. Examples as up to three buttons under the field, in Tab order after it, each named "Use this example: ". Pressing one fills the field and returns focus to it. They replace the quoted list.
4. Disclosure, its own full size line under the examples, read with the field (its ID is added to the field's aria-describedby), so an admin theme that folds descriptions behind a help icon (Gin's description toggle) does not hide it (second commit, found while taking the screenshots): "Made by AI with {provider}. Your description is sent to {provider}. Check the result before you use it." With site context: "Uses site context from this site (N items)." for images, "Uses site context from this site." for chat generators.
5. Options, closed: Shape first, with pixel sizes ("Square, 1024 x 1024"), then Format, Quality, Model, then the generator's own options. The closed title shows the choice, "Options (Square, PNG)", and updates as it changes.
6. Cost line under Generate: "Each press is a paid request to {provider}." Not shown for providers listed as free (cost_notice.free_providers, default echoai) or when the site turns it off (cost_notice.enabled), both on the Editor options tab. No amounts or estimates.
7. While running: the button reads "Generating…" and the page announces (polite) "Generating image. This can take up to a minute."; errors stay assertive, as before.

No update hook: cost_notice is new in config/install and the schema; an existing site without it shows the cost line until the setting is saved.

How it was tested

• Plain Drupal 11.4 (aimplan1), Echo provider, headless Firefox:
  • axe-core 4.10.2 (WCAG 2.0, 2.1 and 2.2 A and AA): 0 violations on the image form, the document form with Options open, and the Add media page form, in Claro, Gin and Default Admin at 1440 and 1920.
  • Accessibility tree (Playwright's ARIA snapshot, Firefox): the field is named "Describe the document AI", its description holds the help and the disclosure, the examples are a group "Example descriptions" of buttons named with their text, then "Options (PDF)" and "Generate document".
  • Keyboard: from the field, Tab reaches the two examples, Options, then Generate; Enter on an example fills the field and puts focus back in it.
• Varbase E2E, Firefox: 04-01-01-form (new label, help, disclosure, generating message, no cost line with Echo, an example fills the field, the closed Options title) and 06-01-01-settings (examples as buttons, the cost line shown when Echo is not listed as free) pass; the full suite on a fresh CI-like site, see below.
• Kernel tests (26) pass. phpcs (Drupal, DrupalPractice), phpstan level 1, cspell, eslint (core config on js/, and step definitions), stylelint: clean.

Not tested

• No NVDA or Orca pass: no screen reader is available in this environment. The accessibility tree and keyboard order above were checked instead; a real screen reader pass is still needed for the acceptance criterion.
• Real providers (Echo only), so the cost line with a paid provider was seen only by removing Echo from the free list.
• Mobile widths (out of scope).

AI-Generated: Yes. Written with Claude Code (Claude Opus 5.5) under the Drupal AI policy; tested by the author before submission.

Checkpoints:

• File an issue
• Addition/Change/Update/Fix
• Testing to ensure no regression
• Automated unit testing coverage
• Automated functional testing coverage
• UX/UI designer responsibilities
• Readability
• Accessibility
• Performance
• Security
• Developer Documentation
• User Guide Documentation
• Reviewed by human
• Code review by maintainers
• Full testing and approval
• Credit contributors
• Review with the product owner
• Release notes snippet
• Release