18f / frontend Goto Github PK
View Code? Open in Web Editor NEW18F's Front End Guild – content has been moved to https://github.com/18F/development-guide
License: Other
18F's Front End Guild – content has been moved to https://github.com/18F/development-guide
License: Other
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.
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?
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:
Here are some components that I'm starting to see a lot and that we could help people figure out:
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).
Basic chart types, a style guide for designing them, and code samples for generating them.
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).
Let's just keep a running list of topics we'd like to talk/teach each other for brownbags!
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.
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.
A guide that goes over the recommend front end frameworks and libraries to use.
https://pages.18f.gov/frontend/css-coding-styleguide/, scss-lint.yml file link is broken
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?
Set the HTML font size to 10px to ensure .1 rem unit equals 1px.
It should be 1 rem unit equals 10px.
, right?
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.
Set up meeting with people who have done css regression testing and write down their experiences with example code
These could be phrased as stories, such as:
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.
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.
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?
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.
Some points to hit:
<!DOCTYPE html>
<html lang="en">
(or whatever the primary language is)<br>
, <img>
, <link>
, etc.header
, nav
, main
, section
, figure
, etc.Maybe reference HTML5 Boilerplate?
@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.
I'm working on a draft here: https://docs.google.com/document/d/18e7cFYZhIVAeuKeE4g_nre7To9m6ZH9sd4ptP0ndC2w/edit
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:
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
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:
Set up meeting with people who have done JS unit testing and write down their experiences with example code
I was looking at Thoughtbot's order section of their Sass styleguide https://github.com/thoughtbot/guides/tree/master/style/sass#order:
@extends
and @includes
at the top of your declaration list..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:
@extend
directives@include
directives.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?
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
The recs page on staging is missing a lot of link URLs.
Goal: Document our choices on various CSS style questions.
Set up meeting with people who have done functional front end testing and write down their experiences with example code to spread the knowledge.
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!
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.
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.
This is related to #18 about updating the repo roadmap.
This is related to dependency management, but might merit a page of its own. There are a couple of tools to consider:
I ended up going with browserify for the College Scorecard, but after talking with @jmcarp about it I tried out webpack and was sold.
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.
Can we add the URL https://pages.18f.gov/frontend/ to the top part of the GitHub repo?
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).
Write a how-to
Goal: See if we can find examples of a CSS/Sass styleguide that we could either copy whole cloth or fork.
Steps:
Keep in mind:
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.
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
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:
.
How to do it, etc.
<img src="foo.svg">
, <object>
, inline <svg>
viewBox
and preserveAspectRatio
viewBox
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.
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.