Needs updating to new cascade 11/10/2011
This is a detailed theoretical guide to the archive interface, focusing on the style sheets. If you would rather, here's a practical step by step tutorial on making a skin.
Read this guide first. Rails is DRY and so is our front end; this is not like what you have done before.
The AO3 front end, which is XHTML and CSS, uses a classification system that might be new to you in some ways, but will be familiar in others.
Rules on the archive are written in modules, and generally in order from the most general or global rules, that affect the most things on the most pages, to the most specific rules, that move a single element in one context. We continually combine and simplify rules, finding commonalities of purpose behind ways of displaying information, working towards a simple and consistent interface.
To put this another way: In our stylesheet, classes are laid out so more general classes (.blurb, .index, .work) are modified by more specific classes further down the cascade. Just like a chair can be modified by the adjective hard, a blurb can be modified by the class collection.
The core process in all front end design is the naming of things. By really thinking about each element we deal with, and describing it simply and aptly, we create the most readable (and therefore flexible, accessible, and maintainable) interface we can. This is true for CSS classes, for style rules, for bug fixing, for XHTML markup, and for page design.
Layout makers and post-release users: If you are remaking the interface, you can change this hierarchy because each object is described with many classes and so the display can be organised in lots of different ways.
There are about thirty stylesheets loaded by the document head, plus Internet Explorer conditionals. The order the sheets are listed in the document head is the cascade hierarchy.
The archive core defines typographical rules (font size etc) and basic element display. It doesn't use a lot of custom selectors like #dashboard or .blurb. Everything on the archive inherits these global, core rules. Let's move on to the sheet called site-chrome.css
navigation is the name we use for actions. div id="main" holds all the content on the archive. Within #main, we use repeating groups of HTML elements to display different kinds of content and different ways of interacting with it. The next level of selector - describing things contained within #main - is Metadata Grouping.
The way we display these groupings changes according to the kind of content it describes, so the next level of selector modifies these rules by content type.
What content you see is also modified by who you are, so we can also use the modifiers of roles and states.
Within the division #main the view changes. There are N basic views:
Works are viewed on their own pages. They are similar to a blog post: metadata at the top and comments at the bottom. Here's a diagram of the work view.
Bookmarks can be viewed on their own or grouped with all the bookmarks of a work. Grouped together, they are an index view.
Each identity has its own set of pages, listing activities like works written, works viewed, personal profile, preference settings, and so on. There's a persistent dashboard navigation to move through these pages.
Profile view is only used in user/collection.
Indices are lists of works, users, collections, or bookmarks. The metadata (title, tags, summary...) describing them is grouped in a blurb.
Views follow regular layouts and contain repeating groups of html elements. These groups are described with classes. We use single English words in our classes. Rails generates some classes, and those contain underscores; you can use them to target rules at individual pages.
Now we understand the taxonomy, let's look at how to manipulate different structures in the Archive. It's useful to think of these groups as objects.
There are different objects, or works, in the archive that you can interact with. A work might be a bookmark, a story, a comment, and they all follow a consistent design pattern: NAME CONTENT. Many other pieces of information may be attached to this HEAD BODY structure; this pattern is how all web pages are structured too, and all emails, sms messages, and so on. First we name something, then we show it. The archive by default shows as much information and as many actions as possible. Because all the information is classed, any of it can be hidden, de-emphasised or highlighted with CSS. We can easily reorganise pages as we develop and gladly allow our users to reorganise things to their own liking.
Blurbs are like identity cards. They're probably the most used structure in the archive, so let's look at the blurb in detail.
Return to the documentation index.