newspack-components 4.7.0 → 4.8.0

package/src/card-feature/README.md

@@ -15,11 +15,11 @@ Cards sit side by side, so a bare "Enable" names no feature out of context. The
 
 | State | Condition | Button | Dropdown | Badge |
 |---|---|---|---|---|
-| **Unmet requirements** | `requirements` is set | "Enable" — disabled (clickable if `requirementsActionable`) | Shown if `enabled` and `requirementsActionable` (and `moreControls` provided); otherwise hidden | Error badge with `requirements` text |
+| **Unmet requirements** | `requirements` is set | "Enable" — blocked but still focusable, and described by the badge (clickable if `requirementsActionable`) | Shown if `enabled` and `requirementsActionable` (and `moreControls` provided); otherwise hidden | High-intent badge with `requirements` text |
 | **Disabled** | `!enabled`, no requirements | "Enable" | Hidden | None |
-| **Enabled** | `enabled`, no requirements | "Configure" | Shown if `moreControls` provided | Success badge ("Enabled") |
+| **Enabled** | `enabled`, no requirements | "Configure" | Shown if `moreControls` provided | Stable-intent badge ("Enabled") |
 
-The card content (title + description) is visually muted (gray text, lighter border) when `requirements` is set.
+When `requirements` is set the title drops to the muted text colour. The description already uses that colour in every state, so the unmet-requirements state is signalled by the title colour plus the high-intent badge.
 
 ## Basic usage
 
@@ -40,7 +40,21 @@ import { __ } from '@wordpress/i18n';
 
 ## With unmet requirements
 
-When `requirements` is set the button is disabled and an error badge displays the string. The title and description are visually muted.
+When `requirements` is set, a high-intent badge displays the string and the title drops to the muted text colour. By default the requirement is treated as locked: the button is blocked and the "More" dropdown is hidden, so `onEnable` and `moreControls` have nothing to act on. `onConfigure` is unreachable whenever `requirements` is set at all, locked or not, because the button only reads "Configure" when there is no outstanding requirement.
+
+A blocked button keeps its place in the tab order and is described by the high-intent badge, so a keyboard or screen-reader user reaches it and hears why it will not act. Don't wrap it in your own `disabled` handling, which would undo that.
+
+```tsx
+import { __ } from '@wordpress/i18n';
+
+<CardFeature
+	title={ __( 'Metered countdown', 'newspack-plugin' ) }
+	description={ __( 'Show a countdown banner letting readers know how many free views they have left.', 'newspack-plugin' ) }
+	requirements={ __( 'Requires an API-based ESP', 'newspack-plugin' ) }
+/>
+```
+
+Set `requirementsActionable` when the button is how the reader clears the requirement. It stays clickable and routes to `onEnable`, and an enabled card keeps its "More" dropdown so the feature can still be turned off.
 
 ```tsx
 import { __ } from '@wordpress/i18n';
@@ -50,8 +64,9 @@ import { __ } from '@wordpress/i18n';
 	description={ __( 'Show a countdown banner letting readers know how many free views they have left.', 'newspack-plugin' ) }
 	enabled={ isEnabled }
 	requirements={ __( 'Requires metering', 'newspack-plugin' ) }
-	onEnable={ () => setEnabled( true ) }
-	onConfigure={ () => history.push( '/settings/countdown' ) }
+	requirementsActionable
+	enableLabel={ __( 'Set up metering', 'newspack-plugin' ) }
+	onEnable={ () => history.push( '/settings/metering' ) }
 	moreControls={ [
 		{ title: __( 'Disable', 'newspack-plugin' ), onClick: () => setEnabled( false ) },
 	] }
@@ -60,35 +75,50 @@ import { __ } from '@wordpress/i18n';
 
 ## With a custom icon
 
-The `icon` prop accepts an object, not a bare node. Pass `node` for the icon element, `fill` to control the SVG colour (applied via `currentColor`), `backgroundColor` for a container background, and `radius` for the corner treatment.
+`icon` takes either a descriptor object or a ready React element. A descriptor gets the standard treatment: pass `node` for the icon element, `fill` for the SVG colour, `backgroundColor` for a container background, and `radius` for the corner treatment. A ready element renders exactly as given, with no container, background or radius, which is the escape hatch for an icon that already carries its own chrome.
+
+A descriptor's container is always **40 × 40 px** with the SVG at **24 × 24 px**. Setting `backgroundColor` without a `radius` gives 2px corners; pass `radius: 'full'` for a circle.
 
-The icon container is always **40 × 40 px** with the SVG at **24 × 24 px**. `radius` only applies when `backgroundColor` is set.
+`fill` sets the container's `color`, which the SVG picks up through `fill: currentcolor`. That only recolours single-colour icons that inherit their fill, such as those from `@wordpress/icons`. A vendor's own mark carries `fill` on its paths and keeps its colours, so pair it with `backgroundColor` rather than trying to tint it.
+
+`fill` and `backgroundColor` take any CSS colour. Reach for the Newspack palette when the icon should read as ours, and pass a literal when it should carry a third party's colour.
 
 ```tsx
 import { __ } from '@wordpress/i18n';
 import { Icon, starFilled } from '@wordpress/icons';
+import colors from 'newspack-colors';
 
-// Icon with fill only
+// Newspack palette, fill only
 <CardFeature
 	title={ __( 'Content gifting', 'newspack-plugin' ) }
 	description={ __( 'Let subscribers share gated articles with non-subscribers.', 'newspack-plugin' ) }
-	icon={ { node: <Icon icon={ starFilled } />, fill: '#003da5' } }
+	icon={ { node: <Icon icon={ starFilled } />, fill: colors[ 'primary-600' ] } }
 	enabled={ isEnabled }
 	onEnable={ handleEnable }
 	onConfigure={ handleConfigure }
 	moreControls={ [ { title: __( 'Disable', 'newspack-plugin' ), onClick: handleDisable } ] }
 />
 
-// Icon with circular background
+// A vendor mark on its own brand background, keeping the mark's colours
 <CardFeature
-	title={ __( 'Content gifting', 'newspack-plugin' ) }
-	description={ __( 'Let subscribers share gated articles with non-subscribers.', 'newspack-plugin' ) }
-	icon={ { node: <Icon icon={ starFilled } />, fill: '#003da5', backgroundColor: '#dfe7f4', radius: 'full' } }
+	title={ __( 'Mailchimp', 'newspack-plugin' ) }
+	description={ __( 'Sync reader activity with your Mailchimp audience.', 'newspack-plugin' ) }
+	icon={ { node: <MailchimpMark />, backgroundColor: '#ffe01b', radius: 'full' } }
 	enabled={ isEnabled }
 	onEnable={ handleEnable }
 	onConfigure={ handleConfigure }
 	moreControls={ [ { title: __( 'Disable', 'newspack-plugin' ), onClick: handleDisable } ] }
 />
+
+// A ready element, rendered as-is
+<CardFeature
+	title={ __( 'Mailchimp', 'newspack-plugin' ) }
+	description={ __( 'Sync reader activity with your Mailchimp audience.', 'newspack-plugin' ) }
+	icon={ <IntegrationIcon provider="mailchimp" /> }
+	enabled={ isEnabled }
+	onEnable={ handleEnable }
+	onConfigure={ handleConfigure }
+/>
 ```
 
 ## With custom button labels
@@ -112,7 +142,7 @@ import { __ } from '@wordpress/i18n';
 
 ## With a custom badge
 
-Override `badgeText` and `badgeLevel` to change the badge shown when the feature is enabled. Available levels: `default`, `info`, `success`, `warning`, `error`.
+Override `badge` to change the badge shown when the feature is enabled. See [`BadgeIntent`](../types.ts) for the available intents.
 
 ```tsx
 import { __ } from '@wordpress/i18n';
@@ -121,8 +151,7 @@ import { __ } from '@wordpress/i18n';
 	title={ __( 'Stripe', 'newspack-plugin' ) }
 	description={ __( 'Accept payments via Stripe.', 'newspack-plugin' ) }
 	enabled={ isEnabled }
-	badgeText={ __( 'Live mode', 'newspack-plugin' ) }
-	badgeLevel="info"
+	badge={ { label: __( 'Live mode', 'newspack-plugin' ), intent: 'informational' } }
 	onEnable={ handleEnable }
 	onConfigure={ () => history.push( '/settings/stripe' ) }
 	moreControls={ [ { title: __( 'Disable', 'newspack-plugin' ), onClick: handleDisable } ] }
@@ -150,23 +179,34 @@ import { __ } from '@wordpress/i18n';
 />
 ```
 
+## What the layout rests on
+
+The card is built on `Card.Root`, `Card.Header` and `Card.Content` from `@wordpress/ui`. Three things about that pairing decide how it renders.
+
+**Cards in a row bottom-align their action rows.** `Card.Root` is `display: flex; flex-direction: column`, and `.newspack-card-feature__actions` takes `margin-top: auto`. Two cards with descriptions of different lengths still put their buttons on one baseline. No test covers this, because jsdom computes no layout. If a library update drops the column direction, the cards stop aligning and nothing fails.
+
+**The action row sits in `Card.Content`, which the library documents as the main content area.** The description sits in `Card.Header`, so the two are inverted. The gap between them lands at zero while `--wpds-dimension-gap-xl` and `--wpds-dimension-padding-2xl` are both 24px, and `margin-top: auto` is unlayered, so it wins over the library's layered rule either way. Move the action row when the library ships a `Card.Footer`.
+
+**The title keeps its own type size.** `Card.Title` renders at `heading-lg`, which is 15px, and this title is 20px. It uses `heading-x-large()` from `@wordpress/base-styles` instead. Switch to `<Card.Title render={ createElement( 'h3' ) }>` if the two sizes ever agree.
+
 ## Props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `title` | `string` | — | Card heading (**required**) |
+| `headingLevel` | `2`–`6` | `3` | Heading level for the title. The default sits under a `SectionHeader` or a `WizardsTab` heading, both of which are h2. Raise it when the cards sit under a deeper section label |
 | `description` | `string` | — | Supporting text below the title |
-| `icon` | `CardFeatureIcon` | — | Icon displayed on the right. See `CardFeatureIcon` below. |
+| `icon` | `CardFeatureIcon \| ReactElement` | — | Icon displayed on the right. A descriptor gets the 40 × 40 container; a ready element renders as-is. See `CardFeatureIcon` below. |
 | `enabled` | `boolean` | `false` | Whether the feature is currently enabled |
-| `requirements` | `string` | — | When set, enters the unmet-requirements state; value is used as the error badge text |
+| `requirements` | `string` | — | When set, enters the unmet-requirements state. The value is the high-intent badge text and the primary button's accessible description, so write it to read sensibly after the button's label |
 | `requirementsActionable` | `boolean` | `false` | When `requirements` is set, keep the primary button clickable so it can remediate the unmet requirement, and keep the "More" dropdown visible on an enabled card (degraded but still operable) |
-| `enableLabel` | `string` | `"Enable"` | Primary button label when not enabled |
-| `configureLabel` | `string` | `"Configure"` | Primary button label when enabled |
-| `onEnable` | `() => void` | — | Called when the primary button is clicked and the feature is not enabled |
-| `onConfigure` | `() => void` | — | Called when the primary button is clicked and the feature is enabled |
+| `enableLabel` | `string` | `"Enable"` | Label for the primary button in its "Enable" states: not enabled, or enabled with an unmet requirement |
+| `configureLabel` | `string` | `"Configure"` | Label for the primary button in its "Configure" state: enabled, with no unmet requirement |
+| `onEnable` | `() => void` | — | Called when the primary button is clicked while it reads "Enable". That covers the not-enabled case and the enabled-with-unmet-requirements case, where the feature is on but the requirement is what the button acts on |
+| `onConfigure` | `() => void` | — | Called when the primary button is clicked while it reads "Configure", which is the enabled state with no unmet requirements |
 | `moreControls` | `MoreControl[]` | — | Items for the "More" dropdown. Shown when `enabled` and either there are no `requirements` or `requirementsActionable` is set |
-| `badgeText` | `string` | `"Enabled"` | Badge text shown when enabled |
-| `badgeLevel` | `BadgeLevel` | `"success"` | Badge level shown when enabled |
+| `badge` | `{ label?: string; intent?: BadgeIntent }` | `{ label: "Enabled", intent: "stable" }` | Badge shown when enabled. Ignored while `requirements` is set, which takes the badge |
+| `busy` | `boolean` | `false` | Shows the primary button as busy and blocks it while an action is in flight |
 | `className` | `string` | — | Additional class name applied to the card element |
 
 ### `CardFeatureIcon`
@@ -177,7 +217,8 @@ type CardFeatureIcon = {
 	fill?: string;               // SVG fill colour (applied via currentColor)
 	backgroundColor?: string;    // Background colour of the 40×40 container
 	radius?: 'small' | 'full';   // 'small' = 2px ($radius-small), 'full' = 50% ($radius-round)
-	                             // Only applied when backgroundColor is set.
+	                             // Defaults to 'small' whenever backgroundColor is set,
+	                             // and has nothing to round without one.
 };
 ```
 
@@ -187,6 +228,6 @@ type CardFeatureIcon = {
 type MoreControl = {
 	title: string;
 	onClick: () => void;
-	icon?: React.ReactNode;
+	icon?: JSX.Element;
 };
 ```

package/src/card-feature/index.test.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies.
  */
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 
 /**
  * WordPress dependencies.
@@ -20,46 +20,261 @@ jest.mock( '@wordpress/i18n', () => {
 	return { ...actual, _x: jest.fn( text => text ) };
 } );
 
+const primaryButton = () => screen.getByRole( 'button', { name: /Enable|Configure/ } );
+const moreMenu = () => screen.queryByRole( 'button', { name: /^More options for/ } );
+
 describe( 'CardFeature', () => {
 	beforeEach( () => {
 		_x.mockClear();
 	} );
 
-	it( 'names the feature in the primary button, keeping the visible label first', () => {
-		render( <CardFeature title="Metered Countdown" /> );
-		const button = screen.getByRole( 'button', { name: 'Enable Metered Countdown' } );
-		expect( button ).toHaveTextContent( 'Enable' );
-		expect( button.getAttribute( 'aria-label' ).startsWith( button.textContent ) ).toBe( true );
+	describe( 'structure', () => {
+		it( 'renders the title as a level-3 heading and the description alongside it', () => {
+			render( <CardFeature title="Content gifting" description="Let subscribers share gated articles." /> );
+			expect( screen.getByRole( 'heading', { level: 3 } ) ).toHaveTextContent( 'Content gifting' );
+			expect( screen.getByText( 'Let subscribers share gated articles.' ) ).toBeInTheDocument();
+		} );
+
+		it( 'renders the title at the requested heading level', () => {
+			render( <CardFeature title="Content gifting" headingLevel={ 4 } /> );
+			expect( screen.getByRole( 'heading', { level: 4 } ) ).toHaveTextContent( 'Content gifting' );
+			expect( screen.queryByRole( 'heading', { level: 3 } ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'omits the description paragraph when none is passed', () => {
+			const { container } = render( <CardFeature title="Content gifting" /> );
+			expect( container.querySelector( '.newspack-card-feature__description' ) ).toBeNull();
+		} );
 	} );
 
-	it( 'carries a custom label into the accessible name', () => {
-		render( <CardFeature title="Subscription retention" enableLabel="Change" /> );
-		expect( screen.getByRole( 'button', { name: 'Change Subscription retention' } ) ).toHaveTextContent( 'Change' );
+	describe( 'accessible names', () => {
+		it( 'names the feature in the primary button, keeping the visible label first', () => {
+			render( <CardFeature title="Metered Countdown" /> );
+			const button = screen.getByRole( 'button', { name: 'Enable Metered Countdown' } );
+			expect( button ).toHaveTextContent( 'Enable' );
+			expect( button.getAttribute( 'aria-label' ).startsWith( button.textContent ) ).toBe( true );
+		} );
+
+		it( 'carries a custom label into the accessible name', () => {
+			render( <CardFeature title="Subscription retention" enableLabel="Change" /> );
+			expect( screen.getByRole( 'button', { name: 'Change Subscription retention' } ) ).toHaveTextContent( 'Change' );
+		} );
+
+		it( 'names the feature in the configure state too', () => {
+			render( <CardFeature title="Content Gifting" enabled /> );
+			expect( screen.getByRole( 'button', { name: 'Configure Content Gifting' } ) ).toBeInTheDocument();
+		} );
+
+		it( 'names the feature in the More menu', () => {
+			render( <CardFeature title="Content Gifting" enabled moreControls={ [ { title: 'Disable', onClick: () => {} } ] } /> );
+			expect( screen.getByRole( 'button', { name: 'More options for Content Gifting' } ) ).toBeInTheDocument();
+		} );
+
+		it( 'gives the accessible-name order its own catalogue entry', () => {
+			render( <CardFeature title="Metered Countdown" /> );
+			expect( _x ).toHaveBeenCalledWith( '%1$s %2$s', 'accessible button name: visible action label, then feature name', 'newspack-plugin' );
+		} );
+
+		it( 'distinguishes two cards that share a button label', () => {
+			render(
+				<>
+					<CardFeature title="Metered Countdown" />
+					<CardFeature title="Content Gifting" />
+				</>
+			);
+			expect( screen.getByRole( 'button', { name: 'Enable Metered Countdown' } ) ).toBeInTheDocument();
+			expect( screen.getByRole( 'button', { name: 'Enable Content Gifting' } ) ).toBeInTheDocument();
+		} );
 	} );
 
-	it( 'names the feature in the configure state too', () => {
-		render( <CardFeature title="Content Gifting" enabled /> );
-		expect( screen.getByRole( 'button', { name: 'Configure Content Gifting' } ) ).toBeInTheDocument();
+	describe( 'primary button', () => {
+		it( 'reads Enable and calls onEnable when the feature is off', () => {
+			const onEnable = jest.fn();
+			const onConfigure = jest.fn();
+			render( <CardFeature title="Content gifting" onEnable={ onEnable } onConfigure={ onConfigure } /> );
+			expect( primaryButton() ).toHaveTextContent( 'Enable' );
+			fireEvent.click( primaryButton() );
+			expect( onEnable ).toHaveBeenCalledTimes( 1 );
+			expect( onConfigure ).not.toHaveBeenCalled();
+		} );
+
+		it( 'reads Configure and calls onConfigure once enabled', () => {
+			const onEnable = jest.fn();
+			const onConfigure = jest.fn();
+			render( <CardFeature title="Content gifting" enabled onEnable={ onEnable } onConfigure={ onConfigure } /> );
+			expect( primaryButton() ).toHaveTextContent( 'Configure' );
+			fireEvent.click( primaryButton() );
+			expect( onConfigure ).toHaveBeenCalledTimes( 1 );
+			expect( onEnable ).not.toHaveBeenCalled();
+		} );
+
+		it( 'still routes to onEnable when enabled with an unmet requirement, since the button reads Enable', () => {
+			const onEnable = jest.fn();
+			const onConfigure = jest.fn();
+			render(
+				<CardFeature
+					title="Content gifting"
+					enabled
+					requirements="Requires metering"
+					requirementsActionable
+					onEnable={ onEnable }
+					onConfigure={ onConfigure }
+				/>
+			);
+			expect( primaryButton() ).toHaveTextContent( 'Enable' );
+			fireEvent.click( primaryButton() );
+			expect( onEnable ).toHaveBeenCalledTimes( 1 );
+			expect( onConfigure ).not.toHaveBeenCalled();
+		} );
+
+		it( 'keeps the button live on an actionable requirement before the feature is on, which is how Activate reaches the user', () => {
+			const onEnable = jest.fn();
+			render(
+				<CardFeature
+					title="Mailchimp"
+					requirements="Requires WooCommerce"
+					requirementsActionable
+					enableLabel="Activate"
+					onEnable={ onEnable }
+				/>
+			);
+			const button = screen.getByRole( 'button', { name: 'Activate Mailchimp' } );
+			expect( button ).not.toHaveAttribute( 'aria-disabled' );
+			fireEvent.click( button );
+			expect( onEnable ).toHaveBeenCalledTimes( 1 );
+			expect( screen.getByText( 'Requires WooCommerce' ) ).toBeInTheDocument();
+		} );
+
+		it( 'does not fire when a requirement is not actionable, but stays reachable', () => {
+			const onEnable = jest.fn();
+			render( <CardFeature title="Content gifting" requirements="Managed by site configuration" onEnable={ onEnable } /> );
+			expect( primaryButton() ).toHaveAttribute( 'aria-disabled', 'true' );
+			expect( primaryButton() ).not.toHaveAttribute( 'disabled' );
+			fireEvent.click( primaryButton() );
+			expect( onEnable ).not.toHaveBeenCalled();
+		} );
+
+		it( 'points the blocked button at the badge that explains why', () => {
+			render( <CardFeature title="Content gifting" requirements="Managed by site configuration" /> );
+			const describedBy = primaryButton().getAttribute( 'aria-describedby' );
+			expect( describedBy ).toBeTruthy();
+			expect( document.getElementById( describedBy ) ).toHaveTextContent( 'Managed by site configuration' );
+		} );
+
+		it( 'leaves the enabled badge unlinked, since it explains nothing about the button', () => {
+			render( <CardFeature title="Content gifting" enabled /> );
+			expect( primaryButton() ).not.toHaveAttribute( 'aria-describedby' );
+		} );
+
+		it( 'disables the button while an action is in flight, even with an actionable requirement', () => {
+			const onEnable = jest.fn();
+			const { rerender } = render( <CardFeature title="Content gifting" busy onEnable={ onEnable } /> );
+			expect( primaryButton() ).toHaveAttribute( 'aria-disabled', 'true' );
+			fireEvent.click( primaryButton() );
+			expect( onEnable ).not.toHaveBeenCalled();
+
+			rerender( <CardFeature title="Content gifting" busy requirements="Requires metering" requirementsActionable onEnable={ onEnable } /> );
+			expect( primaryButton() ).toHaveAttribute( 'aria-disabled', 'true' );
+		} );
+
+		it( 'accepts custom labels for both states', () => {
+			const { rerender } = render( <CardFeature title="Apple News" enableLabel="Connect" configureLabel="Manage connection" /> );
+			expect( screen.getByRole( 'button', { name: 'Connect Apple News' } ) ).toBeInTheDocument();
+			rerender( <CardFeature title="Apple News" enabled enableLabel="Connect" configureLabel="Manage connection" /> );
+			expect( screen.getByRole( 'button', { name: 'Manage connection Apple News' } ) ).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'badge', () => {
+		it( 'shows nothing when off, and the enabled badge when on', () => {
+			const { rerender } = render( <CardFeature title="Content gifting" /> );
+			expect( screen.queryByText( 'Enabled' ) ).not.toBeInTheDocument();
+			rerender( <CardFeature title="Content gifting" enabled /> );
+			expect( screen.getByText( 'Enabled' ) ).toBeInTheDocument();
+		} );
+
+		it( 'lets the requirements badge win over the enabled badge', () => {
+			render( <CardFeature title="Content gifting" enabled requirements="Requires metering" /> );
+			expect( screen.getByText( 'Requires metering' ) ).toBeInTheDocument();
+			expect( screen.queryByText( 'Enabled' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'accepts custom badge text', () => {
+			render( <CardFeature title="Stripe" enabled badge={ { label: 'Live mode', intent: 'informational' } } /> );
+			expect( screen.getByText( 'Live mode' ) ).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'More menu', () => {
+		const controls = [ { title: 'Disable', onClick: jest.fn() } ];
+
+		it( 'appears only when enabled and controls are supplied', () => {
+			const { rerender } = render( <CardFeature title="Content gifting" moreControls={ controls } /> );
+			expect( moreMenu() ).not.toBeInTheDocument();
+			rerender( <CardFeature title="Content gifting" enabled /> );
+			expect( moreMenu() ).not.toBeInTheDocument();
+			rerender( <CardFeature title="Content gifting" enabled moreControls={ controls } /> );
+			expect( moreMenu() ).toBeInTheDocument();
+		} );
+
+		it( 'stays available on an actionable requirement and hides on a locked one', () => {
+			const { rerender } = render(
+				<CardFeature title="Content gifting" enabled requirements="Requires metering" requirementsActionable moreControls={ controls } />
+			);
+			expect( moreMenu() ).toBeInTheDocument();
+			rerender( <CardFeature title="Content gifting" enabled requirements="Managed by site configuration" moreControls={ controls } /> );
+			expect( moreMenu() ).not.toBeInTheDocument();
+		} );
 	} );
 
-	it( 'names the feature in the More menu', () => {
-		render( <CardFeature title="Content Gifting" enabled moreControls={ [ { title: 'Disable', onClick: () => {} } ] } /> );
-		expect( screen.getByRole( 'button', { name: 'More options for Content Gifting' } ) ).toBeInTheDocument();
+	describe( 'icon', () => {
+		it( 'renders a ready element as-is, without the descriptor container', () => {
+			const { container } = render( <CardFeature title="Content gifting" icon={ <span data-testid="ready-icon" /> } /> );
+			expect( screen.getByTestId( 'ready-icon' ) ).toBeInTheDocument();
+			expect( container.querySelector( '.newspack-card-feature__icon' ) ).toBeNull();
+		} );
+
+		it( 'applies the descriptor colours inline and rounds fully on request', () => {
+			const { container } = render(
+				<CardFeature
+					title="Content gifting"
+					icon={ { node: <span data-testid="descriptor-icon" />, fill: '#003da5', backgroundColor: '#dfe7f4', radius: 'full' } }
+				/>
+			);
+			const iconContainer = container.querySelector( '.newspack-card-feature__icon' );
+			expect( screen.getByTestId( 'descriptor-icon' ) ).toBeInTheDocument();
+			expect( iconContainer ).toHaveClass( 'newspack-card-feature__icon--radius-full' );
+			expect( iconContainer ).toHaveStyle( { backgroundColor: '#dfe7f4', color: '#003da5' } );
+		} );
+
+		it( 'hides the descriptor container from assistive tech, since the title already names the feature', () => {
+			const { container } = render( <CardFeature title="Content gifting" icon={ { node: <svg /> } } /> );
+			expect( container.querySelector( '.newspack-card-feature__icon' ) ).toHaveAttribute( 'aria-hidden', 'true' );
+		} );
+
+		it( 'falls back to small corners when a background is set without a radius', () => {
+			const { container } = render( <CardFeature title="Content gifting" icon={ { node: <span />, backgroundColor: '#dfe7f4' } } /> );
+			const iconContainer = container.querySelector( '.newspack-card-feature__icon' );
+			expect( iconContainer ).toHaveClass( 'newspack-card-feature__icon--radius-small' );
+			expect( iconContainer ).not.toHaveClass( 'newspack-card-feature__icon--radius-full' );
+		} );
+
+		it( 'leaves an unbacked descriptor icon without a radius class', () => {
+			const { container } = render( <CardFeature title="Content gifting" icon={ { node: <span />, fill: '#003da5' } } /> );
+			const iconContainer = container.querySelector( '.newspack-card-feature__icon' );
+			expect( iconContainer ).not.toHaveClass( 'newspack-card-feature__icon--radius-small' );
+		} );
 	} );
 
-	it( 'gives the accessible-name order its own catalogue entry', () => {
-		render( <CardFeature title="Metered Countdown" /> );
-		expect( _x ).toHaveBeenCalledWith( '%1$s %2$s', 'accessible button name: visible action label, then feature name', 'newspack-plugin' );
+	it( 'passes className through to the card element', () => {
+		const { container } = render( <CardFeature title="Content gifting" className="newspack-subscribers__card" /> );
+		expect( container.querySelector( '.newspack-card-feature' ) ).toHaveClass( 'newspack-subscribers__card' );
 	} );
 
-	it( 'distinguishes two cards that share a button label', () => {
-		render(
-			<>
-				<CardFeature title="Metered Countdown" />
-				<CardFeature title="Content Gifting" />
-			</>
-		);
-		expect( screen.getByRole( 'button', { name: 'Enable Metered Countdown' } ) ).toBeInTheDocument();
-		expect( screen.getByRole( 'button', { name: 'Enable Content Gifting' } ) ).toBeInTheDocument();
+	it( 'marks the card as muted only when requirements are set', () => {
+		const { container, rerender } = render( <CardFeature title="Content gifting" enabled /> );
+		expect( container.querySelector( '.newspack-card-feature--muted' ) ).toBeNull();
+		rerender( <CardFeature title="Content gifting" enabled requirements="Requires metering" /> );
+		expect( container.querySelector( '.newspack-card-feature--muted' ) ).toBeInTheDocument();
 	} );
 } );