design
design copied to clipboard
Skunkworks 10/23 - Docs Redesign
This PR implements a redesign of our component documentation pages on .design worked on by me and @sooachung over Skunkworks in Oct 2023.
The PR introduces several new features including:
- Support for authenticated content pages
- New design that replaces tabs with a single scrollable interface
- Sticky breadcrumbs to better support the scrollable interface
- Support for a new LiveExample block content type on Contentstack that will allow us to insert LiveExamples into our design guidelines
- Support for a new image gallery content type on Contentstack
- Support for code blocks for each storybook function definable in the function's
parameters
- Integration with the
experimental
branch on Contentstack, which can be used in the future for similar blue-sky changes to .design
As presented in my Skunkworks demo, these are the visioned benefits of this change:
- It allows us to document our components in a use-case driven way in an attractive and user-friendly interface.
- All information on our design system lives in one place.
- Everyone gets their questions answered before they have to come to us on Slack.
- They get to just enjoy the visual sexiness of the new design!
For maximization of the updates made here, I recommend updating our design guidelines on Contentstack to resemble the guidelines for TextInput on the experimental
branch of our Contentstack instance. This is an example guideline that Sooa and I have created to demonstrate how powerful these new updates can be.
Other changes that would help make the most of these features are:
- To migrate the LiveExample content type from the
experimental
branch tomain
on Contentstack. - Add code snippets to its
parameters
as demonstrated in this PR - Migrate the TextInput component documentation from the
experimental
branch tomain
on Contentstack.
Not making the above changes and merging this in would still ensure the layout changes and breadcrumbs are added to our website. If I were around to help push this through, I would've gotten this PR reviewed, then applied the above changes, and then asked our users for thoughts on the new guidelines format proposed with the TextInput guidelines. IF feedback was positive, then similar changes could be made to other components moving forward. If the changes were applied, it would be best for engineers to get in the habit of contributing to guidelines as the goal of this initiative is to combine engineering docs with design docs.
--
The LiveExample content type on Contentstack works by identifying stories on Storybook by function name. For example, the States Demo
story on Storybook is defined by the function StatesDemo
in the Storybook file, and that's what should be populated in the LiveExample entry on Contentstack.
--
Aspects of this PR I consider a little incomplete are:
- Code style
- Reliability/accuracy of the scrolling breadcrumbs
- Error catching on LiveExample blocks
This PR would also address the following tickets: