# CSS Variables — Allowed

This gauge covers Chapter 16 after the combined practical projects.

## Learning goal

Define reusable colour values with CSS custom properties, use them through
`var()`, and override them deliberately without losing readable contrast —
including following the system light/dark preference.

## Inherited tools

Everything allowed through `../phase10/allowed.md` remains available.

## New CSS

- Custom property declarations beginning with `--`
- The `:root` pseudo-class for document-wide values
- `var(--property-name)`
- `var(--property-name, fallback)`
- Custom property declarations on a component or theme container
- `@media (prefers-color-scheme: dark)` / `light` for token overrides (lesson 05)

## Learning rules

1. Use meaningful names such as `--color-surface` and `--color-text` that
   describe a role rather than one specific colour.
2. Put values in `:root` when the whole document should be able to use them.
3. Read a custom property with `var()`. Declaring a custom property alone does
   not apply it to any visual CSS property.
4. Custom properties participate in the cascade and normally inherit. A value
   declared on a nearer ancestor can override the same name from `:root`.
5. Keep related theme overrides together on one container class so descendants
   receive a coherent palette.
6. Use a fallback when a missing or invalid custom property would otherwise
   make a declaration invalid.
7. A fallback is used only when the referenced custom property is missing or
   invalid, not merely because its colour has weak contrast.
8. Re-check text, border, focus, hover, and active contrast after changing a
   palette. Variables reduce repetition but do not guarantee accessibility.
9. Avoid creating a variable for every single literal. Extract values that are
   repeated or represent a clear design role.
10. Prefer overriding the same role tokens under `prefers-color-scheme` rather
    than inventing a parallel set of dark-only property names.

## Not allowed

- JavaScript theme switching (system preference via media query is lesson 05)
- Custom properties that store spacing, sizing, typography, or motion values
  in lessons 01–03 (see Chapter 24 Design Tokens to lift this)
- Meaning communicated by colour alone
- Theme overrides that remove visible keyboard focus
- Inline styles for ordinary presentation (colours, margins, fonts)
- Any HTML tag, attribute, or CSS property not inherited or listed above

## Limited exception — HTML→CSS data channel

Lesson `04-html-data-channel.html` may use an inline `style` attribute **only**
to set custom properties (for example `style="--progress: 80%"`). Do not use
inline styles for ordinary colours or spacing in that lesson either — only the
data channel variable(s).

## Pages

- `01-root-palette.html` — define and use a document-wide colour palette
- `02-scoped-overrides.html` — override inherited variables inside components
- `03-fallback-theme.html` — use fallbacks in a reusable themed interface
- `04-html-data-channel.html` — pass per-instance values from HTML into CSS via `style="--…"`
- `05-prefers-color-scheme.html` — follow OS light/dark with token overrides

## Rules to lean on

Rules 2, 11–12, 43–45, 49–50, 121, 155–162, and 244.