Writing style

Strings are a component. They ship, they regress, and they are the part of the product a user actually reads. This page is the ruling for every string that appears in a Nubisco UI surface: labels, titles, helper text, toasts, banners, confirmations, empty states, errors, accessible names.

It is written to be applied mechanically. Where two options are defensible, one of them is chosen here so that twelve applications do not each choose separately. If you disagree with a ruling, change this page; do not fork it in your view.

The rulings, in one screen ​

Action verbs (Save against Done, Close against Cancel, Delete against Remove) follow one rule: the button says the verb of the thing it does. This page governs everything else.

Voice ​

The product speaks like a competent colleague who is doing the task with you, not a system reporting on itself and not a brand talking at you.

Three properties, in priority order when they conflict:

1. Accurate. The string must be true of what just happened. A toast that says Saved when the request is still in flight is a lie the user will act on. NbInlineLoading exists so that a save has three honest states (active, finished, error) instead of one optimistic one.
2. Specific. Name the thing. Delete environment beats Delete item, and Loading invoices beats Loading. NbSpinner's label prop is the accessible name and should carry the noun. Named contradiction:Spinner.vue line 64 defaults that prop to label: 'Loading', which is the exact string this rule bans. The default exists so the component never announces an empty name, not as a licence to leave it. Always pass a noun. The default is drift to be fixed in the component, listed in Where the library contradicts this page.
3. Short. Cut every word that survives removal without changing the meaning. Cut please, simply, just, successfully, currently, in order to.

What that rules out:

Humour, exclamation marks, emoji in product strings and second-person praise (Nice work!) are out. A person meets these strings on their hundredth day, not their first, and usually while something is going wrong.

Tone follows stakes, and the component already knows the stakes ​

Tone is not a free choice per string. The component you picked has already declared the stakes; the string matches it. Every row below is a real prop of a real component in this library.

The four toast durations are declared in src/composables/useToast.composable.ts as NB_TOAST_DURATIONS: success 4000, info 6000, warning 8000, error 0. Copy length has to fit the clock. Four seconds is roughly one short line read once. If a success message needs two sentences, it is not a success message, it is a banner. An error is 0, meaning it stays until dismissed, so an error is the one variant where a second sentence is affordable.

Sentence case, everywhere ​

Capitalise the first letter of the string and nothing else, except proper nouns and things that are already capitalised for other reasons (see the table below).

This applies to page titles, section headings, tab labels, button labels, form labels, table headers, menu items, toast titles, banner titles, tooltips, placeholders, helper text, empty-state titles, notification titles and every aria-label.

Add file            not   Add File
Items per page:     not   Items Per Page:
Mark all as read    not   Mark All As Read
Delete environment  not   Delete Environment

Those four are not invented examples. They are the shipped default values of NbFileUploader's buttonLabel, NbPagination's pageSizeLabel, NbNotificationCenter's markAllLabel, and the canonical confirm label. The library is already in sentence case; the applications are the drift.

Title case is banned because it cannot be applied consistently by twelve teams: it requires a shared judgement about which words are "important", and the audit shows that judgement is not shared. Sentence case needs no judgement at all, which is exactly why it is the ruling.

Uppercase is styling, never authoring ​

Some surfaces render uppercase. NbSidebarMenuGroup headings, the record kind strip inside NbConfirm (.nb-confirm__subject-kind), NbCommandPalette group headings and inspector field labels all apply text-transform: uppercase in their own SFC style block.

That is a visual treatment, not a content rule. Type the string in sentence case and let CSS shout. Passing subject-label="ENVIRONMENT" produces the same pixels today and a broken string the moment the styling changes, and screen readers may spell out a fully capitalised word letter by letter.

There is no case in this library where you type an uppercase string. If you find one, it is a defect.

What does take a capital ​

Everything else is lowercase, including our own feature and component names in prose. Write the command palette, the notification centre, the inspector, not the Command Palette. NbCommandPalette is the component; the thing on screen is a command palette.

Non-standard capitalisation in third-party names is preserved exactly as the owner writes it: GitHub, JavaScript, npm, pnpm, macOS, iPhone.

Person ​

My is common in shipped apps and it is banned here for a concrete reason: a sidebar containing My projects, Projects and All projects has three labels and two meanings, and the audit found exactly that kind of triple. If a view shows only the user's own records, the plain noun is correct and the scope belongs in the page description, not the label.

Tense ​

IToastOptions.message documents the past-tense rule in the type itself: The news, in one sentence. Written in the past tense: "Draft saved". NbInlineLoading ships label: 'Saving', finishedLabel: 'Saved', errorLabel: 'Could not save', which is the same three tenses in one component.

Never write a future promise for something that already happened (Your changes will be saved) and never write the passive to hide the actor where the actor matters (The comment was deleted when you deleted it: write Comment deleted).

Punctuation ​

When a period belongs ​

This is the single most-drifted rule in the fleet, so it is a table, not a principle.

The rule underneath the table: a period ends a sentence. It does not end a label. Mixed lists are the failure mode, so decide per string, and never leave one item in a list of six with a stray period.

Everything else ​

Do not use  , manual line breaks or <br> to shape a string. If the wrap is wrong, the container is wrong.

Numbers ​

Counts that change with singular and plural must not be built by appending (s). Write both forms and pick, or reword to a form that does not inflect (Selected: 1, Selected: 4). NbPagination deliberately exposes itemLabel (default items) so a product can supply its own noun rather than hardcoding one.

Dates and times ​

Never type a date format into a string. NbDatePicker and NbCalendar both resolve their locale as props.locale || navigator.language || 'pt-PT' and hand the value to toLocaleDateString. A hardcoded dd/mm/yyyy in your view is wrong for half the fleet and wrong for every user in the other half.

Never invent a relative string by hand (2 days ago built with subtraction and concatenation). It will not translate and it will not agree with the notification centre sitting next to it.

Terminology ​

One word per concept, product-wide. These are the terms the audit found split across synonyms. The left column is the word to use; the right column is what it means and what it replaces.

When a product needs a term not in this table, add it here rather than deciding locally. That is the entire mechanism that stops the next six-phrasing drift.

Do not use internal names in user-facing copy. Component names (NbShellPanel), route names, database table names and enum values (no-results) are for us.

Bias-free terminology ​

The rules above make strings consistent. These make them safe to ship to someone who is not like the person who wrote them. They are rulings, not sensitivities: every one of them has a mechanical consequence, and most of them are also a translation or a search problem.

Never write a gendered third person ​

You cannot know a user's gender, and half the fleet's data has no field for it. Do not guess, do not write he/she, and do not write (s)he.

In order of preference: rewrite to second person, rewrite to plural, rewrite to drop the pronoun, and only then use singular they. Singular they is correct English and is the ruling where a pronoun is unavoidable, but the first three rewrites are shorter, which is why they come first.

A person's own pronouns, where a product stores them, are data. Render them as given, never inferred from a name, a title or an avatar.

Never use a disability as a metaphor ​

These are not banned to avoid offence in the abstract. They are banned because they are metaphors, and a metaphor is the least precise word available for a technical statement.

Note what the right column has in common: it is more specific. The importer went crazy and The importer retried 4,000 times in 30 seconds are the same event, and only one of them can be acted on.

View, see, hear, watch and read are all fine as ordinary verbs, and so is screen reader. The ban is on disability as a figure of speech, not on sensory vocabulary.

Never use ownership or exclusion metaphors that name people ​

allowlist and blocklist are also self-defining, which whitelist and blacklist are not: nothing in the word blacklist says what the list does. That is a usability argument before it is anything else.

Kill, hang and abort stay legal in code identifiers and in log lines; this page governs strings a user reads. Where a third-party API name contains a banned word (a master branch, an upstream blacklist field), quote the API's name exactly in the place that names the API, and use our word everywhere else.

Do not describe people by a condition or an age ​

Write a person who uses a screen reader, not a screen reader user where the sentence is about the person; write people with low vision, not the visually impaired; write people who cannot use a mouse, not motor impaired users. Never use age, gender, nationality or ability as a proxy for skill level: new to the product is the thing you actually meant, and it is testable.

The words for our own users ​

admin, member, owner, viewer are roles: they name a permission set, not a kind of person, and they take no article of judgement (a mere viewer). Never write power user, non-technical user or end user in product copy. The user reading it is one of those, and being told so is not information.

Writing for translation ​

Nothing in this library translates itself, and nothing in it blocks translation. Every user-facing string in every component is a prop or a slot with an English default: NbPagination ships pageSizeLabel: 'Items per page:' and itemLabel: 'items', NbConfirm ships busyLabel: 'Working...', NbSpinner ships label: 'Loading', NbToast ships closeLabel: 'Close', and a toast queue takes statusLabels and closeLabel for the whole queue at once (IToastQueueOptions, whose own docblock says the map is there "for applications that are not in English"). There is no locale prop on the library as a whole and no bundled catalogue. The rulings below are what makes a string translatable later without rewriting the view.

Layout must survive text expansion ​

Translated UI text is routinely longer than English. Budget for +50% on a short label and +100% on a word of five characters or fewer, plus longer individual words in German, Finnish and Hungarian.

The consequences are layout consequences, so they are rules for the view, not for the writer:

• A button's width comes from its content. Never fix a button width to fit the English word.
• A label that must not wrap needs a container that can grow, not white-space: nowrap and a truncation.
• Truncation with an ellipsis is a last resort, and when it is used the full string must still be reachable: a title, a tooltip, or the accessible name.
• Never lay out two labels so they read as one line (Items per page: next to a select is one string plus one control, which is why NbPagination exposes pageSizeLabel including its colon rather than composing it).
• Test at 200% browser zoom with the longest string you have. That is a WCAG 1.4.4 requirement anyway.

What a shorter string buys you ​

Every rule on this page that cuts words (please, simply, successfully, in order to) also cuts translation cost and expansion risk. That is not the reason for those rules, but it is the reason not to relax them for a product that is currently English-only. Every product in this fleet is one contract away from not being.

Errors ​

One application in the audit throws 21 alert() calls carrying raw exception text. That is the worst content defect in the fleet: it is unstyled, unthemed, modal, uncloseable by keyboard convention, invisible to the toast queue, and it shows the user a stack of implementation detail they cannot act on.

The three parts ​

Every error string has up to three parts, in this order:

1. What happened, from the user's point of view, in the past tense, naming the thing. Could not publish the release.
2. Why, if you actually know and the reason is meaningful to the user. The environment has unresolved links.
3. What to do next, as an imperative. Resolve them and publish again.

Part 1 is mandatory. Parts 2 and 3 are included when they are true and useful. Never invent a cause. Something went wrong is part 1 with the noun removed, which makes it useless; Please try again later on its own is part 3 with no part 1, which makes it unactionable.

Could not publish the release. The environment has unresolved links. Resolve
them and publish again.

Could not upload avatar.png. The file is 12 MB and the limit is 5 MB. Choose a
smaller file.

Could not load invoices. The request timed out. Try again.

Where an error goes ​

Raw exception text ​

Never render an exception message, a stack, a status line or a JSON error body to a user. Log it, and map it. useConfirm's options include formatError precisely so the mapping happens in one place per call site rather than by interpolating String(error) into a sentence.

A reasonable default mapping:

Every row uses the same skeleton, so a rewrite is substitution, not authorship.

Field validation copy ​

Loading and progress ​

One audited application renders the literal string Loading under eight different class names. The ruling:

Never write Please wait, never write Loading, please wait..., and never leave a save with no visible state at all, which four audited apps do.

Accessibility ​

Most of this library's accessibility is content. A label is the accessible name. A message is what a live region says out loud. Nothing on this page is decoration, and this section is the part of it that a screen reader, a voice control user or a magnifier user meets directly.

Politeness is already decided, and the copy has to fit it ​

You do not choose aria-live. The component you picked chose it, from the severity you passed. These are the values in the source today:

Three rules follow from that table:

1. An assertive string has to be worth interrupting for. If it is not, you picked the wrong severity, not the wrong words.
2. Do not type the severity into the message. NbToaster already prepends a visually hidden severity word per variant from NB_TOAST_STATUS_LABELS (Success, Error, Warning, Information). Writing Error: could not save the draft gets announced as Error Error: could not save the draft.
3. Never let the icon or the colour carry the meaning. The icons in NbBanner, NbMessage and NbTextInput are all aria-hidden="true". If removing the icon leaves the string ambiguous, the string is incomplete, which is a plain WCAG 1.4.1 failure and not a style preference.

Label in name ​

If a control shows text, its accessible name must contain that text, in the same order (WCAG 2.5.3). This constrains the aria-label rule in An aria-label on a control that already displays a label may extend the visible text, never replace it.

Visible: Delete        aria-label="Delete Production"     legal, extends it
Visible: Delete        aria-label="Remove environment"    breaks 2.5.3
Visible: (icon only)   aria-label="Delete environment"    legal, it is the name

The second row is not a theoretical failure. Voice control users say the word they can see: click Delete matches nothing when the name is Remove environment, and the control becomes unoperable by voice while looking perfectly labelled to everyone else.

The two names a spinner has ​

NbSpinner has label and showLabel, and they are not the same job. label is the accessible name and is always announced. showLabel decides whether that same string is also drawn on screen. So write one string that works both ways: Loading invoices reads correctly out loud and reads correctly as visible text. Please wait while we load your invoices fails as both.

Focus order is part of the copy ​

NbConfirm puts initial focus on Cancel, not on the confirming button (Confirm.vue focuses the cancel element on mount and on open, and cancel is the ghost button while confirm carries the danger variant). A screen reader user therefore hears, in this order: the title (via aria-labelledby), the message (via aria-describedby), then Cancel.

That order is why the destructive-dialog strings are shaped the way they are. The title has to be the action, because it is heard first and nothing before it explains the dialog. The cancelLabel has to read as an answer to the title: Keep editing answers Discard changes, and No answers nothing. And the confirm label is heard last, out of context, which is the argument for the verb phrase: the confirm button says the verb.

Link text ​

A link's text is its accessible name, and screen reader users pull a list of links exactly as they pull a list of actions.

Two links with the same text must go to the same place, and one destination should not be reached by two different phrasings on one page. A link that leaves the product says so in words (Cloudflare dashboard), not only with an external-link icon, which is aria-hidden wherever we draw one. Link text takes no trailing period even when it ends a sentence: the period is outside the link.

Headings, and the order they are read in ​

Headings are navigation before they are typography. One h1 per view, and it names the view rather than the product. Do not skip a level to get a smaller font, and do not use a heading as a label for a single control. A heading with no content under it is a label that has been styled wrongly.

Alternative text ​

Never start alt text with Image of or Graphic of, and never repeat a caption that is already on the page in the alt as well: the reader hears it twice.

Do not encode meaning in case or in punctuation ​

Uppercase is styling (see Uppercase is styling, never authoring), and some screen readers spell out a fully capitalised word letter by letter. Asterisks, colons and parentheses do not mark required, optional or disabled to a screen reader: the control's own state and helper text do. If a field is optional, say so in words where the reader will meet it.

Where the library contradicts this page ​

This page rules on the library, and the library is not yet fully compliant with it. Every known divergence is listed here rather than quietly tolerated, so that a reader who finds one in the source knows whether it is a carve-out (none of them are) or a defect (all of them are).

If you find a divergence that is not in this table, add it. A page that rules on a library is only credible while its list of known failures is complete.

The mechanical rewrite ​

Applied to one view, in order. Each step is checkable.

1. Collect every literal string in the template and the script, including every aria-label, title, placeholder and thrown message.
2. Delete every alert(), confirm() and prompt(). Route them to NbToast, useConfirm() and a real field respectively.
3. Recase every string to sentence case. Search for a second capital letter that is not part of a proper noun from the table above.
4. Remove every typed uppercase string. If the design wants uppercase, the SFC style block does it.
5. Apply the period table. Buttons, labels, titles and headings lose theirs; sentences keep theirs.
6. Delete please, simply, just, successfully, Oops, every exclamation mark and every emoji.
7. Replace we and my. Replace log in with sign in.
8. Replace every gendered third-person pronoun, every disability metaphor (sanity check, blind spot, crippled, insane) and every master/slave, whitelist/blacklist, dummy or man hours using the bias-free tables. Grep for the words; they do not appear in context by accident.
9. Replace every Loading string using the loading table. Every NbSpinner gets an explicit label, because its default is one of the strings you are removing.
10. Break every concatenated sentence into one interpolated string with named placeholders, and replace every count === 1 ? ... : ... plural with Intl.PluralRules. Delete every (s).
11. Rewrite every error to the three-part form, mapping status codes with the table above. No exception text survives.
12. Replace every hardcoded date format with a locale-formatted one, and every hand-formatted number with Intl.NumberFormat.
13. Rewrite every link whose text is Learn more, here or a bare URL to name its destination, and check that no aria-label replaces text the control already shows.
14. Check every button says its verb, and that none of them says OK, Yes, Done or Dismiss.
15. Read the result out loud in order. If a string cannot be spoken as a sentence or a label, it is neither, and it needs rewriting.

Checklist ​

• [ ] Every string is sentence case, and no string is typed uppercase.
• [ ] No em dashes anywhere.
• [ ] Periods follow the table, consistently within each list.
• [ ] No exclamation marks, no please, no Oops, no emoji.
• [ ] Second person only where ownership is ambiguous. No we, no My.
• [ ] Imperative for actions, past for outcomes, present for state.
• [ ] Numerals for all counts. Units spaced. No (s) plurals.
• [ ] No hardcoded date or number formats.
• [ ] Terminology matches the table, one word per concept.
• [ ] Every error names what happened, and adds why and what next when known.
• [ ] No alert(), no raw exception text.
• [ ] Loading copy names the noun, or is a skeleton with no copy.
• [ ] Every aria-label reads as a name a person would say out loud, and where the control also shows text, the name contains that text verbatim.
• [ ] No string repeats a severity the live region already announces, and no string depends on an icon or a colour to be understood.
• [ ] No link text is Learn more, Click here or a raw URL.
• [ ] Decorative images have alt=""; meaningful ones describe the information.
• [ ] No gendered third-person pronoun, no he/she, no (s)he.
• [ ] No disability used as a metaphor: no sanity check, blind spot, crippled, insane, dumb, lame.
• [ ] No master/slave, whitelist/blacklist, grandfathered, man hours, dummy data, guys, power user or end user.
• [ ] No sentence is built by concatenation, and every interpolation uses a named placeholder.
• [ ] Every plural goes through Intl.PluralRules, never a ternary and never (s).
• [ ] No layout depends on the English string's length; the longest label still fits at 200% zoom.
• [ ] Every NbSpinner passes an explicit label, and every NbBanner passes close-label="Close".