diff --git a/docs/ux/datagrid.md b/docs/ux/datagrid.md index 4dc3dbf160..b509ee5793 100644 --- a/docs/ux/datagrid.md +++ b/docs/ux/datagrid.md @@ -136,4 +136,5 @@ If a user is not allowed to create any new items, do not render a "Create […]" - Columns that display boolean values may use visual indicators such as `Badge` or `Pill` to communicate the state more clearly at a glance. Plain text representations (e.g. "Yes / No", "Enabled / Disabled") are equally valid — use visual indicators where the state is particularly important or users scan for it frequently, but plain text is fine when the context makes the value self-explanatory. - Identifiers, names, and values that uniquely identify a row item should always be present and clearly visible, even if the grid is heavily filtered or sorted. - Columns with content that is self-explanatory, either by itself or by sticking to the guidelines described, do not necessarily need a column header/title. A leftmost column that holds the checkboxes in order to select multiple items for bulk actions does not need a title. +- When a cell value is empty or unknown, render `- -` (two hyphens separated by a space) as a placeholder. For name columns specifically — human-readable, human-assigned names — if the name is not set, show the item's ID instead, unless the DataGrid already has a dedicated ID column: in that case, use `- -` to avoid showing the same ID value twice. See [UX Writing and Content Design](ux-writing-content-design.md) for the full rationale and the rules that apply to detail views and breadcrumbs. - See [UX Writing and Content Design](ux-writing-content-design.md) for broader writing guidelines. diff --git a/docs/ux/ux-writing-content-design.md b/docs/ux/ux-writing-content-design.md index cce4c5f9fa..84cd60e136 100644 --- a/docs/ux/ux-writing-content-design.md +++ b/docs/ux/ux-writing-content-design.md @@ -207,6 +207,40 @@ Application authors have some flexibility in applying this, but must be consiste Use “Sign in”, just as recommended by SAP Fiori content guidelines. Make sure to use "sign in" consistently. +## Rendering Empty or Unknown Values + +When a field or data point has no value — because it was not set, is not available, or is unknown — **render two hyphens separated by a space as a visual placeholder: `- -`** + +**Do not** use an en dash (–) or em dash (—). Many code and text editors apply "smart" typography automatically, substituting `--` with an en dash as you type. The space between the hyphens prevents this substitution. + +### Do + +`- -` + +### Don't + +`–` or `—` (en/em dash — visually similar, but semantically wrong and easily introduced by tooling) + +`--` (adjacent hyphens — may be silently transformed by formatters) + +`N/A` or `n/a` (avoid unless firmly established convention in the given context) + +### Names as Identifiers: Fall Back to the ID + +For fields that serve as a human-readable, human-assigned name for an item — the **Name column** in a DataGrid, a **detail view page title**, and **breadcrumb segments** — do not render `- -` when the name is missing or not set. Instead, display the item's **ID**. + +The ID is the next best thing to identify, reference, or communicate about an item: it remains unique, stable, and actionable even when a human-readable name is absent. Rendering `- -` in these positions is ambiguous and prevents the user from distinguishing between items or sharing a link meaningfully. + +Apply this wherever a human-readable name is the primary means of identifying an item: + +- **Name column in a DataGrid** — show the ID in place of the name, unless the DataGrid already has a dedicated ID column visible. If an ID column is already present, use `- -` instead — the item is already identifiable, and repeating the ID in the name column would be redundant and confusing. +- **Detail view page title** — use the ID as the title +- **Breadcrumb segment** — use the ID as the segment label + +Display the ID as-is, without additional decoration beyond what would normally apply to a name in that position. + +**Exception: verbatim metadata display.** When rendering an item's raw metadata fields — for example, in a definition list (`