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!
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.
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.
Scroll bars (overflow:scroll) within the page are generally discouraged, though there may be some designs for which this makes particular sense.
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.
Page Structure Definitions
The body of a page generated by Sandvox can have a class of allow-sidebar or no-sidebar. The former indicates whether the page can have a sidebar, even if empty; the latter means that there isn't room for a sidebar, usually because the contents are too wide (e.g. it contains a big photo.) The home page for a site is also given an additional class of home-page to allow for a different “look” on the home page, like a bigger header. 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. 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 (there is no h2 > a)
- 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.
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.
- IE 5, 5.2 (mac), 5.5, 6: Design should degrade gracefully, being useable if not optimal.
- NN/IE 4: Style sheet will be hidden from these browsers.
Testing Parameters
CSS should be valid; please use The W3's or WDG's validation service. (If you are doing non-standard but non-breaking things, like CSS 3.0 things that generate an error, that's OK.)
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.
Text should be of decent contrast and size; color palettes should be used that work with the color blind. You can use Vischeck to test colors.
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.
| z_HTMLPage_no_sidebar.html | A page with custom HTML, with no sidebar allocated |
| z_HTMLPage_sidebar.html | A custom HTML page, with a sidebar allocated |
| z_iframe.html | An iFrame page (containing the apple.com home page) |
| z_PhotoPage1.html | A photo page, first in a series with no “previous” button. |
| z_PhotoPage2.html | A photo page with both a “previous” and “next” button |
| z_PhotoPage3+GeneralIndex_.html | A photo page, last in a series with no “next” button. Also, a general index afterwards, and some really long elements to test overflows |
| z_PhotoPage_oneoff.html | A photo page, not part of a photo album, so there are no prev/next/list controls. |
| z_Text+Empty.html | An empty page; it should have some “main” area showing, at least on Safari (since our editing environment is essentially Safari) |
| z_Text+Home+Empty.html | Similar to above, but a home page |
| z_Text+Home+GeneralIndex_.html | A full text page, with callouts, lots of sidebar content, and a general index. |
| z_Text+ListingIndex_.html | A text page with a simple listing index |
| z_Text+PhotoIndex+Long_Stuff+Home.html | A page with a photo grid index; a lot of elements are longer than usual to test how the layout behaves on overflows |
| z_Text_Empty_Sidebar_No_Menu+Home.html | Text with embedded graphics (wide and narrow) and no sidebar contents. (There should still be room allocated for the sidebar, though perhaps not a background drawn.) |
| z_Text_Long_Sidebar_No_Menu+Home.html | Text with embedded graphics (wide and narrow), plus a very long sidebar. |
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.)
- 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.
- javascript.js (optional) if any javascript is used
- thumbnail.png
- 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.
- 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 should be incremented each time it is released to help prevent caching of old versions of the design.
- 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 differening 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.
- KTMinimumAppVersion
- 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)
Banners
New as of version 1.2 are settable banners. A banner is an image (generally shown along the top of the page), up to 800 pixels wide and up to 300 pixels tall, that are part of your design but can be replaced by the user using the inspector. Several of the built-in designs have settable banners.
The way you can make a design take advantage of this is to specify the info.plist, setting a property for bannerName, with the value being the file name of the initial image:
<key>bannerName</key> <string>Sky.jpeg</string>
Your design will make use of the image, but you should consider what will happen if there is an image specified that is larger or smaller than the one you provide. It should probably be cropped if it is too big, and probably not repeat if it is too small.
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 can use image replacement on a few specific elements such as #previous-photo, #next-photo, and #photo-list to replace text with images. This should be included in the CSS, as it is not associated with 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.
Fonts
Fonts to use for standard text
- Feel free to specify Mac-specific and/or PC-specific fonts as first choice, in case the browser has those fonts installed.
- As a first fallback, specify Standard Mac/Windows fonts:
- Arial
- Arial Black
- Comic Sans MS
- Courier New
- Georgia
- Helvetica
- Impact
- Times New Roman
- Times
- Trebuchet MS
- Verdana
- As a last resort (for Linux and older Windows systems), specify generic fallbacks like serif or sans-serif.
Fonts for Header Textual Images
The fonts that are already installed on Mac OS X Tiger are safe to use in your Quartz Composer files; you shouldn't bundle that font in the package. For third-party fonts, you can bundle the font in the design package and it will be opened. Of course you will need permission for redistribution of that font, which is usually harder to obtain than permission to simply use a font. (See the Font Sources section for sources of useable fonts.)
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.)
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:
- The sidebar (for “allow-sidebar” pages) should appear alongside the main contents. (If there are no contents in the sidebar, it is still probably a good idea to reserve the space as if there were, to keep pages consistent.)
- We want our pages to fit in an 800x600 screen as much as possible (meaning that your design should be no wider than 771 px allowing for scrollbars on an IE system). This means that you could have a two-column layout (floating the callout within the main area) with plenty of horizontal space, or a tighter three-column layout for sidebars (200px), main content (320px), and callouts (200px).
- Note: Even though many people have screens much wider than 800 pixels across, we take the position that it's better not to require that one have a wide screen to view a website. And when a user has multiple windows open on their screen, it's nice not to have to fill the screen with the browser window. (Further explanation and discussion can be found on this post on one our initial web designer's weblog.)
- 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.
- 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.
- On the Photo Page, please be careful about vertical spacing for the header, photo title, and previous/next/list controls. It would be annoying for somebody to have to scroll down, down, down just to see the whole photo. So it might make sense to put the navigation controls inline next to the title, for example.
- 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 wihout 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.
Optional opportunities for nice "goodies" to make your design really shine.
Please take advantage of these as much as possible!
- "Bullet" character that your CSS can incorporate into <ul> elements.
- Underline graphics
- Previous, Next, List buttons to replace #previous-photo, #next-photo, and #photo-list (Use revised phark replacement: text-indent: -5000px; background: url(...); height: ...)
- Placeholder photograph (640 pixels wide or tall) that's consistent with the theme of the site.
- Varying graphics based on even/odd/numbered selectors in repeated elements (e.g. "e","o","i1","i2"...)
- Bordered vs. Non-bordered pagelets. (The option for a border is specific on a per-pagelet basis in Sandvox.) By default, a pagelet is “bordered” unless the web page creator turns it off.
- Take advantage of the “top” and “bottom” divs surrounding major areas for attaching graphics
- Consider having your design allow use of an 800x200 image as a background for the header area. This would allow for swapping in of various standard-sized "header images" such as those from Free Web Page Headers.
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.
Images
Images used in designs you distribute need to be created by the designer, or need to be explicitly known to be OK for redistribution (since you are not just using the stock image, but are then distributing to others). This means no trademarked images (like company logos). For content by others, there a number of approaches:
- Images with an expired copyright, any images before 1923
- Stock photos from sites with appropriate restrictions. (Many stock photo sites are not appropriate; please be careful.)
- Images from government entities
Here are some stock photo sites with good potential:
- Stock Exchange
- Image * After
- PD Photo
- ShutterStock
- flickr
- Geek Philosopher
- For more possible sources, see Wikipedia:Public domain image resources
- A source of public domain vector art is Open Clip Art Library
Font Sources
Fonts for Header Textual Images need to be redistributable if you (or Karelia) is to make your design available to others. Here are some potential sources of fonts; you will need to secure permission and possibly pay a licensing fee to the creator of the font if you are going to be distributing your design.
- SelfBuild Type Foundry
- Pizzadude Fonts
- Tepid Monkey Fonts
- Larabie Fonts
- Iconian Fonts
- Paul Lloyd Fonts
- Fonthead Design
- Ænigma Fonts
- Fenotype Fonts
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.
