# Shadows

## Essence

Approved shadow token whitelist for Portfolio Design System.

`Shadows` defines the approved elevation and crisp affordance treatments for surfaces, labels, and icons that need visual lift.

## Hook

Use when a surface needs elevation from its surrounding background.

## Internal Rules

- Use `--shadow-soft` before adding local soft `box-shadow` values.
- Use `--shadow-crisp-black` when inverse labels or icons need a hard black lift.
- Do not create a new shadow token without explicit approval.
- Shadow names must describe the role, not only the numeric value.
- Do not use shadows as separators when spacing or background grouping should do the job.
- Keep shadows compact enough that dense layouts do not feel heavy.

## Current Tokens

- `--shadow-soft`: soft lifted surface shadow used by cards and visual tiles.
- `--shadow-crisp-black`: hard black offset shadow used by inverse text/icon affordances.

## Use When

- A card or visual tile needs to lift from a secondary background surface.
- White text/icon affordances need a crisp black shadow on visual tiles.

## Do Not Use When

- A component only needs a border or background contrast.
- Elevation would make a repeated grid feel noisy.
- The surface is interactive focus feedback; use Interaction States instead.

## Code Paths

- `packages/design-system/src/styles/tokens.css`
- `packages/design-system/src/components/ArticleCard.astro`
- `packages/design-system/src/components/UseCaseItem.astro`
- `packages/design-system/src/components/UseCaseCard.astro`