Sandvox Designers Guide

Experienced CSS web designers can build their own designs for Sandvox (or tweak existing designs from Karelia.)
If you do not know CSS (Cascading Style Sheets), then this section is not for you! Instead, please visit Sandvox Designers Only for a designer-centric look at Sandvox.
Download the Sandvox Design Kit (includes CSS starting points and sample HTML files for testing).
Please note that all of Karelia's designs are licensed only under the terms of the Sandvox Design License.
If you just want to make a quick change to an existing design, see our page titled Quickly modifying existing designs.
Recent updates to this page:
- Updates to designs and minor points; no longer really worth supporting IE 5 due to very low market share.
- Moved the content about the design aspects (not CSS) to Sandvox Designers Only page.
- Several additions to Minimal Standards whoops, this section was deleted; it has been restored
- Info.plist format: Clarification on bundle identifiers, Minimum App Version, KTMenusUseNonBreakingSpaces; KTIgnoredResources
- Structure of a Sandvox Design Package: Clarification on size/resolution of design thumbnails
- New section: Navigation Arrows
- New section: Custom Media Sizes
- New section: Photo Grid
- New section: Banners
- New section: Body Classes
- New section: Continue Reading Link
- Several updates highlighted in the Element Specification
- Clarified sizes of photo thumbnails (128px max) and photo pages (640 px. wide without sidebar; 320 wide with sidebar)
- Discuss div#page-bottom-contents added with Sandvox 1.6.
- New info.plist keys to better deal with grouping variations of the same basic design
- Documented info.plist keys that we have supported for a while, but forgot to mention! hasLocalFonts, viewport, and several related to custom banners.
Design Overview
Please read Sandvox Designers Only first for an overview of the designs and their contents.
Design Considerations and Constraints
Unlike some web-building programs where designs are simply “skins” on a fixed layout, Sandvox designs are completely abstract, subject to a few sizing constraints. Site/Page titles could go on the top, side or bottom; sidebars can go to the left or right; layouts can even be horizontally scrolling instead of vertically.
Most pages have the same overall structure, but there are several different page types (e.g. text page, photo-viewing page, etc.) that the designer will want to take advantage of.
The HTML markup is very rich, with many opportunities for a designer to hook into special div's throughout the page. Repeated elements have special markup that allows variety in the output.
Many header level text elements can be processed and converted into a graphic that is displayed in place of the text, as well; we call this "Header Textual Images” (described later in this document)
Special effects (such as having items appear to move when you scroll) are OK but should not be intrusive.
JavaScript for special effects and such are OK, as long as the site works perfectly well without JavaScript enabled! It should definitely not be required for navigation.
A page will generally not be empty, except that when the page is first created, it will start out empty. So be sure your design works OK if there is basically no content. If you need to use min-height to force elements to be at least a certain size, that is a good workaround — we want the layout to look OK when it's empty for the authoring environment (which uses Safari's rendering engine). When the real page is published, it hopefully won't need to rely on the min-height property (since that property is not supported in IE 6).
Page Structure Definitions

The body of a page generated by Sandvox may have one or more classes associated with it. See below.
A page can optionally have a logo image set for it. A page should look good with a logo of any size - or no logo at all. You may want to center the logo horizontally and vertically in the space allotted for it; see the thumbnail section for more details.
h1 is the site title.
h2 is the page title.
The sitemenu holds a short list of links to main pages on the website
On most page types (the “allow-sidebar” ones), there is a sidebar which contains pagelets (a small unit of content), at least 200px wide. Each pagelet has an optional h4 title. Generally, content in a pagelet should be centered (e.g. images) or have reasonable margins (e.g. text).
The main area is the area which holds the main contents.
An article div contains a single block of text & graphics.
Each article can have a callout which is supplemental content for that article. It is made up of pagelets as well.
For a folder, which we call a collection, its index.html page can be any page type. After the “main” area, it can optionally have an index which lists its contents in a variety of ways. (textual like a weblog, simple listing, photo thumbnails, etc.)
h3 is used for the title of each linked page in an index, which is a list of items listed in a folder.
The following tags have within them a <span class="in">. This is used for header textual replacement.
- h1 or h1 > a
- h2 or h2 > a (h2 > a would happen from an archive page, linking back to the main page)
- h3 or h3 > a
- h3 or h3 > a
Warning: Sandvox uses some element classes such as kBlock and kImage that only appear in the applications' web view, for editing use, and are not part of the exported pages. Do not rely on these classes in your CSS.
Body Classes
- sandvox (always there)
- allow-sidebar or 'no-sidebar (whether or not there is a sidebar on this page; the sidebar could be empty)
- has-custom-banner or no-custom-banner (whether or not a custom banner has been set for this page)
- home-page (if it's the home page, allows for a different look like a taller banner)
- IR or no-IR (whether graphical image replacement has been enabled)
Target Browsers
- Modern Browsers (Safari, Firefox, IE7, etc.): Should work really well; take advantage of advanced CSS 2.1/3.0 features if desired with graceful fallback.
- Older browsers like Firefox 2 and Internet Explorer 6 should be planned for, and degrade gracefully if the design has modern features.
- Very old browsers like IE 5.0, 5.2, 5.5, 4.0 don't need to be supported on newly created designs; their usage is minuscule now!
Testing Parameters
Be sure to validate your CSS. CSS should be valid except for aspects where you are pushing the limits of the standards; please use The W3's or WDG's validation service. Mac users may find this script useful: http://earthlingsoft.net/ssp/blog/2007/01/css_validation
If you are doing non-standard but non-breaking things, like CSS 3.0 things that generate an error, that's OK. Some examples of CSS that is not technically valid, but still fine:
- word-wrap: break-word;
- rgba() colours for Safari
- text-shadow
- the various corner-radius properties (like -moz-border-radius and -webkit-border-radius)
See how well the design works with larger and smaller text; imagine the user increasing the browser font sizes...
See how well the design works if you add more content within the body (e.g. a title with multiple lines), or take all the content away.
Look out for any other combinations of large and small bits of content. For instance, what happens if you have a weblog-style collection, with long callout content but short article content ?
Testing Files
A number of test files are included with this package, these can be used to exercise the style sheets as much as possible. Though ideally, the design should be installed into Sandvox and taken through its paces, especially to make sure that the editing boxes are reasonable.
Structure of a Sandvox Design Package
A sandvox design is a packaged in folder. It is named for the design's title (a hopefully catchy name which doesn't appear on the page) with the extension ".svxDesign". (It will be a package in the Finder on Mac OS X if you have Sandvox installed.)
The folder contains the following elements:
- main.css
- CSS file to handle all page types generated by Sandvox. (Optionally, you can include other CSS files from main.css to deal with browser-specific issues.)
- print.css
- optional print-media CSS file.
- Info.plist
- Computer-readable file describing the technical details about the design. Also a good catch-all place to store information such as the sources of images and fonts. See details below.
- placeholder.jpg
- a picture (optional), 640 pixels wide or tall, that will show up as a placeholder for a photo page. This photo should go well thematically with the design it accompanies. Karelia can often find a good placeholder to go with your design.
- javascript.js (optional) if any javascript is used
- thumbnail.png or thumbnail.tiff
- A thumbnail image representing your design. Not a miniaturized version of the page, but an image to indicate the essence (color and images, not text) of the design. Sandvox adds a rounded-rectangle border around this image, so do not include any border in your image. For thumbnails showing a pixel pattern from the design, the image can be its minimum size of 100 pixels wide by 65 pixels high. Most thumbnails should be double size (200 by 130) or even quadruple size (400 by 260) for a future version of Sandvox to display at a higher resolution ... but if the thumbnail image has pixel textures equivalent to the web page, it should not be scaled up. You can use a multi-resolution TIFF if you want to make sure the thumbnail looks good in several sizes.
- Credits.rtf
- Credits file containing copyright information, credit for third-party graphics and fonts, etc.
The folder also contains any images (.png, .jpg, .gif) and fonts (for Header Textual Images) used by the design. These should be in the same directory as the rest of the files, not a subdirectory.
Additional text files (ending in .txt or .rtf) containing notes, licensing information, etc. are fine; they will not be uploaded to web sites that use your design.
Info.plist format
This XML file can be opened in Property List Editor or a text editor. It contains the following keys and values:
- CFBundleIdentifier
- unique identifier for your design using the reverse domain name, like com.domain.name. Designs provided with Sandvox will be of the form sandvox.title. (Spaces are OK in this identifier) Yours would be like com.myCompany.Sandvox.MyDesignTitle
- CFBundleShortVersionString
- Numerical/string version of design; this is shown to the user when they do a "Get Info" from the finder.
- CFBundleVersion
- An integer like 1, 21, 87, 30493, etc. (no letters or decimals); this should be incremented each time it is released to help Sandvox notify users of new versions.
- title
- Title of design. (memorable rather than purely descriptive)
- genre
- one of the following: simple, business, artistic, fun, specialty (for use by future versions of Sandvox)
- contributor
- author(s) of design; this is shown with the design in the program
- url
- home page of design’s contributor; clicking on link will go to this page.
- comments
- Additional information about the design. (Be careful about keeping this text as valid XML so that the file stays valid!)
- CalloutBorderable
- true or false, whether callout pagelets can have a border attribute set. Set this to false if your design doesn’t have any differing look between bordered and non-bordered pagelets in the callout.
- SidebarBorderable
- like CalloutBorderable, for the sidebar.
- KTIgnoredResources
- An array of paths (within the bundle) of any resource files that should not be published. By default Sandvox ignores files named "thumbnail.png" and "placeholder."
- KTMenusUseNonBreakingSpaces
- By default Sandvox converts spaces in Site Menu items to non-breaking spaces. This ensures that long titles are not split over 2 lines. However, in some designs you may wish to keep the standard spaces. If so, include this key in your Info.plist file with a value of NO.
- KSMinimumAppVersion
- The oldest version of Sandvox this design can be used with.
- imageReplacement
- a dictionary indicating what elements can be replaced, and what Quartz Composer file should be used. See “Header Textual Images” section.
- bannerName
- file name of banner (see section below)
- ATSApplicationFontsPath
- Name of font file in bundle, or name of folder containing fonts. Required for Sandvox to load any embedded fonts. Documented here.
- ParentBundleIdentifier
- If you have a group of designs, with multiple variations (color scheme, width, etc.) please come up with a single identifier that all of the variations share. This way, in a future version of Sandvox, we can recognize that the separate design packages all belong to the same "family" and can be grouped together in a main choice.
- MainColor
- If your design is part of a group of designs, please specify a hex string like #FF9999 what the main distinguishing color of the scheme is. That way our new version of Sandvox can show what the various color choices are at a glance. For particularly dark colors, you may want to cheat a bit and use a slightly lighter color; the swatches will be shown against a background of approximately #333333 so a dark gray swatch might not show up.
- hasLocalFonts
- If your design does image textual replacement, and you have included a non-standard font in the design package (that you have the rights to distribute), setting this to true will cause the font to be loaded by Sandvox.
- viewport
- This is to provide the best experience when viewing a website with a mobile device such as the iPhone. The default value is 771, which is the standard minimum size for standard sandvox designs. If your design has enough padding on the left and right that this can be an even smaller number, please specify that so that the website won't waste valuable screen space on the iphone by showing borders on the left and right sides. Conversely, if you have a wide design, you should specify a larger value here.
- bannerCSSSelector
- See the section below.
- bannerWidth
- Width of banner. If unspecified it will be 800 pixels.
- bannerHeight
- Height of banner. If unspecified it will be 200 pixels.
Banners
A banner is an image (generally shown along the top of the page) that is part of your design but can be replaced by the user using the inspector. Several of the built-in designs have settable banners.
Some designs may want to always have a banner (providing a default image); others may want to initially have no banner showing, and insert the banner image into the flow if there is a custom banner image specified. (using the CSS selector tt>has-custom-banner</tt> to reserve space for it.)
To allow users to customize the banner in your design, you just have to supply the appropriate CSS selector in your Design's Info.plist file. For example:
<key>bannerCSSSelector</key> <string>#page-top</string>
If the user does then set a custom banner, the above code would cause Sandvox to generate this CSS, thereby overriding the design default:
#page-top
{
background: url(path-to-custom-banner.jpeg);
}
You can also adjust other features of the design if the user has chosen a custom banner by using the CSS selectors has-custom-banner and no-custom-banner.
Sizing
Clearly, the user may well select a banner image that is of a different size to the space available. Thus, Sandvox also needs to know the dimensions of your banner image. The preferred method is to use Sandvox's support for customizing media sizes.
Header Textual Images
Because browsers may not have very good fonts installed, and as a way to foster creativity, Sandvox can generate lovely textual images out of headline elements. Text is converted to an image by passing it through a Quartz Composer file that is specified in the design; it is then included in the website and replaced for the actual text using revised Phark image replacement. (This CSS is generated by Sandvox; the designer does not need build any of this into the CSS.)
Note: Your CSS will need to use image replacement on a few specific Graphical Navigation elements. Though it's the same image replacement technique, this is distinct from Header Textual Images.
The hooks we support for image replacement are as follows.
| Code | CSS Selector Equivalent | Description |
|---|---|---|
| mc | #sitemenu li.currentPage span | Current page in site menu |
| m | #sitemenu li span | Other page in site menu |
| h1h | .home-page h1 | Site title for the Home Page |
| h1 | h1 | Site title on other pages |
| h2 | h2 | Title of page |
| h3 | .article h3 | Heading of an index’s link to another page |
| h4s | #sidebar h4 | Title of a sidebar pagelet |
| h4c | .callout h4 | Title of a pagelet attached to an callout |
You can specify any and all of the above selectors in your Info.plist file under the key of “image replacement”. (See some existing Info.plist files for an example.) Please note that, unlike with CSS, you must explicitly specify an entry in Info.plist for each type of text that you want replaced; if you specify a replacement for #sitemenu li but not #sitemenu li.currentPage, you will see a Header Textual Image on all links in the site menu except for the current page.
The Quartz Composer files are generally simple files since they are only rendering a still image. The files should be configured to have a published “String” and “Size” inputs and a published “Image” output. "String" is for the string (not rich text or HTML); "Size" is a value from 0.0 to 1.0 (default value:0.5) that is some adjustment on the size which allows the user to tweak the size to better fit or better word-wrap their title text. Generally, the top level of the file is a “Render in Image” patch with specific image dimensions set which correspond to the area reserved on the web page for the image.
You should match the font, size, and color as closely as possible in your CSS for each element that is to be replaced; that will make it optimal if image replacement is turned off or we are in "editing" mode. Also, if you specify the font-size and width and height of the block in pixels, it will be easiest to drop in the image of the right dimensions.
Note: any element that is getting replaced will be marked as class=”replaced” in the HTML. This will allow your style sheet to provide a reasonable fallback font and size for non-replaced text, and then specify the actual font and size to match the replaced font, so that it matches the rendered text more closely.
Element Specification
Please download the PDF document showing the hierarchy. (Not embedded in this wiki due to formatting constraints; if we can figure out how to do a table with indentation, it might be worth moving to the wiki.)
RECENT UPDATES
(Not reflected in the PDF or this diagram)
span#logo-container contains img#logo or a.imageLink > img#logo.
div.sitemenu > div.sitemenu-content > ul > > li, with these possible classes:
- i1, i2, i3, etc.
- e or o
- last
- currentPage [if this page is the currently chosen page]
- currentParent [if this page is part of the chosen section]
Within the site menu li, you have a > text, or just text
div#page-content has these classes: has-photo-navigation or has-text-navigation or no-navigation depending on what kind of navigation arrows there are.
For navigation arrows, there is a div of class collection-navigation and either photo-navigation or text-navigation. Within that div, there are divs for each navigation element: previous-page, next-page, collection-index. For photo-navigation, there are always all three, and there is an anchor if there is a page to link to. For text, the div for previous or next does not appear if it is not appropriate.
On pages that can have a callout (e.g. text page, you have div.article with a class of has-callout or no-callout (depending on whether there are callouts there). Other kinds of pages (like movie pages) have div.no-callouts around the content. (Apologies for this being confusing -- it's for backward compatibility.) You may want to clear floats in .article-info to properly clear floated images in the article.
Inside div#page-bottom, as of Sandvox 1.6, we now generate div#page-bottom-contents. Inside that, there may be paragraphs or divs, or neither!
Photo Grid
One of the index types built into Sandvox is the photo grid. The aim is to lay out the pages' thumbnails in a neat grid.
HTML
For each item in the grid, the following HTML is generated:
<div class="gridItem">
<a class="imageLink"><img /></a>
CSS
The photo grid should have fixed-width, left-floated .gridItem divs to allow an arbitrary "photo album" of image thumbnails to display nicely with floating.
In order to make the thumbnail images be nicely centered vertically and horizontally, you may want to employ some CSS similar to the following. It's a bit of a trick, which unfortunately fails in some browser engines. Please use it anyway for the benefit of modern browsers. Note the top: and bottom: declarations.
.gridItem img {
margin: auto;
display:block;
position: absolute;
top: 0;
bottom: 45px;
right: 0;
left: 0;
}
Custom Media Sizes
Sandvox sites can make use of images in a number of locations. Sandvox provides sensible defaults for the sizes of these images, but if your design is unusually sized, you can customize them.
To customize a media size:
- Control-click the Sandvox application and select "Show Package Contents."
- In the Resources folder, locate the KTScaledImageTypes.plist file and open it. This is the master list of all the media sizes Sandvox knows about.
- Open up your design's Info.plist and (if it doesn't exist yet) create a new dictionary for the key KTScaledImageTypes.
- In that dictionary, create a copy of the original entry in KTScaledImageTypes.plist.
So for example, the most common use is to create a custom banner size:
<key>KTScaledImageTypes</key>
<dict>
<key>bannerImage</key>
<dict>
<key>alignment</key>
<string>top</string>
<key>behavior</key>
<string>CropToRect</string>
<key>maxHeight</key>
<integer>265</integer>
<key>maxWidth</key>
<integer>800</integer>
</dict>
</dict>
Navigation Arrows
The user can enable navigation arrows for the entirety of any collection, regardless of content. Furthermore, there are both graphical and textual styles available; which is used is automatically determined by the index in use.
HTML
The HTML Sandvox generates differs slightly between graphical and textual navigation arrows. Of particular note is reversed order of the "next page" and "list" links.
Textual Navigation
<div class="collection-navigation text-navigation">
<div class="previous-page"><a><span>«</span> Page Title</a></div>
<div class="collection-index"><a>List</a></div>
<div class="next-page"><a>Page Title <span>»</span></a></div>
</div>
Sandvox will automatically generate the « & » characters for you; the <span> can be used for styling.
Graphical Navigation
<div class="collection-navigation photo-navigation">
<div id="previous-photo" class="previous-page"><a>Previous</a></div>
<div id="next-photo" class="next-page"><a>Next</a></div>
<div id="photo-index" class="collection-index"><a>List</a></div>
</div>
These should be replaced with Previous, Next, and List graphical buttons. Use revised phark replacement: text-indent: -5000px; background: url(...); height: ...
Important: The div ids "next-photo" etc. are deprecated as of Sandvox 1.5 and remain only for backward compatibility.
Continue Reading Link
If the user chooses to truncate summaries then Sandvox will also display a link at the end of the summary that links to the full article. The HTML is generated at the top of the .article-info div as follows:
<div class="continue-reading-link">
<a>Continue reading…</a>
</div>
It is important to note that the anchor tag is not generated while previewing in Sandvox in order to allow editing. So, please do not rely on it for styling.
CSS
You can use CSS to position the navigation controls pretty much anywhere you like.
Please be careful about vertical spacing for the header, page title, and controls; it would be annoying for somebody to have to scroll down, down, down just to see the page's content. So, it might make sense to put the navigation controls inline next to the title, for example.
Default Styling
To make your life easier, Sandvox provides some sensible default formatting of textual navigation:
div.text-navigation { text-align:center; margin-bottom:1em;}
div.text-navigation div { display:inline; margin:0px 0.5em; }
Navigation-Dependent Layout
There is also a CSS selector higher up the tree to note if a page contains navigation arrows within. This is useful for affecting the layout of other page elements in the presence of navigation. For example, some designs place graphical navigation arrows beside the page title, so this can be used to make the title narrower at the same time. The selector will be one of:
no-navigationhas-text-navigationhas-photo-navigation
Minimal Standards
Most designs will want to take advantage of a number of selectors to make the design fun and beautiful. But a design should do a few things, at the minimum:
- Within a block of text, inline images of class “narrow” and of class “article-thumbnail” should be floated to economize space.
- We have explicit "clear" divs placed after main content items to deal with clearing after floated items. The "Simple Clearing of Floats" technique, where you put overflow:auto in the container that you want floated items to clear, works for the most part, but it may give you problems where it creates scrollbars where you don't want them. So to be safe, we have "clear" to take care of things. There could conceivably be floats on pagelets, so using overflow:hidden or overflow:auto make sense here.
- To keep font sizes consistent, we are asking that all designs specify, in the body, font-size: 76%; as suggested in "Sane CSS Sizes". This allows us to specify fonts in terms of ems, not pixels or points. <p> text in the main body should be at 1 em. Please avoid absolute font sizes, and make sure not to allow for tiny fonts.
- A few of our indexes (simple listing, photo grids) use
<h3>for what really should display at a normal size and weight. They are marked as<h3>for semantic consistency, but you will probably want to make sure that the display is appropriate. - It would be good to restrict text width to a reasonable width for readability, e.g. max-width: 50em;
- To keep sidebars and the main-content from getting too wide in case of long words, use word-wrap: break-word; (which is not a true standard, but works widely) along with overflow:hidden.
- To deal with PNG files and transparency issues in IE, you may want to make use of some IE-specific fixes for this.
- Please make sure that your design will handle titles (such as in the site menu and pagelets) that wrap to more than one line. We want to avoid a title truncating or overflowing ungracefully.
- When saving graphic files along with the design, try to choose an optimal format (e.g. PNG over JPEG if the size is reasonable, to avoid compression artifacts, GIF over PNG to get a bit of transparency without being IE-incompatible) and if you are saving from Photoshop, don't include unnecessary metadata. You can make PNGs as small as possible by using PNGCrusher.
- Please avoid using selectors on 'div' and 'span' without class or ID specifiers.
- anchors will have the class "imageLink" when they are surrounding images; this will allow you to have a different look (e.g. no underlines on images)
Making Use of Third-Party Content
If you are distributing a design, it is your responsibility to make sure you have clearance for any content you use.
You can document the sources and permissions in the comments section of the "License.rtf" file that goes with a design.
Installation of Designs in Sandvox
Your custom Sandvox designs can be put into any of:
- home folder → Library → Application Support → Sandvox → Designs
- home folder → Library → Application Support → Sandvox
- Library → Application Support → Sandvox → Designs
- Library → Application Support → Sandvox
You will need to re-launch Sandvox to have it notice any changes to your installed designs.
