@jobber/components 8.13.0 → 8.13.1-addeditor-cab44cf.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/dist/docs/Combobox/Combobox.md +1 -1
  2. package/dist/docs/InputText/InputText.md +1 -1
  3. package/dist/docs/Toast/Toast.md +2 -2
  4. package/dist/docs/errors/errors.md +2 -2
  5. package/dist/docs/formatting/formatting.md +245 -0
  6. package/dist/docs/index.md +3 -0
  7. package/dist/docs/product-vocabulary/product-vocabulary.md +524 -0
  8. package/dist/docs/voice-and-tone/voice-and-tone.md +385 -0
  9. package/package.json +3 -3
package/dist/docs/Combobox/Combobox.md CHANGED
@@ -22,7 +22,7 @@ Combobox is designed to handle lists of selectable options, so the component is
22
22
  text based.
23
23
 
24
24
  You may customize the activator and action `label`. Refer to the
25
- [Product Vocabulary](/content/product-vocabulary) for consistency in consistency
25
+ [Product Vocabulary](../product-vocabulary/product-vocabulary.md) for consistency in consistency
26
26
  in terminology and naming conventions when setting these values.
27
27
 
28
28
  You may also set an optional `subjectNoun` for the Combobox content. This will
package/dist/docs/InputText/InputText.md CHANGED
@@ -151,7 +151,7 @@ but minimizes the need for it as the user should be set up for success by proper
151
151
  guidance pre-submission before any "bad" data gets to the server.
152
152
 
153
153
  Follow the
154
- [product vocabulary](/content/product-vocabulary#component-view-general-phrasing)
154
+ [product vocabulary](../product-vocabulary/product-vocabulary.md#component-view-general-phrasing)
155
155
  for guidance on writing helpful error messages.
156
156
 
157
157
  ```tsx
package/dist/docs/Toast/Toast.md CHANGED
@@ -41,7 +41,7 @@ The Toast label should be clear and concise, and should not take up more than
41
41
  one line.
42
42
 
43
43
  Use the pattern "action + subject" to maintain
44
- [active voice](/content/voice-and-tone). The subject should be specific without
44
+ [active voice](../voice-and-tone/voice-and-tone.md). The subject should be specific without
45
45
  overloading too much detail for the user to parse at a quick glance.
46
46
 
47
47
  | ✅ Do | ❌ Don't |
@@ -54,7 +54,7 @@ overloading too much detail for the user to parse at a quick glance.
54
54
  * Examples of action labels: `Undo`, `View`, `Refresh`
55
55
  * Toast's label does not require a period
56
56
  * Use sentence case, and only capitalize
57
- ["branded"](/content/product-vocabulary) Jobber features
57
+ ["branded"](../product-vocabulary/product-vocabulary.md) Jobber features
58
58
 
59
59
  | ✅ Do | ❌ Don't |
60
60
  | ---------- | ----------------------- |
package/dist/docs/errors/errors.md CHANGED
@@ -25,8 +25,8 @@ First and foremost: design to avoid the possibility of errors!
25
25
 
26
26
  #### Effective content
27
27
 
28
- Follow the guidance in our [product vocabulary](../content/product-vocabulary)
29
- and [voice & tone](../content/voice-and-tone) guides to help you craft effective
28
+ Follow the guidance in our [product vocabulary](../product-vocabulary/product-vocabulary.md)
29
+ and [voice & tone](../voice-and-tone/voice-and-tone.md) guides to help you craft effective
30
30
  error messages.
31
31
 
32
32
  #### Validation and form inputs
package/dist/docs/formatting/formatting.md ADDED
@@ -0,0 +1,245 @@
1
+ # GrammarThis page defines the grammar and punctuation rules for writing at Jobber. These
2
+ rules ensure our content is consistent, clear, and easy to scan across the
3
+ product.## CapitalizationUse sentence case for almost all product content, with the exception of
4
+ instances where all-caps is a stylistic decision (i.e. MON WED TUE as calendar
5
+ weekday headers). Additionally, as outlined in the Buttons section, button
6
+ labels are title cased.This means in general, capitalize only the first letter of the content unless
7
+ there is a proper noun (such as a person's name) involved. This applies to:- Headings and titles
8
+ - Body copy
9
+ - Card headers
10
+ - Menu options
11
+ - List itemsJobber features such as jobs, quotes and invoices don't count as proper nouns.
12
+ They shouldn't be capitalized.### NamesRespect user input for names and do not force capitalization. For example, names
13
+ like “LaGrange”, “DeAndre”, and “dos Santos” all carry meaning, and we should
14
+ not impose a standardized structure that omits these nuances.### ButtonsButton labels should be title-cased. This means in general, capitalize all words
15
+ with the exception of:- Articles (a, an, the)
16
+ - Coordinating conjunctions (but, for)
17
+ - Prepositions (at, by, to, etc.)| ✅ **Do** | ❌ **Don't** |
18
+ | -------------------- | -------------------- |
19
+ | Approve and Schedule | Approve and schedule |
20
+ | Create a Quote | Create A Quote |## ContractionsContractions help keep Jobber's tone conversational, and make our content easier
21
+ to scan for SPs. They should be used.| ✅ **Do** | ❌ **Don't** |
22
+ | ----------------------------- | ---------------------------------- |
23
+ | Can't, couldn't, you're, it's | Can not, could not, you are, it is |## HeadingsHeadings and subheadings are titles and subtitles that can refer to specific
24
+ sections.When writing a heading, try to keep it short. SPs are busy, and need to
25
+ understand the content of a page or section quickly. Don't try to communicate
26
+ technical details in the headline, leave that to the body copy.Start by addressing the general thought, then post-headline, move on to the
27
+ particulars.#### Start with the general ideaUse the heading to name the **section** or **task**. Save specifics for the body
28
+ copy. This improves scanning and makes screens easier to reuse.| ✅ **Do** | ❌ **Don't** |
29
+ | ---------------- | ------------------------------------ |
30
+ | Invoice details | Invoice for Anna Smith, May 14, $620 |
31
+ | Schedule options | Schedule the job for next Thursday |
32
+ | Payment history | Payments received this month |#### Be clearHeadings should be easy to understand at a glance. Avoid vague, overly friendly,
33
+ or conversational phrases — they slow people down.| ✅ **Do** | ❌ **Don't** |
34
+ | ---------------- | ---------------------- |
35
+ | Job history | Where you've been |
36
+ | Add a new client | Let’s get you set up! |
37
+ | Quote overview | Ready to win the work? |#### Keep it short and scannableHeadings should be easy to read on mobile and in motion. Avoid repeating screen
38
+ names, filler phrases, or full sentences.| ✅ **Do** | ❌ **Don't** |
39
+ | --------------------- | ------------------------------------------- |
40
+ | Create invoice | This screen lets you create an invoice |
41
+ | Upcoming appointments | Your upcoming appointments are listed below |
42
+ | Add line item | Add a line item to the quote |### SubheadingsSubheadings can be useful when a heading requires further context. They should
43
+ always offer real help, not filler. Just because a layout has a subheading, it
44
+ doesn't mean it should be used.Only use subheadings when they:- Clarify something that’s not obvious from the heading
45
+ - Add meaningful guidance to a task or section
46
+ - Help reduce the need for extra body copy**Example**:If you were introducing the concept of reviews for SPs, where Jobber can
47
+ automate asking SPs for a review upon a completion of a job, you wouldn't put
48
+ the technical aspect of automation in the heading, that would be saved for the
49
+ subheading. Heading: Ask your clients for reviews 
50
+ Subheading: Jobber can ask your clients for reviews on your behalf, at a time
51
+ of your choice For more guidance on how to structure headings and subheadings, you can view the
52
+ [structure of content video.](https://us02web.zoom.us/clips/share/ExCgjrtsR4GZje6y5di2rA)## ListsUse lists to make instructions or content easy to scan. SPs often work in
53
+ fast-moving situations, so these rules have been added with keeping lists clear
54
+ and readable in mind.The two main ways to organise lists in Jobber are with bullet points or numbers.
55
+ In some instances there are also sentenced based lists. Follow these rules to
56
+ achieve consistency when adding or editing a list.### Bullet point listUse a bullet point list when the list items don't require a specific order.
57
+ Bullet point lists should be introduced with a colon. Don't put periods at the
58
+ end of items if every item is one sentence.**Example** where periods are not required:All Connect features plus:- Advanced quote customization
59
+ - Track costs with job costing
60
+ - Automated quote follow-upsIf one or more of the items is more than one sentence long, all items should end
61
+ with a period.**Example** where periods are required:Here’s what a client sees after accepting a quote:- A confirmation message. It tells them you'll be in touch to schedule the job.
62
+ - A payment summary with any required deposit.
63
+ - A prompt to create a client account, if they haven't already.### Numbered listUse numbered lists when **order matters**, such as creating an invoice from a
64
+ completed job. Follow the same rules on colons and periods as bullet point list.**Example**:To create an invoice from the job page:1) Tap more actions and select create invoice
65
+ 2) Review the line items and costs
66
+ 3) Tap send to email it to the client### Sentence listOccasionally you may want to structure a list with a sentence. These are rarer
67
+ than bullet point and numbered lists, but they can be useful in describing a
68
+ sequence or laying out the impact of an action.Try to limit the amount of items in a sentence list, if it becomes hard to scan
69
+ consider a bullet point or numbered list.Use an oxford comma to help communicate that the last two items of the list are
70
+ seperate.| ✅ **Do** | ❌ **Don't** |
71
+ | ----------------------------------------------- | ---------------------------------------------- |
72
+ | Change images, tagline, and contact information | Change images, tagline and contact information |## PronounsDefault to addressing SPs with "you", we don;t usually speak on their behalf
73
+ with "I" or "my".| ✅ **Do** | ❌ **Don't** |
74
+ | ---------------------- | -------------------- |
75
+ | Your average job value | My average job value |Use "I" when SPs need to declare something, this is usually related to a legal
76
+ requirement.| ✅ **Do** | ❌ **Don't** |
77
+ | ----------------------------------- | ------------------------------------- |
78
+ | I agree to the terms and conditions | You agree to the terms and conditions |When referring to Jobber, feel free to use "we" and "we're". Avoid using
79
+ "Jobber" wherever possible, we should be happy to take ownership rather than
80
+ talking in the third person.| ✅ **Do** | ❌ **Don't** |
81
+ | ---------------------------------------------- | -------------------------------------- |
82
+ | We've made improvements to your scheduled view | Jobber has improved your schedule view |## PunctuationThese rules are in place so that punctuation can be applied consistently across
83
+ Jobber. Consistent use of punctuation will make the product feel more cohesive
84
+ for SPs.## AmpersandsDon't use ampersands in the product. They don't save much space, don't look
85
+ great, and they draw attention to the most irrelevant part of the sentence.| ✅ **Do** | ❌ **Don't** |
86
+ | -------------------- | ------------------ |
87
+ | Review and Send | Review & Send |
88
+ | Approve and Schedule | Approve & Schedule |## CommasAs stated with sentence lists, we use oxford commas at Jobber to help establish
89
+ that the last two items are separate. They should be used in lists of three
90
+ items or more, unless you're doing a bullet point list or a numbered list.## Exclamation marksAvoid exclamation marks in nearly all scenarios. There should be an extremely
91
+ high threshold for the use of exclamation marks to ensure the genuine moments of
92
+ excitement aren't diluted.Most of Jobber is not exclamation worthy. Even when a user completes something
93
+ important, like:- Sending a quote or invoice
94
+ - Scheduling a job
95
+ - Collecting a deposit
96
+ - Turning on Jobber Payments
97
+ - Signing up for Marketing SuiteThese are normal workflows, not celebrations. They should be acknowledged
98
+ professionally, not enthusiastically.| ✅ **Do** | ❌ **Don't** |
99
+ | ---------------- | ------------------- |
100
+ | Quote sent | You sent the quote! |
101
+ | Job scheduled | Your job is booked! |
102
+ | Payment received | You got paid! |There are more experimental areas such as trial where exclamation marks may be
103
+ used to try and generate excitement and enthusiasm for Jobber. Even in these
104
+ cases, they should be limited to one per page to focus the excitement on one
105
+ specific area.## Hyphens, en dashes, and em dashesUse dashes thoughtfully. Each has a specific role, and misusing them can make
106
+ content harder to scan or understand for SPs.| **Type** | **Use for** | **Example** |
107
+ | ----------- | ------------------------- | ------------------------------------------------ |
108
+ | Hyphen (-) | Compound modifiers | Full-service job |
109
+ | En dash (–) | Ranges and numeric spans | Jan 2–Jan 5 |
110
+ | Em dash (—) | Last-resort clarification | Payment failed — update your billing information |### HyphensUse hyphens to join words that act as a single modifier before a noun. They help
111
+ clarify meaning and reduce ambiguity.| ✅ **Do** | ❌ **Don't** |
112
+ | ------------------ | ------------------ |
113
+ | Full-service job | Full service job |
114
+ | One-time cleanup | One time cleanup |
115
+ | Real-time tracking | Real time tracking |Do not use hyphens when the compound comes **after** the noun.> ✅ This job is full service.\
116
+ > ❌ This job is full-service.### En dashes ( – )Use en dashes for **ranges** especially in time, date, and dollar amounts. No
117
+ spaces on either side.| ✅ **Do** | ❌ **Don't** |
118
+ | --------------- | --------------- |
119
+ | Jan 2–Jan 5 | Jan 2 - Jan 5 |
120
+ | 2:00 PM–4:00 PM | 2:00PM - 4:00PM |
121
+ | $200–$500 | $200 - $500 |En dashes are also used when **expressing a relationship** between values.> The visit window is 8:00 AM–12:00 PM.\
122
+ > The client–contractor agreement includes scope and payment terms.### Em dashes ( — )Use em dashes **only when absolutely necessary**, typically as a last resort to
123
+ break up a sentence for readability or emphasis. As AI (over)uses the Em dash,
124
+ it's important to ensure all content produced by AI has been reviewed. Otherwise
125
+ Jobber content will look and sound like it has been purely AI generated.They should **not** be your go-to for style or tone. Often, a clearer option is
126
+ to split the sentence.| ✅ **Do** | ❌ **Don't** |
127
+ | ----------------------------------------------------- | ------------------------------------------------------ |
128
+ | The quote was approved. You can now schedule the job. | The quote was approved — you can now schedule the job. |## MultiplicationUse the `×` symbol to indicate multiplication whenever possible, rather than an
129
+ `x`.| **✅ Do** | **❌ Don't** |
130
+ | ----------- | ----------- |
131
+ | 12 × $48.00 | 12 x $48.00 |## ParenthesesRestrict to when you need to communicate that some information or tasks are
132
+ optional, or if you want to highlight a particular action is recommended. In
133
+ these cases, just use the word, rather than overload SPs with information.| ✅ **Do** | ❌ **Don't** |
134
+ | ----------------------------- | ------------------------------------------------------- |
135
+ | Ask for reviews (recommended) | Ask for reviews (recommended for businesses like yours) |## PeriodsDon't use a period in microcopy such as error messages, list items, or form
136
+ instructions. Headings don't need a period as they should be restricted to one
137
+ sentence. In microcopy generally, don't use a period unless what you're writing
138
+ is more than one sentence long.| ✅ **Do** | ❌ **Don't** |
139
+ | ---------------- | ----------------- |
140
+ | Enter your email | Enter your email. |## Question marksQuestion marks should be avoided. They create uncertainty, take up space, and
141
+ increase decision-making effort for SPs, especially in fast-moving contexts like
142
+ job scheduling, invoicing, or follow-ups.#### Don’t use question marks in confirmation modalsConfirmation modals should state what’s about to happen, not ask for permission.
143
+ Framing the action as a question forces us into over long and confusing button
144
+ labels like “Yes, do the action”.| ✅ **Do** | ❌ **Don't** |
145
+ | ---------------- | ------------------------------------------ |
146
+ | Archive this job | Are you sure you want to archive this job? |
147
+ | Delete client | Delete this client? |#### Don’t use them in headlines or body copyHeadlines and hero copy should be clear and declarative, not speculative or
148
+ “salesy.” Avoid phrases like “Ready to…” or “Want to…”.| ✅ **Do** | ❌ **Don't** |
149
+ | ---------------------------- | ------------------------------------- |
150
+ | Cut down on admin work | Ready to cut down on your admin work? |
151
+ | Track time from anywhere | Want to track time from the field? |
152
+ | Book more jobs automatically | Need to book more jobs? |#### Say what’s happening rather than what might happenEven if you’re presenting a choice, **state the outcome**. This helps SPs make
153
+ quick, confident decisions, and keeps button text clear and specific.| ✅ **Modal heading** | ❌ **Modal heading** |
154
+ | -------------------------------- | -------------------------------- |
155
+ | Cancel this visit | Are you sure you want to cancel? |
156
+ | Remove team member from schedule | Remove this team member? |## Quotation marksQuotation marks can be helpful to clearly identify exact text that came from a
157
+ client, user, or file. This could include job notes, filenames, custom inputs,
158
+ or copied phrases.#### Where to use quotation marks in JobberUse quotation marks when you're referencing exact input, especially in:- File and attachment names
159
+ - Client-submitted phrases#### Use quotes for client input, filenames, or copied phrasesOnly use quotation marks when you’re showing exactly what the user or client
160
+ entered. Not to add emphasis.| ✅ **Do** | ❌ **Don't** |
161
+ | --------------------------------------------- | ------------------------------------------- |
162
+ | The client wrote: “Please use the back door.” | The client wrote: Please use the back door. |
163
+ | File uploaded: “invoice\_1023.pdf” | File uploaded: invoice\_1023.pdf |#### Use curly quotes, not straight quotesFor the sake of consistency, always use smart (typographic) quotation marks — “
164
+ and ” — in all content. Avoid straight quotes (" or ').| ✅ **Do** | ❌ **Don't** |
165
+ | --------------------------- | --------------------------- |
166
+ | “Approved by client” | "Approved by client" |
167
+ | “Please avoid the driveway” | 'Please avoid the driveway' |#### Punctuation goes inside the quotesIn most cases, place periods and commas **inside** the quotation marks. This
168
+ keeps the sentence flowing and avoids awkward phrasing.| ✅ **Do** | ❌ **Don't** |
169
+ | ----------------------------------------- | ----------------------------------------- |
170
+ | The client said: “We’ll be home after 5.” | The client said: “We’ll be home after 5”. |## SpellingWe use American spelling in Jobber as this is where most of our SPs are based.| ✅ **Do** | ❌ **Don't** |
171
+ | --------- | ----------- |
172
+ | Labor | Labour |
173
+ | Customize | Customise |
174
+ | Canceled | Cancelled |## NumbersUse numbers, don't spell them out.| ✅ **Do** | ❌ **Don't** |
175
+ | ------------------------------- | ---------------------------------- |
176
+ | 14 | Fourteen |
177
+ | You have 5 jobs scheduled today | You have five jobs scheduled today |#### Use commas| ✅ **Do** | ❌ **Don't** |
178
+ | -------- | ----------- |
179
+ | 140,000 | 140 k |#### Use the En dash ( – )As stated in the hyphens section, use an En dash when you want to show a
180
+ numerical range and don't use a space.| ✅ **Do** | ❌ **Don't** |
181
+ | ------------- | --------------- |
182
+ | Between 10-15 | Between 10 - 15 |#### AbbreviationDon't abbreviate numbers when there's a decimal place involved. It's unlikely
183
+ within Jobber, a platform that deals in quotes and invoices, that the numbers
184
+ after a decimal place are going to be irrelevant. There is no need to put a
185
+ decimal place if the post decimal place value is zero (.00).As stated, don't use shorteners such as "k", this makes Jobber seem less focused
186
+ on accuracy.| ✅ **Do** | ❌ **Don't** |
187
+ | --------- | ----------- |
188
+ | $3,345.34 | $3,345 |
189
+ | $32,000 | $32 k |#### HyphensUse a hyphen with phone numbers. Don't use spaces.| ✅ **Do** | ❌ **Don't** |
190
+ | ------------ | -------------- |
191
+ | 912-790-5542 | (912) 790-5542 |## TimeSPs can choose between 12 hour and 24 hour time formats in their settings, so
192
+ this guidance isn't based on which one Jobber prefers. Respect the user's
193
+ locale and product settings, and use existing localized time formatters when
194
+ available instead of building time strings by hand.Examples in this guide assume en-US. The localized formatter may produce
195
+ different output in other locales - trust it over hand-built strings.If you're implementing a new surface, first look for existing
196
+ internationalization or formatting helpers in that product.For both formats, use a colon (:) rather than a period when the localized
197
+ format uses numeric times. Example: `11:40`### 12 HourWhen the localized format uses 12 hour time, include AM or PM using the
198
+ formatter's localized output.- Include a space between the last number "Scheduled for 11:40 AM"
199
+ - Use the En dash for ranges, and make sure AM or PM is included in both times
200
+ "10:00 AM–11:40 AM"| ✅ **Do** | ❌ **Don't** |
201
+ | ----------------- | ------------------- |
202
+ | 2:00 PM | 2 pm |
203
+ | 11:40 AM | 11.40 AM |
204
+ | 11:40 AM–12:20 PM | 11.40 A.M–12.20 P.M |### 24 HourWhen the localized format uses 24 hour time, there is no need to add AM or PM.
205
+ Remember that times before 10:00 require a zero at the start "09:59"| ✅ **Do** | ❌ **Don't** |
206
+ | -------- | ----------- |
207
+ | 02:00 | 2:00 AM |
208
+ | 19:40 | 19:40 PM |### Time durationDisplay hours, minutes and seconds when a timer is actively running.| ✅ **Do** | ❌ **Don't** |
209
+ | -------- | ----------- |
210
+ | 0:04:31 | 0:04 |Display hours and minutes rounded up when referring to a record of time.| ✅ **Do** | ❌ **Don't** |
211
+ | ----------- | ----------- |
212
+ | 1 hr 21 min | 1:21:21 |### Time unit standardsUse these time unit abbreviations based on available space and context. Keep
213
+ styling consistent across a screen or component.| **Unit** | **Full** | **Abbreviated** | **Condensed** |
214
+ | -------- | -------- | --------------- | ------------- |
215
+ | Seconds | seconds | sec | s |
216
+ | Minutes | minutes | min | m |
217
+ | Hours | hours | hr | h |
218
+ | Days | days | days | d |#### General rules- Use **full words** when space allows
219
+
220
+ > 4 hours and 12 minutes.
221
+
222
+ - Use **abbreviated form** in dense UIs or mobile
223
+
224
+ > 4 hr 12 min
225
+
226
+ - Don’t mix styles within the same string
227
+ > ✅ 2 hr 10 min ❌ 2 h 10 min#### ✅ Time range formattingUse standard punctuation and spacing for time unit standards.| ✅ **Do** | ❌ **Don't** |
228
+ | ----------- | ------------------------------------ |
229
+ | 1 hr 15 min | 1hr 15minutes |
230
+ | 45 minutes | 45 min *(if space allows full word)* |## DatesDates and date-times should respect the user's locale and product settings. Do
231
+ not enforce a single punctuation style, month length, or date-part order across
232
+ all surfaces.Examples in this guide assume en-US. Localized formatters may produce different
233
+ punctuation, abbreviations, and ordering in other locales, so trust them over
234
+ hand-built strings.When a localized formatter is available, use it rather than building date
235
+ strings by hand. This applies to punctuation, month abbreviations, whether the
236
+ year is shown, and the order of date and time values.If you're implementing a new surface, first look for existing
237
+ internationalization or formatting helpers in that product.Avoid custom shorthand that overrides the localized format.| ✅ **Do** | ❌ **Don't** |
238
+ | --------------- | -------------- |
239
+ | December 5 2025 | December 5 '25 |
240
+ | Oct 15 | Oct 15th |When communicating a date range, preserve the localized date format on both
241
+ sides of the range and use the En dash ( – ) between the start and end values.
242
+ If the range overlaps a year, it needs to be indicated.| ✅ **Do** | ❌ **Don't** |
243
+ | ------------------------------------------ | ------------------------------------ |
244
+ | Dec 31 2022, 2:00 PM – Jan 1 2023, 3:00 PM | Dec 31, 2:00 PM, 2022 Jan 1, 3:00 PM |
245
+ | October 12 – November 17 | October 12-November 17 |
package/dist/docs/index.md CHANGED
@@ -42,6 +42,7 @@
42
42
  [Flex](./Flex/Flex.md)
43
43
  [FormatFile](./FormatFile/FormatFile.md)
44
44
  [FormatRelativeDateTime](./FormatRelativeDateTime/FormatRelativeDateTime.md)
45
+ [formatting](./formatting/formatting.md)
45
46
  [Frame](./Frame/Frame.md)
46
47
  [Gallery](./Gallery/Gallery.md)
47
48
  [Glimmer](./Glimmer/Glimmer.md)
@@ -71,6 +72,7 @@
71
72
  [Page](./Page/Page.md)
72
73
  [page-layouts](./page-layouts/page-layouts.md)
73
74
  [Popover](./Popover/Popover.md)
75
+ [product-vocabulary](./product-vocabulary/product-vocabulary.md)
74
76
  [ProgressBar](./ProgressBar/ProgressBar.md)
75
77
  [Radii](./Radii/Radii.md)
76
78
  [RadioGroup](./RadioGroup/RadioGroup.md)
@@ -97,3 +99,4 @@
97
99
  [Typography](./Typography/Typography.md)
98
100
  [Typography](./Typography/Typography.md)
99
101
  [usage-guidelines](./usage-guidelines/usage-guidelines.md)
102
+ [voice-and-tone](./voice-and-tone/voice-and-tone.md)
package/dist/docs/product-vocabulary/product-vocabulary.md ADDED
@@ -0,0 +1,524 @@
1
+ # Product vocabulary
2
+
3
+ When and how to use words for our in-product experience.
4
+
5
+ For an overview of how we speak on behalf of the Jobber brand, refer to the
6
+ [Voice and Tone Guidelines](https://jobber.atlassian.net/l/c/8vMbiEG1).
7
+
8
+ For feature and product positioning guidance, refer to the
9
+ [Product Messaging Guide](https://docs.google.com/document/d/1W8CUyeJUIgbUXuWh87mgeoWScyL1OuF0-2hUujhP1Rs/edit?usp=sharing).
10
+
11
+ ***
12
+
13
+ ## People and us
14
+
15
+ ### account / profile
16
+
17
+ Use **account** in reference to the SP's business' Jobber account.
18
+
19
+ | ✅ **Do** | ❌ **Don't** |
20
+ | ------------------------------------------------- | ------------------------------------------------------------------- |
21
+ | Only the account owner can set up Jobber Payments | Your account can not set up Jobber Payments for this Jobber account |
22
+
23
+ Use **profile** for individual users to reduce ambiguity.
24
+
25
+ | **✅ Do** | **❌ Don't** |
26
+ | --------------------------------------------------------- | -------------------------------------------------------------------- |
27
+ | Join Lawn Care Pro Co. on Jobber by creating your profile | Join Lawn Care Pro Co.'s account by creating your own Jobber account |
28
+
29
+ ### administrator / admin
30
+
31
+ Always refer to this permission set as **administrator** permission for
32
+ consistency with what appears on **Manage Team**.
33
+
34
+ ### client / customer
35
+
36
+ We call our Jobber subscribers **customers** and we call the people they serve
37
+ **clients**.
38
+
39
+ | **✅ Do** | **❌ Don't** |
40
+ | ------------------------------------------------------- | --------------------------------------------------------- |
41
+ | All selected invoices have been emailed to your clients | All selected invoices have been emailed to your customers |
42
+
43
+ Sometimes in product, the context makes sense to use **customer** as terms our
44
+ integration partners use or as a blanket term for existing clients and new
45
+ leads.
46
+
47
+ | **✅ Do** | **❌ Don't** |
48
+ | ---------------------------------------------------- | ------------------------------------------------------ |
49
+ | Sync clients with active QuickBooks Online customers | Sync customers with active QuickBooks Online customers |
50
+
51
+ ### Jobber / Jobber.com / Jobber mobile app
52
+
53
+ Refer to our overall software regardless of platform as **Jobber**.
54
+
55
+ When its necessary to be platform specific, use **Jobber.com** when referring to
56
+ the app accessed through our website when a user logs in.
57
+
58
+ | **✅ Do** | **❌ Don't** |
59
+ | ----------------------------------------------- | ----------------------------------- |
60
+ | View your schedule by logging in on Jobber.com. | View your schedule on Jobber Online |
61
+
62
+ Use **Jobber mobile app** when referring to the iOS or Android version of
63
+ Jobber.
64
+
65
+ | **✅ Do** | **❌ Don't** |
66
+ | -------------------------------------------- | ------------------------------------------- |
67
+ | View your schedule in the Jobber mobile app. | View your schedule in the Jobber mobile app |
68
+
69
+ ### users / team / team members / field worker
70
+
71
+ Use **users** when referring to the account's user limit, permissions, or
72
+ individual team management.
73
+
74
+ | **✅ Do** | **❌ Don't** |
75
+ | ------------------------------------------------ | -------------------------------------------------- |
76
+ | This user will be over your account’s user limit | This person will be over your account's user limit |
77
+
78
+ Never use **users** to refer to an individual directly.
79
+
80
+ | **✅ Do** | **❌ Don't** |
81
+ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
82
+ | Feedback from people like you will help us shape the future of this feature. | The feedback we receive from users like you will help shape the future of this feature. |
83
+
84
+ Use **team member** or team when referring to assignments, time sheets and other
85
+ work specific areas.
86
+
87
+ | **✅ Do** | **❌ Don't** |
88
+ | -------------------------------------------------- | ------------------------------------------- |
89
+ | No team members are currently assigned to this job | No users are currently assigned to this job |
90
+
91
+ Never use **fieldworker** as this does not cover all company roles
92
+ appropriately.
93
+
94
+ ### we / our
95
+
96
+ Generally avoid referring to Jobber as **we** - focus on the user and what they
97
+ can do rather than on Jobber itself.
98
+
99
+ | **✅ Do** | **❌ Don't** |
100
+ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
101
+ | The Mailchimp integration could not be set up. Please correct the following errors: | We weren't able to set up your Mailchimp integration. Please correct the following errors: |
102
+
103
+ Use **we** when we are actually performing an action for the user or making a
104
+ suggestion.
105
+
106
+ | **✅ Do** | **❌ Don't** |
107
+ | ------------------------------------------------------------------ | --------------------------------------------------------------------------- |
108
+ | We'll email you as soon as we hear back from the cardholder's bank | You'll receive an email when a response is given from the cardholder's bank |
109
+
110
+ Use **our** when referencing our teams, help center, or services we offer.
111
+
112
+ | **✅ Do** | **❌ Don't** |
113
+ | -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
114
+ | Jobber Payments is our seamless and secure online payment processor. | Jobber Payments is a seamless and secure online payment processor in Jobber |
115
+
116
+ ### you / you're / you are
117
+
118
+ Referring to the user directly can help avoid awkward phrasing in our messaging.
119
+ Stay human.
120
+
121
+ | **✅ Do** | **❌ Don't** |
122
+ | ------------------------------------ | -------------------------------------------------------- |
123
+ | You are over your plan’s user limit. | This Jobber account is over the user limit of it's plan. |
124
+
125
+ For validation and inline errors, avoid saying the user caused the error.
126
+
127
+ | **✅ Do** | **❌ Don't** |
128
+ | ------------------------------- | -------------------------------------- |
129
+ | Deposit amount must be positive | Your entered deposit amount is invalid |
130
+
131
+ ## Actions
132
+
133
+ ### above / below / left / right
134
+
135
+ Avoid spatial terms to direct users as they can be misinterpreted or irrelevant
136
+ depending on screen size, screen reader, and so on. Reference a call to action
137
+ and the component directly when possible.
138
+
139
+ | **✅ Do** | **❌ Don't** |
140
+ | ------------------------------------------------------------ | ------------------------------------------------------------------ |
141
+ | Finish linking your Google and Jobber accounts by logging in | Finish linking your Google and Jobber accounts by logging in below |
142
+ | View the sample's details in the following list | Click on the request below to view it's details |
143
+
144
+ ### add / create / new
145
+
146
+ Use **create new** when a user is generating something from scratch within
147
+ Jobber. Abbreviating to **New \[object]** for page or view titles.
148
+
149
+ Use **add** when a user is adding something to an object in Jobber, even if that
150
+ object is being newly created (ex. a note).
151
+
152
+ ### back / continue / next / previous
153
+
154
+ Use **continue** and **back** (or an accessible back arrow icon) when progress
155
+ is saved at each step on a form (ie. Save and Continue).
156
+
157
+ Use **next** and **previous** in product tours or in pagination.
158
+
159
+ ### click / tap / press
160
+
161
+ Avoid using verbs that are platform specific and that make assumptions about how
162
+ a user is navigating an interface.
163
+
164
+ | **✅ Do** | **❌ Don't** |
165
+ | ---------------------------- | ------------------------- |
166
+ | Select an option to continue | Tap an option to continue |
167
+
168
+ ### close / dismiss / cancel
169
+
170
+ Use an X icon with "**close**" as the accessible label for modals. Use
171
+ **cancel** for modals where the user can lose changes, such as forms.
172
+
173
+ ### delete / destroy / remove
174
+
175
+ Use **delete** when permanently erasing information available in Jobber. Always
176
+ follow up with a confirmation dialog. Think of **delete** as the inverse of
177
+ [**create**](#add--create--new).
178
+
179
+ | **✅ Do** | **❌ Don't** |
180
+ | ------------- | ------------- |
181
+ | Delete Quote | Remove Quote |
182
+ | Delete Client | Remove Client |
183
+
184
+ Use **remove** when hiding information from the current view but not permanently
185
+ erasing it. Think of **remove** as the inverse of [**add**](#add--create--new).
186
+
187
+ | **✅ Do** | **❌ Don't** |
188
+ | --------------------------------- | --------------------------------- |
189
+ | Remove users over your plan limit | Delete users over your plan limit |
190
+ | Remove tax rate | Delete tax rate from group rate |
191
+
192
+ Never use **destroy** unless Wreck-it Ralph is making a cameo.
193
+
194
+ ### enable / disable / turn on / turn off / connect / disconnect
195
+
196
+ When discussing Jobber features, use **turn on** and **turn off** for
197
+ controlling the availability of it on an account.
198
+
199
+ | **✅ Do** | **❌ Don't** |
200
+ | ----------------------- | ---------------------- |
201
+ | Turn on Jobber Payments | Enable Jobber Payments |
202
+
203
+ When referencing the apps in the App Marketplace, use **connect** and
204
+ **disconnect** for controlling their availability.
205
+
206
+ | **✅ Do** | **❌ Don't** |
207
+ | ----------------- | ----------------- |
208
+ | Connect Mailchimp | Turn on Mailchimp |
209
+
210
+ ### export / import / download / upload
211
+
212
+ Use **export** and **import** when data is moving in or out of Jobber and is
213
+ converted into a different format.
214
+
215
+ | **✅ Do** | **❌ Don't** |
216
+ | ------------- | --------------- |
217
+ | Import CSV | Upload CSV |
218
+ | Export Report | Download Report |
219
+
220
+ Use **download** and **upload** when data is being transferred in or out of
221
+ Jobber in the same format.
222
+
223
+ | **✅ Do** | **❌ Don't** |
224
+ | -------------------- | ------------------ |
225
+ | Upload photo | Import photo |
226
+ | Download attachments | Export attachments |
227
+
228
+ ### got it
229
+
230
+ Use **got it** as a call to action when a user can acknowledge a message without
231
+ taking action on it, like in promo cards or onboarding.
232
+
233
+ ### link / attach / copy / clone / duplicate
234
+
235
+ Use **link** when the same information is shown elsewhere in Jobber but not
236
+ copied to create a new version.
237
+
238
+ | **✅ Do** | **❌ Don't** |
239
+ | ---------------------------------- | ---------------------------------- |
240
+ | Link quote note to related invoice | Copy quote note to related invoice |
241
+
242
+ Use **copy** when Jobber creates a new version that would have no effect on the
243
+ original when edited.
244
+
245
+ | **✅ Do** | **❌ Don't** |
246
+ | ---------- | --------------- |
247
+ | Copy Quote | Duplicate Quote |
248
+
249
+ Use **attach** when describing receipts, forms or signatures being added to an
250
+ object. For file selection, use **select a file** for consistency.
251
+
252
+ | **✅ Do** | **❌ Don't** |
253
+ | ----------------------------------------------------------- | ----------------------------------------------------------- |
254
+ | Attach a receipt to this expense [Select a file](#actions) | Attach a receipt to this expense [Attach a file](#actions) |
255
+
256
+ ### refresh / reload
257
+
258
+ Use **refresh** in error messages or on error banner actions, for system or
259
+ connectivity errors. Although 'Reload' and 'Refresh' have the same meaning, use
260
+ 'Refresh' for consistency.
261
+
262
+ | **✅ Do** | **❌ Don't** |
263
+ | -------- | ----------- |
264
+ | Refresh | Reload |
265
+
266
+ ### save / update / submit
267
+
268
+ Use **save** at the end of a form on completion or **save changes** on editing.
269
+
270
+ | **✅ Do** | **❌ Don't** |
271
+ | ----------------------- | ----------- |
272
+ | Save Job / Save Changes | Update Job |
273
+
274
+ Use **update** when individual changes or groups of changes can be saved inline
275
+ without needing to save a whole view or page.
276
+
277
+ | **✅ Do** | **❌ Don't** |
278
+ | --------------------- | ------------------- |
279
+ | Update Business Hours | Save Business Hours |
280
+
281
+ Use **submit** when an account user is completing and sending a form to Jobber,
282
+ or when a service consumer is submitting a form to their service provider.
283
+
284
+ | **✅ Do** | **❌ Don't** |
285
+ | --------------- | ------------- |
286
+ | Submit Feedback | Save Feedback |
287
+
288
+ ### sync / pull / push
289
+
290
+ Use sync when a process with integration is active or to describe an integration
291
+ in a general way.
292
+
293
+ | **✅ Do** | **❌ Don't** |
294
+ | ------------------------------------ | ------------------------------------ |
295
+ | It appears the sync may have stalled | It appears the push may have stalled |
296
+
297
+ Use **pull** or **push** when the sync is explicitly one-way with any aspect of
298
+ an integration.
299
+
300
+ | **✅ Do** | **❌ Don't** |
301
+ | ------------------------------------------------------ | ------------------------------------------------------ |
302
+ | Push approved timesheet hours | Sync approved timesheet hours |
303
+ | All active items will be pulled from QuickBooks Online | All active items will be synced from QuickBooks Online |
304
+
305
+ ### vault / vaulted / add / store
306
+
307
+ Avoid using **vault** or **vaulted** for card storage. Use **add** and **store**
308
+ instead.
309
+
310
+ | **✅ Do** | **❌ Don't** |
311
+ | ------------------------------------- | ------------------------------------------------ |
312
+ | Stored cards will need to be re-added | Any vaulted cards will need to be re-established |
313
+
314
+ ## Concepts and items
315
+
316
+ In general, none of these should be capitalized unless explicitly stated or when
317
+ used in a page title.
318
+
319
+ ### address / property / service address / billing address
320
+
321
+ Use **property** when referring to the service address, custom fields and tax
322
+ rate altogether.
323
+
324
+ On quotes and invoices, use **service address** instead of property address to
325
+ clearly differentiate between a **billing address**.
326
+
327
+ ### app / application / integration
328
+
329
+ Use app when referring to the Jobber app itself, or the apps provided within the
330
+ App Marketplace. Apps in the Marketplace can also just be referred to by their
331
+ brand name.
332
+
333
+ | **✅ Do** | **❌ Don't** |
334
+ | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
335
+ | Try the Jobber app | Try the Jobber Mobile Application |
336
+ | Connect Mailchimp to your account to automate your marketing. | Connect the Mailchimp integration to your account to automate your marketing. |
337
+
338
+ Use integration when referring to how an app connects with Jobber.
339
+
340
+ | **✅ Do** | **❌ Don't** |
341
+ | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
342
+ | The Mailchimp integration will be removed because the user who connected it to Jobber no longer has administrator permissions. | The Mailchimp app will be removed because the user who connected it to Jobber no longer has administrator permissions. |
343
+
344
+ ### assessment / visit / appointment
345
+
346
+ Use **appointment** to describe both visits and assessments to service consumers
347
+ in emails and within client hub, or to refer to scheduled events in the calendar
348
+ in a generalized manner.
349
+
350
+ Within Jobber, use **visit** or **assessment** as the name for those distinct
351
+ items.
352
+
353
+ ### attachment / file
354
+
355
+ Use **attachments** when referring to files as a grouping rather than singular
356
+ or as a verb.
357
+
358
+ | **✅ Do** | **❌ Don't** |
359
+ | ---------------------------- | ----------------- |
360
+ | Internal notes & attachments | Add an attachment |
361
+ | Quote attachments | Attach a file |
362
+ | Email attachments | |
363
+
364
+ ### client hub
365
+
366
+ Always refer to our service consumer portal as the customer's client hub. Stick
367
+ to sentence case, as it is a general term, not branded.
368
+
369
+ | **✅ Do** | **❌ Don't** |
370
+ | ------------------------------------------ | ------------------------------------------ |
371
+ | Changes will be visible in your client hub | Changes will be visible in your Client Hub |
372
+
373
+ ### estimate / quote
374
+
375
+ TBD
376
+
377
+ ### help center / help docs / help documentation / learn more
378
+
379
+ Use Help Center exclusively when linking to additional help documentation, and
380
+ link to the related document directly when possible.
381
+
382
+ | \*\*✅ Do \*\* | **❌ Don't** |
383
+ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
384
+ | Learn how disputes work and how to prevent them in our [Help Center](#concepts-and-items) | Learn how disputes work and how to prevent them in our [Documentation](#concepts-and-items) |
385
+
386
+ Avoid using **learn more** as a link's label as it is poor for accessibility.
387
+ Stick to descriptive labels that give more context of where the link is taking a
388
+ user.
389
+
390
+ | **✅ Do** | **❌ Don't** |
391
+ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
392
+ | Learn how disputes work and how to prevent them in our [Help Center](#concepts-and-items) | Want to know how disputes work and how to prevent them? [Learn more](#concepts-and-items) |
393
+
394
+ ### Jobber Card Reader
395
+
396
+ Always refer to **Jobber Card Reader** in title case, as it's our branded
397
+ feature.
398
+
399
+ ### Jobber Payments
400
+
401
+ Always refer to **Jobber Payments** in title case, as it's our branded feature.
402
+
403
+ ### Jobber Labs / beta
404
+
405
+ We always refer to our area for experimentation with new functionality as the
406
+ branded feature, **Jobber Labs**.
407
+
408
+ ### products and services / products & services / line items
409
+
410
+ Use **products and services** (and avoid flipping the words) when referring to
411
+ the master list of them in body text, and sentences in general.
412
+
413
+ | **✅ Do** | **❌ Don't** |
414
+ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
415
+ | The exported products and services are attached in a CSV file | Attached are your exported products & services in a CSV file |
416
+ | Would you like to add recommended products and services based on your industry to your account? | Would you like to add recommended line items based on your industry to your account? |
417
+
418
+ Use **products & services** for titles and navigation to keep things short and
419
+ snappy.
420
+
421
+ | **✅ Do** | **❌ Don't** |
422
+ | -------------------------- | ---------------------------- |
423
+ | Add to Products & Services | Add to Products and Services |
424
+
425
+ Use **line items** to describe the groupings of products and services on a
426
+ quote, job or invoice.
427
+
428
+ | **✅ Do** | **❌ Don't** |
429
+ | ---------------------- | ------------------------------- |
430
+ | Add line item to quote | Add product or service to quote |
431
+
432
+ ### subscription / subscribe(d) / plan
433
+
434
+ Use **subscription** in reference to an SP’s individual recurring payment and
435
+ how it is managed.
436
+
437
+ Use **subscribe(d)** as a verb referring to the act of choosing, or having
438
+ chosen, a plan.
439
+
440
+ Use **plan** in reference to
441
+ [Jobber's pre-determined feature templates](https://getjobber.com/pricing/)
442
+ users can subscribe to.
443
+
444
+ ### task / basic task / to do
445
+
446
+ Use **task** when referring to all task items in Jobber.
447
+
448
+ | **✅ Do** | **❌ Don't** |
449
+ | -------- | -------------- |
450
+ | New task | New basic task |
451
+
452
+ ### text / text message / sms
453
+
454
+ Use **text message** where space allows, and **text** as an action verb when
455
+ space is limited.
456
+
457
+ ### timesheets
458
+
459
+ **Timesheets** is a single word in Jobber.
460
+
461
+ | **✅ Do** | **❌ Don't** |
462
+ | ------------------ | ------------------- |
463
+ | Approve timesheets | Approve time sheets |
464
+
465
+ ### track / log / record
466
+
467
+ TBD
468
+
469
+ ## General phrasing
470
+
471
+ ### please
472
+
473
+ Avoid **please** for the most part, particularly in error messages to avoid
474
+ overuse and loss of meaning.
475
+
476
+ | **✅ Do** | **❌ Don't** |
477
+ | ---------------- | ----------------------- |
478
+ | Enter your email | Please enter your email |
479
+
480
+ Use **please** sparingly when we're requesting the user to take additional
481
+ effort to resolve an issue, outside of standard errors.
482
+
483
+ | **✅ Do** | **❌ Don't** |
484
+ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
485
+ | Your card cannot be used to make this payment, please contact your card issuer | Your card cannot be used to make this payment. Contact your card issuer. |
486
+
487
+ ### sorry
488
+
489
+ Avoid using **sorry** much like the word please, as they can lose meaning when
490
+ overused.
491
+
492
+ | **✅ Do** | **❌ Don't** |
493
+ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
494
+ | Client cannot have more than 1500 email addresses | Sorry, can not add email address. You may not have more than 1500 email addresses on a single client. |
495
+
496
+ ### success, successful, successfully
497
+
498
+ Avoid these words in general as they are redundant.
499
+
500
+ | **✅ Do** | **❌ Don't** |
501
+ | ----------------------- | -------------------------------- |
502
+ | Your password was reset | Successfully reset your password |
503
+
504
+ If referring to the **Success** team, always capitalize Success.
505
+
506
+ | **✅ Do** | **❌ Don't** |
507
+ | ---------------------------------------------------- | ---------------------------------------------------- |
508
+ | Please contact our Success team for more information | Please contact the success team for more information |
509
+
510
+ ### valid / invalid
511
+
512
+ Avoid defaulting to generic messages for invalid fields where possible, as they
513
+ can be unhelpful.
514
+
515
+ | **✅ Do** | **❌ Don't** |
516
+ | ------------------------------ | -------------------------- |
517
+ | Email address must contain a @ | Enter a valid phone number |
518
+
519
+ Sometimes we can't account for all states of an error though, in this case err
520
+ on using "valid".
521
+
522
+ | **✅ Do** | **❌ Don't** |
523
+ | ----------------------------- | ------------------------------------------------ |
524
+ | Enter a valid expiration year | The expiration year is invalid, please try again |
package/dist/docs/voice-and-tone/voice-and-tone.md ADDED
@@ -0,0 +1,385 @@
1
+ # Voice & tone
2
+
3
+ If you work with Jobber — whether you're writing product copy, designing an
4
+ interface, building an AI feature, or crafting a marketing email — there's a
5
+ good chance you're speaking on behalf of the brand. To make sure we all sound
6
+ like the same Jobber, we have guidelines for voice and tone.
7
+
8
+ Our **voice** is our personality. It's consistent, recognizable, and doesn't
9
+ change regardless of who we're talking to or what we're building. Our **tone**
10
+ is how we apply that voice in a given moment. It shifts based on context and
11
+ audience, but it always operates within the boundaries the voice sets.
12
+
13
+ Think of it like this: you're the same person whether you're talking to a new
14
+ client or a longtime friend. Your personality doesn't change, but how you
15
+ express it does.
16
+
17
+ This document covers the foundational layer: what Jobber's voice is, how tone
18
+ works as a system, and the principles that apply everywhere. Audience-specific
19
+ guidance builds on this foundation and lives separately.
20
+
21
+ ## Jobber's voice
22
+
23
+ Jobber's voice is confident and direct, but never cold. We're loyal to our users
24
+ and hungry for their success, and that comes through in everything we write.
25
+ We're not especially cute, gentle, or goofy. There's a time and place for that,
26
+ but we're here to help people run better businesses, and our voice reflects
27
+ that.
28
+
29
+ We're also a collaborator, not just a tool. That means we show up with relevant
30
+ knowledge when it's needed, back users up when they're busy, and earn trust by
31
+ being consistent and transparent. We never make users feel talked down to, and
32
+ we never make them feel like they're on their own.
33
+
34
+ If something sounds stiff or unnatural out loud, it's probably not in our voice.
35
+
36
+ In practice, that means:
37
+
38
+ * **Lead with what matters.** Don't make people work to find the point.
39
+ * **Use the simplest word that does the job.** Never use jargon to sound
40
+ credible.
41
+ * **Be direct without being blunt.** Say what you mean, but stay human about it.
42
+ * **Show the work, not the complexity.** If something happens behind the scenes,
43
+ say what it did, not how it did it.
44
+ * **Don't perform positivity.** Sincerity lands better than enthusiasm.
45
+ * **Meet frustration with honesty and a clear path forward.**
46
+
47
+ ## Our priorities
48
+
49
+ When writing for Jobber, two things should always be true.
50
+
51
+ **Clarity first.** Every word should earn its place. If a message isn't
52
+ immediately understood, it isn't doing its job. Pick one thing to say and say it
53
+ well.
54
+
55
+ **Empathy always.** Put yourself in the user's position. What are they trying to
56
+ do right now? What do they already know? What would make this moment harder or
57
+ easier? Let those answers shape what you write.
58
+
59
+ Tone, energy, and detail level all follow from these two.
60
+
61
+ ## Tone
62
+
63
+ Our voice stays constant. Our tone adapts.
64
+
65
+ In product, tone shifts based on two things: the context the user is in, and
66
+ where they are in their journey with Jobber. Getting both right is the
67
+ difference between copy that feels generic and copy that feels like it was
68
+ written for this moment and this person.
69
+
70
+ ## Getting started
71
+
72
+ This is often the first time a user encounters a feature or flow. It's a moment
73
+ of potential — they're here because they want to do something. Don't waste it
74
+ with technical explanations or feature descriptions.
75
+
76
+ **Lead with the action.** Start with a verb. The user should know what to do
77
+ before they know why.
78
+
79
+ **Front-load the value.** Put the most important information first. Users scan
80
+ before they read — if the value isn't in the first few words, it may not land at
81
+ all.
82
+
83
+ **One idea at a time.** Don't bundle multiple instructions or benefits into a
84
+ single message. If there's more to say, expose the steps without explaining them
85
+ all upfront. Take it one at a time.
86
+
87
+ **Keep it short.** Aim for one sentence. Two at most.
88
+
89
+ **Avoid technical language.** Write for someone encountering this for the first
90
+ time. If a word needs explaining, replace it.
91
+
92
+ | ✅ **Do** | ❌ **Don't** |
93
+ | -------------------------------------------- | ------------------------------------------------------------------------- |
94
+ | Add your first client to get started | The client management module allows you to store and organize client data |
95
+ | Set up your schedule to start booking jobs | Welcome to the scheduling feature |
96
+ | Create a quote to start winning work | Quote creation is now available |
97
+ | Connect your bank account to get paid faster | Payment integration setup required |
98
+
99
+ ## Taking action
100
+
101
+ The user is focused and moving. Copy should serve the action, not compete with
102
+ it. Keep it minimal when the task is clear. Add context only when the
103
+ consequences aren't obvious or the stakes are high.
104
+
105
+ **Use active voice.** The user is the subject. They do things — things don't
106
+ happen to them.
107
+
108
+ **Be specific.** Generic labels create doubt. Tell the user exactly what will
109
+ happen when they act.
110
+
111
+ **Lead with a verb.** Button labels should start with an action word and use
112
+ title case. No punctuation.
113
+
114
+ **Match the weight of the action.** A routine task needs a short label. A
115
+ significant or irreversible action warrants a brief line of context — enough to
116
+ feel considered, not alarming.
117
+
118
+ **Never use filler labels.** Vague labels like "Click here" or "OK" tell the
119
+ user nothing. Even "Submit" on its own is ambiguous — "Submit Documents" or
120
+ "Submit Request" is always clearer. Every label should be meaningful on its own.
121
+
122
+ **Active voice applies to everything.** Not just buttons — confirmations,
123
+ instructions, helper text, error messages. If Jobber is doing something, say
124
+ "we." If the user is doing something, say "you." Passive voice creates distance
125
+ and ambiguity.
126
+
127
+ | ✅ **Do** | ❌ **Don't** |
128
+ | -------------------------------------------- | ----------------------------- |
129
+ | Send Quote | Submit |
130
+ | Schedule Job | OK |
131
+ | Add Line Item | Click here |
132
+ | Save Changes | Yes |
133
+ | Delete Client | Click here to proceed |
134
+ | Submit Documents | Submit |
135
+ | Your quote has been sent to Sarah | The quote was sent |
136
+ | We drafted this quote based on your last job | A draft has been generated |
137
+ | You haven't added any line items yet | No line items have been added |
138
+
139
+ ## Success
140
+
141
+ Most success states are routine. A job was scheduled, a quote was sent, changes
142
+ were saved. Acknowledge it clearly and move on. Users don't need enthusiasm —
143
+ they need confirmation.
144
+
145
+ **Be brief and specific.** Say what happened. Don't editorialize.
146
+
147
+ **Don't over-celebrate the ordinary.** Completing a normal workflow isn't an
148
+ achievement. Treating it like one feels hollow and, over time, erodes trust.
149
+
150
+ **Save celebration for milestones that actually matter.** First job booked,
151
+ first payment received, hitting a revenue goal — these are moments worth
152
+ marking. Celebrate the user's achievements, not Jobber's processes. Completing a
153
+ sync or finishing a setup step is Jobber doing its job, not the user doing
154
+ theirs.
155
+
156
+ ### Routine acknowledgment
157
+
158
+ | ✅ **Do** | ❌ **Don't** |
159
+ | ------------------------- | ---------------------------------------- |
160
+ | Quote sent to Sarah | Quote sent successfully! |
161
+ | Job scheduled for Tuesday | Great job! Your job has been scheduled! |
162
+ | Changes saved | Done! Everything's saved and good to go! |
163
+
164
+ ### Success with additional context
165
+
166
+ Sometimes completing an action unlocks something new. When it does, use the
167
+ moment to tell the user what's most relevant to them right now — not everything
168
+ that's changed, just what matters most in that moment.
169
+
170
+ | ✅ **Do** | ❌ **Don't** |
171
+ | -------------------------------------------------------------- | ---------------------------------- |
172
+ | Jobber Payments is set up. You can now accept payments online. | Integration successful! Great job! |
173
+
174
+ ### Milestone moments
175
+
176
+ | ✅ **Do** | ❌ **Don't** |
177
+ | ---------------------------------------------------------- | ------------------------------------ |
178
+ | Congrats, you've booked your first job. | Woohoo! First job unlocked! 🎉 |
179
+ | Milestone achieved: $100k in revenue this year. Nice work. | Amazing work! You're a superstar! 💰 |
180
+ | Your first payment just came in. That's a big deal. | 🎉 You got paid! Congrats!! |
181
+ | 100 jobs completed. You're building something real. | 100 jobs! You're on fire! 🔥 |
182
+ | Your first 5-star review. That's what it's all about. | Woohoo! Someone loves you! ⭐⭐⭐⭐⭐ |
183
+
184
+ ## Guidance
185
+
186
+ Good guidance is invisible. Users shouldn't notice it — they should just feel
187
+ like the product is easy to use. That means offering help at the right moment,
188
+ in the right amount, and then stepping back.
189
+
190
+ **Only guide when it adds something.** If the UI makes the next step obvious,
191
+ don't add text just to fill the space. Unnecessary guidance creates noise and
192
+ teaches users to ignore it.
193
+
194
+ **Be specific.** Generic instructions tell the user nothing they couldn't
195
+ already see. Guidance should relate directly to what the user is trying to do
196
+ and why it matters.
197
+
198
+ **Don't repeat the label.** Helper text exists to add context, not echo what's
199
+ already on screen. If a field is labelled "Business Name", the helper text
200
+ shouldn't say "enter your business name."
201
+
202
+ **Let the component and the moment guide you.** A tooltip is a quick answer to a
203
+ specific question. Helper text adds context before someone acts. An empty state
204
+ orients someone who has nothing to work with yet. Each has a different job —
205
+ match what you write to that purpose, not to how much space you have.
206
+
207
+ **Headlines and body copy work together, not in parallel.** The headline carries
208
+ the main idea. Body copy adds context that the headline can't. If you find
209
+ yourself repeating the headline in different words, you don't need body copy.
210
+ Every line should earn its place.
211
+
212
+ | ✅ **Do** | ❌ **Don't** |
213
+ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
214
+ | **Get paid faster** / Accept card payments directly from quotes and invoices. | **Get paid faster** / Get paid faster with Jobber Payments. |
215
+ | **New in scheduling** / You can now drag and drop jobs directly on the calendar. | **New in scheduling** / We've made some improvements to the scheduling feature in Jobber. |
216
+
217
+ ### Empty states
218
+
219
+ | ✅ **Do** | ❌ **Don't** |
220
+ | ------------------------------------------------------------------------ | --------------------- |
221
+ | No jobs scheduled yet. Add your first job to get started. | No data to display |
222
+ | You haven't added any team members. Add someone to start assigning jobs. | No team members found |
223
+ | No clients yet. Add your first one to start sending quotes. | Nothing here yet |
224
+
225
+ ### Helper text
226
+
227
+ | ✅ **Do** | ❌ **Don't** |
228
+ | ----------------------------------------------------------------- | ------------------------ |
229
+ | This is the name your clients will see on quotes and invoices. | Enter your business name |
230
+ | Add your hourly rate so we can calculate job costs automatically. | Enter a number |
231
+ | Choose how far you're willing to travel for a job. | Set your service area |
232
+
233
+ ### General body copy
234
+
235
+ | ✅ **Do** | ❌ **Don't** |
236
+ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
237
+ | Turn on automatic reminders to follow up with clients who haven't responded to a quote. | This feature allows you to configure automated reminder functionality for outstanding quotes. |
238
+ | Your team can see their schedule, update job status, and log time — all from the mobile app. | The mobile application provides team members with access to various job management capabilities. |
239
+ | Connect Jobber to QuickBooks Online to keep your books up to date without the double entry. | This integration enables synchronization between Jobber and QuickBooks Online accounting software. |
240
+
241
+ ## Errors
242
+
243
+ Something has gone wrong. This is not the moment for technical language, humor,
244
+ or vague reassurance. Users are frustrated or confused — meet them with clarity
245
+ and a way forward.
246
+
247
+ **Explain what happened in plain language.** You don't need to surface the
248
+ technical cause, but you do need to tell the user what went wrong in terms that
249
+ mean something to them.
250
+
251
+ **Always give a path forward.** An error without a next step leaves the user
252
+ stuck. Even if the fix is outside Jobber's control, tell them what to do.
253
+
254
+ **Don't blame the user.** Focus on the fix, not the fault. "That email address
255
+ is already in use" is better than "you entered a duplicate email."
256
+
257
+ **Don't be vague to avoid being technical.** "Something went wrong" on its own
258
+ is not helpful. Be as specific as the situation allows.
259
+
260
+ **Be human, not dramatic.** Errors are frustrating enough without the product
261
+ making them feel worse. Stay calm, stay clear.
262
+
263
+ | ✅ **Do** | ❌ **Don't** |
264
+ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
265
+ | We couldn't save your quote. Check your connection and try again. | An error occurred while attempting to save the record. Please retry the operation. |
266
+ | That email address is already linked to an account. Try signing in instead. | The value entered in the email field already exists in the system. |
267
+ | We couldn't process your payment. Check your card details and try again. | Payment processing failed due to an invalid response from the payment gateway. |
268
+ | Something went wrong on our end. Try again or contact support. | Whoopsie! The servers are taking a little nap. Try again soon! 😴 |
269
+
270
+ ## High stakes moments
271
+
272
+ When an action is irreversible or has significant consequences, say so clearly.
273
+ Don't soften it to the point of ambiguity and don't dramatize it to the point of
274
+ panic. Just be direct about what's about to happen.
275
+
276
+ **State the consequence, not just the action.** "Delete" on its own isn't
277
+ enough. Tell the user what they'll lose.
278
+
279
+ **Don't bury the risk.** The consequence should be the first thing the user
280
+ reads, not a footnote.
281
+
282
+ **If something can't be undone, say so.** Don't leave users to assume the
283
+ consequences. A single clear line — "This can't be undone" — is better than
284
+ silence.
285
+
286
+ **Give a genuine out.** Cancel should always be an option, and it should be easy
287
+ to find.
288
+
289
+ **When a headline is present, let it name the action. Use the body to state the
290
+ consequence.**
291
+
292
+ | ✅ **Do** | ❌ **Don't** |
293
+ | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
294
+ | **Delete client** / Sarah Johnson and all her jobs, invoices, and history will be permanently removed. This can't be undone. | **Are you sure?** / Are you sure you want to delete this client? This action will delete the client. |
295
+ | **Cancel your plan** / Your team will lose access at the end of your current billing period. | **Cancel plan** / Canceling your plan will cancel your plan and all associated features. |
296
+ | You're over your team member limit. Purchase additional members or upgrade your plan. | User limit exceeded. Please review your subscription. |
297
+
298
+ ## AI insights
299
+
300
+ Jobber AI has access to two things most tools don't: knowledge of your business
301
+ and knowledge of the industry. A good insight draws on both. A generic one
302
+ wastes the moment.
303
+
304
+ **Be specific to the user.** An insight that could apply to anyone adds no
305
+ value. Ground it in what Jobber actually knows — their clients, their jobs,
306
+ their patterns.
307
+
308
+ **Ask before acting.** Where an action has consequences, check in first. A
309
+ prompt that says "want me to handle this?" respects the user's autonomy. One
310
+ that acts without asking undermines it.
311
+
312
+ **Surface yourself at the right moment.** An insight offered mid-task is an
313
+ interruption. One offered at a natural pause is a collaborator checking in.
314
+
315
+ **Say less.** If it takes more than two sentences to explain an insight, it
316
+ probably isn't ready to be surfaced yet.
317
+
318
+ | ✅ **Do** | ❌ **Don't** |
319
+ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
320
+ | You haven't followed up with 3 clients since last week. Want me to send a reminder? | Jobber AI has detected potential follow-up opportunities in your client list. |
321
+ | Jobs like this one usually take 2 hours. Want to update the estimate? | Based on historical data analysis, your time estimation may require adjustment. |
322
+ | Brian typically prefers morning appointments. Want to schedule accordingly? | Customer preference data suggests scheduling optimization may be beneficial. |
323
+
324
+ ## Motivation
325
+
326
+ Jobber's users are building something. There are moments in the product where
327
+ acknowledging that progress genuinely matters — not as a default tone, but as a
328
+ response to something real happening in their business.
329
+
330
+ **Identify the moment.** Motivation is earned, not assumed. The right moment is
331
+ one where the user has done something meaningful — hit a milestone, made a
332
+ decision, or is close to achieving a goal. Generic encouragement feels hollow.
333
+ Specific acknowledgment feels human.
334
+
335
+ **Match the energy to the moment.** A user closing in on a revenue goal deserves
336
+ more than a neutral confirmation. A user completing a routine task doesn't need
337
+ a pep talk.
338
+
339
+ | ✅ **Do** | ❌ **Don't** |
340
+ | ---------------------------------------------------- | -------------------------------------- |
341
+ | You're $2k away from your revenue goal. Keep going. | Great job completing your tasks today! |
342
+ | 10 quotes sent this week. That's your best week yet. | You're doing amazing! Keep it up! 🌟 |
343
+
344
+ ### Humor
345
+
346
+ A light touch can make Jobber feel human, but only when the moment genuinely
347
+ calls for it. Warmth and humor are not the same thing — a well-timed observation
348
+ that shows Jobber is paying attention will always land better than a joke.
349
+
350
+ Never use humor when a user is frustrated, confused, or at risk of losing
351
+ something. And never let it get in the way of clarity.
352
+
353
+ **In AI interactions**
354
+
355
+ These examples rely on Jobber knowing enough about the user to feel genuine
356
+ rather than generic.
357
+
358
+ | ✅ **Do** | ❌ **Don't** |
359
+ | ------------------------------------------------------- | -------------------------------------------------- |
360
+ | Still at it at 11pm. Let's get this done quickly. | Burning the midnight oil! You're a rockstar! 🌟 |
361
+ | Quiet week — looks like you've got some breathing room. | Wow, not many jobs this week! Hope things pick up! |
362
+
363
+ ## Technical rules
364
+
365
+ For full guidance on capitalization, punctuation, spelling, pronouns, dates, and
366
+ numbers, see [Formatting](../formatting/formatting.md). A few reminders on the rules
367
+ that most directly affect voice and tone:
368
+
369
+ * **American English spelling.** Labor, not labour. Customize, not customise.
370
+ * **Use "you" and "we".** Address users as "you". Refer to Jobber as "we". Avoid
371
+ referring to Jobber in the third person.
372
+ * **Oxford comma.** Use a comma before "and" or "or" in a list. "Jobs, quotes,
373
+ and invoices" not "jobs, quotes and invoices."
374
+
375
+ A few additional rules not covered in formatting:
376
+
377
+ **Use active voice.** Covered in taking action, but it applies everywhere. If
378
+ you find yourself writing "was" or "has been", check if active voice would be
379
+ clearer.
380
+
381
+ **Avoid absolute statements.** Don't make promises you can't keep. "Always",
382
+ "never", "guaranteed" set expectations that erode trust when they aren't met.
383
+
384
+ **Use contextual links.** Link meaningful words or phrases, not "click here" or
385
+ "read more". The link text should make sense on its own.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jobber/components",
3
- "version": "8.13.0",
3
+ "version": "8.13.1-addeditor-cab44cf.0+cab44cfa",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "main": "dist/index.cjs",
@@ -497,7 +497,7 @@
497
497
  "devDependencies": {
498
498
  "@apollo/client": "^3.7.10",
499
499
  "@csstools/postcss-global-data": "^1.0.3",
500
- "@jobber/design": "0.103.0",
500
+ "@jobber/design": "0.103.1-addeditor-cab44cf.11+cab44cfa",
501
501
  "@jobber/hooks": "2.21.0",
502
502
  "@rollup/plugin-alias": "^5.1.0",
503
503
  "@rollup/plugin-commonjs": "^25.0.7",
@@ -551,5 +551,5 @@
551
551
  "> 1%",
552
552
  "IE 10"
553
553
  ],
554
- "gitHead": "bbe63d684891b974697436ac348514b2afc97394"
554
+ "gitHead": "cab44cfa1430ab6784636b2d3db8ad771db0999a"
555
555
  }