Color scheme

Tokenized Color System and Dark Mode

This assignment upgrades the shared CSS architecture you built last unit. You will replace your simple color tokens with oklch() seeds and light-dark() semantic tokens, expand your variables file with tokens the rest of your site will use going forward, add a working theme toggle with persistence, and roll the new color system across every page on your portfolio.

When you are finished, your site should support light mode, dark mode, and a system default option, all driven by one set of token declarations in colors.css.

What You Are Building

Here is what your root-level css/ and js/ directories should look like when this assignment is complete.


        [portfolio]
        ├── css/
        │   ├── base/
        │   │   ├── elements.css
        │   │   └── reset.css
        │   ├── components/
        │   │   └── theme-toggle.css    # New
        │   ├── layout/
        │   ├── tokens/
        │   │   ├── colors.css          # Update
        │   │   └── variables.css       # Update
        │   ├── utilities/
        │   └── main.css                # Update
        ├── js/
        │   └── theme-preference.js     # New
        ├── index.html                      # Update: Add Links
        └── README.md                       # Update: Pages Links
    

Assignment Instructions

1. Expand Your Variables

Open css/tokens/variables.css. You probably have a handful of spacing and typography tokens from the architecture assignment. Replace or expand your file so it includes at least the tokens below. These cover what the theme toggle and future components will need. You can add more of your own, but these are the baseline:


        :root {
            /* Typography */
            --font-family-sans: system-ui, sans-serif;
            --font-family-mono: monospace;
            --font-size-sm: 1.4rem;
            --font-size-md: 1.6rem;
            --font-size-lg: 1.8rem;

            /* Spacing */
            --spacing-xs: 4px;
            --spacing-sm: 8px;
            --spacing-md: 16px;
            --spacing-lg: 24px;
            --spacing-xl: 32px;

            /* Radii */
            --radius-sm: 4px;
            --radius-md: 6px;
            --radius-lg: 8px;

            /* Transitions */
            --transition-base: 0.2s ease;

            /* Icons */
            --icon-size-sm: 24px;
            --icon-size-md: 32px;

            /* Focus */
            --outline-width: 2px;
        }
    

If you already have tokens with other names for the same purpose (for example --space-md instead of --spacing-md), make the names from step 1 the source of truth. Define each value on the step 1 name, then point any legacy name at it so old declarations keep working while you migrate:


        :root {
            --spacing-md: 16px;

            /* Legacy name for backwards compatibility */
            --space-md: var(--spacing-md);
        }
    

2. Rebuild Your Color Tokens

Open css/tokens/colors.css. Replace your existing color declarations with a seed and semantic token system. The structure has three parts: seeds at the top, the color-scheme switching rules in the middle, and semantic tokens at the bottom.

Start with your seeds. These are the raw, human-chosen colors that everything else derives from. Use oklch() for your brand/accent color so you can generate a ramp from it. The grays and neutrals can stay as hex or be converted to oklch() as well:


        :root {
            color-scheme: light;

            /* ---- Seeds ---- */
            --seed-bg: #f4f6f8;
            --seed-surface: #ffffff;
            --seed-text: #1e293b;
            --seed-text-muted: #64748b;
            --seed-accent: oklch(0.55 0.2 260);  /* CHANGE THIS: Choose your own hue */
            --seed-accent-hover: color-mix(in oklch, var(--seed-accent) 80%, black);
            --seed-link: var(--seed-accent);
            --seed-link-hover: var(--seed-accent-hover);
            --seed-border: #e2e8f0;
            --seed-border-strong: #cbd5e1;
        }
    

Next, add a palette ramp from your accent seed. Use color-mix(in oklch, ...) to generate at least five steps by mixing with white (tints) and black (shades):


        :root {
            /* ---- Accent ramp ---- */
            --accent-200: color-mix(in oklch, var(--seed-accent) 30%, white);
            --accent-300: color-mix(in oklch, var(--seed-accent) 50%, white);
            --accent-400: color-mix(in oklch, var(--seed-accent) 75%, white);
            --accent-500: var(--seed-accent);
            --accent-600: color-mix(in oklch, var(--seed-accent) 80%, black);
            --accent-700: color-mix(in oklch, var(--seed-accent) 60%, black);
            --accent-800: color-mix(in oklch, var(--seed-accent) 40%, black);
        }
    

Now add the color-scheme switching rules. These detect which theme the user selected and flip color-scheme accordingly:


        /* User chose dark */
        html:has(input[name='theme-preference'][value='dark']:checked) {
            color-scheme: dark;
        }

        /* User chose system and OS is dark */
        @media (prefers-color-scheme: dark) {
            html:has(input[name='theme-preference'][value='system']:checked) {
                color-scheme: dark;
            }
        }
    

Finally, define your semantic tokens using light-dark(). Each token gets a light value (usually your seed) and a dark value (an oklch() color you choose for readability on dark backgrounds). These go on :root, html so they resolve correctly in both modes:


        :root,
        html {
            /* ---- Semantic tokens ---- */
            --color-bg: light-dark(var(--seed-bg), oklch(0.18 0.02 260));
            --color-surface: light-dark(var(--seed-surface), oklch(0.22 0.03 260));
            --color-text: light-dark(var(--seed-text), oklch(0.88 0.02 260));
            --color-text-muted: light-dark(var(--seed-text-muted), oklch(0.68 0.03 250));
            --color-accent: light-dark(var(--seed-accent), oklch(0.62 0.15 240));
            --color-accent-hover: light-dark(var(--seed-accent-hover), oklch(0.68 0.18 240));
            --color-link: light-dark(var(--seed-link), oklch(0.65 0.16 240));
            --color-link-hover: light-dark(var(--seed-link-hover), oklch(0.72 0.18 240));
            --color-border: light-dark(var(--seed-border), oklch(0.32 0.02 260));
            --color-border-strong: light-dark(var(--seed-border-strong), oklch(0.38 0.02 260));

            /* Tint the native checkboxes, radios, and range sliders */
            accent-color: var(--color-accent);

            /* ---- Header chrome ---- */
            --header-bg: var(--color-accent);
            --header-text: light-dark(#ffffff, #f0f4f8);

            /* ---- Theme toggle (consumed by theme-toggle.css) ---- */
            --theme-toggle-bg: color-mix(in srgb, var(--header-text) 20%, var(--header-bg));
            --theme-toggle-border: color-mix(in srgb, var(--header-text) 40%, var(--header-bg));
            --theme-toggle-bg-hover: color-mix(in srgb, var(--header-text) 30%, var(--header-bg));
            --theme-toggle-border-hover: color-mix(in srgb, var(--header-text) 55%, var(--header-bg));

            /* ---- Shadows ---- */
            --shadow-color: light-dark(rgb(0 0 0 / 0.09), rgb(0 0 0 / 0.28));
            --shadow-sm: 0 1px 2px 0 var(--shadow-color);
            --shadow-md: 0 1px 3px 0 var(--shadow-color);
        }
    

The examples above use a blue hue (260). Replace the hue angle with whatever brand color you want. The lightness and chroma values for the dark side are a starting point. Adjust them until both modes look good on your site.

Choose Your Own Accent Hue

The seed oklch(0.55 0.2 260) is a medium blue. Change the last number to shift the hue: 150 for green, 30 for orange, 330 for pink. Keep lightness near 0.55 and chroma near 0.2 for a color that works well as both a light and dark mode accent.

3. Add the Theme Toggle CSS

Create css/components/theme-toggle.css and paste in the following. This styles the disclosure widget and radio buttons into a compact toggle. It references the token names from your variables.css and colors.css:


        details.theme-menu {
            position: relative;
            display: inline-block;
            width: max-content;
            margin: 0;
            padding: 0;
            border: none;
            background: transparent;
            flex-shrink: 0;
            box-shadow: none;
            overflow: visible;
            color: inherit;

            &:focus,
            &:focus-visible {
                outline: none;
            }

            > summary.theme-control {
                text-transform: none;
                font-weight: normal;
                list-style: none;
                width: max-content;

                &::after {
                    content: none;
                    display: none;
                }

                &::-webkit-details-marker {
                    display: none;
                }

                &::marker {
                    content: '';
                }

                &:focus {
                    outline: none;
                }

                &:focus-visible {
                    outline: var(--outline-width) solid var(--color-accent);
                    outline-offset: var(--outline-width);
                }

                &::before {
                    content: '\2699\FE0F';
                }
            }

            .theme-control {
                box-sizing: border-box;
                display: inline-flex;
                align-items: center;
                justify-content: center;
                min-width: calc(var(--icon-size-md) + var(--spacing-md));
                min-height: calc(var(--icon-size-md) + var(--spacing-md));
                margin: 0;
                padding: 0;
                font-size: var(--icon-size-sm);
                line-height: 1;
                color: var(--header-text);
                background-color: var(--theme-toggle-bg);
                border: 1px solid var(--theme-toggle-border);
                border-radius: var(--radius-sm);
                cursor: pointer;
                transition:
                    background-color var(--transition-base),
                    border-color var(--transition-base);

                &:hover {
                    background-color: var(--theme-toggle-bg-hover);
                    border-color: var(--theme-toggle-border-hover);
                }
            }

            > .theme-extra {
                position: absolute;
                z-index: 50;
                top: calc(100% + var(--spacing-md));
                right: 0;
                margin: 0;
                display: flex;
                flex-direction: column;
                align-items: flex-end;
                gap: var(--spacing-md);
                padding: 0;
                background: none;
                border: none;
                box-shadow: none;
            }

            &:not([open]) > .theme-extra {
                display: none;
            }

            &[open] > .theme-extra {
                animation: theme-extra-reveal 0.2s ease-out;
            }

            .theme-pick {
                position: relative;

                input {
                    position: absolute;
                    opacity: 0;
                    width: 0;
                    height: 0;
                    margin: 0;
                    pointer-events: none;
                }

                &:has(input:focus-visible) {
                    outline: var(--outline-width) solid var(--color-accent);
                    outline-offset: var(--outline-width);
                }
            }
        }

        html:has(input[name='theme-preference'][value='light']:checked) {
            & details.theme-menu > summary.theme-control::before {
                content: '\2600\FE0F';
            }

            & details.theme-menu .theme-pick[data-theme-pick='light'] {
                display: none;
            }
        }

        html:has(input[name='theme-preference'][value='dark']:checked) {
            & details.theme-menu > summary.theme-control::before {
                content: '\1F316';
            }

            & details.theme-menu .theme-pick[data-theme-pick='dark'] {
                display: none;
            }
        }

        html:has(input[name='theme-preference'][value='system']:checked) {
            & details.theme-menu .theme-pick[data-theme-pick='system'] {
                display: none;
            }
        }

        @keyframes theme-extra-reveal {
            from {
                transform: translateY(-0.4rem);
            }

            to {
                transform: translateY(0);
            }
        }
    

Open css/main.css and add an import for this new file in the components layer:


        @import url('components/theme-toggle.css') layer(components);
    

4. Add the Toggle HTML

Add the following markup to the header or navigation area of every page on your site. This creates a disclosure widget with three radio options: light, system, and dark. The CSS :has() selectors in your colors.css detect which radio is checked and flip color-scheme accordingly.


        <details class="theme-menu">
            <summary class="theme-control">
                <span class="visually-hidden">Color scheme</span>
            </summary>
            <div class="theme-extra" role="group" aria-label="Choose color scheme">
                <label class="theme-control theme-pick" data-theme-pick="light">
                    <input name="theme-preference" type="radio" value="light">
                    <span aria-hidden="true">&#9788;&#65039;</span>
                    <span class="visually-hidden">Light</span>
                </label>
                <label class="theme-control theme-pick" data-theme-pick="system">
                    <input name="theme-preference" type="radio" value="system" checked>
                    <span aria-hidden="true">&#9881;&#65039;</span>
                    <span class="visually-hidden">System default</span>
                </label>
                <label class="theme-control theme-pick" data-theme-pick="dark">
                    <input name="theme-preference" type="radio" value="dark">
                    <span aria-hidden="true">&#127766;</span>
                    <span class="visually-hidden">Dark</span>
                </label>
            </div>
        </details>
    

Make sure you also have a .visually-hidden utility class in your css/utilities/utilities.css if you do not already. This hides the labels visually while keeping them accessible to screen readers:


        .visually-hidden {
            position: absolute;
            width: 1px;
            height: 1px;
            padding: 0;
            margin: -1px;
            overflow: hidden;
            clip-path: inset(50%);
            white-space: nowrap;
            border: 0;
        }
    

5. Add the Persistence Script

Without JavaScript, the toggle resets to the system default every time the page reloads. The script below reads localStorage, checks the matching radio before paint so there is no flash of the wrong theme, then registers a single document-level listener so any theme-preference radio the user activates later is saved under the same key.

Create js/theme-preference.js and paste the following:


        /**
         * Theme preference: restore on load (before paint) and persist on change.
         * Load in <head> WITHOUT defer or async.
         */
        (() => {
            const ALLOWED = new Set(['light', 'system', 'dark']);
            const id = 'theme-preference-sync';

            let container = document.getElementById(id);
            if (!container) {
                container = document.createElement('div');
                container.id = id;
                container.hidden = true;
                container.setAttribute('aria-hidden', 'true');

                ['light', 'system', 'dark'].forEach((v) => {
                    const input = document.createElement('input');
                    input.type = 'radio';
                    input.name = 'theme-preference';
                    input.value = v;
                    if (v === 'system') {
                        input.checked = true;
                    }
                    container.appendChild(input);
                });

                const mount = document.body ?? document.head;
                if (mount) {
                    mount.appendChild(container);
                }
            }

            let stored = null;
            try {
                stored = localStorage.getItem('theme-preference');
            } catch {
                /* storage may be disabled */
            }

            const value = ALLOWED.has(stored) ? stored : 'system';
            const input = container.querySelector(
                'input[value="' + value + '"]'
            );
            if (input) {
                input.checked = true;
            }

            document.addEventListener('change', (e) => {
                if (e.target.name === 'theme-preference') {
                    try {
                        localStorage.setItem('theme-preference', e.target.value);
                    } catch {
                        /* storage may be disabled */
                    }
                }
            });
        })();
    

Link it in the <head> of every page, before your stylesheet, without defer or async:

The required live shared sheet is css/main.css. If you are keeping a bundler, follow After This Assignment: Stop or Keep.


        <script src="js/theme-preference.js"></script>
        <link rel="stylesheet" href="css/main.css">
    

6. Roll Out Across Your Site

Go through every main page (not standalone pages with their own scoped styles) on your portfolio and replace hardcoded colors with your semantic tokens. Every background-color, color, border-color, and box-shadow should reference a --color-* token. Toggle between light and dark mode on each page and verify that nothing breaks, disappears, or becomes unreadable.

Pay special attention to text contrast. Light text on a light background or dark text on a dark background means a token is pointing to the wrong value for that mode. Use your browser's accessibility tools or a contrast checker to verify at least 4.5:1 contrast for body text in both themes.

7. Update Your Homepage and README

Your homepage should already link to your previous assignments. Make sure it also uses the new token system and that the theme toggle is visible and working. Update your README.md to note that the site now supports dark mode and briefly describe where the color tokens live.

8. Commit, Push, and Verify

Stage your changes, commit with a descriptive message, and push to GitHub. Verify that the deployment workflow succeeds and that your live site loads with both light and dark mode working. Test the toggle on at least two pages and confirm that the preference persists when you navigate between them.

Submission

Complete the report below with your site details and reflections. When you are finished, click the download button to generate a PDF and submit it to Canvas.

Color Tokens and Dark Mode Report
Site Details

My live portfolio homepage is at and the source code is at .

Reflection
Deriving Dark Mode Values

Your light-dark() tokens use your seed values for light mode and handpicked oklch() values for dark mode. But you also know how to derive colors automatically with color-mix(). Why not use color-mix() to generate the dark values from the seeds instead of choosing them by hand? What would you gain and what would you lose?

Understanding color-mix() Percentages

Look at these two lines from your ramp:


                --accent-200: color-mix(in oklch, var(--seed) 30%, white);
                --accent-400: color-mix(in oklch, var(--seed) 75%, white);
            

Step 200 is lighter than step 400, but its percentage is smaller. Explain what the percentage number actually represents and why a smaller number produces a lighter color when mixing with white.

Looking Back

Now that you have built a full color token system with dark mode, what is something you understand about CSS color that you did not understand before this unit? Be specific about the concept, not just the syntax.