# Gradients

## Essence

Approved gradient token whitelist for Portfolio Design System.

`Gradients` defines reusable multi-color treatments that are stronger than ordinary color tokens and need an explicit visual role.

## Hook

Use when a component needs a reusable brand or surface gradient rather than a flat color.

## Internal Rules

- Use existing `--gradient-*` tokens before adding local gradient CSS.
- Do not create a new gradient token without explicit approval.
- Gradient names must describe the role, not only the colors.
- Gradients are not substitutes for semantic color tokens.
- Components that animate gradients must own their own motion behavior and respect `prefers-reduced-motion`.
- Any text placed over a gradient must preserve readable contrast for every visible part of the gradient.

## Current Tokens

- `--gradient-brand`: balanced blue-pink-blue seamless gradient used by `Header Home Button`.
- `--gradient-brand-blue-dominant`: blue-dominant gradient with pink accent stops, used where blue should occupy roughly 80% of the animated cycle.

## Use When

- Rendering the temporary brand pill in `Header Home Button`.
- Rendering animated foreground masks where blue should dominate and pink should behave as a shorter accent.
- A repeated brand/surface treatment needs a shared token.

## Do Not Use When

- Setting ordinary text, background, border, or interaction state color.
- A gradient is one-off exploration without an approved reusable role.
- A component only needs Main Accent, Alt Accent, or inverse color behavior.

## Exception Rule

If a component needs a new gradient:

- explain the visual role;
- confirm why flat color tokens are not enough;
- propose a semantic `--gradient-*` name;
- ask for owner/design-system approval before adding it.

## Accessibility Notes

- Keep gradients dark or stable enough for foreground text.
- Avoid bright stops behind white text unless contrast is checked.
- Animated gradient consumers must disable animation for reduced-motion users.

## Related Components And Patterns

- `Header Home Button`: first consumer of `--gradient-brand`.
- `Icon and Label Button`: uses `--gradient-brand-blue-dominant` for its `Accent = animated` foreground treatment.
- `Colors`: owns flat semantic colors, not gradients.
- `Interaction States`: owns state derivations, not gradients.

## Code Paths

- `packages/design-system/src/styles/tokens.css`
- `packages/design-system/src/components/HeaderHomeButton.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`