# Writing How to write interface text in Zenox products, from button labels to error messages. Interface text is part of the design. A label that names the wrong thing or an error that does not say how to fix it costs the user as much as a broken control. These rules apply to every string a Zenox product shows, in English, Portuguese and Spanish alike, and to the defaults the library's patterns ship with. ## Voice and tone Zenox users investigate threats and fix exposures, often under time pressure. Write like a competent colleague: direct, calm and specific. - **Direct.** Lead with what matters. Cut words that do not change the meaning. - **Calm.** State severity as a fact; never add alarm the data does not carry. No exclamation points. - **Specific.** Name the object and the number: "3 domains expire this week", not "Some items need attention". - **Respectful.** Never blame the user, never joke about a failure, never call a task "simple". | Too formal | Too casual | Right | | ------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------- | | The requested operation could not be completed due to insufficient permissions. | Oops, you can't do that! | You don't have permission to delete assets. Ask a tenant admin. | | Please be advised that the scan has been successfully scheduled. | Scan's all set, you're good to go. | Scan scheduled for 02:00 | ## Plain language - Prefer short sentences and common words. If a sentence needs a second read, split it. - Use one term for one concept, everywhere. If the product calls it an alert, it is never also a notification, an event or a finding on the next screen. - Spell out acronyms at first use unless the audience uses them daily (IP, URL, CVE, DNS do not need it; "EASM" in onboarding text does). - No idioms, metaphors or slang. They do not translate and do not help the reader. - No judgments about effort or speed: drop "simply", "just", "easily", "quickly". What is easy for one person is not for another. - Software does not want, think or see. "The scan found 4 open ports", not "The scanner thinks there are 4 open ports". Established terms such as "ingest" are fine. - Name the thing. "Select the Domain field", not "Select it". ## Voice, tense and mood - Use the active voice and the present tense: "Zenox checks the certificate every hour." - Use the imperative for instructions: "Enter a domain." Not "You should enter a domain." - Use the passive voice when naming the actor would blame the user: "The file couldn't be uploaded", not "You uploaded an invalid file". - Use the future tense only for something that will happen at a known time: "The report will be sent at 08:00." ## Capitalization **Sentence case for everything:** page and dialog titles, buttons, tabs, menu items, labels, column headers, toasts. Capitalize only the first word and proper nouns. | Right | Wrong | | -------------------------- | -------------------------- | | Create alert rule | Create Alert Rule | | Last seen | Last Seen | | Connect Microsoft Entra ID | Connect microsoft entra id | - Product, company and standard names keep their own capitalization: Zenox, Vydar, Tellyu, Microsoft Entra ID, CVE-2024-3400. - Never type text in capitals. The only uppercase in the interface is the caption style (`text-xs font-semibold uppercase tracking-widest`), applied with CSS, for short group labels such as sidebar sections. ## Punctuation and symbols | Mark | Rule | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Period | End full sentences with one: descriptions, helper text, message bodies. No period on titles, labels, buttons, menu items, tabs, column headers, placeholders, toast titles or empty-state titles. | | Colon | No colon after a form label: the label sits above the field. Use one only to join a label and a value on one line ("Owner: Security team") and to introduce a list. | | Comma | Use the serial comma in English lists: "domains, hosts, and certificates". | | Hyphen | Join compound adjectives before a noun: "case-sensitive value", "high-severity alerts". No spaces around it. | | Dashes | No em or en dashes in interface text. Split the sentence or use a comma. Write ranges with words: "10 to 20". | | Ellipsis | Not in buttons, menu items, labels or placeholders, and not to show progress: loading is a Spinner or a Skeleton. | | Exclamation point | Never. | | Question mark | Only in a confirmation title that asks for a decision: "Delete asset vpn-01?" | | Quotation marks | Straight double quotes (`"`) around names the user typed or chose, inside a sentence: `Rule "Leaked credentials" was deleted`. Not around IDs, dates, numbers or UI labels, and never for emphasis. | | Parentheses | Avoid them in labels and buttons. Never write plurals as "(s)". | | Slash | In sentences, write the word you mean: "Linux or Windows". A spaced slash may join two distinct values in a narrow column header: "City / Country". | | Ampersand | Write "and". Keep `&` only inside a proper name. | | Apostrophe | Contractions are fine in English ("can't", "don't"). Do not make product names possessive: "the Vydar dashboard", not "Vydar's dashboard". | ## Numbers, dates and values Numbers, dates, times, identifiers and empty values follow [Data display](/guidelines/data-display): absolute times in the user's time zone, numbers through the locale's formatters, and a muted dash for an empty value. ## Word choice Use the same verb for the same action across every product and language. The Portuguese and Spanish columns are the reference for the products' translation files. | English | Portuguese | Spanish | Use for | Not | | --------------------- | -------------------- | ------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------- | | Create | Criar | Crear | Making a new object and saving it | Add (for new objects), New (as a button) | | Add | Adicionar | Agregar | Putting an existing thing into a list or group: add a member, add a domain to a scope | Create | | Edit | Editar | Editar | Changing an existing object | Modify, Update (as a button) | | Save | Salvar | Guardar | Keeping changes to an existing object | Apply (in forms) | | Apply | Aplicar | Aplicar | Applying filters or settings that affect a view | Save | | Submit | Enviar | Enviar | Sending something into a review or workflow | Send (unless it is a message) | | Cancel | Cancelar | Cancelar | Leaving a task without keeping changes | Abort, Dismiss | | Close | Fechar | Cerrar | Closing something that changed nothing (a details panel, an error dialog) | OK | | Delete | Excluir | Eliminar | Destroying something that was saved | Remove, Erase; "Deletar", "Apagar" | | Remove | Remover | Quitar | Taking something out of a list without destroying it | Delete | | Discard | Descartar | Descartar | Throwing away unsaved changes or a draft | Delete | | Duplicate | Duplicar | Duplicar | Creating a new object from an existing one | Copy, Clone | | Copy | Copiar | Copiar | Copying a value to the clipboard | Duplicate | | Export | Exportar | Exportar | Producing a file: "Export to CSV", "Export to PDF" | Download (as a button), product names | | Try again | Tentar novamente | Reintentar | Retrying a failed request | Retry, Reload | | Clear | Limpar | Limpiar | Removing applied filters or a typed value | Reset (unless restoring defaults) | | Show more / Show less | Mostrar mais / menos | Mostrar más / menos | Expanding and collapsing a list | See more, Expand | | Sign in / Sign out | Entrar / Sair | Iniciar sesión / Cerrar sesión | Starting and ending a session | Log in, Login, Log out | - "OK" only acknowledges information. Never pair a question with OK and Cancel, or with Yes and No: name the action instead. - Say "please" only when you are making the user wait or redo work, and not in every message. - Do not say "successfully" ("com sucesso", "con éxito") in a success message: the message itself says it worked. ## Text in components | Element | Rule | Example | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | Button | A verb, plus the object when it is not obvious. One to three words. | Create rule, Export to CSV | | Link | Describe the destination. A link that reads "Learn more" alone says nothing to a screen reader. | Learn about detection rules | | Page title | The object or the task, as a noun phrase. | Alerts, Detection rules | | Dialog title | What happens, or the question to answer. | Invite member, Delete asset vpn-01? | | Field label | A noun phrase naming the value. Never a sentence, never a colon. | Domain, Notification email | | Placeholder | An example of the expected format, only when it helps. Never a replacement for the label; it disappears as the user types. No period. | acme.com | | Helper text | One sentence about format, limits or consequences, with a period. | Separate several domains with commas. | | Tooltip | The name of an icon-only control, or one short sentence of help. | Copy, Refresh | | Tab, menu item | A noun or a short verb phrase, sentence case. | Overview, Export to PDF | | Column header | Singular when each row has one value, plural when a cell lists several. | Owner, Tags | | Badge, status | One or two words, a state not a sentence. | Resolved, In progress | ## Messages Every message answers up to three questions, in this order: what happened, why, and what the user can do. Skip the "why" when it does not help them act. | Type | Write | Example | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Success | A short past-tense statement, the object first. No period, no "successfully". | Asset deleted, 12 alerts resolved | | Error | What went wrong and what to do, in full sentences. No error codes or stack traces in the text: put them in a "Details" section or in the logs. | The report couldn't be generated. Try again in a few minutes. | | Field error | How to fix the value, not that it is wrong. | Enter a domain, such as acme.com. | | Required field | Name the field. | Domain is required. | | Warning | The consequence, then the choice. | 3 of 12 alerts are already closed and won't change. Resolve the other 9? | | Confirmation | Title: the question, naming the object. Body: what changes and whether it can be undone. Button: the same verb as the title. | Delete asset vpn-01? / Its findings and history are deleted too. This can't be undone. / Delete asset | | Information | Context the user should know before acting, one or two sentences. | Results include assets discovered in the last 30 days. | Never show a raw backend message to the user: it can carry internal details or personal data. Map known errors to written messages and fall back to a generic one. When an unexpected error may reach support, show the request ID as a copyable value under the message ("Reference: 7f3a9c"), so support can find the request in the logs. ## Writing for translation Every Zenox interface ships in English, Portuguese and Spanish. - Keep a message in one string, with named variables: `"{count} alerts resolved"`. Never build a sentence by joining fragments; word order changes between languages. - Write singular and plural as separate strings, chosen by count. Never "(s)". - Leave room: Portuguese and Spanish run about 30% longer than English. Do not size a button or a column to the English text. - Do not put a variable where its grammar depends on the word (gender, articles). Write a separate message for each case instead. - Quote names the user typed so the sentence stays readable in every language.