By signing up, you agree to the Code of Conduct, which applies to all online and in-person spaces managed by the Public Lab community and non-profit. You also agree to our Privacy Policy.

As an open source community, we believe in open licensing of content so that other members of the community can leverage your work legally -- with attribution, of course. By joining the Public Lab site, you agree to release the content you post here under a Creative Commons Attribution Sharealike license, and the hardware designs you post under the CERN Open Hardware License 1.1 (full text). This has the added benefit that others must share their improvements in turn with you.

Introducing a (draft) Style Guide for Public Lab

For a long time, folks making new pages and interfaces at PublicLab.org have not had much (if any) guidance or direction, and, understandably, have brought their own ideas to the project. This is great initiative, but we could do a better job setting some clear design conventions, and the whole site would benefit from some more consistency.

@sylvan and I have been working on a Style Guide to serve this purpose. This guide is designed to support coders, designers, and writers building and designing pages on PublicLab.org.

We're at a point where we could use some input and feedback, so here's a draft!

Our goals include:

Simpler and more consistent design

Easier to understand and use: clear and well-explained guidance for design will make it easier to start doing UI work at Public Lab, and easier for people using PublicLab.org to use.

Less customization: using standard libraries like Bootstrap 4 (http://getbootstrap.com) and less custom code will make it less fragile, more compatible and accessible, and easier to upgrade. We strongly encourage using widely familiar interface design conventions, so people don't to have to "learn how to use PublicLab.org."

Easier to maintain: with a set of standards, it will be clearer what UI /should/ look like, and less likely that it will diverge and become inconsistent or messy. Less code will be easier to maintain at a high level of quality in the long term.

More support and guidance for people designing new pages/interfaces

Increased stability

Better organized UI code: cleaning up our code, reducing redundancy, and standardizing (and re-using) templates will make it easier for everyone to do good UI design overall.

so, we can embed gists
i'd like to embed something where you can switch to see the rendered HTML too, though
anyone know a site like that?
best would be doing that through a GitHub repository even!
yeah maybe the slide deck will be the working document
with messier comments and such

Hi @warren
I saw your comment in one of the slides regarding blue buttons everywhere.
How about keeping blue for primary and main buttons but for other features like tags and all, we can have many more great combinations.
I tried this in one of my PR. And this looks great

Oh, interesting -- can you share a screenshot? In general, I am wondering if we can be quite sparing with colored buttons so as not to overwhelm people with choices. But I'm open to suggestions and would love to see what you've got!

Hi @warren I saw your comment in one of the slides regarding blue buttons everywhere. How about keeping blue for primary and main buttons but for other features like tags and all, we can have many more great combinations. I tried this in one of my PR. And this looks great Bootstrap has many button color classes, we can try them.

Check out the blog at https://publiclab.org/blog | Love our work? Become a Public Lab Sustaining Member today at https://publiclab.org/donate If this email title has an ID in the format #0000, you can reply with the email you use at PublicLab.org and your response will be posted as a comment on the website.

Oh, sorry, i didn't see the screenshot in the email, maybe I didn't wait for it to load. Thanks!

So, on a very detailed technical page like the revisions page I'm not so worried. But on leading pages, especially "above the fold," I think the question of "too many choices" and too noisy colors is something to be cautious about.

But fundamentally the Style Guide incorporates, refines upon, and "generalizes" a lot of the work that went into that project. So they largely still stand, but the Style Guide is an attempt to make a more holistic guidance document from them that can be applied to other pages as well!

I especially wanted to note the shift, which was a major breakthrough of the DIAL UI project, away from listing all posts in a single "firehose," and towards displaying our topics. This has some really serious and excellent ramifications:

It presents Topics (formerly Tags) as a set of topically-focused communities, essentially like a forum. This is reflected in the card design for Topics.

It orients many things around these Topics, like creating a post (within a topic, rather than just on anything), Subscribing, and may even be part of future plans for spam management (just within a topic you're "moderator" in, perhaps?). Wikis may start to "live inside" topics, conceptually.

This is all still evolving, but is an important part of our Style Guide so we'd love to hear input.

Hey guys! I wanted to provide some feedback on our topic cards that have replaced the smaller tags on posts. I've been getting a lot of feed-back from first time users and have some proposals that I think can help to solve theses those users are having.

First, students are having trouble adding tags because our tag editor box is short and they're not easily able to see the entirety of what they're typing. A wider tag editor box on posts could help to alleviate this.

The tags under "see more" are too dissimilar from the large topic cards and need to be more visually coherent. To solve this, we can update the smaller tags under "see more" like shown below, to make the font should be the same and just a little smaller, appear in an outlined box, displayed one per line.

A student had trouble because they thought they were adding the tag "soil x" instead of "soil" because the 'x' that denotes the delete function is visually so similar to the font of the tag. I would propose that the delete function should no longer be an ‘x’ but be moved into the “...” context menu of the topic cards, both big and small.

The wording "8 more" to unfold the additional tags is a bit cryptic and doesn't describe what users are seeing when they make the expansion. Perhaps we could change the text to something like "This is also a part of:"

It is confusing that the '+' sign after the text "8 more" doesn't expand to show the 8 more tags but instead opens the tag editor. As it stands, the format suggests that this would be the function of the '+' sign. To remedy this, I'd suggest that we move the '+' sign to before the text and use it to expand the hidden tags and to open the tag editor.

This new system would need a new way to display the power tags and can be used an opportunity to onboard more users to the power tag system. A sub section of the "This page is also a part of:" expansion could call out the power tags. If possible, we could link the word 'powertags' to the wiki to increase a user's understanding of how things are organized on the site.

Love this. this is all perfect. Great short texts too. If folks are ready, we can start chopping this up into pieces for implementation.

One note - there are some tags which don't contain a colon (so aren't technically "power tags" which are for almost entirely utility use: method and project come to mind. Should we make a short list of those which should, like power tags, be pushed to the bottom of the list in the "grey" boxes?

One more thing that may be a little odd. The tag input form makes sense above the power tag zone. But when entering, we may have to add extra code to ensure that tags get properly added /above/ vs. /below/ that box, depending on what kind of tag they are. Just noting because this will be a little tricky to get wired properly.