docs(accordion): enhance inline documentation

- Enhanced `accents` property JSDoc with semantic meaning explaining
inline vs bottom positioning and usage guidelines
- Enhanced default slot documentation in rh-accordion-header with
detailed description of title text best practices
- Added comprehensive JSDoc for `expanded` property explaining when and
why to use it
- Added inline comment for `container` part describing its semantic role

This addresses the missing documentation identified in issue #2487.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Assisted-By: Claude <noreply@anthropic.com>

Author: bennypowers

elements/rh-accordion/rh-accordion-header.ts

@@ -88,7 +88,15 @@ export class RhAccordionHeader extends LitElement {
         <span id="header-container" class="${classMap({ [accents ?? '']: !!accents })}">
           <!-- summary: inline element containing the heading text or slotted heading content -->
           <span id="header-text" part="text">
-            <!-- summary: accordion toggle content -->
+            <!-- summary: panel's title text or heading content
+                 description: |
+                   Contains the primary label that describes what content will be revealed when the panel expands.
+                   Title text should be written concisely (max 65 characters) so users know what to expect.
+                   Avoid writing titles that sound like calls to action - make it easy for users to understand
+                   the content within. Title text that is too long should be broken into separate sections, and
+                   text that is too vague may not help users understand the panel content.
+
+                   @see [Title text](https://ux.redhat.com/elements/accordion/guidelines/#title-text) in Guidelines documentation -->
             <slot></slot>
           </span>
           <!-- summary: container for accents within the header -->

elements/rh-accordion/rh-accordion-panel.ts

@@ -21,6 +21,23 @@ import styles from './rh-accordion-panel.css';
 export class RhAccordionPanel extends LitElement {
   static readonly styles = [styles];
 
+  /**
+   * Sets the initial visibility state of the panel content.
+   * When `true`, the panel is expanded and its content is visible.
+   * When `false` (default), the panel is collapsed and its content is hidden.
+   *
+   * ## Usage guidelines
+   * - Use to draw attention to important content that should be immediately visible
+   * - Set on the first panel in a FAQ or help section to show the most common question
+   * - Supports multiple panels being expanded simultaneously for content comparison
+   * - Users can expand and collapse panels one at a time by default, or multiple panels
+   *   when implementing "Expand all" functionality
+   *
+   * By default, all panels are collapsed (expanded=false). Users expand panels by clicking
+   * the header, which animates the caret icon and reveals the content.
+   *
+   * @see [Expanding and collapsing panels](https://ux.redhat.com/elements/accordion/guidelines/#expanding-and-collapsing-panels) in Guidelines documentation
+   */
   @property({ type: Boolean, reflect: true }) expanded = false;
 
   @consume({ context, subscribe: true })
@@ -37,6 +54,12 @@ export class RhAccordionPanel extends LitElement {
     const { expanded } = this;
     const { large = false } = this.ctx ?? {};
     return html`
+      <!-- summary: main wrapper region that contains the panel content
+           description: |
+             The container part represents the structural element that holds the panel's body content.
+             It maintains the color scheme context to ensure proper text visibility and color contrast,
+             and should match the color palette of the container it's in. This part defines the overall
+             styling and boundaries for the panel's revealed content area. -->
       <div id="container"
            class="${classMap({ large, expanded, content: true })}"
            part="container"

elements/rh-accordion/rh-accordion.ts

@@ -76,7 +76,18 @@ export class RhAccordion extends LitElement {
   }
 
   /**
-   * Sets accordion header's accents position to inline or bottom
+   * Positions the accent slot content relative to the panel's title.
+   * The accent slot contains secondary information such as tags, badges, or other small elements.
+   *
+   * - `inline` (default) - Accents appear on the same line as the title
+   * - `bottom` - Accents appear below the title
+   *
+   * ## Usage guidelines
+   * - Use `inline` when accents are brief and horizontal space permits for both title and accents
+   * - Use `bottom` when you have multiple accent elements or need more horizontal space for the title text
+   * - Accent content represents secondary, supplementary information to the title
+   *
+   * @see [Accent slot](https://ux.redhat.com/elements/accordion/style/#accent-slot) in Style documentation
    */
   @property({ attribute: true, reflect: true }) accents?: 'inline' | 'bottom';