Creating consistent admin interfaces

Discourse · September 17, 2024, 5:50am

These guidelines aim to create a cohesive admin interface, focusing on usability, accessibility, and a structured layout. See the table of contents for what is included and to navigate to each section easily.

Note: The terminology used here is defined in the admin interface glossary.

1. Breadcrumbs

Breadcrumbs serve as a navigational tool, aiding users in understanding their current location, content structure, and hierarchy within the admin interface.

Admin > Breadcrumb > Trail
Page title

Design

Structure

Admin: fixed prefix that appears at the beginning of every breadcrumb trail, linking to /admin
Link: opens the page in the same window
Separator: a greater than sign > separates each link

Usage

When to use:

Present on every admin page
Sit above the content (title, description, tabs)
Show the currently selected page

When not to use:

When visiting a new or edit route

Content

Each item includes a link to its related page
Shows the currently selected page

Accessibility

A nav element with aria-label="Breadcrumb" wraps an ordered list to provide a navigation landmark
Apply aria-current="page" on the last link to indicate it’s the current page
For more details, see WAI-ARIA Authoring Practices Breadcrumb Example

Implementation

The DBreadcrumbsContainer component must be placed somewhere on the page:

<DBreadcrumbsContainer />

Then, every DBreadcrumbsItem element added to a any component on a route or a child route will be rendered into this container. Each DBreadcrumbsItem has a @label and @path that must be provided:

<DBreadcrumbsItem @path="/admin" @label={{i18n "admin_title"}} />
<DBreadcrumbsItem
  @path="/admin/plugins"
  @label={{i18n "admin.plugins.title"}}
/>
<DBreadcrumbsItem
  @path="/admin/plugins/{{@plugin.name}}"
  @label={{@plugin.nameTitleized}}
/>

How this looks with a visual example, using the Discourse AI plugin:

2. Page header and title

The top section of an admin page, containing the page title, along with optional actions and description.

Design

Structure

Page title: Title of the page
Page description: Intro or description of what the content covers (optional)
Primary action: Page title primary action (optional)
Secondary action: Page title secondary action button settings (optional)

Usage and content

Page title: Utilize heading level 1 to explain the main subject of the page in sentence case
Page description: Supports basic markdown nodes such as _italic_, **bold**, and [link name](url)
Primary action: Utilize btn-primary. Don’t include an icon.
Secondary action: Utilize btn-default button settings, visible only if a primary action exists. Don’t include an icon.

Be clear with action buttons. For example, use descriptive labels like “Add emoji” instead of just “Add” to reduce ambiguity.

Implementation

The AdminPageHeader component is used here. This accepts arguments for @titleLabel, @descriptionLabel, @titleLabelTranslated, @descriptionLabelTranslated, and @learnMoreUrl. This uses named yields in Ember to provide 3 sections for the content:

breadcrumbs - Any additional DBreadcrumbsItem components for the page should be placed here.
actions - Used to define the buttons to the right of the title. This yields an object called actions which can be used to render Default, Primary, and Danger buttons.
tabs - Used to define the tabs for the page using NavItem components. @hideTabs can be used to remove this part of the header if it’s not needed.

A complete example is below:

<AdminPageHeader
  @titleLabel="admin.backups.title"
  @descriptionLabel="admin.backups.description"
  @learnMoreUrl="https://meta.discourse.org/t/create-download-and-restore-a-backup-of-your-discourse-database/122710"
>
  <:breadcrumbs>
    <DBreadcrumbsItem
      @path="/admin/backups"
      @label={{i18n "admin.backups.title"}}
    />
  </:breadcrumbs>
  <:actions as |actions|>
    <actions.Primary
      @action={{routeAction "showStartBackupModal"}}
      @title="admin.backups.operations.backup.title"
      @label="admin.backups.operations.backup.label"
      class="admin-backups__start"
    />
  </:actions>
  <:tabs>
    <NavItem
      @route="admin.backups.settings"
      @label="settings"
      class="admin-backups-tabs__settings"
    />
    <NavItem
      @route="admin.backups.index"
      @label="admin.backups.menu.backup_files"
      class="admin-backups-tabs__files"
    />
    <NavItem
      @route="admin.backups.logs"
      @label="admin.backups.menu.logs"
      class="admin-backups-tabs__logs"
    />
    <PluginOutlet @name="downloader" @connectorTagName="div" />
  </:tabs>
</AdminPageHeader>

Page titles for the browser tab are handled in Ember routes using the titleToken functionality. Every time this is used in a route it adds the token to the end of the browser tab title. Be aware that you must use the DiscourseRoute class to extend your route, not the normal Route from ember for this to work:

titleToken() {
  return I18n.t("admin.backups.title");
}

3. Tabs

An optional navigation that provides access to deeper levels of settings or features.

Design

We’re using tabs to switch between different but related views within the same context.

Usage

Not used for primary navigation
Only active one at a time

Implementation

See the Page Header details, the tabs are defined in the AdminPageHeader component.

4. Overview/section landing page

Allows users to view the contents of a section, especially when the sidebar is collapsed or on mobile.

Design

Structure
Use three equal column layout using a grid system. On small screens, these columns will stack vertically.

Design and usage

Can be accessed through breadcrumbs (Admin > Community > Overview)
Each section should have one, except for plugins (which show installed) and reports (only one page)
The item has a:
- name - same as the section link
- description - a short description of what the page is about
- icon - same icon used for the sidebar

Implementation

Code snippets or link to a topic/GitHub

5. Page content

The main area of an admin page where settings, configurations, and other content are displayed and interacted with.

Design

Structure
Use a 2/3 + 1/3 layout using a grid system. The primary section takes up two-thirds and the secondary section takes up one-third of the space. On small screens, these columns will stack vertically.

Config area: A specific section within the page content dedicated to settings and configurations.
Help/reference/inset: An area within the page content providing guides, documentation, or additional contextual information. (optional)

Design and usage

Group similar settings and actions together in cards
Structure primary/secondary layouts so the primary (2/3) section is used for main settings, and the secondary (1/3) section is for additional information or helpful context
If the secondary section is not available, keep the primary section width the same

Content

Follow the guidelines for config area when adding content
Follow the guidelines for help inset content

Implementation

Code snippets or GitHub links

5.a. Subhead

A subhead is a secondary heading used to break up the content under a section, usually below the tabs.

Structure

Subheading: Subheading of what the content covers (optional)
Primary action: Subheading primary action (optional)
Secondary action: Subheading secondary action button settings (optional)

Usage and content

Subheading: Utilize heading level 2 to explain the main subject of the related content. Only include if:
- There is a primary action button, or
- There is a description explaining the section.
Primary action: Utilize btn-primary. Don’t include an icon.
Secondary action: Utilize btn-default button settings, visible only if a primary action exists. Don’t include an icon.

Be clear with action buttons. For example, use descriptive labels like “Add emoji” instead of just “Add” to reduce ambiguity.

Implementation

This is similar to AdminPageHeader, there is an AdminPageSubheader component. The main difference is that there is only a single named yield for actions.

actions - Used to define the buttons to the right of the title. This yields an object called actions which can be used to render Default, Primary, and Danger buttons.

<AdminPageSubheader @titleLabel="admin.backups.files_title">
  <:actions>
    <actions.Primary
      @action={{routeAction "showStartBackupModal"}}
      @title="admin.backups.operations.backup.title"
      @label="admin.backups.operations.backup.label"
      class="admin-backups__start"
    />
  </:actions>
</AdminPageSubheader>

5.b. Config area

The config area is made up of cards or sections. Cards are great for grouping related info and tasks, helping users scan and prioritize content more easily.

Design

Card

Cards are set up with a 2px border-radius and use a background of --secondary. It also have a 1px solid border with --primary-low and 20px padding around the content.

Default variation

Accordion variation

Design and usage

Group related information
Display information so admins and mods see the most important stuff first
Use headings that clearly explain what the card is for
Break complicated ones into multiple sections, if necessary

default variation

Stick to one primary call to action per card
Place primary call to action at the bottom of the card for next steps

accordion variation

Use the top right corner of the card for optional actions like “View all”

Content

Form content should use the FormKit ember components in core described in the docs
Card headers should be sentence-cased

Do Don’t

General settings General Settings

Contact information CONTACT INFORMATION

Implementation

We have an AdminConfigAreaCard component that should be used for all of these cards. For now this only has @translatedHeading and @heading arguments, in future we can add actions and make them collapsible and so on:

<AdminConfigAreaCard
  @heading="admin.config_areas.about.general_settings"
  class="admin-config-area-about__general-settings-section"
>
  <AdminConfigAreasAboutGeneralSettings
    @generalSettings={{this.generalSettings}}
    @setGlobalSavingStatus={{this.setSavingStatus}}
    @globalSavingStatus={{this.saving}}
  />
</AdminConfigAreaCard>

Embedded site settings

This section is a work in progress.

5.c. Help inset

This section provides additional guidance, documentation, or context within the page content.

v1

Design

Design and usage

Show related documentation or guides about the page’s content to provide useful info
Include an icon in the heading to make it easily recognizable
Place this section in the secondary (1/3) layout area

Content

Headers should be sentence-cased

Implementation

Code snippets or link to a topic/GitHub

5.d. Table

Tables display information in a grid of cells, columns, and rows, making it easy for admins to quickly scan items and take action.

Design

Usage

Use tables to display structured content where each entry shares the same attributes.
Allow admins to review, enable/disable, edit, and delete data sets.
Suitable for data sets that will continue to grow over time.

Design

Use horizontal lines between rows to visually separate content, including the last row. Avoid using borders or frames around the table to prevent it from looking like a net.
Do not apply vertical lines between columns. Tables without vertical lines are generally easier to scan and read.

Additional actions

Row Actions: Include additional actions in the far-right column of each table row.

Action buttons within table rows can be more minimal since they are placed next to the resource. For instance, “Edit” and “Delete” are sufficient
Visibility: Ensure these actions are always visible.
Action Menu: If a table row contains more than two actions, consider using a “more menu” button with a dropdown list of options. Icons in the dropdown menus are encouraged to break things up visually.

Content

Header: The table header is the top row that identifies the columns below. It provides clarity, especially if the data is non-descriptive or ambiguous. Headers should be short, descriptive, and relevant, using title case. Avoid headers that are too long for the content in the rows below.
Columns: Order columns by priority or in a way that tells a coherent story with the data. Size columns according to their content, with narrow columns for small content and wider columns for paragraphs.
Rows: Rows should support text, buttons, links, and icons to enhance the data presentation.

Implementation

Tables mostly work without effort or custom components.

For <td> cells which wrap the buttons for each row, they should have the admin-table-row-controls CSS class applied. This ensures the buttons are aligned. Each button should have the btn-small class applied too.

For [...] dropdown menus, DMenu should be used with DropdownMenu, here is an example:

<DMenu
  @identifier="backup-item-menu"
  @title={{i18n "more_options"}}
  @icon="ellipsis-v"
  class="btn-small"
>
  <:content>
    <DropdownMenu as |dropdown|>
      <dropdown.item>
        <DButton ...[button args here] />
      </dropdown.item>
      <dropdown.item>
        <DButton ...[button args here] />
      </dropdown.item>
    </DropdownMenu>
  </:content>
</DMenu>

Toggles in the table row are handled using the DToggleSwitch component:

<DToggleSwitch
  @state={{this.enabled}}
  class="admin-flag-item__toggle {{@flag.name_key}}"
  {{on "click" (fn this.toggleFlagEnabled @flag)}}
/>

5.e Third-level route

A third-level route is one that can be reached only from a config area. These usually come in the form of edit/new routes like this one for flags:

Design

Usage

Do not show the top part of the page UI (breadcrumbs, page header and subheader)
Instead, show a single “Back to X” link that allows the admin to get to the main config area
Any sub-titles on the page should be done with config area cards

Implementation

There is a simple BackButton component that can be used on the top of the page to go back:

<BackButton
  @route="adminConfig.flags"
  @label="admin.config_areas.flags.back"
/>

6. General guidance

All text in admin interfaces should follow the text formatting guidelines outlined here:

7. Plugins

Some plugins need an in-depth configuration UI for their plugin (for example AI, Automation, Gamification) rather than only having a collection of site settings. For example, here is Discourse AI:

Some examples of plugins using this are:

Discourse AI GitHub - discourse/discourse-ai
Discourse Gamification GitHub - discourse/discourse-gamification
Discourse Chat (core)

Design

Usage

General admin UI guidelines should be followed when making independent plugin UIs.

Implementation

Ember Routing

All route templates will be under
admin/assets/javascripts/discourse/templates/admin-plugins/show/
All route js files will be under admin/assets/javascripts/discourse/routes/ and
prefixed with admin-plugins-show-
The admin route map should be in a file like admin-PLUGIN-NAME-plugin-route-map.js
The route map should have a structure like this. The important part is that
we use admin.adminPlugins.show as the resource.

export default {
  resource: "admin.adminPlugins.show",

  path: "/plugins",

  map() {
    this.route("discourse-ai-personas", { path: "ai-personas" }, function () {
      this.route("new");
      this.route("show", { path: "/:id" });
    });
  },
};

The current example of how this all works is seen in the Discourse AI plugin, if you go to /admin/plugins/discourse-ai/ai-personas
If you only have a “top level” route, e.g. one that doesn’t define sub-routes, then the template path will be something like admin/assets/javascripts/discourse/templates/admin-plugins/show/your-route-name.hbs. If there are sub routes then you get into the territory of needing index.hbs, show.hbs, and new.hbs routes and so on.

Navigation

Plugins can either show their navigation in an inner sidebar, or on the top tabbed navigation bar. The latter is highly recommended, and in future the inner sidebar support may be dropped.

Any links that will be shown in either the top bar or the inner sidebar for
the plugin show page should be defined in an initializer (e.g.
assets/javascripts/initializers/admin-plugin-configuration-nav.js) using
api.addAdminPluginConfigurationNav and specifying the mode with either
PLUGIN_NAV_MODE_TOP or PLUGIN_NAV_MODE_SIDEBAR.
This initializer should only run if the user is admin.
The site settings link for the plugin is generated automatically, no need to include it here.
An example can be seen here discourse-ai/assets/javascripts/initializers/admin-plugin-configuration-nav.js at ab4544d8977ec0e9d6aa42b4551df8317aa9b365 · discourse/discourse-ai · GitHub.

Server-Side

add_admin_route is still used to show the custom admin routes in the admin sidebar and from the /plugins index with the tabs along the top. Basically, this defines the root page of your plugin UI.
- use_new_show_route: true should be passed as an additional argument here so the new plugin show page is used.

UI Conventions

Each index route for the plugin should show a AdminPageSubheader component to describe the intent of that route and to add any related action buttons.
Action buttons that need to be rendered into the main plugin page header must use the admin-plugin-config-page-actions outlet with a dedicated component. The best place to do this is in the same initializer where addAdminPluginConfigurationNav is used.
- plugin and actions are passed as outletArgs. plugin is the model representation of the current plugin so the name of the plugin and other things can be accessed, actions are the yielded action button components from AdminPageHeader.

api.renderInOutlet(
  "admin-plugin-config-page-actions",
  ChatAdminPluginActions
);

Empty lists should have a CTA button using the btn-small and btn-default styles, with the admin-plugin-config-area__empty-list class on the container

Related topics:

Last edited by @ella 2024-11-15T01:17:23Z

Last checked by @hugh 2024-09-17T05:50:18Z

Check document
Perform check on document:

Moin · September 17, 2024, 2:09pm

And

still don’t work. I think the second one is -23 instead of -24

tobiaseigen · September 17, 2024, 3:54pm

So glad to finally see this up on meta. Months of work went into this, and we are going to be using it to standardize the UI and navigation of every page in the admin interface.

Should we maybe just remove that table of contents and rely on discotoc instead? I think that would be less fragile, though I do like seeing the table of contents at the top of the post.

hugh · September 18, 2024, 6:11am

Thanks @Moin - all fixed!

I’ve made this change, otherwise it’s simply a duplicated table of contents.

Topic		Replies	Views
Introducing experimental admin sidebar navigation Announcements feedback , experimental , admin-sidebar	86	4693	May 26, 2024
Developing Discourse Plugins - Part 5 - Add an admin interface Developer Guides plugin-guides , tutorial	47	24859	September 24, 2024
Preparing for Discourse's upgrade to Ember 5 Announcements	56	6930	April 8, 2024
Theme-Component v Plugin: What's the difference Dev	22	5362	June 9, 2020
Brand Header Theme component official , brand-header	20	52864	July 8, 2024

Do	Don’t
General settings	General Settings
Contact information	CONTACT INFORMATION