Application Style Guide

On this page...

The Look/Branding

  • Anything designed at or for the NYC Department of Education must include the NYC DOE logo and follow the DOE color palette.
    • You can find everything you need for color, fonts, NYC DOE Logos, headings, etc. in the DOE Vendor Guide.
  • We do not permit project or product-specific logos on the family-facing website.
  • Applications may use type treatments to distinguish their names if they are text-based, so they are screen-readable.

UI Elements

  • Make sure your site or application platform is accessible to people with disabilities
  • Have appropriate, nested heading levels (H2 follows H1)
  • Buttons vs links
    • Buttons are for actions
      • Name buttons descriptively
      • Never use “Submit. Use "Next", "Continue", "Send", or other simple verbs instead
    • Links are for browsing the site, learning more, etc.
  • Be consistent—it helps your clients learn how to use the application
    • Similar buttons should be in the same place throughout the application
      • "Send" should always be in the same place each time it has to be clicked to advance
  • Do not create brands, logos, or text treatments without consulting DIIT’s Digital Communications team and the Marketing and Digital Communications office at Tweed.

The Words

  • Keep text to a minimum
    • Be considerate of the user’s time by being concise
    • It's way more polite than saying "please" and "thank you" at every step
  • Never use colons after heading items
  • Address the user directly
  • Use plain language
  • Avoid exclamation marks and all caps
    • If emphasis is required, use bold (<strong>)—but sparingly
  • Consider translation
    • Avoid metaphors, idioms, acronyms
    • Consider putting Google translate on the application
  • Be consistent:
    • if one menu item is a verb, they all should be;
    • if one bullet has a period at the end, they all should.
  • Follow the Style Guide for general rules of capitalization, date format, etc.

Instructions

  • Instructional text is in sentence case.
  • It:
    • starts with a verb (active voice)
      • never starts with “Note” or “Please note”
    • is numbered when there are 2 or more steps
    • speaks directly to the user
      • avoids qualifications and conditional statements)
    • can use common contractions like "you’re," "isn’t," "can’t"
    • uses “for example” instead of “e.g.”
    • uses “in other words” instead of “i.e.”
    • doesn’t use technical terms when a commonplace alternative exists:
      • “Use” not “utilize”
      • “Box” or “blank,” not “field”
      • “Type” or “Write” not “enter” (unless the instruction means to click the Enter key)

Error Messages

  • Take responsibility for the error: “We couldn’t find that Student ID number,” not “that student ID number is invalid.”
  • Never blame the user
  • Don’t use red text as the sole indication of an error condition—doing so is an accessibility issue
  • Tell the user what he or she can do to remedy the situation—if nothing, apologize
  • Avoid technical terms and jargon (“404 error”) or, if unavoidable, explain your terms
  • Refer to screen elements by the exact same names as appear on the screen. (Ex: Don’t say “log in” as our screens say “sign in”)
  • Always give the user a way forward