Orbit, Kiwi.com’s design system, has new documentation
Kiwi.com’s design system, Orbit, has matured a lot since we launched our documentation at orbit.kiwi last April.
We now offer unified components for designers, as well as React developers; and, we also started experimenting with React Native, looking more closely into native mobile development.
orbit.kiwi has always aimed to be a place where you can find everything Orbit-related. In the past months, we’ve been identifying crucial issues with our documentation, and now we have the tools to solve them. As a result, we’re introducing brand new documentation at orbit.kiwi.
Improved structure
In the previous version of our documentation, there were plenty of limitations in content structure. We removed all of them, and now we can adjust orbit.kiwi to any content needs to present the documentation as clear as possible.
Let’s go through the biggest improvements.
New sidebar structure
We split our sidebar into two sections — For everyone’s use and For Kiwi.com’s use — to differentiate the content for the open-source community from the content specifically made for Kiwi.com (such as company logos or content guidelines).
We also created more specific categories for some of the components, these are now:
- UI components — The main blocks for building a user interface (Alerts, Buttons, Badges, Modals, …).
- Layout components — Wrappers helping you align components together (Stack, Grid, Layout, …).
- Utility components — functional utilities, such as Portal, Truncate or Image.
- Accessibility components — Components improving keyboard navigation (SkipLink, SkipNavigation).
Quick access from the homepage
Based on the feedback we got, we highlighted the most visited content, such as the visual style guide, which is now available on the home page.
Also, our team is now available on a new support channel — Spectrum.Chat/Orbit.
Another new feature is the possibility to bookmark any page, which displays it directly on the homepage. Your bookmarks can be also easily accessed from any page through the icon in the right part of the navigation bar.
Better structure for component pages
Whenever you open the component page, you’ll see a header including:
- links to any related APIs (React, React Native, and Sketch to be added soon),
- quick links to Storybook Playground,
- or Github repository.
The component documentation always includes component status to inform you about all the available implementations.
All sections on the page are easily accessible thanks to a new, always-visible table of contents allowing you to jump directly to them. No more scrolling up and down.
You can now easily copy a direct link to any section of the page, just hover over the title and copy the link.
Documenting content and design decisions
As a novelty, the component pages start with a general section that will give you an overview of every component. We started adding the content structure of every one of them, check Alert or Card. The rest will be available in the next few weeks.
Future plans for design documentation
In the next quarters, we plan to add guidelines for accessibility, insights from research and detailed reasoning behind our design decisions to provide everyone with context on why we do the things the way we do.
Adding live examples of components
Until now, live examples of React components were only available on Storybook. Even though orbit.kiwi is not built on React (more on that later), we are now able to render components there. Plus, you can find there working code samples you can copy-paste easily to your projects.
We are still far from having all components covered by live examples, however, we plan to improve this in the next quarter, together with adding a component playground. When this is ready, there won’t be a need for switching between orbit.kiwi and Storybook.
Improved search
We analysed search behavior from the past months and based on the insights we improved our search.
When your search keyword matches a component’s name, it is offered to you as a top result together with the possibility of jumping right into React or React Native API (if available).
We also enriched the names of the components with synonyms so that you can access the content without searching for the keyword we are using. It means, that now you can get info about Select even when searching for dropdown.
Future plans with search
We plan to:
- extend our search with live search,
- display matching design tokens, icons or illustrations.
Still powered by Wordpress
When we launched orbit.kiwi last year, we needed a quick solution for our documentation. The easiest solution seemed to be to use Wordpress, with the plan of creating a “proper solution” later. Even though we were aware that at that moment, it meant a lot of manual work in updating documentation.
When we discussed the next steps for our orbit.kiwi, we agreed that Wordpress, together with Gutenberg, is still the easiest way on how to push our documentation forward. Plus, it also turned out to be an inclusive solution for non-developers contributing to our documentation.
Keeping Wordpress allowed us to use the core part of the previous version of our documentation and thus we could focus on displaying our content better. We created almost 20 Gutenberg blocks that are written specifically for the purposes of a design system documentation. For example, we have blocks for:
- rendering React examples,
- colour palettes connected to our design tokens or
- rendering markdown files fetched from Github.
The previous version of orbit.kiwi required us to do a lot of manual work when updating component’s APIs, icons or design token. Fortunately, we managed to automate all of these processes and we can still enjoy the benefits of Wordpress as our CMS.
We are not ready for open-sourcing the Wordpress template powering orbit.kiwi yet, but we plan to do it later this year.
We’re staying open-source
Kiwi.com’s design system Orbit was an open-source from day one, and thanks to that, we got a lot of feedback we could use when working on it. I can now proudly say that last year was a hell of a journey for Orbit!
It’s always great to see people outside Kiwi.com asking for advice, and it’s even better seeing new pull requests. Although our Github is open for issues, we know that for designers, it’s not a very friendly space.
That’s why we’re also opening Spectrum.chat room for people interested in Orbit. If you have any related feedback for us, we will be happy to hear it there.
Also, if you’d like to help us with the design system documentation, you can sign up here. Don’t forget to mention you’re especially interested in Orbit.
