# Link

> Slug: `link` · Category: Navigation

## When to use
- Navigating to another page, route, or external resource.
- Embedding a clickable reference inside a paragraph or sentence (use `inline`).
- Standalone calls-to-action that should look like a link, not a button (e.g. "Learn more", "Read details").

## When NOT to use
- For actions that change application state but don't navigate — use `<Button>` instead.
- For navigation styled as a button — use `LinkStyledAsButton`.
- For accordion/disclosure toggles — use `AccordionButton` or `Accordion`.

## Variants & decision tree
- **Block link** (`inline={false}`, default): standalone link with `size` (`large` | `medium` | `small`) and `alignment` (`left` | `center`). Use in cards, hero sections, or near a CTA group.
- **Inline link** (`inline={true}`): styled to flow inline with surrounding text (no size/alignment data attributes). Use inside paragraphs and `NoticeBar` body copy.
- **Monochrome**: removes the brand accent color — use when the link sits over imagery or branded panels and you need neutral coloring.

## States
Default · Hover · Focused · Pressed · Disabled (uses `aria-disabled`, not the native `disabled` attribute). `inverse` swaps to dark-background colors. Force-state classes (`hover`, `focused`, `pressed`) are for visual testing only.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `ReactNode` | — | Required link text content. |
| `href` | `string` | — | URL the link points to. |
| `inline` | `boolean` | `false` | Render inline (omits size/alignment). |
| `size` | `'large' \| 'medium' \| 'small'` | `'large'` | Block-mode size. |
| `alignment` | `'left' \| 'center'` | `'center'` | Block-mode alignment. |
| `disabled` | `boolean` | `false` | Sets `aria-disabled` and removes `href`. |
| `monochrome` | `boolean` | `false` | Neutral color treatment. |
| `inverse` | `boolean` | inherited | Dark-background styling. |
| `target` / `rel` / `hreflang` / `ping` / `referrerpolicy` | anchor attrs | — | Native anchor pass-throughs. |
| `a11yLabel` | `string` | — | `aria-label` override. |
| `describedBy` | `string` | — | `aria-describedby`. |

## Usage examples
```tsx
{/* Inline */}
<p>
  See our <Link inline label="terms of service" href="/terms" /> for details.
</p>

{/* Block */}
<Link label="Learn more" href="/plans" size="large" alignment="left" />
```

## Composition
Used inside `NoticeBar` (`linkLabel` + `href` props), card bodies, and supplementary action trays. Pair with `Button` when a primary action exists alongside.

## Accessibility
- Always pass meaningful `label` text — avoid "click here".
- For external links, pair `target="_blank"` with `rel="noopener noreferrer"`.
- `disabled` uses `aria-disabled`; the link still receives focus so screen readers can announce it.
- Use `a11yLabel` only when the visible label is ambiguous out of context.

## Do / Don't
- Do use `inline` inside paragraphs.
- Do prefer `Button` for actions that don't navigate.
- Don't combine with `onClick` to perform actions; use the `href`.
- Don't override `tdds-link*` classes — let `inverse`/`monochrome` props handle theming.
