UI Principles

The Warehouse UI aims to be clean, clear and easy to use. Changes and additions to the UI should follow these four principles:

1. Be Consistent

Creating consistent interfaces is more aesthetically pleasing, improves usability and helps new users master the UI faster.

Before creating a new design, layout or CSS style, always consider reusing an existing pattern. This may include modifying an existing design or layout to make it more generic.

Following this principle can also help to reduce the footprint of our frontend code, which will make Warehouse easier to maintain in the long term.

2. Consider Usability and Accessibility

Ensuring Warehouse follows usability and accessibility best practices will make the site easier to use for everybody. At a minimum:

  • Ensure contrast is high, particularly on text. This can be checked:
  • Write semantic HTML
  • Ensure image alt tags are present and meaningful
  • Add labels to all form fields (if you want to hide a label visually but leave it readable to screen readers, apply .sr-only)
  • Where possible add ARIA roles to the HTML
  • Indicate the state of individual UI components with CSS styles. For example, darken a button on hover.
  • Ensure that keyboard users can easily navigate each page. It is particularly important that the outline is not removed from links.
  • Consider color blind users: if using color to convey meaning (e.g. red for an error) always use an additional indicator (e.g. an appropriate icon) to convey the same meaning.

3. Provide Help

Never assume that all Warehouse users are as familiar with the Python ecosystem as you are. Something that may seem obvious or second-nature to you may be a difficult or novel concept for someone else.

Seek out places in the interface where help text should be included - either as standard text on the page, or by adding a help icon (that links to help content).

4. Write Clearly, with Consistent Style and Terminology

Warehouse follows the Material design writing style guide.

When writing interfaces use direct, clear and simple language. This is especially important as Warehouse caters to an international audience with varying proficiency in English. If you’re unsure, please check the readability of your text.

Be consistent, particularly when it comes to domain specific words. Use this glossary as a guide:

Term Definition
Project A collection of releases and files, and information about them. Projects on Warehouse are made and shared by members of the Python community so others can use them.
Release A specific version of a project. For example, the requests project has many releases, like requests 2.10 and requests 1.2.1. A release consists of one or more files.
File Something that you can download and install. Because of different hardware, operating systems, and file formats, a release may have several files, like an archive containing source code or a binary wheel.
Package A synonym for a file.
User A person who has registered an account on Warehouse.
Maintainer A user who has permissions to manage a project on Warehouse.
Owner A user who has permissions to manage a project on Warehouse, and has additional permission to add and remove other maintainers and owners to a project.
Author A free-form piece of information associated with a project. This information could be a name of a person, an organization, or something else altogether. This information is not linked to a user on Warehouse.