From 37350a2b50e8b4877d6462f30df96f12707cec7d Mon Sep 17 00:00:00 2001 From: Franz Heidl Date: Thu, 8 Oct 2026 14:48:50 +0200 Subject: [PATCH 1/3] =?UTF-8?q?feat(ui):=20uxdocs=20=E2=80=93=20add=20rend?= =?UTF-8?q?ering=20empty=20and=20unknown=20values=20guidelines=20(#2030)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Franz Heidl --- docs/ux/datagrid.md | 1 + docs/ux/ux-writing-content-design.md | 34 ++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/docs/ux/datagrid.md b/docs/ux/datagrid.md index 4dc3dbf160..d77f76911a 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 or identifier columns specifically, if the name is not set, show the item's ID instead — it allows users to identify and reference the item even without a human-readable name. 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..fe41be1174 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 (—). Although they look similar at small sizes, some editors and formatters (including Markdown-aware tools and Prettier) automatically convert adjacent double hyphens into a dash. 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 act as the primary identifier of an item — the **Name** 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 the name is the primary means of identifying an item: + +- **Name column in a DataGrid** — show the ID in place of the name +- **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 (`
`) that shows all properties of an item as-is — do **not** substitute the ID for the name. Use `- -` as per the rule above. The purpose of verbatim metadata display is to accurately reflect what is stored: substituting the ID would misrepresent the data by implying a name exists when it does not. + ## Errors and Error Messages No exclamation marks. We're talking to professionals, there is no reason to be alarmistic about anything. Never use double or triple punctuations. From 4688475ca18eedfb1c8c06e265af094aab4bab19 Mon Sep 17 00:00:00 2001 From: Franz Heidl Date: Thu, 8 Oct 2026 14:55:03 +0200 Subject: [PATCH 2/3] =?UTF-8?q?feat(ui):=20uxdocs=20=E2=80=93=20fix=20smar?= =?UTF-8?q?t=20typography=20explanation=20in=20empty=20values=20guidelines?= =?UTF-8?q?=20(#2030)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Franz Heidl --- docs/ux/ux-writing-content-design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ux/ux-writing-content-design.md b/docs/ux/ux-writing-content-design.md index fe41be1174..e64ba90ad9 100644 --- a/docs/ux/ux-writing-content-design.md +++ b/docs/ux/ux-writing-content-design.md @@ -211,7 +211,7 @@ Use “Sign in”, just as recommended by SAP Fiori content guidelines. Make sur 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 (—). Although they look similar at small sizes, some editors and formatters (including Markdown-aware tools and Prettier) automatically convert adjacent double hyphens into a dash. The space between the hyphens prevents this substitution. +**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 From 72f427222e721aa23abe082623a76c1a98111e5a Mon Sep 17 00:00:00 2001 From: Franz Heidl Date: Thu, 8 Oct 2026 17:03:07 +0200 Subject: [PATCH 3/3] =?UTF-8?q?feat(ui):=20uxdocs=20=E2=80=93=20refine=20n?= =?UTF-8?q?ame=20column=20ID=20fallback=20guidance=20(#2030)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Franz Heidl --- docs/ux/datagrid.md | 2 +- docs/ux/ux-writing-content-design.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ux/datagrid.md b/docs/ux/datagrid.md index d77f76911a..b509ee5793 100644 --- a/docs/ux/datagrid.md +++ b/docs/ux/datagrid.md @@ -136,5 +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 or identifier columns specifically, if the name is not set, show the item's ID instead — it allows users to identify and reference the item even without a human-readable name. 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. +- 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 e64ba90ad9..84cd60e136 100644 --- a/docs/ux/ux-writing-content-design.md +++ b/docs/ux/ux-writing-content-design.md @@ -227,13 +227,13 @@ When a field or data point has no value — because it was not set, is not avail ### Names as Identifiers: Fall Back to the ID -For fields that act as the primary identifier of an item — the **Name** 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**. +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 the name is the primary means of identifying an item: +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 +- **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