# Colors

## Essence

Approved color token whitelist for Portfolio Design System.

`Colors` defines the only color values the Design System can use. New colors require an explicit question and Design System decision before implementation.

## Hook

Use whenever a component, token, page, preview, or artifact needs color.

## Internal Rules

- Use only existing `--color-*` tokens.
- Do not hardcode new hex, rgb, hsl, named, or alpha colors in component or app code.
- Do not create a new color token without explicit approval.
- If a new color seems necessary, stop and ask before implementation.
- Color choices should express semantic role, not decoration.
- Every color role owns a base token and an `-inverse` counterpart.
- `Inverse` selects an approved semantic counterpart for inverse surfaces; it is not a mathematical RGB inversion.
- Interaction state colors should consume color tokens through Focus & Interaction States.
- `--color-debug` is used only for debugging or marking places where a color is missing or undefined.

## Current Tokens

- `--color-bg: #ffffff / rgb(255, 255, 255)`.
- `--color-surface: #ffffff / rgb(255, 255, 255)`.
- `--color-text: #191b1f / rgb(25, 27, 31)`.
- `--color-secondary-text: #5c6470 / rgb(92, 100, 112)`.
- `--color-line: #b8c0ca / rgb(184, 192, 202)`.
- `--color-accent: #0b6bcb / rgb(11, 107, 203)`.
- `--color-accent-soft: #e5f1ff / rgb(229, 241, 255)`.
- `--color-success: #1f7a4d / rgb(31, 122, 77)`.
- `--color-warning: #9a5b00 / rgb(154, 91, 0)`.
- `--color-debug: #ff00ff / rgb(255, 0, 255)`.

## Inverse Tokens

- `--color-bg-inverse` resolves to `--color-text`.
- `--color-surface-inverse` resolves to `--color-text`.
- `--color-text-inverse` resolves to `--color-bg`.
- `--color-secondary-text-inverse` resolves to `--color-line`.
- `--color-line-inverse` resolves to `--color-secondary-text`.
- `--color-accent-inverse` resolves to `--color-accent-soft`.
- `--color-accent-soft-inverse` resolves to `--color-accent`.
- `--color-success-inverse` currently preserves `--color-success`.
- `--color-warning-inverse` currently preserves `--color-warning`.
- `--color-debug-inverse` preserves `--color-debug`.

## Use When

- Setting text color.
- Setting background or surface color.
- Setting border/line color.
- Setting accent/navigation/link color.
- Setting status color.
- Marking an undefined or missing color with debug color.

## Do Not Use When

- A component needs typography, spacing, layout, or interaction behavior instead of color.
- A color is purely decorative and not tied to a role.
- A new local color would bypass the approved token set.

## Exception Rule

If the approved color set cannot express the needed role:

- stop implementation;
- explain the missing role;
- propose whether an existing color token can cover it;
- if not, propose a new semantic color token;
- ask for user/design-system approval before adding or using it.

## Debug Color Rule

Use `--color-debug` only to:

- mark missing color decisions;
- make undefined component areas obvious;
- show placeholders that still need a real token or component decision.

Do not use `--color-debug` as production styling.

## Edge Cases

- Icons do not own color; the consuming component sets icon color.
- Typography does not own color; text components consume color tokens.
- Interaction tokens derive from color tokens.
- If a color repeats as a semantic role, propose a token instead of hardcoding it.

## Accessibility Notes

- Text and interactive states must preserve readable contrast.
- Status colors that preserve their base value in inverse mode require contrast validation in their consuming component.
- Debug color is intentionally loud and should not appear in finished UI.
- Do not communicate state by color alone when text, shape, or accessible names are needed.

## Related Components And Patterns

- `Typography`: text style foundation, not color.
- `Heading`, `Paragraph`, `Caption`, `Link`: consume text color tokens.
- `Focus & Interaction States`: consumes color tokens for state behavior.
- `Icons`: icons inherit color from consuming components.
- `Stub Object`: uses debug color as a placeholder signal.
- Individual color Essences define the semantic contract for each base/inverse pair.

## Code Paths

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