diff --git a/AGENTS.md b/AGENTS.md
index 0043680..c5ddf45 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -256,10 +256,13 @@ Use `Avatar` with a required `name`; sizes are `sm`, `md`, and `lg`. Supply `src
### Alert
-Use `Alert` for persistent inline feedback. Tones are `info`, `warning`, `success`, and `danger`.
+Use `Alert` for persistent inline feedback. Tones are `info`, `warning`, `success`, and `danger`; variants are `default` and `subtle`.
- Use `danger` for failures that need immediate attention; it uses `role="alert"`.
+- Use `subtle` for persistent advisory regions such as danger zones that should communicate meaning without competing with current content. Subtle alerts use `role="status"` unless `role` is set explicitly.
- Use quieter tones for advisory state; they use `role="status"`.
+- Theme alert fills and borders with `--bits-alert-surface` and `--bits-alert-border`; do not target private `.bits-alert-*` selectors.
+- Pass `icon={null}` when the alert should have no marker. Subtle alerts otherwise use a compact, glyph-free marker by default.
- Provide a concrete recovery control through `action` when the user can resolve the condition.
- Do not use Alert for transient confirmation that is better handled by Toast.
- Do not use Toast as the only record of a blocking error.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 39eb981..59f91f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,11 +10,13 @@ this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
### Added
- Dialog block content, compact and medium sizes, and disabled/loading confirmation states for short form workflows.
+- A subtle Alert variant with derived low-emphasis surfaces, borders, and compact markers.
### Changed
- Dialog focus trapping now includes native select, textarea, editable, and explicitly tabbable controls.
- An open Select consumes Escape before a containing dialog closes.
+- Alert surfaces and borders can be themed through `--bits-alert-surface` and `--bits-alert-border`.
## 0.2.0 - 2026-09-02
diff --git a/README.md b/README.md
index d56e0f7..6e443f7 100644
--- a/README.md
+++ b/README.md
@@ -177,21 +177,30 @@ import { Segmented } from '@16-bits-design/ui/segmented';
### Alert
-Use `Alert` for persistent inline feedback that must remain available in the page. Danger alerts use `role="alert"`; info, warning, and success alerts use the quieter `role="status"`. Actions remain explicit composable controls.
+Use `Alert` for persistent inline feedback that must remain available in the page.
+The default variant uses a strong tone border for events that need attention now;
+use `variant="subtle"` for persistent advisory regions such as a danger zone.
+Subtle alerts use a compact marker and the quieter `role="status"`, including for
+the danger tone. Actions remain explicit composable controls.
```tsx
import { Alert } from '@16-bits-design/ui/alert';
import { Button } from '@16-bits-design/ui/button';
| Variable | Purpose | Fallback |
|---|---|---|
--bits-alert-surface | Alert background fill | --bits-raised, or a tone-derived wash for subtle alerts |
--bits-alert-border | Alert border color | The alert tone, or a weakened tone mix for subtle alerts |