Let CSS Pick Your Text Color

import { LitElement, html, css } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { contrastRatio, resolveToSrgb } from '../library/color-tokens-shared/contrast';
import { demoChrome } from '../library/color-tokens-shared/chrome';
import type { SrgbColor } from '../library/color-tokens-shared/types';

/**
 * The WCAG 2 AA threshold for normal-size text, the bar the report holds white against.
 *
 * The report flags a row below this as failing, so the reader sees exactly where a hardcoded white foreground stops being readable.
 */
const AA_NORMAL = 4.5;

/**
 * Black, as an sRGB color, the readable alternative the naive badge throws away.
 */
const BLACK: SrgbColor = { r: 0, g: 0, b: 0, alpha: 1 };

/**
 * White, as an sRGB color, the foreground the naive badge hardcodes.
 */
const WHITE: SrgbColor = { r: 1, g: 1, b: 1, alpha: 1 };

/**
 * One accent worth landing on, paired with a label, so a preset button can name the trap it triggers.
 */
interface AccentPreset {

	/**
	 * The label shown on the preset button.
	 */
	label: string;

	/**
	 * The accent color the button applies, as a CSS color string the picker can also round-trip.
	 */
	accent: string;
}

/**
 * The presets that make the failure reproducible without the reader hunting for a bad color.
 *
 * Each one is a color where a hardcoded white foreground reads poorly or vanishes, so a single click proves the token is more than one value.
 */
const PRESETS: readonly AccentPreset[] = [
	{ label: 'Yellow', accent: '#ffd60a' },
	{ label: 'Near white', accent: '#eef0f2' },
	{ label: 'Neutral gray', accent: '#9aa0a8' },
];

/**
 * D1, the naive token fails.
 *
 * A color input drives a single `--accent`, and the badge hardcodes `color: white`, the junior instinct that treats a token as one value.
 * The contrast report scores white on the accent against the WCAG 2 AA bar and shows black beside it, so the reader watches white fail on a yellow, a near-white, and a neutral-gray accent while black stays readable.
 * The lesson is that "the accent" is a contract that owes a readable foreground on top of the background color it sets.
 *
 * @element demo-color-token-contract-color-tokens-naive-badge
 */
@customElement( 'demo-color-token-contract-color-tokens-naive-badge' )
export class NaiveBadgeDemo extends LitElement {

	/**
	 * The current accent color, driving `--accent` on the badge and the report.
	 *
	 * It starts on the sRGB rendering of the article's canonical accent `oklch(65% 0.18 260)`, a color where white is the weaker pick, so the badge opens on the running example with white already failing.
	 */
	@state()
	private accent = '#488bfb';

	/**
	 * Styles for the harness, composed on the shared demo chrome so this lab matches the others.
	 *
	 * Only the preview badge and the preset row are unique here; the controls, swatch, and report come from `demoChrome`.
	 */
	static styles = [
		demoChrome,
		css`
			.preview {
				display: flex;
				align-items: center;
				gap: var(--space-3, 12px);
				padding: var(--space-4, 16px);
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
				background: var(--bg, #fcfcfb);
			}

			/* The naive badge: the accent is a runtime variable, but the foreground is hardcoded white, which is the bug the report exposes. */
			.badge {
				display: inline-flex;
				align-items: center;
				padding: 0.3em 0.8em;
				border-radius: var(--radius-pill, 999px);
				background: var(--accent, #5566d8);
				color: white;
				font-weight: 600;
				font-size: var(--fs-14, 14px);
			}

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

			.preset {
				padding: 0.35em 0.7em;
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
				background: var(--surface, #fff);
				color: var(--ink, #17171a);
				font: inherit;
				font-size: var(--fs-13, 13px);
				cursor: pointer;
			}

			.preset:hover {
				background: var(--tint, #eef2fe);
			}

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

	/**
	 * Reads the accent back as an sRGB color, or `null` when the current value does not parse.
	 *
	 * Every ratio in the report runs off this one resolved color, so the badge and the numbers can never disagree about what is on screen.
	 */
	private get resolvedAccent(): SrgbColor | null {
		return resolveToSrgb( this.accent );
	}

	/**
	 * Updates the accent from the color input.
	 *
	 * @param event - The input event from the color picker.
	 */
	private onPick = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.accent = event.target.value;
		}
	};

	/**
	 * Applies a preset accent, the one-click path to a color where white fails.
	 *
	 * @param accent - The preset accent to apply.
	 */
	private applyPreset( accent: string ): void {
		this.accent = accent;
	}

	/**
	 * Renders one report row for a candidate foreground on the current accent.
	 *
	 * It scores the candidate against the accent, prints the ratio, and tags the verdict pass or fail at the AA bar, so white and black sit side by side with the same yardstick.
	 *
	 * @param label - The row label naming the candidate foreground.
	 * @param candidate - The candidate foreground color in sRGB.
	 * @param accent - The resolved accent the candidate sits on.
	 * @returns The rendered report row.
	 */
	private reportRow( label: string, candidate: SrgbColor, accent: SrgbColor ) {
		const ratio = contrastRatio( candidate, accent );
		const passes = ratio >= AA_NORMAL;

		return html`
			<div class="report-row">
				<span class="report-label">${label}</span>
				<span class="report-ratio">${ratio.toFixed( 2 )}:1</span>
				<span class="report-verdict" data-pass=${passes ? 'true' : 'false'}>${passes ? 'AA pass' : 'AA fail'}</span>
			</div>
		`;
	}

	/**
	 * Renders the picker, the presets, the naive badge, and the contrast report.
	 */
	render() {
		const accent = this.resolvedAccent;

		return html`
			<div class="demo">
				<h3 class="demo-title">A badge that hardcodes color: white</h3>
				<div class="controls">
					<div class="control">
						<label class="control-label" for="accent">Accent</label>
						<input id="accent" type="color" .value=${this.accent} @input=${this.onPick} />
						<span class="control-value">${this.accent}</span>
					</div>
				</div>
				<div class="presets">
					${PRESETS.map(
						( preset ) => html`
							<button type="button" class="preset" @click=${() => this.applyPreset( preset.accent )}>
								${preset.label}
							</button>
						`,
					)}
				</div>
				<div class="preview">
					<span class="badge" style="--accent:${this.accent};">Featured</span>
					<span class="swatch" style="background:${this.accent};"></span>
				</div>
				${accent
					? html`
						<div class="report">
							${this.reportRow( 'White on accent (the badge)', WHITE, accent )}
							${this.reportRow( 'Black on accent (thrown away)', BLACK, accent )}
						</div>
					`
					: html`<p class="demo-note">That value is not a color, so there is nothing to score.</p>` }
				<p class="demo-note">
					The badge always paints <strong>white</strong> text.
					On a yellow, a near-white, or a neutral-gray accent that white drops below the AA bar while black stays readable, so the token owes a foreground decision on top of the background it sets.
				</p>
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'demo-color-token-contract-color-tokens-naive-badge': NaiveBadgeDemo;
	}
}

import { LitElement, html, css } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { resolveToSrgb } from '../library/color-tokens-shared/contrast';
import { demoChrome } from '../library/color-tokens-shared/chrome';
import { parse, rgb } from 'culori';
import type { SrgbColor } from '../library/color-tokens-shared/types';

/**
 * Whether the engine parses `oklch()` at all, checked once so the readback can say when the floor hex is what actually paints.
 *
 * On an engine without the function the swatch's literal `oklch()` declaration fails to parse and the hex declaration before it holds, the same floor pattern the component uses in step 7, so the sliders stop driving the paint and the demo says so instead of pretending.
 */
const SUPPORTS_OKLCH = CSS.supports( 'color', 'oklch(65% 0.18 260)' );

/**
 * The canonical accent's slider positions, the values every slider opens on.
 *
 * They spell the article's running `oklch(65% 0.18 260)`, so the first readback the reader sees is the accent resolving to `rgb(72, 139, 251)` and the hex `#488bfb` the Tier 0 floor uses.
 */
const SEED = { lightness: 65, chroma: 0.18, hue: 260 } as const;

/**
 * D2, the oklch sliders, where the accent's three numbers become three separate controls.
 *
 * Each slider is a gradient strip that previews its whole range at the other two sliders' current values, lightness from black to white, chroma from the neutral gray axis out past the sRGB edge, where the painted strip saturates, and hue around the wheel, so moving one slider visibly repaints the range of the other two.
 * The swatch paints the literal `oklch()` string the sliders spell, and the readback prints the `rgb()` and hex the string resolves to through the shared culori resolver, since modern engines keep a computed `oklch()` in its oklch form.
 * The strips and the swatch each declare a hex or neutral floor before their `oklch()` value, the same two-declaration fallback the component's Tier 0 uses, so an engine without the function paints the floors and the demo flags that the sliders are no longer in charge.
 * Pushing the sliders outside sRGB splits the readback in two, the channel clip an sRGB screen approximately paints and the chroma-walked spelling the CSS mapping algorithm defines, since past the boundary one honest hex stops existing and any single answer is a policy, the gamut boundary step 5 returns to.
 * The lightness poles are the split at its widest, since the mapping answers plain white at or above 100 percent and plain black at or below 0 whatever the chroma and hue say, while the clip keeps only a bent tint, dropping most of the chroma and letting the hue drift, so the demo words each pole's message for its own answer instead of letting a white answer under a tinted sample read as a bug.
 *
 * @element demo-color-token-contract-color-tokens-oklch-dials
 */
@customElement( 'demo-color-token-contract-color-tokens-oklch-dials' )
export class OklchDialsDemo extends LitElement {

	/**
	 * The lightness slider on the oklch 0 to 100 percent scale, perceptual rather than HSL's arithmetic lightness.
	 */
	@state()
	private lightness: number = SEED.lightness;

	/**
	 * The chroma slider, distance from gray, where 0 is achromatic and the top of the range sits deliberately past what sRGB can display.
	 */
	@state()
	private chroma: number = SEED.chroma;

	/**
	 * The hue slider in degrees around the wheel, where 260 is the article's blue.
	 */
	@state()
	private hue: number = SEED.hue;

	/**
	 * Styles for the harness, composed on the shared demo chrome.
	 *
	 * The gradient slider strips come from the chrome; only the preview swatch, the readback row, and the value samples are local.
	 */
	static styles = [
		demoChrome,
		css`
			.preview-swatch {
				height: 4.5rem;
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
			}

			.readback {
				display: flex;
				flex-wrap: wrap;
				align-items: center;
				gap: var(--space-2, 8px);
				font-size: var(--fs-13, 13px);
				color: var(--ink-soft, #56565c);
			}

			/* A small rendered sample beside each printed color value, so the reader sees the color the string names; the oklch and hex samples only disagree when a wide-gamut screen can outrun the sRGB spelling. */
			.chip-swatch {
				display: inline-block;
				width: 0.9em;
				height: 0.9em;
				border: 1px solid var(--line, #e7e6e2);
				border-radius: 3px;
			}
		`,
	];

	/**
	 * The literal `oklch()` string the three sliders currently spell, the exact value the swatch paints.
	 */
	private get oklchString(): string {
		return `oklch(${this.lightness}% ${this.chroma} ${this.hue})`;
	}

	/**
	 * Whether the current sliders leave the sRGB gamut, converted without mapping so an out-of-range channel is visible.
	 *
	 * The check is about the sRGB spelling the readback prints rather than the paint, since a wide-gamut display can render past sRGB, so the flag names the moment the rgb() and hex answers stop being the whole story.
	 */
	private get outOfSrgbGamut(): boolean {
		const parsed = parse( this.oklchString );

		if ( parsed === undefined ) {
			return false;
		}

		const converted = rgb( parsed );

		if ( converted === undefined ) {
			return false;
		}

		return [ converted.r, converted.g, converted.b ].some( ( channel ) => channel < 0 || channel > 1 );
	}

	/**
	 * The sliders' color resolved to sRGB through the shared culori resolver, the same chroma-reduction strategy CSS defines, or `null` when the string does not resolve.
	 *
	 * This is the demo's readback source instead of the computed style, because modern engines serialize a computed `oklch()` background in its oklch form, which would answer the "what rgb and hex is this" question with the question.
	 */
	private get resolved(): SrgbColor | null {
		return resolveToSrgb( this.oklchString );
	}

	/**
	 * Which lightness pole the sliders sit on with chroma still asked for, or `null` when they are off both poles.
	 *
	 * CSS Color 4's gamut mapping returns plain white for a lightness at or above 100 percent and plain black at or below 0, whatever the chroma and hue say, while the paint clips channels instead, so each pole gets a message worded for its own answer rather than a white-worded message over a black result.
	 */
	private get lightnessPole(): 'white' | 'black' | null {
		if ( this.chroma <= 0 ) {
			return null;
		}

		if ( this.lightness >= 100 ) {
			return 'white';
		}

		if ( this.lightness <= 0 ) {
			return 'black';
		}

		return null;
	}

	/**
	 * The raw sRGB conversion with each overflowing channel clamped at its limit, the spelling an sRGB screen approximately paints for an out-of-gamut request.
	 *
	 * Engines do not run the CSS mapping algorithm when rendering, they clip the channels that overshoot, so this answer matches the vivid paint while the shared resolver's answer matches the spec, and the demo prints both once they diverge.
	 */
	private get clipped(): SrgbColor | null {
		const parsed = parse( this.oklchString );

		if ( parsed === undefined ) {
			return null;
		}

		const converted = rgb( parsed );

		if ( converted === undefined ) {
			return null;
		}

		const clamp = ( channel: number ): number => {
			return Math.min( 1, Math.max( 0, channel ) );
		};

		return {
			r: clamp( converted.r ),
			g: clamp( converted.g ),
			b: clamp( converted.b ),
			alpha: 1,
		};
	}

	/**
	 * The lightness strip's gradient, black to white at the current chroma and hue, so the slider previews exactly what moving it would paint.
	 */
	private get lightnessTrack(): string {
		const stops = this.trackStops( 11, ( t ) => `oklch(${Math.round( t * 100 )}% ${this.chroma} ${this.hue})` );

		return `linear-gradient(to right, ${stops})`;
	}

	/**
	 * The chroma strip's gradient, from the neutral gray axis out past the sRGB edge at the current lightness and hue, the fan of the reference diagrams unrolled into a strip.
	 */
	private get chromaTrack(): string {
		const stops = this.trackStops( 9, ( t ) => `oklch(${this.lightness}% ${( t * 0.4 ).toFixed( 2 )} ${this.hue})` );

		return `linear-gradient(to right, ${stops})`;
	}

	/**
	 * The hue strip's gradient, the wheel unrolled from 0 to 360 degrees at the current lightness and chroma.
	 */
	private get hueTrack(): string {
		const stops = this.trackStops( 13, ( t ) => `oklch(${this.lightness}% ${this.chroma} ${Math.round( t * 360 )})` );

		return `linear-gradient(to right, ${stops})`;
	}

	/**
	 * Builds an evenly spaced gradient stop list from a color-per-position function.
	 *
	 * @param count - How many stops to place from 0 to 100 percent inclusive.
	 * @param colorAt - The color for a position, where the argument runs 0 to 1.
	 * @returns The comma-joined `color percent%` stop list.
	 */
	private trackStops( count: number, colorAt: ( t: number ) => string ): string {
		const stops: string[] = [];

		for ( let i = 0; i < count; i += 1 ) {
			const t = i / ( count - 1 );
			stops.push( `${colorAt( t )} ${( t * 100 ).toFixed( 1 )}%` );
		}

		return stops.join( ', ' );
	}

	/**
	 * Formats a resolved sRGB color as the `rgb()` string a legacy notation would spell it as.
	 *
	 * @param color - The resolved sRGB color with channels on a 0 to 1 scale.
	 * @returns The `rgb(r, g, b)` string with 0 to 255 channel bytes.
	 */
	private toRgbText( color: SrgbColor ): string {
		const byte = ( channel: number ): number => {
			return Math.round( channel * 255 );
		};

		return `rgb(${byte( color.r )}, ${byte( color.g )}, ${byte( color.b )})`;
	}

	/**
	 * Formats an sRGB color as a lowercase hex string, the spelling the Tier 0 floor uses.
	 *
	 * @param color - The resolved sRGB color with channels on a 0 to 1 scale.
	 * @returns The `#rrggbb` hex string.
	 */
	private toHex( color: SrgbColor ): string {
		const byte = ( channel: number ): string => {
			return Math.round( channel * 255 ).toString( 16 ).padStart( 2, '0' );
		};

		return `#${byte( color.r )}${byte( color.g )}${byte( color.b )}`;
	}

	/**
	 * Updates the lightness slider from its strip.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onLightness = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.lightness = Number( event.target.value );
		}
	};

	/**
	 * Updates the chroma slider from its strip.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onChroma = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.chroma = Number( event.target.value );
		}
	};

	/**
	 * Updates the hue slider from its strip.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onHue = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.hue = Number( event.target.value );
		}
	};

	/**
	 * Renders the three gradient sliders, the painted swatch, and the resolved rgb and hex readback.
	 */
	render() {
		const outOfGamut = this.outOfSrgbGamut;
		const pole = this.lightnessPole;
		const resolved = this.resolved;
		const clipped = this.clipped;

		return html`
			<div class="demo">
				<h3 class="demo-title">Three sliders, one color</h3>
				<div class="sliders">
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="l-slider">Lightness</label>
							<span class="control-value">${this.lightness}%</span>
						</div>
						<input
							id="l-slider"
							class="slider-strip"
							type="range"
							min="0"
							max="100"
							step="1"
							.value=${String( this.lightness )}
							@input=${this.onLightness}
							style="background: var(--line, #e7e6e2); background: ${this.lightnessTrack};"
						/>
						<p class="slider-hint">Black to white, independent of the other two sliders.</p>
					</div>
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="c-slider">Chroma</label>
							<span class="control-value">${this.chroma}</span>
						</div>
						<input
							id="c-slider"
							class="slider-strip"
							type="range"
							min="0"
							max="0.4"
							step="0.005"
							.value=${String( this.chroma )}
							@input=${this.onChroma}
							style="background: var(--line, #e7e6e2); background: ${this.chromaTrack};"
						/>
						<p class="slider-hint">Neutral gray out to as vivid as it gets, an absolute distance, not a relative saturation.</p>
					</div>
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="h-slider">Hue</label>
							<span class="control-value">${this.hue}</span>
						</div>
						<input
							id="h-slider"
							class="slider-strip"
							type="range"
							min="0"
							max="360"
							step="1"
							.value=${String( this.hue )}
							@input=${this.onHue}
							style="background: var(--line, #e7e6e2); background: ${this.hueTrack};"
						/>
						<p class="slider-hint">The color family around the wheel, red near 30, green near 145, blue at 260.</p>
					</div>
				</div>
				<!-- The hex floor before the literal oklch() is the component's own Tier 0 pattern, so an engine without the function paints the floor instead of nothing. -->
				<div class="preview-swatch" style="background: #488bfb; background: ${this.oklchString};"></div>
				<p class="readback">
					<span>You wrote</span>
					<span class="chip-swatch" aria-hidden="true" style="background: #488bfb; background: ${this.oklchString};"></span>
					<span class="code-chip">${this.oklchString}</span>
					${resolved && ! outOfGamut
						? html`
							<span>which is</span>
							<span class="chip-swatch" aria-hidden="true" style="background: ${this.toHex( resolved )};"></span>
							<span class="code-chip">${this.toRgbText( resolved )}</span>
							<span class="code-chip">${this.toHex( resolved )}</span>
						`
						: null }
					${resolved && clipped && outOfGamut
						? html`
							<span>an sRGB screen shows about</span>
							<span class="chip-swatch" aria-hidden="true" style="background: ${this.toHex( clipped )};"></span>
							<span class="code-chip">${this.toRgbText( clipped )}</span>
							<span class="code-chip">${this.toHex( clipped )}</span>
							<span>while the CSS mapping spells it</span>
							<span class="chip-swatch" aria-hidden="true" style="background: ${this.toHex( resolved )};"></span>
							<span class="code-chip">${this.toRgbText( resolved )}</span>
							<span class="code-chip">${this.toHex( resolved )}</span>
						`
						: null }
				</p>
				${SUPPORTS_OKLCH
					? null
					: html`
						<p class="readback">
							<span class="report-verdict" data-pass="false">no oklch() here</span>
							<span>This browser does not parse the function, so the hex floor is what paints and the sliders no longer drive the swatch.</span>
						</p>
					` }
				${pole === 'white' && SUPPORTS_OKLCH
					? html`
						<p class="readback">
							<span class="report-verdict" data-pass="false">lightness pole</span>
							<span>Nothing at white's own lightness can also be vivid, so the contradiction has to break one way or the other. The clip keeps a visible tint but bends it, dropping most of the chroma and letting the hue drift, which is the working group's own complaint about clipping, while the mapping algorithm keeps the lightness and answers plain white, the same policy that pins a runaway calc(l + 20) to white. Past the gamut there is no single true hex, only a policy.</span>
						</p>
					`
					: null }
				${pole === 'black' && SUPPORTS_OKLCH
					? html`
						<p class="readback">
							<span class="report-verdict" data-pass="false">lightness pole</span>
							<span>Nothing at black's own lightness can also be vivid, so the same contradiction breaks here the other way. The clip keeps a faint bent tint, which is what you are seeing, while the mapping algorithm keeps the lightness and answers plain black, the mirror of the rule that pins a runaway calc(l + 20) to white. Past the gamut there is no single true hex, only a policy.</span>
						</p>
					`
					: null }
				${outOfGamut && pole === null && SUPPORTS_OKLCH
					? html`
						<p class="readback">
							<span class="report-verdict" data-pass="false">outside sRGB</span>
							<span>These numbers overshoot what sRGB can hold, so one honest hex stops existing and the demo prints two. The paint keeps the vividness by clipping each channel at its limit, while the CSS mapping algorithm keeps the lightness and walks chroma down, and a wide-gamut display can sit past both.</span>
						</p>
					`
					: null }
				<p class="demo-note">
					Each strip previews its slider's range at the other two sliders' current values, so moving one repaints the other two.
					The sliders open on the article's canonical accent, which resolves to <span class="chip-swatch" aria-hidden="true" style="background: #488bfb;"></span> <span class="code-chip">rgb(72, 139, 251)</span>, exactly the <span class="code-chip">#488bfb</span> the Tier 0 floor spells it as in step 7.
					Lightness is the perceptual slider, so equal steps look like equal changes, the promise HSL's lightness does not keep.
				</p>
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'demo-color-token-contract-color-tokens-oklch-dials': OklchDialsDemo;
	}
}

import { LitElement, html, css } from 'lit';
import { customElement, state, query } from 'lit/decorators.js';
import { pickForeground } from '../library/color-tokens-shared/contrast';
import { demoChrome } from '../library/color-tokens-shared/chrome';

/**
 * The WCAG 2 AA threshold for normal-size text, the bar the report reads each ratio against.
 */
const AA_NORMAL = 4.5;

/**
 * The lightness, on the oklch 0 to 100 percent scale, at which the canonical accent lands so its foreground pick is black.
 *
 * It is the article's pinned value, so the lab opens on the central lesson rather than asking the reader to find it.
 */
const CANONICAL_LIGHTNESS = 65;

/**
 * Whether the engine ships `contrast-color()`, checked once so the lab can show the live browser pick beside the WCAG 2 comparison when it exists.
 *
 * When it is missing the WCAG 2 comparison drives the badge and explains the black-versus-white result, and where `contrast-color()` runs the live browser pick is the authoritative one, since CSS Color 5 leaves the exact algorithm user-agent defined.
 */
const SUPPORTS_CONTRAST_COLOR = CSS.supports( 'color', 'contrast-color(red)' );

/**
 * D3, the contrast-color lab, where the platform picks the foreground and the pick is often black.
 *
 * A gradient-strip lightness slider moves a source `oklch(L 0.18 260)`, its track painting the slider's whole range at the pinned chroma and hue, opening on the canonical accent where black wins, and the report prints both WCAG ratios so the reader sees black beat white on a medium blue.
 * Where `contrast-color()` ships, the badge's foreground is the live `contrast-color(var(--accent))` result, read back and shown beside the WCAG 2 comparison, which lands on the same result for these accents; where it does not, the WCAG 2 comparison drives the badge.
 * The senior move is the closing beat: a brand that wants white changes the contract by darkening the accent until white is the higher-contrast pick, rather than overriding the browser's pick by hand.
 *
 * @element demo-color-token-contract-color-tokens-contrast-lab
 */
@customElement( 'demo-color-token-contract-color-tokens-contrast-lab' )
export class ContrastLabDemo extends LitElement {

	/**
	 * The source lightness on the oklch 0 to 100 percent scale, driven by the slider.
	 *
	 * Chroma and hue are pinned, so lightness alone flips the foreground and the demo opens on the canonical accent's value.
	 */
	@state()
	private lightness = CANONICAL_LIGHTNESS;

	/**
	 * The badge whose foreground is the live `contrast-color()` result, read back to display when the function is supported.
	 */
	@query( '.platform-badge' )
	private $platformBadge?: HTMLElement;

	/**
	 * The computed foreground the platform painted, read from the badge after each render, or an empty string before the first read.
	 */
	@state()
	private platformForeground = '';

	/**
	 * Styles for the harness, composed on the shared demo chrome.
	 *
	 * The badge fill is the source accent; the platform badge sets its foreground with `contrast-color()` so the engine, not the JavaScript, paints it.
	 */
	static styles = [
		demoChrome,
		css`
			.badges {
				display: flex;
				flex-wrap: wrap;
				gap: var(--space-3, 12px);
			}

			.badge {
				display: inline-flex;
				align-items: center;
				padding: 0.4em 0.9em;
				border-radius: var(--radius-pill, 999px);
				background: var(--accent-source, oklch(65% 0.18 260));
				font-weight: 600;
				font-size: var(--fs-14, 14px);
			}

			/* The JavaScript badge paints the WCAG 2 winner the shared helper returns, so it works on every engine. */
			.js-badge {
				color: var(--js-foreground, black);
			}

			/* The platform badge lets contrast-color() pick, and the lab reads that pick back to show it beside the WCAG 2 comparison. */
			.platform-badge {
				color: contrast-color(var(--accent-source, oklch(65% 0.18 260)));
			}

			.badge-stack {
				display: flex;
				flex-direction: column;
				gap: var(--space-1, 4px);
				align-items: flex-start;
			}

			.badge-caption {
				font-size: var(--fs-12, 12px);
				color: var(--ink-soft, #56565c);
			}

			.senior {
				display: flex;
				flex-wrap: wrap;
				align-items: center;
				gap: var(--space-3, 12px);
				padding: var(--space-3, 12px);
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
				background: var(--tint, #eef2fe);
			}

			.senior-button {
				padding: 0.4em 0.8em;
				border: 1px solid var(--accent, #2257e6);
				border-radius: var(--radius-sm, 7px);
				background: var(--surface, #fff);
				color: var(--accent, #2257e6);
				font: inherit;
				font-size: var(--fs-13, 13px);
				font-weight: 600;
				cursor: pointer;
			}

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

			.senior-text {
				margin: 0;
				font-size: var(--fs-13, 13px);
				color: var(--ink-soft, #56565c);
			}
		`,
	];

	/**
	 * Reads the platform foreground back after each render so the printed value matches what `contrast-color()` painted.
	 *
	 * It only reads when the function is supported and the badge exists, so an engine without `contrast-color()` simply shows the WCAG 2 winner.
	 */
	updated(): void {
		if ( ! SUPPORTS_CONTRAST_COLOR || ! this.$platformBadge ) {
			return;
		}

		const next = getComputedStyle( this.$platformBadge ).color;

		if ( next !== this.platformForeground ) {
			this.platformForeground = next;
		}
	}

	/**
	 * The current source accent as an oklch string, built from the pinned chroma and hue and the slider lightness.
	 *
	 * Keeping chroma and hue fixed makes lightness the only variable, so the foreground flip is attributable to one slider.
	 */
	private get accent(): string {
		return `oklch(${this.lightness}% 0.18 260)`;
	}

	/**
	 * The lightness strip's gradient, the slider's whole range painted at the pinned chroma and hue, so the control previews exactly what moving it selects.
	 */
	private get lightnessTrack(): string {
		const stops: string[] = [];

		for ( let i = 0; i < 13; i += 1 ) {
			const t = i / 12;
			const lightness = Math.round( 20 + t * 75 );
			stops.push( `oklch(${lightness}% 0.18 260) ${( t * 100 ).toFixed( 1 )}%` );
		}

		return `linear-gradient(to right, ${stops.join( ', ' )})`;
	}

	/**
	 * Updates the source lightness from the slider.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onLightness = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.lightness = Number( event.target.value );
		}
	};

	/**
	 * Changes the contract so white becomes the higher-contrast pick, the senior alternative to overriding the foreground.
	 *
	 * It darkens the accent by lowering lightness until black no longer wins, which is what a brand that wants white text should do rather than shipping the lower-contrast pair.
	 */
	private darkenForWhite = (): void => {
		this.lightness = 38;
	};

	/**
	 * Renders one report row for a candidate foreground, with its ratio and AA verdict.
	 *
	 * @param label - The row label naming the candidate.
	 * @param ratio - The WCAG ratio of the candidate on the accent.
	 * @param isWcagWinner - Whether this candidate wins the WCAG 2 comparison.
	 * @returns The rendered report row.
	 */
	private reportRow( label: string, ratio: number, isWcagWinner: boolean ) {
		const passes = ratio >= AA_NORMAL;

		return html`
			<div class="report-row">
				<span class="report-label">${label}${isWcagWinner ? ' (WCAG 2 winner)' : ''}</span>
				<span class="report-ratio">${ratio.toFixed( 2 )}:1</span>
				<span class="report-verdict" data-pass=${passes ? 'true' : 'false'}>${passes ? 'AA pass' : 'AA fail'}</span>
			</div>
		`;
	}

	/**
	 * Renders the slider, the badges, the dual-ratio report, and the change-the-contract panel.
	 */
	render() {
		const pick = pickForeground( this.accent );

		return html`
			<div class="demo" style="--accent-source:${this.accent}; --js-foreground:${pick?.foreground ?? 'black'};">
				<h3 class="demo-title">Lightness drives the foreground pick</h3>
				<div class="sliders">
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="lightness">Lightness</label>
							<span class="control-value">${this.lightness}%</span>
						</div>
						<input
							id="lightness"
							class="slider-strip"
							type="range"
							min="20"
							max="95"
							step="1"
							.value=${String( this.lightness )}
							@input=${this.onLightness}
							style="background: var(--line, #e7e6e2); background: ${this.lightnessTrack};"
						/>
						<p class="slider-hint">Only lightness moves; chroma stays 0.18 and hue 260, so the foreground flip is attributable to one thing.</p>
					</div>
				</div>
				<div class="badges">
					<div class="badge-stack">
						<span class="badge js-badge">Featured</span>
						<span class="badge-caption">WCAG 2 winner: ${pick?.foreground ?? 'n/a'}</span>
					</div>
					${SUPPORTS_CONTRAST_COLOR
						? html`
							<div class="badge-stack">
								<span class="badge platform-badge">Featured</span>
								<span class="badge-caption">contrast-color(): ${this.platformForeground || 'reading'}</span>
							</div>
						`
						: html`
							<div class="badge-stack">
								<span class="badge-caption">contrast-color() is not supported here, so the badge falls back to the WCAG 2 winner.</span>
							</div>
						` }
				</div>
				${pick
					? html`
						<div class="report">
							${this.reportRow( 'Black on accent', pick.blackRatio, pick.foreground === 'black' )}
							${this.reportRow( 'White on accent', pick.whiteRatio, pick.foreground === 'white' )}
						</div>
					`
					: html`<p class="demo-note">That accent does not parse, so there is nothing to score.</p>` }
				<p class="demo-note">
					On the canonical <span class="code-chip">oklch(65% 0.18 260)</span> <strong>black</strong> wins, where a brand reflexively reaches for white.
					Slide lightness down and the winner flips to white, so the binary tracks lightness, and a passing ratio can still read poorly on a mid-tone, which is why the mid-tones still want a human eye.
					At the slider's far ends <span class="code-chip">oklch(L 0.18 260)</span> leaves the sRGB gamut, where the browser paints a chroma-reduced mapping and the report scores the accent mapped the same way rather than the raw string.
				</p>
				<div class="senior">
					<button type="button" class="senior-button" @click=${this.darkenForWhite}>Make white readable</button>
					<p class="senior-text">
						When the brand wants white, change the contract by darkening the accent until white earns the higher-contrast pick, rather than overriding the browser's pick by hand.
					</p>
				</div>
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'demo-color-token-contract-color-tokens-contrast-lab': ContrastLabDemo;
	}
}

import { LitElement, html, css } from 'lit';
import { customElement, state, query } from 'lit/decorators.js';
import { demoChrome } from '../library/color-tokens-shared/chrome';

/**
 * D4, the container mix, where the interpolation space is the visible decision.
 *
 * The badge's own container mix, the accent against `canvas` at one percentage, is computed twice, once `in srgb` and once `in oklab`, with the value the browser actually paints printed under each, and for that near-neutral tint the two spaces land almost together, which the note says out loud.
 * The mix slider is a gradient strip painting its own range of oklab tints for the current accent, so the control previews what each position selects before the reader commits to it.
 * A second, fixed pair mixes the accent against the opener's brand yellow at 50 percent, where the paths split visibly, srgb toward olive and oklab toward a cooler sage, so the reader sees what naming the space protects even though the badge itself never mixes distant hues.
 *
 * @element demo-color-token-contract-color-tokens-container-mix
 */
@customElement( 'demo-color-token-contract-color-tokens-container-mix' )
export class ContainerMixDemo extends LitElement {

	/**
	 * The accent feeding both mixes, driven by the color input.
	 *
	 * It starts on the canonical accent so the demo opens on the article's running color.
	 */
	@state()
	private accent = '#488bfb';

	/**
	 * The mix percentage of accent against canvas, shared by both spaces so only the space differs.
	 *
	 * A soft-badge variant's container tint mixes near 16 percent, the default here, and raising it deepens the tint while the two spaces keep nearly agreeing on this near-neutral pair, which is exactly why the fixed distant-hue pair below exists.
	 */
	@state()
	private mix = 16;

	/**
	 * The mix strip's gradient, the slider's range painted as the oklab mix of the current accent toward canvas, so the control shows the tints it selects and follows the scheme the way the swatches do.
	 */
	private get mixTrack(): string {
		const stops: string[] = [];

		for ( let i = 0; i < 9; i += 1 ) {
			const t = i / 8;
			const percent = Math.round( 8 + t * 52 );
			stops.push( `color-mix(in oklab, ${this.accent} ${percent}%, canvas) ${( t * 100 ).toFixed( 1 )}%` );
		}

		return `linear-gradient(to right, ${stops.join( ', ' )})`;
	}

	/**
	 * The srgb container swatch, read back to print the value the browser paints.
	 */
	@query( '.srgb-swatch' )
	private $srgbSwatch!: HTMLElement;

	/**
	 * The oklab container swatch, read back to print the value the browser paints.
	 */
	@query( '.oklab-swatch' )
	private $oklabSwatch!: HTMLElement;

	/**
	 * The computed srgb mix, read from the painted swatch after each render, or an empty string before the first read.
	 */
	@state()
	private srgbComputed = '';

	/**
	 * The computed oklab mix, read from the painted swatch after each render, or an empty string before the first read.
	 */
	@state()
	private oklabComputed = '';

	/**
	 * The srgb distant-hue swatch, read back to print the value the browser paints.
	 */
	@query( '.hue-srgb-swatch' )
	private $hueSrgbSwatch!: HTMLElement;

	/**
	 * The oklab distant-hue swatch, read back to print the value the browser paints.
	 */
	@query( '.hue-oklab-swatch' )
	private $hueOklabSwatch!: HTMLElement;

	/**
	 * The computed srgb distant-hue mix, read from the painted swatch after each render, or an empty string before the first read.
	 */
	@state()
	private hueSrgbComputed = '';

	/**
	 * The computed oklab distant-hue mix, read from the painted swatch after each render, or an empty string before the first read.
	 */
	@state()
	private hueOklabComputed = '';

	/**
	 * Styles for the harness, composed on the shared demo chrome.
	 *
	 * Each swatch applies its own `color-mix` so the browser, not the JavaScript, computes the result, and the code reads the painted value back rather than re-deriving it.
	 */
	static styles = [
		demoChrome,
		css`
			.pair {
				display: grid;
				grid-template-columns: 1fr 1fr;
				gap: var(--space-3, 12px);
			}

			.space {
				display: flex;
				flex-direction: column;
				gap: var(--space-2, 8px);
				padding: var(--space-3, 12px);
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
				background: var(--bg, #fcfcfb);
			}

			.space-name {
				font-family: var(--font-mono, ui-monospace, monospace);
				font-size: var(--fs-12, 12px);
				color: var(--ink, #17171a);
			}

			.container-swatch {
				height: 4rem;
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
			}

			/* The two swatches differ only by interpolation space; the accent and the percentage are identical. */
			.srgb-swatch {
				background: color-mix(in srgb, var(--accent-source, #488bfb) var(--mix, 16%), canvas);
			}

			.oklab-swatch {
				background: color-mix(in oklab, var(--accent-source, #488bfb) var(--mix, 16%), canvas);
			}

			/* The distant-hue pair is pinned at 50 percent against the opener's brand yellow, the case where the two paths visibly split, srgb toward olive and oklab toward a cooler sage. */
			.hue-srgb-swatch {
				background: color-mix(in srgb, var(--accent-source, #488bfb) 50%, #ffd60a);
			}

			.hue-oklab-swatch {
				background: color-mix(in oklab, var(--accent-source, #488bfb) 50%, #ffd60a);
			}

			.pair-title {
				margin: 0;
				font-size: var(--fs-12, 12px);
				color: var(--ink-soft, #56565c);
			}

			.computed {
				font-family: var(--font-mono, ui-monospace, monospace);
				font-size: var(--fs-12, 12px);
				color: var(--ink-soft, #56565c);
				word-break: break-all;
			}

			@media (max-width: 30rem) {
				.pair {
					grid-template-columns: 1fr;
				}
			}
		`,
	];

	/**
	 * Reads all four painted swatches after every render so the printed values track the live mixes.
	 *
	 * Reading the computed `backgroundColor` back is the honest move: the browser owns the interpolation, and the lab reports what it produced instead of re-implementing the mix in JavaScript.
	 */
	updated(): void {
		if ( ! this.$srgbSwatch || ! this.$oklabSwatch || ! this.$hueSrgbSwatch || ! this.$hueOklabSwatch ) {
			return;
		}

		const nextSrgb = getComputedStyle( this.$srgbSwatch ).backgroundColor;
		const nextOklab = getComputedStyle( this.$oklabSwatch ).backgroundColor;
		const nextHueSrgb = getComputedStyle( this.$hueSrgbSwatch ).backgroundColor;
		const nextHueOklab = getComputedStyle( this.$hueOklabSwatch ).backgroundColor;

		if ( nextSrgb !== this.srgbComputed ) {
			this.srgbComputed = nextSrgb;
		}

		if ( nextOklab !== this.oklabComputed ) {
			this.oklabComputed = nextOklab;
		}

		if ( nextHueSrgb !== this.hueSrgbComputed ) {
			this.hueSrgbComputed = nextHueSrgb;
		}

		if ( nextHueOklab !== this.hueOklabComputed ) {
			this.hueOklabComputed = nextHueOklab;
		}
	}

	/**
	 * Updates the accent from the color input.
	 *
	 * @param event - The input event from the color picker.
	 */
	private onPick = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.accent = event.target.value;
		}
	};

	/**
	 * Updates the shared mix percentage from the slider.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onMix = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.mix = Number( event.target.value );
		}
	};

	/**
	 * Renders the controls and the two container swatches with their computed values.
	 */
	render() {
		return html`
			<div class="demo" style="--accent-source:${this.accent}; --mix:${this.mix}%;">
				<h3 class="demo-title">The same container, mixed two ways</h3>
				<div class="controls">
					<div class="control">
						<label class="control-label" for="accent">Accent</label>
						<input id="accent" type="color" .value=${this.accent} @input=${this.onPick} />
						<span class="control-value">${this.accent}</span>
					</div>
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="mix">Mix amount</label>
							<span class="control-value">${this.mix}%</span>
						</div>
						<input
							id="mix"
							class="slider-strip"
							type="range"
							min="8"
							max="60"
							step="1"
							.value=${String( this.mix )}
							@input=${this.onMix}
							style="background: var(--line, #e7e6e2); background: ${this.mixTrack};"
						/>
						<p class="slider-hint">How much accent survives the mix toward canvas, shared by both spaces so only the space differs.</p>
					</div>
				</div>
				<p class="pair-title">The badge's own mix, the accent tinted toward canvas.</p>
				<div class="pair">
					<div class="space">
						<span class="space-name">color-mix(in srgb, accent ${this.mix}%, canvas)</span>
						<div class="container-swatch srgb-swatch"></div>
						<span class="computed">${this.srgbComputed}</span>
					</div>
					<div class="space">
						<span class="space-name">color-mix(in oklab, accent ${this.mix}%, canvas)</span>
						<div class="container-swatch oklab-swatch"></div>
						<span class="computed">${this.oklabComputed}</span>
					</div>
				</div>
				<p class="pair-title">A distant-hue pair, pinned at 50 percent against the opener's brand yellow, where the space decision turns visible.</p>
				<div class="pair">
					<div class="space">
						<span class="space-name">color-mix(in srgb, accent 50%, #ffd60a)</span>
						<div class="container-swatch hue-srgb-swatch"></div>
						<span class="computed">${this.hueSrgbComputed}</span>
					</div>
					<div class="space">
						<span class="space-name">color-mix(in oklab, accent 50%, #ffd60a)</span>
						<div class="container-swatch hue-oklab-swatch"></div>
						<span class="computed">${this.hueOklabComputed}</span>
					</div>
				</div>
				<p class="demo-note">
					In the canvas pair only the space differs, and for this blue tint toward a near-neutral surface the two results land almost together, differing past the digits that matter.
					In the distant-hue pair the same decision turns visible, srgb dragging the midpoint toward olive while oklab holds a cooler sage.
					The badge writes <strong>in oklab</strong> on purpose, a more perceptually uniform blend than sRGB, and the author names that space as part of the contract rather than letting a default stand in or trusting the endpoints to stay friendly.
				</p>
				<p class="demo-note">
					The polar spaces (<span class="code-chip">oklch</span>, <span class="code-chip">hsl</span>) add a second choice, the hue arc, where <span class="code-chip">longer hue</span> takes the other way around the wheel, but the badge never mixes across distant hues, so that stays a note here rather than a control.
				</p>
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'demo-color-token-contract-color-tokens-container-mix': ContainerMixDemo;
	}
}

import { LitElement, html, css } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { resolveToSrgb } from '../library/color-tokens-shared/contrast';
import { demoChrome } from '../library/color-tokens-shared/chrome';

/**
 * A trusted brand token the picker can apply as a real `var(--brand-*)` reference.
 *
 * The label names it for the button, the token is the custom property the demo root defines, and the swatch color is only for the button's own chip, never the value applied to the panel.
 */
interface BrandToken {

	/**
	 * The label shown on the token button.
	 */
	label: string;

	/**
	 * The custom-property reference applied to the panel, for example `var(--brand-blue)`.
	 *
	 * This is a design-system token, so it is trusted and set directly, the path the free-text field deliberately rejects.
	 */
	token: string;

	/**
	 * The concrete color the demo root binds the token to, used only to tint the button's own swatch.
	 */
	swatch: string;
}

/**
 * The curated brand tokens, the trusted half of the input split.
 *
 * A consumer picks one of these named tokens and the panel applies `var(--brand-*)` directly, because a design-system reference is a trusted token rather than a user-typed color.
 */
const BRAND_TOKENS: readonly BrandToken[] = [
	{ label: '--brand-blue', token: 'var(--brand-blue)', swatch: '#5566d8' },
	{ label: '--brand-teal', token: 'var(--brand-teal)', swatch: '#0f9e8f' },
	{ label: '--brand-plum', token: 'var(--brand-plum)', swatch: '#8a4fb0' },
];

/**
 * D5, alpha from any color, with the input-trust split made visible.
 *
 * A free-text field takes an absolute color in the common syntaxes, named, hex, hsl, or oklch, gated by `CSS.supports` and resolved to a concrete value before it ever becomes a CSS value, and a separate picker applies a trusted `var(--brand-*)` token directly, so the two trust levels never share a path.
 * The accepted accent feeds two panels that look similar and are not: one stores the alpha in the color with `color-mix(in srgb, accent 20%, transparent)`, the other leaves the color opaque and fades the whole element with `opacity`.
 * Over a striped backdrop the difference shows: the color-mix panel keeps crisp opaque text and border while only its fill is translucent, and the opacity panel fades its text and border too, which is why a translucent color and a faded element are different decisions.
 *
 * @element demo-color-token-contract-color-tokens-alpha-lab
 */
@customElement( 'demo-color-token-contract-color-tokens-alpha-lab' )
export class AlphaLabDemo extends LitElement {

	/**
	 * The accent currently applied to the two panels, either an accepted free-text color or a trusted token reference.
	 *
	 * It starts on the canonical accent so the panels open on the article's running color.
	 */
	@state()
	private accent = 'oklch(65% 0.18 260)';

	/**
	 * The raw text in the free-text field, kept separate from `accent` so a rejected value never reaches the panels.
	 */
	@state()
	private draft = 'oklch(65% 0.18 260)';

	/**
	 * Why the current draft was rejected, or `null` when it is a valid color.
	 *
	 * It drives the inline error, so an invalid string is shown as rejected rather than injected into the panels.
	 */
	@state()
	private rejection: string | null = null;

	/**
	 * Styles for the harness, composed on the shared demo chrome.
	 *
	 * The brand tokens are defined here on `.demo` so a `var(--brand-*)` reference resolves, and the striped backdrop is what makes the alpha difference observable.
	 */
	static styles = [
		demoChrome,
		css`
			.demo {
				/* The trusted design-system tokens live on the demo root, so a var(--brand-*) reference the picker applies resolves in the cascade. */
				--brand-blue: #5566d8;
				--brand-teal: #0f9e8f;
				--brand-plum: #8a4fb0;
			}

			.token-row {
				display: flex;
				flex-wrap: wrap;
				gap: var(--space-2, 8px);
			}

			.token {
				display: inline-flex;
				align-items: center;
				gap: 0.45em;
				padding: 0.35em 0.7em;
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
				background: var(--surface, #fff);
				color: var(--ink, #17171a);
				font-family: var(--font-mono, ui-monospace, monospace);
				font-size: var(--fs-12, 12px);
				cursor: pointer;
			}

			.token:hover {
				background: var(--tint, #eef2fe);
			}

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

			.token-swatch {
				width: 0.9em;
				height: 0.9em;
				border-radius: 3px;
				border: 1px solid var(--line, #e7e6e2);
			}

			.error {
				margin: 0;
				font-size: var(--fs-13, 13px);
				color: color-mix(in oklab, crimson 75%, var(--ink, #17171a));
			}

			.ok {
				margin: 0;
				font-size: var(--fs-13, 13px);
				color: var(--ink-soft, #56565c);
			}

			.panels {
				display: grid;
				grid-template-columns: 1fr 1fr;
				gap: var(--space-3, 12px);
			}

			/* The striped backdrop sits behind both panels, so a translucent fill lets the stripes show through and a faded element does too, which is how the eye tells the two apart. */
			.stage {
				display: flex;
				flex-direction: column;
				gap: var(--space-1, 4px);
			}

			.stage-label {
				font-size: var(--fs-12, 12px);
				color: var(--ink-soft, #56565c);
			}

			.backdrop {
				padding: var(--space-3, 12px);
				border-radius: var(--radius-sm, 7px);
				background:
					repeating-linear-gradient(
						45deg,
						var(--line-soft, #f2f1ec),
						var(--line-soft, #f2f1ec) 8px,
						var(--line, #e7e6e2) 8px,
						var(--line, #e7e6e2) 16px
					);
			}

			.panel {
				display: flex;
				align-items: center;
				justify-content: center;
				min-height: 4.5rem;
				padding: var(--space-3, 12px);
				border: 2px solid var(--accent-source, #5566d8);
				border-radius: var(--radius-sm, 7px);
				color: var(--ink, #17171a);
				font-weight: 600;
				font-size: var(--fs-13, 13px);
				text-align: center;
			}

			/* Alpha lives in the color: only the fill is translucent, while the border and text stay fully opaque. */
			.panel.color-alpha {
				background: color-mix(in srgb, var(--accent-source, #5566d8) 20%, transparent);
			}

			/* Alpha lives on the element: the color is opaque but opacity fades the fill, the border, and the text together. */
			.panel.element-opacity {
				background: var(--accent-source, #5566d8);
				opacity: 0.2;
			}

			@media (max-width: 32rem) {
				.panels {
					grid-template-columns: 1fr;
				}
			}
		`,
	];

	/**
	 * Validates and applies the free-text draft, the untrusted path.
	 *
	 * It trims the value, rejects an empty string, a `var()` reference (a trusted design-system token, which belongs on the picker path), and the CSS-wide keywords (which resolve to something other than a concrete color), then gates syntax with `CSS.supports` and resolves the value to a concrete color, so a typo or a context-dependent color like `currentColor` updates the error rather than the panels.
	 *
	 * @param event - The input event from the free-text field.
	 */
	private onDraftInput = ( event: Event ): void => {
		if ( ! ( event.target instanceof HTMLInputElement ) ) {
			return;
		}

		this.draft = event.target.value;
		const candidate = this.draft.trim();

		if ( candidate === '' ) {
			this.rejection = 'Type a color to apply it.';
			return;
		}

		if ( /\bvar\s*\(/.test( candidate.toLowerCase() ) ) {
			this.rejection = 'A var() reference is a trusted token, so apply it from the picker below.';
			return;
		}

		if ( [ 'inherit', 'initial', 'unset', 'revert', 'revert-layer' ].includes( candidate.toLowerCase() ) ) {
			this.rejection = 'A CSS-wide keyword resolves to something other than a concrete color, so it is rejected, not applied.';
			return;
		}

		if ( ! CSS.supports( 'color', candidate ) ) {
			this.rejection = 'That is not a color the browser can parse, so it is rejected, not applied.';
			return;
		}

		if ( resolveToSrgb( candidate ) === null ) {
			this.rejection = 'That is a valid color, but one this field cannot resolve to a fixed value, like currentColor, a system color, or a nested color function, so it takes only plain absolute colors.';
			return;
		}

		this.rejection = null;
		this.accent = candidate;
	};

	/**
	 * Applies a trusted brand token directly, the path a design-system reference takes.
	 *
	 * It clears any free-text rejection and sets the accent to a `var(--brand-*)` reference, which resolves against the tokens defined on the demo root.
	 *
	 * @param token - The brand token reference to apply.
	 */
	private applyToken( token: string ): void {
		this.rejection = null;
		this.accent = token;
	}

	/**
	 * Renders the two input paths, the inline validation, and the two alpha panels over the striped backdrop.
	 */
	render() {
		return html`
			<div class="demo">
				<h3 class="demo-title">Two inputs, two trust levels, one accent</h3>
				<div class="controls">
					<div class="control">
						<label class="control-label" for="free-text">Free text</label>
						<input
							id="free-text"
							type="text"
							.value=${this.draft}
							placeholder="named, hex, hsl(), or oklch()"
							aria-invalid=${this.rejection !== null ? 'true' : 'false'}
							aria-describedby="free-text-note"
							@input=${this.onDraftInput}
						/>
					</div>
				</div>
				<p id="free-text-note" class=${this.rejection ? 'error' : 'ok'} role="status">
					${this.rejection ?? html`Accepted, applied as <span class="code-chip">${this.accent}</span>.`}
				</p>
				<div class="token-row">
					${BRAND_TOKENS.map(
						( brand ) => html`
							<button type="button" class="token" @click=${() => this.applyToken( brand.token )}>
								<span class="token-swatch" style="background:${brand.swatch};"></span>
								${brand.label}
							</button>
						`,
					)}
				</div>
				<div class="panels" style="--accent-source:${this.accent};">
					<div class="stage">
						<span class="stage-label">Translucent color: <span class="code-chip">color-mix(in srgb, accent 20%, transparent)</span></span>
						<div class="backdrop">
							<div class="panel color-alpha">Crisp text, crisp border</div>
						</div>
					</div>
					<div class="stage">
						<span class="stage-label">Faded element: <span class="code-chip">opacity: 0.2</span></span>
						<div class="backdrop">
							<div class="panel element-opacity">Faded text, faded border</div>
						</div>
					</div>
				</div>
				<p class="demo-note">
					Both panels read 20 percent, and they are not the same decision.
					The color-mix panel fades only its fill, so its border and label stay opaque, while <strong>opacity</strong> fades the whole element, label and border included, and composites the stripes differently.
				</p>
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'demo-color-token-contract-color-tokens-alpha-lab': AlphaLabDemo;
	}
}

import { LitElement, html, css } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { demoChrome } from '../library/color-tokens-shared/chrome';

/**
 * The source color every derivation starts from, the article's canonical accent.
 *
 * Keeping the source pinned makes the sliders the only variables, so the generated string reads as one accent plus a set of named channel adjustments.
 */
const SOURCE = 'oklch(65% 0.18 260)';

/**
 * D6, the relative color syntax lab, where channel math is a unitless number.
 *
 * Four gradient strips drive lightness, chroma, hue, and alpha through the relative form, each strip painting its own channel's range at the other three's current values, and a source-becomes-result row prints the exact string the result swatch paints, over stripes so a lowered alpha stays visible.
 * The dropped panel is live rather than a frozen exhibit: its valid cell paints the full four-slider string and follows every control, while the twin swaps only the lightness slot for the same number as a percentage and never moves, since one poisoned channel fails the entire declaration and the literal source floor shows through, so the drop is shown rather than described.
 * On an engine with no relative color syntax at all every relative declaration falls to its source floor, so the verdict line says that plainly, gated on a probe of the valid form.
 * The rule on screen is the lesson: in relative color syntax the channel keywords resolve to unitless numbers on a 0 to 1 scale, so a percentage cannot be added to one.
 *
 * @element demo-color-token-contract-color-tokens-relative-lab
 */
@customElement( 'demo-color-token-contract-color-tokens-relative-lab' )
export class RelativeLabDemo extends LitElement {

	/**
	 * The lightness delta added to the `l` channel, a unitless number on the 0 to 1 scale.
	 */
	@state()
	private lightnessDelta = 0.2;

	/**
	 * The chroma multiplier applied to the `c` channel, where 1 leaves chroma unchanged.
	 */
	@state()
	private chromaScale = 1;

	/**
	 * The hue delta added to the `h` channel, in degrees, the one channel that is an angle.
	 */
	@state()
	private hueDelta = 0;

	/**
	 * The alpha applied after the slash, from 0 (transparent) to 1 (opaque).
	 */
	@state()
	private alpha = 1;

	/**
	 * Styles for the harness, composed on the shared demo chrome, which owns the gradient strips.
	 *
	 * The stripes under the result swatch are what make a lowered alpha observable, the same trick the alpha lab's backdrop uses.
	 */
	static styles = [
		demoChrome,
		css`
			.becomes {
				display: flex;
				flex-wrap: wrap;
				align-items: center;
				gap: var(--space-2, 8px);
				font-size: var(--fs-13, 13px);
				color: var(--ink-soft, #56565c);
			}

			/* The striped stage under the result swatch, so a lowered alpha visibly lets the stripes through; inline-flex gives the inline span swatch inside it a real box. */
			.alpha-stage {
				display: inline-flex;
				padding: 0;
				border-radius: var(--radius-sm, 7px);
				background: repeating-linear-gradient(45deg, var(--line-soft, #f2f1ec), var(--line-soft, #f2f1ec) 6px, var(--line, #e7e6e2) 6px, var(--line, #e7e6e2) 12px);
			}

			.dropped {
				display: grid;
				grid-template-columns: 1fr 1fr;
				gap: var(--space-3, 12px);
				padding: var(--space-3, 12px);
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
				background: var(--bg, #fcfcfb);
			}

			.dropped-cell {
				display: flex;
				flex-direction: column;
				gap: var(--space-1, 4px);
			}

			.dropped-label {
				font-size: var(--fs-12, 12px);
				color: var(--ink-soft, #56565c);
			}

			/* Each cell paints the source's sRGB spelling as a floor (the same #488bfb the article's Tier 0 uses, so even an engine without oklch() shows the source color) and then its full relative string inline; the valid one applies and tracks every slider, while its twin carries a percentage in the lightness slot, so the entire declaration fails and the floor shows through, which is the drop made visible. */
			.dropped-swatch {
				height: 3rem;
				border: 1px solid var(--line, #e7e6e2);
				border-radius: var(--radius-sm, 7px);
			}

			.verdict-line {
				display: flex;
				align-items: center;
				gap: var(--space-2, 8px);
				font-size: var(--fs-12, 12px);
				color: var(--ink-soft, #56565c);
			}
		`,
	];

	/**
	 * Formats a signed channel adjustment as the calc() expression relative color syntax takes.
	 *
	 * The sign lives in the operator, so `0.2` prints `calc(l + 0.20)` and `-0.12` prints `calc(l - 0.12)`, the two spellings the article teaches.
	 *
	 * @param channel - The channel keyword, `l` or `h`.
	 * @param delta - The signed adjustment the slider holds.
	 * @param digits - How many decimals the number prints with, 2 for lightness and 0 for degrees.
	 * @returns The calc() expression for the channel slot.
	 */
	private signedCalc( channel: string, delta: number, digits: number ): string {
		const sign = delta >= 0 ? '+' : '-';

		return `calc(${channel} ${sign} ${Math.abs( delta ).toFixed( digits )})`;
	}

	/**
	 * Builds the relative-color string for a full set of channel positions, the one form every strip stop, the result swatch, and the printed string share.
	 *
	 * @param lightnessDelta - The signed lightness adjustment.
	 * @param chromaScale - The chroma multiplier.
	 * @param hueDelta - The signed hue rotation in degrees.
	 * @param alpha - The alpha after the slash.
	 * @returns The `oklch(from ...)` string for those positions.
	 */
	private relativeString( lightnessDelta: number, chromaScale: number, hueDelta: number, alpha: number ): string {
		const lightness = this.signedCalc( 'l', lightnessDelta, 2 );
		const chroma = `calc(c * ${chromaScale.toFixed( 2 )})`;
		const hue = this.signedCalc( 'h', hueDelta, 0 );

		return `oklch(from ${SOURCE} ${lightness} ${chroma} ${hue} / ${alpha.toFixed( 2 )})`;
	}

	/**
	 * The generated relative-color string for the current sliders, the exact value the result swatch paints and the reader copies.
	 */
	private get generated(): string {
		return this.relativeString( this.lightnessDelta, this.chromaScale, this.hueDelta, this.alpha );
	}

	/**
	 * Builds a gradient of relative-color stops varying one channel across its range while the other three hold their current values.
	 *
	 * The stops are literal relative-color strings the browser computes, so on an engine without the syntax the whole gradient fails to parse and the strip's neutral inline floor shows instead, the same two-declaration fallback the article teaches.
	 *
	 * @param colorAt - The relative-color string for a position, where the argument runs 0 to 1 across the slider's range.
	 * @returns The `linear-gradient` value for the strip.
	 */
	private trackFor( colorAt: ( t: number ) => string ): string {
		const stops: string[] = [];

		for ( let i = 0; i < 13; i += 1 ) {
			const t = i / 12;
			stops.push( `${colorAt( t )} ${( t * 100 ).toFixed( 1 )}%` );
		}

		return `linear-gradient(to right, ${stops.join( ', ' )})`;
	}

	/**
	 * The lightness strip's gradient, `calc(l + n)` swept across the slider's range at the other channels' current values.
	 */
	private get lightnessTrack(): string {
		return this.trackFor( ( t ) => this.relativeString( -0.4 + t * 0.74, this.chromaScale, this.hueDelta, this.alpha ) );
	}

	/**
	 * The chroma strip's gradient, `calc(c * k)` swept from gray at 0 out past the sRGB edge at 2.
	 */
	private get chromaTrack(): string {
		return this.trackFor( ( t ) => this.relativeString( this.lightnessDelta, t * 2, this.hueDelta, this.alpha ) );
	}

	/**
	 * The hue strip's gradient, `calc(h + deg)` swept a half turn each way around the wheel.
	 */
	private get hueTrack(): string {
		return this.trackFor( ( t ) => this.relativeString( this.lightnessDelta, this.chromaScale, -180 + t * 360, this.alpha ) );
	}

	/**
	 * The alpha strip's gradient layered over stripes, the slash channel swept 0 to 1 so the fade is visible against a pattern.
	 */
	private get alphaTrack(): string {
		const fade = this.trackFor( ( t ) => this.relativeString( this.lightnessDelta, this.chromaScale, this.hueDelta, t ) );

		return `${fade}, repeating-linear-gradient(45deg, var(--line-soft, #f2f1ec), var(--line-soft, #f2f1ec) 6px, var(--line, #e7e6e2) 6px, var(--line, #e7e6e2) 12px)`;
	}

	/**
	 * Whether the engine parses relative color syntax at all, probed with the valid base form.
	 *
	 * When this is false both dropped-panel cells fall to the literal source floor, so the verdict line states that plainly instead of implying the valid form painted while the percentage form was dropped.
	 */
	private get relativeFormSupported(): boolean {
		return CSS.supports( 'color', 'oklch(from red l c h)' );
	}

	/**
	 * Updates the lightness delta from its slider.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onLightness = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.lightnessDelta = Number( event.target.value );
		}
	};

	/**
	 * Updates the chroma multiplier from its slider.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onChroma = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.chromaScale = Number( event.target.value );
		}
	};

	/**
	 * Updates the hue delta from its slider.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onHue = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.hueDelta = Number( event.target.value );
		}
	};

	/**
	 * Updates the alpha from its slider.
	 *
	 * @param event - The input event from the range slider.
	 */
	private onAlpha = ( event: Event ): void => {
		if ( event.target instanceof HTMLInputElement ) {
			this.alpha = Number( event.target.value );
		}
	};

	/**
	 * Renders the four gradient strips, the source-becomes-result row, and the live dropped-percentage panel.
	 */
	render() {
		const generated = this.generated;
		const relativeSupported = this.relativeFormSupported;
		const validForm = this.signedCalc( 'l', this.lightnessDelta, 2 );
		const percentSign = this.lightnessDelta >= 0 ? '+' : '-';
		const percentForm = `calc(l ${percentSign} ${Math.round( Math.abs( this.lightnessDelta ) * 100 )}%)`;
		const poisoned = `oklch(from ${SOURCE} ${percentForm} calc(c * ${this.chromaScale.toFixed( 2 )}) ${this.signedCalc( 'h', this.hueDelta, 0 )} / ${this.alpha.toFixed( 2 )})`;
		const percentParses = CSS.supports( 'color', poisoned );

		return html`
			<div class="demo">
				<h3 class="demo-title">Adjust channels with unitless numbers</h3>
				<div class="sliders">
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="l-delta">Lightness delta</label>
							<span class="control-value">${this.lightnessDelta.toFixed( 2 )}</span>
						</div>
						<input
							id="l-delta"
							class="slider-strip"
							type="range"
							min="-0.4"
							max="0.34"
							step="0.01"
							.value=${String( this.lightnessDelta )}
							@input=${this.onLightness}
							style="background: var(--line, #e7e6e2); background: ${this.lightnessTrack};"
						/>
						<p class="slider-hint">Applied as ${validForm}, a unitless number on the 0 to 1 scale.</p>
					</div>
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="c-scale">Chroma multiplier</label>
							<span class="control-value">${this.chromaScale.toFixed( 2 )}</span>
						</div>
						<input
							id="c-scale"
							class="slider-strip"
							type="range"
							min="0"
							max="2"
							step="0.05"
							.value=${String( this.chromaScale )}
							@input=${this.onChroma}
							style="background: var(--line, #e7e6e2); background: ${this.chromaTrack};"
						/>
						<p class="slider-hint">Applied as calc(c * ${this.chromaScale.toFixed( 2 )}), where 0 collapses to gray.</p>
					</div>
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="h-delta">Hue rotation</label>
							<span class="control-value">${this.hueDelta}</span>
						</div>
						<input
							id="h-delta"
							class="slider-strip"
							type="range"
							min="-180"
							max="180"
							step="1"
							.value=${String( this.hueDelta )}
							@input=${this.onHue}
							style="background: var(--line, #e7e6e2); background: ${this.hueTrack};"
						/>
						<p class="slider-hint">Applied as ${this.signedCalc( 'h', this.hueDelta, 0 )}, the one channel measured in degrees.</p>
					</div>
					<div class="slider-row">
						<div class="slider-head">
							<label class="control-label" for="alpha">Alpha</label>
							<span class="control-value">${this.alpha.toFixed( 2 )}</span>
						</div>
						<input
							id="alpha"
							class="slider-strip"
							type="range"
							min="0"
							max="1"
							step="0.05"
							.value=${String( this.alpha )}
							@input=${this.onAlpha}
							style="background: var(--line, #e7e6e2); background: ${this.alphaTrack};"
						/>
						<p class="slider-hint">Applied after the slash; the strip and the result sit on stripes so translucency shows.</p>
					</div>
				</div>
				<div class="becomes">
					<span class="swatch" style="background: #488bfb; background: ${SOURCE};"></span>
					<span class="code-chip">${SOURCE}</span>
					<span>becomes</span>
					<span class="alpha-stage"><span class="swatch" style="background: #488bfb; background: ${generated};"></span></span>
				</div>
				<pre class="code-block">${generated}</pre>
				<p class="demo-note">
					Every channel keyword (<span class="code-chip">l</span>, <span class="code-chip">c</span>, <span class="code-chip">h</span>) resolves to a <strong>unitless number</strong>, with lightness on a 0 to 1 scale, so the math is <span class="code-chip">calc(l + 0.2)</span>, never <span class="code-chip">calc(l + 20%)</span>.
					The panel below proves it with your own numbers.
				</p>
				<div class="dropped">
					<div class="dropped-cell">
						<span class="dropped-label">Valid: <span class="code-chip">${validForm}</span></span>
						<div class="dropped-swatch" style="background: #488bfb; background: ${generated};"></div>
					</div>
					<div class="dropped-cell">
						<span class="dropped-label">Dropped: <span class="code-chip">${percentForm}</span></span>
						<div class="dropped-swatch" style="background: #488bfb; background: ${poisoned};"></div>
					</div>
				</div>
				${relativeSupported
					? html`
						<p class="verdict-line">
							<span class="report-verdict" data-pass=${percentParses ? 'false' : 'true'}>${percentParses ? 'parsed' : 'dropped'}</span>
							<span>
								Drag any slider and the valid cell follows the whole string, while the twin with <span class="code-chip">${percentForm}</span> in its lightness slot never paints, since a percentage cannot be added to the unitless <span class="code-chip">l</span> and one poisoned channel drops the entire declaration, leaving the source floor showing.
							</span>
						</p>
					`
					: html`
						<p class="verdict-line">
							<span class="report-verdict" data-pass="false">unsupported</span>
							<span>
								This browser has no relative color syntax at all, so both forms fail to parse and both cells fall to the source's sRGB floor; on a supporting engine only the percentage form is dropped.
							</span>
						</p>
					` }
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'demo-color-token-contract-color-tokens-relative-lab': RelativeLabDemo;
	}
}