New post: What makes a design system good #513
Merged
Conversation
This file contains 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
harriplappalainen
force-pushed
the
master
branch
from
dceecd5
to
6bdece6
Compare
tatut
reviewed
Jan 23, 2024
|
|
||
| ## Documentation | ||
|
|
||
| Documentation is the first place the users will flock to when they are interested in or about to use a design system. Best place for docs is a dedicated website in my opinion, made with easy-to-use frameworks such as Next.js or Gatsby. First off, the home page or the navigation bar should offer links to the most important parts of the design system. To figure out what are the important parts, we need to understand the different roles in the target audience. Developers implement the components, so they need information about the components and how to get started. Designers want to look at the designs, guidelines, and patterns on how to approach different use cases such as form validation. Product owners are interested in why they should use the design system and how it would improve their product’s development on a day-to-day basis. Documentation is a benefit for the team behind the design system as well as it helps newcomers to get familiar with it. When we have figured out the needs of the users, all we need to do is provide them with quick paths to satisfaction. A good example of a documentation site is <a href="https://hds.hel.fi/" target="_blank">hds.hel.fi</a> which received positive feedback for being clear and informative. People especially liked components docs because of live code editors which allow users to test the components in a quick and easy fashion. |
There was a problem hiding this comment.
why does the technology used to create the website for the DS affect if the DS is good?
do they have some unique advantage that you could elaborate on
| Documentation is the first place the users will flock to when they are interested in or about to use a design system. Best place for docs is a dedicated website in my opinion, made with easy-to-use frameworks such as Next.js or Gatsby. First off, the home page or the navigation bar should offer links to the most important parts of the design system. To figure out what are the important parts, we need to understand the different roles in the target audience. Developers implement the components, so they need information about the components and how to get started. Designers want to look at the designs, guidelines, and patterns on how to approach different use cases such as form validation. Product owners are interested in why they should use the design system and how it would improve their product’s development on a day-to-day basis. Documentation is a benefit for the team behind the design system as well as it helps newcomers to get familiar with it. When we have figured out the needs of the users, all we need to do is provide them with quick paths to satisfaction. A good example of a documentation site is <a href="https://hds.hel.fi/" target="_blank">hds.hel.fi</a> which received positive feedback for being clear and informative. People especially liked components docs because of live code editors which allow users to test the components in a quick and easy fashion. | ||
|
|
||
|
|
||
| I find that components are the ‘meat’ of a design system, so their behavior and specifications should be explained in depth. <a href="https://storybook.js.org/" target="_blank">Storybook</a> is a great tool for displaying isolated components and demonstrating all their possible use cases. With Storybook the users can browse the component’s props, fiddle with them in a live demo and read the component docs if you wish to add those there as well. Stories work well with visual regression testing too, e.g. <a href="https://www.chromatic.com/" target="_blank">Chromatic</a> or <a href="https://loki.js.org/" target="_blank">Loki</a>. Speaking of testing… |
tatut
approved these changes
Jan 23, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
A frontend developer's personal view on what are the most important parts of a design system that provides value.