APPC Web Design Manual



The goal of this mountain of text is to outline APPC’s web design philosophy and ultimately provide documentation that’s applicable to all web projects. If you have your doubts, here are a few things to consider.

Sticking to best practices facilitates growth. In the event we need to bring on a new hire or contract worker for any web projects, we’ll be able to attract the best talent if we do things in line with other employers. We need to stay competitive, and we can’t do that if we’re not following best practices.

The other side of that coin is you. You’ll be much more valuable to the rest of the world if you have experience building and deploying web projects using best practices than you would working with a solution built for a very specific purpose. You will learn skills and procedures that you can take anywhere. If you interviewed at a company and listed “web” as a skill, they’d assume you’re familiar with some very specific procedures and technologies. If you follow this document, you’ll be covered.

Beyond that, doing things “the right way” is beneficial to APPC’s image. We’re part of the University of Pennsylvania. That means something. We want to show the world that we’re competent and our work is purposeful. Lack of focus on use cases and poor overall user experiences do not help us in that respect.

This guide does not cover roles and responsibilities. Those will vary project to project based on time and availability. Instead, treat this as a brief outline of the four phases of website design — content strategy, build, revision, and rollout — that can be supplemented and elaborated upon as needed.

1: Content Strategy Phase

1-1: Content Audit

It’s always tempting to jump right into the fun parts of web design, like drawing logomarks or picking color palettes, but the first step of any creative project should be figuring out the content. To do that, you need to start with a content audit. Think of a content audit as like a catalog of resources. The goal here is to produce a document that lists the crucial elements for your site. If you’re migrating or redesigning an existing site, this should reflect all current content, even content that’s being abandoned. Why? Because it’s better to have a trail of what was abandoned and why rather than simply excluding it from the content audit and wondering later on if something was overlooked. If you’re creating a new site, the content audit serves as an inventory of all the content that needs to be created for launch.

The easiest way to do a content audit is in a simple spreadsheet with a column for each attribute and a row for each asset. These will vary by project, but some common attributes include:

  • Role – Is the asset a single entry, an index collecting many entries, a static page?
  • Content Type – Is the asset a page, block of text, video, PDF, something else?
  • Publication Date – When was the asset published, or when should it appear to have been published?
  • Author – Who is the the displayed owner of the content type, or the associated user in the CMS?
  • Taxonomy – What hierarchy does this asset belong to? Is it part of a series that follows the same content model, or is it unique and does not belong in any taxonomy?
  • URLs – Where did this asset live, and where is it going to live? If you’re migrating or redesigning a site, this helps map redirects and helps with keyword optimization.

Please feel free to use this content audit template spreadsheet. Just dupe it and customize as needed.

1-2: User Research

The second most important component of a website (after content) is the user. No matter how pretty you make it, a website won’t be worth much if it doesn’t meet the wants and needs of the end user. And the best way to know what your users want is to ask.

The most common method of collecting user research is through focus groups or individual interviews. Even if the project budget doesn’t allow for such an intensive level of data collection, it’s essential that user research involves real users. Online surveys are a good alternative to in-person interviews.

Another option is to hire an outside party to conduct research. There are very large organizations that specialize in user research and they tend to do a very good job.

Chart the common trends across your user research. Determinant variables will emerge. Identify patterns that will help craft user personas and scenarios.

1-3: User Personas

A persona is an abstracted representation of your user’s goals and behaviors, speckled with fictitious personal details to create an empathetic anchor. They provide a clear pass/fail metric for products. “What would [persona] do if they hit this page?” “Would [persona] be able to figure out this feature?” “Is this language how we would talk to [persona]?” Personas have long been popular in marketing and user experience design because they’re easily adaptable and reusable… you can swap a persona for another in the middle of a project without derailing all the work you’ve done. That’s what makes this model a perfect fit for APPC. Initiatives often change directions. Very often. Instead of trying to fight change, we should adopt a process that anticipates it.

Developing a persona involves combing through user research, mapping the qualities of a user to a template, and attaching an invented name and photo to protect the user that the persona was based upon. Allow me to reiterate this: the personal details of personas should be fictional, even if they’re created based on user research. It just makes it a little easier when the persona that’s been causing everyone headaches isn’t someone that you have to eat lunch with every day.

Persona Example - Connie

Main Qualities of a Persona

  • Expertise – Indicators of technical proficiency levels as well as general connectedness.
  • Personality – Myers-Briggs Type Indicators are good here, even if they’re not worth much in the real world.
  • Social Demographics – Age, location, social class, income, and other things that can be targeted directly.
  • Desires and Goals – What the user hopes to accomplish, using the product or in general.
  • Motivations – What drives this person to engage with the product. Are they teachers looking for lessons? Stakeholders trying to see ROI?
  • Influences – How does this user make decisions? Are they likely to click links on social networks, or do most product recommendations come from their monthly book club?
  • Variables – The little things that flesh out the big picture. Owns an iPad, commutes to work, doesn’t know how to cook, etc.

The most important element of a persona is authenticity. Personas need to be consistent so that they can serve as strong foundations for product decisions. It’s better to have a complete persona that’s not the right fit for a project and gets shelved than it is to have a great fitting persona that doesn’t reflect reality.

And, again, personas are reusable. Just because they don’t fit your current project scope doesn’t mean they can’t be employed in the future.

1-3: Content Models

Content models essentially serve as display templates for different content types, making evident the common components among assets in a given taxonomy. For example, a page listing a publication might include fields for author name and release date. These fields will be useful for anything that’s considered a publication, so it makes sense to design a content model for publications that includes these elements.

Content models are essential for designers and developers during the build phase in order to prevent miscommunication about field requirements. The best way to create a content model is in a spreadsheet, listing all required attributes for each component on a page. Using the above example of a publication, the author name field would need an indicator that it’s a simple text string, and the release date field would be formatted to as a date display. Spreadsheets are great. Sometimes I wish I was a spreadsheet.

1-5: Content Hierarchies

The goal of content hierarchies is to determine logical structures for the content, both site-wide and for individual pages.

For site-wide content hierarchy, this is about page flow and urgency. In most cases, a page for privacy policy will be less important than a video, and therefore shouldn’t be ranked higher in terms of hierarchy. It’s important to determine what users see when they land on a page, where they are being funneled, and how many clicks it takes to perform an action.

For individual page hierarchy, this is about the structure of assets on a page and what their level of importance is. Consider how a user sees a page: from top-to-bottom, left-to-right (in most cases). Is the essential information being communicated effectively? If there’s an action, is it presented in a logical context? Are other content blocks grouped correctly? It’s easy to treat pages as just a single content block sandwiched between a header and footer, but we need to consider all elements in context.

Again: Spreadsheets are great. But content hierarchy can be established just as well by using wireframes.

1-6: Card Sorting

Once you understand what your content is and how it’s organized, you need to check in with your users. A card sorting session is a good way to gauge comprehension of your assets and see where there are holes in hierarchical logic. Here’s the procedure in a nutshell:

  • Take your content audit and make an index card for each entry. Like, a real index card that you can hold and touch and get paper-cuts from. It’s okay to use the only most important or popular assets as long as all content types are represented. Try to stick to 50 cards or less.
  • Gather some participants from outside your team. Ideally these would be screened participants who overlap with your target audience in some way and are compensated for their time. Not so ideally, these participants are any person in grabbing distance who wants some mental stimulation.
  • Give the participant your index cards along with a stack of blank colored cards and a pen. Ask them to sort the index cards into logical containers, then name each container using a colored card. Encourage thinking aloud.

Make a record of the participant’s hierarchy, either by taking a photo or making notes. From there, you can look at how often cards appeared together and how often certain cards appeared in specific containers. The commonalities between different sessions will give an idea of how to improve your content hierarchy. The differences will make problem areas that need attention more apparent.

2: Build Phase

2-1: Development Priorities

This section might seem like common knowledge if you’ve worked on a website before, but it’s extremely important to affirm development priorities with your team before any actual development begins. These are the deal breakers. These are the things we have to absolutely stick to and can not compromise on.

  • Standards. All public facing code should follow modern web standards.
  • Accessibility. All site content must meet WCAG 2.0 guidelines.
  • Mobile first. Start small and add features instead of starting big and needing to take away.
  • Design in browser. It is faster, easier and smoother to design with real materials than to translate a mockup.
  • Progressive enhancement. Follow the model of Elements (content) > Markup (HTML) > Styles (CSS) > Interactions (JS).

It may be worth memorizing this list and reciting it out loud every time you meet a new person. It will make you popular.

Progressive Enhancement Structure

2-2: Content-Only Build

Now we’re getting to the bulk of the work. The first step in the build phase is to make a content-only version of your new website

Content-only builds are super important. When you start with just the markup layer without any styling or polish, you can ensure accessibility, as the content-only build will be what a user sees when absolutely everything is broken… javascript, css, webfonts, the whole shebang. It’s easy to start with an accessible base and add styles on top. It’s hard to start with a style and make sure it degrades gracefully later on.

In terms of labor, creating the content-only build requires populating all of the items from our content audit in a fresh WordPress environment, along with all the associated taxonomies, tags, and fields. Once this is completed and passes inspection from stakeholders, we can begin the actual design work.

2-3: appcwp WordPress Theme

Normally, going from content-only to basic styles is a headache and time-sink. But we have a bit of a shortcut. The appcwp WordPress theme was designed as a barebones parent theme for APPC website projects. We load it as the parent and develop our theme as the child. There are a few distinct benefits to working with this model.

  • Using a unified parent theme as the framework for all sites makes updating and maintaining sites much easier. New version of Bootstrap? Updated HTML shim? Make the change once to appcwp and then push it to all the live sites. This will lead to less fragmentation and less headaches down the line, since we won’t have to worry about dependency conflicts or outdated plugins.
  • We’ll be able to switch to a faster release schedule and do away with the painful “major release candidate” model we’re currently using. Instead of waiting for things to slowly break and then working on a huge redesign over the course of six months to a year, the core codebase behind our sites will always be up to date, and we can focus on content and delivery.
  • We don’t have to worry about third-party themes anymore. Buying a theme for $50 and then customizing it to fit our needs is great in theory. But as we’ve learned from recent major web projects, they’re more trouble than they’re worth. These themes don’t always follow best practices, they don’t always meet accessibility guidelines, and sometimes they don’t even function in all environments. We end up spending more time troubleshooting and hacking themes than we would if we created our own from scratch.
  • Since appcwp is a barebones theme without any styling, we’re able to start with a content-only build of the site that we know degrades gracefully in questionable conditions and meets accessibility guidelines out of the box. This saves a lot of time, eliminating the need to use separate themes for content-only builds and production builds.
  • We’ll be able to reuse environments and elements across projects. The appcwp theme is managed by the APPC’s private git, so creating a new theme will be as simple as creating a local copy of the git.

Since we’re using git to store repos, we have the option to use version control. This is huge. If you’re not familiar with version control, it essentially keeps a record of every change ever made to a project, who made the change, why, and allows rolling back selective elements without losing any progress. It’s the closest thing our world has to actual magic.

2-4: Style Guide

Style guides are the ultimate tool for content managers. Every site needs a style guide, even if the style isn’t necessarily unique. The goal is to make maintenance of the site modular to the point of having a complete stranger (or a work-study student) be able to create new content using only the style guide.

For websites, style guides have the benefit of being able to offer code snippets. Users who aren’t comfortable typing HTML can copy and paste snippets for established content blocks, such as responsive video embeds.

It’s important to maintain the style guide as the site develops and update it with new snippets and examples.

2-5: Content Block Development

Any website is essentially a cascade of content blocks, with each block containing a series of smaller blocks, all the way down to the individual element being displayed… words, pictures, videos. This page is a content block, and inside that block is another block with a menu, and inside that menu is a link, and inside that link is some text.

During content block development, you’ll write CSS for the content models that were created during the content strategy phase — all those little details and extra fields like publication dates and author names — using the content hierarchy to establish layout and flow. All the preliminary work we’ve done with logging things in spreadsheets pays off here, and the designer isn’t forced to do too much trial and error.

Working this way also makes it easy to develop and maintain the style guide for your site. Make a content block, put it in the style guide. Easy-peasy.

3: Revision Phase

3-1: Accessibility Testing

We’ve already got accessibility mostly under control thanks to the content-only build we started with. But it’s important to continually reassess the accessibility of your site during development.

This includes things like testing the contrast ratio between foreground and background, testing on various operating systems, and testing without a mouse. Make sure everything is accessible with only a keyboard, that all elements display properly regardless of environment, and that everything is visible for users with vision impairment.

3-2: Edge Case Testing

This is where things get weird. The goal is to find every little thing that can (and therefor, probably will) break. Load the site on an iPad, an old Gateway running Windows 95, a PipBoy, a Commodore 64, whatever you can get your hands on. Turn off Javascript and disable cookies. Throttle your bandwidth so the site loads crazy slow. Like 28,800 baud modem slow, because some of your users are going to be using a 28.8kbps connection. Just try your hardest to replicate the extreme edge cases that you’ll see when the product launches.

3-3: Site Optimization

Site optimization is a continuous process, squashing bugs and reducing code redundancy as you go, but there are a few tasks that should be put off until the site is moving towards a release candidate. These include:

  • SEO: Keyword stuffing, metadata, optimizing permalinks.
  • UX: Concatenate scripts and styles, integrate CDNs, generate optimized images & srcsets.
  • Social Media: Twitter cards, OpenGraph data, other sharing hooks like Edmodo or Pinterest. These really depend on the scope of the project and target audience.
  • Javascript: Fancy pants stuff. Now that content is in place and styles are ready to go, that last layer of polish can be put on top with animated elements and other spiffy wow-factorials.

4: Rollout Phase

4-1: Success Metrics

Almost there, I promise.

Every site should have success metrics. I know what you’re thinking… “But APPC doesn’t make money! We ain’t no Commmmmmcast!”. That’s okay. Success metrics don’t have to be lofty accounting goals like “reach a trillion dollar valuation” or “don’t operate at a loss”. Here are some sample metric targets:

  • Increase average weekly visits
  • Increase average number of page views
  • Decrease bounce rate
  • Acquire a given number of new newsletter subscribers per week
  • Acquire a given number of social media interactions per month
  • Increase referral links

Personally, I’ve found that the simplest way is to implement a user survey on the site and set a threshold for success. Just a little pop-over modal that asks for a rating of the site on a four star scale. If more users rate positively than negatively… congrats, you’ve met your metric.

4-2: Double Checklist

Measure twice, cut once. Wait, that’s not good enough. Measure, like, eleven times. This is important! Run through this checklist and verify that everything is ready to go.

  • Compare final site to initial content inventory. Make sure nothing was left behind.
  • Proofread all content. Have outside parties help.
  • Check all links and interactivity. Make sure nothing is a dead end.
  • Have the designer check the site on all major platforms and browsers.
  • Check responsive breakpoints.
  • Check font weights and color contrast ratios against WCAG 2.0 guidelines.
  • Make sure the site is accessible to keyboard users and screen reader users.
  • Make sure 404, empty SERP, and “Nothing Found” pages exist.
  • Validate HTML, CSS, and JS.
  • Check that CDN caching is working properly and cron jobs are running.
  • Check that analytics are enabled and reporting properly.
  • Security tests, certificates, other complicated developer stuff.

4-2: Launch

A website launch happens in two stages: soft launch and hard launch.

The soft launch can be thought of a friends and family preview. Invite a few people that represent your target audience, have them use the site for a few weeks, see what happens. This is where those last few bugs get ironed out.

The hard launch is the real deal. The website becomes publicly accessible and the marketing can begin. There can be issues during a hard launch: domain name errors, database crashes, load balance issues. Most of these can be avoided by staging the site on the live server in a top-secret folder during the soft launch. This will prevent DNS issues and you can fully test the site, including the CDN. Then during hard launch, redirects can be used to take the site live while the content is migrated to the root directory and the cache is rebuilt.

Maintenance & Upkeep

Congrats! You’re done!


Web projects are never “done”. At least not until they’re taken offline. Maintenance is unavoidable as new technologies emerge and the web evolves. The best way to stay on top of your site’s upkeep is by instituting a feedback process and a regular release schedule. Keep a spreadsheet for bugs and user feedback (or use your favorite task manager). Take time every release cycle to triage these items and see what can be accomplished. Make changes on a staging server, then swap the staging and live environments after ensuring there are no issues.

In the software world, release cycles are normally every week or every two weeks, but your project’s budget may dictate a longer or shorter release cycle.