[VZ] Should Capital Framework be more tightly coupled with the design manual?

[ascott1]

Up until now Capital Framework has been it's own project. Out of the box the styles (particularly fonts and colors) don't even explicitly match those of the design manual. These were intentional choices so that Capital Framework could have potential outside of CFPB (particularly within government).

@cfarm pointed out the following recently (paraphrased):

We should be focusing on solving our own problems.

With the advent of the US Web Standards, should we move to more tightly couple Capital Framework with the CFPB design manual? If so, what would that look like? If not, why not?

Let's try to reach consensus around this as it can strongly influence many other decisions, such as #191

[Scotchester]

With the advent of the U.S. Web Standards …

Could you please elaborate on this? I am fairly sure I know what you are implying, but let's state it explicitly.

[ascott1]

Could you please elaborate on this? I am fairly sure I know what you are implying, but let's state it explicitly.

Part of the intention of Capital Framework (at least my understanding of it) was that it had the potential to be used by other government agencies (as well as non-gov projects). The US Web Design Standards supplant the potential use case for Capital Framework to be used by other government agencies. This, potentially, impacts the need for CF to not be coupled to CFPB specific design.

[Scotchester]

K, that's what I inferred. I agree, to an extent, though the USWDS are not as mature (in some respects—thinking mainly WRT supporting a build process) as ours, so there's still some potential use case for CF in government right now.

That being said, I'd still love to have it be useful non-gov entities, as well, though I recognize this should be a secondary priority to it being useful for us.

[mistergone]

I was going to post this in #191, but uh... it belongs here, doesn't it?

This might be a crazy idea (and I might be a crazy person), but I don't think a unified approach between CF and the design manual is a good idea. Instead of having CF's documentation in the design manual, let the design manual serve as the "ideal" for CF's features (and thus, its documentation). This allows for the design manual team (and designers) to decide on changes and document them in that repo before any front-end work on those standards gets done.

Imagine this process:

1. The Design Manual gets an update to its standards which comes from designers and the design-manual team.
2. The Capital Framework team (front-ends) takes note of these updates and changes, and does the work necessary to implement the features of design-manual.
3. The design manual links to CF, and CF has nice code snippets that developers can copy/paste.

BUT WHY!?!?!

Well, there are a couple reasons:

1. I think Capital Framework still has applications outside of CFPB, and is open-sourced and implemented as such. But, if a person wants some of our code, but not our design standards, then we want to document that code, not point them to a manual of how to design a CFPB page.
2. As hinted above, the Design Manual includes many things that have nothing to do with a code framework because it is essentially a set of documents aimed at maintaining a visual brand, not using code to implement features. As a for instance, the proposed tooltips design manual page. This page is full of things that have little to do with the code, but rather how the tooltips are used and styled. Compare this with the USWDS accordion documentation usage guidelines - the USWDS documentation is not interested in telling a developer or designer how to maintain a visual brand, but rather just... well, "Here's an expandable! Use it to hide and show things!" Developers might not be interested in visual branding, and designers might not be interested in a bunch of code snippets between the visual branding guidelines.
3. The design manual can easily be linked up to refer to CF documentation, and this makes organizational sense since our design specifications and visual brand are implemented via CF.
4. It allows our design manual to extend beyond the reach of our framework in those instances when the designers might be exceeding our developers' bandwidth (without the documentation hinting at features that haven't been implemented yet).

I didn't read all that, Chuck

Instead of moving docs into the design-manual repo, I think we should maintain separate CF docs and have the design-manual documents link right to useful sections of the CF docs.

These two repos are beautiful friends running hand-in-hand through a field of daisies, except sometimes the design-manual is going to let go and run away and it'd be bad if the CF repo was handcuffed to it.

[Scotchester]

:+1: to almost everything @mistergone wrote. Those reasons are exactly why I'm hesitant about over-integrating the two things.

That said, I think that doing something somewhere in the middle is a good idea. I think having some core HTML snippets in the Design Manual would be valuable. My current inclination is to provide snippet files in the component repos that are meant for inclusion in the Design Manual.

One thing I'm not quite following is the idea of the Design Manual working ahead of Capital Framework. I'm not sure that we want to publish things in the DM that aren't yet implemented.

[mistergone]

@Scotchester - "Maybe the Design Manual might pull ahead of CF" is a thing my brain made up, and I thought might be a possibility. But since there are people webbed between the CF projects and the DM project, those people might regulate against that kind of thing. :grin: I definitely don't have a reason to advocate the idea, I was just considering all possible futures.