Writing style

Voice and tone

Our voice is clear but not cold, conversational but not jargon-y, helpful but not overly-prescriptive.

Write like you speak. Use contractions (it's, you'll, we're). Read your text aloud to ensure it sounds natural and friendly.

Keep it clear. Aim for a seventh-grade reading level. Write straightforward text without trying to be creative with words.

Be consistent. Use the same terms throughout. Always say “design tokens” not “design variables” or “theme values.”

Content structure

Use bigger ideas, fewer words

Shorter is always better. Give customers just enough information to make decisions confidently. Prune every excess word.

Get to the point fast

Lead with what's most important. Front-load keywords for scanning. Make customer choices and next steps obvious.

Make content scannable

Use headings, lists, and clear formatting. Readers should understand content at a glance. Keep paragraphs short.

Grammar and mechanics

Follow these fundamental rules:

• Sentence case for everything. Default to sentence-style capitalization. Only capitalize the first word and proper nouns. Never Use Title Capitalization.
• Skip end punctuation on headings. No periods, colons, or exclamation marks on headings, labels, or buttons.
• Use the Oxford comma. Include a comma before the conjunction in lists of three or more items.
• One space after periods. Use only one space after periods, question marks, and colons.
• Start with verbs. Begin statements with imperative verbs when possible. Avoid “you can” and “there is/are/were.”

Accessibility in content

Write with accessibility in mind:

• Clear, informative link text. Link text should be unique and describe where it leads. Never say “here” or “click here.” Say “View the component documentation” not “Click here.”
• Descriptive alt text. Provide alt text for images that describes their content and purpose.
• Proper heading hierarchy. Use heading levels sequentially (h1, h2, h3) without skipping levels.
• ARIA labels when needed. Include ARIA labels for screen readers when visual context isn't sufficient.
• Avoid directional language. Don't use “above,” “below,” “left,” or “right” that assumes visual orientation.

Localization considerations

Write content that translates well:

• Avoid slang and idioms. Don't use culturally-specific references or expressions that don't translate literally.
• Use gender-neutral language. Avoid gendered pronouns and terms. Use “they/them” or rephrase to avoid pronouns entirely.
• Keep sentences simple. Complex sentence structures with multiple clauses are harder to translate accurately.
• Be careful with humor. Humor rarely translates well and isn't appropriate in error messages or technical content.

Component documentation

When documenting components, include:

• Clear purpose. What is this component for? Start with one sentence.
• Usage guidelines. When should you use it? What are the alternatives?
• Code examples. Working examples showing typical use cases with all necessary imports.
• Props/API reference. Complete list of available options with types and defaults.
• Accessibility notes. How to ensure the component meets WCAG standards.

Code examples

Code examples should be:

• Complete and runnable. Include all necessary imports and context.
• Realistic. Show actual use cases, not contrived examples.
• Well-commented. Explain non-obvious parts, but don't over-comment.
• Consistently formatted. Follow the project's linting and formatting rules.

Example of a good code sample:

// Complete with imports and context
import { BrandButton } from '@facioquo/react-ui';

function MyComponent() {
  const handleClick = () => {
    console.log('Button clicked');
  };

  return (
    <BrandButton variant="primary" onClick={handleClick}>
      Save changes
    </BrandButton>
  );
}

Error messages and feedback

When writing error messages:

• Be friendly and helpful. Avoid jargon. Don't blame the user.
• Be specific. Say “Enter a credit card number” not “Field required.”
• Don't apologize too much. In most cases, apologizing won't fix the problem.
• Don't try to be funny. Humor isn't appropriate in error states or when things fail.

Feedback messages should use the same terms as the UI elements that triggered them.

Additional resources