Style Guide

ComPAIR is an open-source learning application being developed by the University of British Columbia's Centre for Teaching, Learning & Technology using a GPL-3.0 license. ComPAIR primarily uses default Bootstrap grids and styles. This basic style guide spells out application-specific uses of the styles.

Introduction

Users in ComPAIR can be given one of three roles. Roles provide increasing levels of permission, which affect the UI. Students can manage—add, edit, delete—their own answers (during the designated answer period), comparisons (during the designated comparison period), comments, and replies (if enabled). Instructors can additionally manage and duplicate their own courses and assignments and edit users in their courses. System Administrators can additionally manage users and which users can access which courses.

There are three main types of objects in the application: courses, assignments, and users. These objects may have slightly different styles applied, as noted in the sections below. When new objects are created, use the term "Add"; when editing, "Edit"; when copying, "Duplicate"; and when removing, "Delete" (and deleting always triggers a confirmation message before the action is performed).

Object conventions are often applied to the four primary assignment interactions—answering, comparing, replying, and commenting—too, and these have additional conventions of their own, as noted in the section below.

Global Adminstration Bar

The global adminstration bar appears at the top of every page and contains varying amounts of administrative functions (depending on the user's application role) that are not context specific. Options on the bar appear with an icon on the left and then "First Letter Each Word Capitalized" text written as verb+noun and matching the first two words of the resulting page's h1 heading. Instructors currently see: Download Reports and Add Course. System Administrators additionally see: Add User, Manage User, and Manage LTI.

All users see their display name on the right-hand side of the bar, with a dropdown that provides access to their user profile and an option to log out. The dropdown options follow the display conventions above, except they do not have to follow the verb+noun structure.

^ Back to top

Breadcrumbs

Breadcrumbs function as the main navigation for the application and appear just below the global administration bar for every page except the home page. The home page is always the first link shown, with all child pages listed and linked up until the current page. The current page is listed but not linked.

The breadcrumb labels should match the h1 on each page. These are dynamically generated based on page location and hard-coded only in the compair-config.js file, though additional modifications are also made on-the-fly (using breadcrumb.options) in individual controllers (to add object names in place of generic text).

^ Back to top

Headings

The application currently uses five levels of headings.

h1: Used as the first heading on each page (and only appears once); no content should appear above this heading; should match breadcrumb label; "First Letter Each Word Capitalized" when hard-coded (some h1s are user-generated); object name h1s include the icon for that object before the text (as noted below); no other h1s include icons
- Courses:  before course name
- Assignments:  before assignment name
- Users:  before user name
h2 / h3: Used as sub-headings (and further sub-headings) on any page; "First letter capitalized" when hard-coded (some h2s/h3s are user-generated); object name h2s include the icon for that object before the text (see above for guidelines); no other h2s/h3s include icons
h4: Used only in relation to comparisons; in comparing as criterion titles; in viewing comparisons as student work divider; "First letter capitalized" when hard-coded; icons always precede text (as noted below)
- Criteria:  before criterion title
- Users:  before user name
h5: Used only in relation to comparisons; in viewing comparisons as sub-headings dividing student work into sections; "First Letter Each Word Capitalized"; custom style with lighter gray colour and bottom border applied; no icons
h6: (not currently used)

^ Back to top

.intro-text Paragraphs

When appropriate, one or more p tags with class="intro-text" appear just below the page's h1 or first h2. This text is slightly larger in display and meant to provide an introduction to the page or section. Text to emphasize may be bolded here.

^ Back to top

Object Lists

When objects appear as a list of items (i.e., home page with courses, course pages with assignments, management pages with users), they share some commonalities in display.

Each object appears on a new row
Each row alternates background colour between #ffffff and #f9f9f9
Each row includes relevant metadata about the object and actions that can be taken on the object (e.g., edit)
- Courses: Students see # assignments, # unfinished assignments, Year/Term; Instructors/Admins see Edit, Duplicate, # assignments, # students, Year/Term, Delete
- Assignments: Students see # answers, # comments, Completed work status, Needed work status, # feedback status; Instructors/Admins see Edit, Duplicate, # answers, # comparisons, # comments, Answer/Compare status, Delete
- Users: Instructors/Admins see Edit, Drop, Bulk action, Display Name, First Name, Last Name, Student Number, Email, Course Role, Course Group
If present, orange label tags highlight important information about the object ("status" items above)

Filters of various types are used to affect the list of objects and make it easier to locate a specific object. These appear in the upper right corner before the list starts. When long enough, filters shown as drop-down selects include a search function.

Some of this styling is applied to other lists of items in the application as well. For example, the display of assignment interactions for answers and comments also follows these conventions.

^ Back to top

Assignment Interactions

Outside of managing an assignment, users can interact with assignments in four main ways: answering, comparing answer pairs, replying to answers, and commenting on the assignment. When the results of these activities are displayed in the application, they follow the same introductory line. Before the answer, comparison, reply, or comment, there should be text containing (from left to right):

The user's profile icon
The user's name (linked to their profile), presented as Display Name (Full Name), where the full name only appears to those in a non-Student role
A gray label—class="label-default"—to indicate if this is an instructor/teaching assistant (otherwise no label shown)
A bolded verb, e.g., answered, submitted, replied, with text+icon to indicate public and private for replies (as noted below)
- Public:  after bolded text
- Private:  after bolded text
The date presented at the end as "on MMM D @ h:mm a:"

Tabs are used to help users navigate these interactions for assignments. In each assignment, Students see tabs for Answers (answers and related replies aka peer feedback), Your Work + Feedback (their answer, related replies, their comparisons), and Help Comments (comments about the assignment). Instructors/Admins see tabs for Answers (answers and related replies aka peer feedback), Comparisons (comparisons grouped by student including answer pairs seen, answers chosen per criterion, and peer feedback given), Help Comments (comments about the assignment), and Participation (summary of student interactions).

Answers and comments follow the display conventions for object lists as noted above. Actions Instructors/Admins can take on answers include Star (add to instructor's top picks list), Edit, and Delete; the same applies to comments except without the first option.

^ Back to top

Buttons

The application primarily uses four types of buttons. All button text is "First Letter Each Word Capitalized".

Green / class="btn-success": Indicates a primary action a user must take to complete an activity; used as the final button in submitting all forms (including inline forms) and for "View Course", "Answer/Finish Answer", and "Compare Pairs" buttons; form buttons are center aligned; other buttons are right aligned when practical; no icons added; larger sizing preferred
Blue / class="btn-primary": Indicates a secondary action a user can take; used to present contextual administrative options and optional student activities, e.g., adding assignments, editing user profiles, replying to answers; also used for selection of answer per criterion in comparison form; buttons are right aligned when practical; must contain a related icon to the left of the text; medium sizing preferred
White / class="btn-default": Indicates one of two or more options where de-emphasis of button(s) is desired; used for buttons to save drafts of answers and comparisons and to make choices during duplication process; as save button, always center aligned and to the left of the "Submit" button; no icons added; sizing should be appropriate to surrounding context
Turquoise / class="btn-info": Indicates access to additional information; used for button to open pop-ups of attachments or links, to read more answer text, and to see the student comparison preview; no icons added; smaller sizing preferred

^ Back to top

Forms

Unless displayed inline, forms always use fieldsets with legends to organize the form fields. Additionally, forms share other styles.

Legends use "First Letter Each Word Capitalized" for text and should succintly summarize the fields below
When appropriate, a div with class="instructional-text" can be used to contain explanatory text for the fieldset; this must appear within the fieldset and can contain bolded or dynamic text to improve guidance
Sub-sections of a fieldset are set apart with <hr> lines
Labels are bold and appear above or to the right of the fields, and should also be "First Letter Each Word Capitalized" for text except as noted below
- Checkbox labels may be normal weight and "First word capitalized", if the text has to be longer for usability reasons
- Sub-labels are also normal weight and use class="text-muted"
Required fields should have a red asterisk after their labels, added with class="required-star"
Required text fields should also use the compair-field-with-feedback directive to add dynamic green/red highlighting and icons
Placeholders should be used only when needed to further explain a field
Informational text to inform users about important form settings should use a paragraph tag with class="alert alert-info"
Blank drop-down selects read: "- Select appropriate term here -" (with "First letter capitalized" text)
Date fields should use the date picker
Forms are be submitted with a green button that is center aligned at the bottom of the form; if relevant, a save draft white button can appear to the left of this button

^ Back to top

Modal Pop-ups

Modal pop-ups are used to help users view or interact with a page when it is a sub-step of the page they are on, e.g, looking at an attachment, adding a group, replying to an answer, commenting on an assignment. For these instances, it is better (or required) that users remain on the same page and at the same place on the page then have to navigate away to complete an action and then return back.

^ Back to top

Confirmation Messages

Colour-coded messages pop up to confirm (green) or warn (orange or red) about actions a user has taken in the application (e.g., saving, deleting). Messages should be phrased as "Subject Past Tense Action" (with "First Letter Each Word Capitalized") with no punctuation, followed by any necessary information to explain the message (in sentence form with appropriate punctuation). Whenever possible, the heading text should match with the text of the link or button clicked. For example: clicking "Save Draft" for an answer returns a heading of "Answer Draft Saved" followed by the text "Remember to submit your answer before the deadline."

^ Back to top

.collapsible-content Elements

Content pieces can be designed to collapse/expand with show/hide functions in Angular and class="collapsible-content" on the element to toggle. The content is always displayed under linked (blue) text and should contain information that can be progressively revealed (i.e., can be sought optionally). A chevron appears to the left of this text, facing right——when the content is collapsed/hidden and facing down——when the content is expanded/shown.

If the progressive reveal is part of filling out a form—that is, the user needs to confirm the addition of something to the form— a checkbox should be used in place of this convention.

When the assignment itself is being displayed in this way, a containing div with class="standalone-assignment" should be applied, as well as a h2/h3 heading with the assignment name preceded by the icon . This will style the assignment similar to how it appears on the assignment page, to help with the user's recognition that this is the assignment.

^ Back to top

.labels Tagging

The application uses two kinds of labels to tag information.

Orange / class="label-warning": Identifies important information as related to assignments; used for outstanding work, rounds remaining, feedback received, and answer scores; appears as part of metadata except in case of rounds remaining (where it is part of the heading)
Gray / class="label-default": Identifies instructors/teaching assistants in assignments; used when instructors/TAs answer, reply, or comment; appears as part of metadata

^ Back to top