@evolve.ui/theme-system 1.0.1 → 1.2.0

package/src/effects/hooks.ts

@@ -0,0 +1,493 @@
+/**
+ * Hook catalog: the only DOM the effect layer may bind to.
+ * Selector parts stay separate so the emitter can assemble them and so evidence can cover each token.
+ * `structural` records position a literal cannot prove (a child combinator or a last-child). Link 5
+ * must witness those hooks in a story play test.
+ */
+
+export type PseudoSlot = 'before' | 'after';
+
+/** States in which the host repaints its own background. `focus-within` can only be acknowledged. */
+export type StateBackground = 'hover' | 'active' | 'focus-within';
+
+export type SourceEvidence = {
+    readonly kind: 'source';
+    /** Path relative to `shared-configs/core-components/src`. */
+    readonly file: string;
+    readonly literal: string;
+    readonly exclusive?: true;
+};
+
+export type PackageName = 'react-select' | 'react-toastify' | 'react-tooltip';
+
+export type PackageEvidence = {
+    readonly kind: 'package';
+    readonly package: PackageName;
+    readonly literal: string;
+};
+
+export type HookEvidence = SourceEvidence | PackageEvidence;
+
+export type EffectHook = {
+    readonly component: string;
+    readonly host: string;
+    readonly is?: string;
+    readonly has?: string;
+    readonly lacks?: string;
+    readonly positioned: boolean;
+    readonly taken: readonly PseudoSlot[];
+    readonly stateBackgrounds: readonly StateBackground[];
+    readonly evidence: readonly [HookEvidence, ...HookEvidence[]];
+    readonly structural?: string;
+    /** Sibling states whose `is` clauses can never match the same element at once. */
+    readonly exclusiveWith?: readonly string[];
+};
+
+const src = (file: string, literal: string, exclusive?: true): SourceEvidence =>
+    exclusive === true ? { exclusive, file, kind: 'source', literal } : { file, kind: 'source', literal };
+
+const pkg = (packageName: PackageName, literal: string): PackageEvidence => ({
+    kind: 'package',
+    literal,
+    package: packageName,
+});
+
+const evidence = <T extends readonly [HookEvidence, ...HookEvidence[]]>(...items: T): T => items;
+
+const CHILD_OF_REGION = 'The button is a child of the region; a literal cannot prove the child combinator.';
+const OVERLAY_LAST_CHILD =
+    'The overlay div is the last child of the dropzone group; a literal cannot prove the child combinator or that last-child position.';
+
+const OVERLAY_TEXT_PATH =
+    'The message is a descendant of the overlay (last child of the dropzone group) through a child combinator; a literal cannot prove that path.';
+
+const listCardHost = 'div.group\\/list-file-card.rounded-container';
+const gridCardHost = '.group\\/grid-file-card';
+const dropzoneHost = '[role="region"] > [role="button"]';
+
+const listCardEvidence = [
+    src('FileUpload/components/ListFileCard/ListFileCard.tsx', '<div'),
+    src('FileUpload/components/ListFileCard/ListFileCard.tsx', "'group/list-file-card", true),
+    src('FileUpload/components/ListFileCard/ListFileCard.tsx', "'rounded-container border'"),
+] as const;
+
+const gridCardEvidence = [
+    src('FileUpload/components/GridFileCard/GridFileCard.tsx', "'group/grid-file-card", true),
+] as const;
+
+const progressCompleteEvidence = [
+    src('ProgressCircle/ProgressCircle.tsx', '<svg'),
+    src('ProgressCircle/ProgressCircle.tsx', 'role={ariaRole}'),
+    src('ProgressCircle/ProgressCircle.tsx', "'status'"),
+    src('ProgressCircle/ProgressCircle.tsx', 'aria-valuenow={ariaValueNow}'),
+    src('ProgressCircle/ProgressCircle.tsx', 'isComplete ? 100'),
+] as const;
+
+const checkboxEvidence = [
+    src('ChoiceListItem/Checkbox.tsx', 'type="checkbox"'),
+    src('ChoiceListItem/choiceListItem.tsx', '<input'),
+] as const;
+
+const regionEvidence = [
+    src('FileUpload/components/FileDropzone/FileDropzone.tsx', 'role="region"'),
+    src('FileUpload/components/FileDropzone/FileDropzone.tsx', "role: 'button'"),
+] as const;
+
+export const effectHooks = {
+    modal: {
+        component: 'Modal',
+        host: 'dialog[data-hui-id="Modal"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        evidence: evidence(
+            src('Modal/ComposableModal.tsx', '<dialog'),
+            src('Modal/ComposableModal.tsx', 'data-hui-id="Modal"')
+        ),
+    },
+    'modal.backdrop': {
+        component: 'Modal',
+        host: '.hui-modal-backdrop',
+        is: '.fixed',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        evidence: evidence(
+            src('Modal/components/Backdrop/Backdrop.tsx', 'hui-modal-backdrop opacity-0'),
+            src(
+                'Modal/components/Backdrop/Backdrop.tsx',
+                'fixed bottom-0 left-0 right-0 top-0 z-[1001] flex items-center justify-center bg-background-overlay'
+            )
+        ),
+    },
+    drawer: {
+        component: 'Drawer',
+        host: '[data-hui-id="Drawer"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        evidence: evidence(src('Drawer/Drawer.tsx', 'data-hui-id="Drawer"', true)),
+    },
+    bottomSheet: {
+        component: 'BottomSheet',
+        host: '[role="dialog"][aria-modal="true"]',
+        is: '.rounded-t-xl',
+        positioned: true,
+        taken: ['before'],
+        stateBackgrounds: [],
+        evidence: evidence(
+            src(
+                'BottomSheet/components/BottomSheetOverlay/BottomSheetOverlayTranslate3d.tsx',
+                'aria-modal="true"',
+                true
+            ),
+            src('BottomSheet/components/BottomSheetOverlay/BottomSheetOverlayTranslate3d.tsx', 'role="dialog"'),
+            src('BottomSheet/components/BottomSheetOverlay/BottomSheetOverlayTranslate3d.tsx', 'rounded-t-xl')
+        ),
+    },
+    menu: {
+        component: 'Menu',
+        host: '.Menu[role="menu"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        evidence: evidence(src('Menu/Menu.tsx', "'Menu relative", true), src('Menu/Menu.tsx', "role: 'menu'")),
+    },
+    'select.menu': {
+        component: 'Select',
+        host: 'div',
+        has: '> [role="listbox"][id^="react-select-"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        structural: 'The listbox is a child of the menu div; a literal cannot prove the child combinator.',
+        evidence: evidence(
+            src('Select/Select.tsx', 'instanceId={defaultInstanceId}'),
+            pkg('react-select', "role: 'listbox'"),
+            pkg('react-select', "id: _this4.getElementId('listbox')"),
+            pkg('react-select', "'react-select-'"),
+            pkg('react-select', 'createElement("div"')
+        ),
+    },
+    tooltip: {
+        exclusiveWith: ['tooltip.inverse'],
+        component: 'Tooltip',
+        host: '[role="tooltip"].hui-text-body-secondary',
+        is: ':not(.\\!bg-background-inverse)',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        evidence: evidence(
+            src('Tooltip/Tooltip.tsx', 'hui-text-body-secondary !bg-background-primary !shadow-03'),
+            src('Tooltip/Tooltip.tsx', "'!bg-background-inverse': isInverse"),
+            pkg('react-tooltip', "role = 'tooltip'")
+        ),
+    },
+    'tooltip.inverse': {
+        exclusiveWith: ['tooltip'],
+        component: 'Tooltip',
+        host: '[role="tooltip"].hui-text-body-secondary',
+        is: '.\\!bg-background-inverse',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        evidence: evidence(
+            src('Tooltip/Tooltip.tsx', 'hui-text-body-secondary !bg-background-primary !shadow-03'),
+            src('Tooltip/Tooltip.tsx', "'!bg-background-inverse': isInverse"),
+            pkg('react-tooltip', "role = 'tooltip'")
+        ),
+    },
+    'datePicker.popover': {
+        // Binds through data-testid, which is not a styling contract.
+        component: 'DatePicker',
+        host: '[data-testid="date-picker-popover"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        evidence: evidence(src('DateTimeInput/datePicker/DatePicker.tsx', 'data-testid="date-picker-popover"', true)),
+    },
+    'timePicker.popover': {
+        // Binds through data-testid, which is not a styling contract.
+        component: 'TimePicker',
+        host: '[data-testid="time-picker-popover"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        evidence: evidence(src('DateTimeInput/timePicker/TimePicker.tsx', 'data-testid="time-picker-popover"', true)),
+    },
+    toast: {
+        component: 'ToastContainer',
+        host: '.Toastify__toast-container > *',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        structural:
+            'The toast node is a child of the container. toastClassName is a function, so the toast class is dropped; a literal cannot prove the child combinator.',
+        evidence: evidence(
+            src('Toast/components/ToastContainer/ToastContainer.tsx', 'toastClassName={(context) =>', true),
+            pkg('react-toastify', 'Toastify__toast-container')
+        ),
+    },
+
+    dropzone: {
+        component: 'FileDropzone',
+        host: `${dropzoneHost}[aria-disabled]`,
+        positioned: true,
+        taken: [],
+        stateBackgrounds: ['hover', 'active'],
+        structural: CHILD_OF_REGION,
+        evidence: evidence(
+            ...regionEvidence,
+            src('FileUpload/components/FileDropzone/FileDropzone.tsx', "'aria-disabled': isDisabled")
+        ),
+    },
+    'dropzone.disabled': {
+        component: 'FileDropzone',
+        host: dropzoneHost,
+        is: '[aria-disabled="true"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        structural: CHILD_OF_REGION,
+        evidence: evidence(
+            ...regionEvidence,
+            src('FileUpload/components/FileDropzone/FileDropzone.tsx', "'aria-disabled': isDisabled")
+        ),
+    },
+    'dropzone.dragging': {
+        component: 'FileDropzone',
+        host: dropzoneHost,
+        is: '.outline-4',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        structural: CHILD_OF_REGION,
+        evidence: evidence(
+            ...regionEvidence,
+            src('FileUpload/utils/styles.ts', 'outline outline-4 outline-offset-0 outline-focus-primary')
+        ),
+    },
+    'dropzone.error': {
+        component: 'FileDropzone',
+        host: dropzoneHost,
+        is: '.bg-background-critical-light',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: ['hover', 'active'],
+        structural: CHILD_OF_REGION,
+        evidence: evidence(
+            ...regionEvidence,
+            src(
+                'FileUpload/utils/styles.ts',
+                'bg-background-critical-light outline-dashed outline-1 -outline-offset-1 outline-border-critical'
+            )
+        ),
+    },
+    'dropzoneOverlay.accept': {
+        exclusiveWith: ['dropzoneOverlay.reject'],
+        component: 'FileDropzoneOverlay',
+        host: '.group\\/dropzone > div:last-child',
+        is: '.outline-4:not(.outline-border-critical)',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        structural: OVERLAY_LAST_CHILD,
+        evidence: evidence(
+            src('FileUpload/components/FileDropzoneOverlay/FileDropzoneOverlay.tsx', "'group/dropzone'", true),
+            src('FileUpload/components/FileDropzoneOverlay/FileDropzoneOverlay.tsx', '<div'),
+            src(
+                'FileUpload/components/FileDropzoneOverlay/styles.ts',
+                'outline outline-4 outline-offset-0 outline-focus-primary'
+            ),
+            src(
+                'FileUpload/components/FileDropzoneOverlay/styles.ts',
+                'bg-background-critical-light/50 outline-border-critical'
+            )
+        ),
+    },
+    'dropzoneOverlay.reject': {
+        exclusiveWith: ['dropzoneOverlay.accept'],
+        component: 'FileDropzoneOverlay',
+        host: '.group\\/dropzone > div:last-child',
+        is: '.outline-4.outline-border-critical',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: [],
+        structural: OVERLAY_LAST_CHILD,
+        evidence: evidence(
+            src('FileUpload/components/FileDropzoneOverlay/FileDropzoneOverlay.tsx', "'group/dropzone'", true),
+            src('FileUpload/components/FileDropzoneOverlay/FileDropzoneOverlay.tsx', '<div'),
+            src(
+                'FileUpload/components/FileDropzoneOverlay/styles.ts',
+                'outline outline-4 outline-offset-0 outline-focus-primary'
+            ),
+            src(
+                'FileUpload/components/FileDropzoneOverlay/styles.ts',
+                'bg-background-critical-light/50 outline-border-critical'
+            )
+        ),
+    },
+    'overlayDragText.valid': {
+        // The message div of a valid drag. The invalid message uses text-text-critical and needs no hook.
+        component: 'FileDropzoneOverlay',
+        host: '.group\\/dropzone > div:last-child .text-center > .text-xl.font-medium',
+        is: '.text-blue-600',
+        positioned: false,
+        taken: [],
+        stateBackgrounds: [],
+        structural: OVERLAY_TEXT_PATH,
+        evidence: evidence(
+            src('FileUpload/components/FileDropzoneOverlay/FileDropzoneOverlay.tsx', "'group/dropzone'", true),
+            src('FileUpload/components/FileDropzoneOverlay/FileDropzoneOverlay.tsx', '<div'),
+            src(
+                'FileUpload/components/FileDropzoneOverlay/components/OverlayDropzoneContent.tsx',
+                'className="text-center"'
+            ),
+            src(
+                'FileUpload/components/FileDropzoneOverlay/components/OverlayDropzoneDragText.tsx',
+                "'text-xl font-medium'"
+            ),
+            src(
+                'FileUpload/components/FileDropzoneOverlay/components/OverlayDropzoneDragText.tsx',
+                "validation.dragValidationError ? 'text-text-critical' : 'text-blue-600'"
+            )
+        ),
+    },
+
+    listFileCard: {
+        component: 'ListFileCard',
+        host: listCardHost,
+        positioned: false,
+        taken: [],
+        stateBackgrounds: ['hover'],
+        evidence: evidence(...listCardEvidence),
+    },
+    'listFileCard.uploading': {
+        component: 'ListFileCard',
+        host: listCardHost,
+        is: '[aria-busy="true"]',
+        positioned: false,
+        taken: [],
+        stateBackgrounds: ['hover'],
+        evidence: evidence(
+            ...listCardEvidence,
+            src('FileUpload/components/ListFileCard/ListFileCard.tsx', 'aria-busy={isProcessing || undefined}')
+        ),
+    },
+    'listFileCard.selected': {
+        component: 'ListFileCard',
+        host: listCardHost,
+        has: 'input[type="checkbox"]:checked',
+        positioned: false,
+        taken: [],
+        stateBackgrounds: ['hover'],
+        evidence: evidence(...listCardEvidence, ...checkboxEvidence),
+    },
+    'listFileCard.error': {
+        component: 'ListFileCard',
+        host: listCardHost,
+        is: '.bg-background-critical-light',
+        positioned: false,
+        taken: [],
+        stateBackgrounds: ['hover'],
+        evidence: evidence(
+            ...listCardEvidence,
+            src(
+                'FileUpload/components/ListFileCard/ListFileCard.tsx',
+                "'bg-background-critical-light': isError && !isDragging"
+            )
+        ),
+    },
+    'listFileCard.complete': {
+        // A card showing a status icon instead of the progress circle is not matched.
+        component: 'ListFileCard',
+        host: listCardHost,
+        has: 'svg[role="status"][aria-valuenow="100"]',
+        positioned: false,
+        taken: [],
+        stateBackgrounds: ['hover'],
+        evidence: evidence(...listCardEvidence, ...progressCompleteEvidence),
+    },
+
+    gridFileCard: {
+        component: 'GridFileCard',
+        host: gridCardHost,
+        positioned: true,
+        taken: [],
+        stateBackgrounds: ['hover', 'focus-within'],
+        evidence: evidence(...gridCardEvidence),
+    },
+    'gridFileCard.uploading': {
+        component: 'GridFileCard',
+        host: gridCardHost,
+        is: '[aria-busy="true"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: ['hover', 'focus-within'],
+        evidence: evidence(
+            ...gridCardEvidence,
+            src('FileUpload/components/GridFileCard/GridFileCard.tsx', 'aria-busy={isProcessing || undefined}')
+        ),
+    },
+    'gridFileCard.selected': {
+        component: 'GridFileCard',
+        host: gridCardHost,
+        has: 'input[type="checkbox"]:checked',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: ['hover', 'focus-within'],
+        evidence: evidence(...gridCardEvidence, ...checkboxEvidence),
+    },
+    'gridFileCard.error': {
+        component: 'GridFileCard',
+        host: gridCardHost,
+        is: '.ring-border-critical',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: ['hover', 'focus-within'],
+        evidence: evidence(
+            ...gridCardEvidence,
+            src('FileUpload/components/GridFileCard/GridFileCard.tsx', 'ring-border-critical')
+        ),
+    },
+    'gridFileCard.complete': {
+        // A card showing a status icon instead of the progress circle is not matched.
+        component: 'GridFileCard',
+        host: gridCardHost,
+        has: 'svg[role="status"][aria-valuenow="100"]',
+        positioned: true,
+        taken: [],
+        stateBackgrounds: ['hover', 'focus-within'],
+        evidence: evidence(...gridCardEvidence, ...progressCompleteEvidence),
+    },
+} as const satisfies Record<string, EffectHook>;
+
+export type EffectHookId = keyof typeof effectHooks;
+
+const hookRecord = (id: EffectHookId): EffectHook => effectHooks[id];
+
+/** `host + is + :has(has) + :not(:has(lacks))`, unscoped. */
+export const hookSelector = (id: EffectHookId): string => {
+    const hook = hookRecord(id);
+    const is = hook.is ?? '';
+    const has = hook.has !== undefined ? `:has(${hook.has})` : '';
+    const lacks = hook.lacks !== undefined ? `:not(:has(${hook.lacks}))` : '';
+    return `${hook.host}${is}${has}${lacks}`;
+};
+
+/** `'listFileCard.selected'` -> `'listFileCard'`. An id with no dot is returned unchanged. */
+export const rootOf = (id: EffectHookId): string => {
+    const dot = id.indexOf('.');
+    return dot === -1 ? id : id.slice(0, dot);
+};
+
+/** First pseudo slot the component does not paint itself. */
+export const freePseudoSlot = (taken: readonly PseudoSlot[]): PseudoSlot | undefined => {
+    if (!taken.includes('before')) {
+        return 'before';
+    }
+    if (!taken.includes('after')) {
+        return 'after';
+    }
+    return undefined;
+};

package/src/effects/index.ts

@@ -0,0 +1,2 @@
+export { effectClasses } from './classes';
+export type { EffectClass } from './classes';

package/src/effects/layers.ts

@@ -0,0 +1,18 @@
+/**
+ * Which brands have an effect layer. EverydayHarbor is the first.
+ * Locked brands are `?: never`, so they cannot be registered without leaving `LOCKED_BRANDS`.
+ */
+import type { Brands } from '../themes/brands';
+import type { LOCKED_BRANDS } from '../themes/themeValues';
+import type { EffectLayer } from './rules';
+
+import { everydayHarborEffects } from './brands/EverydayHarbor';
+
+export type LockedBrand = (typeof LOCKED_BRANDS)[number];
+export type EffectBrand = Exclude<Brands, LockedBrand>;
+
+export type EffectLayerRegistry = { readonly [B in EffectBrand]?: EffectLayer } & {
+    readonly [B in LockedBrand]?: never;
+};
+
+export const effectLayers = { EverydayHarbor: everydayHarborEffects } as const satisfies EffectLayerRegistry;

package/src/effects/rules.ts

@@ -0,0 +1,90 @@
+/**
+ * Effect rules are data. Authors name a hook or an opt-in class and the values to apply.
+ * The emitter chooses the selector, the layer, and which declarations are enforced.
+ *
+ * Enforced (layered `!important`): material, shadow, paint, and every pseudo-element declaration.
+ * Default (layered, normal): `vars`, radius, and the emitter's `position: relative`.
+ * `PaintProperty`, `When`, and `vars` leave focus, outlines, borders, and type metrics to their own conventions.
+ * `vars` is limited to text and icon colour channels plus `--effect-font-accent`. Focus, outline, and border colours are not remappable.
+ * A `vars` remap inherits into the hook's whole subtree, including any text field inside a modal, drawer, sheet, or menu.
+ * `shadow` is a shadow token name. The emitter prepends the Tailwind ring variables.
+ */
+import type { CSSVariables } from '../themes/generateCSSVars';
+import type { EffectClass } from './classes';
+import type { EffectHookId, StateBackground } from './hooks';
+import type { EffectTokenRef, EffectTokenValues, TokensOfKind } from './tokens';
+
+export type EffectMaterial = 'surface' | 'raised' | 'scrim';
+
+/** Token names each material expands to. `edge: true` adds the masked 1px edge. */
+export const materials = {
+    surface: { fill: 'surface-fill', filter: 'surface-filter', shadow: 'surface-shadow', edge: true },
+    raised: { fill: 'raised-fill', filter: 'raised-filter', shadow: 'raised-shadow', edge: true },
+    scrim: { fill: 'scrim-fill', filter: 'scrim-filter', shadow: null, edge: false },
+} as const satisfies Record<
+    EffectMaterial,
+    {
+        fill: TokensOfKind<'paint'>;
+        filter: TokensOfKind<'filter'>;
+        shadow: TokensOfKind<'shadow'> | null;
+        edge: boolean;
+    }
+>;
+
+export type PaintProperty =
+    | 'background'
+    | 'backgroundColor'
+    | 'backgroundImage'
+    | 'backdropFilter'
+    | 'color'
+    | 'fontFamily';
+
+export type When = 'hover' | 'active';
+
+type PaintFor<P extends PaintProperty> = P extends 'fontFamily'
+    ? EffectTokenRef<TokensOfKind<'font'>>
+    : P extends 'backdropFilter'
+      ? EffectTokenRef<TokensOfKind<'filter'>>
+      : EffectTokenRef<TokensOfKind<'paint'>>;
+
+export type Decoration = {
+    readonly inset?: `${number}px`;
+    readonly borderRadius?: `${number}px` | 'inherit';
+    readonly borderWidth?: `${number}px`;
+    readonly borderStyle?: 'dashed' | 'dotted' | 'solid';
+    readonly borderColor?: EffectTokenRef<TokensOfKind<'paint'>>;
+    readonly background?: EffectTokenRef<TokensOfKind<'paint'>>;
+    readonly boxShadow?: EffectTokenRef<TokensOfKind<'shadow'>>;
+};
+
+export type EffectVars = {
+    readonly [K in
+        | Extract<CSSVariables, `--color-text-${string}` | `--color-icon-${string}`>
+        | '--effect-font-accent']?: K extends '--effect-font-accent'
+        ? EffectTokenRef<TokensOfKind<'font'>>
+        : EffectTokenRef<TokensOfKind<'channels'>>;
+};
+
+export type EffectRule = {
+    readonly on: EffectHookId | EffectClass;
+    readonly when?: When;
+    readonly unless?: string;
+    readonly material?: EffectMaterial;
+    readonly shadow?: TokensOfKind<'shadow'>;
+    readonly paint?: { readonly [P in PaintProperty]?: PaintFor<P> };
+    readonly vars?: EffectVars;
+    readonly radius?: TokensOfKind<'length'>;
+    readonly before?: Decoration;
+    readonly after?: Decoration;
+    readonly acknowledge?: readonly StateBackground[];
+};
+
+/** Brand layers bind catalog hooks. Opt-in classes belong to the vocabulary. */
+export type BrandEffectRule = Omit<EffectRule, 'on'> & {
+    readonly on: EffectHookId;
+};
+
+export type EffectLayer = {
+    readonly tokens: EffectTokenValues;
+    readonly rules: readonly BrandEffectRule[];
+};

package/src/effects/rules.typecheck.ts

@@ -0,0 +1,50 @@
+/**
+ * Compile-time guard rails. `ts-check` covers this file; it is not a published entry.
+ * Each `@ts-expect-error` is one line so the error stays on that line.
+ */
+import type { EffectLayerRegistry } from './layers';
+import type { BrandEffectRule, EffectRule } from './rules';
+
+import { fx, type EffectTokenValues } from './tokens';
+
+declare const readyTokens: EffectTokenValues;
+
+// @ts-expect-error a brand must provide every token that has no registry default
+export const incompleteTokens: EffectTokenValues = { 'solid-fill': '#000' };
+
+// @ts-expect-error rules carry token refs, never literal colours
+export const literalColour: EffectRule = { on: 'modal', paint: { background: '#E3B341' } };
+
+// @ts-expect-error outline is outside PaintProperty
+export const outlinePaint: EffectRule = { on: 'modal', paint: { outlineColor: fx.dash } };
+
+// @ts-expect-error focus states are not a `when`
+export const focusState: EffectRule = { on: 'modal', when: 'focus-visible' };
+
+// @ts-expect-error only catalogued hooks and vocabulary classes are targets
+export const uncatalogued: EffectRule = { on: 'textInput', material: 'surface' };
+
+// @ts-expect-error shadow takes a shadow-kind token name
+export const wrongKind: EffectRule = { on: 'modal', shadow: 'surface-fill' };
+
+// @ts-expect-error channel remaps take channels tokens
+export const paintIntoChannels: EffectRule = { on: 'modal', vars: { '--color-text-inverse': fx.ctaFill } };
+
+// @ts-expect-error --effect-font-accent takes a font token
+export const fontAccentChannels: EffectRule = { on: 'modal', vars: { '--effect-font-accent': fx.ctaInkRgb } };
+
+// @ts-expect-error focus colours are not remappable
+export const focusColourVar: EffectRule = { on: 'modal', vars: { '--color-focus-primary': fx.ctaInkRgb } };
+
+// @ts-expect-error border colours are not remappable
+export const borderColourVar: EffectRule = { on: 'modal', vars: { '--color-border-primary': fx.ctaInkRgb } };
+
+// @ts-expect-error locked brands cannot register an effect layer
+export const lockedBrand: EffectLayerRegistry = { Default: { rules: [], tokens: readyTokens } };
+
+// @ts-expect-error brand rules bind hooks, not opt-in classes
+export const classTarget: BrandEffectRule = { on: 'hui-fx-glass', material: 'surface' };
+
+export const selectedAccent: EffectRule = { on: 'listFileCard.selected', shadow: 'selected' };
+export const surfaceFillRef: 'var(--effect-surface-fill)' = fx.surfaceFill;
+export const serifSwitch: EffectRule = { on: 'modal', vars: { '--effect-font-accent': fx.fontSerif } };