Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Banner): expose frame theme target (#6007)

freddymeta47a7ffbf3d47
diff --git a/.changeset/banner-frame-theme-target.md b/.changeset/banner-frame-theme-target.md
new file mode 100644
index 0000000000..23916cbb3e
--- /dev/null
+++ b/.changeset/banner-frame-theme-target.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Banner exposes a `banner-frame` theme target on the visible frame that owns whole-banner elevation and the elevated-card silhouette. The target reflects `container` and `elevation`; existing Banner targets and default rendering are unchanged.
+@freddymeta
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 5bd1de6b30..129e15eb81 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -4,7 +4,7 @@
"reason": "Banner renders a single wrap-capable flex header row — status icon, title/description column, and an end area pushed over with `marginInlineStart: 'auto'` — above an optional content panel. Its status, close and expand glyphs (`info`, `warning`, `error`, `success`, `close`, `chevronDown`) are all radially symmetric or vertical, and the expanded state rotates the chevron 180° about the block axis. Every inset, corner radius and border it draws is a logical property, so the whole banner mirrors under RTL with nothing positioned, ordered or animated along the inline axis for the audit to assert.",
"evidence": {
"apps/storybook/stories/Banner.stories.tsx": "sha256:15792a91bf7a7df1d6e15085cc42b9fc7f4df05135d09b6360b2a24ca2a6db5d",
- "packages/core/src/Banner/Banner.tsx": "sha256:a17ff3f61b7ee40a407373486366877684c650e7d08ae9fc2d8606c0bae9de66",
+ "packages/core/src/Banner/Banner.tsx": "sha256:d69e58bc792b8c8802311aacd7b629c890915424f5b575d3bb3f71645db9c77f",
"packages/core/src/Banner/index.ts": "sha256:64591b4c3a37ae382a910fc9314300c3045bf8d602b28cc60a681d7b8f3a17f6"
}
},
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index 8c56970eb2..8895e7f958 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -129,6 +129,7 @@ export const docs = {
},
theming: {
targets: [
+ {className: 'astryx-banner-frame', visualProps: ['container', 'elevation']},
{className: 'astryx-banner', visualProps: ['container', 'status']},
{className: 'astryx-banner-icon', visualProps: ['status']},
{className: 'astryx-banner-description'},
@@ -191,6 +192,13 @@ export const docsZh = {
],
theming: {
targets: [
+ {
+ className: 'astryx-banner-frame',
+ visualProps: [
+ 'container',
+ 'elevation',
+ ],
+ },
{
className: 'astryx-banner',
visualProps: [
diff --git a/packages/core/src/Banner/Banner.spec.md b/packages/core/src/Banner/Banner.spec.md
index e936c6750c..1760d3070b 100644
--- a/packages/core/src/Banner/Banner.spec.md
+++ b/packages/core/src/Banner/Banner.spec.md
@@ -34,9 +34,8 @@ system_specs: []
## Intent
Banner presents a persistent status message at the top of a page or section.
-This contract records the current painted surfaces and admits the Banner frame as
-a separately targetable surface. Runtime implementation follows in a separate
-change; the existing status and content targets remain unchanged.
+This contract records the current painted surfaces and the Banner frame as a
+separately targetable surface. The status and content targets remain unchanged.
## Compatibility and migration
@@ -75,18 +74,18 @@ prop vocabulary or extensibility rule changes.
## Behavioral and layout contract
-The requirements below distinguish current implementation from the approved
-additive target contract.
+The requirements below describe the current implementation and its additive
+frame target contract.
-| ID | Invariant | Basis | Contract state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------- |
-| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`. | Current source, public docs, and tests | Current behavior |
-| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`. | Current source and tests | Current behavior |
-| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style. | Current source and elevation tests | Current behavior |
-| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners. | Current source | Current behavior |
-| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius. | Current compiler output and CSS inheritance | Current reachability gap |
-| FR6 | The Banner frame MUST expose `banner-frame` and reflect `container` and `elevation`. The existing `banner` target MUST remain on the Status surface rather than move to the outermost DOM element. | Owner decision; `component:Banner/DEC-1` | Current contract; implementation pending |
-| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes MUST remain unchanged. | Current target inventory; compatibility policy | Current contract; implementation pending |
+| ID | Invariant | Basis | Contract state |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------ |
+| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`. | Current source, public docs, and tests | Current behavior |
+| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`. | Current source and tests | Current behavior |
+| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style. | Current source and elevation tests | Current behavior |
+| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners. | Current source | Current behavior |
+| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius. | Current compiler output and CSS inheritance | Current reachability gap |
+| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element. | Owner decision; current source and tests | Current behavior |
+| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged. | Current target inventory; compatibility policy | Current behavior |
### Allowed variation
@@ -145,11 +144,7 @@ unqualified `banner` target.
```json
{
- "Banner frame": {
- "none": {
- "reason": "reachability-gap: The approved banner-frame target is not yet emitted or documented by the runtime implementation."
- }
- },
+ "Banner frame": {"target": "banner-frame"},
"Status surface": {"target": "banner"},
"Icon": {"target": "banner-icon"},
"Title": {"inherits": "banner"},
@@ -164,10 +159,9 @@ unqualified `banner` target.
}
```
-This map records current runtime reachability. `banner` belongs to the primary
-Status surface rather than the outermost DOM element. DEC-1 admits the Banner
-frame under `banner-frame`; its temporary `none` disposition is therefore a
-reachability gap that the implementation change must close.
+This map records runtime reachability. `banner` belongs to the primary Status
+surface rather than the outermost DOM element, while `banner-frame` belongs to
+the visible frame that owns whole-banner elevation and silhouette.
## Family and system relationships
@@ -180,13 +174,13 @@ reachability gap that the implementation change must close.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | -------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| FR1, FR7 | `Banner.test.tsx` and `themingTargets.test.ts` | Status surface, content surface, current target axes | Moving, removing, or changing an existing target breaks current assertions. | `audit:Banner/theming` |
-| FR2, FR3, FR4 | `Banner.test.tsx` plus current source inspection | Flat/elevated card and elevated section | Frame, status surface, content surface, shadow, or radius ownership changes from the recorded state. | `audit:Banner/surfaces` |
-| FR5 | Compiler output plus browser/computed-style evidence | Card with and without content; elevated card | `banner.borderRadius` unexpectedly reaches the frame/content, or docs claim that the current route already does. | `audit:Banner/radius` |
-| FR6, FR7 | Implementation PR target, compiler, probe, and component tests | Card/section across none, low, med, and high elevation | `banner-frame` is absent, uses another name, misses an axis, or moves the existing `banner` target. | `audit:Banner/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Eight anatomy entries and four currently emitted targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:Banner/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1, FR7 | `Banner.test.tsx` and `themingTargets.test.ts` | Status surface, content surface, current target axes | Moving, removing, or changing an existing target breaks current assertions. | `audit:Banner/theming` |
+| FR2, FR3, FR4 | `Banner.test.tsx` plus current source inspection | Flat/elevated card and elevated section | Frame, status surface, content surface, shadow, or radius ownership changes from the recorded state. | `audit:Banner/surfaces` |
+| FR5 | Compiler output plus browser/computed-style evidence | Card with and without content; elevated card | `banner.borderRadius` unexpectedly reaches the frame/content, or docs claim that the current route already does. | `audit:Banner/radius` |
+| FR6, FR7 | Implementation PR target, compiler, probe, and component tests | Card/section across none, low, med, and high elevation | `banner-frame` is absent, uses another name, misses an axis, or moves the existing `banner` target. | `audit:Banner/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Eight anatomy entries and five current targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:Banner/theming` |
## Decision log
diff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsx
index 0ba4d2d4f9..98d19b2592 100644
--- a/packages/core/src/Banner/Banner.test.tsx
+++ b/packages/core/src/Banner/Banner.test.tsx
@@ -4,7 +4,8 @@
* @file Banner.test.tsx
* @input Uses vitest, @testing-library/react, Banner component
* @output Unit tests for Banner component behavior, including the
- * 'banner-icon' theme target riding on the status icon glyph (#4166)
+ * 'banner-frame' theme target on the outer elevation/radius painter and the
+ * 'banner-icon' theme target on the status icon glyph (#4166)
* @position Testing; validates Banner.tsx implementation
*
* SYNC: When modified, update this header
@@ -14,6 +15,7 @@ import {describe, it, expect, vi, afterEach} from 'vitest';
import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Banner} from './Banner';
+import {defineTheme, generateThemeCSS} from '../theme';
import {registerIcons, resetIcons} from '../Icon';
import {InternationalizationProvider} from '../i18n';
@@ -511,6 +513,57 @@ describe('Banner', () => {
});
describe('elevation', () => {
+ it("carries the 'banner-frame' target and its visual axes on the outer painter", () => {
+ const containers = ['card', 'section'] as const;
+ const elevations = ['none', 'low', 'med', 'high'] as const;
+
+ for (const containerType of containers) {
+ for (const elevation of elevations) {
+ const {container, unmount} = render(
+ <Banner
+ status="info"
+ title="Heads up"
+ container={containerType}
+ elevation={elevation}
+ />,
+ );
+ const frame = container.firstElementChild;
+ expect(frame).toHaveClass(
+ 'astryx-banner-frame',
+ containerType,
+ elevation,
+ );
+ expect(frame).toHaveAttribute('data-container', containerType);
+ expect(frame).toHaveAttribute('data-elevation', elevation);
+ expect(frame?.firstElementChild).toHaveClass('astryx-banner');
+ expect(frame?.firstElementChild).not.toHaveClass(
+ 'astryx-banner-frame',
+ );
+ unmount();
+ }
+ }
+ });
+
+ it('lets a theme set frame shadow and radius without a structural selector', () => {
+ const theme = defineTheme({
+ name: 'banner-frame-test',
+ components: {
+ 'banner-frame': {
+ 'container:card+elevation:high': {
+ boxShadow: 'var(--shadow-high)',
+ borderRadius: 'var(--radius-element)',
+ },
+ },
+ },
+ });
+ const {component: css} = generateThemeCSS(theme);
+
+ expect(css).toContain('.astryx-banner-frame.card.high');
+ expect(css).toContain('box-shadow: var(--shadow-high)');
+ expect(css).toContain('border-radius: var(--radius-element)');
+ expect(css).not.toContain(':has(');
+ });
+
it('renders a distinct root class for each elevation level', () => {
const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
const {container} = render(
diff --git a/packages/core/src/Banner/Banner.tsx b/packages/core/src/Banner/Banner.tsx
index 864908e76f..85c0f9c474 100644
--- a/packages/core/src/Banner/Banner.tsx
+++ b/packages/core/src/Banner/Banner.tsx
@@ -9,7 +9,8 @@
* @position Core implementation; consumed by index.ts, tested by Banner.test.tsx
*
* Visual structure:
- * - Root container: layout-only wrapper (flex column), no visual styling, no theme target
+ * - Banner frame (themeProps 'banner-frame'): owns the resting elevation and,
+ * for elevated card banners, the outer radius that shapes that shadow
* - Header area (themeProps 'banner'): colored status background with icon, title, description, actions, dismiss
* - Content area (themeProps 'banner-content'): card background for additional content (children)
* - Status icon (themeProps 'banner-icon'): the target rides on the default
@@ -226,7 +227,7 @@ const statusIconColor: Partial<Record<BannerStatus, IconColor>> = {
// =============================================================================
const styles = stylex.create({
- // Root container — layout only, no visual styling
+ // Root container — outer elevation and elevated-card radius painter
root: {
display: 'flex',
flexDirection: 'column',
@@ -577,6 +578,7 @@ export function Banner({
handlePointerDownCapture,
)}
{...mergeProps(
+ themeProps('banner-frame', {container, elevation}),
stylex.props(
styles.root,
elevationStyles[elevation],
diff --git a/packages/themes/probe/src/probeTheme.ts b/packages/themes/probe/src/probeTheme.ts
index d77e82f94a..49fd142399 100644
--- a/packages/themes/probe/src/probeTheme.ts
+++ b/packages/themes/probe/src/probeTheme.ts
@@ -6,7 +6,7 @@
// test fixture. Regenerate with: pnpm visual:probe-theme
//
// defineTheme takes six things and this covers all six:
-// components 274 targets, 885 selectors (generated from the docs)
+// components 277 targets, 898 selectors (generated from the docs)
// tokens custom properties, read back off the themed element
// icons every registry entry swapped for a marked glyph
// indicators check / radio / checkbox swapped — the swap that reaches furthest
@@ -586,6 +586,50 @@ export const probeTheme = defineTheme({
outlineColor: 'hsl(35.6 93% 25%)',
},
},
+ 'banner-frame': {
+ base: {
+ backgroundColor: 'hsl(25.7 70% 48%)',
+ color: 'hsl(251.7 82% 12%)',
+ borderColor: 'hsl(334.6 70% 25%)',
+ outlineColor: 'hsl(51.5 85% 25%)',
+ },
+ 'container:card': {
+ backgroundColor: 'hsl(314.7 89% 46%)',
+ color: 'hsl(112.0 92% 12%)',
+ borderColor: 'hsl(10.8 90% 25%)',
+ outlineColor: 'hsl(162.5 70% 25%)',
+ },
+ 'container:section': {
+ backgroundColor: 'hsl(16.1 83% 50%)',
+ color: 'hsl(305.4 91% 12%)',
+ borderColor: 'hsl(67.5 85% 25%)',
+ outlineColor: 'hsl(233.6 86% 25%)',
+ },
+ 'elevation:none': {
+ backgroundColor: 'hsl(315.3 93% 58%)',
+ color: 'hsl(195.7 86% 12%)',
+ borderColor: 'hsl(182.2 90% 25%)',
+ outlineColor: 'hsl(265.5 79% 25%)',
+ },
+ 'elevation:low': {
+ backgroundColor: 'hsl(284.0 78% 47%)',
+ color: 'hsl(172.7 94% 12%)',
+ borderColor: 'hsl(53.0 72% 25%)',
+ outlineColor: 'hsl(203.0 93% 25%)',
+ },
+ 'elevation:med': {
+ backgroundColor: 'hsl(138.9 75% 47%)',
+ color: 'hsl(78.8 92% 12%)',
+ borderColor: 'hsl(238.6 87% 25%)',
+ outlineColor: 'hsl(142.1 93% 25%)',
+ },
+ 'elevation:high': {
+ backgroundColor: 'hsl(252.5 72% 55%)',
+ color: 'hsl(117.7 77% 12%)',
+ borderColor: 'hsl(330.0 77% 25%)',
+ outlineColor: 'hsl(12.3 88% 25%)',
+ },
+ },
'banner-icon': {
base: {
backgroundColor: 'hsl(262.3 84% 51%)',
@@ -4585,6 +4629,22 @@ export const probeTheme = defineTheme({
outlineColor: 'hsl(94.7 77% 25%)',
},
},
+ 'stepper-frame': {
+ base: {
+ backgroundColor: 'hsl(220.4 78% 60%)',
+ color: 'hsl(124.6 78% 12%)',
+ borderColor: 'hsl(219.2 77% 25%)',
+ outlineColor: 'hsl(209.9 87% 25%)',
+ },
+ },
+ 'stepper-summary': {
+ base: {
+ backgroundColor: 'hsl(56.5 79% 47%)',
+ color: 'hsl(163.3 90% 12%)',
+ borderColor: 'hsl(253.4 72% 25%)',
+ outlineColor: 'hsl(238.5 80% 25%)',
+ },
+ },
switch: {
base: {
backgroundColor: 'hsl(355.8 75% 58%)',
@@ -5488,6 +5548,30 @@ export const probeTheme = defineTheme({
borderColor: 'hsl(260.2 75% 25%)',
outlineColor: 'hsl(14.9 76% 25%)',
},
+ 'elevation:none': {
+ backgroundColor: 'hsl(55.4 88% 60%)',
+ color: 'hsl(28.2 76% 12%)',
+ borderColor: 'hsl(276.0 80% 25%)',
+ outlineColor: 'hsl(245.4 91% 25%)',
+ },
+ 'elevation:low': {
+ backgroundColor: 'hsl(243.3 91% 61%)',
+ color: 'hsl(328.4 93% 12%)',
+ borderColor: 'hsl(96.5 91% 25%)',
+ outlineColor: 'hsl(237.2 83% 25%)',
+ },
+ 'elevation:med': {
+ backgroundColor: 'hsl(98.3 88% 61%)',
+ color: 'hsl(125.6 75% 12%)',
+ borderColor: 'hsl(195.0 93% 25%)',
+ outlineColor: 'hsl(298.1 83% 25%)',
+ },
+ 'elevation:high': {
+ backgroundColor: 'hsl(118.2 84% 63%)',
+ color: 'hsl(163.2 82% 12%)',
+ borderColor: 'hsl(50.2 88% 25%)',
+ outlineColor: 'hsl(32.5 75% 25%)',
+ },
isPressed: {
backgroundColor: 'hsl(134.4 77% 49%)',
color: 'hsl(197.7 74% 12%)',