Project

General

Profile

Design/UX #10439

Create Style Guide for Commons

Added by Sonja Leix 10 months ago. Updated 2 months ago.

Status:
New
Priority name:
Normal
Assignee:
Category name:
Design
Target version:
Start date:
2018-10-04
Due date:
% Done:

0%

Estimated time:

Description

Create a style guide for CUNY Academic Commons to compiles all the site's design elements like typography, link, and button styles, color scheme, consistent padding/margin, etc.

This will help us design more consistently in the future, it will also help the developers to have a reference for implementation. It will be a base to achieve more design consistency across the site and aid as a style library for a potential future redesign.

It will be a living guide and after initial design and internal sign off we should consider creating an HTML style guide. It can live on Github and can be updated over time.

Commons-styleguide_121218.pdf (2.19 MB) Commons-styleguide_121218.pdf Sonja Leix, 2018-12-14 11:17 AM

History

#1 Updated by Sonja Leix 10 months ago

I would approach it by first taking inventory of all existing styles on the site (I assume there are a lot of unnecessary duplicates or variations of styles), then make decisions together which ones to drop/replace to simplify the style guide to achieve more consistent styles. We want to only includes styles we need, e.g. one style for each of these: primary button large, primary button small, secondary button large, secondary button small, link style in text, nav styles (default, hover, active), etc.

#2 Updated by Sonja Leix 10 months ago

Matt,
You mentioned that Chris might have started on a style guide or has done some work on buttons in the past? Is that something you could dig up and share? If not, I'm happy to start from scratch.

#3 Updated by Boone Gorges 10 months ago

Reposting Chris's comment from #9801:

have to disagree about having Sonja spending time doing a style guide or inventory of styles of the current site. It’s a mess and something that we would basically throw out when we redesign. But I do think there are things we could do to document functionality and needs.

Along those lines I have this site I made 3 or 4 years ago that is a start at documenting the current interface elements: https://redesign2015.commons.gc.cuny.edu/

Sonja, I sent you an invite to the site. Let em know if you don’t get it.

Here is the document on buttons that you were referring to Matt: http://www.teachingmultimedia.com/commons/buttons/buttons.html

If you read it you’ll see that there are a number of different styles which are sometimes confusingly used. [Some of these issues have actually be remediated.]

Instead of documenting the styles that we have, I would instead advocate that time be spent documenting functionality and types of interface elements. If we do that it could be a valuable tool for the redesign.

So at a higher level than buttons, but maybe how much do we have an list of items with title, thumb, date, description, or when do we use tabs, etc.

For the redesign we can then focus on whether these are the right interfaces, making a style guide etc.

I would also advocate against what I’m doing here and move the conversation on style guides and redesign to another thread either here in red mine or on the Commons.

#4 Updated by Boone Gorges 10 months ago

To respond to Chris's feedback above: I take your point, but would like to push back against it. For five+ years we have put off incremental visual and design improvements because it felt like a waste to put effort into something in advance of a major redesign. As a result, there are small or medium things we might have addressed years ago that would, in hindsight, have been worth handling, but which have gone undone because of our approach. Let's not continue to do this. If Sonja were to spend a few hours on a styleguide - first, doing a high-level review of interface elements and design, as recommended by Chris, but then also documenting (within reason) existing styles - it's likely that it'd lead directly to us making some meaningful, small changes that would serve us well in advance of a full redesign.

This is predicated on the assumption that Sonja wouldn't be spending many dozens of hours on this project. If that's the case, then I agree that we should limit the scope.

#5 Updated by Chris Stein 10 months ago

Thanks for moving this over Boone. I hear what you’re saying about the continually delayed changes and its a valid point. If Sonja’s time is limited and focused on making the style guide rather than documenting all of the various styles in existence then I’m on board. Those two links represent a lot of hours looking over the site and comparing things. It can be a time sink. That’s my main concern. having a styleguide would be great now and in the future.

Sonja I’m also open to your opinion on how best you can spend your time towards improving the existing interface while helping to set up the major redesign. I can also help doing some of the documentation or other work to help reduce busywork hours for you.

Also there are different versions of style guides, static/dynamic etc., can you tell us a bit more about the form you’re thihking about for the guide?

#6 Updated by Sonja Leix 10 months ago

Thanks Boone for your input! I agree with the approach to not push this off yet again, but use this project to prepare for a major redesign.

Chris Stein wrote:

Thanks for moving this over Boone. I hear what you’re saying about the continually delayed changes and its a valid point. If Sonja’s time is limited and focused on making the style guide rather than documenting all of the various styles in existence then I’m on board. Those two links represent a lot of hours looking over the site and comparing things. It can be a time sink. That’s my main concern. having a styleguide would be great now and in the future.

Sonja I’m also open to your opinion on how best you can spend your time towards improving the existing interface while helping to set up the major redesign. I can also help doing some of the documentation or other work to help reduce busywork hours for you.

Also there are different versions of style guides, static/dynamic etc., can you tell us a bit more about the form you’re thihking about for the guide?

Thanks for sharing those resources and previous attempts. We can certainly use some of these resources to inform this task and give us a starting point.

I agree that given my somewhat limited time on the project, I wouldn't do a full style audit of the website, as I agree a lot of it would likely be wasted leg work. I would rather document the primary design elements (like buttons, typography styles, form elements, etc.) as well as interaction patterns (incl. things like error messages, etc.). From there I would start creating a living style guide (with the help of Boone).

After the first iteration of the living style guide is done, we can focuse on high-traffic sections of the site and identify any missing styles. This will help us make it more and more comprehensive - along this journey we'll likely make a lot of decisions to simplify current styles. We can then start rolling out styles into the site over the next release(s).

This will also be the perfect opportunity to craft a comprehensive design system which will lay the foundation of the redesign. We currently have an extensive list of individual or contextual styles for elements. Which is, understandably so, the current reality due to iterating on the site over the past 5+ years.

How does that sound for scope? Happy to discuss and refine and am always open for suggestions.

#7 Updated by Matt Gold 10 months ago

This all sounds great to me. I appreciate the conscientiousness you are all showing, and Chris's concern that Sonja's time be spent wisely. I do agree that we need to start to move this all forward, and it sounds like Sonja will be able to recognize and step back from potential time-sinks as they approach. So, I would encourage us to move forward on this. Thank you all!

#8 Updated by Sonja Leix 9 months ago

Matt Gold wrote:

This all sounds great to me. I appreciate the conscientiousness you are all showing, and Chris's concern that Sonja's time be spent wisely. I do agree that we need to start to move this all forward, and it sounds like Sonja will be able to recognize and step back from potential time-sinks as they approach. So, I would encourage us to move forward on this. Thank you all!

Thanks Matt, I'll start working on this as soon as the 1.14 release issues no longer need my attention.

#9 Updated by Sonja Leix 8 months ago

For this project I'm looking to create a living style guide (incl. pattern library) – it will be driven by design, but live in code. This way we can all access the same most current version of the style guide. And ideally it's setup in a way that is directly connected to inform the styles of the website – so we only have to make an update to a style in one place. Or vice versa, the style guide is informed by the styles of the website and rendered from there to be up-to-date.

I've done some research into living style guide solutions. But first let me start by sharing a few examples of living style guides out there that I like:
Lonely Planet: https://rizzo.lonelyplanet.com/styleguide/design-elements/colours
Buffer: https://buffer.com/style-guide
CenturyLink: https://assets.ctl.io/cyclops/1.8.6/
Mailchimp: http://ux.mailchimp.com/patterns/forms (not sure if we need actual html code snippets in the style guide)
Chameleon: https://pusher.github.io/chameleon/components/buttons/
U.S. Design System: https://designsystem.digital.gov/components/

We can start with basic styles (like consistent buttons) and work our way towards a more complete style guide. This will help us work towards a full or partial redesign potentially in 2019.

Now we need to look at the technical aspect of living style guides and find a solution that works for us. I'd love to hear Boone's feedback on which solution would make the most sense and is the easiest to integrate and update. I did some research already, but would need to know which direction to go to dig a little deeper for the best solution:
Overview of Pattern Library Generators: https://github.com/davidhund/styleguide-generators (not sure which direction, PHP based, parsing CSS source, Gulp/Grunt, etc.)
More styleguide tools: http://styleguides.io/tools
Chameleon: https://github.com/pusher/chameleon
Pattern Lab: https://patternlab.io/ (might not be exactly what we are looking for, but it's a holistic approach we potentially want to look at for the full redesign)
I worked with KSS on Node before: http://kss-node.github.io/kss-node/

First two links are overview of a variety of tools. Boone, if you could narrow it down for direction of tool or language, I can continue to dig.

#10 Updated by Boone Gorges 8 months ago

Thanks for sharing the initial research, Sonja! I've added Ray as a watcher, as he may have opinions regarding implementation.

As a general principle, I think we should steer clear of tools that are too closely tied to a specific templating language. A number of the tools try to enforce atomic design by asking you to build a library of reusable elements, and then to include them when building molecular or template-level items. This approach won't work well for us, for a couple reasons. One is that we use WordPress, which uses PHP-based template, rather than Moustache or Handlebars or a true templating language. (We could build middleware, but it's lots of work.) Two is that our markup comes from many places other than theme templates, such as plugins and mu-plugins. Finally, I can envision a future where we build things that are technically different from what the Commons currently is (say, something non-WordPress-based), but where we still want to use the style guide toolset.

I like the idea of building a styleguide out of our CSS, using KSS. kss-node is one tool of this type, http://styleguide.sc5.io/ is another, and there are probably others. With this kind of approach, we could keep our existing infrastructure (ie not rewrite template files, and our changes to CSS would be mostly for consolidation at first), and add styleguide integration through inline comments + some build steps (grunt, php, whatever). This feels to me like something that we can do in stages, within our existing theme/plugin setup.

#11 Updated by Sonja Leix 8 months ago

Matt and team,
which part of the Commons should I first focus on to review what styles exist and to start creating a style guide? Please include any sub sections that might be relevant and you wanted me to also include in this.

To inform this questions the consideration should be most used or having the widest range of UI variation. Please let me know and if you can share a link so I'm sure to find the right thing.

Thanks.

#12 Updated by Matt Gold 8 months ago

Thanks, Sonja. I see a few possibilities here:

1. The profile/portfolio section -- e.g. what you see when you go to https://commons.gc.cuny.edu/members/[username] and then also click on "Commons Profile." The rationale for starting here is that we have two divergent styles (public portfilio, which is its own design that the Commons team created a few years ago in an effort to help people put together online CVs) and the Commons profile, which inherits basic buddypress styling from the main site and which connects more to the network. So, what unites this area of the site is the Users own profile; but then there are two parts, one more public facing and one that shows internal connections with the Commons (e.g group memberships, sites, etc). FYI, when we were creating the Commons profile section, we had lots of discussions about what it meant to be creating a part of the site focused on the individual member (the portfolio) and a part of the site that focused on connections (which is what the Commons is supposed to be about). in the end, we split the difference and made both interfaces available through tabs.

2. The group interface. the rationale for starting here is that it is heavily used and also in need of a redesign. Work on this part of the site could also affect other areas of the site, such as group and blog directories or the Commons user's Commons profiles, as described above.

Those are probably the two places I'd start, though I'd love to hear what others think.
Commons Profile

#13 Updated by Boone Gorges 8 months ago

Starting with single groups seem like the best approach to me. As Matt notes, they're heavily used. They also contain much of the design language used throughout the site. Specifically, they have:

- single-item navigation (left-hand nav)
- secondary nav (like "All Docs" when clicking the Docs item)
- BP item lists (like under Members)
- miscellaneous other kinds of item lists that come from other plugins (Docs, Forums, Files)

#14 Updated by Sonja Leix 8 months ago

Thanks for sharing your feedback Matt and Boone.
Reviewing the suggested sections, I tend to lean towards Groups or more specifically starting with single groups. My reasoning is, that there is less of a focus on BuddyPress UI (though it's woven in with the members section). Groups include a lot of different styles and UI components that will help kick-start this project. I would start with the main single group page, and then start to dive deeper into the sub sections to identify unique styles that need to be defined. Once that's done, I can then focus on the groups archive page.

If everyone is ok with this direction, I'd start there.

#15 Updated by Chris Stein 8 months ago

I agree Groups is a good place to start.

While you’re looking at groups, and the Commons in general a few things you might keep in mind:
There are a few main types of interfaces that are common across the site but not all the same
  • Lists of things (people, groups, sites, activity). These tend to have similar elements (title, image, description, time) but not always similar style
  • Forms
  • Tabs
  • Buttons and Links
As you move forward after that another thing...
There are some specialized interfaces that were designed more to fit their function than an overall style (this is off the top of my head and not exhaustive):
  • Editing a Doc
  • Social Paper
  • Portfolio
  • Inviting people to the Commons

I can also give you links to some of the research that was done a while ago like the Button Styles.
Perhaps if you like and have the time we can schedule a time to talk and I can cover some of the discussion Matt referenced on Profile/Portfolio and any other back history that you’re interested in.

#16 Updated by Matt Gold 8 months ago

so -- groups it is! thank you, Sonja, and thank you, Chris

#17 Updated by Sonja Leix 8 months ago

Chris,
Thanks for the additional info and yes, would love to get on a call with you to get more insight. Do you have some time next week (Wed or Thur maybe)?

#18 Updated by Sonja Leix 7 months ago

Hi team,
I've put together the first draft of a style guide focusing on Individual Groups.

The attached PDF includes:
– Atomic Design Principles – A look at what desired design system we're trying to achieve longer term
– Styles inventory – What styles are currently present on individual groups pages
– Style guide – A start of some general styles (will be extended on in the next step)

Understanding the longer-term design system we're trying to get to will help us understand how we think about elements and styles on the page.
The inventory will help us consolidate styles and make decisions about visual hierarchy.
The decisions we make by looking at the inventory will then be added to the style guide. From there we can start implementing styles for groups.

The goal is to create more consistency in design (and on the technical side HTML classes to style i.e. primary buttons the same across the site) and at the same time, make it easier to update styles. This will give us a big leg up during a possible redesign project.

#19 Updated by Boone Gorges 7 months ago

This is excellent, Sonja!

What are next steps? Perhaps we can start by choosing one or two items to remediate - say, consolidating the various greys - and use that as a test case for integrating the living styleguide toolchain?

#20 Updated by Sonja Leix 7 months ago

Boone,
Yes, I'd like to start with a few items. The greys would be a good starting point, so would be the buttons. I can put together a unified look for primary, secondary, and maybe another type of button.

#21 Updated by Boone Gorges 3 months ago

  • Target version changed from 1.15 to 1.16

#22 Updated by Sonja Leix 2 months ago

Matt,
it would be good to discuss in what capacity you want me to focus on this since the redesign bid is also something that will be going out at some point.

Also available in: Atom PDF