The Four User-Preference Media Queries Your CSS Should Honor

import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';

/**
 * The naive "before" card the article opens against, the one that answers the viewport and ignores the person.
 *
 * It adapts to a single `width` breakpoint and nothing else, so it feels responsive while reading exactly one signal.
 * The simulated reduced-motion switch is ignored on purpose, so it never stops the floating orb the way it does on the finished card, which is the failure the opener demonstrates.
 * The real `prefers-reduced-motion` query is still honored, so a visitor who set Reduce Motion never gets the loop, since the published page owes a real person stillness even while it teaches broken code.
 * The Save action is hidden with `display: none` until `:hover`, with no `:focus-within`, so it leaves the tab order and a touch or keyboard user can never reach it.
 * This is deliberately broken so the opener is literally true on screen; the finished `<adaptive-card>` is the version that honors every signal.
 *
 * It accepts the same demo hooks as `<adaptive-card>` so one harness can drive both cards, but it reads only `wide`.
 * The `sim-reduced-motion`, `sim-contrast`, and `sim-forced-colors` hooks are accepted and ignored, which is exactly the broken behavior: a switch that visibly changes the finished card does nothing here.
 *
 * @element broken-card
 * @attr wide - The one demo hook the broken card honors, forcing the two-column width layout the way a slider drives the real width query.
 * @attr sim-reduced-motion - Accepted for harness parity and ignored, so the hero keeps animating under it, the broken behavior.
 * @attr sim-contrast - Accepted for harness parity and ignored, so the hierarchy never strengthens under it, the broken behavior.
 * @attr sim-forced-colors - Accepted for harness parity and ignored, so the card never adopts the system palette under it, the broken behavior.
 */
@customElement( 'broken-card' )
export class BrokenCard extends LitElement {

	/**
	 * The article title shown as the card's heading and its accessible name.
	 */
	@property( { type: String } )
	heading = '';

	/**
	 * The article summary shown under the heading.
	 */
	@property( { type: String } )
	summary = '';

	/**
	 * A demo-only hook that forces the two-column width layout, the one signal this card reads.
	 *
	 * Production ships the reflow as a real `@media ( width >= 40rem )` query, and this `:host([wide])` twin stands in for it so a width slider can drive the same reflow inside a fixed iframe a viewport query cannot read.
	 * The demo component drives the reflow from this attribute alone, so a 360px frame stays one column instead of reading the wide iframe around it.
	 * It is the only hook the broken card honors, which is the whole point: it answers width and nothing else.
	 * Defaults to `false`, so the card stays one column until the slider passes the breakpoint.
	 */
	@property( { type: Boolean, reflect: true } )
	wide = false;

	/**
	 * A demo hook accepted for parity with `<adaptive-card>` and deliberately ignored.
	 *
	 * The finished card stops the hero under this hook, and the broken card ignores it on purpose, so the simulated request never stops the orb, which is the failure the demo shows.
	 * The real `prefers-reduced-motion` query is still honored in CSS, separately from this hook, so an actual Reduce Motion visitor never sees the loop.
	 */
	@property( { type: Boolean, attribute: 'sim-reduced-motion', reflect: true } )
	simReducedMotion = false;

	/**
	 * A demo hook accepted for parity with `<adaptive-card>` and deliberately ignored.
	 *
	 * The finished card strengthens its whole hierarchy under this hook, and the broken card carries no contrast branch, so nothing changes.
	 * It reflects so a harness can target both cards the same way, but no CSS here responds to it, which is the failure the demo shows.
	 */
	@property( { type: Boolean, attribute: 'sim-contrast', reflect: true } )
	simContrast = false;

	/**
	 * A demo hook accepted for parity with `<adaptive-card>` and deliberately ignored.
	 *
	 * The finished card adopts the system color keywords under this hook, and the broken card holds its brand colors, so it fights the palette instead of integrating.
	 * It reflects so a harness can target both cards the same way, but no CSS here responds to it, which is the failure the demo shows.
	 */
	@property( { type: Boolean, attribute: 'sim-forced-colors', reflect: true } )
	simForcedColors = false;

	/**
	 * Styles for the broken card, scoped to its shadow root.
	 *
	 * The only adaptation here is the width breakpoint, on purpose, mirrored by the `wide` attribute for the demo slider.
	 * There is no branch for the simulated contrast or forced-colors hooks, so the hierarchy never strengthens and the palette is never adopted, and Save is gated behind hover alone, so it never reaches touch or keyboard.
	 * The one real preference the broken card still honors is `prefers-reduced-motion`, a safety floor that leaves the orb still for a visitor who asked for no motion even while the simulated switch stays ignored.
	 */
	static styles = css`
		/* The host is the layout container, so the two-column reflow can key off the card's own width and never off a fixed iframe. */
		:host {
			display: block;
			container-type: inline-size;
			color: var( --ink, #17171a );
			font-family: var( --font-sans, system-ui, sans-serif );
		}

		.card {
			display: grid;
			gap: var( --space-4, 16px );
			max-width: 34rem;
			padding: var( --space-4, 16px );
			background: var( --surface, #ffffff );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --radius-lg, 14px );
		}

		/* The one signal the broken card reads: the viewport width. */
		/* This is the real production query, the broken card's single correct adaptation, since width is the one signal it answers. */
		/* Both tracks are minmax( 0, ... ) so neither can overflow its share, and align-items: start keeps each column at its own content height, so the two columns never overlap. */
		@media ( width >= 40rem ) {
			.card {
				grid-template-columns: minmax( 0, 11rem ) minmax( 0, 1fr );
				align-items: start;
			}
		}

		/* The demo twin of the width query above: the wide attribute drives the same reflow from the width slider, since a viewport query cannot read the fixed demo frame. */
		:host( [wide] ) .card {
			grid-template-columns: minmax( 0, 11rem ) minmax( 0, 1fr );
			align-items: start;
		}

		/* This :host( :not( [wide] ) ) pin is a demo-only seam that holds the reflow to the wide hook so the slider drives it, outranking and overriding the viewport @media that would otherwise leak through the demo iframe and force two columns early, and production deletes it along with the other seams. */
		:host( :not( [wide] ) ) .card {
			grid-template-columns: minmax( 0, 1fr );
		}

		/* A production robustness floor that keeps the card one-column whenever the card box itself is under 30rem, so a viewport width breakpoint never forces two columns inside a narrow container. */
		/* The :host( [wide] ) selector is listed too because a container query adds no specificity: the bare .card floor at (0,1,0) would lose to the (0,3,0) wide seam above, while the @media reflow only ties .card against .card and falls to source order. */
		/* This matches the finished card, so the only difference between the two stays the signals each one reads, not their layout. */
		@container ( width <= 30rem ) {
			.card,
			:host( [wide] ) .card {
				grid-template-columns: minmax( 0, 1fr );
			}
		}

		/* The hero floats under a real no-preference and stops under a real reduce, but the card has no branch for the simulated switch, so the demo's reduced-motion request slides past it. */
		/* The cover sits at the start of its row and takes its column width, so its 4 / 3 box is derived from the width and never inflates past the column. */
		.cover {
			position: relative;
			overflow: hidden;
			width: 100%;
			min-width: 0;
			align-self: start;
			aspect-ratio: 4 / 3;
			border-radius: var( --radius-md, 11px );
			background: linear-gradient( 135deg, var( --accent, #2257e6 ), var( --accent-2, #5b8bff ) );
		}

		/* The floating orb, the moving part, kept identical to the finished card so the only difference is that nothing here turns it off for the simulated switch. */
		.cover::after {
			content: '';
			position: absolute;
			top: 50%;
			left: 50%;
			width: 56%;
			aspect-ratio: 1;
			margin: -28% 0 0 -28%;
			border-radius: 50%;
			background: radial-gradient( circle at 30% 30%, #ffffff, rgb( 255 255 255 / 0 ) 70% );
			opacity: 0.85;
		}

		/* The card ignores the simulated switch on purpose, but never the real OS setting: the loop exists only under a real no-preference, so a real Reduce Motion request leaves the orb still and the published page never floats motion at a visitor who asked for none. */
		@media ( prefers-reduced-motion: no-preference ) {
			.cover::after {
				animation: float 4s ease-in-out infinite;
			}
		}

		@keyframes float {
			0% {
				transform: translate( -55%, -30% ) scale( 0.7 );
			}

			25% {
				transform: translate( 55%, -45% ) scale( 1.05 );
			}

			50% {
				transform: translate( 60%, 45% ) scale( 0.8 );
			}

			75% {
				transform: translate( -50%, 50% ) scale( 1.1 );
			}

			100% {
				transform: translate( -55%, -30% ) scale( 0.7 );
			}
		}

		/* The body groups the heading, summary, and footer, so the wide two-column layout matches the finished card's shape. */
		/* The min-width of 0 lets the body shrink and wrap inside its track instead of pushing the cover or overflowing the card. */
		.body {
			display: grid;
			grid-template-rows: auto auto 1fr;
			gap: var( --space-3, 12px );
			min-width: 0;
			align-content: start;
		}

		.heading {
			margin: 0;
			font-size: var( --fs-18, 18px );
			line-height: 1.25;
		}

		.summary {
			margin: 0;
			color: var( --ink-soft, #56565c );
			font-size: var( --fs-14, 14px );
			line-height: 1.6;
		}

		.footer {
			display: flex;
			align-items: center;
			justify-content: space-between;
			gap: var( --space-3, 12px );
			align-self: end;
		}

		.read {
			color: var( --accent, #2257e6 );
			font-size: var( --fs-13, 13px );
			text-decoration: none;
		}

		/* The hover trap: Save is removed from the layout, and from the tab order, until a hover that touch and keyboard never produce. */
		.save {
			display: none;
			align-items: center;
			gap: 6px;
			padding: 8px 14px;
			font: inherit;
			font-size: var( --fs-13, 13px );
			color: var( --ink, #17171a );
			background: var( --surface, #ffffff );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --radius-pill, 999px );
			cursor: pointer;
		}

		/* Hover is the only way Save ever appears, so there is no path to it without a mouse. */
		.card:hover .save {
			display: inline-flex;
		}
	`;

	/**
	 * Renders the broken card: a hero that keeps animating and a Save action that only a hover can reveal.
	 *
	 * The heading, summary, and footer are grouped in a `.body` element, so the `wide` two-column layout matches the finished card's shape.
	 */
	render() {
		return html`
			<article class="card" aria-labelledby="heading">
				<div class="cover" role="presentation"></div>
				<div class="body">
					<h3 class="heading" id="heading">${this.heading}</h3>
					<p class="summary">${this.summary}</p>
					<div class="footer">
						<a class="read" href="#">Read article</a>
						<button class="save" type="button">Save</button>
					</div>
				</div>
			</article>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'broken-card': BrokenCard;
	}
}

import { LitElement, html, css } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import type { SignalReading, SignalRow } from './types';

/**
 * Reads a media query and calls back whenever its value changes.
 *
 * It lives in the demo layer, not in the production card, since the card honors its CSS preferences in CSS and never needs to read them in JavaScript.
 * Uses `addEventListener( 'change' )`, the modern form, rather than the deprecated `addListener` alias.
 * Calls `onChange` once immediately with the current value, so a subscriber starts in sync.
 *
 * @param query - The media query string to watch.
 * @param onChange - Called with the current match state now and on every change.
 * @returns A teardown function that removes the listener.
 */
export function watchMedia( query: string, onChange: ( matches: boolean ) => void ): () => void {
	const $list = window.matchMedia( query );
	const handler = ( event: MediaQueryListEvent ): void => onChange( event.matches );
	$list.addEventListener( 'change', handler );
	onChange( $list.matches );
	return () => $list.removeEventListener( 'change', handler );
}

/**
 * A read-only live read-out of the five build signals, so a reader sees what each one reports before any styling depends on it.
 *
 * Each row reads its real `matchMedia()` value and updates through {@link watchMedia}.
 * Forced colors and reduced data are flagged as unreliable for different reasons, which each row's own note states.
 * A false forced-colors read genuinely means the mode is not active right now, though Apple platforms offer no OS path into it, while a false reduced-data read carries no information because no user agent lets a user set it.
 *
 * @element signal-dashboard
 */
@customElement( 'signal-dashboard' )
export class SignalDashboard extends LitElement {

	/**
	 * The five build signals, in the order the article introduces them.
	 *
	 * The two flagged rows carry `reliable: false` and their own `note`, since a false read means something different on each.
	 */
	private readonly signals: SignalRow[] = [
		{ label: 'prefers-reduced-motion', query: '(prefers-reduced-motion: reduce)', reliable: true },
		{ label: 'prefers-contrast: more', query: '(prefers-contrast: more)', reliable: true },
		{ label: 'any-pointer: coarse', query: '(any-pointer: coarse)', reliable: true },
		{
			label: 'forced-colors',
			query: '(forced-colors: active)',
			reliable: false,
			note: 'false really does mean the mode is off right now, and Apple platforms offer no OS path into it',
		},
		{
			label: 'prefers-reduced-data',
			query: '(prefers-reduced-data: reduce)',
			reliable: false,
			note: 'false carries no information, since no user agent lets a user set it',
		},
	];

	/**
	 * The current match state for every signal, recomputed by the live listeners.
	 */
	@state()
	private readings: SignalReading[] = this.signals.map( ( signal ) => ( { ...signal, matches: false } ) );

	/**
	 * The teardown functions returned by each {@link watchMedia} subscription, cleared on disconnect.
	 */
	private teardowns: ( () => void )[] = [];

	/**
	 * Subscribes every signal to its live media-query changes when the element connects.
	 */
	connectedCallback(): void {
		super.connectedCallback();
		this.teardowns = this.signals.map( ( signal, index ) =>
			watchMedia( signal.query, ( matches ) => this.updateReading( index, matches ) ),
		);
	}

	/**
	 * Removes every media-query listener when the element disconnects, so no subscription leaks.
	 */
	disconnectedCallback(): void {
		super.disconnectedCallback();
		this.teardowns.forEach( ( teardown ) => teardown() );
		this.teardowns = [];
	}

	/**
	 * Styles for the dashboard, scoped to its shadow root.
	 */
	static styles = css`
		:host {
			display: block;
			color: var( --ink, #17171a );
			font-family: var( --font-sans, system-ui, sans-serif );
		}

		.grid {
			display: grid;
			gap: var( --space-2, 8px );
		}

		.row {
			display: grid;
			grid-template-columns: 1fr auto;
			align-items: center;
			gap: var( --space-3, 12px );
			padding: 10px 12px;
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --radius, 8px );
		}

		.name {
			font-family: var( --font-mono, monospace );
			font-size: var( --fs-12, 12px );
		}

		/* The note and the on-badge text sit at 11px, so both hold at least 4.5:1 against their grounds, the AA floor for body-size text. */
		.note {
			display: block;
			margin-top: 3px;
			font-family: var( --font-sans, sans-serif );
			font-size: 11px;
			color: var( --ink-soft, #56565c );
		}

		.value {
			font-family: var( --font-mono, monospace );
			font-size: 11px;
			padding: 3px 9px;
			border-radius: var( --radius-pill, 999px );
		}

		.value.on {
			color: #157347;
			background: rgb( 31 157 91 / 0.12 );
		}

		.value.off {
			color: var( --ink-soft, #56565c );
			background: var( --line-soft, #f2f1ec );
		}
	`;

	/**
	 * Updates one signal's match state from its live listener.
	 *
	 * @param index - The signal's position in the readings array.
	 * @param matches - Whether the query now matches.
	 */
	private updateReading( index: number, matches: boolean ): void {
		this.readings = this.readings.map( ( reading, i ) => ( i === index ? { ...reading, matches } : reading ) );
	}

	/**
	 * Renders the live read-out, one row per signal, with each flagged row's own honesty note.
	 *
	 * Each value cell is a polite live region, so a screen reader hears a row flip when a real OS preference changes, the exact moment the dashboard exists to show.
	 */
	render() {
		return html`
			<div class="grid">
				${this.readings.map(
					( reading ) => html`
						<div class="row">
							<span class="name">
								${reading.label}
								${reading.note
									? html`<span class="note">${reading.note}</span>`
									: null}
							</span>
							<span class="value ${reading.matches ? 'on' : 'off'}" aria-live="polite">${reading.matches ? 'matches' : 'no match'}</span>
						</div>
					`,
				)}
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'signal-dashboard': SignalDashboard;
	}
}

import { css } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { AdaptiveCard } from '../adaptive-card';

/**
 * A demo-only subclass of `adaptive-card` that adds the attribute hooks a sandboxed harness needs.
 *
 * A demo iframe cannot set a real OS preference or resize the real viewport, so this subclass forces each branch on screen from an attribute a switch or slider controls.
 * None of these hooks exist on the production `adaptive-card`, so the code a reader copies stays clean and the simulation seams live only here.
 * Each seam mirrors the exact response its real `@media` query produces, so what the switch shows on screen is what the preference produces in production.
 *
 * @element demo-adaptive-card
 * @attr wide - Forces the two-column width layout, so a width slider can drive the reflow a viewport `@media` cannot inside a fixed iframe.
 * @attr sim-reduced-motion - Forces the reduced-motion response, so a switch can stop the hero while the feedback stays.
 * @attr sim-contrast - Forces the `prefers-contrast: more` response, so a switch can strengthen the whole hierarchy.
 * @attr sim-forced-colors - Forces the forced-colors integration, so a non-Windows reader still sees the system-color adoption.
 */
@customElement( 'demo-adaptive-card' )
export class DemoAdaptiveCard extends AdaptiveCard {

	/**
	 * Forces the two-column width layout regardless of the real viewport.
	 *
	 * A harness sets this once its width slider passes the breakpoint, so the reflow lands exactly where the label says.
	 * Defaults to `false`, so the card stays one column until the demo forces the wide layout.
	 */
	@property( { type: Boolean, reflect: true } )
	wide = false;

	/**
	 * Forces the reduced-motion response without an OS setting.
	 *
	 * Defaults to `false`, so the demo hero animates until a switch requests reduced motion.
	 */
	@property( { type: Boolean, attribute: 'sim-reduced-motion', reflect: true } )
	simReducedMotion = false;

	/**
	 * Forces the `prefers-contrast: more` response without an OS setting.
	 *
	 * Defaults to `false`, so the demo starts on the baseline hierarchy until a switch strengthens it.
	 */
	@property( { type: Boolean, attribute: 'sim-contrast', reflect: true } )
	simContrast = false;

	/**
	 * Forces the forced-colors integration without a Windows Contrast theme.
	 *
	 * The real query never returns true on Apple platforms, so this hook is the only way a non-Windows reader sees the card adopt the system palette.
	 * Defaults to `false`, so the demo leaves the integration to the real query until a switch forces it.
	 */
	@property( { type: Boolean, attribute: 'sim-forced-colors', reflect: true } )
	simForcedColors = false;

	/**
	 * The parent card's styles plus the demo-only seams that force each branch on screen.
	 *
	 * The seams sit after the parent styles, so they win where they apply and leave the production rules untouched everywhere else.
	 */
	static styles = [
		AdaptiveCard.styles,
		css`
			/* The demo loops the hero so a reader can watch the reduced-motion switch stop an ongoing motion, while the shipped card plays its finite settle once. */
			/* The loop is gated on the real no-preference query and stopped under a real reduce request, so a visitor who set Reduce Motion never gets the loop, even before touching the simulation switch, which stays the seam for everyone else. */
			@media ( prefers-reduced-motion: no-preference ) {
				.cover::after {
					animation: demo-float 4s ease-in-out infinite;
				}
			}

			@media ( prefers-reduced-motion: reduce ) {
				.cover::after {
					animation: none;
				}
			}

			@keyframes demo-float {
				0%,
				100% {
					transform: translate( -30%, -20% ) scale( 0.85 );
				}

				50% {
					transform: translate( 30%, 20% ) scale( 1.05 );
				}
			}

			/* Width: force the two-column reflow from the wide hook, and pin one column otherwise, so a slider drives the layout instead of the viewport a fixed iframe cannot change. */
			:host( [wide] ) .card {
				grid-template-columns: minmax( 0, 11rem ) minmax( 0, 1fr );
				align-items: start;
			}

			:host( :not( [wide] ) ) .card {
				grid-template-columns: minmax( 0, 1fr );
			}

			/* The parent's one-column container floor targets .card at (0,1,0), which the (0,3,0) wide seam above would outrank, since a container query adds no specificity; restating the floor against the seam keeps a narrow card one column even with wide set. */
			@container ( width <= 30rem ) {
				:host( [wide] ) .card {
					grid-template-columns: minmax( 0, 1fr );
				}
			}

			/* Reduced motion: stop the looping hero and drop the Save lift, the full result a real reduce request produces. */
			/* The lift rules live in the parent's no-preference block, which still matches while the switch simulates reduce, so the seam overrides them the way the real query's absence would. */
			:host( [sim-reduced-motion] ) .cover::after {
				animation: none;
			}

			:host( [sim-reduced-motion] ) .save {
				transition: background-color 120ms ease;
			}

			:host( [sim-reduced-motion] ) .card:focus-within .save,
			:host( [sim-reduced-motion] ) .card:hover .save {
				transform: none;
			}

			/* Contrast: the same hierarchy the real @media (prefers-contrast: more) branch strengthens. */
			:host( [sim-contrast] ) .card {
				border-color: var( --ink, #17171a );
				border-width: 2px;
			}

			:host( [sim-contrast] ) .cover {
				border: 2px solid var( --ink, #17171a );
			}

			:host( [sim-contrast] ) .summary {
				color: var( --ink, #17171a );
			}

			:host( [sim-contrast] ) .read {
				text-decoration: underline;
				text-decoration-thickness: 2px;
			}

			:host( [sim-contrast] ) .save {
				color: var( --ink, #17171a );
				border-color: var( --ink, #17171a );
				border-width: 2px;
			}

			:host( [sim-contrast] ) .card:focus-within {
				outline-width: 3px;
			}

			/* Forced colors: paint the CSS system keywords the real @media (forced-colors: active) branch adopts, so a non-Windows reader still sees the integration. */
			:host( [sim-forced-colors] ) .card {
				background: Canvas;
				color: CanvasText;
				border-color: CanvasText;
			}

			:host( [sim-forced-colors] ) .cover {
				background: Canvas;
				border: 1px solid CanvasText;
			}

			:host( [sim-forced-colors] ) .cover::after {
				animation: none;
				background: none;
			}

			:host( [sim-forced-colors] ) .summary {
				color: CanvasText;
			}

			:host( [sim-forced-colors] ) .read {
				color: LinkText;
			}

			:host( [sim-forced-colors] ) .save {
				color: ButtonText;
				background: ButtonFace;
				border-color: ButtonText;
			}

			:host( [sim-forced-colors] ) .card:focus-within {
				outline-color: CanvasText;
			}
		`,
	];
}

declare global {
	interface HTMLElementTagNameMap {
		'demo-adaptive-card': DemoAdaptiveCard;
	}
}

import { LitElement, html, css } from 'lit';
import { customElement, state } from 'lit/decorators.js';

/**
 * Demo harness for the forced-colors lesson, driven entirely from inside the demo.
 *
 * One toggle drops both cards into a simulated high-contrast palette, a black canvas with white text and yellow link and button accents, the shape of a Windows Contrast theme.
 * A sandboxed iframe cannot enter real forced-colors mode and Apple platforms never report it, so the toggle paints the palette on screen instead, standing in for a state the visitor has not set.
 * The fighting card re-asserts its brand styling over the theme, the opt-out a real product takes with `forced-color-adjust: none`, while the integrating card adopts the system keywords and sits inside the palette.
 * Real forcing would repaint untouched plain author colors into system colors at paint time, so the failure dramatized here is a card refusing the user's chosen palette and muddying the theme's guarantees.
 *
 * With the toggle off, both cards show the same branded baseline, so the before reads as one card and the after splits them apart.
 *
 * @element demo-user-preference-media-queries-forced-colors
 */
@customElement( 'demo-user-preference-media-queries-forced-colors' )
export class MediaQueriesForcedColorsDemo extends LitElement {

	/**
	 * Whether the simulated forced-colors palette is painted on the stage.
	 *
	 * Off leaves both cards on their branded baseline, the before; on paints the high-contrast theme so the fighting and integrating responses split apart, the after.
	 */
	@state()
	private forced = false;

	/**
	 * Styles for the harness, scoped to its shadow root.
	 *
	 * The stage-left, controls-right split and the toggle chrome follow the site's shared demo convention, so the article's demos read as one set.
	 * The `.theme` wrapper stands in for a forced-colors theme, switching from the page surface to a literal high-contrast palette the moment `.on` is set, so a reader on any OS sees the divergence a Windows theme would force.
	 */
	static styles = css`
		:host {
			display: block;
			height: 100%;
			font-family: var( --font-sans, system-ui, sans-serif );
			color: var( --ink, #17171a );
		}

		.wrap {
			display: grid;
			grid-template-columns: minmax( 0, 1fr ) 16rem;
			gap: 0;
			min-height: 360px;
			height: 100%;
		}

		/* The stage holds the two cards on the left, divided from the control the way the published harnesses divide stage from controls. */
		.stage {
			display: grid;
			align-content: start;
			padding: 22px;
			border-right: 1px solid var( --line, #e7e6e2 );
		}

		/* The controls column carries the one toggle and the Windows note, on the right. */
		.controls {
			display: grid;
			gap: 12px;
			align-content: start;
			padding: 18px;
		}

		/* The toggle: a labeled button with a track and a knob that slides on, the shared control across the article demos. */
		.toggle {
			display: flex;
			align-items: center;
			justify-content: space-between;
			gap: 10px;
			background: var( --bg, #fcfcfb );
			color: var( --ink, #17171a );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: 7px;
			padding: 9px 12px;
			font: inherit;
			font-size: 13px;
			cursor: pointer;
		}

		.toggle:focus-visible {
			outline: 2px solid var( --accent, #2257e6 );
			outline-offset: 2px;
		}

		.track {
			position: relative;
			width: 36px;
			height: 20px;
			border-radius: 999px;
			background: var( --line, #e7e6e2 );
			transition: background 0.2s ease;
			flex: none;
		}

		.track.on {
			background: var( --accent, #2257e6 );
		}

		.knob {
			position: absolute;
			top: 2px;
			left: 2px;
			width: 16px;
			height: 16px;
			border-radius: 50%;
			background: #ffffff;
			transition: transform 0.2s ease;
		}

		.track.on .knob {
			transform: translateX( 16px );
		}

		/* The stage surface: a branded surface when off, the simulated high-contrast palette when on. */
		.theme {
			display: grid;
			grid-template-columns: 1fr 1fr;
			gap: var( --space-4, 16px );
			padding: var( --space-4, 16px );
			background: var( --bg, #fcfcfb );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --radius-md, 11px );
			transition: background 0.2s ease, border-color 0.2s ease;
		}

		/* The simulated forced-colors theme: black canvas, white text, yellow link and button accents, the palette a Windows Contrast theme forces. */
		.theme.on {
			--sim-canvas: #000000;
			--sim-canvas-text: #ffffff;
			--sim-link-text: #ffff00;
			--sim-button-text: #000000;
			--sim-button-face: #ffff00;
			background: var( --sim-canvas );
			border-color: var( --sim-canvas-text );
		}

		/* Both cards share one fixed brand look, so off they read as a single identical pair, and the toggle is the only thing that splits them. */
		.card {
			display: grid;
			gap: var( --space-3, 12px );
			padding: var( --space-4, 16px );
			background: #14275e;
			border: 1px solid #14275e;
			border-radius: var( --radius-md, 11px );
		}

		/* The hero: a deep brand gradient with a bright orb, so the brand has real presence to either hold or surrender. */
		.cover {
			position: relative;
			overflow: hidden;
			min-height: 6.5rem;
			border-radius: var( --radius, 8px );
			background: linear-gradient( 135deg, #2257e6, #5b8bff );
		}

		.cover::after {
			content: '';
			position: absolute;
			top: 50%;
			left: 30%;
			width: 46%;
			aspect-ratio: 1;
			margin: -23% 0 0 -23%;
			border-radius: 50%;
			background: radial-gradient( circle at 30% 30%, #ffffff, rgb( 255 255 255 / 0 ) 70% );
			opacity: 0.8;
		}

		.heading {
			margin: 0;
			font-size: var( --fs-15, 15px );
			line-height: 1.3;
			color: #c9d6ff;
		}

		.summary {
			margin: 0;
			font-size: var( --fs-13, 13px );
			line-height: 1.55;
			color: #9fb2e6;
		}

		.footer {
			display: flex;
			align-items: center;
			justify-content: space-between;
			gap: var( --space-3, 12px );
		}

		.read {
			font-size: var( --fs-12, 12px );
			color: #9fb2e6;
			text-decoration: underline;
		}

		.save {
			padding: 7px 12px;
			font: inherit;
			font-size: var( --fs-12, 12px );
			color: #ffffff;
			background: #3a63c9;
			border: 1px solid #3a63c9;
			border-radius: var( --radius-pill, 999px );
		}

		.tag {
			display: inline-flex;
			align-items: center;
			gap: 6px;
			font-family: var( --font-mono, monospace );
			font-size: 10px;
			letter-spacing: 0.06em;
			text-transform: uppercase;
			color: #9fb2e6;
		}

		.tag::before {
			content: '';
			width: 7px;
			height: 7px;
			border-radius: 50%;
			background: currentColor;
		}

		/* Fighting is the base brand card and never changes, so when the theme comes on it holds these colors against the palette, the way forced-color-adjust: none holds them in a real product. */

		/* Integrating: when the theme is on, adopt the system keywords so the card sits inside the chosen palette and stays legible. */
		.theme.on .card.integrating {
			background: var( --sim-canvas );
			color: var( --sim-canvas-text );
			border-color: var( --sim-canvas-text );
		}

		.theme.on .card.integrating .cover {
			background: var( --sim-canvas );
			border: 1px solid var( --sim-canvas-text );
		}

		.theme.on .card.integrating .cover::after {
			content: none;
		}

		.theme.on .card.integrating .heading,
		.theme.on .card.integrating .summary,
		.theme.on .card.integrating .tag {
			color: var( --sim-canvas-text );
		}

		.theme.on .card.integrating .read {
			color: var( --sim-link-text );
		}

		.theme.on .card.integrating .save {
			color: var( --sim-button-text );
			background: var( --sim-button-face );
			border-color: var( --sim-button-text );
		}

		.verdict {
			margin: 0;
			font-size: var( --fs-12, 12px );
			line-height: 1.5;
			color: #9fb2e6;
		}

		.theme.on .card.integrating .verdict {
			color: var( --sim-canvas-text );
		}

		.note {
			margin: 0;
			font-family: var( --font-mono, monospace );
			font-size: 10.5px;
			line-height: 1.6;
			color: var( --ink-soft, #56565c );
		}

		@media ( width <= 640px ) {
			.wrap {
				grid-template-columns: 1fr;
			}

			.stage {
				border-right: none;
				border-bottom: 1px solid var( --line, #e7e6e2 );
			}

			.theme {
				grid-template-columns: 1fr;
			}
		}

		/* The harness chrome honors a reduced-motion request too, so the toggle track and knob snap instead of sliding. */
		@media ( prefers-reduced-motion: reduce ) {
			.track,
			.knob {
				transition: none;
			}
		}
	`;

	/**
	 * Toggles the simulated forced-colors palette.
	 */
	private onToggle = (): void => {
		this.forced = ! this.forced;
	};

	/**
	 * Renders the two cards on the simulated stage on the left, the toggle and the Windows note on the right.
	 *
	 * The fighting card keeps the brand class in every state, so its colors stay fixed while the theme changes underneath it.
	 * The integrating card only adopts the system keywords once `.on` is set, so off it matches the fighting card and on it splits away into the palette.
	 */
	render() {
		return html`
			<div class="wrap">
				<div class="stage">
					<div class=${ this.forced ? 'theme on' : 'theme' }>
						<div class="card fighting">
							<span class="tag">Fights the palette</span>
							<div class="cover"></div>
							<h3 class="heading">Designing for the person</h3>
							<p class="summary">Brand styling re-asserted over the theme, the move forced-color-adjust: none makes in a real product, so the palette the user chose never lands here.</p>
							<div class="footer">
								<span class="read">Read article</span>
								<button class="save" type="button">Save</button>
							</div>
							<p class="verdict">${ this.forced ? 'Brand held against the theme, so the card refuses the palette the user chose and muddies the guarantees the theme was set to carry.' : 'Branded and readable, the same as its neighbor for now.' }</p>
						</div>

						<div class="card integrating">
							<span class="tag">Integrates with it</span>
							<div class="cover"></div>
							<h3 class="heading">Designing for the person</h3>
							<p class="summary">System color keywords adopted, so the card drops into whatever palette the user chose and keeps every part legible.</p>
							<div class="footer">
								<span class="read">Read article</span>
								<button class="save" type="button">Save</button>
							</div>
							<p class="verdict">${ this.forced ? 'Canvas, CanvasText, LinkText, ButtonText, and ButtonFace adopted, so the card reads cleanly inside the theme.' : 'Branded and readable, the same as its neighbor for now.' }</p>
						</div>
					</div>
				</div>
				<div class="controls">
					<button type="button" class="toggle" @click=${ this.onToggle } aria-pressed=${ this.forced }>
						<span>Forced colors</span>
						<span class=${ this.forced ? 'track on' : 'track' }><span class="knob"></span></span>
					</button>
					<p class="note">
						Simulated palette, painted here so the response is visible on any OS.
						Real forced colors is a Windows Contrast themes path: the query never returns true on Apple platforms, and forced-color-adjust is a Safari no-op.
					</p>
				</div>
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'demo-user-preference-media-queries-forced-colors': MediaQueriesForcedColorsDemo;
	}
}

import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import type { ReachabilityVariant } from './types';

/**
 * A card whose Save action is either trapped behind hover or reachable by default, for teaching the hover-reachability rule.
 *
 * The `'hover-only'` variant hides Save with `display: none` until `:hover`, which also drops it from the tab order, so a touch or keyboard user never sees or reaches it.
 * The `'reachable'` variant keeps Save visible and focusable and lets hover only add emphasis, the version that ships.
 * Tab into either card to feel the difference: the broken one never lands focus on Save, the reachable one does.
 *
 * @element hover-only-card
 * @attr variant - `'hover-only'` for the broken card, `'reachable'` for the fixed one.
 */
@customElement( 'hover-only-card' )
export class HoverOnlyCard extends LitElement {

	/**
	 * Which reachability variant to render.
	 *
	 * Defaults to `'hover-only'`, the broken case, so an unconfigured card shows the failure the demo is about.
	 */
	@property( { type: String, reflect: true } )
	variant: ReachabilityVariant = 'hover-only';

	/**
	 * The card heading shown above the action.
	 */
	@property( { type: String } )
	heading = '';

	/**
	 * Styles for the card, scoped to its shadow root.
	 *
	 * The two variants share a base and diverge only in how Save is revealed, so the contrast is the affordance and nothing else.
	 */
	static styles = css`
		:host {
			display: block;
			color: var( --ink, #17171a );
			font-family: var( --font-sans, system-ui, sans-serif );
		}

		.card {
			display: grid;
			gap: var( --space-3, 12px );
			padding: var( --space-4, 16px );
			background: var( --surface, #ffffff );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --radius-lg, 14px );
		}

		.card:focus-within {
			outline: 2px solid var( --accent, #2257e6 );
			outline-offset: 4px;
		}

		.heading {
			margin: 0;
			font-size: var( --fs-16, 16px );
		}

		.save {
			justify-self: start;
			padding: 8px 14px;
			font: inherit;
			font-size: var( --fs-13, 13px );
			color: var( --ink, #17171a );
			background: var( --surface, #ffffff );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --radius-pill, 999px );
			cursor: pointer;
		}

		/* The broken card: Save is removed from the layout, and from the tab order, until a hover that touch and keyboard never produce. */
		:host( [variant='hover-only'] ) .save {
			display: none;
		}

		:host( [variant='hover-only'] ) .card:hover .save {
			display: inline-flex;
		}

		/* The reachable card: Save stays present and focusable, and hover only adds emphasis. */
		:host( [variant='reachable'] ) .save {
			display: inline-flex;
			opacity: 1;
			transition: background-color 120ms ease;
		}

		/* The focus tint is feedback that must reach keyboard users regardless of pointer capability, so it is never gated by hover, mirroring the production card. */
		:host( [variant='reachable'] ) .card:focus-within .save {
			background-color: var( --tint, #eef2fe );
		}

		/* Hover only enhances an already-available action, on devices that actually hover. */
		@media ( hover: hover ) {
			:host( [variant='reachable'] ) .card:hover .save {
				background-color: var( --tint, #eef2fe );
			}
		}

		/* The lift is motion, so it exists only under no-preference, and it is not gated by hover, so keyboard focus gets it too. */
		@media ( prefers-reduced-motion: no-preference ) {
			:host( [variant='reachable'] ) .save {
				transition: transform 120ms ease, background-color 120ms ease;
			}

			:host( [variant='reachable'] ) .card:focus-within .save {
				transform: translateY( -1px );
			}
		}

		@media ( hover: hover ) and ( prefers-reduced-motion: no-preference ) {
			:host( [variant='reachable'] ) .card:hover .save {
				transform: translateY( -1px );
			}
		}
	`;

	/**
	 * Renders the card and its Save action in whichever reachability variant is set.
	 */
	render() {
		return html`
			<article class="card" aria-labelledby="heading">
				<h3 class="heading" id="heading">${this.heading}</h3>
				<button class="save" type="button">Save</button>
			</article>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'hover-only-card': HoverOnlyCard;
	}
}

import { LitElement, html, css, nothing, type CSSResultGroup } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import type { HeroVariant } from './types';

/**
 * Reads the optional, Chromium-only Save-Data hint, one input a product may fold into its own asset policy.
 *
 * It decides nothing on its own: a product leads with its user setting and asset policy, and may consult this hint as an optional signal rather than the gate.
 * The `navigator` existence check keeps the read safe in a server render, where no browser globals exist.
 * Optional chaining is required, since `connection` is `undefined` in Firefox and Safari.
 * Defaults to `false` wherever the hint is absent, so nothing withholds the full hero on a guess.
 *
 * @returns True when the browser reports a Save-Data preference, otherwise false.
 */
export function readSaveDataHint(): boolean {
	if ( typeof navigator === 'undefined' ) {
		return false;
	}
	return navigator.connection?.saveData ?? false;
}

/**
 * An article card that reads the person and the device, going past the viewport width.
 *
 * It honors `prefers-reduced-motion`, `prefers-contrast: more`, and `forced-colors` in pure CSS, so no preference depends on JavaScript.
 * The Save action stays visible and focusable by default, and hover only enhances its presentation, so touch and keyboard users always keep it.
 * The one signal CSS can't carry today is reduced data, so the card takes a product-set `heroVariant` rather than reading a browser query, and a consumer may seed that value from the optional Save-Data hint.
 *
 * This is the production component a reader copies as is: every preference adaptation is a real `@media` query with no demo scaffolding to strip out.
 * The demos drive it with a `demo-adaptive-card` subclass that adds attribute hooks, so a sandboxed iframe can force a branch without touching this file.
 *
 * @element adaptive-card
 * @slot summary - The card's summary text; it falls back to the `summary` attribute when empty.
 * @fires card-save - Fired when the Save button is pressed, carrying the article `id` so a page can react.
 * @cssprop [--adaptive-card-accent=var(--accent)] - The accent used for focus, links, and the Save tint.
 */
@customElement( 'adaptive-card' )
export class AdaptiveCard extends LitElement {

	/**
	 * The article title shown as the card's heading and its accessible name.
	 *
	 * When it is empty, the heading element and the `aria-labelledby` wiring are both omitted, so the card never exposes an empty heading as its accessible name.
	 */
	@property( { type: String } )
	heading = '';

	/**
	 * The article summary shown under the heading.
	 *
	 * A slotted `summary` overrides this, so a consumer can pass inline markup like emphasis or a link, which the slot renders inside the summary paragraph, while a plain string still works.
	 */
	@property( { type: String } )
	summary = '';

	/**
	 * A stable identifier for the article, echoed back in the `card-save` event.
	 *
	 * It carries no preference data, so it stays a plain product field.
	 * The `attribute` is set explicitly because Lit lowercases the default observed attribute, so `article-id` would otherwise never reach this property.
	 */
	@property( { type: String, attribute: 'article-id' } )
	articleId = '';

	/**
	 * The href the read link points at, a plain product field like the article id.
	 *
	 * It reflects so the host keeps the property visible as an attribute, for devtools inspection and attribute selectors; the anchor itself reads the property either way.
	 * It defaults to empty, and the read link renders only when a consumer sets it, so a copied card never ships a link to a route that does not exist.
	 */
	@property( { type: String, attribute: 'read-href', reflect: true } )
	readHref = '';

	/**
	 * Which hero variant to render, the seam a product's own asset policy drives.
	 *
	 * The card only receives this value; the product decides it from its user setting and asset policy, and a consumer may seed it from {@link readSaveDataHint} as an optional input.
	 * `'light'` swaps the animated hero for a flat static one, a pure-CSS stand-in that changes presentation rather than transferring a smaller file, the transfer the real asset policy would make.
	 * Defaults to `'full'`, so the card never withholds the rich hero without an explicit decision.
	 */
	@property( { type: String, attribute: 'hero-variant' } )
	heroVariant: HeroVariant = 'full';

	/**
	 * Styles for the card, scoped to its shadow root.
	 *
	 * Every preference adaptation lives here as a real `@media` query, with nothing to delete before shipping.
	 * The state feedback (the focus ring, the Save tint) is declared outside the hero animation, so the reduced-motion branch removes motion without removing feedback.
	 */
	static styles: CSSResultGroup = css`
		/* The host is the layout container, so the two-column reflow can key off the card's own width and stay robust in a narrow slot. */
		:host {
			display: block;
			container-type: inline-size;
			color: var( --ink, #17171a );
			font-family: var( --font-sans, system-ui, sans-serif );
		}

		.card {
			display: grid;
			gap: var( --space-4, 16px );
			max-width: 34rem;
			padding: var( --space-4, 16px );
			background: var( --surface, #ffffff );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --radius-lg, 14px );
		}

		/* The width reflow: the cover takes a flexible column that caps at 11rem, and the body takes the rest. */
		/* Both tracks are minmax( 0, ... ) so neither can overflow its share, and align-items: start keeps each column at its own content height. */
		@media ( width >= 40rem ) {
			.card {
				grid-template-columns: minmax( 0, 11rem ) minmax( 0, 1fr );
				align-items: start;
			}
		}

		/* A production robustness floor that keeps the card one-column whenever the card box itself is under 30rem, so a viewport width breakpoint never forces two columns inside a narrow container. */
		/* Without this floor the body would collapse to about 10rem the instant the card went two-column and crush the heading. */
		@container ( width <= 30rem ) {
			.card {
				grid-template-columns: minmax( 0, 1fr );
			}
		}

		/* The body groups the heading, summary, and footer, so the two-column layout can place the cover beside the whole text block. */
		/* The min-width of 0 lets the body shrink and wrap inside its track instead of pushing the cover or overflowing the card. */
		.body {
			display: grid;
			grid-template-rows: auto auto 1fr;
			gap: var( --space-3, 12px );
			min-width: 0;
			align-content: start;
		}

		/* The footer pins to the bottom of the body, so in the wide layout the Save action lines up with the foot of the cover. */
		.footer {
			display: flex;
			align-items: center;
			justify-content: space-between;
			gap: var( --space-3, 12px );
			align-self: end;
		}

		/* The focus cue is declared on its own, outside the hero animation, so removing motion never removes feedback. */
		.card:focus-within {
			outline: 2px solid var( --adaptive-card-accent, var( --accent, #2257e6 ) );
			outline-offset: 4px;
		}

		/* The cover is a deep gradient field with a bright orb that settles into place, a clear motion the reader sees on arrival. */
		/* The cover sits at the start of its row and takes its column width, so its 4 / 3 box is derived from the width and never inflates past the column to overlap the body. */
		.cover {
			position: relative;
			overflow: hidden;
			width: 100%;
			min-width: 0;
			align-self: start;
			aspect-ratio: 4 / 3;
			border-radius: var( --radius-md, 11px );
			background: linear-gradient( 135deg, var( --accent, #2257e6 ), var( --accent-2, #5b8bff ) );
		}

		/* The orb, the moving part: it drifts in and settles over a finite run, so the motion has a clear end and never loops forever. */
		/* A finite settle keeps the hero clear of WCAG 2.2.2, which governs motion that starts on its own and runs past five seconds. */
		.cover::after {
			content: '';
			position: absolute;
			top: 50%;
			left: 50%;
			width: 56%;
			aspect-ratio: 1;
			margin: -28% 0 0 -28%;
			border-radius: 50%;
			background: radial-gradient( circle at 30% 30%, #ffffff, rgb( 255 255 255 / 0 ) 70% );
			opacity: 0.85;
			animation: settle 2.4s ease-out both;
		}

		/* The lighter hero the reduced-data product path selects, a flat fill that stands in for the lighter real asset a product would serve. */
		.cover.light {
			background: var( --tint, #eef2fe );
		}

		.cover.light::after {
			content: none;
		}

		@keyframes settle {
			0% {
				transform: translate( -55%, -35% ) scale( 0.7 );
				opacity: 0;
			}

			55% {
				transform: translate( 30%, 20% ) scale( 1.08 );
				opacity: 0.9;
			}

			100% {
				transform: translate( 0%, 0% ) scale( 1 );
				opacity: 0.85;
			}
		}

		.heading {
			margin: 0;
			font-size: var( --fs-18, 18px );
			line-height: 1.25;
		}

		.summary {
			margin: 0;
			color: var( --ink-soft, #56565c );
			font-size: var( --fs-14, 14px );
			line-height: 1.6;
		}

		.read {
			color: var( --adaptive-card-accent, var( --accent, #2257e6 ) );
			font-size: var( --fs-13, 13px );
			text-decoration: none;
		}

		/* Save is visible and focusable by default, so touch and keyboard users always reach it. */
		/* The color tint can transition because a color change is not the motion a reduced-motion user is guarding against. */
		.save {
			opacity: 1;
			display: inline-flex;
			align-items: center;
			gap: 6px;
			padding: 8px 14px;
			font: inherit;
			font-size: var( --fs-13, 13px );
			color: var( --ink, #17171a );
			background: var( --surface, #ffffff );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --radius-pill, 999px );
			cursor: pointer;
			transition: background-color 120ms ease;
		}

		/* The focus tint is feedback that must reach keyboard users regardless of pointer capability, so it is never gated by hover. */
		.card:focus-within .save {
			background-color: var( --tint, #eef2fe );
		}

		/* Hover only enhances an already-available action, on devices that actually hover. */
		@media ( hover: hover ) {
			.card:hover .save {
				background-color: var( --tint, #eef2fe );
			}
		}

		/* The cosmetic lift is motion, so it drops out under a reduced-motion request, but it is not gated by hover, so keyboard focus gets it too. */
		@media ( prefers-reduced-motion: no-preference ) {
			.save {
				transition: transform 120ms ease, background-color 120ms ease;
			}

			.card:focus-within .save {
				transform: translateY( -1px );
			}
		}

		@media ( hover: hover ) and ( prefers-reduced-motion: no-preference ) {
			.card:hover .save {
				transform: translateY( -1px );
			}
		}

		/* Touch context: size the target up, the only thing any-pointer: coarse decides here. */
		@media ( any-pointer: coarse ) {
			.save {
				padding: 12px 18px;
				min-height: 44px;
			}
		}

		/* Requirement: cut the optional hero motion, keep the focus and Save feedback above. */
		@media ( prefers-reduced-motion: reduce ) {
			.cover::after {
				animation: none;
			}
		}

		/* Requirement: strengthen the whole hierarchy across border, text, separation, and focus. */
		/* This handles the more branch only. */
		@media ( prefers-contrast: more ) {
			.card {
				border-color: var( --ink, #17171a );
				border-width: 2px;
			}

			.cover {
				border: 2px solid var( --ink, #17171a );
			}

			.summary {
				color: var( --ink, #17171a );
			}

			.read {
				text-decoration: underline;
				text-decoration-thickness: 2px;
			}

			.save {
				color: var( --ink, #17171a );
				border-color: var( --ink, #17171a );
				border-width: 2px;
			}

			.card:focus-within {
				outline-width: 3px;
			}
		}

		/* System mode: adopt the system palette and integrate, never fight it. */
		@media ( forced-colors: active ) {
			.card {
				background: Canvas;
				color: CanvasText;
				border-color: CanvasText;
			}

			.cover {
				background: Canvas;
				border: 1px solid CanvasText;
			}

			.cover::after {
				animation: none;
				background: none;
			}

			.summary {
				color: CanvasText;
			}

			.read {
				color: LinkText;
			}

			.save {
				color: ButtonText;
				background: ButtonFace;
				border-color: ButtonText;
			}

			.card:focus-within {
				outline-color: CanvasText;
			}
		}
	`;

	/**
	 * Renders the card: a semantic `article`, a heading, the summary, the read link when an href is set, and a Save button visible by default.
	 *
	 * The heading, summary, and footer are grouped in a `.body` element, so the two-column wide layout places the cover beside the whole text block.
	 * The hero gets the `light` class when `heroVariant` is `'light'`, the only place the product's asset decision touches the view.
	 * The heading and the read link each render only when their property is set, so a card missing one never ships an empty heading as its accessible name or a dead anchor.
	 */
	render() {
		return html`
			<article class="card" aria-labelledby=${this.heading ? 'heading' : nothing}>
				<div class="cover ${this.heroVariant === 'light' ? 'light' : ''}" role="presentation"></div>
				<div class="body">
					${this.heading ? html`<h3 class="heading" id="heading">${this.heading}</h3>` : null}
					<p class="summary"><slot name="summary">${this.summary}</slot></p>
					<div class="footer">
						${this.readHref ? html`<a class="read" href=${this.readHref}>Read article</a>` : null}
						<button class="save" type="button" @click=${this.handleSave}>Save</button>
					</div>
				</div>
			</article>
		`;
	}

	/**
	 * Dispatches the `card-save` event with the article id when Save is pressed.
	 *
	 * It is `composed` so the event crosses the shadow boundary, and `bubbles` so a listener on the host receives it.
	 */
	private handleSave = (): void => {
		this.dispatchEvent(
			new CustomEvent<string>( 'card-save', {
				detail: this.articleId,
				bubbles: true,
				composed: true,
			} ),
		);
	};
}

declare global {
	interface HTMLElementTagNameMap {
		'adaptive-card': AdaptiveCard;
	}
}