Context
Currently our design tokens—like colors, spacing, and fonts—are used in a way that shows the computed values in the browser dev tools when inspecting (e.g., #ffffff for white). This makes it tough to quickly experiment or tweak these values in the dev tools because you can't see the actual token name (like--color-primary). It slows down our ability to iterate and refine our designs on the fly.
Proposed solution
Switch to using CSS custom properties (aka CSS variables) for our design tokens. By doing this, we'll be able to see and adjust the actual token names in the browser, making it much easier to make changes, experiment, and understand what’s going on.
- Advantages of Using CSS Custom Properties:
- Real-Time Iteration: Developers and Designers can quickly modify and experiment with design tokens directly in the browser’s developer tools by adjusting the CSS custom properties. This speeds up the design iteration process and makes it easier to test different design options.
- Improved Readability: Seeing the actual design token names (e.g., --color-primary) in the CSS makes it clear which tokens are being applied making it easier to compare between designs in Figma and code implementation.
- Considerations:
- Performance: Monitor the performance impact of using custom properties, especially in complex layouts. While CSS custom properties are generally performant, it's important to ensure they do not introduce unintended performance issues.
Implementation Plan
- Update Components: Gradually update components to use CSS custom properties instead of hardcoded values or precomputed tokens.
- Testing & Iteration: Use browser developer tools to iterate on design tokens in real-time during the development process. Test across different components to ensure consistency and functionality.
- Documentation & Training: Update documentation to reflect the new approach and provide training sessions for developers on using CSS custom properties effectively.
Next Steps
- Prototype: Create a prototype with a small set of components using CSS custom properties for design tokens to evaluate the approach in practice.
- Review & Feedback: Gather feedback from the team on the effectiveness and usability of this approach.
- Full Rollout: Plan the rollout of CSS custom properties across the entire codebase