> For the complete documentation index, see [llms.txt](https://guide.techfleet.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.techfleet.org/resources/brand-guide/editorial-style-guide/interface-copywriting.md). # Interface Copywriting ## UX Writing Principles * Clarity and Conciseness: Interface text must be short and easy to understand instantly. * Scannability: People don't read web pages; they scan them. Use short paragraphs, bullet points, and clear headings. * Plain Language: Writing should be presented in the most plain language you can use, at a 7th grade reading level. See [Reading Level](/resources/brand-guide/brand-foundations/reading-level-standards.md) requirements. ## Interface Elements * Buttons and CTAs: Use action-oriented verbs. Tell the person exactly what will happen when they click. * Form Labels: Keep labels short. Use helper text below the field if more explanation is needed. Form labels, instructions, and error messages must be programmatically associated with the right field. | Do This | Not This | | -------------------- | ------------ | | "Submit Application" | "Submit" | | "Create Account" | "Go" | | "Download PDF" | "Click Here" | | "Save Profile" | "Save" | | "Join Project" | "Join" | ## System States and Messages * Error Messages: Be empathetic, clear, and actionable. Don't blame the person. Tell them what went wrong and how to fix it. * Success Messages: Be celebratory but appropriate. Confirm that the action was successful. * Empty States: When a page has no data yet, use the space to encourage action. Tell the person what they can do next. | Do This | Not This | | --------------------------------------------------------------------------------------- | ------------------------ | | "We couldn't find an account with that email. Please check the spelling and try again." | "Invalid email address." | | "Your application was sent! We will email you within two days." | "Success." | | "You don't have any projects yet. Click 'Find a Project' to get started." | "No projects found." | | "That password is too short. It must be at least 8 characters." | "Password error." | | "Your profile has been updated." | "Update complete." | ## Accessibility in UX Content * Alt Text: Always write descriptive Alt Text for images, charts, and icons so screen readers can describe them to people with vision impairments. * Meaningful Links: Never use "click here" as link text. The link text should describe where the link goes. * Media: Provide captions for all pre-recorded video, live captions for live events, audio descriptions for video where meaning depends on visuals, and transcripts for podcasts and audio-only content. | Do This | Not This | | -------------------------------------------------------------------------- | ---------------------------------- | | "Read our Three-Year Strategy" | "Click here to read our strategy." | | Alt text: "A group of four people smiling and looking at a laptop screen." | Alt text: "Image of people." | | "Download the Annual Report PDF" | "Download" | | Alt text: "Bar chart showing a 20% increase in volunteer signups." | Alt text: "Chart." | | "View the event schedule" | "More info" | ## UX Components To ensure our digital products are intuitive and consistent, use these specific rules for common interface components. ### Action Labels (Buttons and Links) * Always use the "Verb + Noun" formula for primary actions (e.g., "Save profile", "Create project"). * Keep labels to three words or fewer. * Do not use vague labels like "Submit", "Go", or "Click here". | Do This | Not This | | --------------------- | -------- | | "Join project" | "Submit" | | "Upload resume" | "Upload" | | "Cancel subscription" | "Cancel" | | "Send message" | "Send" | | "View dashboard" | "View" | ### Date and Time Formatting * Write dates as Month Day, Year (e.g., January 15, 2026). * Do not use ordinal numbers (e.g., 15th). * Write times using a 12-hour clock with am/pm (e.g., 2:30 pm). * Include the time zone if the event is distributed (e.g., 2:30 pm EST). | Do This | Not This | | --------------------------------------------------- | --------------------------------------- | | "The meeting is on March 4, 2026 at 1:00 pm EST." | "The meeting is on March 4th at 13:00." | | "Applications close on November 30, 2026." | "Applications close on 11/30/26." | | "Join us at 9:00 am PST." | "Join us at 9 AM." | | "The event runs from October 1 to October 5, 2026." | "The event runs from Oct 1st-5th." | | "Office hours are at 4:30 pm GMT." | "Office hours are at 16:30." | ### Tooltips * Tooltips should only provide highly contextual, supplementary information. They must never contain essential information required to complete a task, as they are difficult to access on mobile devices and for some screen reader users. * Keep tooltip copy under 100 characters. Do not include links or formatted text inside a tooltip. | Do This | Not This | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | "Your public profile URL." | "This is the URL that other people will see when they view your profile. You can change it later in your account settings by clicking here." | | "Only visible to you." | "This information is private and will not be shared with anyone else on the platform." | | "Must include a special character." | "Your password needs to be strong, so make sure you include at least one special character like an exclamation point or a question mark." | | "Used for account recovery." | "We need your phone number just in case you forget your password and need us to send you a text message to recover your account." | | "Optional field." | "You do not have to fill this out if you do not want to, it is completely up to you." | ### Modals and Confirmation Dialogs * The modal title should clearly state the action being taken or the decision required. * The body text should explain the consequences of the action. * The primary button must match the action described in the title. Never use "OK" or "Yes" for destructive actions. | Do This | Not This | | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Title: Delete project? Body: This will permanently remove all files. This action cannot be undone. Buttons: Cancel / Delete project | Title: Are you sure? Body: Do you want to do this? Buttons: No / Yes | | Title: Leave team? Body: You will no longer have access to the team's files or chat. Buttons: Cancel / Leave team | Title: Warning Body: You are about to leave the team. Buttons: Cancel / OK | | Title: Publish article? Body: This article will be visible to everyone on the website. Buttons: Cancel / Publish article | Title: Confirm Body: Ready to publish? Buttons: No / Yes | | Title: Discard changes? Body: Any unsaved edits will be lost. Buttons: Keep editing / Discard changes | Title: Unsaved changes Body: You have unsaved changes. Buttons: Cancel / OK | | Title: Remove user? Body: This person will no longer be able to log in. Buttons: Cancel / Remove user | Title: Are you sure? Body: Do you really want to remove this user? Buttons: No / Yes | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://guide.techfleet.org/resources/brand-guide/editorial-style-guide/interface-copywriting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.