Shared Css Variables

Use the shared theme CSS variable vocabulary defined in site core cssVariables.md. Read that contract before creating or changing theme variables. Reuse its variables whenever their defined purposes match, define its required foundation, and use optional families where applicable. Prefer direct references to shared variables over component aliases: use var(--surfaceRaised) for a raised card rather than defining --cardSurface as another name for it. Discourage aliases that merely rename existing variables, including spacing and radius aliases; component ownership or hypothetical future overrides do not justify them. Optional component variables require a distinct semantic need that broader shared variables cannot represent. Each theme owns its values and appearance-mode overrides in its single variables.css file. Different values, matching colors, or a different visual style do not justify inventing variable names. When a reusable concept is missing, explain the proposed meaning, value type, consumers, and why existing variables are insufficient, then request approval before extending the shared contract. Update cssVariables.md with an approved extension before adopting it. Introduce a theme-specific variable only when the requirement is unique and the shared contract cannot reasonably be extended to support it; document its meaning and why both reuse and a shared extension are unsuitable in the theme documentation. Keep names semantic and camelCase, and preserve externally required names at integration boundaries.

Philosophy

A shared vocabulary makes themes easier to understand, maintain, and evolve while allowing distinct visual identities. Explicit meanings prevent accidental coupling between unrelated elements, and narrowly justified exceptions preserve room for unique designs.

Fix

Compare each variable with /home/dev/site/cssVariables.md. Replace redundant aliases with direct references to the matching shared variables, override values without changing meanings, propose reusable additions for approval, and document only justified theme-specific exceptions.