diff --git a/source/code-standards/accessibility.slim b/source/code-standards/accessibility.slim index 3f11432..31e756d 100644 --- a/source/code-standards/accessibility.slim +++ b/source/code-standards/accessibility.slim @@ -4,9 +4,19 @@ id: 'code-standards' --- h1 Accessibility -p The accessibility of a web site's content, including its source order without any applied CSS or JavaScript, must be taken into account. Web Platform's Accessibility Basics article is a good introduction to accessibility for those unfamiliar with them. During development, websites should be checked with a screen reader to ensure they are easy to use. All developers using computers running OS X or have access to iOS device have access to VoiceOver as it is installed on both operating systems. Another popular screen reading application, especially for Windows machines, is JAWS, although that is proprietary software and fairly expensive at that. A final resource for testing accessibility is to access a website using the Lynx Browser. As a text-only browser, it will strip out styling and interactions, leaving raw content in the order it is presented. As an added bonus, this is also a good analogue to how crawlers and search engines view a given page. +p The accessibility of a web site's content, including its source order without any applied CSS or JavaScript, must be taken into account. + +p Web Platform's Accessibility Basics article is a good introduction to accessibility for those unfamiliar with them. During development, websites should be checked with a screen reader to ensure they are easy to use. + +p All developers using computers running OS X or those with access to an iOS device have access to VoiceOver as it is installed on both Apple operating systems. Another popular screen reading application, especially for Windows machines, is JAWS, although that is proprietary software and fairly expensive at that. + +p A final resource for testing accessibility is to access a website using the Lynx Browser. As a text-only browser, it will strip out styling and interactions, leaving only raw content in the order it is presented. As an added bonus, this is also a good analogue to how crawlers and search engines typically view a given page. h2 RDFa -p Resource Description Framework in Attributes, more commonly known as RDFa, is an extension to HTML5 allowing for robust markup of objects in HTML, including items such as people, places, events, recipes, and reviews. They are used to precisely describe these objects, mostly to machines, by attaching metadata about each object as attributes. The most common immediate use for this metadata is in use by search engines and social networks, amongst others, allowing their crawlers to understand exactly what is on any given page. This, in turn, allows them to provide more accurate and higher ranked information about each piece of content. A useful side effect of marking up all content with RDFa information, especially when using a Content Management System (CMS), is that it ensures that all of the relevant metadata is readily available in individual chunks and thus becomes fine-grain points of control for each piece of content that can be syndicated outside of pure markup. +p Resource Description Framework in Attributes, more commonly known as RDFa, is an extension to HTML5 allowing for robust markup of objects in HTML, including items such as people, places, events, recipes, and reviews. + +p They are used to precisely describe these objects, mostly to machines, by attaching metadata about each object as attributes. The most common immediate use for this metadata is in use by search engines and social networks, amongst others, allowing their crawlers to understand exactly what is on any given page. + +p This, in turn, allows them to provide more accurate and higher ranked information about each piece of content. A useful side effect of marking up all content with RDFa information, especially when using a Content Management System (CMS), is that it ensures that all of the relevant metadata is readily available in individual chunks. These chunks become fine-grain points of control for each piece of content that can be syndicated outside of pure markup. diff --git a/source/code-standards/css.html.slim b/source/code-standards/css.html.slim index 92a1f05..29c5d0b 100644 --- a/source/code-standards/css.html.slim +++ b/source/code-standards/css.html.slim @@ -133,7 +133,7 @@ section.styleguide-module-details section.styleguide-module-details h2 Reset - p A CSS reset is designed to reset various element styles to a baseline and reduce browser inconsistencies and allow. For Ally we will be using a modified version of a CSS reset based on the one used in HTML5 Boilerplate. + p A CSS reset is designed to reset various element styles to a baseline and reduce browser inconsistencies and allow. We will be using a modified version of a CSS reset based on the one used in HTML5 Boilerplate. h2 Understanding Specificity p There are many selectors to take into account when calculating specificity, but for our purposes we're going to keep things simple. If you're interested in learning more about calculating specificity for conflicting rules read up on Specificity by Patrick Griffiths or a Star Wars spin on specificity by Andy Clarke. @@ -149,6 +149,14 @@ section.styleguide-module-details li ID Selector #{inline_code("#id {color: #ccc}")} li ID + Type Selector #{inline_code("#id p {color: #efefef;}")} + p It is best to keep specificity low and styles reusable. ID selectors are not recommended. + + p For more information on low-specificity strategies read the following: + + ul + li Strategies for Keeping Specificity Low by Chris Coyier + li The Specificity Graph by Harry Roberts + section.styleguide-module-details h2 Guidelines for Coding CSS p There are some very basic guidelines we follow when it comes to specificity and avoiding or overriding conflicting CSS rules. @@ -167,6 +175,7 @@ section.styleguide-module-details ul li being overly specific prevents you from being able to reuse CSS rules elsewhere li the more specific your selectors are, the larger and more complex your stylesheet will become + li avoid ID selectors li it's easier to be less specific from the start while adding specific rules as situations come up than it is to refactor later p Don't write something like this: diff --git a/source/code-standards/html.html.slim b/source/code-standards/html.html.slim index ca73660..eee8c31 100644 --- a/source/code-standards/html.html.slim +++ b/source/code-standards/html.html.slim @@ -5,6 +5,8 @@ id: 'code-standards' h1 HTML p Developers are strongly encouraged to use bits of pieces of HTML5 but should ensure that older browsers degrade gracefully. See our official browser support. +p To ensure old browsers properly serve HTML5 content, use html5shiv. + section.styleguide-module-details h2 Doctype p Always use a doctype. Using a doctype forces a browser to render a page in "Standards Mode". To learn more about the history of the Doctype and different rendering modes you should read the work of Henri Sivonen, Activating Browser Modes with Doctype. HTML5 keeps the doctype nice and simple. Using the HTML5 doctype reduces the amount of code needed by dropping attributes. As another perk, there is no longer a need to use cdata to escape inline JavaScipt (no longer required to meet the XML strictness in XHTML). @@ -83,6 +85,8 @@ section.styleguide-module-details .styleguide-code = code_example( "/code-standards/code-examples/form" , "html") + p In the case of boolean attributes like controls, required, selected, do not add values. + section.styleguide-module-details h2 Validation p HTML pages should be verified against the W3C validator. Validation isn't indicative of concise, beautiful, semantic markup but it does help ensure the markup is at least well formed. @@ -98,7 +102,7 @@ section.styleguide-module-details section.styleguide-module-details h2 Template - p The following snipped can be used to create a new HTML5 document. English is specified by default and doesn't contain the directional indicator #{inline_code('dir=ltr')} because it's the default. + p The following snippet can be used to create a new HTML5 document. English is specified by default and doesn't contain the directional indicator #{inline_code('dir=ltr')} because it's the default. .styleguide-code = code_example( "/code-standards/code-examples/html-template" , "html") diff --git a/source/code-standards/modules.html.slim b/source/code-standards/modules.html.slim index 04eb1b9..5e20d6e 100644 --- a/source/code-standards/modules.html.slim +++ b/source/code-standards/modules.html.slim @@ -4,31 +4,71 @@ id: 'code-standards' --- h1 Modules -p Components are the primary building block of any interface. They are the bits and bobs that combine to form a cohesive user interface; from menus to messages, pagers to pictures, and everything else in between. Components should be written to be able to be dropped in to any position in a layout. The way to accomplish this is to build components using eq.js. This will allow a component and its elements to respond appropriately regardless of where they land in a given document flow. Components should be simple layouts to position elements inside of themselves either through extends or by constructing a component with elements placed inside an internal layout (decide before starting a project and carry that decision through the lifespan of the project) if the layout is not component specific. They may choose to control their overall sizing and one-off sizing and positioning, but those choices should be relative the container they are dropped in to and not layout or position specific. +p Components are the primary building block of any interface. They are the bits and bobs that combine to form a cohesive user interface; from menus to messages, pagers to pictures, and everything else in between. + +p Components should be written to be able to be dropped in to any position in a layout. The way to accomplish this is to build components using eq.js. This will allow a component and its elements to respond appropriately regardless of where they land in a given document flow. + +p Components should be simple layouts to position elements inside of themselves either through extends or by constructing a component with elements placed inside an internal layout (decide before starting a project and carry that decision through the lifespan of the project) if the layout is not component specific. + +p They may choose to control their overall sizing and one-off sizing and positioning, but those choices should be relative to the container they are dropped into and not layout or position specific. h3 Base Module -p Each project should contain a base component which contains base styling for raw tags (h2, blockquote, p, etc…). The base component's elements should be named after the tag they style, so basic styling for h2 would provide both an extendable and full class .base--h2. To apply these styles, create a styled aspect, providing a .base--STYLED class. This aspect should have raw elements styled without classes, allowing it to be dropped into any section of a site and provide basic styling. Additional aspects can be created to create different base stylings. +p Each project should contain a base component which contains base styling for raw tags (h2, blockquote, p, etc…). + +p The base component's elements should be named after the tag they style, so basic styling for h2 would provide both an extendable and full class .base--h2. + +p To apply these styles, create a styled aspect, providing a .base--STYLED class. This aspect should have raw elements styled without classes, allowing it to be dropped into any section of a site and provide basic styling. Additional aspects can be created to create different base stylings. h3 Layouts -p Layouts are the structure of an interface. Providing structure to pages and components, layouts are responsible for sizing and positioning of their elements. There are two kinds of layouts, simple and complex. The distinguishing factor between simple and complex layouts is that complex layouts adapt and change their sizing and positioning based on media queries whereas simple layouts do not. Complex layouts are generally used for laying out pages and regions within pages, with simple layouts being used for laying out sub-sections inside complex layouts and providing common layouts for components. While simple layouts may be used within components or even within other simple or complex layouts, complex layouts should never be used within one another. +p Layouts are the structure of an interface. Providing structure to pages and components, layouts are responsible for sizing and positioning of their elements. + +p There are two kinds of layouts, simple and complex. The distinguishing factor between simple and complex layouts is that complex layouts adapt and change their sizing and positioning based on media queries whereas simple layouts do not. + +p Complex layouts are generally used for laying out pages and regions within pages, with simple layouts being used for laying out sub-sections inside complex layouts and providing common layouts for components. + +p While simple layouts may be used within components or even within other simple or complex layouts, complex layouts should never be used within one another. h3 Aspects -p Aspects are a specific implementation of a component or layout. Components and layouts always should have an aspect when used to determine what kind of implementation is being worked with. Aspects can be used as a way to pivot styling of elements if need be or to control implementation-specific styling, such as changing colors in a message component or determining exact sizing of a body element of a layout. It is preferable to use aspects as pivot points rather than to create unique classes for each element as it allows for the reuse of identical elements regardless of the aspect of a component or layout they are used in. +p Aspects are a specific implementation of a component or layout. + +p Components and layouts should always have an aspect when used to determine what kind of implementation is being worked with. Aspects can be used as a way to pivot styling of elements if need be or to control implementation-specific styling, such as changing colors in a message component or determining exact sizing of a body element of a layout. + +p It is preferable to use aspects as pivot points rather than to create unique classes for each element as it allows for the reuse of identical elements regardless of the aspect of a component or layout they are used in. h3 Elements -p Elements are the individual pieces that make up a component or layout, each being component or layout specific. Think of them as individual HTML elements (h2, blockquote, p, etc…) in components and regions and items in layouts. When styling an item inside components or layouts, it is strongly discouraged to use raw tag selectors and instead use element classes for each. This is to avoid any potential conflicts, such as would happen if there would be a pager component inside of a slider component (.slider li and .pager li). The only exception to this rule is for the base component. +p Elements are the individual pieces that make up a component or layout, each being component or layout specific. + +p Think of them as individual HTML elements (h2, blockquote, p, etc…) in components and regions and items in layouts. + +p When styling an item inside components or layouts, using raw tag selectors is strongly discouraged. + +p Instead, use element classes for each item. This is to avoid any potential conflicts, such as what would happen if there were a pager component inside of a slider component (.slider li and .pager li). + +p The only exception to this rule is for the base component. h3 States -p States provide a way to alter how a component, layout, element, or aspect behaves. Common states include active, open, and closed. Because states live in the in-between world of JavaScript and CSS, often changing with interactions from the user, states are controlled by data attributes and get attached to the components, layouts, elements, or aspects they are modifying. This provides easy to maintain states on a per-object basis without needing per-object states. +p States provide a way to alter how a component, layout, element, or aspect behaves. Common states include active, open, and closed. + +p Because states live in the in-between world of JavaScript and CSS, often changing with interactions from the user, states are controlled by data attributes and get attached to the components, layouts, elements, or aspects they are modifying. + +p This provides easy to maintain states on a per-object basis without needing per-object states. h3 CSS Naming Conventions -p Components and layouts form prefixes the prefixes for aspects and elements, separated by double dash (--). Simple layouts start with an underscore (_) and complex layouts start with two underscores (__) to distinguish them from components, and aspects are written in all caps (CAPS) to distinguish them from elements, written in all lowercase (lowercase). States are applied to the state data attribute (data-state) and queried using attribute selectors as they have the strong tendency to either be manipulated by JavaScript or be used as a hook for JavaScript. If an object has multiple states, each state should be space (' ') separated in the data-state data attribute. A sample document written up using this naming convention could look like the following: +p Components and layouts form the prefixes for aspects and element names, separated by a double dash (--). + +p Simple layouts start with an underscore (_) and complex layouts start with two underscores (__) to distinguish them from components. + +p Aspects are written in all caps (CAPS) to distinguish them from elements, which are written in all lowercase (lowercase). + +p States are applied to the state data attribute (data-state) and queried using attribute selectors as they have the strong tendency to either be manipulated by JavaScript or to be used as a hook for JavaScript. + +If an object has multiple states, each state should be space (' ') separated in the data-state data attribute. A sample document written up using this naming convention could look like the following: / /
diff --git a/source/code-standards/performance.html.slim b/source/code-standards/performance.html.slim index 40204c3..8edb0ae 100644 --- a/source/code-standards/performance.html.slim +++ b/source/code-standards/performance.html.slim @@ -2,18 +2,41 @@ title: Performance id: 'code-standards' --- -h1 Performance -p When building modern websites, performance is a real design and development constraint and must be taken into account at every level of the development process. The reason it is a design and development constraint is fairly simple: with the explosion of an everything-connected world and the rise of the mobile-only user, the chances that a site is going to be viewed primarily by someone sitting at a workstation with a high speed internet connection diminishes daily. This constraint isn't new either; way back in 2006, Amazon reported that a 100ms delay cost them 1% of sales. This was before the great reach of broadband took hold and before the current mobile computing boom came full swing, which have only lessened the patience of consumers. As Compuware reports, 75% of mobile web users expect a site to load as fast or faster on their mobile devices as they do their desktop computers, with 60% of mobile web users leaving a site and not coming back if it takes more than 3 seconds to load, with 78% of users trying only one more time. Moreover, if a user abandons a mobile site, 33% will go to a competitor's site. What all this means is that performance affects website revenue. Google, helpfully, provides some interesting insight into how performance could have affected their 2011 revenue: +section.styleguide-module-details + + h1 Performance + + p When building modern websites, performance is a real design and development constraint and must be taken into account at every level of the development process. + + p The reason it is a design and development constraint is fairly simple: with the explosion of an everything-connected world and the rise of the mobile-only user, the chances that a site is going to be viewed primarily by someone sitting at a workstation with a high speed internet connection diminishes daily. + + p This constraint isn't new either; way back in 2006, Amazon reported that a 100ms delay cost them 1% of sales. This was before the great reach of broadband took hold and before the current mobile computing boom arrived, which have only lessened the patience of consumers. + + p As Compuware reports, 75% of mobile web users expect a site to load as fast or faster on their mobile devices than they do on their desktop computers and with: + + ul + li 60% of mobile web users leaving a site and not coming back if it takes more than 3 seconds to load + li 78% of users trying only one more time + li 33% of those who give up will go to a competitor's site + + p What all this means is that performance affects website revenue. Google, helpfully, provides some interesting insight into how performance could have affected their 2011 revenue: + + ul + li Google made approximately $18.8 Million per day on search advertising + li A 400ms delay (less than half of a second) reduces average number of daily searches by 0.59% (and is about twice their warning threshold) + li That amounts to a daily loss of $111,000, or about $40.5 Million a year + + p When discussing and testing performance, it is important to do both with an eye toward mobile. + + p This means that all performance testing needs to take place on actual devices, not just emulators, and on actual networks. Many of the standards have some wiggle room, and are presented as the ideals and maximums for performance standards. -ul - li Google made approximately $18.8 Million per day on search advertising. - li A 400ms delay (less than half of a second) reduces average number of daily searches by 0.59% (and is about twice their warning threshold) - li That amounts to a daily loss of $111,000, or about $40.5 Million a year + p These ideals and maximums have been chosen with an eye towards the realities of a media heavy site, including the realities of advertising and heavy multimedia usage. -p When discussing and testing performance, it is important to do both with an eye toward mobile. This means that all performance testing needs to take place on actual devices, not just emulations, and on actual networks. Many of the standards have some wiggle room, but presented are the ideals and maximums for performance standards. The ideals and maximums have been chosen with an eye towards the realities of a media heavy site, including the realities of advertising and heavy multimedia usage. As 80% of the end-user response time is spent on the front-end, most of the performance suggestions are front-end based. + p As 80% of the end-user response time is spent on the front-end, most of the performance suggestions are front-end based. section.styleguide-module-details + h2 Testing and Grading Performance p In addition to the below, sites should be able to hit and maintain certain performance benchmarks from a variety of different resources across the internet. These systems are a good way of doing easy tests of a site to determine how they stack up. The following are good testing and grading resources, and the minimum target scores for each resource: @@ -21,17 +44,21 @@ section.styleguide-module-details ul li Page Speed - 85 li Web Page Test - li First Byte Time: 85 - li Use persistent connection: 85 - li Use gzip compression for transferring compressable responses: 90 - li Compress Images: 90 - li Use Progressive JPEGs: 90 - li Leverage browser caching of static assets: 90 - li Use a CDN for all static assets: 85 - li YSlow - 85 - li Payload Performance - - p Load times, load sizes, and number of requests are extraordinarily important and often overlooked or left to the end of a development cycle to start to optimize. Ideal statistics are presented first, with maximums presented second that should only be broached under edge circumstances. It is always best to keep actual performance as much under these numbers as possible. + ul + li First Byte Time: 85 + li Use persistent connection: 85 + li Use gzip compression for transferring compressable responses: 90 + li Compress Images: 90 + li Use Progressive JPEGs: 90 + li Leverage browser caching of static assets: 90 + li Use a CDN for all static assets: 85 + li YSlow - 85 + + h4 Payload Performance + + p Load times, load sizes, and number of requests are extraordinarily important and often overlooked or left to the end of a development cycle to start to optimize. Ideal statistics are presented first, with maximums presented second that should only be broached under edge circumstances. + + p It is always best to keep actual performance as far below these thresholds as possible. ul li Time To First Byte: 200ms - 350ms @@ -40,24 +67,31 @@ section.styleguide-module-details li Total Download Size: 1MB - 2MB li DNS Lookup: 10ms - 20ms li HTTP Requests: 50 - 75 - li Page Performance - p Once a site has been downloaded, performance of the user interactions is important as well. The goal to reach for is a site running at or above 60 frames per second. Anything below this makes sites appear poorly built, sluggish, and unresponsive. When dealing with user input, interactions should be under 100ms to feel instant and under 250ms to feel fast. Anything longer and interactions begin to feel sluggish. Some good rules of thumb to avoid the user interface from feeling this way are: + h4 Page Performance + + p Once a site has been downloaded, performance of the user interactions is important as well. + + p The goal to reach for is a site running at or above 60 frames per second. Anything below this makes sites appear poorly built, sluggish, and unresponsive. + + p When dealing with user input, interactions should be under 100ms to feel instant and under 250ms to feel fast. Anything longer and interactions begin to feel sluggish. Some good rules of thumb to prevent the user interface from feeling this way are: ul - li Do not bind expensive processes to document/window events (scroll, resize, etc…) + li Do not bind expensive processes to document/window events (scroll, resize, etc…); if you do, use throttling, rate-limiting, or debouncing li Use CSS3 translate instead of absolute position with top and left properties li Do not emulate fixed positioning using JavaScript li Animate through CSS3 instead of JavaScript - li Group JavaScript document reads and writes separately. Use requestAnimationFrame to reduce layout thrashing when reading and li writing to the DOM + li Group JavaScript document reads and writes separately + li Use requestAnimationFrame to reduce layout thrashing when reading and writing to the DOM li Avoid Internet Explorer's CSS expression selectors - li Front End Optimizations - p There are a number of optimization techniques that can be employed in order to enhance overall performance on a site. Some of these are battle-hardened optimizations that should be employed on all sites, while others are more experimental. As such, they will be divided into categories based on which are most critical for success, and which can be played with. +section.styleguide-module-details + h2 Front-End Optimizations -section.styleguide-module-details - h2 Critical Optimizations + p There are a number of optimization techniques that can be employed in order to enhance the overall performance of a site. Some of these are battle-hardened optimizations that should be employed on all sites, while others are more experimental. As such, they will be divided into categories based on which are most critical for success, and which can be played with. + + h4 Critical Optimizations ul li Avoid page redirects @@ -66,32 +100,33 @@ section.styleguide-module-details li Images should have a slightly shorter cache, at least 15 days li HTML should have a short cache, around 15 minutes li Internet Explorer Edge header should always be passed - li All JavaScript should be moved to the footer + li All JavaScript should be moved to the footer; except in the case of some utilities like Modernizr li document.write should be avoided li Images with no transparency should be served as progressive JPEGs, not as PNG files li CSS and JavaScript should be minified and aggregated li Reduce all blocking in the critical path to only page HTML and CSS - li Do not group CSS by media in tags; all of the CSS gets downloaded anyway. Instead, reduce the number of aggregates li and wrap internal CSS in media queries. + li Do not group CSS by media in tags; all of the CSS gets downloaded anyway. Instead, reduce the number of aggregates and wrap internal CSS in media queries li Use a CDN li Cache page requests li Utilize progressive enhancement with feature detection to serve only what is needed to a user li Ensure that files that are only useful on particular pages only load on those pages, not all pages li Always load CSS before JavaScript - li Recommended Optimizations + li Serve gzipped versions of assets when possible; this will rely on server configuration + + h4 Recommended Optimizations ul - li Lazy load non-critical content. See Filament Group's Ajax-Include Pattern - li Employ a Responsive Image solution. Until a standard exists, look for one based on image width over viewport size. - li ASYNC and DEFER all on-page scripts (for instance, DART tags). See $script.js for a light weight async JavaScript loader + li Lazy load non-critical content. See Filament Group's Ajax-Include Pattern + li Employ a Responsive Image solution like Picturefill; until a standard exists, look for one based on image width over viewport size + li ASYNC and DEFER all on-page scripts (for instance: DART tags); see $script.js for a light weight async JavaScript loader li ASYNC all ads - li When utilizing a CDN such as Akami, use it to serve scripts such as jQuery instead of Google's CDN as it will be faster on a li cold cache - li Inline small but important files (generally <3Kb) to reduce HTTP requests. Aggregate other small files to reduce HTTP li requests + li When utilizing a CDN such as Akami, use it to serve scripts such as jQuery instead of Google's CDN as it will be faster on a cold cache + li Inline small but important files (generally <3Kb) to reduce HTTP requests. Aggregate other small files to reduce HTTP requests -section.styleguide-module-details - h2 Experimental Optimizations + h4 Experimental Optimizations ul - li Inline above-the-fold CSS into the HTML. Push additional CSS to the footer + li Inline above-the-fold CSS into the HTML using something like Critical; push additional CSS to the footer li Utilize .webp and .webm file formats - li Employ the spdy protocol + li Employ the SPDY protocol li Dynamically serve appropriately sized images from server side instead of relying upon a client side technique diff --git a/source/code-standards/responsive-web-design.html.slim b/source/code-standards/responsive-web-design.html.slim index 3a421b7..6957fe9 100644 --- a/source/code-standards/responsive-web-design.html.slim +++ b/source/code-standards/responsive-web-design.html.slim @@ -11,27 +11,34 @@ p When starting projects, RWD should not be a line item, something to throw on a section.styleguide-module-details h2 Future Friendly - p The methodology of RWD is a methodology of creating sites that are Future Friendly. The core tenants of being future friendly are as follows: + p RWD is a methodology for creating websites that are future-friendly. The core tenants of being future-friendly are as follows: ul - li Acknowledge and embrace unpredictability. - li Think and behave in a future-friendly way. - li We can't be all things to all devices. - li Create meaningful content and services. - li Design services and information architecture content and mobile first - li Design content models to be used across presentations (website, apps, APIs, etc…) - li Design content models around standards to be interoperable. Focus on its long term integrity - li Having well-structured content is essential to art direction. Structure and store content accordingly - li Help others do the same. - li The set of suggestions from the Future Friendly manifesto that should not be followed as written are those dealing with device categorization and device detection. The sentiment is correct, enhance any given device with a user experience that is tailored to its capabilities, but that should be done using progressive enhancement and feature detection instead. Creating enhanced experiences this way, and encouraging users to take advantage of those enhanced experiences (as opposed to forcing them upon users based on their user agent string) allows for a more sustainable and future looking approach to delivering these experiences. + li Acknowledge and embrace unpredictability. + li Think and behave in a future-friendly way. + li We can't be all things to all devices. + li Create meaningful content and services. + li Design services and information architecture content-first and mobile-first. + li Design content models to be used across presentations (website, apps, APIs, etc.) + li Design content models around standards to be interoperable. Focus on its long term integrity. + li Having well-structured content is essential to art direction. Structure and store content accordingly. + li Help others do the same. + li The set of suggestions from the future-friendly manifesto that should not be followed as written are those dealing with device categorization and device detection. The sentiment is correct, enhance any given device with a user experience that is tailored to its capabilities, but that should be done using progressive enhancement and feature detection instead. Creating enhanced experiences this way, and encouraging users to take advantage of those enhanced experiences (as opposed to forcing them upon users based on their user agent string) allows for a more sustainable and future looking approach to delivering these experiences. section.styleguide-module-details h2 Device Detection - p Device detection is a bad and unsustainable practice. Relying upon current knowledge, device detection is a method of identifying a device based on its User Agent String. This is a poor method of identification in and of itself; it is based on current knowledge, meaning that lists need to be maintained and can only be updated after a device has been released, making said lists consistently out of date. Additionally, if used for categorizing devices, for instance into phone, tablet, and desktop devices, it requires subjective determinations that may or may not reflect the realities of the actual device and its user, and itself pushes lists out of date and can create divergent lists. Oh, and user agent strings can (and often times, especially on the mobile web, do) be faked to emulate the user agent string of another device and/or browser. It should go without saying that using user agent strings to determine and pivot on browsers and browser versions should also not be done. + p Device detection is a bad and unsustainable practice. Device detection is a method of identifying a device based on its User Agent String. This is a poor method of identification in and of itself; it is based on current knowledge, meaning that lists need to be maintained and can only be updated after a device has been released, making said lists consistently out of date. + + p Additionally, if used for categorizing devices, for instance into phone, tablet, and desktop devices, it requires subjective determinations that may or may not reflect the realities of the actual device and its user. This categorization can also push lists out of date and create divergent lists. Oh, and user agent strings can (and often times, especially on the mobile web, do) be faked to emulate the user agent string of another device and/or browser. It should go without saying that using user agent strings to determine and pivot on browsers and browser versions should also not be done. p Device detection extends to choices made when designing sites as well, not just user agent strings. Common examples of non user agent string device detection include mimicking iOS native app visual styling and user experience patterns on the web, constraining designs to "phone", "tablet", and "desktop" sizes (or "small", "medium", and "large"), choosing media queries and breakpoints based on "common" device sizes, and making assumptions about features based on screen size (such as small screens have touch capabilities). - p The reason device and/or browser detection was used in the past, and some still believe it has a place in a modern web development workflow, is because it is often used as a means to make guesses at the features available to work with or at the stereotypical expected user behavior. Unfortunately, it is a pretty terrible tool for doing both. On the feature side, there is a widely accepted best practice of using progressive enhancement and feature detection to "ask" a browser what features are available and enhance the experience with those features. This approach means that a web page can adapt to what is actually available in a way that works across all past, present, and future devices in a way that is much more reliable and hardy than device detection. On the expected user behavior side, as Josh Clark points out: + p The reason device and/or browser detection was used in the past, and some still believe it has a place in a modern web development workflow, is because it is often used as a means to make guesses at the features available to work with or at the stereotypical expected user behavior. Unfortunately, it is a pretty terrible tool for doing both. + + p On the feature side, there is a widely accepted best practice of using progressive enhancement and feature detection to "ask" a browser what features are available and enhance the experience with those features. This approach means that a web page can adapt to what is actually available in a way that works across all past, present, and future devices in a way that is much more reliable and hardy than device detection. On the expected user behavior side, as Josh Clark points out: - p While talking about mobile, the point is as follows: users are the same regardless of the device they choose to use. Assuming a user has a different set of wants or needs exclusively based on the fact a user agent string says they are using a tablet device will always be wrong. Bring personal experience into decision making; when browsing a website on your phone, are your wants and needs there all that different than when you do so on a desktop computer? + blockquote + p While talking about mobile, the point is as follows: users are the same regardless of the device they choose to use. + p Assuming a user has a different set of wants or needs exclusively based on the fact a user agent string says they are using a tablet device will always be wrong. + p Bring personal experience into decision making; when browsing a website on your phone, are your wants and needs there all that different than when you do so on a desktop computer? diff --git a/source/code-standards/sass.html.slim b/source/code-standards/sass.html.slim index 7372a43..2c96398 100644 --- a/source/code-standards/sass.html.slim +++ b/source/code-standards/sass.html.slim @@ -4,7 +4,17 @@ id: 'code-standards' --- h1 Sass and Compass -p When writing CSS, use Sass with the Compass authoring framework. When compiling Sass and Compass, only use the Ruby gems to compile them or a tool that calls out to the Ruby gems. The scss syntax should be used exclusively when writing and sharing Sass. In order to ensure that all environments are the same, the minimum version of Ruby that should be used is 2.0.0 (standard on OS X version 10.9 and up) and all gems should be installed and versions managed by Bundler. When writing a Gemfile, versions should all be specified using the specifier to ensure that gems stay on the same major and minor versions, making upgrades in minor versions purposeful. Gems should be installed in to a vendor folder in each project, which should be ignored from version control. In addition to Bundler, there are a number of Compass extensions that should be used as a standard for a variety of needs. +p When writing CSS, use Sass with the scss syntax and the Compass authoring framework. + +p When compiling Sass and Compass, only use the Ruby gems to compile them or a tool that calls out to the Ruby gems. + +p In order to ensure that all environments are the same, the minimum version of Ruby that should be used is 2.0.0 (standard on OS X version 10.9 and up) and all gems should be installed and managed by Bundler. + +p When writing a Gemfile, versions should all be specified using the specifier to ensure that gems stay on the same major and minor versions, making upgrades in minor versions purposeful. + +p Gems should be installed in to a vendor folder in each project, which should be ignored from version control. + +p In addition to Bundler, there are a number of Compass extensions that should be used as a standard for a variety of needs. / # Set this to the root of your project when deployed: / http_path = "/" @@ -25,11 +35,17 @@ p When writing CSS, use Sass with the Compass authoring framework. When compilin h3 Mixin/Extend Pattern -p Mixins are best used when they don't needlessly duplicate the properties they write. We can do this using placeholder selectors and @extend. The only properties that should be directly written to the selector calling a mixin should be properties that have been directly altered due to mixin arguments. Any other properties should be extended. All arguments that have default values should have those default values controlled by globally namespaced !default variables to make overriding those defaults easy and accessible. All mixins that provide extends should also have an $extend optional argument, ideally as its last argument, also globally defaulted. +p Mixins are best used when they don't needlessly duplicate the properties they write. We acheive this using placeholder selectors and @extend. + +p The only properties that should be directly written to the selector calling a mixin should be properties that have been directly altered due to mixin arguments. Any other properties should be extended. -p Mixins should also be divided up by purpose. While an omni mixin may be easier to write, having smaller mixins will make maintaining and using said mixins, as well as changing discrete parts of a rendered component, easier to do. +p All arguments that have default values should have those default values controlled by globally namespaced !default variables to make overriding those defaults easy and accessible. -p Let's take a look at a typical message component mixin as an example of how to re-write it using our mixin/extend pattern. +p All mixins that provide extends should also have an $extend optional argument, ideally as its last argument, also globally defaulted. + +p Mixins should also be divided up by purpose. While an omni mixin may be easier to write, having smaller mixins will make maintaining and using said mixins, as well as changing discrete parts of a rendered component, easier. + +/ p Let's take a look at a typical message component mixin as an example of how to re-write it using our mixin/extend pattern. / // Sass / @mixin message($color, $padding: .25em .5em, $width: 80%) { @@ -86,7 +102,7 @@ p Let's take a look at a typical message component mixin as an example of how to / color: #bf0000; / } -p While the single mixin may allow us to easily get the output we want, it does so at the cost of duplicating properties, and thus vastly bloating, our output CSS. This can be remedied almost entirely simply by rewriting our original mixin using our new mixin/extend pattern. +/ p While the single mixin may allow us to easily get the output we want, it does so at the cost of duplicating properties, and thus vastly bloating, our output CSS. This can be remedied almost entirely simply by rewriting our original mixin using our new mixin/extend pattern. / // Sass / $message-padding: .25em .5em !default; @@ -173,7 +189,7 @@ p While the single mixin may allow us to easily get the output we want, it does / color: #bf0000; / } -p While this approach certainly requires more work up front to build the mixins and extendables, it produces much more controlled and succinct output CSS, which is what we're aiming to write. +/ p While this approach certainly requires more work up front to build the mixins and extendables, it produces much more controlled and succinct output CSS, which is what we're aiming to write. h3 Partial Structure @@ -181,11 +197,17 @@ p Sass partials are a way for us to organize our styling knowledge into maintain p At the root of our Sass folder is our style.scss file, which holds the core of our styling, and a no-script.scss file to provide a CSS fallback if scripting isn't available. In the sass folder, create an enhancements folder, a fallbacks folder, and a partials folder for stylesheets that provide enhanced styling for powerful browsers, fallback styling for less powerful browsers, and partials for all to draw from, each respectively. -p Each feature being enhanced with or fallback being provided for should be named feature.scss and be placed into their respective folder; for instance, enhancements and fallbacks for CSS Animations would have a folder structure that looked something like sass/enhancements/css-animations.scss and sass/fallbacks/css-animations.scss. +p Each feature being enhanced or fallback being provided should be named feature.scss and be placed into their respective folder; for instance, enhancements and fallbacks for CSS Animations would have a folder structure that looked something like sass/enhancements/css-animations.scss and sass/fallbacks/css-animations.scss. + +p The partials directory should be divided up into 3 sub directories, global, components, and layouts. + +p Inside of global, there should be a folder for variables, a folder for functions, a folder for mixins, and a folder for extendables. + +p Inside each of those folders should go partials whose content should be made available globally and aren't component specific. For instance, global color and typographic variables, background/text color contrast mixins, ligature extendables, etc. -p The partials directory should be divided up into 3 sub directories, global, components, and layouts. Inside of global, there should be a folder a piece for variables, functions, mixins, and extendables, with partials to match. Inside each of those folders should go partials whose content should be made available globally and aren't component specific. For instance, global color and typographic variables, background/text color contrast mixins, ligature extendables, etc… +p Both components and layouts should be built using a similar partial structure, henceforth known as the component partial structure. -p Both components and layouts should be built using a similar partial structure, henceforth known as the component partial structure. Each component should have a partial and matching folder, and inside that folder a partial a piece for variables, functions, mixins, and extendables. Each of these partials should hold styling knowledge specific to that component; for instance, variables could have color variables specific to that component, but the color it is set to should come from the global color partial. An example of this can be seen in the example sass folder. +p Each component should have a partial and a matching folder, and inside that folder there should be a partial for variables, a partial for functions, a partial for mixins, and a partial for extendables. Each of these partials should hold styling knowledge specific to that component; for instance, variables could have color variables specific to that component, but the color it is set to should come from the global color partial. An example of this can be seen in the example sass folder. p The Import Once extension should be utilized to prevent duplication of selectors for extendable classes. Mixins should share their naming convention with the object they are used to style.