-
Notifications
You must be signed in to change notification settings - Fork 6
Towards a style guide
Interface Style Guide
This guide defines the styles, icons, fonts and general UI control that should be used for any user interface we code. This creates a consistent look and feel - and saves time.
secondly, i would say we should define our style guide in terms of the css classes to use and for those that need to extend bootstrap, our style guide should basically be a reference to the classes in our own custom chaise.css (or whatever).
and thirdly, then we need to pick a set of non-bootstrap 3rd party ui components, such as which dropdown control to use (e.g., angular-ui-selector or whatever its called).
-
Interface Style Guide
- Doctype
- Framework
- Custom Styles/css
- Custom Markdown Styles
- Normalize.css
- Basic example
- Layout
- Typography
- Tables
- Style
- Components
- Patterns
- Usability and Accessibility
Include the HTML5 doctype at the beginning of all your projects.
<!DOCTYPE html>
<html lang="en">
...
</html>
The underlying framework for our interfaces is Bootstrap. We are currently using version 3.
To add Bootstrap to your project:
-
Click the "Download Bootstrap button" on the Getting Started page and unzip the download.
-
Add the folders ("css", "fonts" and "js") to your project (usually either at the root directory of your web files or under an "assets" directory there).
-
Update the
<head>
section to link to the stylesheet:~~~~ <link href="css/bootstrap.min.css" rel="stylesheet"> ~~~~
-
Update the bottom of your HTML code - right before the closing
</body>
tag - to import the Bootstrap javascript as well as jQuery:<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> <script src="js/bootstrap.min.js"></script>~~~~ <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
~~~~
Note, if you prefer, you can download jQuery, add it to your web files and link to that.
The style of the Chaise
application can be overridden by providing a custom CSS document that is loaded after the rest of the styles. See the above link for more information.
For improved cross-browser rendering, we use Normalize.css, a project by Nicolas Gallagher and Jonathan Neal.
The following is a basic example of an HTML page using Bootstrap (without a grid or any content yet):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
<title>Bootstrap 101 Template</title>
<!-- Bootstrap -->
<link href="css/bootstrap.min.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<h1>Hello, world!</h1>
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<!-- Include all compiled plugins (below), or include individual files as needed -->
<script src="js/bootstrap.min.js"></script>
</body>
</html>
Bootstrap uses two kinds of containing elements - one for fixed width and one for full-width.
In general, we use the full-width "container-fluid" tag so that the app takes the full width of the browser window:
<div class="container-fluid">
...
</div>
Container tags contain rows (divs using the row
class) and then the appropriate column classes.
In general, a row is made up of 12 possible columns. To make your grid, you 'chunk' the columns together to get the widths you want.
Further, the column classes use size terms to indicate breakpoints (points where columns will stack vertically instead of going all the way across horizontally) for different size viewports (phone, tablet, laptop, etc). There will be more discussion in the "Responsive" section but for now we'll use the medium version for examples in this document (col-md-#).
For example:
- If you you want two columns of equal width, you would use two divs with the class
col-md-6
- For a left sidebar and a larger content area, you could use
col-md-4
andcol-md-8
Note: For one column, no column classes are needed, just the 'row' div. However, if you run into layout issues, use the col-*-12
Here's the bootstrap HTML tags for a full-width app with a left sidebar and main content area:
...
<div class="container-fluid">
<div class="row">
<div class="col-md-4">
Sidebar content
</div>
<div class="col-md-8">
Main content
</div>
</div>
</div>
...
Note that rows/columns can be nested as needed.
Our preferred font is "Helvetica Neue".
Add it to the font-family
CSS rule for the body
tag as follows to allow graceful degradation if that font is not available:
body {
font-family: "Helvetica Neue",Helvetica,Arial,sans-serif;
}
Use <h1>
through <h6>
in a hierarchical manner as appropriate. You can also include a secondary header within the heading tags using the <small>
tag:
<h1>h1. Bootstrap heading <small>Secondary text</small></h1>
<h2>h2. Bootstrap heading <small>Secondary text</small></h2>
Bootstrap uses a default font-size of 14px for the body copy but better practice is using 16px for improved readability. Add the following rule to your custom stylesheet:
body {
font-size: 16px;
}
Make a paragraph larger (good for opening paragraphs on a text-heavy page) by adding the lead
class to a paragraph tag:
<p class="lead">...</p>
Highlight:
You can use the mark tag to <mark>highlight</mark> text.
Strikethrough:
<del>This line of text is meant to be treated as deleted text.</del>
Underline:
<u>This line of text will render as underlined</u>
Small text:
<small>This line of text is meant to be treated as fine print.</small>
Bold:
<strong>rendered as bold text</strong>
Italics/emphasized:
<em>rendered as italicized text</em>
<p class="text-left">Left aligned text.</p>
<p class="text-center">Center aligned text.</p>
<p class="text-right">Right aligned text.</p>
<p class="text-justify">Justified text.</p>
<p class="text-nowrap">No wrap text.</p>
Inline code:
For example, <code><section></code> should be wrapped as inline.
User input:
To switch directories, type <kbd>cd</kbd> followed by the name of the directory.<br>
To edit settings, press <kbd><kbd>ctrl</kbd> + <kbd>,</kbd></kbd>
Code block:
<pre><p>Sample text here...</p></pre>
Variables:
<var>y</var> = <var>m</var><var>x</var> + <var>b</var>
Use <table>
HTML tags as usual but include the following classes to automatically style them.
At the very minimum, use the table
class for a clean look without borders on all cells:
<table class="table">
...
</table>
For long tables that may be difficult to parse, add the .table-striped
class to shade every other row:
<table class="table table-striped">
...
</table>
For long tables, you can also cut the cell padding in half with the .table-compact
class.
Also use:
-
.table-bordered
to add lines to all cells - for data tables -
.table-hover
so that rows are shaded when the mouse hovers over them (another good trick for long tables) - If you wrap the table in a div with the
.table-responsive
class, it will allow tables to scroll horizontally on mobile devices.
<div class="table-responsive">
<table class="table">
...
</table>
</div>
For the default ("vanilla") application, we keep colors as neutral as possible. The default colors for the current chaise application are:
-
The navbar is very dark gray (#4D4D4D), as set in chaise's custom css file, appheader.css:
.navbar-inverse .navbar-collapse, .navbar-inverse .navbar-form { border-color: #4D4D4D; }
-
Branding text (Chaise) is white, also set in appheader.css:
.navbar-inverse .navbar-brand { color: #FFFFFF; }
-
Links and other elements use the default Bootstrap styles
Bootstrap includes icons (glyphicons), which is a decent collection of commonly used icons. You can find the available options and details on how to use them here.
These are font icons, which means you can use CSS to change their color, size, etc.
Here's the cheatsheet for icons used in chaise. It basically uses specific classes on an empty code or i tag:
question mark (Help): <span class="glyphicon glyphicon-question-sign"></span>
bookmark (Permalink): <span class="glyphicon glyphicon-bookmark"></span>
left arrow (Go Back): <span class="glyphicon glyphicon-chevron-left"></span>
magnifying glass (Search): <span class="glyphicon glyphicon-search"></span>
You can also adjust the size of a glyphicon TBD
Inconsistency alert - Material Design:
We sometimes use Material Design icons if we can't find what we want with glyphicons. These use i tags and the prefix "md".
You can also adjust the size using classes "md-lg", ""
red circle with x (Close filter): <i class="md-cancel md-lg"></i>
Difference between toolbar and app bar?
?
Hacked from http://codepen.io/zavoloklom/pen/dIgco and then integrated into Angular. The HTML and CSS could use some cleaning up.
The basic idea for the sidebar is that it's a fixed div that was originally designed to slide in and out. It always looks open, but the additional stages (ie, when you click on a top-level choice and see the options) are actually another sidebar overlaying the first one. We decided not to slide them in and out and the "swoop" aspect is irrelevent now.
There are actually 4 sidebars (in
tags) that represent:- "sidebar" - the top-level facets
- "morefilters" - shows all available facets
- "editfilter" - shows options of a facet that may be selected/de-selected
- "collectionsTree" - shows available Chaise collections
Hovering shows gray background
Components for selecting options include:
- Checkboxes (most common)
- Slider (used for number/date ranges) - built on rzslider, a Slider directive for AngularJS: https://github.com/angular-slider/angularjs-slider
- Text field (searching attributes)
Responsive design basically creates a design that displays appropriately and is functional on various sizes, layouts and resolutions. The Bootstrap framework is inherently responsive - but you do need to consider the type of size classes you use (col-sm-, col-md-, col-lg, will collapse at different breakpoints.) See the Grid section of the Bootstrap site for more details.
For FaceBase chaise, we also needed to add a third-party style for extra wide columns so the layout used more real estate on larger, high resolution displays. At the end of the FB custom.css file, we appended the XL classes from https://github.com/marcvannieuwenhuijzen/BootstrapXL/blob/master/BootstrapXL.css within a media query that affects displays of 1600px and greater.
@media (min-width: 1600px) {
.container {
width: 1570px;
}
<add -xl- classes >
}
We also use some javascript to change which XL class is being used for certain breakpoints as the defaults weren't quite working for the layout:
<script>
$(function(){
var content = $("#main-content");
$(window).resize(function() {
checkWidth(content);
});
checkWidth(content);
});
function checkWidth(content){
var viewportWidth = $(window).width();
if(viewportWidth >= 1696){
if( content.hasClass("col-xl-9") ){
content.removeClass("col-xl-9").addClass("col-xl-10");
}
}else{
if( content.hasClass("col-xl-10")){
content.removeClass("col-xl-10").addClass("col-xl-9");
}
}
}
</script>
The default breakpoints for Bootstrap 3 are:
/* Extra small devices (phones, less than 768px) */
/* No media query since this is the default in Bootstrap */
/* Small devices (tablets, 768px and up) */
@media (min-width: @screen-sm-min) { ... }
/* Medium devices (desktops, 992px and up) */
@media (min-width: @screen-md-min) { ... }
/* Large devices (large desktops, 1200px and up) */
@media (min-width: @screen-lg-min) { ... }
Buttons indicate a user can take an action and are made up of text, image or both with a background color appropriate to the app.
Terms buttons Chiclets
Describe each type and then how to choose
When to use Buttons
Typography (ie, capitalized or initial caps)
Accessibility - to ease reading: button height 27 px
Density - measurements between text and background: text size, button height, text left and right padding
Generic Dropdown
Segmented dropdown
Specs
Code
Exclusive selection
Multiple selection
Icon toggles
Specs
code
Editing value
Deleting
- ACLs In ERMrestJS and Chaise
- Facet Examples
- Facets JSON Structure
- Logging
- Model Annotation
- Model-based Logic and Heuristics
- Preformat Annotation Guide
- Export Annotation Guide
- Pseudo-Column Logic & Heuristics
- Table Alternatives
- Intro to Docker
- Chaise Dev Guide
- Dev Onboarding
- ERMrest 101
- ERMrest Howto
- ERMrestJS Dev Guide
- Extend Javascript Array
- Custom CSS guide
- Towards a style guide