Adding code usage links to point to Storybook#6149
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates component documentation pages to reduce/avoid rendering the auto-generated Code usage tables on design.va.gov (which can overflow on smaller viewports) by replacing them with Storybook links, and it also adjusts component naming in docs toward Title Case.
Changes:
- Replace
{% include component-docs.html ... %}Code usage tables with<va-link-action>links to the corresponding Storybook docs pages. - Update component doc titles and in-page component-name references to Title Case in multiple component pages.
- Remove Code usage sections in a few places where the docs should no longer render them.
Reviewed changes
Copilot reviewed 62 out of 62 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/_components/text.md | Replaces Code usage include with Storybook link (mobile). |
| src/_components/template.md | Updates component doc template to instruct Storybook-link Code usage. |
| src/_components/telephone.md | Replaces Code usage include with Storybook link. |
| src/_components/tag/tag-status.md | Replaces Code usage include with Storybook link. |
| src/_components/tabs.md | Replaces Code usage include with Storybook link. |
| src/_components/table.md | Replaces Code usage include with Storybook link. |
| src/_components/summary-box.md | Title-case updates + replaces Code usage text with Storybook link. |
| src/_components/sort.md | Replaces Code usage include with Storybook link. |
| src/_components/snackbar.md | Replaces Code usage include with Storybook link (mobile). |
| src/_components/sidenav.md | Replaces Code usage include with Storybook link. |
| src/_components/service-list-item.md | Replaces Code usage include with Storybook link. |
| src/_components/search-input.md | Replaces Code usage include with Storybook link. |
| src/_components/search-filter.md | Replaces Code usage include with Storybook link. |
| src/_components/progress-bar-activity.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/process-list.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/pagination.md | Replaces Code usage include with Storybook link. |
| src/_components/on-this-page.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/modal/index.md | Replaces Code usage include with Storybook link. |
| src/_components/modal/crisis-line-modal.md | Replaces Code usage include with Storybook link. |
| src/_components/loading-indicator.md | Replaces Code usage include with Storybook links (web + mobile). |
| src/_components/link/index.md | Replaces combined Code usage include with Storybook links (web + mobile). |
| src/_components/link/action.md | Replaces Code usage include with Storybook link. |
| src/_components/language-toggle.md | Title-case updates + Storybook preview link_text capitalization + checklist include formatting. |
| src/_components/icon.md | Adds Storybook links for Code usage (but retains component-docs include). |
| src/_components/header/minimal.md | Replaces Code usage include with Storybook link. |
| src/_components/form/textarea.md | Replaces Code usage include with Storybook link. |
| src/_components/form/text-input.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/form/telephone-input.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/form/statement-of-truth.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/form/select.md | Replaces Code usage include with Storybook link. |
| src/_components/form/radio-button.md | Replaces Code usage include with Storybook links (web + mobile). |
| src/_components/form/progress-bar-segmented.md | Replaces Code usage include with Storybook link + title-case link text. |
| src/_components/form/privacy-agreement.md | Replaces Code usage include with Storybook link. |
| src/_components/form/prefill.md | Removes Code usage anchor/section references. |
| src/_components/form/penalty-notice.md | Title-case updates. |
| src/_components/form/need-help.md | Title-case updates + replaces Code usage text with Storybook link. |
| src/_components/form/memorable-date.md | Replaces Code usage include with Storybook link. |
| src/_components/form/index.md | Title-case updates for sub-page names. |
| src/_components/form/file-input.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/form/date-input.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/form/combo-box.md | Replaces Code usage include with Storybook link. |
| src/_components/form/checkbox.md | Replaces Code usage include with Storybook links (web + mobile). |
| src/_components/footer/minimal.md | Removes Code usage include (page now only shows checklist). |
| src/_components/details.md | Replaces Code usage include with Storybook link. |
| src/_components/critical-action.md | Replaces Code usage include with Storybook link. |
| src/_components/card/index.md | Replaces Code usage include with Storybook link. |
| src/_components/card/card-status.md | Replaces Code usage include with Storybook link. |
| src/_components/button/index.md | Replaces Code usage include with Storybook links (web + mobile). |
| src/_components/button/button-segmented.md | Replaces Code usage include with Storybook links (web + mobile). |
| src/_components/button/button-icon.md | Replaces Code usage include with Storybook link. |
| src/_components/button/button-group.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/breadcrumbs.md | Replaces Code usage include with Storybook link. |
| src/_components/banner/official-gov.md | Replaces Code usage include with Storybook link. |
| src/_components/banner/maintenance.md | Replaces Code usage include with Storybook link. |
| src/_components/banner/index.md | Replaces Code usage include with Storybook link. |
| src/_components/back-to-top.md | Removes Code usage include (no replacement added). |
| src/_components/alert/index.md | Replaces Code usage include with Storybook links (web + mobile). |
| src/_components/alert/alert-sign-in.md | Replaces Code usage include with Storybook link. |
| src/_components/alert/alert-expandable.md | Replaces Code usage include with Storybook link. |
| src/_components/address-block.md | Title-case updates + checklist include formatting. |
| src/_components/additional-info.md | Title-case updates + replaces Code usage include with Storybook link. |
| src/_components/accordion.md | Replaces Code usage include with Storybook link. |
|
|
||
| Refer to the [Tag component in Storybook]({{ site.baseurl }}/storybook/?path=/docs/components-tag--docs) for detailed code usage documentation. | ||
| <va-link-action | ||
| href="{{ site.storybook_path }}/?path=/docs/components-va-tag--docs" |
There was a problem hiding this comment.
It looks like URL path is incorrect here, it should be /docs/components-tag--docs instead.
| * The Back to top component stays fixed in the lower right edge of the main content area when the user reaches the bottom of the page. | ||
| * Clicking Back to top takes the user to the top of the page. | ||
|
|
||
| {% include component-docs.html component_name=page.web-component %} |
There was a problem hiding this comment.
Question
When there are no component props, we exclude the "Code usage" section?
There was a problem hiding this comment.
typically - but you are right to call this out. I left it in for va-tag, I should leave it in for this one too.
RyanMunsch
left a comment
RyanMunsch
left a comment
There was a problem hiding this comment.
This is looking good, @jeana-adhoc. I just spotted the one broken Storybook link for tag that is noted in the comment above
|
Wasn't planning to fully review, but while looking out of curiosity: was this the only use of one of the things in src/_includes/component-docs.html that should also be deleted/cleaned up? Edit: Or, alternatively, would it be better for the new logic be generalized and continue using that shared display logic to fill in the Code Usage section even if it's now just a link to the appropriate Storybook doc? |
This is a great call out and as I worked on this I realized this could be done better (in a more DRY coded way). But we decided for timing, to at least get the table out quickly for now. I'm going to try to see if I can leverage the component-docs html include, to handle this logic, and maybe this could have been done in a more simple way all along. Thanks for the nudge. |
|
@RyanMunsch & @danbrady - I've written this a bit more dryly. The only problem is that it reveals that in our component library tsx files we're not naming our components correctly, so they will be in sentence case in the links instead of title case. I'm willing to deal with that for now to get this PR merged. ETA: I've let @amyleadem know about the inconsistent casing, and she agreed we'll deal with that later. |
Summary
When
va-tablehas columns with unbreakable strings (no spaces or hypens) it can cause the table to be non-responsive and extend past the viewport. After looking at a few ways to bring the strings, we decided it would just be best to point users to storybook and to not even include the table on design.va.gov. We support this decision with research that's been done to indicate that developers refer to storybook anyway and don't rely on, or look at the tables on VA.govI also took opportunity to update component names to match this guidance: https://design.va.gov/about/naming-conventions/#page-titles-and-display-names where we are instructed to Transform kebab-case of the component name to Title Case for documentation use on design.va.gov
I edited the existing component-docs.html include to contain the logic for the links to storybook.
Related Issue
Closes #6136
Preview Environment Links
Open Preview Environment