From 959b87a2425e5edc13da2454dbfa43ec8f627b7a Mon Sep 17 00:00:00 2001 From: Jeremia Kimelman Date: Fri, 9 Mar 2018 14:19:39 -0500 Subject: [PATCH 1/5] Update frameworks.md to suggest using React --- pages/js/frameworks.md | 55 ++++++------------------------------------ 1 file changed, 8 insertions(+), 47 deletions(-) diff --git a/pages/js/frameworks.md b/pages/js/frameworks.md index 78b4c98..0f177eb 100644 --- a/pages/js/frameworks.md +++ b/pages/js/frameworks.md @@ -5,6 +5,14 @@ layout: docs sidenav: js --- # Frameworks + +**We recommend using [React]() for projects when possible.** As a team, we enjoy using React because it has a strong component model, enables easy server side rendering, and faciliates debugging by making the UI elements a function of the application state. React is most akin to the "view layer" in an MVC (Model-View-Controller) architecture and is frequently used with some other libraries. In our projects, we tend to use: + +* [Redux](https://www.npmjs.com/package/redux) for managing state +* [Webpack](https://www.npmjs.com/package/webpack) and [Babel](https://babeljs.io/) for compiling our Javascript + +However, we are not dogmatic about React - we just vastly prefer it. Here are some other popular frameworks that have been used at 18F and some of their key characteristics. + ## Angular AngularJS (commonly referred to as "Angular") is an open-source web application framework maintained by Google and by a community of individual developers and corporations to address many of the challenges encountered in developing single-page applications ([Wikipedia](http://en.wikipedia.org/wiki/AngularJS)). @@ -63,50 +71,3 @@ Backbone.js is a JavaScript library with a RESTful JSON interface and is based o - Designed primarily for REST data. -## React -React (sometimes styled React.js or ReactJS) is an open-source JavaScript library for creating user interfaces that aims to address challenges encountered in developing single-page applications ([Wikipedia](https://en.wikipedia.org/wiki/React_(JavaScript_library))). - -#### When to use: -- Single page apps that requires data manipulation on the front end without a server side request/response architecture. -- When there's a strong need to render JavaScript based UI on the server due to performance or accessibility reasons. -- JavaScript UI that incorperates many nested components. -- A UI with many components and updates that needs to be performance conscious. -- When only a "view" framework is desired/required. -- To ensure all front end components conform to a single standard. - -#### When not to use: -- When a complex build process is not feasible. React requires transforming "jsx" files to regular JavaScript. -- When developers unfamiliar with JSX and don't have time to learn. -- While open source, is maintained primarily by Facebook. - - -## Flux -Flux is not a framework, nor is it M**VC. It's a software architecture for -writing complex single page applications. - -#### When to use: -- A complex JavaScript app that requires both viewing and modifying (CRUD) data - in a UI rendered on the client. Flux will likely be overkill for apps that - don't modify data in any way. -- When the data service for the front end is REST and/or something besides REST, - such as Websockets. -- An app thats data flow has grown or will grow overly complex. - -#### When not to use: -- Applications that don't require any updating (create, update, delete) of data. -- When the cost of updating an app's architecture to flux is more than the cost - of writing the software as it exists. - -#### Pros: -- Easily add non-REST services to a front end, in a transparent way. -- Cleans up complex data flow by using uni-directional data flow. -- Cleans up complex async behavior and nested callbacks by using an evented - system and functionality to wait for data. -- Can use simple JavaScript objects rather than a complex framework. -- Easily tie components together in a clean way. -- Requires little 3rd party software. - -#### Cons: -- More verbose in file and directory structure. -- Finding best way to use can be difficult for beginners. -- Can be hard to find a good structure when beginning. From c619f558a7bb196cc2b6de043169117aa3ecf5d3 Mon Sep 17 00:00:00 2001 From: Heather Battaglia Date: Fri, 19 Jul 2019 16:41:45 -0600 Subject: [PATCH 2/5] remove front end dev/designer descriptions --- pages/index.md | 30 +----------------------------- 1 file changed, 1 insertion(+), 29 deletions(-) diff --git a/pages/index.md b/pages/index.md index 1042e97..31e6e98 100644 --- a/pages/index.md +++ b/pages/index.md @@ -3,32 +3,4 @@ title: 18F Front-End Guide permalink: / --- Welcome to the 18F Front-End Guide! This is where we keep all of our -guidelines for front-end design and development. - -## What is front end? - -The Front-End Guild did a series of exercises to determine the -fundamental differences between the front-end design and front-end -developer roles at 18F. Using [some of our own research -methods](https://methods.18f.gov), the Front-End Guild came up with -the following recommendations on knowing the difference between the -two disciplines: - -**Front-end designers** design, write, and implement the -presentational code base for websites and applications. They should -have a clear understanding of design fundamentals and systems, such -as interface style guides, responsive design, grid systems, front-end -frameworks, and accessibility best practices. Front-end designers -should feel comfortable creating and implementing design systems -using semantic HTML5, CSS/Sass and be able to assist in debugging -this aspect of the code base. - -**Front-end developers** architect, write, and implement the -functional code base for websites and applications. They should have -a clear understanding of client-side render and response, such as -HTTP methods, API consumption, the browser loading/rendering -pipeline, and accessibility best practices. Front-end developers -should feel comfortable developing and implementing client-side -interactions and frameworks using semantic HTML5 and JavaScript, and -should be able to help with debugging, testing, and performance -optimization of the code base. +guidelines for front-end design and development. \ No newline at end of file From e16afb5051c7bc23dd77bf002500e466b8c07713 Mon Sep 17 00:00:00 2001 From: Heather Battaglia Date: Fri, 19 Jul 2019 16:55:45 -0600 Subject: [PATCH 3/5] remove web components page --- pages/web-components.md | 54 ----------------------------------------- 1 file changed, 54 deletions(-) delete mode 100644 pages/web-components.md diff --git a/pages/web-components.md b/pages/web-components.md deleted file mode 100644 index 16649c9..0000000 --- a/pages/web-components.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Web Components -permalink: /web-components/ ---- -# Web components - -## Initial Impressions -First, check out [this article](http://developer.telerik.com/featured/web-components-arent-ready-production-yet/) and [its follow-up](http://developer.telerik.com/featured/web-components-ready-production/) for some background on whether Web Components (or, more specifically, [custom elements]) are ready for production. TL;DR: - -* Custom element [polyfills](https://github.com/WebReflection/document-register-element) (needed for [every browser except Chrome](http://caniuse.com/#search=custom%20elements)) are indeed ready for production. -* If you need the [template element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) and the so-called [shadow DOM](http://www.html5rocks.com/en/tutorials/webcomponents/shadowdom/) for style encapsulation, you're [out of luck](http://caniuse.com/#search=shadow%20dom): outside of Chrome, only Firefox supports it, and only with a hidden setting. Things might change soon though, as Edge (ex-IE) has also recently implemented <template> element. (The polyfills for shadow DOM, particularly, are *uuuuugly*.) -* The JavaScript libraries that expose similar APIs for defining web components are a mixed bag, as you'll see below. - -My first stop when sussing out web components was [WebComponents.org], which appears to be a collaboration between Google (makers of [Polymer]), Mozilla (makers of [x-tag]) and other open web technology folks. There's also [CustomElements.io](https://customelements.io/), which serves as a showcase for [custom elements] made primarily with Polymer and x-tag. I also enjoyed poking around the [examples](http://component.kitchen/components) on [component.kitchen], which are all available on GitHub. - -So, what about the tools? - -## [x-tag] -I tried Mozilla's x-tag first, and was impressed. The [API](http://x-tags.org/docs) is simple, I liked that you can declare components in vanilla JS, and I was able to get something working in Chrome quickly. However, I was forced to abandon it after running into untraceable errors in x-tag core when testing in IE9. x-tag also relies on the same polyfills as Polymer, which are a pain to get and update (see below for more details). Survey says: - -:-1: **I couldn't get it working in IE9**—or any browser other than Chrome, for that matter. - -## [Polymer] -Google's Polymer Project fully embraces [HTML imports], which are a way to encapsulate your component's contents, behavior and appearance in a separate HTML file. It's a neat framework, but it also assumes that you want all of the bells and whistles, including two-way data binding and the [shadow DOM]. In my testing it also appeared to be wholly incompatible with IE9, and thus basically unusable at 18F. - -:warning: The suite of polyfills that Polymer requires also entails an unnecessarily convoluted [build process](https://www.polymer-project.org/0.5/resources/tooling-strategy.html#building-individual-polyfills) if you don't need all of its features. Documentation for the polyfills is sparse, and I was unable to find any mention of the errors that I encountered in IE9. For future reference, it's best to get everything from a [CDN](http://cdnjs.com/libraries/webcomponentsjs) or [install them from npm or bower](http://webcomponents.org/polyfills/). Also, if you don't need the shadow DOM, save yourself some bytes and use the bundled `webcomponents-lite.js`, which just provides [custom elements] and [HTML imports]. - -:-1: **Polymer gets my thumbs down for trying to do too much.** - -## Vanilla JS ([document.registerElement()](https://github.com/WebReflection/document-register-element)) -Next up, I tried out [Andrea Giammarchi's](http://webreflection.blogspot.com/2014/07/a-w3c-custom-elements-alternative.html) [polyfill](https://github.com/WebReflection/document-register-element) for the core custom elements API, the `document.registerElement()` function. Andrea's polyfill has some major advantages over x-tag and Polymer: - -1. At just 3K minified and zipped, it's *tiny* compared to Polymer's hefty 150K payload (after you include all of the necessary polyfills). -2. It works in IE9 if you include either [aight] or Andrea's [dom4] polyfill. -3. The API does exactly what the spec says it should, and nothing more. No two-way data binding, no event delegation, no performance-hobbling shadow DOM shims (or shams). - -:+1: **Use this! It works great!** - -## [Bosonic] -A link to [Bosonic] features prominently on [WebComponents.org], and claims support for IE9. Unlike x-tag and Polymer, Bosonic simply follows the web component specs and uses a transpiler to convert [HTML imports] into vanilla JS and CSS at runtime. Check out the [docs](http://bosonic.github.io/documentation.html) for more info. The [platform](https://github.com/bosonic/bosonic/blob/master/dist/bosonic-platform.js) and [runtime](https://github.com/bosonic/bosonic/blob/master/dist/bosonic-runtime.js) JS files weigh in at about 82K total. - -:question: **I didn't get a chance to try this one**, but it's worth a look if you need [HTML imports] and [shadow DOM]. - -[x-tag]: http://x-tags.org/ -[Polymer]: https://www.polymer-project.org/ -[Bosonic]: http://bosonic.github.io/ -[WebComponents.org]: http://webcomponents.org/ -[component.kitchen]: http://component.kitchen/ -[custom elements]: http://www.smashingmagazine.com/2014/03/04/introduction-to-custom-elements/ -[HTML imports]: http://webcomponents.org/articles/introduction-to-html-imports/ -[template tag]: http://www.html5rocks.com/en/tutorials/webcomponents/template/ -[shadow DOM]: http://www.html5rocks.com/en/tutorials/webcomponents/shadowdom/ -[aight]: https://github.com/shawnbot/aight -[dom4]: https://github.com/WebReflection/dom4 From 2735116c151e346738941041fe41280e60898dc1 Mon Sep 17 00:00:00 2001 From: Heather Battaglia Date: Fri, 19 Jul 2019 17:00:14 -0600 Subject: [PATCH 4/5] rewrite css page --- pages/css/css.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/pages/css/css.md b/pages/css/css.md index 10e537b..6f35e4f 100644 --- a/pages/css/css.md +++ b/pages/css/css.md @@ -5,6 +5,4 @@ sidenav: css --- # CSS -The purpose of the CSS coding styleguide is to create consistent CSS or -preprocessor CSS code across 18F. The styleguide should be treated as a guide -— rules can be modified according to project needs. +The purpose of the CSS coding styleguide is to help 18F developers make decisions about CSS tools and implementations. The goal of this guide is not to be dogmatic, but to explain how and why we recommend certain approaches, and to help developers make their own decisions for their individual projects. \ No newline at end of file From 90795d9ca35b41368d5762c9d56a5e2ec30eda8a Mon Sep 17 00:00:00 2001 From: Heather Battaglia Date: Fri, 19 Jul 2019 21:18:51 -0600 Subject: [PATCH 5/5] rework architecture section --- pages/css/architecture.md | 80 ++++++++++++--------------------------- 1 file changed, 25 insertions(+), 55 deletions(-) diff --git a/pages/css/architecture.md b/pages/css/architecture.md index eebe9ea..8f0cd06 100644 --- a/pages/css/architecture.md +++ b/pages/css/architecture.md @@ -3,36 +3,42 @@ title: Architecture permalink: /css/architecture/ sidenav: css --- -# Architecture +# Choosing a CSS methodology and architecture A site's architecture should be based on its goals and purposes. This means the guidance here should be adapted to different sites and situations. -## Modular or component architecture -When using a modular or component architecture, every page is broken into a -series of modular components. There are two sets of these components: -`components` and `modules`. The architecture starts out with basic HTML element -rules: HTML, p, a, form, etc tags that than have components and modules written -on top of them. Components are very basic structure such as buttons, blurbs, -navs, and positioning structures like insets, island, and enclosure. From -here, modules are built with these components. This architecture also attempts -to keep the specificity trend in an upwards curve as you move down in the file +In general, 18F recommends using a modular approach (specifically, [modified BEM]) +to provide consistency and scalability to larger apps. However, for some applications +(such as a rapid prototype), an atomic architecture may make more sense. Below are +some considerations for choosing an architecture. + +## Modular architecture +Naming conventions like [BEM] and [SMACSS] popularized the idea of modular architecture. +Modular architectures are very helpful for a few different kinds of projects: +- larger, more complex sites with reusable components +- sites maintained and built by multiple engineers +- production sites that will be handed off to partner teams or vendors + +In a modular architecture, every page is broken into `components` and `modules`. +*Components* provide basic recurring elements such as buttons, lists, and navs. +*Modules* are built by combining these components into reusable structures. +This helps keep the specificity trend in an upwards curve as you move down in the file (more on this to come). -- Start with an elements file for all tag rules (a, h1-h5, p, \*, html, body). +A few helpful things to keep in mind when building out a modular architecture: +- Start with an elements file for all tag rules (`a`, `h1`-`h5`, `p`, `*`, `html`, `body`). - Create component files for each structural element, such as buttons, navs, - etc. These are mainly class-based and use [BEM] or another [naming - scheme](#css-naming). + etc. - Create more specific structure with modules. For instance, if the logo image and text needs very specific treatment, use a module. - - Build modules from components through mixins, extends, and HTML. - - Modules can have higher specificity, it’s fine to use deeper nesting. + - Build modules from components through Sass mixins, extends, and HTML. - Have an overrides file or folder comprised of global rules that are meant to override components and modules. - These can be generic utilities. - A good thing to put here are breakpoint-specific rules, such as hiding something at small breakpoints. -### File structure +### Example file structure ```sh _elements.scss _mixins.scss @@ -50,46 +56,10 @@ lib/neat.scss _overrides.scss ``` -For the `util`, `typography`, `elements`, and `overrides` files, once they grow -too large (300 lines or more) in size, split them into their own folder with -sub files. - -```sh -elements/_all.scss -elements/_p.scss -elements/_h.scss -typography/_body.scss -typography/_links.scss -overrides/_breakpoints.scss -overrides/_util.scss -util/_center.scss -util/_clearfix.scss -``` - - -## Importing -As you likely know, CSS rules that are later in the file override earlier -rules. This means Sass imports can be used to control inheritance and -specificity. - -- Start with base elements. -- Move to single nested classes and utils. -- Move next to more specific classes, often with nesting. -- Move next to overrides, possibly with !important rules. -- Import alphabetically. -- Only modify import order for groups of files, not specific files. +## Atomic architecture -```scss -// Bad -@import 'module/logo'; -@import 'component/mask'; -@import 'component/button'; /* Has to be imported after "mask" */ - -// Good -@import 'component/button'; -@import 'component/mask'; -@import 'module/logo'; -``` [BEM]: http://getbem.com/introduction/ +[SMACSS]: http://smacss.com/ +[modified BEM]: /css/naming \ No newline at end of file