-
Notifications
You must be signed in to change notification settings - Fork 36
[WIP][Experiment] Make the guide as a tool for decision-making, rather than a set of opinions #213
base: master
Are you sure you want to change the base?
Conversation
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm torn about deleting this. On one hand, we haven't had front end designers at 18F for nearly two years. On the other hand, it feels valuable to define what we expect from front end developers (and what we don't expect). Perhaps that definition process is one that we should go through again new, though?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should keep the bit about front-end developers.
* [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. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Brought this over from the ancient PR that never got merged, just to have something to work with.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I still think, especially given people's concerns about Facebook, that we should say "React or React-like" frameworks.
I'd also feel comfortable being more dogmatic about it, and say "Use a react-like framework unless you have a compelling reason not to, such as the partner already using another framework". I just think the ramp-up time for developers diving into one person's fave framework from six months ago is much greater than any benefit from that framework in most cases.
Unless we have a strong second choice, I'd be happy dropping the angular and Backbone sections, too.
@@ -1,54 +0,0 @@ | |||
--- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This page hasn't been updated in years, reads in first person, and has outdated takes in it. If we want to recommend a certain web component ideology, we need to do it fresh.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The guide hasn't created consistency, so it seems a bit pompous to suggest that that's the goal.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should be dogmatic, where being dogmatic is warranted. We should just say why we care.
For example, at this point, I'm fairly comfortable saying atomic CSS should not be used for long-lived code unless the partner is already using it and you're adopting their house style. It's just too difficult to pick through when you want to make changes, and unfamiliar to too many partners.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wanted to get the actionable, "we generally recommend this" bit out in front of any ideological postulation.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This bit here is my stab at documenting why you might choose a modular system. Very open to additions/criticisms.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we acknowledge that yes, it's ugly, clunky and tends to break the cascade, but it's ugly, clunky and tends to break the cascade in well-known, widely used and predictable ways?
@@ -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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Too large" is a matter of opinion. I've literally never done this myself and have not seen it on a project in the wild.
``` | ||
|
||
|
||
## Importing |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
WTF is this doing in this section. Moved to "Specificity" for now.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it was attempting to show how the files should be organized for predictability and findability, which seems useful, but awkward here.
- Move next to overrides, possibly with !important rules. | ||
- Import alphabetically. | ||
- Only modify import order for groups of files, not specific files. | ||
## Atomic architecture |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Help, I don't know what to write about atomic CSS because I can't stop hating it long enough to figure it out. :-p We should do some user interviews with folks like @hursey013 who have used/appreciated atomic CSS to figure out what they find it useful for.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can't help you. I think it's only suitable for prototypes.
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]) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd suggest our first suggestion would be "Use USWDS" wouldn't it?
(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`). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why?
I don't think it's a bad idea, it just feels like a fairly strong opinion to not have a reason.
- 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we have an opinion on mixin vs extend? I know a lot of folks do :-)
@@ -3,36 +3,42 @@ title: Architecture | |||
permalink: /css/architecture/ | |||
sidenav: css | |||
--- | |||
# Architecture | |||
# Choosing a CSS methodology and architecture |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think my strongest opinion when it comes to our CSS is that we're either writing a quick throwaway prototype or something we intend to hand over and have our partner maintain, and we need to figure that out and behave accordingly from the get-go. For the former, I don't care what you write or how you write it, or if you follow any methodology at all beyond the mad scientist voices in your head. For the latter, I don't care how smart you are, you can't make the deliverable smarter than their average developer.
After some discussions about how things get documented and maintained (or not) at 18F, @tbaxter-18f and some others came up with a rough framework for how to most usefully document our opinions, guidelines, and decisions. One of the points of conversation included the idea that sets of opinions are less valuable than explanations of why we recommend the things we recommend, how to evaluate future tooling, and how to prevent one voice from owning an entire set of documents.
The front end guide seems like a good place to try these guidelines out and see if it gives us something that is more valuable than what we've got. The current form is almost impossible to maintain properly, especially given the fluctuations in the number of front end developers at 18F. Rather than devote several entire pages to "how to write your CSS," what if it became a tool for deciding how to write CSS yourself? What if we focused on tools that people could use even as technology changes, without having to update the documentation every time a new framework comes in vogue?
This is an experiment to see what such a rewrite would entail, and, as such, I'd love feedback and conversation around it.