Style guide

Conventions for a consistent, unified approach to layout and style throughout the user interface

Overview

As a general rule, we follow the principles and practices in Google's Material Design style guide. Any time you are uncertain about how to proceed with a style decision, please refer to to it for guidance.

The official reference is here: Material Design style guide

Tabs

The sequence of the tabs on a form should follow this basic rule:

Primary/essential content → Secondary content → Advanced/optional content

Tabs should represent a logical information architecture, and should use progressive disclosure (don't overwhelm with too much detail on the first tab).

For example:

• Basic Info (required, foundational)

• Advanced Settings (optional, builds on basic)

• Permissions (contextual, depends on other settings)

• Review (summary, final step)

Buttons

Placement

Button placement depends on the specific context and type of action. Bottom placement is preferred for:

• Form submission buttons (Save, Submit, Continue) - users expect these at the bottom after completing the form

• Wizard/stepper navigation (Next, Previous, Finish)

• Modal dialogs - actions typically appear at the bottom

• Mobile interfaces - bottom placement is more thumb-friendly

Top placement is preferred for:

• Page-level actions (Create New, Add Item, Export)

• Toolbar actions (Edit, Delete, Share) that apply to the entire page or selected content

• Navigation actions that don't require form completion

• Destructive actions that you want to separate from form submission buttons

Material Design principles specify:

• Forms: Primary actions should be at the bottom, following the natural completion flow

• Content pages: Actions can be at the top in app bars or floating action buttons

• Mobile: Consider reachability - bottom placement is often more accessible

Alignment and Sequence

On web forms, buttons should be placed at the bottom of the page, aligned to the left margin. The correct sequence (from left to right) is:

1. Save (primary action - leftmost)

2. Cancel (dismissive action - next to primary)

3. Duplicate (secondary action)

4. View References (secondary action)

5. Delete (destructive action - rightmost or separated)

The key principle here is:

• Primary actions go first (leftmost) in the natural reading flow

• Dismissive actions (e.g., Cancel) typically appear next to the primary action

• Destructive actions (e.g., Delete) are placed last or visually separated

This follows the logic that users read left-to-right and encounter the most important action first. The "Save then Cancel" pairing at the beginning creates a clear primary action hierarchy.

When it is possible to do so, buttons that perform destructive actions should be separated entirely. For example, a Delete button should be placed in a different area of the form, rather than mixing it with form submission buttons.

Confirmations

The prompt for confirmation of a destructive action should look like this:

Tooltips

Tooltips provide brief, contextual help for UI elements. They should be concise, scannable, and easy to understand.

Tone:

• Use a clear, neutral, and instructional tone.

• Avoid jargon, unless it is widely understood by users.

Length:

• Aim for one sentence or less.

• Avoid multiple sentences or blocks of text.

Punctuation:

• Do not use ending punctuation (like periods) for short phrases or fragments. Example: "Displays on the learner's dashboard"

• Use a period if the tooltip is a complete sentence. Example: "This text appears under the achievement title."

Grammar:

• Use sentence case (capitalize the first word).

• Use active voice when possible.

Icons:

• Including an icon is optional.

• When you include an icon in a tooltip, follow a consistent semantic hierarchy:

  • question mark for help/documentation

  • info for basic information

  • lightbulb for insights and quick tips

Examples:

• ❌ "this text will be shown under the achievement title."

• ✅ "This text appears under the achievement title."

• ✅ "Appears under the achievement title"

Grids

Action icons in data tables and grids should be placed in the right-most column.

This follows the natural reading flow (left-to-right in most languages) where users first scan the data content and then encounter the actions they can take on that data. There are some exceptions:

• Selection controls (like checkboxes) are typically placed in the left-most column

• In some cases, a single primary action icon might be placed on the left if it is the most important element for that row

The right-aligned approach for action icons is part of Material Design's broader principle of creating a clear visual hierarchy and intuitive user flow in a data-dense interface element.