This is an area to host resources and documentation supporting the evolution and proper use of Superset design system elements. If content is to be added to this section or requires revisiting, a proposal should be submitted to the dev@superset.apache.org email list with either a text proposal or a link to a GitHub issue providing the markdown that will be added to this wiki. The Dev list will have the chance to review the proposal and arrive at lazy consensus. A committer may then copy/paste the markdown to this wiki, and make it public.
Use sentence-case capitalization for everything in the UI (except these exceptions below).
Sentence case is predominantly lowercase. Capitalize only the initial character of the first word, and other words that require capitalization, like:
Sentence case vs. Title case:
Why sentence case?
When writing about a UI element, use the same capitalization as used in the UI.
For example, if an input field is labeled “Name” then you refer to this as the “Name input field”. Similarly, if a button has the label “Save” in it, then it is correct to refer to the “Save button”.
Where a product page is titled “Settings”, you refer to this in writing as follows: “Edit your personal information on the Settings page”.
Often a product page will have the same title as the objects it contains. In this case, refer to the page as it appears in the UI, and the objects as common nouns:
Acronyms and abbreviations. Examples: URL, CSV, XML, CSS, SQL, SSH, URI, NaN, CRON, CC, BCC
Proper nouns and brand names. Examples: Apache, Superset, AntD JavaScript, GeoJSON, Slack, Google Sheets, SQLAlchemy
Technical terms derived from proper nouns. Examples: Jinja, Gaussian, European (as in European time zone)
Key names. Capitalize button labels and UI elements as they appear in the product UI. Examples: Shift (as in the keyboard button), Enter key
Named queries or specific labeled items. Examples: Query A, Query B
Database names. Always capitalize names of database engines and connectors. Examples: Presto, Trino, Drill, Hive, Google Sheets
Button variants:
Button styles: Each button variant has three styles:
Primary buttons have a fourth style: dropdown.
Usage: Buttons communicate actions that users can take. Do not use for navigations, instead use links.
Purpose:
| Button Type | Description |
|---|---|
| Primary | Main call to action, just 1 per page not including modals or main headers |
| Secondary | Secondary actions, always in conjunction with a primary |
| Tertiary | For less prominent actions; can be used in isolation or paired with a primary button |
| Destructive | For actions that could have destructive effects on the user's data |
Button text is centered using the Label style. Icons appear left of text when combined. If no text label exists, an icon must indicate the button's function.
Button labels should be clear and predictable. Use the “{verb} + {noun}” format, except for common actions like “Done,” “Close,” “Cancel,” “Add,” or “Delete.” This formula provides necessary context and aids translation, though compact UIs or localization needs may warrant exceptions.
Interface errors appear when the application can't do what the user wants, typically because:
In all cases, encountering errors increases user friction and frustration while trying to use the application. Providing an error experience that helps the user understand what happened and their next steps is key to building user confidence and increasing engagement.
The best error experience is no error at all. Before implementing error patterns, consider what you might do in the interface before the user would encounter an error to prevent it from happening at all. This might look like:
Only report errors users care about. The only errors that should appear in the interface are errors that require user acknowledgement and action (even if that action is “try again later” or “contact support”).
Do not start the user in an error state. If user inputs are required to display an initial interface (e.g. a chart in Explore), use empty states or field highlighting to drive users to the required action.
Select one pattern per error (e.g. do not implement an inline and banner pattern for the same error).
| When the error... | Use... |
|---|---|
| Is directly related to a UI control | Inline error |
| Is not directly related to a UI control | Banner error |
Inline errors are used when the source of the error is directly related to a UI control (text input, selector, etc.) such as the user not populating a required field or entering a number in a text field.
Use the LabeledErrorBoundInput component for this error pattern.
Banner errors are used when the source of the error is not directly related to a UI control (text input, selector, etc.) such as a technical failure or a loading problem.
Use the ErrorAlert component for this error pattern.
ToastType.DANGEREffective error messages communicate:
Error messages should be:
Example:
❌ “Cannot delete a datasource that has slices attached to it.”
✅ “Please delete all charts using this dataset before deleting the dataset.”