DC-36(feat): Design Token System with USWDS Integration #3
Conversation
adbergen
changed the title
There was a problem hiding this comment.
Pull Request Overview
This pull request introduces a comprehensive design token management workflow for the Summer EBT Self-Service Portal, enabling scalable, USWDS-compliant theming for 50+ states. The implementation uses Figma Tokens Studio for token management, a Node.js transformation script to convert tokens to USWDS-compatible Sass, and Vite as the build system with Lightning CSS and sass-embedded for performance optimization.
Key Changes:
- Design token management workflow using Figma Tokens Studio with automated GitHub sync
- Vite-based custom USWDS compiler replacing the official @uswds/compile tooling
- Integration of frontend and .NET backend build processes for unified development experience
Reviewed Changes
Copilot reviewed 15 out of 18 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| vite.config.ts | Configures Vite build system with USWDS compilation, token transformation plugin, and static asset copying |
| tsconfig.json | TypeScript configuration for ES2022 with strict mode and bundler resolution |
| scripts/tokens-to-scss.js | Token transformation script converting Figma JSON to USWDS SCSS variables with smart caching |
| sass/_uswds-theme.scss | USWDS theme loader that imports state-specific tokens and USWDS core |
| src/styles.scss | Main Sass entry point following USWDS custom compiler pattern |
| src/main.ts | Application entry point importing USWDS styles |
| package.json (web) | Frontend dependencies and build scripts for token management and Vite |
| package.json (root) | Workspace-level convenience scripts for frontend and backend |
| pnpm-workspace.yaml | Workspace configuration defining package boundaries |
| SEBT.Portal.Api.csproj | .NET project file integration for frontend builds |
| index.html | HTML entry point with USWDS component examples |
| README.md | Comprehensive documentation of token workflow and project structure |
| 0003-design-token-management.md | ADR documenting design decisions and alternatives considered |
| .gitignore | Ignore rules for build outputs and generated files |
| .env.example | Environment configuration template for state selection |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @forward 'uswds'; | ||
|
|
||
| // 3. Load project's custom styles | ||
| @forward '../sass/uswds-theme-custom-styles'; |
There was a problem hiding this comment.
The file references _uswds-theme-custom-styles.scss which doesn't exist in the diff. This will cause a build error when Sass tries to compile. Either remove this line if custom styles aren't needed yet, or ensure the file is created.
| @forward '../sass/uswds-theme-custom-styles'; |
There was a problem hiding this comment.
@adbergen The web build script is not working with an error that it cannot find this file. Is this supposed to point to uswds-theme-dc? If so, we should probably add that value dynamically during the build
There was a problem hiding this comment.
If I try to change this to mathch the dc.sass file, it still fails
There was a problem hiding this comment.
I added a style sheet for the sebt portal with the name below and updated this line and it is all working now
| @forward '../sass/uswds-theme-custom-styles'; | |
| @forward '../sass/sebt-portal-custom-styles'; |
jhernandez-cfa
left a comment
jhernandez-cfa
left a comment
There was a problem hiding this comment.
@adbergen Was this applied or ignored? It would be useful to setup for both since this will most likely run on windows servers
I was referencing the CoPilot suggestion to make this call to lsof a more OS agnostic call
Co-authored-by: Copilot <[email protected]>
| **Cons**: | ||
| - Gulp dependency (legacy build tool, declining adoption) |
There was a problem hiding this comment.
Is this still a dependency?
This pull request introduces a comprehensive design token management workflow for the Summer EBT Self-Service Portal, enabling scalable, USWDS-compliant theming for 50+ states using Figma Tokens Studio and a Vite-based build system. It establishes the initial implementation for DC, automates the transformation of Figma design tokens into USWDS-compatible Sass, and integrates the frontend and backend build processes for a unified developer experience. Key documentation and configuration files are added, along with scripts and ignore rules to support this workflow.
Design Token Management and Build Workflow:
0003-design-token-management.md) detailing the adoption of Figma Tokens Studio for design token management, automated token transformation via Node.js, and integration with Vite and USWDS for scalable, multi-state theming. The ADR documents the rationale, alternatives considered, risks, and workflow for maintaining design-code consistency across all states.README.mdinsrc/SEBT.Portal.Webdocumenting the token workflow, project structure, key features, and build performance, providing clear onboarding and operational instructions.Frontend Build System and Tooling:
package.jsonandpnpm-workspace.yamlto define scripts and package boundaries, enabling streamlined builds, development, and dependency management for both frontend and backend using pnpm workspaces. [1] [2]package.jsoninsrc/SEBT.Portal.Webspecifying dependencies (USWDS, Vite, Lightning CSS, sass-embedded, etc.) and scripts for token transformation, development, build, and preview..gitignorefor the frontend to exclude build outputs, generated theme files, and editor artifacts, ensuring a clean repository and preventing accidental commits of generated assets..NET Backend Integration:
SEBT.Portal.Api.csproj) to automatically build the frontend (including token transformation and Vite build) before .NET builds in production, and to start the frontend dev server alongsidedotnet watchin development. Also added cleaning of frontend build artifacts ondotnet clean.USWDS Theme and Example Implementation:
src/SEBT.Portal.Web/sass/_uswds-theme.scssto load state-specific theme variables (from Figma tokens) and configure USWDS core with notification suppression, establishing the pattern for scalable theming.index.htmlwith example USWDS components, workflow summary, and verification of successful token-based theming using the DC state as the initial implementation.