docs(announcement): enhance inline documentation

[bennypowers]

What I did

Enhanced inline documentation for rh-announcement component to improve developer experience and API understanding, following the documentation standards established in PR #2548 for rh-progress-stepper.

Testing Instructions

⚠️ Important: LLM-Assisted Documentation

This documentation was created with assistance from LLM tools. Reviewers MUST carefully verify the semantic meaning and design system accuracy of all new documentation.

Please check that the enhanced documentation:

1. Accurately describes the semantic meaning of each API element in the context of the Red Hat Design System
2. Correctly references the design guidelines and style documentation
3. Provides meaningful guidance on when/why to use each variant or option
4. Aligns with existing design system principles and terminology

Specific sections to review:

1. dismissable property (lines 40-58)

• Verify usage guidelines match the Close button documentation
• Confirm the semantic meaning of "required at minimum" is accurate
• Check that accessibility notes about focus order and keyboard interaction are correct

2. imagePosition property (lines 60-78)

• Verify positioning descriptions (inline-start vs block-start) are accurate
• Confirm image sizing guidelines (48px max height, 20-25px for text logos) match Style documentation
• Check that usage guidelines about when to use each option are appropriate

3. colorPalette property (lines 37-51)

• Verify theme selection best practices match the Theme documentation
• Confirm guidance about dark theme with navigation is correct
• Check color contrast accessibility requirements are accurate

4. Inline slot documentation (lines 125-182)

• image slot (lines 125-139): Verify image sizing guidelines and positioning descriptions
• default slot (lines 143-166): Verify 65-character limit, "when to use" and "when NOT to use" lists
• cta slot (lines 170-182): Verify 25-character limit and "required" designation

5. Inline CSS part documentation (lines 111-121)

• row part (lines 111-115): Verify semantic description of container role
• image part (lines 117-121): Verify responsive positioning description

Notes to Reviewers

About Issue #2488

Issue #2488 mentions a close() method that is missing documentation. However, after investigation:

• No public close() method exists in rh-announcement
• The component uses an event-based dismissal pattern with the dismissable property
• Users interact with a close button (when dismissable=true) that fires a cancelable close event
• There is only a private #closeHandler() method (not part of public API)

This PR documents the existing public API including:

• The dismissable property that controls the close button
• The close event that fires when users dismiss the announcement
• All slots and CSS parts with comprehensive inline documentation

Recommendation: Issue #2488 should be updated or closed as the referenced close() method does not exist as public API.

Documentation Format

Following the project standard:

• Properties use multi-line JSDoc with usage guidelines and @see references
• Slots and CSS parts use inline HTML comments in the template (NOT @slot/@csspart tags in class JSDoc)
• All documentation includes semantic meaning from design system docs

Addresses issue #2488 (with clarification about non-existent close() method)

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: b662366

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

❌ Deploy Preview for red-hat-design-system failed. Why did it fail? →

Name	Link
🔨 Latest commit	b662366
🔍 Latest deploy log	https://app.netlify.com/projects/red-hat-design-system/deploys/69163d58a5b46d0008b4ed2e