Silver Style Guide

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