Silver Style Guide

From Silver

Being worked on in gdoc

Editors should follow the following style guides, in order of preference:

  1. W3C Manual of Style
  2. Chicago Manual of Style
  3. WAI Style Guide
  • HTML structure
    • Sections
      • Use section elements with headings for every sub-section
      • Do not use sub-sections unless there is more than one
    • Inline
      • Use q instead of " for quotes, to allow generation of curly quotes
  • Lists
    • Lists that continue a sentence: each list item is lowercase, a single clause, terminated by a semi-colon except:
      • second-to-last terminated by semi-colon and "and";
      • the last one that is terminated by a period.
    • Other lists: each list item is a single sentence in sentence case, terminated by a period.
    • List items do not include paragraphs or other block-level elements inside.
    • List items of more than one sentence generally should become sections instead.
    • To Be Discussed When to use ordered lists and when to use bulleted lists.
  • Images
    • Coding
      • Use <figure> with <figcaption> for main images
      • Use <img> with alt for small inline images
      • Do not use size attributes, allow size to come from native size and / or CSS
    • Screen shots
      • Size images to display well at a width of 400 px
      • Image should be in 4:3 width to height ratio (800 x 600 recommended)
    • Relationship diagrams
      • Use SVG
      • Size containing box to drawing
  • Informative Content
    • Written in plain language
  • Normative Content
    • Include a plain-language summary
  • Plain Language Summaries
  • Guidelines
    • Name
      • short label
      • clause with no sentence punctuation
    • Guideline
      • full sentence
  • Outcomes
    • Name
      • short description of result
      • clause with no sentence punctuation
    • Outcome
      • is benefits to the user
      • full sentence
  • Definitions
    • The term in the glossary should be the singular form, even when commonly used in plural.
    • First paragraph of the definition should be a concise description suitable for incorporation into a tooltip.
    • Definitions should be full sentences or dictionary-like clauses, not “drop-in” substitutions as in WCAG 2.
  • Special terms ("outcomes", "success criteria")
    • lower case when referenced inline
    • Sentence case in the glossary
  • Headers
    • Sentence case
  • Term references
    • Link the first time in each top-level section
    • When terms and sections are the same, link to the term, which links to the section
  • WCAG Plural vs Singular
    • The W3C Content Accessibility Guidelines 3.0 are...
    • WCAG 3.0 is...
  • Avoid using "you" and contractions