Scope
I worked on the UX and development of the website and had help from a UI designer for the brand and typography elements. I initially started work on the project in Fall of 2019 with a scope of 4 months to have the website designed and developed before the new year. At this stage in the project, we had a pre-existing website that was literally a one-page scroll using basic HTML/CSS. We also have a React UI Kit in Storybook that developers were already using, but the code documentation only existed on Storybook. This was a side project, with some directional guidance from a senior developer and senior UI designer who was in charge of designing the components.
As VSTUI React Kit is gaining usage internally, more and more people are visiting the web page to find information. We needed a new page that makes finding information easier for developers and product managers. I started the project off by collecting requirements from the stakeholders and then completing some initial secondary research and competitive analysis which I had to present to design leadership. The old system was coined VSTUI and renamed Stewie to respect the newly update design system.
Competitive Analysis
Design Systems
The following are the list of design systems I analyzed during this research and discovery phase.
Ethos
Companies often have an ethos or philosophy for their design on the main landing page. This ethos trickles down to how employees and users perceive the design system and how each component was designed and developed with this in mind. They often answer the following questions:
- Why was this system built and for whom?
- What is the belief or set of principles behind this system?
- How is this system governed and by whom?
- Why do we need this design system?
VitalSource defines our system as way to efficiently create cohesive content that everyone can access. Our system places very strong emphasis on the accessibility of our content for every user. The system is governed by a core group of designers and developers.
“IBM has always served as a medium between mankind and machine, blending science, service and society to pave a path towards progress.”
IBM Design System
“Our design system helps us work together to build a great experience for all of Shopify’s merchants.”
Shopify Polaris
“Fluent is an open-source, cross-platform design system that gives designers and developers the frameworks they need to create engaging product experiences—accessibility, internationalization, and performance included.”
Microsoft Fluent
Ecosystem
Companies with multiple ecosystems tend to have a landing page that links to each subpage. We see this pattern with large companies like IBM, Apple, Google and Microsoft. They have multiple physical products with each one having unique UI and UX requirements. Their design systems are exhaustive and very different from VSTUI. Our design system caters to a smaller pool of digital products across different devices. We don’t produce physical products, which makes having a cohesive digital experience a lot easier to manage and scale.
Larger companies also unify their disciplines into one cohesive page. Brand, Marketing, Industrial, Product and Content all live under one design system page and each have their own category and subpage. VST has documentation on Marketing materials that live in various Confluence pages, and various developer documentation and repos that exist in other formats. The fragmentation can be resolved by simplifying and uniting the Marketing page into the design systems workflow. This will further enhance cross-discipline communication and on-boarding, and provide a strong, cohesive language. We will continue to work on our brand, but including what has been documented thus far in our design system is vital to strengthening the core message.
Navigation & Search
Sidebars are very commonly used for navigation across design systems. This is mostly due to the ease of seeing everything at once and the necessity of grouping large amounts of datasets. Verticality provides unlimited space for a growing design system because additional content can be appended or nested into descendant navigation. Content is hierarchically stacked intentionally based on workflow or relevance. Where relevance is not necessarily of importance, content is alphabetically sorted to help users easily find content. Search is another functionality that is helpful for users when they can’t find what they are looking for in the design system.
Information Architecture
Finally there was that big question: How we do organize the site’s content to fit our users’ needs (developers, stakeholders, and designers)? The goal is ultimately have one unified documentation site to avoid the pitfalls of a fragmented system that is update separately. This would also make it easier to send all users to the same page and have the same experience. Patterns and components would have a section for usage, style, and code which includes both design and developer documentation for each component.
Feedback
Before we consider redesigning the site, we needed to know what was important to the users browsing through VSTUI. I interviewed two developers using the design system at different intervals and a project manager to get their feedback. Below are some of the key points and pain points for the users.
Pain Points
- Keys are hard to remember or find in Github repo, so it would be nice to have them on the website for reference.
- There are discrepancies from the UI kit and the documentation that needs to be kept up to date.
- Not a fan of JIRA Confluence as the previous documentation method.
Improvements
- The documentation website should be a reference for both design guides and API docs. Docs should only change with major releases.
- I want to see real, live examples of components.
- I’m hungry for whatever I can find that describes/demonstrates interactions and behaviors.
Limitations
There are limitations around how the project can be developed in order to make it easy to maintain by designers. Originally, my research led me to leveraging Gatsby CMS and React to tie in Storybook, but stakeholders did not like that it would require specific knowledge to setup and maintain the CMS. Although using React would allow us to leverage our own React library of component, this would also mean designers could not maintain it easily. Thus, we settle on using vanilla Javascript to create the dynamic parts of the documentation website and JSON as the way to handle storing and changing the data served to the website. Designers can modify the JSON and upload it to the server, which is then read by basic Javascript functions to manipulate the DOM.
Page Template
Pages are loaded using one template similar to how react is a one-page application. However, unlike React Routers we had to use anchor hashtags to load specific pages. In a future refactor, the proper URL forming would use query strings or other parameters so that we can save anchor hashtags for scrolling to specific points on a page.
.../stewie/pages/page.html#components-button
.../stewie/pages/page.html#gettingstarted-developer
.../stewie/pages/page.html#patterns-accountentry<body>
<!-- Navigation -->
<div id="nav"></div>
<div id="body-container">
<div id="page-header">
<!-- Header Content -->
<div id="Header-content"></div>
<div id="tab-navigation" class="hidden">
<button
class="tablink"
onclick="openPage('Usage', this)"
id="defaultOpen"
>
<a>Usage</a>
</button>
<button class="tablink" onclick="openPage('Style', this)">
<a>Style</a>
</button>
<hr id="highlight" />
</div>
</div>
<!-- Tab Content -->
<div id="content-container">
<div id="content-inner" class="hidden"></div>
<div id="component-content-inner" class="hidden">
<div id="Usage" class="tabcontent"></div>
<div id="Style" class="tabcontent"></div>
<div id="Code" class="tabcontent"></div>
</div>
</div>
</div>
<!-- Load Navigation Javascript -->
<script src="../js/content.js"></script>
</body>Dynamic Structure
Designers would be able to use the folder structure of sites to upload JSON files that contained information about components. As long as designers had a template for this JSON and knew the folder structure, they would be able to create component pages easily and quickly. The code would then fetch the endpoint and generate the page using the JSON file and also alert the designer if they have missed a key value or had a typo with a UI error.
Human Readable JSON file used by Designers:
[
{
"header": "Buttons",
"description": "Clicking or tapping a button invokes an action."
},
{
"usage": {
"demo": "True",
"principles": [
{
"title": "Findable",
"body": "Buttons should be recognizable and easily located amongst other elements."
},
{
"title": "Actionable",
"body": "Buttons should indicate or convey that they trigger actions."
},
{
"title": "Understandable",
"body": "Buttons and their triggered actions must be clear to everyone."
}
],
"guidelines": [
{
"title": "Placement",
"donot": {
"image": "dont.jpg",
"body": "Don’t stack buttons when there is space for them to be placed side by side."
},
"do": {
"image": "do.jpg",
"body": ""
}
}
...
"style": [
{
"header": "General Styling",
"specs": [
{
"title": "Relative Sizes",
"image": "relative-sizes.jpg",
"list": [
"Text sizes are relative to button sizes (14, 32; 16; 40; 18; 48).",
"Button text uses Roboto Medium 500."
]
}
...
]
}
]
}
]Fetching the JSON with a callback if it is not in session storage and appending elements into the DOM. Similar methods were used to load the side navigation. The performance here is measured in O(n) time, which is linear to the items in the JSON file. The load time is minimized because data is pulled from sessionStorage if the page has previously been loaded, but the files are also quite small.
function loadComponent(component) {
// Using the same template and change it to component view
switchComponentView();
// Fetch the current JSON if it is not in session storage and the page is empty
loadJSONFile("components", component, function (json) {
const header = document.getElementById("Header-content");
const usage = document.getElementById("Usage");
const style = document.getElementById("Style");
var isEmpty = header.innerHTML === "" && usage.innerHTML === "" && style.innerHTML === "";
if (isEmpty) {
// Calling separate methods to generate the elements to be appended to the DOM
header.appendChild(createHeader(json[0]));
header.appendChild(createDescription(json[0]));
usage.appendChild(createIframe(json[1]));
usage.appendChild(createPrinciples(json[1].usage["principles"]));
usage.appendChild(createTypes(json[1].usage["types"]));
usage.appendChild(createGuidelines(json[1].usage["guidelines"]));
style.appendChild(createStyles(json[1].style));
}
...Component Examples
The example section of each component page was an iframe that pulled data from Storybook. In the next iteration of the site, further exploration with the design system engineers is necessary to upload props, usage, and more examples for the Code tab of the website.
Final Thoughts
POJO
Using Javascript was definitely a challenge as this meant everything was written from scratch. There was definitely more work involved rather than being able to leverage Reacts capabilities. While there are javascript libraries for certain functionalities, they come with too much built in and it was much faster to load self-written algorithms.
Four 9s
The previous site was one giant HTML file. This meant that editing the site was cumbersome because you had to know where everything was on the 10,000+ lines of html code. Secondly, every time an edit was made and there was a bug, the entire site was taken down. The new refactored site loaded each page individually based on JSON files. If there was a bug, the designer would see a UI error only on that section of that page. Since the entire site is separated over multiple files, editing only affected single instances of the site. Changes are now reflected locally and then committed to the Github repo before committing the changes to production. This meant that the documentation site was always available to users.
ReactJS
Whenever we refactor the site again, we should really leverage React and our own UI Kit. There is no advantage in using JS to create a website for a React Component Library; however, leadership wanted the code base available to designers to modify when necessary. They didn’t want to have development as a bottleneck for updating the documentation website. However, in retrospect, we can still leverage JSON files as a way for designers to update the site while the core of the site is built on React.
Accessibility
While the design was tested for contrast accessibility, the code was not developed with accessibility in mind. This was a big undertaking as the site’s documentation has a lot of images. Since the site was developed for internal employees, accessibility was not a top priority. We would have accessibility built in if we utilize our own React library. If we continue to have the site built on plain JS, we should prioritize this for the next iteration to be inclusive of all employees and outside visitors.