[WIP][Experiment] Make the guide as a tool for decision-making, rather than a set of opinions #213
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -3,36 +3,42 @@ title: Architecture | ||
| permalink: /css/architecture/ | ||
| sidenav: css | ||
| --- | ||
| # 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. | ||
|
|
||
| In general, 18F recommends using a modular approach (specifically, [modified BEM]) | ||
|
There was a problem hiding this comment. I'd suggest our first suggestion would be "Use USWDS" wouldn't it? |
||
| 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. I wanted to get the actionable, "we generally recommend this" bit out in front of any ideological postulation. |
||
|
|
||
| ## 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 | ||
|
There was a problem hiding this comment. 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. 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? |
||
|
|
||
| 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). | ||
|
|
||
| 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. Why? I don't think it's a bad idea, it just feels like a fairly strong opinion to not have a reason. |
||
| - Create component files for each structural element, such as buttons, navs, | ||
| 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 Sass mixins, extends, and HTML. | ||
|
There was a problem hiding this comment. Do we have an opinion on mixin vs extend? I know a lot of folks do :-) |
||
| - 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. | ||
|
|
||
| ### Example file structure | ||
| ```sh | ||
| _elements.scss | ||
| _mixins.scss | ||
| @@ -50,46 +56,10 @@ lib/neat.scss | ||
| _overrides.scss | ||
| ``` | ||
|
|
||
|
There was a problem hiding this comment. "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. |
||
|
There was a problem hiding this comment. WTF is this doing in this section. Moved to "Specificity" for now. There was a problem hiding this comment. I think it was attempting to show how the files should be organized for predictability and findability, which seems useful, but awkward here. |
||
| ## Atomic architecture | ||
|
There was a problem hiding this comment. 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. Can't help you. I think it's only suitable for prototypes. |
||
|
|
||
|
|
||
|
|
||
| [BEM]: http://getbem.com/introduction/ | ||
| [SMACSS]: http://smacss.com/ | ||
| [modified BEM]: /css/naming | ||
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.