Utility research synthesis

Patterns and themes found in six user interviews

Utilities feature goal

1. The utilities feature helps people modify their existing projects easily.

2. The utilities feature helps people create prototypes easily.

3. The utilities feature helps people try out new ideas easily.

Personas

1. Experienced front-end designer (3)

2. Beginner developer with no design expertise (1)

3. Visual designer with limited development expertise (1)

4. Program director with some front-end expertise (1)

TOC

Themes and patterns

Utilities help people build websites more easily

• For getting a prototype together, utilities work well

• I’d use the system I see here for prototyping, I would not use it on a finished product

• Utility classes let you feel like you have control, you can change it to your liking

• I enjoy being able to tinker and change things around, but I would have a really hard time setting anything up from scratch, I’m not sure where to start.

• Colors seem like they're a good use for utilities, seem easier to understand than classes associated with spacing and alignment (responsive) since it’s hard to understand the context of the element.

• You’ve done a lot of work to make it intuitive. When I played with it most of it just worked.

Legible classes are easier to understand

• Descriptive class names helps to bridge the gap between technical and non-technical, the translation there is easier there for both folks.

• It's nice to be able to determine the actual attribute of a class like "padding"

• I do like that this is a bit more explicit, it reminds me of Shed, which is easier to read, but when things start getting bigger, you think good lord, there is a lot going on, but it is handy especially if it’s documented well

• I’ve seen things like s, m, x, xl, but I think the thing that is weird about that is needing classes like xxs, I feel like the "small" scale it more descriptive.

• When I was in the actual code it could help me see the existing classes which was a better way to collaborate.

• Margin-t, t for text?

• I like the idea of t-shirt sizes, it’s easy to learn a label, hard to learn a value

We also heard a few thoughts preferring shorter syntax:

• I’m accustomed to tachyons shorter syntax like .p1

• The more I use tachyons the more appreciate the terseness of it

Users want the actual values (colors and sizes) mapped to their corresponding token/class

• With tachyons, I use the class declaration to search the documentation

• It would help to see the absolute size especially for something like 1p5 to see what the scale is actually.

• I might want some more examples to demonstrate some of the utilities

• If you’re talking about colors then some of the actual utility classes are paired with it

• Seeing neutral and primary in docs, but would like to know what those colors actually are.

• I thought it was a little weird there was no color swatch next to primary, what is the default, where are we starting from?

• It’s hard to understand what green warm is, in terms of what that would look like, without an example next to the variable name.

• I would expect to see a color palette associated with the different colors

• I’m looking for the default palette, I’m looking for these to correlate with a style guide where they tell me what those values actually are.

Users want to know the limitations of the system

• How many px units are there for border? Does it go to 22?

• Is there a u-background-color-white-1, and 2, 3, etc?

• I’m not sure where (margin and padding values) ends, does it go up to 100?

• Why does border-1px have a px on it when the others don’t?

• I’d have to get to know what "modifiers" means

• I’d be curious also if I could use a direct value for a line height, like line-height-28

• I also don’t what it’s half of? What is 1?

• I don’t know if there is a "normal" (font) option

• Sometimes it’s hard to know what the parameters of the code structure are

• I like seeing the constraints and guidelines of an existing project, and would not mind if design system came with preset out of the box values until we found something that needed to be designed outside the system

• There’s no border radius xl (when there was xl for another sizing)

• Border black 20, what does 20 mean? Is that the opacity?

• Do the numbers work with bg-neutral?

Most users didn’t understand the meaning of the u- prefix and its meaningful difference between the usa prefix

• Why is something usa- and why some are not (referring to u-)

• Why am I seeing usa-u? I need to read to figure out why it’s like this

• I don’t know what u- is or the 6 in the class, but i could start deducing it

• U- means unit? Although that doesn’t really make sense

• U- vs usa-, maybe the u- is just a shorter version of usa-

• Forgets to use the u- prefix when copying code

• I don’t know if I like u-. I’ve used usa- and I like that better. Maybe just remove the u- prefix altogether, but then you may encounter conflicts if you’re using another library.

• Usa vs u - I think the u is much better, it’s more utilitarian, it ties more in with utilities.

• The usa prefix carries too much branding, I don’t think it’s needed. I would imagine that usa is a custom class name, whereas the u- classes are more generic.

• I can see where u- might get confused with usa-, but I understand it as utility

Users want straightforward, practical, concise docs, and get overwhelmed by long documentation and content

• (the color doc) feels overwhelming, but I may come back and read it later, but it isn’t immediately helpful for find out about class

• Color guidance should not be theoretical and overly academic

• Having all of this (docs) is a bit of a firehose

• (likes?) having a narrative inline with the examples

• I do not tend to read documentation. I'd look at examples, and finding code related examples, before going to the more educational pieces

• In documentation, grouping by like things is helpful, also having all of the classes listed out

• People want to shop, e.g. choose navigation, etc.

• The challenge with basscss/tachyons was their documentation, I just want to be familiar with the limitations are out of the box so I could know what comes prepackaged.

• Basscss has a buried page that lists out all of the utilities which is awesome, I’ll go back to that page.

• Responsive docs, why is there a slash in the examples?

• For hover, I don’t know if I should include "desktop" also

• Why is hover: in the beginning of the class? Usually, it's something you apply after.

• If this was something I was using I would have the documentation open in the other window to reference it

• I don’t think the docs would be in depth. I really like the current docs.

• For utilities, I would only need minimal documentation with an explanation of the number increments, and what those values equal.

• There are a lot of classes here

It was unclear what spacing units (padding, margin) were mapped to, most thinking ems or rems

• I don’t know what u- is or the 6 in the class, but I could start deducing it

• I’m not sure if (margin and padding values) are rems, or ems.

• Padding-6, 6 is not clear on what size unit 6 is

• I’m not sure what to guess what type of units would be associated with the different spacing numbers, they might be ems or rems

• Padding 4: is that ems?

• Now that I know what the values are for, it makes sense

• I like the idea of t-shirt sizes, it’s easy to learn a label, hard to learn a value

• Padding - these numbers, what are they mapped to? Ems rems? I think they should be rems, but they seem kind of granular, a little smaller than what I’d expect to be the base font size. Thought they were based on a 5px scale.

• I’m liking the values your using for the sizing

Users expected padding to go up to 10 and were confused why it only went up to 9

• I would expect the max (of padding values) to be maybe 10, but that doesn’t work. It seems slightly odd to me that it ends at 9, whereas 10 seems like an even amount.

• For padding, I’m curious if that’s a 1-10 scale? (Tries 10, doesn’t work)

• Tries 10 for max padding value

Most users didn’t understand what 1p5 meant

• I’m not sure how p5 relates to that scale.

• I don’t know what 1p5 is, perhaps just the word "half"

Users expect a default set of colors included in the system

• I would expect the library to come with colors, because there have been colors in previous version of USWDS

• I would want colors to include all of the standards colors like blue, red (current palette)

• I would not expect all of the variations of the colors. I’m used to primary, secondary, etc. I’m wondering if you are providing variations that people won’t use

• These preset colors would be good for something like charts, you wouldn’t want to use primary, etc for those.

• I’ve been using the current color palette with USWDS and those are fine, but I want to be smarter about it, and I would want to keep away from too much color.

• Instead of saying here’s the full palette, provide documentation unfold a bit so when you walk through it you start with just black and white and slowly introduce color.

But found a few issues with the way colors were named and responded

• I was surprised to see "neutral" in colors

• Similarly inverse I feel weird about - you have black and white, and then inverse and I feel like you could achieve inverse either way. Inverse to what?

• I see there are warm and cool of some of the colors, but not all of them.

• I’m having a hard time telling whether I’m breaking it or if it’s doing the thing it’s supposed to do

• If I wanted a specific color outside the palette, I would want to choose it myself using a hex value

• Sometimes the red, white and blue color scheme is problematic (too political) that leaned too far one direction or another towards red or blue.

• Tries to use bg-accent (not warm or cool), but doesn't work

• The blue for bg-blue is not the same as the button, it’s not the same hue

• Ok there is no prefix for text color. The rest of these have the property name like border, bg. I would use "color" as the prefix since that maps to CSS.

• bg-black-5, but the background of the card looks gray

• white-1 didn’t make sense bc it was gray

• Thought neutral would be an off white, was surprised when it was dark gray

• Tries changing text color with color-white, text-white

Users tried values in between color numbers, like black-23

• I’d be curious also if I could use a direct value for a line height, like line-height-28

• Adjusting background color, went to value of 8 and it disappeared

• Tried out black-12 color

• Border black 20, what does 20 mean? Is that the opacity? (Tries arbitrary numbers like 63) So is this everything value between 1-100?

• The color value is nice, how to map those to arbitrary values like 23, people might try to do that, maybe limit it to 1-10, instead of 1-100 since you aren’t using that extra zero.

Two users tried to use pink and expected it to be included as a default color

• I would expect there to be pink since that is a default color that ships with browsers. I use pink to test.

• Tried to use "pink" color, but didn't work

Users were confused about the border color, thinking the 20 in border-right-black-20 was a size value

• At first was confused with the border classes, I thought there were two borders.

• Border-color-black-10 is interesting because padding has a size value, and this looks like it has a size value, but I guess it might be a hue

• I don’t get what the u-border-color-black is

• Border-black-20 vs border-1px, I’m not sure what the 20 is

Users found the title of the Scoping section title unclear

• I wasn’t sure what to find in Utility output and scopes, but it didn’t look related to what I need to do with hover. Output makes me think of what the sass would compile too, scope I’m unclear what I’d find.

• Can I just leave off the responsive portion of the class and just do "hover" for example?

• Could utility output just be called responsive?

Users like the constraints of the system

• In working with other teams, sometimes they may not be visual designers, so I optimize for reducing the number of choices

• I’m not trying to get too far away from what the system offers because I’m not a designer

• I like seeing the constraints and guidelines of an existing project, and would not mind if design system came with preset out of the box values, until we found something that needed to be designed outside the system

Users expect all the utilities bundled together and included by default, less choice

• I would like (all the utilities options and code) wrapped up, but some people want to be selective about what part’s they are adding in. If I’m not using it do I want to add all of that code?

• Optional utilities - misc utilities? By reading the docs, my assumption would be that everything is included by default.

• Having two separate libraries, components and utilities could be complicated

But also be more selective in some cases:

• Prefers not to use frameworks. I tend to make modular frameworks. Prefers not to pull in "everything" just the stuff I need

• Compass had a "core", and then modules could be added to it.

Several users mentioned wanting to know performance implications of the utilities

• Am I getting all of these colors with the library, I get concerned with performance

• I would like (all the utilities options and code) wrapped up, but some people want to be selective about what part’s they are adding in. If I’m not using it do I want to add all of that code?

• How big it it really, will it make a huge difference performance wise?

• Prefers not to use frameworks. I tend to make modular frameworks. Prefers not to pull in "everything" just the stuff I need

Users could mostly use font utilities with combined font family and font size

• Totally fine with having the family and size of font in the same class

• I think it’s clever to map the font size and line height to a family, because it does change based on family. It would be cool if you had it set to serif, then the line-height would know that it’s a serif without having to specify serif again

• I would typically do seperate classes like "u-font sans-serif smaller" vs “u-font-sans-serif-smaller”

• I expected there to be a "font-size" since that is how everything else is broken out.

• didn’t know what values between large and small would be for font-size

• If lh-serif wasn’t there I probably would have written lineheight-serif-2

Several users mentioned preferring to work at the component level

• I’m looking at the component level of things more than a utility level

• Utilities tends not to be how I work, I’m more of the CSS Zen Garden school of thought (semantic classes).

• I personally always find myself fighting the system

---

Extra

What things should default to

• I’m used to when I remove a class it would fallback to the inherited style

• I’m having a hard time telling whether I’m breaking it (when I use a wrong class) or if it’s doing the thing it’s supposed to do

The balance of additional behavior built in for common use cases vs. single-purpose control

• When chooses a button background, it would be nice to automatically set the hover color to something that is slightly darker

• I would like the padding to decrease on mobile, I would like the docs to show tell me more about this box.

• One of the challenges was with the grid system, I needed five columns and ended up having to use flexbox to get it to work.

Next steps

Documentation

• Users want straightforward, practical, concise docs, and get overwhelmed by long documentation and content

• Users want the actual values (colors and sizes) mapped to their corresponding token/class

• It was unclear what spacing units (padding, margin) were mapped to, most thinking ems or rems

• Users want to know the limitations of the system

• Users tried values in between color numbers, like black-23

• Users were confused about the border color, thinking the 20 in border-right-black-20 was a size value

• Users found the title of the Scoping section title unclear

• Users like the constraints of the system

• Several users mentioned wanting to know performance implications of the utilities

Talk about

• Most users didn’t understand the meaning of the u- prefix and its meaningful difference between the usa prefix

  • Maintaining the difference between utility and component.

  • Will start building objects like containers, helpers, the space between utilities and components

  • Leaving in the builder

  • Leave off and maybe something to layer on later on

• Users expect all the utilities bundled together and included by default, less choice

  • Use a broader default, but not everything. Support more out of the box.

  • Worry about performance from outputting all

  • Let’s try outputting to all w/o responsive variants (minus colors and breakpoints) and see how it is

  • Output limited set of responsive, hovers, actives

What to do with utilities already in the system?

• Purge them? Or leave them?

• usa-font-sans, sr-only

For future?

• Users expected padding to go up to 10 and were confused why it only went up to 9

• Most users didn’t understand what 1p5 meant

  • 105, 1o5 -

  • 1.5, 1-plus