3 definitions in this file:
The recommended label text (e.g., 'Add', 'Cancel', 'Delete', 'Save as', 'Learn more'). The canonical form as it should appear in the UI.
What this label means — the action it represents. Should be concrete and unambiguous (e.g., for Delete: 'Destroys an existing object so that it no longer exists').
When and how to use this label. Include context, formatting rules, and any caveats (e.g., 'Where appropriate, combine Add with the object: Add user, Add role').
Related terms that serve a different purpose but are often confused with this one. Listed for comparison; helps authors pick the right label. The terms SHOULD match other term values in the same content guideline so tools can cross-reference them.
Where this label is used in the UI (e.g., 'Buttons in dialogs', 'Navigation links', 'Form submission', 'Toolbar actions'). Tells authors where the label normally appears.
Visual or code examples showing the label in context: do/don't pairs, screenshots of correct usage, or code snippets.
References:
richText, example
[
{
"term": "Add",
"definition": "Takes an existing object and uses it in a new context (e.g., adds an item to the cart, adds a user to a group, or adds a document to a folder).",
"usage": "Where appropriate, combine Add with the object (e.g., Add user, Add role). Compare Create, Insert, New, and Upload.",
"alternatives": [
"Create",
"Insert",
"New",
"Upload"
],
"context": "Buttons, menu items, toolbar actions"
},
{
"term": "Cancel",
"definition": "Stops the current action and closes the dialog.",
"usage": "Warn the user of any possible negative consequences of stopping an action from progressing, such as data corruption. Compare Reset.",
"alternatives": [
"Reset",
"Close",
"Done"
],
"context": "Dialog buttons, form actions"
},
{
"term": "Create",
"definition": "Makes a new object from scratch (e.g., creates a calendar event or creates a new document).",
"usage": "In scenarios where the user needs to supply some details or settings as part of the create process, use New to initiate the action and Create to apply the user-supplied details or settings to the new object.",
"alternatives": [
"Add",
"Copy",
"Insert",
"New"
],
"context": "Primary actions, page-level buttons"
},
{
"term": "Delete",
"definition": "Destroys an existing object so that it no longer exists (e.g., deletes a file from a directory or deletes a value from a table cell).",
"usage": "Where appropriate, combine Delete with the object (e.g., Delete column, Delete row). Use Move to trash if the user can recover the object later.",
"alternatives": [
"Clear",
"Remove",
"Move to trash"
],
"context": "Destructive actions, danger buttons, confirmation dialogs"
},
{
"term": "Edit",
"definition": "Allows data or values to be changed.",
"usage": "Use Edit to enter an editing mode. Use Update or Save for the action that applies the changes.",
"alternatives": [
"Update"
],
"context": "Inline actions, page headers, card actions"
},
{
"term": "Remove",
"definition": "Removes an object from the current context but the object is not destroyed as a result of the action (e.g., removes a user from a group or removes an item from the cart).",
"usage": "Where appropriate, combine Remove with the object that will be removed (e.g., Remove user, Remove role). Compare Delete which destroys the object entirely.",
"alternatives": [
"Clear",
"Delete"
],
"context": "List items, tags, selection management"
},
{
"term": "Save",
"definition": "Saves pending modifications made to a file or document. Does not close the window or panel.",
"usage": "Compare Apply (saves changes without closing) and Save as (creates a new object based on the current state).",
"alternatives": [
"Apply",
"Save as",
"Update"
],
"context": "Form actions, editing flows, document editing"
},
{
"term": "Close",
"definition": "Closes the current page or window (e.g., closing a secondary window containing online help).",
"usage": "Do not use Close alongside OK or Cancel actions. Compare Cancel and Done.",
"alternatives": [
"Cancel",
"Done"
],
"context": "Dialogs, panels, modals, secondary windows"
}
]
The localization concern being addressed. Standard values: 'rtl' (right-to-left layout mirroring and bidirectional text), 'text-expansion' (content lengthening during translation), 'pluralization' (plural forms varying across languages), 'date-format' (date and time formatting conventions), 'number-format' (decimal separators, grouping), 'currency' (currency symbol placement and formatting), 'text-direction' (mixed-direction content within a single string), 'icon-direction' (icons that imply directionality), 'truncation' (text overflow behavior across languages), 'sorting' (locale-specific sort order and collation), 'concatenation' (avoiding string concatenation that breaks in other languages). Custom values are allowed and SHOULD be lowercase kebab-case.
Guidance for handling this localization concern. Should be actionable and specific: say what changes across locales, what the author or developer must do, and what to avoid.
Visual or code examples that illustrate the concern: before/after screenshots for RTL, samples of text expansion, or code patterns for pluralization.
References:
richText, example
[
{
"concern": "rtl",
"description": "For right-to-left (RTL) languages, the entire component is mirrored horizontally. Labels are right-aligned and icons that were on the left move to the right. Icons that indicate directionality (arrows, progress indicators) must also be mirrored. Icons that are not directional (checkmarks, close icons) should NOT be mirrored."
},
{
"concern": "text-expansion",
"description": "Localization can lengthen text by 20 to 30 percent for Western European languages, and more for languages like German or Finnish. CJK languages may be shorter. Avoid truncating labels whenever possible — stack buttons vertically when they cannot be displayed side by side. Test all layouts at maximum expected expansion."
},
{
"concern": "concatenation",
"description": "Never construct labels by concatenating strings (e.g., `action + ' ' + object`). Sentence structure, word order, and grammatical agreement differ across languages. Use complete, translatable strings with placeholder tokens for dynamic content."
},
{
"concern": "pluralization",
"description": "Do not assume two plural forms (singular and plural). Some languages have up to six plural forms (e.g., Arabic). Use ICU MessageFormat or equivalent pluralization libraries that support CLDR plural rules. Never use conditional logic like `count === 1 ? 'item' : 'items'`."
}
]
Identifies this guideline as a content spec.
Recommended action labels and terminology. Each entry sets a standard label, its meaning, usage guidance, and cross-references to related terms. Order matters: tools SHOULD preserve it for display. Authors MAY order alphabetically or by frequency of use.
Min items: 1
Localization and i18n considerations. Each entry covers a concern that affects content across languages and writing systems: RTL mirroring, text expansion during translation, pluralization rules, and other i18n concerns. Order matters: tools SHOULD display entries in this order. Authors SHOULD order by impact or frequency.
Min items: 1
Overview of the content guidelines: content philosophy, voice and tone principles, or the scope of labels and localization rules covered.
AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.
Constraint: At least one of labels, localization must be present.
References:
richText, contentLabelEntry, localizationEntry, agents
{
"kind": "content",
"description": "Standard action labels and localization guidelines for the Acme Design System. All UI labels should use sentence case. Prefer the {verb} + {noun} content formula on buttons except for common actions like Done, Close, Cancel.",
"labels": [
{
"term": "Add",
"definition": "Takes an existing object and uses it in a new context.",
"usage": "Combine Add with the object (e.g., Add user, Add role).",
"alternatives": [
"Create",
"Insert",
"New",
"Upload"
],
"context": "Buttons, menu items"
},
{
"term": "Cancel",
"definition": "Stops the current action and closes the dialog.",
"usage": "Warn the user of any possible negative consequences. Compare Reset.",
"alternatives": [
"Reset",
"Close"
],
"context": "Dialog buttons"
},
{
"term": "Create",
"definition": "Makes a new object from scratch.",
"usage": "Use New to initiate the action and Create to apply user-supplied settings.",
"alternatives": [
"Add",
"Copy",
"New"
],
"context": "Primary actions, page-level buttons"
},
{
"term": "Delete",
"definition": "Destroys an existing object so that it no longer exists.",
"usage": "Combine Delete with the object (e.g., Delete column). Use Move to trash if recoverable.",
"alternatives": [
"Clear",
"Remove"
],
"context": "Destructive actions, danger buttons"
},
{
"term": "Save",
"definition": "Saves pending modifications. Does not close the window or panel.",
"usage": "Compare Apply and Save as.",
"alternatives": [
"Apply",
"Save as"
],
"context": "Form actions, editing flows"
}
],
"localization": [
{
"concern": "rtl",
"description": "For RTL languages, the entire component layout is mirrored horizontally. Directional icons (arrows, chevrons) must be flipped. Non-directional icons (close, checkmark) must not be flipped."
},
{
"concern": "text-expansion",
"description": "Localization can lengthen text by 20-30%. Avoid truncating labels. Stack buttons vertically when they cannot be displayed side by side."
},
{
"concern": "concatenation",
"description": "Never construct labels by concatenating strings. Use complete, translatable strings with placeholder tokens for dynamic content."
}
]
}
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub