From 10a2c6815477c517094dad58fe22b605b8aae54f Mon Sep 17 00:00:00 2001 From: AaronPatterson1 Date: Sun, 23 Aug 2026 16:32:18 -0400 Subject: [PATCH 1/5] Add style, grammar, and punctuation docs page Adds a new /language page documenting writing conventions (style, grammar, and punctuation) with Do/Don't example cards, registers it in the app routes and foundations nav, and adds the CheckCircle and CloseCircle icons used by the example cards. --- packages/_icons/lib/icons/checkCircle.tsx | 35 + packages/_icons/lib/icons/closeCircle.tsx | 35 + packages/_icons/lib/index.tsx | 4 + packages/_site/src/App.tsx | 13 + .../_site/src/pages/components/language.tsx | 1003 +++++++++++++++++ .../components/routes_list_docs_components.ts | 4 + 6 files changed, 1094 insertions(+) create mode 100644 packages/_icons/lib/icons/checkCircle.tsx create mode 100644 packages/_icons/lib/icons/closeCircle.tsx create mode 100644 packages/_site/src/pages/components/language.tsx diff --git a/packages/_icons/lib/icons/checkCircle.tsx b/packages/_icons/lib/icons/checkCircle.tsx new file mode 100644 index 0000000..bad4f10 --- /dev/null +++ b/packages/_icons/lib/icons/checkCircle.tsx @@ -0,0 +1,35 @@ +"use client"; + +import type { ComponentProps } from "react"; +import * as stylex from "@stylexjs/stylex"; +import type { IconProps } from "../base.tsx"; + +const CheckCircleIcon = ({ + extend, + className, + fill = "var(--svg-color, #FCFCFC)", + height = "1.25rem", + width = "1.25rem", + style, + ref, + ...props +}: ComponentProps<"svg"> & IconProps) => ( + + Check + + +); +CheckCircleIcon.displayName = "CheckCircleIcon"; + +export { CheckCircleIcon }; \ No newline at end of file diff --git a/packages/_icons/lib/icons/closeCircle.tsx b/packages/_icons/lib/icons/closeCircle.tsx new file mode 100644 index 0000000..f1d0463 --- /dev/null +++ b/packages/_icons/lib/icons/closeCircle.tsx @@ -0,0 +1,35 @@ +"use client"; + +import type { ComponentProps } from "react"; +import * as stylex from "@stylexjs/stylex"; +import type { IconProps } from "../base.tsx"; + +const CloseCircleIcon = ({ + extend, + className, + fill = "var(--svg-color, #FCFCFC)", + height = "1.25rem", + width = "1.25rem", + style, + ref, + ...props +}: ComponentProps<"svg"> & IconProps) => ( + + Close + + +); +CloseCircleIcon.displayName = "CloseCircleIcon"; + +export { CloseCircleIcon }; \ No newline at end of file diff --git a/packages/_icons/lib/index.tsx b/packages/_icons/lib/index.tsx index 72b115a..ae73680 100644 --- a/packages/_icons/lib/index.tsx +++ b/packages/_icons/lib/index.tsx @@ -4,10 +4,14 @@ import { CloseIcon } from "./icons/close.tsx"; import { ChevronUpIcon } from "./icons/chevronUp.tsx"; import { ChevronDownIcon } from "./icons/chevronDown.tsx"; import { ArrowRight } from "./icons/arrowRight.tsx"; +import { CloseCircleIcon } from "./icons/closeCircle.tsx"; +import { CheckCircleIcon } from "./icons/checkCircle.tsx"; export { CloseIcon, ChevronUpIcon, ChevronDownIcon, ArrowRight, + CloseCircleIcon, + CheckCircleIcon, }; diff --git a/packages/_site/src/App.tsx b/packages/_site/src/App.tsx index 9a6b909..7b20291 100644 --- a/packages/_site/src/App.tsx +++ b/packages/_site/src/App.tsx @@ -24,6 +24,7 @@ import AvatarPage from "./pages/components/avatar"; import AccordianPage from "./pages/components/accordian"; import Introduction from "./pages/components/introduction"; import Tokens from "./pages/components/tokens"; +import Language from "./pages/components/language" import AlertPage from "./pages/components/alert"; import AspectRatioPage from "./pages/components/aspect-ratio"; import AlertDialogPage from "./pages/components/alert-dialog"; @@ -439,6 +440,18 @@ export default function App() { path="playground" element={} /> + + + +
+ +
+ + } + /> , ), ); diff --git a/packages/_site/src/pages/components/language.tsx b/packages/_site/src/pages/components/language.tsx new file mode 100644 index 0000000..3b43582 --- /dev/null +++ b/packages/_site/src/pages/components/language.tsx @@ -0,0 +1,1003 @@ +import * as stylex from "@stylexjs/stylex"; +// import InstallationBlock from "../commons/installation-block"; +import { H1, H2, H3, H4, H5 } from "@controlkit/headings"; + +import { CheckCircleIcon, CloseCircleIcon } from "@controlkit/icons"; +import ContentsSidebar from "./commons/contents_sidebar"; +import { useRef } from "react"; +import { styles } from "./_layout/styles"; + +const languagePageStyles = stylex.create({ + wrapper: { + margin: "2rem", + placeItems: "center", + display: "grid", + rowGap: "2rem", + }, + section: { + display: "grid", + rowGap: "1rem", + }, + + tiles: { + gap: "2rem", + display: "grid", + gridTemplateColumns: "1fr 1fr", + paddingBottom: "2rem", + }, + + card: { + padding: "1rem", + borderStyle: "solid", + borderBottomWidth: "0rem", + borderLeftWidth: "0rem", + borderRightWidth: "0rem", + borderTopWidth: "0.25rem", + }, + success: { + borderColor: "#82b536", + backgroundColor: "#28311b", + }, + error: { + borderColor: "#f15b50", + backgroundColor: "#42221f", + }, + cardTitle: { + gap: "1rem", + alignItems: "center", + display: "inline-flex", + fontSize: "1.5rem !important", + lineHeight: "2rem !important", + }, + + bulletList: { + marginTop: "0rem", + }, +}); + +function CustomCard({ + text, + error = false, +}: {text: string, error?: boolean}) { + return ( +
+ + {error ? : } + {error ? "Don't" : "Do"} + + +
+
+ ) +} + +export default function Tokens() { + const divRef = useRef(null); + return ( +
+
+ +
+
+

Style, grammar, and punctuation

+ Follow these writing conventions to make your apps and experiences clear, consistent, and localizable. +
+ +
+

Style and formatting

+ +

Abbreviations

+
    +
  • Use the full name of features and apps in customer-facing copy.
    • +
  • Don't use 'e.g.', 'i.e.', 'etc.', or '&' as they're not localization friendly and can be confusing for users of assistive technologies.
    • +
+
+ + +
+
+ + +
+ +

Plural abbreviations

+ Don't use an apostrophe for plural abbreviations. +
+ + +
+ +

Articles (a, an, the)

+ Avoid articles in buttons, labels, and action-based headings in the UI. +
+ + +
+ +

Bold

+ Use bold text to draw the reader's eye to key phrases and statements in your content, though don't over do it. +
    +
  • For in-app copy or help articles, use bold when referring to static UI elements like menu items, buttons, or headings.
    • +
  • If bold is needed but the UI doesn't support it — for example in a UI message or a flag where the title is already bold — you can use italics.
    • +
+
+ + +
+ +

Capitalization

+
    +
  • Use sentence case in all titles, headings, menu items, labels, and buttons.
    • +
  • Capitalize proper nouns in headings, such as names of people, companies, or apps.
    • +
+
+ + +
+
+ + +
+ +

Contractions (shortened words)

+
    +
  • Use contractions, where possible, as they convey a conversational, friendly tone.
    • +
  • + Use curly apostrophes in UI copy +
      +
    • On a Mac: option + shift + ]
      • +
    • On Windows: Control + ' (or alt + 0146)
      • +
    +
    • +
+
+ + +
+ +

Gender (he, she, they)

+
    +
  • If known, use the pronouns a customer provides. If you don't know, avoid gendered pronouns wherever possible.
    • +
  • + If it's not possible, use 'they' or 'their' rather than 'his/her' or 'he/she'. +
    • +
+
+ + +
+
+ + +
+ +

Headings and titles

+
    +
  • + Use sentence case. Only capitalize the first word of a sentence, proper nouns, and trademarked names (for example: apps, countries, people's names). +
    • +
  • + Don't use bold or italics. +
    • +
  • + Don't use periods. +
    • +
  • + Reconsider using question marks. Preferably rephrase the heading so it's a statement. +
    • +
  • + Phrase UI and documentation headings with an action verb. +
    • +
  • + Avoid gerunds (the 'ing' form of verbs) in UI copy. +
    • +
+
+ + +
+
+ + +
+ +

Articles in headings

+
    +
  • Articles (a, an, the) aren't always needed in UI headings.
    • +
  • + They're better suited to more conversational sections, like product marketing copy and empty states, as they make these sections more approachable and improve understanding. +
    • +
+
+ + +
+ +

Italics

+ In apps, use italics sparingly as it can be difficult to read. Don't use italics in hyperlinks. + Italics can be used for: +
    +
  • UI elements that might change, like a field name or user input.
    • +
  • + For emphasis if the UI doesn't support bold. For example, in a flag or UI message. +
    • +
+ +

Lists

+ Use lists to draw the reader's eye and make items easier to scan and follow. Try to limit lists to 6 items or less. If there are more items, make multiple lists. + Italics can be used for: +
    +
  • UI elements that might change, like a field name or user input.
    • +
  • + For emphasis if the UI doesn't support bold. For example, in a flag or UI message. +
    • +
+ +

Bulleted list

+
    +
  • Use to list options or when the order of the items doesn't matter.
    • +
  • + Phrase each item in a parallel way. +
    • +
  • + Don't use commas or periods at the end of each item. +
    • +
+ +
Fragmented Sentences
+ If your list has fragmented sentences, use a lowercase letter for each item and don't use a period at the end of the list. Use a lead-in sentence with a colon before the items. +
+ + +
+ +
Complete Sentences
+ For lists with complete sentences, start an item with a capital letter and end it with a period. Don't use a lead-in sentence with a colon. +
+ + +
+ +

Numbered lists

+ Use numbered lists for tasks or lists where the order of the items matters. Capitalize the first word of each item and end the item with a period. +
+ + +
+ +

Monospaced text

+ Use monospaced font for names of a file or directory. It's mostly used in attributes, strings, and administrator and developer docs. +
+ + +
+ +

Numbers

+ Use digits rather than words in most cases. + Exceptions: +
    +
  • If a number starts a sentence, write it out.
    • +
  • + In common expressions, write the number out. For example: It's one thing after another. +
    • +
  • + When writing long-form or formal content, write out numbers one to nine. +
    • +
  • + Write out the numbers 'zero' and 'one' if it could be confused for the letters L, I, or O. +
    • +
+
+ + +
+
+ + +
+ +

Numbers 'out of'

+ Use digits rather than words in most cases. +
+ + +
+ + +

Spelling words

+ Use US English in UI copy and code. Check spellings in Merriam-Webster online dictionary. +
+ + +
+ +

Truncation

+ Ellipses (…) are used to show that text has been cut off — or truncated — when a message doesn't fit in a given space. +
    +
  • Avoid truncation whenever possible: shorten UI messages or wrap the text.
    • +
  • + Test your designs using multiple screen widths and magnification levels to ensure it doesn't truncate. +
    • +
  • + If truncation can't be avoided, for example in user-generated content or icon buttons, use a tooltip to display the full text for accessibility and usability. +
    • +
  • + In ADS components that truncate, the ellipsis appears without any space next to the last visible character (for example: Work in pro…). +
    • +
+
+ + +
+ +

UI elements

+
    +
  • Use sentence case, even if the UI element doesn't use it.
    • +
  • + Use bold to emphasize the UI element in a step. +
    • +
  • + If the UI element has an icon, bold both the name and the icon. +
    • +
  • + Avoid using a > symbol where possible, as it is read out as “greater than” by assistive technologies, leading to confusion. Use 'then' instead. +
    • +
+
+ + +
+ +

Grammar

+ +

Active voice

+ Use active voice whenever possible as it improves readability and reflects Control Design's voice and tone. + Active voice: +
    +
  • puts the emphasis on the person or thing doing an action.
    • +
  • makes content shorter, clearer, friendlier, and more conversational.
    • +
+
+ + +
+ +

Pronouns (you, your, we)

+
    +
  • Minimize the use of pronouns.
    • +
  • Most of the time they can be avoided. However, when advising a user, indicating that something in the UI is theirs, or in error messages, you can use 'you' or 'your' or 'we' for a friendlier tone.
    • +
+
+ + +
+
+ + +
+
+ + +
+ +

Tense

+ Present tense helps make instructions and messages in the UI clear and engaging. +
+ + +
+
+ + +
+ Past tense can be used to communicate a completed action, like in error message headings and success flags, or where there could be confusion. +
+ + +
+ +

Punctuation

+ +

Apostrophes (')

+
    +
  • Use an apostrophe to show possession. The apostrophe is placed before the 's' for singular terms and after the 's' for plurals.
    • +
  • If a word ends in an 's' and is singular, add an 's after the 's'.
    • +
  • Use a curly apostrophe for better readability and to differentiate from code. +
      +
    • On a Mac: option + shift + ]
      • +
    • On a Windows: Control + shift + ' (or alt + 0146)
      • +
    +
    • +
+
+ + +
+ +

Colons (:)

+
    +
  • Use colons to introduce a bulleted list or series of steps.
    • +
  • Don't use colons at the end of headings.
    • +
+
+ + +
+ +

Commas (,)

+ Use an Oxford (or 'serial') comma to offset the final item in a list. +
+ + +
+ +

Dashes (—) and hashes (‐)

+

Dashes

+
    +
  • Use dashes in UI content sparingly. If using, use a spaced em dash.
    • +
  • In long-form content, use them sparingly to show an abrupt change in a sentence — like this. If the break happens in the middle of a sentence — like this — use spaced em dashes on either side of the phrase.
    • +
  • If possible, rewrite the sentence or make 2 sentences to avoid a dash. Clear, concise sentences are better for readability and accessibility.
    • +
  • Don't use a dash or hyphen for ranges of numbers. Use 'to' instead.
    • +
  • When adding the space, use non-breaking spaces (option + shift + space) to avoid the dash shifting to a new line.
    • +
  • To make an em dash:
    • +
      +
    • On a Mac: option + shift + hyphen
      • +
    • On Windows: Control + Alt + - (or ALT + 0151)
      • +
    +
+
+ + +
+
+ + +
+ +

Hyphens

+
    +
  • If a noun is described by 2 or more words, use a hyphen to join those words together so they act as a compound adjective (or compound modifier).
    • +
  • Exceptions: don't add a hyphen after the word 'very' or adverbs ending in -ly.
    • +
  • For specific hyphenated word guidance, check Vocabulary (Center Controls only).
    • +
  • Use a hyphen when not doing so could cause confusion or ambiguity. Consult the Merriam-Webster online dictionary if you're not sure.
    • +
+
+ + +
+
+ + +
+ +

Ellipses (...)

+
    +
  • Don't put spaces in between the periods in an ellipsis.
    • +
  • Use the symbol for the ellipsis rather than a string of periods:
    • +
      +
    • On a Mac: Option + ;
      • +
    • On Windows: Control + . (or alt + 0133)
      • +
    +
+ +

Truncation

+ Ellipses can be used to show that text has been cut off — or truncated — when a message doesn't fit in a given space. + +

Quotes

+
    +
  • When using an ellipsis to omit part of a long quote, include spaces on either side of the ellipsis ( … ).
    • +
  • For example: “From medicine and space travel to disaster response … our products help teams all over the planet advance humanity through the power of software.” Center Control: Discover our story.
    • +
+ +

Exclamation marks (!)

+
    +
  • Avoid exclamation marks in UI copy and minimize their use in product marketing copy.
    • +
  • They can be considered for exciting or new things, but ask yourself if it's really that exciting or if one is needed. Don't use more than one exclamation mark per page.
    • +
+
+ + +
+ +

Periods (.)

+
    +
  • Use a period (full stop) at the end of complete sentences, including in helper text, messages, and notifications.
    • +
  • Don't use periods in headers, titles, tooltips, field descriptions, and menu names, even if they are full sentences. While long content is discouraged, an exception is if these elements contain more than 1 sentence.
    • +
  • Only use periods in a bulleted list if the item is a complete sentence. Don't add a period at the end of a list of fragments.
    • +
  • Add only one space after a period (full stop).
    • +
+
+ + +
+ If a link ends a sentence, include a period but don't hyperlink it. +
+ + +
+ +

Quotation marks ('' | "")

+ In the UI, use: +
    +
  • single curly quotes, unless you're writing in code or there's a semantic reason to use straight quotes.
    • +
+ In body copy and long-form content, such as documentation and marketing, use: +
    +
  • double quotes ("") for speech and direct quotes. Don't use italics.
    • +
  • single quotes ('') to draw attention to a word you're defining.
    • +
+
+ + +
+
+ + +
+

Emphasis

+ Don’t use quotation marks to emphasize UI elements, page titles, and other objects. Instead use bold. +
+ + +
+ +
+
+
+
+ ); +} diff --git a/packages/_site/src/pages/components/routes_list_docs_components.ts b/packages/_site/src/pages/components/routes_list_docs_components.ts index ecbb011..c54d8a9 100644 --- a/packages/_site/src/pages/components/routes_list_docs_components.ts +++ b/packages/_site/src/pages/components/routes_list_docs_components.ts @@ -33,6 +33,10 @@ export const foundations = [ { title: "Tokens", route: "/tokens", + }, + { + title: "Style, grammar, and punctuation", + route: "/language", } ] From 0b95a57a16098dd4affa762b2a76c6413c9a961f Mon Sep 17 00:00:00 2001 From: AaronPatterson1 Date: Thu, 27 Aug 2026 14:38:07 -0400 Subject: [PATCH 2/5] Fixing use of dangerouslySetInnerHTML and using standard children prop instead. --- .../_site/src/pages/components/language.tsx | 565 ++++-------------- 1 file changed, 129 insertions(+), 436 deletions(-) diff --git a/packages/_site/src/pages/components/language.tsx b/packages/_site/src/pages/components/language.tsx index 3b43582..5df3b05 100644 --- a/packages/_site/src/pages/components/language.tsx +++ b/packages/_site/src/pages/components/language.tsx @@ -4,7 +4,7 @@ import { H1, H2, H3, H4, H5 } from "@controlkit/headings"; import { CheckCircleIcon, CloseCircleIcon } from "@controlkit/icons"; import ContentsSidebar from "./commons/contents_sidebar"; -import { useRef } from "react"; +import { useRef, type ComponentProps } from "react"; import { styles } from "./_layout/styles"; const languagePageStyles = stylex.create({ @@ -49,16 +49,17 @@ const languagePageStyles = stylex.create({ fontSize: "1.5rem !important", lineHeight: "2rem !important", }, - + bulletList: { marginTop: "0rem", }, }); function CustomCard({ - text, error = false, -}: {text: string, error?: boolean}) { + children, + ...props +}: ComponentProps<"div"> & {error?: boolean}) { return (
-
+
+ {children} +
) } @@ -83,7 +82,7 @@ function CustomCard({ export default function Tokens() { const divRef = useRef(null); return ( -
@@ -104,50 +103,26 @@ export default function Tokens() {
  • Don't use 'e.g.', 'i.e.', 'etc.', or '&' as they're not localization friendly and can be confusing for users of assistive technologies.
    • - - + Ask the experts at Control Design. + Ask the experts at CD.
    - - + Use an input component. For example, a button or a select. + Use an input component, e.g. a button or a select etc.

    Plural abbreviations

    Don't use an apostrophe for plural abbreviations.
    - - + 1990s, DVDs + 1990's, DVD's

    Articles (a, an, the)

    Avoid articles in buttons, labels, and action-based headings in the UI.
    - - + Create password + Create a password

    Bold

    @@ -157,14 +132,8 @@ export default function Tokens() {
  • If bold is needed but the UI doesn't support it — for example in a UI message or a flag where the title is already bold — you can use italics.
    • - - + Go to General configuration then User macros. + Go to the settings page and select Configuration.

    Capitalization

    @@ -173,24 +142,12 @@ export default function Tokens() {
  • Capitalize proper nouns in headings, such as names of people, companies, or apps.
    • - - + Create work item + Create Work Item
    - - + Add permissions for Arni Karan + Add permissions for arni karan

    Contractions (shortened words)

    @@ -205,14 +162,8 @@ export default function Tokens() {
    - - + We can't load this page. + We cannot load this page.

    Gender (he, she, they)

    @@ -223,24 +174,12 @@ export default function Tokens() {
    - - + Ask your admin to add you. + Ask your admin if she can add you.
    - - + Add permissions to their account. + Add permissions to her account.

    Headings and titles

    @@ -265,24 +204,12 @@ export default function Tokens() {
    - - + Organize your to-do list with Trello + Want to Organize Your To-Do List With Trello?
    - - + Add a page to your project + Adding a page to your project

    Articles in headings

    @@ -293,14 +220,8 @@ export default function Tokens() {
    - - + Create work item + Create a work item

    Italics

    @@ -337,97 +258,73 @@ export default function Tokens() {
    Fragmented Sentences
    If your list has fragmented sentences, use a lowercase letter for each item and don't use a period at the end of the list. Use a lead-in sentence with a colon before the items.
    - - +
    Complete Sentences
    For lists with complete sentences, start an item with a capital letter and end it with a period. Don't use a lead-in sentence with a colon.
    - - +

    Numbered lists

    Use numbered lists for tasks or lists where the order of the items matters. Capitalize the first word of each item and end the item with a period.
    - - +

    Monospaced text

    Use monospaced font for names of a file or directory. It's mostly used in attributes, strings, and administrator and developer docs.
    - - + + The location of the Home directory is stored in a configuration file called confluence-init.properties. + + + The location of the Home directory is stored in a configuration file called confluence-init.properties. +

    Numbers

    @@ -446,83 +343,51 @@ export default function Tokens() {
    - - + Your password should be a minimum of 8 characters. + Your password should be a minimum of eight characters.
    - - + Loom is one of the best apps for sharing information in a personal way. + Loom is 1 of the best apps for sharing information in a personal way.

    Numbers 'out of'

    Use digits rather than words in most cases.
    - - +
    - +

    Spelling words

    Use US English in UI copy and code. Check spellings in Merriam-Webster online dictionary.
    - - +

    Truncation

    @@ -540,18 +405,8 @@ export default function Tokens() {
    - - + Shorten or wrap messages. + Don't truncate unless it can't be avoided.

    UI elements

    @@ -568,18 +423,8 @@ export default function Tokens() {
    - - + Go to More, then Link work item. + Go to More > Link Work Item.

    Grammar

    @@ -592,14 +437,8 @@ export default function Tokens() {
  • makes content shorter, clearer, friendlier, and more conversational.
    • - - + Administrators control access to Center Control Cloud applications. + Access to Center Control Cloud applications is controlled by administrators.

    Pronouns (you, your, we)

    @@ -608,78 +447,42 @@ export default function Tokens() {
  • Most of the time they can be avoided. However, when advising a user, indicating that something in the UI is theirs, or in error messages, you can use 'you' or 'your' or 'we' for a friendlier tone.
    • - - + Get access to your work items here. + Get access to the work items here.
    - - + Your projects + My projects
    - - + We couldn't load your page + The page couldn't be loaded

    Tense

    Present tense helps make instructions and messages in the UI clear and engaging.
    - - -
    -
    - - + We can't load work item DSP-32113. + We couldn't load work item DSP-32113. +
    +
    + Validation is required. + Validation will be required.
    Past tense can be used to communicate a completed action, like in error message headings and success flags, or where there could be confusion.
    - - +

    Punctuation

    @@ -696,26 +499,20 @@ export default function Tokens() {
    - - +

    Colons (:)

    @@ -724,48 +521,32 @@ export default function Tokens() {
  • Don't use colons at the end of headings.
    • - - +

    Commas (,)

    Use an Oxford (or 'serial') comma to offset the final item in a list.
    - - + Jira, Confluence, Loom, and Bitbucket are all Center Control apps. + Jira, Confluence, Loom and Bitbucket are all Center Control apps.

    Dashes (—) and hashes (‐)

    Dashes

    • Use dashes in UI content sparingly. If using, use a spaced em dash.
      • -
    • In long-form content, use them sparingly to show an abrupt change in a sentence — like this. If the break happens in the middle of a sentence — like this — use spaced em dashes on either side of the phrase.
      • +
    • In long-form content, use them sparingly to show an abrupt change in a sentence — like this. If the break happens in the middle of a sentence — like this — use spaced em dashes on either side of the phrase.
    • If possible, rewrite the sentence or make 2 sentences to avoid a dash. Clear, concise sentences are better for readability and accessibility.
    • Don't use a dash or hyphen for ranges of numbers. Use 'to' instead.
    • When adding the space, use non-breaking spaces (option + shift + space) to avoid the dash shifting to a new line.
      • @@ -776,32 +557,12 @@ export default function Tokens() {
    - - -
    -
    - - + Jira Service Management belongs to Jira's family of apps. They're all built on the same platform and share the same site URL. + Jira Service Management belongs to Jira's family of apps — they're all built on the same platform and share the same site URL. +
    +
    + 50 to 100 + 50—100

    Hyphens

    @@ -812,8 +573,7 @@ export default function Tokens() {
  • Use a hyphen when not doing so could cause confusion or ambiguity. Consult the Merriam-Webster online dictionary if you're not sure.
    • - - +
    - - +

    Ellipses (...)

    @@ -887,18 +636,8 @@ export default function Tokens() {
  • They can be considered for exciting or new things, but ask yourself if it's really that exciting or if one is needed. Don't use more than one exclamation mark per page.
    • - - + Project is complete. + Project is complete!

    Periods (.)

    @@ -909,35 +648,19 @@ export default function Tokens() {
  • Add only one space after a period (full stop).
    • - - +
    If a link ends a sentence, include a period but don't hyperlink it.
    - - + Center Control's work is guided by many core values. + Center Control's work is guided by many core values.

    Quotation marks ('' | "")

    @@ -951,48 +674,18 @@ export default function Tokens() {
  • single quotes ('') to draw attention to a word you're defining.
    • - - -
    -
    - - + “We have big things planned for the coming year,” said Mike. + ‘We have big things planned for the coming year,’ said Mike. +
    +
    + They tried to avoid talking about the ‘big’ secret. + They tried to avoid talking about the “big” secret.

    Emphasis

    Don’t use quotation marks to emphasize UI elements, page titles, and other objects. Instead use bold.
    - - + Go to Settings + Go to ‘Settings’.
    From aee8b4550c389a5e48a11c3623fd1a6915505b06 Mon Sep 17 00:00:00 2001 From: AaronPatterson1 Date: Thu, 27 Aug 2026 14:38:07 -0400 Subject: [PATCH 3/5] Fixing use of company names and other small mistakes. --- .../_site/src/pages/components/language.tsx | 565 ++++-------------- 1 file changed, 129 insertions(+), 436 deletions(-) diff --git a/packages/_site/src/pages/components/language.tsx b/packages/_site/src/pages/components/language.tsx index 3b43582..5df3b05 100644 --- a/packages/_site/src/pages/components/language.tsx +++ b/packages/_site/src/pages/components/language.tsx @@ -4,7 +4,7 @@ import { H1, H2, H3, H4, H5 } from "@controlkit/headings"; import { CheckCircleIcon, CloseCircleIcon } from "@controlkit/icons"; import ContentsSidebar from "./commons/contents_sidebar"; -import { useRef } from "react"; +import { useRef, type ComponentProps } from "react"; import { styles } from "./_layout/styles"; const languagePageStyles = stylex.create({ @@ -49,16 +49,17 @@ const languagePageStyles = stylex.create({ fontSize: "1.5rem !important", lineHeight: "2rem !important", }, - + bulletList: { marginTop: "0rem", }, }); function CustomCard({ - text, error = false, -}: {text: string, error?: boolean}) { + children, + ...props +}: ComponentProps<"div"> & {error?: boolean}) { return (
    -
    +
    + {children} +
    ) } @@ -83,7 +82,7 @@ function CustomCard({ export default function Tokens() { const divRef = useRef(null); return ( -
    @@ -104,50 +103,26 @@ export default function Tokens() {
  • Don't use 'e.g.', 'i.e.', 'etc.', or '&' as they're not localization friendly and can be confusing for users of assistive technologies.
    • - - + Ask the experts at Control Design. + Ask the experts at CD.
    - - + Use an input component. For example, a button or a select. + Use an input component, e.g. a button or a select etc.

    Plural abbreviations

    Don't use an apostrophe for plural abbreviations.
    - - + 1990s, DVDs + 1990's, DVD's

    Articles (a, an, the)

    Avoid articles in buttons, labels, and action-based headings in the UI.
    - - + Create password + Create a password

    Bold

    @@ -157,14 +132,8 @@ export default function Tokens() {
  • If bold is needed but the UI doesn't support it — for example in a UI message or a flag where the title is already bold — you can use italics.
    • - - + Go to General configuration then User macros. + Go to the settings page and select Configuration.

    Capitalization

    @@ -173,24 +142,12 @@ export default function Tokens() {
  • Capitalize proper nouns in headings, such as names of people, companies, or apps.
    • - - + Create work item + Create Work Item
    - - + Add permissions for Arni Karan + Add permissions for arni karan

    Contractions (shortened words)

    @@ -205,14 +162,8 @@ export default function Tokens() {
    - - + We can't load this page. + We cannot load this page.

    Gender (he, she, they)

    @@ -223,24 +174,12 @@ export default function Tokens() {
    - - + Ask your admin to add you. + Ask your admin if she can add you.
    - - + Add permissions to their account. + Add permissions to her account.

    Headings and titles

    @@ -265,24 +204,12 @@ export default function Tokens() {
    - - + Organize your to-do list with Trello + Want to Organize Your To-Do List With Trello?
    - - + Add a page to your project + Adding a page to your project

    Articles in headings

    @@ -293,14 +220,8 @@ export default function Tokens() {
    - - + Create work item + Create a work item

    Italics

    @@ -337,97 +258,73 @@ export default function Tokens() {
    Fragmented Sentences
    If your list has fragmented sentences, use a lowercase letter for each item and don't use a period at the end of the list. Use a lead-in sentence with a colon before the items.
    - - +
    Complete Sentences
    For lists with complete sentences, start an item with a capital letter and end it with a period. Don't use a lead-in sentence with a colon.
    - - +

    Numbered lists

    Use numbered lists for tasks or lists where the order of the items matters. Capitalize the first word of each item and end the item with a period.
    - - +

    Monospaced text

    Use monospaced font for names of a file or directory. It's mostly used in attributes, strings, and administrator and developer docs.
    - - + + The location of the Home directory is stored in a configuration file called confluence-init.properties. + + + The location of the Home directory is stored in a configuration file called confluence-init.properties. +

    Numbers

    @@ -446,83 +343,51 @@ export default function Tokens() {
    - - + Your password should be a minimum of 8 characters. + Your password should be a minimum of eight characters.
    - - + Loom is one of the best apps for sharing information in a personal way. + Loom is 1 of the best apps for sharing information in a personal way.

    Numbers 'out of'

    Use digits rather than words in most cases.
    - - +
    - +

    Spelling words

    Use US English in UI copy and code. Check spellings in Merriam-Webster online dictionary.
    - - +

    Truncation

    @@ -540,18 +405,8 @@ export default function Tokens() {
    - - + Shorten or wrap messages. + Don't truncate unless it can't be avoided.

    UI elements

    @@ -568,18 +423,8 @@ export default function Tokens() {
    - - + Go to More, then Link work item. + Go to More > Link Work Item.

    Grammar

    @@ -592,14 +437,8 @@ export default function Tokens() {
  • makes content shorter, clearer, friendlier, and more conversational.
    • - - + Administrators control access to Center Control Cloud applications. + Access to Center Control Cloud applications is controlled by administrators.

    Pronouns (you, your, we)

    @@ -608,78 +447,42 @@ export default function Tokens() {
  • Most of the time they can be avoided. However, when advising a user, indicating that something in the UI is theirs, or in error messages, you can use 'you' or 'your' or 'we' for a friendlier tone.
    • - - + Get access to your work items here. + Get access to the work items here.
    - - + Your projects + My projects
    - - + We couldn't load your page + The page couldn't be loaded

    Tense

    Present tense helps make instructions and messages in the UI clear and engaging.
    - - -
    -
    - - + We can't load work item DSP-32113. + We couldn't load work item DSP-32113. +
    +
    + Validation is required. + Validation will be required.
    Past tense can be used to communicate a completed action, like in error message headings and success flags, or where there could be confusion.
    - - +

    Punctuation

    @@ -696,26 +499,20 @@ export default function Tokens() {
    - - +

    Colons (:)

    @@ -724,48 +521,32 @@ export default function Tokens() {
  • Don't use colons at the end of headings.
    • - - +

    Commas (,)

    Use an Oxford (or 'serial') comma to offset the final item in a list.
    - - + Jira, Confluence, Loom, and Bitbucket are all Center Control apps. + Jira, Confluence, Loom and Bitbucket are all Center Control apps.

    Dashes (—) and hashes (‐)

    Dashes

    • Use dashes in UI content sparingly. If using, use a spaced em dash.
      • -
    • In long-form content, use them sparingly to show an abrupt change in a sentence — like this. If the break happens in the middle of a sentence — like this — use spaced em dashes on either side of the phrase.
      • +
    • In long-form content, use them sparingly to show an abrupt change in a sentence — like this. If the break happens in the middle of a sentence — like this — use spaced em dashes on either side of the phrase.
    • If possible, rewrite the sentence or make 2 sentences to avoid a dash. Clear, concise sentences are better for readability and accessibility.
    • Don't use a dash or hyphen for ranges of numbers. Use 'to' instead.
    • When adding the space, use non-breaking spaces (option + shift + space) to avoid the dash shifting to a new line.
      • @@ -776,32 +557,12 @@ export default function Tokens() {
    - - -
    -
    - - + Jira Service Management belongs to Jira's family of apps. They're all built on the same platform and share the same site URL. + Jira Service Management belongs to Jira's family of apps — they're all built on the same platform and share the same site URL. +
    +
    + 50 to 100 + 50—100

    Hyphens

    @@ -812,8 +573,7 @@ export default function Tokens() {
  • Use a hyphen when not doing so could cause confusion or ambiguity. Consult the Merriam-Webster online dictionary if you're not sure.
    • - - +
    - - +

    Ellipses (...)

    @@ -887,18 +636,8 @@ export default function Tokens() {
  • They can be considered for exciting or new things, but ask yourself if it's really that exciting or if one is needed. Don't use more than one exclamation mark per page.
    • - - + Project is complete. + Project is complete!

    Periods (.)

    @@ -909,35 +648,19 @@ export default function Tokens() {
  • Add only one space after a period (full stop).
    • - - +
    If a link ends a sentence, include a period but don't hyperlink it.
    - - + Center Control's work is guided by many core values. + Center Control's work is guided by many core values.

    Quotation marks ('' | "")

    @@ -951,48 +674,18 @@ export default function Tokens() {
  • single quotes ('') to draw attention to a word you're defining.
    • - - -
    -
    - - + “We have big things planned for the coming year,” said Mike. + ‘We have big things planned for the coming year,’ said Mike. +
    +
    + They tried to avoid talking about the ‘big’ secret. + They tried to avoid talking about the “big” secret.

    Emphasis

    Don’t use quotation marks to emphasize UI elements, page titles, and other objects. Instead use bold.
    - - + Go to Settings + Go to ‘Settings’.
    From 253fe004693a4129228bd905a8ea4e4e2bd25286 Mon Sep 17 00:00:00 2001 From: AaronPatterson1 Date: Fri, 28 Aug 2026 11:58:53 -0400 Subject: [PATCH 4/5] Fixing use of company names and other small mistakes. --- .../_site/src/pages/components/language.tsx | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/packages/_site/src/pages/components/language.tsx b/packages/_site/src/pages/components/language.tsx index 5df3b05..f0cde9c 100644 --- a/packages/_site/src/pages/components/language.tsx +++ b/packages/_site/src/pages/components/language.tsx @@ -57,8 +57,7 @@ const languagePageStyles = stylex.create({ function CustomCard({ error = false, - children, - ...props + children }: ComponentProps<"div"> & {error?: boolean}) { return (
    -
    +
    {children}
    @@ -280,14 +279,14 @@ export default function Tokens() { For lists with complete sentences, start an item with a capital letter and end it with a period. Don't use a lead-in sentence with a colon.
    - Center Control has updated security requirements for employees. + Our company has updated security requirements for employees.
    • Always wear your identification tag when working in an office.
    • Use your identification tag to enter an office before 7 am and when you leave after 6 pm.
     - Center Control has updated security requirements for employees: + Our company has updated security requirements for employees:
    • always wear your identification tag when working in an office
    • use your identification tag to enter an office before 7 am and when you leave after 6 pm.
      • @@ -320,10 +319,10 @@ export default function Tokens() { Use monospaced font for names of a file or directory. It's mostly used in attributes, strings, and administrator and developer docs.
      - The location of the Home directory is stored in a configuration file called confluence-init.properties. + To run the program, type python app.py in your terminal. - The location of the Home directory is stored in a configuration file called confluence-init.properties. + To run the program, type python app.py in your terminal.
      @@ -437,8 +436,8 @@ export default function Tokens() {
    • makes content shorter, clearer, friendlier, and more conversational.
    - Administrators control access to Center Control Cloud applications. - Access to Center Control Cloud applications is controlled by administrators. + The team completed the report in three days. + The report was completed by the team in three days.

    Pronouns (you, your, we)

    @@ -538,8 +537,8 @@ export default function Tokens() {

    Commas (,)

    Use an Oxford (or 'serial') comma to offset the final item in a list.
    - Jira, Confluence, Loom, and Bitbucket are all Center Control apps. - Jira, Confluence, Loom and Bitbucket are all Center Control apps. + Cedar, Oak, Willow, and Maple are all types of trees. + Cedar, Oak, Willow and Maple are all types of trees.

    Dashes (—) and hashes (‐)

    @@ -557,8 +556,8 @@ export default function Tokens() {
    - Jira Service Management belongs to Jira's family of apps. They're all built on the same platform and share the same site URL. - Jira Service Management belongs to Jira's family of apps — they're all built on the same platform and share the same site URL. + It's important to use hyphens correctly. They should never be overused or used to replace periods. + It's important to use hyphens correctly — they should never be overused or used to replace periods.
    50 to 100 @@ -659,8 +658,8 @@ export default function Tokens() {
    If a link ends a sentence, include a period but don't hyperlink it.
    - Center Control's work is guided by many core values. - Center Control's work is guided by many core values. + To find something on the internet, all you need is a search engine. + To find something on the internet, all you need is a search engine.

    Quotation marks ('' | "")

    From b272058b056d58b8e9e8508e8c3a91e3632588d5 Mon Sep 17 00:00:00 2001 From: AaronPatterson1 Date: Fri, 28 Aug 2026 12:55:23 -0400 Subject: [PATCH 5/5] Fixing merge issues caused by VSCode. --- .../_site/src/pages/components/language.tsx | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/packages/_site/src/pages/components/language.tsx b/packages/_site/src/pages/components/language.tsx index 06587be..928d08f 100644 --- a/packages/_site/src/pages/components/language.tsx +++ b/packages/_site/src/pages/components/language.tsx @@ -203,8 +203,8 @@ export default function Tokens() {
    - Organize your to-do list with Trello - Want to Organize Your To-Do List With Trello? + Click here for more information + Want more information by clicking here?
    Add a page to your project @@ -279,14 +279,14 @@ export default function Tokens() { For lists with complete sentences, start an item with a capital letter and end it with a period. Don't use a lead-in sentence with a colon.
    - Center Control has updated security requirements for employees. + Our company has updated security requirements for employees.
    • Always wear your identification tag when working in an office.
    • Use your identification tag to enter an office before 7 am and when you leave after 6 pm.
     - Center Control has updated security requirements for employees: + Our company has updated security requirements for employees:
    • always wear your identification tag when working in an office
    • use your identification tag to enter an office before 7 am and when you leave after 6 pm.
      • @@ -319,10 +319,10 @@ export default function Tokens() { Use monospaced font for names of a file or directory. It's mostly used in attributes, strings, and administrator and developer docs.
      - The location of the Home directory is stored in a configuration file called confluence-init.properties. + To run the program, type python app.py in your terminal. - The location of the Home directory is stored in a configuration file called confluence-init.properties. + To run the program, type python app.py in your terminal.
      @@ -436,8 +436,8 @@ export default function Tokens() {
    • makes content shorter, clearer, friendlier, and more conversational.
    - Administrators control access to Center Control Cloud applications. - Access to Center Control Cloud applications is controlled by administrators. + The team completed the report in three days. + The report was completed by the team in three days.

    Pronouns (you, your, we)

    @@ -537,8 +537,8 @@ export default function Tokens() {

    Commas (,)

    Use an Oxford (or 'serial') comma to offset the final item in a list.
    - Jira, Confluence, Loom, and Bitbucket are all Center Control apps. - Jira, Confluence, Loom and Bitbucket are all Center Control apps. + Cedar, Oak, Willow, and Maple are all types of trees. + Cedar, Oak, Willow and Maple are all types of trees.

    Dashes (—) and hashes (‐)

    @@ -556,8 +556,8 @@ export default function Tokens() {
    - Jira Service Management belongs to Jira's family of apps. They're all built on the same platform and share the same site URL. - Jira Service Management belongs to Jira's family of apps — they're all built on the same platform and share the same site URL. + It's important to use hyphens correctly. They should never be overused or used to replace periods. + It's important to use hyphens correctly — they should never be overused or used to replace periods.
    50 to 100 @@ -658,8 +658,8 @@ export default function Tokens() {
    If a link ends a sentence, include a period but don't hyperlink it.
    - Center Control's work is guided by many core values. - Center Control's work is guided by many core values. + To find something on the internet, all you need is a search engine. + To find something on the internet, all you need is a search engine.

    Quotation marks ('' | "")