Webview UI Toolkit

January 2020 – July 2020
System Design | Visual Design
Microsoft | Developer Division

Project overview

While working on VS Code extensions in the Developer Division, I saw the need for a more cohesive set of UI/UX patterns and controls for webviews in VS Code. The extension toolkit is a UI component library for designers and developers to use while building web views for their VS Code extensions.

My contribution

I initiated this project because I saw a need while working on other projects within team. I lead the initial effort for the toolkit (design, research, and documentation).

Setting the scene

What’s VS Code?

Visual Studio Code (VS Code) is a light-weight, open source, code editor that can be customized through first and third-party extensions.

Why are extensions important?

Without extensions, VS Code is a pretty simple text editor, but the extensions bring a lot of the magic. Extensions can provide features like language support, special debugging features, data visualization, etc.

What's a web view?

A web view is an iframe within VS Code that an extension controls.

PHASE 01

Identifying the problem

While I was working as an extension designer I continued to run into the same few issues no matter project. I also realized other designers and engineers across Microsoft were struggling to create cohesive extensions for VS Code for a few reasons:

There was not a design system for webviews

No design system or pre-defined patterns resulted in designers and engineers alike creating one-off solutions. This wasn’t very efficient and lead to more fit-and-finish errors and product inconsistency. Designers not family with VS Code also struggled because the existing patterns and best practices were not well documented at the time.

Teams needed to maintain custom UI

Maintaining a custom UI is costly and can lead to a number of issues ranging from minor fit and finish bugs to larger accessibility bugs. One of the biggest complaints we heard from teams was integrating VS Code’s color tokens was confusing and sometimes difficult because the tokens had very specific names and use cases. This process requires a deep understanding of how VS Code's color themes work and the ability to predict how other themes handle colors. This is easier when it comes to the themes that ship with the product, but becomes more difficult when third-party themes are introduced.

Inspiration

When I looked across the landscape of first and third party extensions, I realized there were a lot of different design needs. Some applications just needed a data grid, some wanted to make a simple GUI introducing their product, and other wanted to create complex dashboards and experiences all within the webview. That’s a pretty big range of needs, but I decided to start with something I knew and use the Fluent Web design system as a base.

VS Code in a standard editor arrangement.

PlatformIO is an example of a complex, third-party extension in VS Code

What is Fluent?

Fluent is Microsoft’s design language and Fluent Web is library of components specific to web applications. I chose this as a starting point because one of my main goals was to improve the experience for designers working inside of Microsoft and many of those creating extensions around the company were converting products and experiences already made in Fluent Web into experiences for VS Code.

A quick look at the fluent component library.

Example from current VS Code toolkit

Left: VS Code button, Right: Fluent Button

The “Ah Ha!” moment

After assessing my own experiences and the experiences of other designers and engineers working across Microsoft I had my ah-ha moment. I decided I should createa library of controls to share with the greater VS Code community, in turn making it easier for people to design and build extensions and eventually making a more cohesive product and customer experience.

PHASE 02

Design explorations

Designing a Figma Toolkit

As I mentioned above, I used the Fluent Web design library as a basis for my new webview toolkit. I audited all the controls and met with the primary VS Code designer, Miguel Solorio, to determine which pieces we felt should and should not be included in our own set.

I then began building out the components in Figma. All of the components are built using Auto Layout, a feature that allows the components to adjust in size driven by things like the amount of text, the number of assets, etc.

The design toolkit includes:

  1. Buttons
  2. Text Fields, Search
  3. Dropdown, Spinbutton
  4. Toggle, Checkbox, Radio
  5. CommandBar, Pivots
  6. ContextMenu
  7. Lists (tables)
  8. Markdown Preview Style guide

A quick overview of the webview toolkit in Figma.

What's a Figma toolkit?

Figma toolkits allow designers consuming the library to gain access to components and styles and use them in other files. Updates to the component library file also appear in files consuming the library. Makes life a bit easier :)

Examples of VS Code styled inputs for webviews.
Examples of VS Code styled pill toggles for webviews.
Examples of VS Code styled command bars and pivots for webviews.
Examples of VS Code styled grouped lists for webviews.
Examples of sample page patterns for webviews.
No items found.

PHASE 03

Testing & Validation

I met with five designers working in different parts of Microsoft that have worked on VS Code extensions; one from Teams, two from the Data Integration Team, and two on the Azure Data Studio team. In each of the interviews, I asked the participants to share their experience with Figma before jumping into discussing the toolkit. The participants ranged in experience, some have only been using Figma for a month or so, while others have been using it for over a year. All the participants had prior experience using toolkits and libraries and only one or two had experience using Auto Layout in Figma.

Findings

All of the participants were able to navigate the toolkit and find different components. When it came to consuming the components in another file, some participants used the Assets panel in Figma, while others preferred to copy and paste components from the toolkit file. All of the participants discussed having a difficult time figuring out best practices for webviews in VS Code. Some mentioned looking for guidance in the VS Code Docs but said they couldn't find any. Three of the participants said they would like to see documentation explaining the different surfaces available in VS Code and how to use them.

Some not so formal testing

In addition to the study I ran with designers form across Microsoft, I also worked closely with different designers on my team who use Figma toolkits in their day-to-day. This project was during the early stages of component libraries at Microsoft so it was helpful to get feedback from designers using a variety of toolkits that were organized and maintained in a variety of different ways.

PHASE 04

Looking ahead

As with most, if not all, projects there's always a time when you move on to something else and another designer takes over. Towards the end of my time working on the toolkit, I knew I was transitioning to a more branding and visual design oriented role. This made me want to make sure the project was in a good state to hand off and easy for others to pick up where I left off.

Creating documentation

I determined we needed basic guidelines stating when to use what controls, how they should and should not be used, etc. Because our toolkit was heavily based on the Fluent Web Framework, I was able to heavily leverage the existing documentation and guidelines. I only needed to rework some of the guidelines for our specific use cases.

Prepping for hand off

As a part of this “final prep process” I cleaned up all the files, created documentation, and compiled notes to hand off to any future designers and developers working on the project. A few months after shipping our initial design library, a design technologist, Hawk Ticehurst, began building out web components for extension developers to use when creating their own extensions. Fellow DevDiv designer, David Dossett, later joined the team and began working on the toolkit. Version 1.0 of the toolkit launched on April 7, 2022.

What I learned from this project

If you’re struggling with a problem, chances are you aren’t the only one.

I was struggling with a lack of documentation and guidance, and I worked on the larger design team! This problem was even more significant for folks who couldn’t just walk up to the product designers or developers and ask questions. By solving the problem I was personally facing, I ended up helping a lot of other people.

Even if you make something great, people won’t use it if they don’t know about it.

The best solutions aren't very helpful if people don't know about it. While developing a carefully thought out system was really important, it was also really important to share these resources with the larger community. This is not a one time thing, but a regular action that needs to be taken so everyone is included and made aware of the resources they can use.

It is really gratifying to make a complicated thing easier.

Theming extensions in VS Code still remains a challenge for people building their own custom UI, but the toolkit made this issue a bit easier.