How to Set Rules for Handing Off Colors from Design Files to CSS
When passing colors from a design file to CSS (Cascading Style Sheets, the rules that control a webpage’s appearance), sharing color values alone may not produce the intended result. Developers also need to know where each color belongs and how it changes during interaction. This guide explains a practical handoff process that keeps the design and implementation aligned.
Specify color roles and interaction states alongside the codes
HEX (hexadecimal) notation expresses colors using base-16 numbers; a six-digit HEX value specifies the red, green, and blue components. But even an accurate value does not tell a developer which element should use it. At minimum, agree on these details:
- Exact color value: Confirm the intended HEX code rather than adding a slightly different color during implementation.
- Where it applies: Record the screen and role, such as page background, text, button, or border.
- Interaction states: Specify the default appearance and any changes for hover (when a pointer is over an element), selection, or other relevant states.
- Transparency and underlying surfaces: If transparency is used, document its value and the background underneath it.
Match each color’s role name between the design file and CSS so that everyone can locate the components affected by a change.
A five-color handoff example for CSS
Consider a page where visitors request information. The following table documents five values for its background, text, and main action button. CSS custom properties (also called CSS variables) let developers assign a name to a value and reference it in multiple places.
| Role in the design | CSS name | HEX color | Where to apply it |
|---|---|---|---|
| Page background | --color-page |
#F6F8FC | Background for the entire page |
| Body text | --color-text |
#25334B | Descriptions and headings |
| Primary button background | --color-action |
#2456A6 | Default request button |
| Primary button text | --color-on-action |
#FFFFFF | Text inside the button |
| Primary button hover | --color-action-hover |
#1D4380 | When a pointer is over the button |
First, define each variable with the corresponding HEX value from the table, for example under :root. Then use background-color: var(--color-page); for the page and color: var(--color-text); for body text. For the button, combine var(--color-action) as its background with var(--color-on-action) as its text color. Set the hover background to var(--color-action-hover). This keeps each value tied to its intended place in the interface.
Using the WCAG contrast formula, body text against the page background has a ratio of approximately 11.94:1; white text on the default blue button is approximately 7.10:1; and white text on the darker hover background is approximately 9.69:1. All three exceed the 4.5:1 minimum for normal-sized text. These figures apply to the specific opaque color pairs in the table, so check the actual rendered screen for overlays and other changes.
Check the implemented page and document revisions
After handoff, compare the design with the page rendered in a browser, using these checks:
- Matching values: Do the background, body text, and button use the values in the handoff table? Has a similar color been hard-coded elsewhere?
- Matching states: Are the expected colors used for hover and selected states? Check that keyboard focus remains visible as well.
- Surrounding colors: Do text and important interface boundaries remain distinguishable against their backgrounds? Inspect transparent areas over the actual surface below them.
- Change records: When a value changes, record the variable name, old and new values, affected screens, and approved design version.
If a mismatch appears, first check whether the design specification has changed instead of introducing another one-off color. A shared list of which color belongs where and in which state makes corrections easier to review.