Webification Style Guide

Back to the Webification hub

• Style Guide
• Recommendations

Style guide

1. Use lower-kebab-case for all folders and filenames (NO SPACES IN FILE NAMES!)
2. Use lower-kebab-case for HTML/CSS classes, ids, etc.
3. Use camelCase for JavaScript variables, functions, etc.
4. Use Windows line endings in your files (CR LF).
5. Try not to add any other frameworks if at all possible. If you have one you'd really like to use, talk to Kenny.
6. When applicable, use print-only or screen-only instructions to describe puzzle interactions that are only available online or to provide information on the printed page that's hidden but accessible online, such as with interactive elements that are meaningless on a printed page. There are already a few classes in the css files in the resources folder you can use to help with this. For example, .print-only and .online-only do exactly what they say.
7. For printing, make sure nothing is split across pages in a weird way, margins and other sizes make sense, and try to remove background colors or graphics to save on ink. If you need multiple pages, make sure both pages include page numbers. Also don't print anything that doesn't make sense to print, like videos or music. For puzzles that include these, it's often just best to omit all printed puzzle content and just print a note saying that this puzzle must be played online.
8. Accessibility best-practices should be followed when possible. Many of these suggestions will be given to you via the browser's F12 dev tools. Common ones include:

• Don't mess with the order that items on the page are visited using the tab key unless you explicitly need to prevent certain things from being read or are going to handle it with other keys besides tab
• Inputs, images, and other interactive elements should always have labels that describe what they're used for. If they don't explicitly have text on the page or as part of themselves like with alt or tooltip attributes, then aria labels should be used.
• The order of the code should mirror the order that the items on the page are visited. If that doesn't end up being true, consider structuring your code differently by using different containers or display types.
• Videos should have captions whenever possible.
• Use containers to place elements based on relative positions on the page instead of manually placing things based on sizes, large invisible blank space characters, etc. Containers will make sure elements still get placed correctly when page size is changed via zooming, the magnifier tool, text scaling, etc.

10. Make sure user interactability is clued in the normal way for websites. For example,

• Links should be colored and underlined
• Something clickable should change the mouse cursor to the pointer finger
• Text you don't intend to be copyable should have the ability to select it intentionally disabled via the user-select CSS property
• Blanks for inputs should have autocomplete disabled
• Puzzles with significant state that won't be saved if the page is closed should set a beforeunload handler so the page warns the user before it closes

11. If your puzzle has state that changes based on user interaction (for example, typing to fill in a text box), THIS STATE MUST BE SAVED AS SOON IT CHANGES, AND THE PUZZLE MUST RESTORE THIS STATE WHEN IT LOADS. The goal here is so that absolutely no user state is lost if the page refreshes or closes because everything that was there before it closed will be put back when it re-opens. Puzzles that use the PuzzleJS framework get this functionality for free, and we don't want puzzles not built with it to differ in this regard. The easiest way to implement this is with localStorage.

Recommendations

1. Use Visual Studio Code instead of notepad since its Intellisense will help you
2. Test in multiple browsers (Chrome, Edge, etc.), including printing, and make sure you test after uploading to the alpha site too, since links may work differently online than they do on local files
3. Especially make sure you test print preview/printing to a PDF even if you have no physical printer available
4. DEFINITELY avoid minifying or obfuscating anything since we want as much of this to be readable and re-usable in the future as possible
5. Use Prettier for formatting