|
| 1 | +# 3. Design token management with Figma Tokens Studio and Vite |
| 2 | + |
| 3 | +Date: 2025-11-19 |
| 4 | + |
| 5 | +## Status |
| 6 | + |
| 7 | +Accepted |
| 8 | + |
| 9 | +## Context |
| 10 | + |
| 11 | +The Summer EBT Self-Service Portal needs to support customization for 50+ states while |
| 12 | +maintaining a consistent design system foundation. Each state requires its own visual identity |
| 13 | +(colors, typography, spacing) while adhering to USWDS (U.S. Web Design System) standards and |
| 14 | +federal accessibility requirements. |
| 15 | + |
| 16 | +Key requirements: |
| 17 | +- **Multi-state branding**: Each state needs customizable theme tokens (DC, CA, TX, etc.) |
| 18 | +- **Designer-developer workflow**: Designers work in Figma, developers need automated sync |
| 19 | +- **USWDS compliance**: Must integrate with USWDS theming system |
| 20 | +- **Scalability**: Clear workflow that scales across 50+ state implementations |
| 21 | + |
| 22 | +Without automated token management, each state implementation would require manual |
| 23 | +translation of design decisions into code, creating maintenance burden and design-code drift. |
| 24 | + |
| 25 | +## Decision |
| 26 | + |
| 27 | +We will use **Figma Tokens Studio** for token management with a **Vite-based custom USWDS compiler**. |
| 28 | + |
| 29 | +**Core Architecture**: |
| 30 | +- **Token Source**: Figma Tokens Studio plugin with GitHub sync to `design/states/{state}.json` |
| 31 | +- **Token Organization**: One JSON file per state following W3C Design Tokens specification |
| 32 | +- **Transformation**: Node.js scripts convert tokens to USWDS SCSS variables and inject fonts |
| 33 | +- **Compilation**: Vite compiles USWDS with state-specific theme tokens using modern build tooling |
| 34 | +- **Optimization**: Lightning CSS, sass-embedded, PurgeCSS for production bundle optimization |
| 35 | + |
| 36 | +**Workflow**: `Figma → Tokens Studio → GitHub → JSON → Transformation Scripts → SCSS → Vite → CSS Bundle` |
| 37 | + |
| 38 | +## Alternatives Considered |
| 39 | + |
| 40 | +### Alternative 1: @uswds/compile (Official Gulp-based tooling) |
| 41 | +**Why rejected**: Gulp is a legacy build tool with slower build times. USWDS documentation |
| 42 | +explicitly supports custom compilers. Vite unifies our toolchain and provides modern |
| 43 | +performance optimizations while maintaining full USWDS compatibility. |
| 44 | + |
| 45 | +### Alternative 2: Style Dictionary |
| 46 | +**Why rejected**: Requires manual Figma export workflow (no GitHub sync). For our web-only |
| 47 | +use case, the platform-agnostic capabilities add complexity without benefit. Figma Tokens |
| 48 | +Studio's direct GitHub integration eliminates manual export steps. |
| 49 | + |
| 50 | +### Alternative 3: CSS Custom Properties at Runtime |
| 51 | +**Why rejected**: USWDS requires IE11 support, which lacks CSS custom property support. |
| 52 | +Build-time compilation is more performant and aligns with USWDS architecture. |
| 53 | + |
| 54 | +### Alternative 4: Manual SCSS Variables |
| 55 | +**Why rejected**: Does not scale to 50+ state implementations. Manual synchronization is |
| 56 | +error-prone and creates a bottleneck in the design-development workflow. Automated pipeline |
| 57 | +is essential for maintaining consistency and velocity. |
| 58 | + |
| 59 | +## Consequences |
| 60 | + |
| 61 | +### Positive |
| 62 | +- **Single source of truth**: Figma becomes the authoritative source for all design tokens |
| 63 | +- **Automated workflow**: Design changes sync to code automatically via GitHub |
| 64 | +- **USWDS compatibility**: Full compliance with USWDS theming and browser requirements |
| 65 | +- **Scalable to 50+ states**: Same pattern replicable across all state implementations |
| 66 | +- **Modern developer experience**: Vite with HMR for rapid iteration |
| 67 | +- **Production optimization**: Automated bundle optimization with Lightning CSS and PurgeCSS |
| 68 | + |
| 69 | +### Negative |
| 70 | +- **Custom tooling maintenance**: Token transformation scripts require ongoing maintenance |
| 71 | +- **Third-party dependency**: Reliance on Figma Tokens Studio plugin |
| 72 | +- **Learning curve**: Team must understand token transformation and Vite configuration |
| 73 | + |
| 74 | +### Risks and Mitigation |
| 75 | +**Risk**: Figma Tokens Studio plugin abandonment |
| 76 | +**Mitigation**: JSON format is portable; migration path to Style Dictionary exists |
| 77 | + |
| 78 | +**Risk**: USWDS version changes breaking compatibility |
| 79 | +**Mitigation**: Custom compiler follows official USWDS patterns documented by USWDS team |
| 80 | + |
| 81 | +**Risk**: State-specific token conflicts |
| 82 | +**Mitigation**: Clear naming conventions and USWDS namespace prevent collisions |
| 83 | + |
| 84 | +## References |
| 85 | + |
| 86 | +**Implementation Details**: See `docs/design-token-system.md` for technical specifications, |
| 87 | +performance metrics, and implementation guide. |
| 88 | + |
| 89 | +**Key Documentation**: |
| 90 | +- [USWDS Custom Compiler Guide](https://designsystem.digital.gov/documentation/getting-started/developers/phase-two-compile/) |
| 91 | +- [Figma Tokens Studio Documentation](https://docs.tokens.studio/) |
| 92 | + |
| 93 | +## Related ADRs |
| 94 | +- **ADR 0002**: Adopt Clean Architecture |
| 95 | + |
| 96 | +## Notes |
| 97 | +This ADR documents the production-ready implementation for DC as the first state. The pattern |
| 98 | +will be replicated for all subsequent state implementations (CA, TX, FL, etc.). |
0 commit comments