docs(navigation-secondary): enhance inline documentation#2751
Open
bennypowers wants to merge 8 commits intomainfrom
Open
docs(navigation-secondary): enhance inline documentation#2751bennypowers wants to merge 8 commits intomainfrom
bennypowers wants to merge 8 commits intomainfrom
Conversation
Enhanced inline documentation for rh-navigation-secondary component family to improve developer experience and API understanding: **rh-navigation-secondary:** - Enhanced nav, container, and cta parts with comprehensive inline documentation explaining structure, styling customization, and responsive behavior - Documented --rh-navigation-secondary-z-index CSS property in CSS file with usage guidelines for z-index stacking and coordination with primary navigation **rh-navigation-secondary-dropdown:** - Enhanced container part with inline documentation covering dropdown state management, expanded/highlight classes, and styling guidelines **rh-navigation-secondary-menu-section:** - Enhanced container part with inline documentation explaining semantic structure, accessibility enhancements, and automatic aria-labelledby association **rh-navigation-secondary-menu.css:** - Documented --rh-navigation-secondary-menu-section-grid CSS property with usage guidelines for responsive grid column layout - Documented --rh-navigation-secondary-menu-section-grid-gap CSS property with usage guidelines for menu section spacing - Documented --rh-navigation-secondary-menu-content-max-width CSS property with usage guidelines for dropdown content width constraints **rh-navigation-secondary-overlay:** - Enhanced `open` property with detailed description of overlay behavior, automatic management by parent component, and accessibility considerations All documentation includes design system context about navigation patterns, accessibility requirements, and usage best practices. Note: Issue #2502 mentioned firstUpdated() method, but this is a Lit lifecycle method (excluded by CEM). This PR documents the public API instead. Closes #2502 🤖 Generated with [Claude Code](https://claude.com/claude-code) Assisted-By: Claude <[email protected]>
|
✅ Deploy Preview for red-hat-design-system ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
…elines Update element, attribute, slot, event, and CSS property documentation. Add demo description .md files. Use RFC 2119 keywords, include ARIA/accessibility notes, and document event detail shapes. Assisted-By: Claude Opus 4.6 (1M context) <[email protected]>
Contributor
Documentation Health
|
| Category | Score | |
|---|---|---|
| Element description | 0/25 | ❌ |
| Attribute documentation | 20/20 | ✅ |
| Slot documentation | 15/15 | ✅ |
| CSS documentation | 15/15 | ✅ |
| Event documentation | 15/15 | ✅ |
| Demos | 0/10 | ❌ |
rh-navigation-secondary-dropdown (RhNavigationSecondaryDropdown) — 80/100 ✅
| Category | Score | |
|---|---|---|
| Element description | 20/25 | ✅ |
| Attribute documentation | 20/20 | ✅ |
| Slot documentation | 15/15 | ✅ |
| CSS documentation | 10/15 | |
| Event documentation | 15/15 | ✅ |
| Demos | 0/10 | ❌ |
rh-navigation-secondary-menu-section (RhNavigationSecondaryMenuSection) — 82/100 ✅
| Category | Score | |
|---|---|---|
| Element description | 22/25 | ✅ |
| Attribute documentation | 20/20 | ✅ |
| Slot documentation | 15/15 | ✅ |
| CSS documentation | 10/15 | |
| Event documentation | 15/15 | ✅ |
| Demos | 0/10 | ❌ |
rh-navigation-secondary-menu (RhNavigationSecondaryMenu) — 68/100 ⚠️
| Category | Score | |
|---|---|---|
| Element description | 14/25 | |
| Attribute documentation | 20/20 | ✅ |
| Slot documentation | 10/15 | |
| CSS documentation | 9/15 | |
| Event documentation | 15/15 | ✅ |
| Demos | 0/10 | ❌ |
rh-navigation-secondary-overlay (RhNavigationSecondaryOverlay) — 78/100 ⚠️
| Category | Score | |
|---|---|---|
| Element description | 19/25 | |
| Attribute documentation | 20/20 | ✅ |
| Slot documentation | 15/15 | ✅ |
| CSS documentation | 9/15 | |
| Event documentation | 15/15 | ✅ |
| Demos | 0/10 | ❌ |
SecondaryNavOverlayChangeEvent — 65/100 ⚠️
| Category | Score | |
|---|---|---|
| Element description | 0/25 | ❌ |
| Attribute documentation | 20/20 | ✅ |
| Slot documentation | 15/15 | ✅ |
| CSS documentation | 15/15 | ✅ |
| Event documentation | 15/15 | ✅ |
| Demos | 0/10 | ❌ |
rh-navigation-secondary (RhNavigationSecondary) — 87/100 ✅
| Category | Score | |
|---|---|---|
| Element description | 17/25 | |
| Attribute documentation | 20/20 | ✅ |
| Slot documentation | 15/15 | ✅ |
| CSS documentation | 10/15 | |
| Event documentation | 15/15 | ✅ |
| Demos | 10/10 | ✅ |
Recommendations:
- SecondaryNavOverlayChangeEvent: add a description to explain what this declaration does (Element description, +5 pts)
- rh-navigation-secondary-menu-section: reference design tokens or theme considerations in CSS descriptions (CSS documentation, +5 pts)
- SecondaryNavDropdownExpandEvent: describe purpose and context using words like 'for', 'when', 'provides', 'allows' (Element description, +5 pts)
- SecondaryNavDropdownExpandEvent: use RFC 2119 keywords (MUST, SHOULD, AVOID) to clarify requirements (Element description, +5 pts)
- rh-navigation-secondary: describe purpose and context using words like 'for', 'when', 'provides', 'allows' (Element description, +5 pts)
Backticks inside HTML comments within lit-html template literals must be escaped as \` to avoid esbuild parse errors. Assisted-By: Claude Opus 4.6 (1M context) <[email protected]>
Replace companion .md files with <meta itemprop="description"> tags in demo HTML files per CEM demo documentation guidelines. Assisted-By: Claude Opus 4.6 (1M context) <[email protected]>
Contributor
|
Size Change: +3.5 kB (+1.35%) Total Size: 263 kB
ℹ️ View Unchanged
|
Fix empty-line-before-comment, max-line-length, and formatting issues in CSS custom property documentation comments. Assisted-By: Claude Opus 4.6 (1M context) <[email protected]>
Remove JSDoc comments from --_ prefixed private CSS custom properties (excluded from manifest). Improve slot documentation with content type guidelines and accessibility considerations. Assisted-By: Claude Opus 4.6 (1M context) <[email protected]>
Add brief comments explaining what each design token controls within this component's context. Assisted-By: Claude Opus 4.6 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What I did
Enhanced inline documentation for
rh-navigation-secondarycomponent to improve developer experience and API understanding.👉 Deploy Preview 👈
This documentation was created with assistance from LLM tools. Reviewers MUST carefully verify the semantic meaning and design system accuracy of all new documentation.
accessible-labelproperty defaults to"secondary"which is generic. A designer should recommend whether the default should include the product name or if documentation should more strongly encourage overriding this value.--rh-navigation-secondary-z-indexdefaults to 102, matching the primary navigation z-index. A designer should confirm whether these should be differentiated when both navigations are visible simultaneously.layoutattribute onrh-navigation-secondary-menuaccepts'fixed-width'and'full-width'but there is no design guidance on when to use'fixed-width'. A designer should provide usage recommendations.color-paletteonrh-navigation-secondary-menudefaults to'lightest'and the JSDoc says menus are "always" lightest. A designer should confirm whether the attribute should be locked or if dark-palette menus are a valid future use case.aria-current="page"manually. A designer should evaluate whether a utility or helper should be provided to simplify this integration for common CMS platforms.<rh-icon>approach would be more consistent with the rest of the design system.