Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs design refresh #626

Merged
merged 33 commits into from
Nov 28, 2023
Merged

Docs design refresh #626

merged 33 commits into from
Nov 28, 2023

Conversation

cdedreuille
Copy link
Contributor

@cdedreuille cdedreuille commented Nov 15, 2023 •
edited by kylegach
Loading

What was done

See corresponding content updates in storybookjs/storybook#24925

  • Upgrade to React 18
  • Remove renderer (framework) from URL
    • Read/write localStorage value instead
    • Add support for renderer query param
      • When provided, it auto-sets the localStorage value to the param's value
      • Use it for framework logos on homepage
    • Update redirects
      • For each version & framework combo, add:
        /docs/<version?>/<framework>/<path> -> /docs/<version?>/<path>
      • Update static redirects to no longer point to URLs with framework
    • Refactor IfRenderer -> If
      • Only filter content client-side
      • IfRenderer still available in MDX, for older content
      • Update CodeSnippets to account for client-side-only filtering
    • Consistently use renderer instead of framework in codebase
  • New sidebar and remove sub-nav toolbar
    • Fixed position header (eyebrow + nav)
    • Add support for index.md pages (linked headings)
    • Changed RendererSelector from dropdown menu to pill-based design
    • Move CodeLanguageSelector into CodeSnippets toolbar
  • New code snippets
    • Use shiki for code highlighting
    • Pull first comment line into snippet title (if it's a filename)
    • Move copy button into snippet toolbar
    • Move CodeLanguageSelector out of SubNav and into snippet toolbar
    • Do the same for a new PackageManagerSelector
      • Value saved/read from localStorage
  • Add "On this page" table to contents

This mega-PR contains the following PRs:

  1. Remove renderer (framework) from URL #620
  2. Upgrade to React 18 #623
  3. Docs sidebar #621
  4. Refactor RendererSelector to pill-based design #624
  5. Update pill menu design #627
  6. Add "On this page" TOC #628
  7. Docs design refresh fixes #629
  8. Highlight current page in sidebar, and other fixes #630
  9. Various TOC improvements #631
  10. Refreshed code snippets #632
  11. Fix snippet loading state styles #634
  12. Update redirects to match changes in monorepo #635

How to test

Note

QA'ing the following steps is much more valuable than an in-depth code review, at this time

  1. Open the deploy preview
  2. Notice the lack of a renderer (framework) in the URL 🎉
  3. Confirm that the renderer pills + menu (under the title) look and feel correct
    1. Confirm that it is highlighting the correct renderer (React, by default, or whatever is in your localStorage1)
    2. Confirm that you can choose another core renderer (React, Vue, Angular, Web Components)
    3. Confirm that both the page content and the localStorage value1 are updated correctly
    4. Confirm that you can choose a community renderer (under the More menu)
      1. Confirm that your selected community renderer has taken the place of the last pill (Web Components)
      2. Confirm that the last pill is now first in the More menu
      3. Confirm that your selected community renderer is not in the menu
    5. Confirm that you can select a core renderer when a community renderer is highlighted
      1. Confirm that all of the pill + menu manipulation from the previous step is now undone
  4. Make note of your current renderer
  5. Open the deploy preview's homepage
    1. Under the hero, click a renderer logo that is different than your current renderer
    2. Confirm that you navigate to the Install page and your renderer automatically changes to the one matching the logo you clicked
    3. Confirm that you can still select a different renderer
  6. Check updated sitemaps
    • Here are helpful diffs (production on left, this PR on right), generated on the latest version:
  7. Check updated generated redirects
    • Here's a helpful diff (production on left, this PR on right), generated on the latest version
  8. Confirm that the header is fixed to the top of the viewport
  9. Confirm that clicking a heading anchor icon places that heading immediately under the header, with no overlap
  10. Confirm that the sidebar looks and feels correct
    1. Confirm that it scrolls and behaves "sticky" correctly
    2. Confirm that the current page is highlighted in the sidebar
      1. Confirm that when the current page is under an accordion, that accordion defaults to an open state
    3. Confirm that you can navigate via the sidebar links
  11. Navigate to a page with code snippets
  12. Confirm that the code snippets look and feel correct
    1. Confirm that the icon and title (filename) are correct
      1. Confirm that terminal snippets have no title
    2. Confirm that the copy button works
    3. Confirm that relevant snippets display "JavaScript", "TypeScript" and "TypeScript 4.9" in a menu in the snippet toolbar
    4. Confirm that snippets with only "npm", "pnpm", and "yarn" options display those options in a menu in the snippet toolbar instead of tabs
      1. Confirm that the selected value is either "npm" (the default) or the value in your localStorage1
      2. Confirm that choosing a new value updates your localStorage1
    5. Confirm that necessary snippets still use tabs (Vue is a good renderer to find these)
    6. If you know of any particularly interesting combinations of snippet types, check those ;)
  13. Navigate to a page with lots of headings, like the argTypes API reference
  14. Confirm the "On this page" feature renders correctly
    1. At viewports > 1508px, it should be expanded, in the right rail
      1. Also confirm that the overall page layout looks correct, with no overflowing content
      2. Click one of the links
        1. Confirm that you are scrolled to the correct heading and that it appears visibly, just under the sticky header
      3. Find a page with lots of headings (argTypes API reference is a good one)
        1. Shrink your browser's viewport vertically until the full "On this page" section can't fit
          1. Confirm that the scrolling works as expected
    2. At viewports <= 1508px, it should not render
  15. Navigate to a page with less than 4 headings, like the Install page
    1. Confirm that the "On this page" feature is not rendered

The rest of these steps can only be tested with the corresponding content changes. I've made a special deploy preview for this purpose.

Most importantly, click every link you can, in content and the sidebar, on a variety of pages (top-level, e.g. Writing stories; mid-level, e.g. Args; and third-level, e.g. Configure TypeScript).

  1. Open the deploy preview with content changes
  2. Confirm that you can click each top-level sidebar heading (Stories, Tests, etc)
    1. The Sharing and API pages are new!
  3. Confirm that clicking the "Get started" heading redirects you to "Install" (which is a temporary workaround, until the docs homepage is available)
  4. Confirm that the "Edit on GitHub" links work correctly (it'll 404 right now, but the URL should work if you change next to changes-from-docs-updates)

Rollout plan

Order matters!

  1. Merge Updates for new docs design components-marketing#71
  2. Merge this PR
  3. Propagate components-marketing updates across other sites
    1. Update Tutorial's SubNav to refer to "Documentation" instead of "Guides"
  4. Check prod with current content
  5. Remove framework facet from Algolia DocsSearch config and kick off a crawl
  6. Merge Docs: Changes corresponding to docs design updates storybook#24925
  7. Immediately cancel any Netlify deploys that are kicked off
  8. Manually run the Push all release branches action
  9. Check prod with new content
  10. Remove all uses of framework:agnostic across all sites

Footnotes

  1. In Chrome, at least: Open DevTools → Application tab → Expand Local storage under the Storage heading in the left sidebar → Click on the URL for the deploy preview ↩ ↩2 ↩3 ↩4

kylegach and others added 13 commits November 7, 2023 10:19
@kylegach
Add @chromaui/tetra
cc8934a
@cdedreuille
Add combobox
1508147
@kylegach
Remove renderer (framework) from URL
ff54027 
- Read/write localStorage value instead
@kylegach
Add support for renderer query param
03f0597 
- When provided, it auto-sets the localStorage value to the param's value
- Use it for framework logos on homepage
@kylegach
Update redirects
fd6757c 
- For each version & framework combo, add:
    `/docs/<version?>/<framework>/<path>` -> `/docs/<version?>/<path>`
- Update static redirects to no longer point to URLs with framework
@kylegach
Refactor IfRenderer -> If
8d85d37 
- Only filter content client-side
- IfRenderer still available in MDX, for older content
- Update CodeSnippets to account for client-side-only filtering
@kylegach
Consistently use renderer instead of framework
2757730
@kylegach
Use @storybookjs/components-marketing canary
c37a438 
- See: storybookjs/components-marketing#71
@kylegach
Merge pull request #620 from storybookjs/remove-renderer-from-url
fc6c9d0
@kylegach
Upgrade to React 18
6bafd5f
@kylegach
Merge pull request #623 from storybookjs/upgrade-react-18
7b98bc4
@cdedreuille @kylegach
Docs sidebar (#621)
6e0d66e 
Co-authored-by: Kyle Gach <[email protected]>
@kylegach
Refactor RendererSelector to pill-based design (#624)
bd54ecc
@netlify Netlify
Copy link

netlify bot commented Nov 15, 2023 •
edited
Loading

✅ Deploy Preview for storybook-frontpage ready!

Name Link
🔨 Latest commit ff61c1e
🔍 Latest deploy log https://app.netlify.com/sites/storybook-frontpage/deploys/6565678b2080630008b71cd9
😎 Deploy Preview https://deploy-preview-626--storybook-frontpage.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@socket-security Socket Security

This comment was marked as off-topic.

Sign in to view
@socket-security Socket Security

This comment was marked as off-topic.

Sign in to view
@cdedreuille @kylegach
Update pill menu design (#627)
60a196b 
* Move everything into RendererSelector

* Remove old pill

* Improve design of the content menu

* Try not use as modal

* Update RendererSelector.tsx

* Fix styling

* Update RendererSelector.tsx

* Fix focus state on pills

* Update RendererSelector.tsx

* Tweaks

- Prevent forwarding `isActive` to DOM
- `React.FC` should only be used for components that accept `children`

---------

Co-authored-by: Kyle Gach <[email protected]>
@kylegach kylegach mentioned this pull request Nov 16, 2023
Merged
@kylegach kylegach mentioned this pull request Nov 20, 2023
Merged
This was referenced Nov 20, 2023
Closed
Merged
@kylegach kylegach force-pushed the docs-design-refresh branch from 03a46d7 to c223f89 Compare November 21, 2023 05:14
@kylegach kylegach marked this pull request as ready for review November 21, 2023 05:37
@domyen
Copy link
Member

domyen commented Nov 21, 2023

I wrote a list of issues found during QA here

Heads up, the sitemap diffs no longer exist so wasn't able to QA that.
image

@kylegach kylegach mentioned this pull request Nov 27, 2023
Merged
@kylegach
Copy link
Collaborator

kylegach commented Nov 27, 2023 •
edited
Loading

@domyen — Thank you!

Those diff links expire after 7 days, which is why they 404'd. I just re-generated them using the latest code, and would appreciate you checking them! The relevant portion (with new links) is quoted here:

  1. Check updated sitemaps
    • Here are helpful diffs (production on left, this PR on right), generated on the latest version:
  2. Check updated generated redirects
    • Here's a helpful diff (production on left, this PR on right), generated on the latest version

@domyen
Copy link
Member

domyen commented Nov 27, 2023

Reviewed the sitemaps, it looks good to me!

@kylegach kylegach merged commit 1f6e1cb into main Nov 28, 2023
5 of 6 checks passed
@kylegach kylegach deleted the docs-design-refresh branch November 28, 2023 04:21
@kylegach kylegach mentioned this pull request Nov 28, 2023
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@cdedreuille @domyen @kylegach