Restructure output as package overrides

[aduth]

This pull request proposes a significant overhaul to the source and output file structure for the project, with two main objectives:

1. Alignment to USWDS v3 in downstream project usage
2. Alignment to USWDS v3 in internal package file structure

For usage, a goal here is that @18f/identity-design-system can act largely as a drop-in replacement to @uswds/uswds, where a consuming project could follow the USWDS developer guidance, and only need to substitute the package names.

For file structure, this exposes the new optimization options for per-package imports, as well as creating a more rigid one-to-one mapping between our overrides and the default design system stylings (which was already a goal documented in CONTRIBUTING.md).

How it works:

Essentially, this creates an output packages directory which contains all of the default USWDS packages directories. For packages we intend to customize, a file is added to the root of the packages directory, containing a reference to the original package as well as any customizations. This way, if a consuming project imports a package by name (e.g. @forward 'usa-alert';), the request will be intercepted if customizations exist, and otherwise load the default USWDS package.

The process for this is quite simple, as it copies the USWDS folders, then adds in our customizations:

https://github.com/18F/identity-style-guide/blob/5a8d45db0ba4333f70480896eaf20af33b5ac6c0/Makefile#L61-L62

Usage:

I updated a relevant section in README.md, though I would like to do a more substantial rewrite of the README prior to a final release.

You can also reference the fully-functional IdP branch at 18F/identity-idp#8093, which has now been updated to use this revised approach. Notably, where previously we had to juggle both @18f/identity-design-system and @uswds/uswds package references, the usage is much more streamlined now.

[zachmargolis]

LGTM

[aduth]

For future Andrew: Ideally this file would be more minimalistic, forwarding the default package and adding our custom components, e.g.:

@forward './uswds/index';
@forward 'usa-code';
@forward 'usa-spinner';
@forward 'usa-verification-badge';

This would also make it more obvious which of these are custom to our design system, vs. extended from USWDS.

The reason we can't do that currently is because uswds/_index.scss references deep paths of the components that it forwards (source), which bypasses our technique for intercepting the root package handle.

Couple options to consider:

• Upstream patch to USWDS to change uswds/_index.scss to reference the top-level handle (I don't see why it couldn't?)
• Some other automation to copy the source uswds/_index.scss file to remove /src/styles file path references.
• Try to intercept the deep path handles, such as the same technique for overriding the top-level handle, but applied for [package]/src/_styles.scss.

[aduth]

Follow-up at uswds/uswds#5241

[aduth]

The rearrangement of this may have inadvertently fixed an existing bug with input margins.

Originally flagged in the visual regression tests on the Form Fields page:

On the live site, previously the top margin was previously 0.5rem (incorrect):

On this branch, the top margin is now halved to 0.25rem (correct):

For reference, the Figma Design System document shows 4px (0.25rem) top margin:

cc @nickttng

[aduth]

I confirmed locally that the only visual regression is the one flagged by the build, explained at #336 (comment).