USWDS Collaboration Prototype (independent investigation)

Overview

The United States Web Design System (USWDS) gives federal teams a common foundation of components, guidance, and design tokens. Its Figma design kit is used by designers across agencies, contractors, and partners, many of whom extend it for their own projects.

This project is an ongoing systems investigation into a simple question: how can those distributed contributors propose, document, and review improvements to a shared design system without depending entirely on centralized Figma workflows? The working prototype lives in a public GitHub repository alongside the Figma source file it governs.

Challenge

Shared design systems serve many teams, but improvements rarely travel back to the source. When a component doesn't fit a project's needs, contributors often create a local fix, a custom variant, or a new component altogether. The improvement works in one place and stays there.

Review adds its own friction. In many enterprise and government Figma environments, contributors may need to hand off source .fig files for internal review and controlled publication, and access to the central workspace isn't always available during early exploration.

Approach

Rather than proposing new tooling, the investigation borrowed a pattern software teams already rely on: issue, branch, test, pull request, review, merge, release. The question was how much of that discipline could carry over to design work without asking designers to change where they design.

The work started from constraints raised in early discussions with people working inside existing governance models. Central ownership and publication controls needed to stay in place. Contributors needed somewhere to experiment before they had access to the central workspace. And reviewers needed enough context to evaluate a change without reconstructing the reasoning behind it.

System

The model separates responsibilities across platforms:

• Figma remains the visual source of truth, where components are designed and validated.
• GitHub holds contribution governance and version history: proposals, review discussions, and a record of what changed and why.
• Releases mark approved versions that teams can adopt.

A contributor identifies a problem, works on the component in a local Figma file or branch, and validates the change. They save the updated .fig file to the repository, commit it, and submit a proposal for review. Once merged, the change can be published and adopted across teams.

Each proposal follows a consistent structure: the problem being solved, the current implementation, the proposed solution, before-and-after screenshots, a Figma link or file reference, a rationale for reuse, accessibility considerations where they apply, and implementation notes. Reviewers assess whether a change improves flexibility, accessibility, scalability, maintainability, consistency, duplication, or documentation clarity.

Worked examples

Two component proposals test the model against real USWDS components:

• USA banner refactor. Modular info card components, expanded and collapsed state handling, an optional and configurable leading mark, and less structural duplication, so the banner can be customized without being rebuilt.
• Button flexibility update. Default and large sizes consolidated into shared properties, large variants added across every button color, and hover states added for prototyping.

Outcome

The investigation has produced a documented contribution model, a standard proposal format, explicit review criteria, and two worked component proposals that show the process from problem to submission. Together, they offer a lightweight way to make shared design systems easier to improve while leaving ownership and publication with the teams responsible for them.

The work is still active. Its next scoped step is testing the model against a state-level design system built on USWDS, starting with the banner, header, footer, identifier, theme tokens, and property naming. The workflow and its assumptions will keep evolving as more governance, tooling, and operational constraints come to light.

Scope and tools

Aether led the investigation independently, including the contribution model, workflow documentation, and component proposals. The work was done in Figma, Git, and GitHub. ChatGPT was used selectively to check Git branch and commit naming conventions, refine the repository description, and spot-check component structure decisions. All workflow concepts, proposals, and directions were developed and reviewed by hand.