``` ### Step 3: Test Icon and SVG Colors Icons using `currentColor` inherit from their parent's `color` property — they adapt automatically. Hardcoded `fill` or `stroke` values need dark variants: ```html Required ``` If you write a custom form element, mirror the token usage from `global.css`. ### Step 6: New Astro Component Template ```astro --- // src/components/MyComponent.astro interface Props { title: string; variant?: 'default' | 'accent'; } const { title, variant = 'default' } = Astro.props; ---

{title}

``` ### Step 7: Verify Contrast Before shipping a new component, verify text contrast in both themes: **Tools:** - [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) - Chrome DevTools → Elements → Computed → contrast ratio badge - Lighthouse accessibility audit **Minimum requirements:** - Body text: **4.5:1** (AA) - Large text (18px+ / 14px+ bold): **3:1** (AA) - Target: **7:1** (AAA) for critical text All semantic text tokens in this design system already meet AA or AAA — use them and you're covered. --- ## 6. Maintaining Theme Consistency ### The Golden Rules 1. **Never use raw hex colors in components** — always use `var(--color-*)` or Tailwind semantic classes 2. **Always add `dark:` variants** when using Tailwind utility classes for colors 3. **Test in both themes** before committing new UI 4. **Use the existing token names** — don't create new tokens unless there's a genuine gap ### Checking for Theme Consistency Issues Quick visual review process: 1. Open the site in a browser 2. Toggle to dark mode using the header button 3. Navigate all pages looking for: - White text on white background (contrast failure) - Very dark text on dark background (contrast failure) - Colorful decorative elements that disappeared (hidden in dark) - Form inputs that look broken 4. Repeat with `prefers-reduced-motion` enabled in DevTools ### Adding New Colors to the Token System 1. Add the primitive to `src/styles/design-tokens.css` in the `:root` block: ```css --palette-brand-new-500: #ff6b6b; ``` 2. Add the semantic token for both light and dark modes: ```css :root { --color-brand-new: var(--palette-brand-new-500); } html.dark { --color-brand-new: var(--palette-brand-new-400); /* adjust for dark bg */ } ``` 3. Extend `tailwind.config.mjs` if you need Tailwind utility class support: ```javascript colors: { 'brand-new': { 400: '#ff8e8e', 500: '#ff6b6b', } } ``` 4. Verify contrast in both themes before using. ### Don't Repeat Design Token Values If you find yourself writing the same color value in multiple places, extract it to a token. Tokens are the single source of truth — changing a token value updates every component that uses it. --- ## 7. Troubleshooting Guide ### Issue: Flash of wrong theme on page load (FOUC) **Symptoms**: Page briefly shows light mode before switching to dark (or vice versa). **Cause**: The inline blocking script in `BaseLayout.astro` is missing, disabled, or placed after CSS. **Fix**: Ensure the theme detection script is the **first** ` ``` --- ### Issue: Theme toggle button doesn't respond **Symptoms**: Clicking the sun/moon icon has no effect. **Diagnosis steps**: 1. Open browser DevTools → Console. Look for JavaScript errors. 2. Check that `[data-theme-toggle]` attribute exists on the button element. 3. Confirm `initThemeToggles()` ran — add `console.log` after the function call. **Common causes**: - The button HTML was modified and `data-theme-toggle` attribute was removed - A JavaScript error elsewhere in `