18f/frontend

18F's Front End Guild –  content has been moved to https://github.com/18F/development-guide

Front-End Guild

18F promotes team best practices across specialty areas through guilds. These guilds support their members in whatever way deemed most appropriate by those members themselves.

This repo is where the 18F Front-End Guild keeps its guide to best practices and resources for front-end development.

Quicklinks

• Guide: https://frontend.18f.gov/
• CONTRIBUTING.md on how to build this guide locally and submitting PRs/issues.

Our mission

We believe that government websites should be functional, maintainable, and thoughtfully designed. Our guild helps TTS promote the adoption and advancement of front-end design and development best practices. In this way, TTS can lead by example while providing effective services that help our partners and customers fulfill their missions. To achieve our vision, the Front-End Guild works to:

• Support the continuous learning necessary for successful front-end work.
• Provide TTS developers with easy-to-understand, actionable guidance around front-end best practices.
• Promote a central knowledge base of shared tools and common patterns.
• Create a healthy and supportive internal environment so that we can, in turn, bolster healthy external communities related to our work.

How to track what we're doing, and how you can be involved!

We use issues in this repo to track work. If you'd like to suggest a new topic or flag an issue, please file an issue.

The front-end space is rapidly changing, and our guide is a living document. Please suggest edits or changes via pull request.

frontend's Issues

Finish OKRs

• finish copy/pasting info that was originally from mural.ly research into needs into OKR format
• document OKRs in frontend repo
• link issue priorities to OKRs so we can track (milestones?)

This is related to #18 about updating the repo roadmap.

Add URL to GitHub repo

Can we add the URL https://pages.18f.gov/frontend/ to the top part of the GitHub repo?

CSS architecture guide

Draft: https://docs.google.com/document/d/1_gC2F3uYedPkwyV34HLdg5QLKP4pnd4vbknHYOxFQx4/edit

Image optimization best practices

Write a how-to

Front End Performance Guide

I'm working on a draft here: https://docs.google.com/document/d/18e7cFYZhIVAeuKeE4g_nre7To9m6ZH9sd4ptP0ndC2w/edit

As a frontend dev at 18F, I want to be involved in the guild

The guild needs to decide how to let the team know what its up to; what activities we want to have as a group; what desserts to eat together at the offsite; etc.

Build/create a linter for the styleguide

Find a way to create a programatic linter for the style guide. This means a linter that obeys all the rules of the style guide.

This would be run as part of a build process and could fail if the code doesn't pass.

An existing tool like this might work if we're able to configure it enough so it works for our style guide. My one requirement is that it's only dependency is nodejs as thats more inline with our current front end workflows.

http://csslint.net/
https://www.npmjs.com/package/sass-lint

List features we'd like to generate with Yeoman

Visual components

Here are some components that I'm starting to see a lot and that we could help people figure out:

Tables

We should know how to make them look good, make them behave well on mobile, and endow them with features like a fixed header (for long scrolling tables).

Charts

Basic chart types, a style guide for designing them, and code samples for generating them.

Maps

Having our own map tiles would be great. We could provide some guidance on symbology, color scales, and tips on finding and integrating geographic data (e.g. for making 50-state maps).

Update @include order guidance

We instruct that users should put @include's before properties, but in the example show @include's at the end of the properties. See Sorting: https://pages.18f.gov/frontend/css-coding-styleguide/format/

.module {
  $amount = 3;
  @extend .component;
  @include sizing($amount);
  margin-top: $amount * 1em;
  text-align: center;

  .module__ele {
    color: #fff932;
  }

  @include media($sm) {
    margin-top: ($amount + 10em);
  }
}

I realize this is bc it is a media include, however I find this confusing. Can we pick a guidance of all includes before properties or be more explicit about exceptions. I still think that it's confusing to have this as an exception.

What do others think?

Add recommendations and tutorials for JS bundling

This is related to dependency management, but might merit a page of its own. There are a couple of tools to consider:

• browserify
• webpack

I ended up going with browserify for the College Scorecard, but after talking with @jmcarp about it I tried out webpack and was sold.

Pitfalls

From what I can tell, browserify's simple plugability (transforms, piping) has created a larger plugin ecosystem than webpack's. However, the plugins themselves (in my case, minifyify) are sometimes poorly documented or just pass off a lot of their logic to lower-level libraries under the hood, which makes it hard to figure out how to configure them. Browserify also eschews any sort of external configuration, which means that you have to construct sometimes convoluted command-line arguments to chain together multiple plugins. Interoperability between plugins is not guaranteed, and I had lots of issues getting source maps to work with my minified JS using browserify plugins.

Webpack, on the other hand, comes pre-installed with a set of handy plugins (including minification), and accepts a configuration file, so it's much easier to configure and use. Rather than having to duplicate your long command-line arguments when running "build" and "watch" commands (with browserify and a completely separate tool called watchify, respectively), you just write your config once and call webpack to build or webpack --watch to watch.

Build time can become an issue on larger projects, though, and in my experience (with minification and source maps turned on), browserify wins hands down on that front. Webpack apparently caches in watch mode, but it's nowhere near as fast as browserify + minifyify.

Change tone of Web Components section

The Web Components page is written in first person and with the tone of a casual blog post. The information should be rewritten into a more authoritative and impersonal tone for a guide. It can still have opinions, but they should be the opinions of 18F or the front end guild. I'm happy to help with this or to edit a draft of this revision.

Libraries we use

This is a call for an accounting of all the frontend libraries and frameworks that we've used on 18F projects, inspired by CFPB's. Specifically:

• I'd like to call out stuff that we're using purely for backwards compatibility, so please list any shims, polyfills, etc. under a Backwards Compatibility (or BC, if you prefer) heading.
• If you're using a package manager such as Bower or npm, please list it! npm users, please also list any bundlers (e.g. Browserify or Webpack) and ES6 transpilers (e.g. Babel or Esperanto).
• If your project includes frontend (functional) tests, please note what you've used to write the tests, e.g. Selenium in Python, Mocha in Node, QUnit, Karma, etc.

Update roadmap

Fix missing links on Recommendations page

The recs page on staging is missing a lot of link URLs.

Framework/libraries recommendations

A guide that goes over the recommend front end frameworks and libraries to use.

Find a home for HTTPS guidelines

@konklone

JS unit testing -- collect experiences

Set up meeting with people who have done JS unit testing and write down their experiences with example code

Show a human readable list of scss lint settings

It would be nice if I could understand what the Sass lint file does. Currently, the 18F frontend style guide is very in depth with examples, rationale, and requires you to navigate to different pages to find what you need.

I like how Thoughtbot's Sass styleguide has concise bullets on a single page: https://github.com/thoughtbot/guides/tree/master/style/sass

Research CSS Style Guides

Goal: See if we can find examples of a CSS/Sass styleguide that we could either copy whole cloth or fork.

Steps:

• Research links to other companies' style guides
• Drop links and comments on them here.

Keep in mind:

• Specificity rules
• File structure
• Units (rems / px)
• Built in linter?
• Naming conventions

@msecret @shawnbot @meiqimichelle @noahmanger

Edit repo README

Somewhere along the way our README died an ignoble death, likely of mistaken merge syndrome. It now is missing friendly intro paragraphs describing what the guild is and what it does.

Basically, everything before How to track what we're doing, and how you can be involved! needs some wordsmithing. And maybe a few things after that as well!

Document use of semantic versioning for frontend assets

In a couple of projects we've used different metrics to determine how semantic versioning applies to frontend assets (and, in the case of College Scorecard, the entire site). I'd like to propose standardizing these conventions for different layers of the frontend stack. For each of these, we should describe what types of changes would cause a change for the major ("incompatible API changes"), minor ("added, backward-compatible functionality") and patch ("backwards-compatible bug fix") version components.

• Stylesheets
• JavaScript libraries (these are covered by semver)
• Components
• Entire sites

Explain responsive SVG

How to do it, etc.

• embedding approaches: <img src="foo.svg">, <object>, inline <svg>
• guidelines for using viewBox and preserveAspectRatio
• a jQuery (preferably straight DOM) shim for older browsers that don't support implying aspect ratio from viewBox

Write hypotheses for guide topics

These could be phrased as stories, such as:

• As a backend developer, I'd like to know how the HTML my app creates should be structured.
• As a front end designer, I'd like to know how I should structure my CSS.
• As a front end developer, I'd like to know how I should manage my JavaScript dependencies.

Complete 18f-pages setup for guild guidelines

Mixed length selectors

What's the best practice for mixed length selectors in the same declaration (short and long selectors)?

The guide states:

Multiple selectors should each be on a single line, with no space after each comma, unless they selector is less than five chars.

Add guidance for Nested Properties

We should add guidance on Sass nested properties.

Currently we encourage using shorthand only when all values are stated. See Property-value pairs: https://pages.18f.gov/frontend/css-coding-styleguide/format/

With Sass, we can also use Nested Properties.

CSS has quite a few properties that are in namespaces for instance, font-family, font-size, and font-weight are all in the font namespace. In CSS, if you want to set a bunch of properties in the same namespace, you have to type it out each time. Sass provides a shortcut for this: just write the namespace once, then nest each of the sub-properties within it. For example:

.18f {
  margin: {
    top: 2em;
    bottom: 1em;
  }
}

.funky {
  font: {
    family: fantasy;
    size: 30em;
    weight: bold;
  }
}

Do we encourage one over the other? Or just let people know both options are available?

Error in Units section

Set the HTML font size to 10px to ensure .1 rem unit equals 1px.

It should be 1 rem unit equals 10px., right?

Sidebar accordion toggle not working

The + and x accordion toggles are not working on https://pages.18f.gov/frontend/, while they appear to be working on https://pages.18f.gov/ . If this bug is not a product of this repo, I can post in the 18f/pages repo.

Sketch out new frontend guide navigation theme

In order to test the new navigation theme with potential users, we should have a sketch or prototype of the navigation.

The proposed navigation scheme is under "Proposed Structure" https://hackpad.com/Front-End-Guide-Redux-bVFBdIxLvt7.

This can be done in different ways:

• In code: take the existing navigation and update it, potentially leaving some empty links. This could help because it would give a more full representation of how the guide would work in user testing. Maybe we could ensure parts of the guide not written yet are not actual links so we don't have dead links
• In design: sketch up the navigation with a design tool, potentially invision. This would allow quick iterations on the design without having to do any code but you wouldn't be able to leverage things that are already complete in code.

Comparative analysis on frontend guides

In order to take the benefits and drawbacks from existing frontend guides for the 18f frontend guide, there should be a competitive analysis of various frontend guides.

Competitive analysis is described in the 18f design method cards, https://methods.18f.gov/comparative-analysis/.

The result of this analysis should be a spreadsheet with a grading system for various aspects of the user experience and another document as a write-up of the main points learned during the analysis.

Emoji's don't render on live 18f Pages website

Looking at the web components page the emojis are rendered when you view the markdown file on GitHub, but the actual web site on 18f Pages shows them as their weird character combinations :-1:, :warning:.

Decide on a styleguide

Goal: Document our choices on various CSS style questions.

Sass order

I was looking at Thoughtbot's order section of their Sass styleguide https://github.com/thoughtbot/guides/tree/master/style/sass#order:

• Use alphabetical order for declarations.
• Place @extends and @includes at the top of your declaration list.
• Place media queries directly after the declaration list.
• Place concatenated selectors second.
• Place pseudo-states and pseudo-elements third.
• Place nested elements fourth.
• Place nested classes fifth.

.class-one {
  @include mixin;
  background-color: $color-variable;
  border: 0;

  @include media($small-screen) {
    margin: ($spacing-variable * 2) 1rem;
  }

  &::before {
    content: "hello";
  }
}

18F's:

Follow ordering:

1. variables
2. @extend directives
3. @include directives
4. properties

.module {
  $amount = 3;
  @extend .component;
  @include sizing($amount);
  margin-top: $amount * 1em;
  text-align: center;

  .module__ele {
    color: #fff932;
  }

  @include media($sm) {
    margin-top: ($amount + 10em);
  }
}

Do we have any guidance for ordering of concatenated selectors, pseudo-states and pseudo-elements, nested elements, nested classes?

Based off our example it seems like we place media queries at the end of everything. What's the thought behind that?

add github integration to slack/#frontent

https://18f.slack.com/archives/admins-slack/p1437581297000048

.scss-lint.yml file link broken

https://pages.18f.gov/frontend/css-coding-styleguide/, scss-lint.yml file link is broken

HTML style guide

Some points to hit:

• HTML5 doctype: <!DOCTYPE html>
• The lang attribute, i.e. <html lang="en"> (or whatever the primary language is)
• No XHTML self-closing tags: <br>, <img>, <link>, etc.
• HTML5 semantics: header, nav, main, section, figure, etc.
• A template for open graph meta tags or SEO more generally?
• Backwards compatibility: html5shiv, etc.

Maybe reference HTML5 Boilerplate?

Functional front end testing -- collect experiences

Set up meeting with people who have done functional front end testing and write down their experiences with example code to spread the knowledge.

Include Ember in M**V frameworks

Ember would be a good choice for some projects. It is particularly great for teams which frequently move from project to project, owing to the consistency of conventions and coding styles across apps.

Apologies in advance if this isn't a productive issue -- I was just surprised to see Ember missing.

Semantic style guide

I would love guidance on best practices for what tags to include in all HTML documents. I'm thinking mostly META tags, but others too.

Examples:

• doctype
• charset
• viewport
• language
• opengraph stuff
• myriad icons (favicon, apple touch icons, etc.)

With a mind toward 508, mobile-friendliness, i18n, etc.

A great deliverable IMO would be a "blank slate" HTML doc, ala https://github.com/h5bp/html5-boilerplate/blob/master/src/index.html

Brownbag topics

Let's just keep a running list of topics we'd like to talk/teach each other for brownbags!

Linter false positive on background images

I ran into an issue that the linter flags duplicate property on background-image bc we have two: SVG with PNG fallback.

This happened here: uswds/uswds#987 (comment)

Any advice or way to turn it off for this? @msecret

Adjust 18f guild template to better support complex content

Our guild might need a more robust guild template because it will likely be a group of frontend guides. May need a landing page with secondary nav to all the guides.

Move recommendations regarding web componants to permanent location

@shawnbot was kind enough to document his experiments with using web components in the wild in this repo's wiki. This should be moved to a single location with our other recommendations. This is likely to be an 18F Guide page.

CSS regression testing -- collect experiences

Set up meeting with people who have done css regression testing and write down their experiences with example code

Meta-research

Lately I've become interested in finding out what groups like 18F are doing in terms of frontend practice, from overarching strategy to specific tools and techniques. I'm also really interested in understanding some of the common pain points for individual designers and developers, and for teams charged with establishing patterns and best practices for a much larger group (for now, 18F; but eventually, maybe the entire federal government).

My first thought was that we should launch a research project of our own, which I'm going to discuss some more with @brethauer in the coming week. But as @xtine suggested, it's probably worth doing some meta-research in the meantime to find out what others have discovered when asking some of the same questions. So, please drop any links to research on frontend practices, patterns, tools and techniques here and let's see if that helps us figure out a reasonable starting point.

@maya, I'll bet you came across a lot of great stuff in your research for the FWDS. Can you share some of that here too?

Is the Frontend Guide a Spec?

I've been slowly making my way through the new visual guide and related assets. At West Virginia University we have a similar project though not nearly as robust as the current visual guide. The frontend guide is really interesting. It almost reads as a spec but not quite. Are there plans to follow the RFC 2119 wording to make the document a little clearer? If you've considered it but decided against using it could you share the reasoning?

Thanks much for the inspiration.

As a guild member, I want to know what the guild is working on right now

Right now, issues don't show prioritization. We need to use milestones or some other solution so team can see what we're up to and contribute. Visual tracker perhaps also a need (ie, waffle.io).

Do research on automate frontend styleguide solution

Create a product similar to KSS that allows a developer to generate and keep and updated styleguide for a frontend project.

Notes from meeting:
Brian: because the templating engine in kss-node isn’t very robust, would rather use a templating engine that is more robust
Noah: limitations of trying to everything in stylesheet are real, good for very basic stuff. As soon as you have component with lots of elements, it becomes difficult. Be interested to see us come up with something better. Like handlebars templates and in the stylesheet you specify which templates to use or what classes to pass in. It would be cool if we could get it to where it could integrate with percy better for visual regression testing
Thoughts: wouldn’t it be cool if you could tag markup with, say, a data attribute that says “kss, include this!”. So it pulls directly into the styleguide. But then you’d lose your reference -- it is sometimes good to see the canonical version. Maybe this means we need to think more about the modularity of our design.

Poll potential users of the guide

I've adapted Brad Frost's Front End Guidelines Questionnaire into this google form with the hopes that we can gather some useful info from other 18F (and even GSA, or gov-wide) potential users of the guide.

This issue is intended to get feedback on the form questions before sending the URL out to collect responses from a larger group. Let me know if you'd like access to edit the form directly, or drop suggestions here.