Style Guide

How we write at OmniColor — tone, structure, formatting and terminology conventions.

Tone

Direct, Not Pedantic

We say what we mean. No filler, no jargon walls, no condescension.

Bad: "It should be noted that, in certain circumstances, one might find it advantageous to consider..."
Good: "Use HSL when you want to adjust a color's lightness without changing its hue."

Helpful, Not Salesy

We explain, not sell. No hype language.

Bad: "Our revolutionary, game-changing color picker will transform your workflow!"
Good: "The color picker shows HEX, RGB, HSL, HSV and CMYK values for any color you select."

Specific, Not Vague

Use exact numbers, exact colors, exact specifications.

Bad: "Use a high contrast between text and background."
Good: "WCAG AA requires at least 4.5:1 contrast for body text and 3:1 for large text."

Headings

Headings use sentence case. Only the first word and proper nouns are capitalized.

Bad: "Understanding the Complete History of Color Theory"
Good: "Understanding the complete history of color theory"

Exception: technical terms that are always capitalized (WCAG, W3C, RGB, HSL, HSV, CMYK, HEX).

Capitalization

  • HEX: Always uppercase (both the format name and the value like #FF7F50)
  • RGB, HSL, HSV, CMYK: Always uppercase
  • WCAG, W3C, CSS, HTML: Always uppercase
  • JavaScript, TypeScript: CamelCase, one word
  • Internet: Lowercase (unless starting a sentence)
  • Web: Lowercase (unless starting a sentence)

Numbers

  • Spell out one through nine: "one color", "three palettes", "nine tools"
  • Use numerals for 10 and above: "10 colors", "150 tools", "1,000 pixels"
  • Use numerals in technical contexts: "4.5:1 contrast", "135deg angle", "16.7 million colors"
  • Include the percent sign rather than spelling out: "50%" not "fifty percent"
  • Use commas for thousands: "16,777,216" not "16777216"

Punctuation

Oxford comma

We use the Oxford comma consistently.

Bad: "red, green and blue"
Good: "red, green, and blue"

Em dashes

Use em dashes (—) with no spaces on either side.

Bad: "Color — the study of hue — is complex."
Good: "Color—the study of hue—is complex."

Quotes

Use straight quotes for code, curly quotes for prose. Use double quotes for quoted speech, single quotes for quotes within quotes.

Terminology

Preferred terms

  • Color (not "colour" — we use American English)
  • HEX (not "hex")
  • RGB (not "rgb")
  • WCAG (not "Wcag" or "wcag")
  • WCAG AA (not "AA" or "WCAG-AA")
  • email (not "e-mail")
  • website (not "web site" or "Web site")
  • signup (noun), sign up (verb)
  • login (noun), log in (verb)

Color-specific terminology

  • hue: Lowercase when referring to the concept; uppercase H when referring to the HSL/HSV value
  • saturation: Lowercase when referring to the concept; uppercase S when referring to the value
  • lightness: Lowercase when referring to the concept; uppercase L when referring to the value
  • value: Lowercase when referring to the concept; uppercase V when referring to the HSV value
  • contrast ratio: Two words when referring to the measure
  • color space: Two words, lowercase
  • color wheel: Two words, lowercase

Structure

Paragraphs

Keep paragraphs short — 2-4 sentences max. One idea per paragraph. Left-aligned, no center-aligned body text.

Sentences

Target 15-25 words. If a sentence has more than 30 words, split it. Short sentences are not "simplistic" — they are readable.

Lists

Use bullet lists for parallel items (3+ items). Use numbered lists for sequential steps (2+ items). Do not mix bullets and numbers in the same list.

Examples

Every concept gets a real example with actual values. No placeholder like #000000 unless it actually represents black.

Code Examples

Format

  • Use code blocks for multi-line code
  • Use inline code for single commands or values
  • Always specify the language (for syntax highlighting)
  • Include comments for non-obvious logic

CSS example

/* Gradient background */
.hero {
  background: linear-gradient(135deg, #155EEF, #7C3AED);
}

JavaScript example

// Convert HEX to RGB
function hexToRgb(hex) {
  const h = hex.replace('#', '');
  return {
    r: parseInt(h.substring(0, 2), 16),
    g: parseInt(h.substring(2, 4), 16),
    b: parseInt(h.substring(4, 6), 16)
  };
}

Links

Descriptive link text

Link text should describe where the link goes. Never use "click here" or "read more" without context.

Bad: "To learn more about WCAG, click here."
Good: "For the full specification, see the WCAG 2.2 specification."

Internal vs external

Internal links go to relative URLs (/tools/...). External links open in the same tab by default, unless there is a specific reason to open a new tab.

Images and Alt Text

Every image must have descriptive alt text (unless decorative, in which case use empty alt). Alt text describes what the image shows, not the filename.

Bad: alt="screenshot-2024-01-15.png"
Good: alt="The OmniColor contrast checker showing a 14.3:1 ratio between dark navy and white"

Accuracy Over Style

When in doubt between stylistic consistency and factual accuracy, accuracy wins. We would rather break style rules than publish incorrect information.

Feedback on This Style Guide

If you have suggestions for improving our style guide, or notice instances where published content does not follow it, contact editorial@omnicolor.pages.dev.