# Style guide

## 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](https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices)

## 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:

<figure><img src="/files/YkPfMgXXWhe0GppiGK12" alt=""><figcaption></figcaption></figure>

## 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**.\
  \&#xNAN;*Example: "Displays on the learner's dashboard"*
* **Use a period** if the tooltip is a complete sentence.\
  \&#xNAN;*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:
  * <i class="fa-circle-question">:circle-question:</i> question mark for help/documentation
  * <i class="fa-circle-info">:circle-info:</i> info for basic information
  * <i class="fa-lightbulb-on">:lightbulb-on:</i> 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.shiftiq.com/contributors/conventions/style-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.