Style Guide
version: 1.0date: 1999-02-05 16:08:59
Book of Style from 1999
I just unearthed this while looking for something else in my backups:
Matthew R. Yarbrough
2.5.99
Table of Contents
Basic Conventions
Web Safe Colors
Web Safe Fonts
Using ASP Fonts
Supported Browsers
Goals
Practice
Browser Features
How components affect page size
Error Checking and you
How to use Includes
Site Structure using ASP
Navigation
Goals
Practice
Naming Conventions
Definitions
Hidden Form Fields
Return To Top
Basic Conventions
These are the standards that a good website should meet. These standards are as follows:The pages must be viewable and functional in Netscape Navigator 2.0.
The site must be optimized for access by the disabled.
The pages must download reasonably quickly over a 28.8 connection.
The site must have consistency and ease of navigation.
The site must fit into a 800 X 600 screen.
The site must use colors and fonts which are web safe.
In order to meet these standards, the following guidelines are provided:
The site must be viewable and functional in Netscape Navigator 2.0.
For all intents and purposes, Navigator is a good base line to determine if a site "works". If the site is accessible, and it does not crash the browser, it is deemed to work. Naturally, the site will look better in newer browsers, but that should not preclude less advanced users from accessing the site. In order to comply with Nav 2.0 standards, all bells and whistles (JavaScript, Flash) should degrade gracefully. If you are using something that does not degrade, there has to be an overriding reason that you are willing to sacrifice accessibility. Other than specific client request, I can think of no reason to sacrifice accessibility. Actual HTML code (as opposed to ASP) should fit within the confines of the w3c HTML 3.2 spec (http://www.w3.org/TR/REC-html32.html).
The site must be optimized for access by the disabled.
In accordance with the Americans with Disabilities Act, you should try to provide for the needs of the visually impaired. It is important to provide ALT and SIZE tags for all non-text elements of a site, this will not only help with page layout as it downloads, but it provides feedback to the users who are unable to see graphics. Keep in mind that this includes many users on older systems and in other countries who are using a text-only browser. Yes, Lynx is still out there and still being supported. A great place to check your site is Cast:Bobby. This will check your site, rate it and suggest things you can do to improve the rating.
The pages must download reasonably quickly over a 28.8 connection.
This is a guiding principle, though the specifics will change as technology disperses. The goal is to allow the average user to access and navigate the site quickly and easily, and this is the "quickly" aspect. For reasonable download times, pages should be no more than 65K in total page weight including graphics. This is harder to gauge when using XML (such as ASP and Cold Fusion) as only the relevant components of a file are downloaded by the user. Animation tends to be rather large, and can bump the page weight up a great deal, so be aware that while a Flash animation may only be 8k, the corresponding GIF may be 50K.
The site must have consistency from amongst same level navigation, and sub areas must have a look and feel that is consistent with the site as a whole.
The user should not have to guess where they are. Fonts, colors, location of logos, and so on should be consistent from area to area within each depth. The site must be consistent in it's use of fonts. That is the font used for the body should always be the same, and the headings should always be the same, but the body need not be the same as the heading. The section on fonts offers a more complete description of how to achieve this. Remember that tables will ignore all surrounding font information. This means that EVERY cell must have its own set of font tags, or that cell will display text the in the browsers default font. On your browser this might be the same as the expected font, but on someone else's, who knows. Be careful and include font tags for everything. You can use Cascading Style Sheets to deal with this, but then you are presuming that only people using IE will be viewing your site.
The site must fit into a 800 X 600 screen.
Realistically this only applies to width. If the user ever has to scroll horizontally on a 800x600 screen with the browser occupying the whole window, that is bad. Vertical scrolling is a fact of life. This is especially important for the graphic artists, as this places an upper limit on the width of any graphics, and it is not 800 pixels. Because the browser will always take up a certain amount of space with its borders, scollbars, navigation, etc. the effective display area is 762 pixels wide. As the webmaster you need to make sure that all of the text, tables, etc. that you place can fit into the display area without forcing horizontal scrolling or odd artifacts. Sometimes, on a small screen with fixed width (even % widths count here) inside other tables, a table will slide under a graphic and look very odd, so make sure that you take in to account the presence of any graphics. And, as much as possible the site you create should also expand to 1280 wide without losing the design. Whenever possible take advantage of the browsers ability to adapt to the users environment.
The site must use colors and fonts which are web safe.
This will be dealt with in detail in the areas on web-safe colors and web-safe fonts, but the basic idea is: use colors and fonts that users are going to be able to see the way you intended them.
Technical Details
When designing for the Web, there are several constraints that are unique to the internet. It is important to keep these issues in mind when designing site in order to ensure that the average user will be able to see the site as it is intended.
Return To Top
Web Safe Colors
In spite of the wide availability of cheap video cards that support millions of colors, the average user is still using 256 colors. This is due both to the users who are still using older computer systems as well as to the reluctance on the part of many users to mess with their settings. There are effectively 216 colors that can be used on the internet, as the OS tends to use about 40 colors (this will vary slightly for non-Windows platforms, but the accepted standard is 216 colors). These colors can be entered using color name, but this is not recommended as different browsers will have slightly different interpretations of the names. It is safer and more consistent to use hex codes for your colors. A hex code is a 6 digit code that breaks down into three 2-digit pieces, these are referred to as "browser safe triplets". Each piece maps to an RGB value that is considered "web safe". The code pairs that can be used to build the hex codes and corresponding RGB values are:00 00
33 51
66 102
99 153
cc 204
ff 255
Any three of these sets can be safely combined to render a color that will be reasonably consistently interpreted by all major browsers. The Art Director for the site determines ahead of time what the RGB values are for each color. Obviously, there must be exceptions to using browser-safe colors. Images of people for instance, but these are generally saved in the JPEG format where everything is dithered anyway.
Return To Top
Web Safe Fonts
The fonts considered to be web-safe are as follows:Win Mac
Arial Bookman, Geneva
Times Times
Verdana Helvetica, Chicago
Tahoma Helvetica
Symbol Symbol
Courier Courier, Monaco
Georgia Palatino, Times
Impact Chicago
When selecting a font, make sure you use both the Win and Mac equivalents.
Return To Top
Using ASP fonts
Keeping fonts uniform across and entire site, and consistent with the site design is extremely important. If you are working with a client that uses IIS or a UNIX webserver that supports Front Page Extensions, you can application variables from the global.asa file, and define your fonts in the global.asa.In order to use these standard pieces on the site, you need to surround any given piece of text with the start and end ASP font tags. For example <%= application("font_subhead") %>Sub-heading<%= application("font_subhead_close") %> produces text in the sub-heading font. Probably the easiest way to do this consistently is to set up tag snippets in your editor (or something similar, if you aren't using Homesite).
Return To Top
Supported Browsers
Goal - You should try to support a wide variety of browsers, with varying degrees of sophistication and success. In principle I support down to Netscape 2. Because of the way the early months of the browser wars went, IE 3 is roughly equivalent to Netscape 2.
Practice - Supporting Netscape 2 however, does not mean that everything will work perfectly. What it does mean is that the site degrades in such a way that users can see the information, and expect their browser to not crash.
Netscape 3 has some limitations on what it can and can't do, and the version 4 browsers support most of the same things. Realistically, IE 3 and Netscape 3 are probably your target audience, though if you want (or your customer wants) to target more recent browsers, just make sure it doesn't blow up older ones.
Browser Features
Function/Browser Netscape 2 Netscape 3 IE 3 Netscape 4 IE 4
ALT tag on Image Rollover X X X
Table background color X X X X
Table background image X X X X
Table Cell Color X X X
Table Cell Background Image X
Page Background Image X X X X
Locked Page Background Image X
JavaScript Image Replacement X X X
JavaScript Form focusing X* X X X X
Automatic download of plugins X X
Use this chart as a reference for which browsers support what features (as you can see, Netscape 2 is pretty feature poor). A few explanations are in order:
ALT tag on Image Rollover - this is when a little (usually yellow) box pops up, like a tool-tip, and displays the contents of the ALT tag when you hold the mouse over an image for a second. This is different from JavaScript Image Replacement
Table background color - the ability of a table to have a different background color from that of the page
Table background image - the ability of a table to use a tiled image as a background
Table Cell Color - the ability to designate the color of INDIVIDUAL CELL backgrounds within a table
Table Cell Background Image - the ability to designate a tiled image as the background for an INDIVIDUAL CELL in a table
Page Background Image - using a tiled image as the background for the entire page
Locked Page Background Image - the ability to "lock" the background image, so that it does not scroll with the page (content will appear to "flow" over the image)
JavaScript Image Replacement - a feature of JavaScript 1.1 and the DOM which allows dynamic image replacement (swap one image from another). This is commonly used in menus and error checking. It can be associated with various mouse actions, such as moving into or out of an area on the screen. This is different from the appearance of the ALT tag over images in some browsers.
JavaScript Form Focusing - using JavaScript 1.1 to place the cursor in a specific form field. Often used with forms and error checking. *In Netscape 2 this may be prevented by an "Out of Memory Error"
Automatic Download of Plugins - Later versions of Internet Explorer will automatically "fetch" an Active X controller for the user. Netscape supports a similar feature for Plug-ins, but not very well, and we generally avoid using it. Most commonly used w/ the Macromedia Shockwave Flash Active X Control.
How components affect page size
Web pages are no longer simply plain text (like this page), but include graphics, animation, streaming audio and video, assorted script and programming languages (CGI, VBScript, JavaScript, ActiveX). Each of these components adds weight to the page. Design with the 28.8 modem user in mind, and try to have each page download in less than 8 seconds. This means that effectively you will try to limit each page to 65K or less. (This entire document is 61.8K). Most HTML Editing programs offer an option to check your page weight. This is useful, but not always entirely accurate. The most effective means of checking is to dial-up on a 28.8 modem in the late afternoon, when net traffic is at it's peak.
Return To Top
Page Size
Managing the components that affect page weight is a matter of planning. The primary area of concern is animation. Animation is very popular and flashy, but it must be kept to a minimum in order to maintain a reasonable download time. It is customary to have an animated logo for the client, and if this is the case any further animation is not advised.A more subtle area of concern is the ASP pages. The server checks through every potentially included ASP page during it's initial pass. This means that if there is an include link to a page inside an IF statment, regardless of the results of that IF statement the server checks to see that the file exists. And of course it loads and evaluates any pages which are actually included. If a page has too much infomration on it, this evaluation can slow down the server significantly in serving the pages. You will see this sort of problem as a slow response from the server. It isn't a common problem, but is one of the reasons that the second-depth contents files should be broken up. It can also be a problem in forms which contain large amounts of redundant information. For example, I worked on one site asked users to select the state they were in, and then had 50 possible next pages. Twice. Once each for two different forms. Simply grinding it's way through that decision tree took the server a while. Since the actual information displayed on the next page was the same for every state except for the name of the state, and whatever state-specific information came out of the database, we changed the first page to pass the name of the chosen state in an ASP variable. Then all we had to do was write out that varaiable on the next page. This reduced 50 possible choices to 1 for each process. It would be possible to reduce it to a single process by sharing the state-selection portion between the two. There would still be some server load assocaited with that, but it would reduce the sheer amount of information to be maintained.
Return To Top
Error Checking and you
Forms are a pain. Let's establish that right up front. However, they are also extremely useful for our clients and for us. The primary problem of forms (after formatting them) is making sure the user puts in the information that you want. To resolve this issue, we use error checking.All forms which have some fields which must be filled out, or must contain a certain type of text, use error checking. Error checking should accomplish the following, if there are errors:
Clearly indicate which field(s) need to be corrected
Places the cursor in the field to be corrected
Provide the user with some indication of what might be wrong with the entered information
Require the user to submit the form as few times as possible
Do not proceed past the current page until the form is validated
Indicate fields to be corrected
This is done through the use of JavaScript Image Replacement. Several red exclamation marks appear next to a field which contains an error
Place the cursor in the field
This is done with JavaScript Form Focusing. Only one form field at a time can be effected, and so only the last field checked will actually have the cursor located in it, though if you're quick of eye, and your machine is slow of processor, you might see it flicker through several different input fields as the form is checked.
Provide Feedback
Most often this amounts to telling the users that a required field has not been filled out, but it can also be information about a required number of digits in a phone number, etc.
Minimal Submission
The error checking goes through the entire form before allowing the user to correct mistakes. That way they know everything that needs to be fixed, and don't have to continually submit the form fixing one problem at a time.
Summary
All of this is summarized visually on the last page of this document with a labeled screenshot. This shows a standard vanilla form which has been submitted with no information filled in. All of the fields are highlighted with red exclamation points, the cursor is in the last field checked (in this case "eve phone"), and a single JavaScript alert box is present summarizing the reasons the form was not submitted and providing the user with information. With variations in language to meet the desires of the clients, and make clear what needs to be done, this is what an incorrectly submitted form should look like.
Degradation and Known Problems
Obviously the JavaScript Image Replacement does not work on all browsers. Users should see no image if their browser does not support this. There should be no errors associated with it. A similar situation exists when placing the cursor in the field.
Netscape 3 has an intractable JavaScript error, where it often, but not always, produces an error with the message "undefined is not a number" after the form has been successfully submitted. The line number associated with this error points to various places depending on the exact site being looked at, and often to a line w/ no JS content. During troubleshooting the error becomes inconsistent, and cannot be reliably associated with any specific section of code. Sometimes it just goes away on its own and then comes back later. At this time, we have decided to let it go.
Netscape 2 will usually produce an out of memory error and not run the JavaScript at all. There is no error checking in Netscape 2 sites. The form can still be filled out and submitted. Because this comprises such a small number of users, I would not be too concerned, as the effort required to make all sites backward compatible with Netscape 2 is vastly out of proportion to any imagined return.
Similarly, old non-Internet Explorer versions of AOL do not support any type of error checking. These should not report any script errors.
Return To Top
How to use Includes
Includes are your friend. Include files are used to call large amounts of content that would be unwieldy in the primary file or files that are going to be displayed on many or all pages in a site. An example would be creating the basic structure of a site. The index file could call included files such as header, footer, buttons, and contents. The first three are components that will show on every page of the site, while the last calls specific content based on variables. I use include files to ease the maintenance of client sites and to simplify the site structure. Deciding if an area needs an include is a matter of judgement, and varies from client to client. If an area has several sub sections, it can be useful to place all those into an include file (productinfo.inc, support.inc, etc. for example) and call to those from the index.asp file. It might seem to make more sense to call them from the content.inc include file, but as a general rule you should never call an include file from another include file if you can possibly help it. It used to be that this could actually generate errors. While this is seldom the case now, it does make it much harder to track down the offending file when errors do occur, or when material needs to be changed.Return To Top
Site Structure using ASP
The index page is the building block from which all else springs. The index serves as a framework that places all content regardless of what area of the site you are in. In many sites there are multiple levels, or depths, that each have their own index. Again, the purpose of these is to maintain a consistent look and feel for each depth. There should not be any content in the index page. It should contain only include calls, body attributes, and layout information. All fonts and colors are called from the file global.asa in the root directory of the client. Rather than enter complete font tags, such as <font face=verdana, garamond, comic color=ff6600 size=2> you will place a call to the global.asa using the format <%= application("font_body") %> content <%= application("font_body_close") %>. This makes maintenance much easier and ensures consistency from page to page within each site. I recommend creating tag snippets in your HTML editor (assuming it supports them) to make your life even easier. There are, as a rule, five sections to each page: Header, Primary Navigation, Secondary Navigation, Content, and Footer. Where these show on each page is a function of how the index file is laid out. It really is that simple.Header - This file contains items such as client logo, header graphics, perhaps some animation, etc.
Primary Navigation - This contains the means for the user to find their way around the site. It will usually consist of graphics, though sometimes the navigation will be via text links. We generally use JavaScript to activate rollovers for buttons, and the script is included in the Templates. Primary Nav is used to move around between the major areas of a site (e.g. Product Information, Support, HR).
Secondary Navigation - Secondary navigation is sometimes included in the same file as primary navigation, though it usually is located on a different part of the page (directly under the header, for example). Secondary Nav is used to move around within a specific area (e.g. Product X, Product Y, Product Z).
Content - Obviously, this is where all of the actual text, content-related graphics, multimedia, etc are located. Once a site is "live" this section is the only one that will really be worked on. It can come in more than one section, depending on the complexity of the site, and alternate depths will have different content files.
Footer - The footer contains any standard information we want to appear on all pages but is not a focus of the site, examples being the corporate logo and copyright information.
Return To Top
Navigation
Goals - Ease of Use, Consistency.
Practice - Sites should be built with the dual goal in mind. It should always be obvious to the user where they are in the site, and how they can get to another section. The location of section titles and navigation should be consistent from section to section within each area.
Return To Top
Naming Conventions
In order to ensure ease of maintenance, consistency in naming files and graphics is crucial. Obviously spaces are not allowed, so to avoid duplicate names, and to make names easier to read, a "-" or "_" is generally used to separate words.
HTML/ASP File Names
File names are built up out of some standard parts:
index - every main page should contain the word index, and the first page the the user hits must always be index.real or index.html.
contents - files which contain content information for one or more index pages
buttons - files which contain buttons for one or more index pages
others - other files should have names that relate to their content/function (registration_form_process.asp, copyright.inc, etc)
Graphics File Names
Graphics tend to have their own quirks, built up as different Graphic Artists and Webmasters have added their own bits. As a rule, graphics are named type-name.[jpg|gif|swf]. This way, it is easy to find all the graphics of a similar type, since they are all together in the file list. Naming of graphics should perform the same function as the ALT attribute of the IMG tag. For example: green_login_button.gif is much more scrutable than grnlgbt.gif, especially 6 months and several projects down the road. If you're operating on a system that only supports 8.3 filenames, good luck.
Directories
Part of the naming conventions is the directory structure we use to organize the files. Directories should be immedately under the root directory for that site, and should not contain sub-directories unless they are absolutely necessary. The only things that should be in the root direcotry are the index page(s), global.asa, and possibly other required index pages. All other files should be in one of the directories. A suggested file tree is as follows:
includes home of all include files, buttons.inc, copyright.inc, contents.inc, etc.
resources home of all graphics, shockwave, or other media files (except Real Audio - those may live on their own server)
As you can see, this would make finding pieces of the site ridiculously easy.
Return To Top
Definitions
Areas - The easiest way to think of areas is as pages. Any discreet page you see on the site is an area. But really areas are content-related parts of the site. Areas often have sub-areas associated with them, each of which is an area is it's own right.Depths - Depth is a fairly abstract concept. The name comes from the idea of "drilling down" through a site, but it really has to do with the type of information displayed, and how that information is laid out on the page. Most sites have two, or maybe three depths. Thus primary navigation areas, such as "welcome", "products", support so on all share certain characteristics. They contain the general information about an area on the site. The pages all have a certain appearance -- Header here, primary navigation there, secondary navigation (if needed over there), contents in this spot. The second depth might deal with the sub-areas, and the layout may be different from the first depth. This is where depths relate back to navigation and providing continuous feedback to the user about exactly where they are in the site. It is possible that a site might be designed where every area is it's own depth, however I generally discourage that because it makes the site difficult to maintain, and creating truly consistent and clear navigation can be much more difficult.
Push - The process of moving files from one server to another.
Return To Top
Hidden Form Fields
There are all sorts of reasons to use hidden form fields, but the two most common are to pass on information from a previous form, through the current one, and on to another page, and invisibly tracking if the user has submitted a form yet. The next topic deals with the former, so on to the latter.In order to keep the navigation fixed on the Inquiry area even after the form has been submitted, and while the user is reading whatever on-screen response they receive, and without using a second URL variable, a hidden field is just the ticket. Near the end of the form, in fact, often as the last thing in the form, add <input type="hidden" name="submit" value="submit"> Then, if you use the following ASP you can easily keep the navigation focused where you want, and still limit what part of the content gets processed by the browser by checking to see if the form element "submit" is defined:
<% if Request.Form("submit") = "" then %> <form action="index.real?action=inquiry" ... > and the rest of the form goes here . . . <% else %> and the form processing and response goes here . . . <% end if %> Using ASP to pass form fields There are times when you need to collect information from several pages of forms before processing the data. In that case, this bit of ASP will automatically collect all the previous form elements and add them on to the current form as hidden fields, with the same name as they had before.
<% for each x in Request.Form %> <input type="hidden" name="<%= x %>" value="<%= Request.Form(x) %>"> <% loop %>
