Guided Tutorials
Modernize CSS to Custom Properties
Replace hardcoded colors, fonts, and spacing with CSS custom properties for a maintainable design system. This tutorial takes a stylesheet full of magic values and produces a clean variables file plus updated references throughout.
What you'll learn
- How to audit a codebase for hardcoded CSS values
- How to extract values into CSS custom properties
- How to organize a variables file for a design system
- How to add dark mode support with variable overrides
Before you start
You only need the following to get started.
Requirements
- Autohand Code installed. Run
autohand --versionto confirm. If not installed, see Your First Autohand Session. - A project with CSS files. Plain CSS, SCSS, or CSS Modules all work.
Project setup
Make sure your working tree is clean before starting. The diff after this tutorial is satisfying to review.
Tip: If you use a CSS preprocessor like SCSS with existing variables, you can still benefit from this tutorial. Ask Autohand to migrate SCSS variables to native CSS custom properties so the variables work at runtime without a build step.
Step 1: Audit your current CSS
Before creating any variables, get a full picture of what hardcoded values exist and how often each one appears. Repeated values are the best candidates for variables.
A typical output looks like:
The audit immediately shows patterns. Values that appear more than 5 times are almost always worth extracting. Values that appear once or twice may be fine to leave hardcoded.
Step 2: Run the modernization prompt
With the audit complete, run the main prompt to extract variables and update all references in one pass.
Autohand will produce the variables file and update the references in a single pass. For large projects with many CSS files, break it into two steps:
Step 3: Review the variables file
The generated variables.css is the foundation of your design system. Review it before moving on. A well-structured variables file organizes tokens by category:
Check these things in the generated file:
- Names are descriptive and consistent.
--color-brandis better than--red. - Related values are grouped with a comment.
- Spacing values follow a clear scale (4, 8, 16, 24, 32, 48 is a standard 4px grid).
- No one-off values that only appeared once are included.
Tip: If the generated names do not match your team's naming convention, ask Autohand to rename them: autohand "Rename the variables in variables.css to follow the BEM-style naming convention: --[category]-[property]-[variant]."
Step 4: Check the updated stylesheets
After Autohand updates the CSS files, verify the replacements look correct. Here is what a typical component stylesheet looks like before and after.
Before:
After:
Open the site in a browser and compare visually. The output should look identical. If anything looks different, the variable value may not match the original hardcoded value. Ask Autohand to check:
Step 5: Add dark mode support
Once your variables are in place, adding a dark mode is a matter of overriding the relevant variables in a [data-theme="dark"] block. This is one of the main benefits of the migration.
The resulting override block:
To toggle dark mode, set the attribute on the root element:
Step 6: Test across pages
After the migration, check every page of the site. Custom properties cascade down from :root, so a mistake in the variables file affects every page at once.
Ask Autohand to generate a quick checklist:
Work through the list systematically. For each page, check:
- Colors match the original design
- Spacing looks the same
- Typography is unchanged
- Interactive states (hover, focus, active) still work
- Dark mode (if implemented) looks correct
If anything looks off, find which variable is responsible:
When all pages check out, remove the old variables.css import from any files that no longer need it, and confirm there are no remaining hardcoded values for the token categories you extracted:
What you learned
- Audited a codebase and found every hardcoded CSS value
- Extracted values into a clean variables file
- Updated all stylesheet references to use custom properties
- Added dark mode support with a single override block