docs(pagination): enhance inline documentation#2752
Closed
bennypowers wants to merge 8 commits intomainfrom
Closed
docs(pagination): enhance inline documentation#2752bennypowers wants to merge 8 commits intomainfrom
bennypowers wants to merge 8 commits intomainfrom
Conversation
Enhanced inline documentation for rh-pagination component to improve developer experience and API understanding: **rh-pagination.ts:** - Enhanced `out-of` slot with comprehensive inline documentation explaining its use as preposition text between current page and total, including internationalization patterns and best practices for screen reader accessibility **rh-pagination.css:** - Documented --rh-pagination-accent-color CSS property with usage guidelines for interactive element colors, focus states, and contrast requirements - Documented --rh-pagination-stepper-color CSS property with usage guidelines for navigation button icon colors and visibility considerations - Documented --rh-pagination-background-focused CSS property with deprecation notice and usage guidelines for disabled stepper button states All documentation includes design system context about color usage, accessibility requirements, and internationalization best practices. Closes #2503 🤖 Generated with [Claude Code](https://claude.com/claude-code) Assisted-By: Claude <noreply@anthropic.com>
|
✅ Deploy Preview for red-hat-design-system ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Size Change: +957 B (+0.37%) Total Size: 261 kB
ℹ️ View Unchanged
|
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) <noreply@anthropic.com>
bennypowers
force-pushed
the
docs/pagination-inline-docs
branch
from
d4400fd to
cf5aba0
Compare
Contributor
Documentation Health
|
| Category | Score | |
|---|---|---|
| Element description | 18/25 | |
| Attribute documentation | 20/20 | ✅ |
| Slot documentation | 9/15 | |
| CSS documentation | 10/15 | |
| Event documentation | 15/15 | ✅ |
| Demos | 10/10 | ✅ |
Recommendations:
- rh-pagination: reference design tokens or theme considerations in CSS descriptions (CSS documentation, +4 pts)
- rh-pagination: description is longer than 400 characters; consider being more concise (Element description, +3 pts)
- rh-pagination: describe purpose and context using words like 'for', 'when', 'provides', 'allows' (Element description, +2 pts)
- rh-pagination: use RFC 2119 keywords (MUST, SHOULD, AVOID) to clarify requirements (Element description, +2 pts)
- rh-pagination: add descriptions to all slots (Slot documentation, +2 pts)
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
Add brief comments explaining what each design token controls within this component's context. Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Member
Author
|
see #2861 |
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-paginationcomponent 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.
--rh-pagination-background-focusedCSS custom property name is misleading (it controls disabled stepper icon color, not focused background). A designer should decide on a clearer name or confirm deprecation plan once--rh-color-icon-status-disabledis available as a design token.overflowattribute is publicly reflected but intended to be computed internally. A designer should confirm whether this should be documented as a public API or hidden from consumers.page-changeevent (or similar) would improve the developer experience, especially for SPA integrations that intercept link clicks.