@ccslabs/xtend 0.1.0-rc.1

package/a11y/motion-contrast-policy.js

@@ -0,0 +1,261 @@
+(function attachXtendA11yMotionContrastPolicy(globalTarget, factory) {
+  const api = factory();
+
+  if (typeof module === 'object' && module.exports) {
+    module.exports = api;
+  }
+
+  if (globalTarget && typeof globalTarget === 'object') {
+    globalTarget.XTendA11yMotionContrastPolicy = Object.freeze({
+      schema: api.MOTION_CONTRAST_POLICY_SCHEMA,
+      contracts: api.CONTRACTS,
+      createMotionContrastPolicy: api.createMotionContrastPolicy,
+      normalizeMotionContrastPolicy: api.normalizeMotionContrastPolicy,
+      validateMotionContrastPolicy: api.validateMotionContrastPolicy
+    });
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : this, function createXtendA11yMotionContrastPolicyModule() {
+  const CONTRACTS = Object.freeze({
+    motionContrast: 'xtend.a11y.motion-contrast-policy.v1',
+    motion: 'xtend.a11y.motion-policy.v1',
+    contrast: 'xtend.a11y.contrast-policy.v1',
+    test: 'xtend.a11y.motion-contrast-test.v1',
+    fabricLaneMapping: 'xtend.fabric.rmt-lane-mapping.v1'
+  });
+
+  const MOTION_CONTRAST_POLICY_SCHEMA = CONTRACTS.motionContrast;
+  const MOTION_POLICY_SCHEMA = CONTRACTS.motion;
+  const CONTRAST_POLICY_SCHEMA = CONTRACTS.contrast;
+  const MOTION_CONTRAST_TEST_SCHEMA = CONTRACTS.test;
+
+  const MOTION_MEDIA_QUERY = '(prefers-reduced-motion: reduce)';
+  const CONTRAST_MEDIA_QUERY = '(forced-colors: active)';
+
+  const PROFILE_POLICY_DEFAULTS = Object.freeze({
+    display: Object.freeze({
+      animationPolicy: 'none-or-instant-state',
+      contrastPolicy: 'semantic-surface-and-focus'
+    }),
+    interactive: Object.freeze({
+      animationPolicy: 'no-essential-motion',
+      contrastPolicy: 'focus-visible-and-state-without-color'
+    }),
+    stateful: Object.freeze({
+      animationPolicy: 'state-change-without-motion-only-feedback',
+      contrastPolicy: 'non-color-state-and-focus'
+    }),
+    feedback: Object.freeze({
+      animationPolicy: 'announcement-without-motion-dependency',
+      contrastPolicy: 'status-not-color-only'
+    }),
+    overlay: Object.freeze({
+      animationPolicy: 'instant-open-close-allowed',
+      contrastPolicy: 'dialog-boundary-and-focus'
+    }),
+    routing: Object.freeze({
+      animationPolicy: 'route-change-without-motion-dependency',
+      contrastPolicy: 'active-route-not-color-only'
+    }),
+    theme: Object.freeze({
+      animationPolicy: 'token-change-without-motion-dependency',
+      contrastPolicy: 'theme-tokens-map-to-system-colors'
+    }),
+    form: Object.freeze({
+      animationPolicy: 'validation-without-motion-only-feedback',
+      contrastPolicy: 'error-and-required-not-color-only'
+    }),
+    media: Object.freeze({
+      animationPolicy: 'controls-stay-readable-without-motion',
+      contrastPolicy: 'controls-and-progress-not-color-only'
+    })
+  });
+
+  const SYSTEM_COLOR_TOKENS = Object.freeze({
+    text: 'CanvasText',
+    surface: 'Canvas',
+    border: 'CanvasText',
+    focus: 'Highlight',
+    focusText: 'HighlightText',
+    status: 'CanvasText',
+    error: 'Mark',
+    errorText: 'MarkText'
+  });
+
+  const FABRIC_A11Y_PREFERENCE = Object.freeze({
+    lane: 'a11y',
+    fiberKind: 'a11y.preference',
+    scheduleRef: 'a11y.user-blocking.preference',
+    scheduleContract: CONTRACTS.fabricLaneMapping,
+    boundary: 'fabric-adapter-observes-preferences-rmt-kernel-remains-framework-agnostic'
+  });
+
+  function normalizeProfile(profile) {
+    const normalized = String(profile || 'display').trim().toLowerCase();
+    return Object.prototype.hasOwnProperty.call(PROFILE_POLICY_DEFAULTS, normalized)
+      ? normalized
+      : 'display';
+  }
+
+  function unique(values) {
+    return Array.from(new Set((values || []).filter(Boolean)));
+  }
+
+  function createMotionPolicy(input = {}) {
+    const profile = normalizeProfile(input.primaryProfile || input.profile);
+    const defaults = PROFILE_POLICY_DEFAULTS[profile] || PROFILE_POLICY_DEFAULTS.display;
+    const motion = input.motion || {};
+
+    return {
+      schema: MOTION_POLICY_SCHEMA,
+      reducedMotion: motion.reducedMotion || 'required',
+      mediaQuery: motion.mediaQuery || MOTION_MEDIA_QUERY,
+      animationPolicy: motion.animationPolicy || defaults.animationPolicy,
+      disableAnimations: motion.disableAnimations !== false,
+      disableTransitions: motion.disableTransitions !== false,
+      noMotionOnlyState: motion.noMotionOnlyState !== false,
+      allowedAnimatedProperties: unique(motion.allowedAnimatedProperties || ['opacity', 'transform']),
+      requiredCss: unique(motion.requiredCss || [
+        '@media (prefers-reduced-motion: reduce)',
+        'animation: none',
+        'transition: none'
+      ])
+    };
+  }
+
+  function createContrastPolicy(input = {}) {
+    const profile = normalizeProfile(input.primaryProfile || input.profile);
+    const defaults = PROFILE_POLICY_DEFAULTS[profile] || PROFILE_POLICY_DEFAULTS.display;
+    const contrast = input.contrast || {};
+
+    return {
+      schema: CONTRAST_POLICY_SCHEMA,
+      highContrast: contrast.highContrast || 'required',
+      mediaQuery: contrast.mediaQuery || CONTRAST_MEDIA_QUERY,
+      contrastPolicy: contrast.contrastPolicy || defaults.contrastPolicy,
+      forcedColorAdjust: contrast.forcedColorAdjust || 'auto',
+      focusVisible: contrast.focusVisible || 'required',
+      nonColorStatus: contrast.nonColorStatus || 'required',
+      tokenAware: contrast.tokenAware !== false,
+      systemColorTokens: Object.assign({}, SYSTEM_COLOR_TOKENS, contrast.systemColorTokens || {}),
+      requiredCss: unique(contrast.requiredCss || [
+        '@media (forced-colors: active)',
+        'forced-color-adjust',
+        'CanvasText',
+        'Highlight'
+      ])
+    };
+  }
+
+  function resolveComponentRef(input = {}) {
+    return input.componentRef || input.tag || (input.profile && input.profile.componentRef) || 'x-component';
+  }
+
+  function createMotionContrastPolicy(input = {}) {
+    const primaryProfile = normalizeProfile(input.primaryProfile || (input.profile && input.profile.primaryProfile));
+    const motion = createMotionPolicy({
+      primaryProfile,
+      motion: input.motion || (input.profile && input.profile.motion)
+    });
+    const contrast = createContrastPolicy({
+      primaryProfile,
+      contrast: input.contrast || (input.profile && input.profile.contrast)
+    });
+
+    return {
+      schema: MOTION_CONTRAST_POLICY_SCHEMA,
+      componentRef: resolveComponentRef(input),
+      primaryProfile,
+      motion,
+      contrast,
+      fabric: Object.assign({}, FABRIC_A11Y_PREFERENCE),
+      testPlan: {
+        schema: MOTION_CONTRAST_TEST_SCHEMA,
+        requiredAssertions: [
+          'prefers-reduced-motion-css',
+          'forced-colors-css',
+          'focus-visible-preserved',
+          'non-color-status',
+          'theme-token-system-colors'
+        ]
+      },
+      requiredCss: unique(motion.requiredCss.concat(contrast.requiredCss)),
+      testRefs: ['motion-contrast', 'a11y-hydration', 'references'],
+      boundaries: {
+        runtimeAgnostic: true,
+        noRmtKernelImport: true,
+        noMotionOnlyState: motion.noMotionOnlyState === true
+      }
+    };
+  }
+
+  function normalizeMotionContrastPolicy(input = {}) {
+    if (input && input.schema === MOTION_CONTRAST_POLICY_SCHEMA) {
+      return Object.assign(createMotionContrastPolicy(input), input, {
+        motion: Object.assign(createMotionPolicy(input), input.motion || {}),
+        contrast: Object.assign(createContrastPolicy(input), input.contrast || {})
+      });
+    }
+
+    return createMotionContrastPolicy(input);
+  }
+
+  function validateMotionContrastPolicy(input = {}) {
+    const policy = normalizeMotionContrastPolicy(input);
+    const errors = [];
+
+    if (policy.schema !== MOTION_CONTRAST_POLICY_SCHEMA) {
+      errors.push('schema must be xtend.a11y.motion-contrast-policy.v1');
+    }
+    if (!policy.componentRef || typeof policy.componentRef !== 'string') {
+      errors.push('componentRef must be a non-empty string');
+    }
+    if (!policy.motion || policy.motion.schema !== MOTION_POLICY_SCHEMA) {
+      errors.push('motion schema must be xtend.a11y.motion-policy.v1');
+    }
+    if (!policy.contrast || policy.contrast.schema !== CONTRAST_POLICY_SCHEMA) {
+      errors.push('contrast schema must be xtend.a11y.contrast-policy.v1');
+    }
+    if (policy.motion && policy.motion.mediaQuery !== MOTION_MEDIA_QUERY) {
+      errors.push('motion mediaQuery must be prefers-reduced-motion reduce');
+    }
+    if (policy.contrast && policy.contrast.mediaQuery !== CONTRAST_MEDIA_QUERY) {
+      errors.push('contrast mediaQuery must be forced-colors active');
+    }
+    if (policy.motion && policy.motion.noMotionOnlyState !== true) {
+      errors.push('motion noMotionOnlyState must be true');
+    }
+    if (policy.contrast && policy.contrast.focusVisible !== 'required') {
+      errors.push('contrast focusVisible must be required');
+    }
+    if (policy.contrast && policy.contrast.nonColorStatus !== 'required') {
+      errors.push('contrast nonColorStatus must be required');
+    }
+    if (!policy.fabric || policy.fabric.lane !== 'a11y' || policy.fabric.fiberKind !== 'a11y.preference') {
+      errors.push('fabric mapping must use a11y lane and a11y.preference fiber');
+    }
+
+    return {
+      ok: errors.length === 0,
+      schema: MOTION_CONTRAST_TEST_SCHEMA,
+      contract: MOTION_CONTRAST_POLICY_SCHEMA,
+      errors,
+      policy
+    };
+  }
+
+  return Object.freeze({
+    CONTRACTS,
+    MOTION_CONTRAST_POLICY_SCHEMA,
+    MOTION_POLICY_SCHEMA,
+    CONTRAST_POLICY_SCHEMA,
+    MOTION_CONTRAST_TEST_SCHEMA,
+    MOTION_MEDIA_QUERY,
+    CONTRAST_MEDIA_QUERY,
+    PROFILE_POLICY_DEFAULTS,
+    SYSTEM_COLOR_TOKENS,
+    FABRIC_A11Y_PREFERENCE,
+    createMotionContrastPolicy,
+    normalizeMotionContrastPolicy,
+    validateMotionContrastPolicy
+  });
+});

package/a11y/runtime-a11y-contract.d.ts

@@ -0,0 +1,44 @@
+export * from '../fabric/xtend-policy-public-types';
+import type {
+  XtendPolicyConstant,
+  XtendPolicyOptions,
+  XtendPolicyReport
+} from '../fabric/xtend-policy-public-types';
+
+export interface XtendRuntimeA11yContract {
+  schema: string;
+  componentRef: string;
+  domains: Record<string, unknown>;
+  screenreader: Record<string, unknown>;
+  motion: Record<string, unknown>;
+  contrast: Record<string, unknown>;
+  states: Record<string, unknown>;
+  keyboard: Record<string, unknown>;
+  focus: Record<string, unknown>;
+  fabric: Record<string, unknown>;
+  rmt: Record<string, unknown>;
+  compatibility: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export declare const RUNTIME_A11Y_CONTRACT_SCHEMA: XtendPolicyConstant<string>;
+export declare const RUNTIME_A11Y_REPORT_SCHEMA: XtendPolicyConstant<string>;
+export declare const RUNTIME_A11Y_WORKPACKAGE: XtendPolicyConstant<string>;
+export declare const RUNTIME_A11Y_CONTRACT_DOC: XtendPolicyConstant<string>;
+export declare const COMPONENT_SHELL_CONTRACT_SCHEMA: XtendPolicyConstant<string>;
+export declare const COMPONENT_STYLING_CONTRACT_SCHEMA: XtendPolicyConstant<string>;
+export declare const A11Y_COMPONENT_CONTRACT_SCHEMA: XtendPolicyConstant<string>;
+export declare const SCREENREADER_SIGNALS_SCHEMA: XtendPolicyConstant<string>;
+export declare const MOTION_CONTRAST_POLICY_SCHEMA: XtendPolicyConstant<string>;
+export declare const RMT_A11Y_AUTHORING_SCHEMA: XtendPolicyConstant<string>;
+export declare const FABRIC_BOUNDARY_SCHEMA: XtendPolicyConstant<string>;
+export declare const KERNEL_BOUNDARY: XtendPolicyConstant<string>;
+export declare const RUNTIME_A11Y_REQUIRED_DOMAINS: XtendPolicyConstant<string[]>;
+export declare const RUNTIME_A11Y_PROFILES: XtendPolicyConstant<string[]>;
+export declare const RUNTIME_A11Y_REQUIRED_ASSERTIONS: XtendPolicyConstant<string[]>;
+export declare const RUNTIME_A11Y_REQUIRED_STATES: XtendPolicyConstant<string[]>;
+export declare const RUNTIME_A11Y_KEYBOARD_KEYS: XtendPolicyConstant<string[]>;
+export declare const RUNTIME_A11Y_FOCUS_BEHAVIORS: XtendPolicyConstant<string[]>;
+export declare const RUNTIME_A11Y_LIVE_REGION_MODES: XtendPolicyConstant<string[]>;
+export declare function createRuntimeA11yContract(options?: XtendPolicyOptions): XtendRuntimeA11yContract;
+export declare function validateRuntimeA11yContract(contract: unknown): XtendPolicyReport;

package/a11y/runtime-a11y-contract.js

@@ -0,0 +1,385 @@
+const RUNTIME_A11Y_CONTRACT_SCHEMA = 'xtend.component.runtime-a11y.v1';
+const RUNTIME_A11Y_REPORT_SCHEMA = 'xtend.component.runtime-a11y-report.v1';
+const RUNTIME_A11Y_WORKPACKAGE = 'WP-E11-04';
+const RUNTIME_A11Y_CONTRACT_DOC = 'development/XTend-Runtime-A11y-UX-Contract.md';
+const COMPONENT_SHELL_CONTRACT_SCHEMA = 'xtend.component.shell.v1';
+const COMPONENT_STYLING_CONTRACT_SCHEMA = 'xtend.component.styling.v1';
+const A11Y_COMPONENT_CONTRACT_SCHEMA = 'xtend.a11y.component-contract.v1';
+const SCREENREADER_SIGNALS_SCHEMA = 'xtend.a11y.screenreader-signals.v1';
+const MOTION_CONTRAST_POLICY_SCHEMA = 'xtend.a11y.motion-contrast-policy.v1';
+const RMT_A11Y_AUTHORING_SCHEMA = 'xtend.rmt.a11y-authoring.v1';
+const FABRIC_BOUNDARY_SCHEMA = 'xtend.component.fabric-boundary.v2';
+const KERNEL_BOUNDARY = 'no-rmt-kernel-import-of-xtend-types';
+
+const RUNTIME_A11Y_REQUIRED_DOMAINS = [
+  'semantics',
+  'accessibleName',
+  'keyboard',
+  'focus',
+  'aria',
+  'screenreader',
+  'motion',
+  'contrast',
+  'states',
+  'forms',
+  'overlays',
+  'routing',
+  'rmt',
+  'fabric',
+  'compatibility',
+  'docs',
+  'tests'
+];
+
+const RUNTIME_A11Y_PROFILES = [
+  'display',
+  'interactive',
+  'form',
+  'feedback',
+  'overlay',
+  'routing',
+  'media'
+];
+
+const RUNTIME_A11Y_REQUIRED_ASSERTIONS = [
+  'semantic-role',
+  'accessible-name',
+  'keyboard-path',
+  'focus-visible',
+  'focus-order',
+  'screenreader-signal',
+  'reduced-motion-safe',
+  'forced-colors-safe',
+  'no-color-only-state'
+];
+
+const RUNTIME_A11Y_REQUIRED_STATES = [
+  'disabled',
+  'busy',
+  'invalid',
+  'error',
+  'expanded',
+  'selected',
+  'active'
+];
+
+const RUNTIME_A11Y_KEYBOARD_KEYS = [
+  'Tab',
+  'Shift+Tab',
+  'Enter',
+  'Space',
+  'Escape',
+  'ArrowLeft',
+  'ArrowRight',
+  'ArrowUp',
+  'ArrowDown',
+  'Home',
+  'End'
+];
+
+const RUNTIME_A11Y_FOCUS_BEHAVIORS = [
+  'visible',
+  'deterministic-order',
+  'restore',
+  'trap',
+  'roving',
+  'route-stable'
+];
+
+const RUNTIME_A11Y_LIVE_REGION_MODES = ['none', 'polite', 'assertive'];
+
+const PROFILE_DEFAULTS = {
+  display: {
+    role: 'region',
+    keyboard: ['Tab'],
+    focus: ['visible'],
+    signals: ['semantic-region'],
+    liveRegion: 'none'
+  },
+  interactive: {
+    role: 'button',
+    keyboard: ['Tab', 'Enter', 'Space'],
+    focus: ['visible', 'deterministic-order'],
+    signals: ['state-change-announcement'],
+    liveRegion: 'none'
+  },
+  form: {
+    role: 'form',
+    keyboard: ['Tab', 'Shift+Tab', 'Enter'],
+    focus: ['visible', 'deterministic-order'],
+    signals: ['validation-error-summary', 'submit-status'],
+    liveRegion: 'polite'
+  },
+  feedback: {
+    role: 'status',
+    keyboard: ['Escape'],
+    focus: ['visible'],
+    signals: ['status-announcement', 'dismissal-announcement'],
+    liveRegion: 'polite'
+  },
+  overlay: {
+    role: 'dialog',
+    keyboard: ['Tab', 'Shift+Tab', 'Escape'],
+    focus: ['visible', 'trap', 'restore'],
+    signals: ['dialog-context', 'focus-return'],
+    liveRegion: 'none'
+  },
+  routing: {
+    role: 'navigation',
+    keyboard: ['Tab', 'Enter', 'ArrowLeft', 'ArrowRight'],
+    focus: ['visible', 'route-stable', 'deterministic-order'],
+    signals: ['route-change-announcement'],
+    liveRegion: 'polite'
+  },
+  media: {
+    role: 'group',
+    keyboard: ['Tab', 'Enter', 'Space', 'ArrowLeft', 'ArrowRight'],
+    focus: ['visible', 'deterministic-order'],
+    signals: ['loading-state', 'control-state'],
+    liveRegion: 'polite'
+  }
+};
+
+function normalizeArray(value) {
+  return Array.isArray(value) ? value.slice() : [];
+}
+
+function unique(values) {
+  return Array.from(new Set(normalizeArray(values).filter(Boolean)));
+}
+
+function normalizeProfiles(inputProfiles) {
+  const profiles = unique(normalizeArray(inputProfiles).length > 0 ? inputProfiles : ['display']);
+  return profiles.filter((profile) => RUNTIME_A11Y_PROFILES.includes(profile)).length > 0
+    ? profiles.filter((profile) => RUNTIME_A11Y_PROFILES.includes(profile))
+    : ['display'];
+}
+
+function collectProfileValue(profiles, key) {
+  return unique(profiles.flatMap((profile) => PROFILE_DEFAULTS[profile][key] || []));
+}
+
+function pickPrimaryProfile(profiles) {
+  return ['overlay', 'form', 'interactive', 'routing', 'feedback', 'media', 'display']
+    .find((profile) => profiles.includes(profile)) || 'display';
+}
+
+function createRuntimeA11yContract(input = {}) {
+  const tag = input.tag || 'x-example';
+  const profiles = normalizeProfiles(input.profiles || input.profile ? normalizeArray(input.profiles || [input.profile]) : ['display']);
+  const primaryProfile = input.primaryProfile || pickPrimaryProfile(profiles);
+  const role = input.role || PROFILE_DEFAULTS[primaryProfile].role;
+  const keyboardKeys = unique(RUNTIME_A11Y_KEYBOARD_KEYS.concat(collectProfileValue(profiles, 'keyboard'), normalizeArray(input.keyboardKeys)));
+  const focusBehaviors = unique(RUNTIME_A11Y_FOCUS_BEHAVIORS.concat(collectProfileValue(profiles, 'focus'), normalizeArray(input.focusBehaviors)));
+  const signals = unique(collectProfileValue(profiles, 'signals').concat(normalizeArray(input.screenreaderSignals)));
+  const liveRegion = input.liveRegion || PROFILE_DEFAULTS[primaryProfile].liveRegion;
+
+  return {
+    schema: RUNTIME_A11Y_CONTRACT_SCHEMA,
+    status: 'contract-draft',
+    workpackage: RUNTIME_A11Y_WORKPACKAGE,
+    componentA11yContract: A11Y_COMPONENT_CONTRACT_SCHEMA,
+    shellContract: COMPONENT_SHELL_CONTRACT_SCHEMA,
+    stylingContract: COMPONENT_STYLING_CONTRACT_SCHEMA,
+    tag,
+    profiles,
+    primaryProfile,
+    semantics: {
+      role,
+      nativeFirst: true,
+      ariaOnlyWhenNativeSemanticsAreInsufficient: true,
+      landmarkAllowed: ['region', 'navigation', 'form', 'dialog', 'status', 'group']
+    },
+    accessibleName: {
+      required: true,
+      sources: ['aria-label', 'aria-labelledby', 'label-slot', 'visible-text', 'host-label'],
+      fallbackAllowed: false
+    },
+    keyboard: {
+      required: true,
+      keys: keyboardKeys,
+      activation: ['Enter', 'Space'],
+      escapeBehaviorRequiredForDismissible: true,
+      rovingTabindexAllowed: true
+    },
+    focus: {
+      behaviors: focusBehaviors,
+      visibleRequired: true,
+      deterministicOrderRequired: true,
+      restoreRequiredForOverlays: profiles.includes('overlay'),
+      trapRequiredForModalOverlays: profiles.includes('overlay'),
+      routeFocusRequired: profiles.includes('routing')
+    },
+    aria: {
+      requiredStates: ['aria-label', 'aria-labelledby', 'aria-describedby', 'aria-disabled', 'aria-busy', 'aria-invalid', 'aria-required', 'aria-current', 'aria-expanded'],
+      invalidAriaPolicy: 'diagnose-and-fail-gate',
+      mirrorVisualStates: true
+    },
+    screenreader: {
+      schema: SCREENREADER_SIGNALS_SCHEMA,
+      signals,
+      liveRegion,
+      liveRegionModes: RUNTIME_A11Y_LIVE_REGION_MODES.slice(),
+      statusRegionsRequired: profiles.includes('feedback') || profiles.includes('form') || profiles.includes('routing'),
+      errorRegionsRequired: profiles.includes('form')
+    },
+    motion: {
+      schema: MOTION_CONTRAST_POLICY_SCHEMA,
+      reducedMotionSafe: true,
+      noMotionRequiredForCoreFunction: true,
+      preferenceMediaQuery: 'prefers-reduced-motion'
+    },
+    contrast: {
+      schema: MOTION_CONTRAST_POLICY_SCHEMA,
+      highContrastRequired: true,
+      forcedColorsRequired: true,
+      focusVisibleRequired: true,
+      noColorOnlyState: true
+    },
+    states: {
+      requiredBehavior: RUNTIME_A11Y_REQUIRED_STATES.slice(),
+      disabled: ['aria-disabled', 'native-disabled-if-available', 'keyboard-blocked'],
+      busy: ['aria-busy', 'screenreader-status'],
+      invalid: ['aria-invalid', 'describedby-error', 'assertive-error-region'],
+      error: ['role-alert-or-associated-error'],
+      active: ['aria-current-or-selected']
+    },
+    forms: {
+      labelsRequired: true,
+      describedByRequiredForHelpAndError: true,
+      validationAnnouncementRequired: true,
+      firstInvalidFocusPolicy: 'first-invalid-or-summary'
+    },
+    overlays: {
+      dialogRoleRequired: true,
+      ariaModalRequired: true,
+      inertBackgroundRequired: true,
+      escapeCloseRequired: true,
+      focusTrapRequired: profiles.includes('overlay'),
+      focusReturnRequired: profiles.includes('overlay')
+    },
+    routing: {
+      ariaCurrentRequired: true,
+      routeAnnouncementRequired: profiles.includes('routing'),
+      focusRestoreRequired: true,
+      activeRouteFocusRequired: profiles.includes('routing')
+    },
+    rmt: {
+      schema: RMT_A11Y_AUTHORING_SCHEMA,
+      adapter: 'xtend.component',
+      fields: ['a11y', 'role', 'name', 'description', 'keyboard', 'focus', 'aria', 'screenreader', 'motion', 'contrast'],
+      kernelBoundary: KERNEL_BOUNDARY
+    },
+    fabric: {
+      schema: FABRIC_BOUNDARY_SCHEMA,
+      lane: 'a11y',
+      fiberKinds: ['a11y.keyboard', 'a11y.focus', 'a11y.announce', 'a11y.preference'],
+      diagnostics: ['a11y.name.missing', 'a11y.focus.invisible', 'a11y.keyboard.unreachable', 'a11y.aria.invalid']
+    },
+    compatibility: {
+      hostModes: ['xtend-only', 'rmt-first', 'vanilla', 'react', 'vue', 'custom-shell'],
+      browserBehaviorRequired: true,
+      noFrameworkSpecificWrapperRequired: true,
+      noCdnDependency: true
+    },
+    docs: {
+      contract: RUNTIME_A11Y_CONTRACT_DOC,
+      requiredSections: ['Semantics', 'Accessible Name', 'Keyboard', 'Focus', 'ARIA', 'Screenreader', 'Motion', 'Contrast', 'States', 'RMT Authoring']
+    },
+    tests: {
+      requiredSuites: ['runtime-a11y-contract', 'a11y-hydration', 'screenreader-signals', 'motion-contrast', 'references'],
+      assertions: RUNTIME_A11Y_REQUIRED_ASSERTIONS.slice(),
+      browserSmokeRequiredForInteractiveShells: true
+    }
+  };
+}
+
+function validateRuntimeA11yContract(contract = {}) {
+  const errors = [];
+
+  if (contract.schema !== RUNTIME_A11Y_CONTRACT_SCHEMA) {
+    errors.push(`schema must be ${RUNTIME_A11Y_CONTRACT_SCHEMA}`);
+  }
+  if (!/^x-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(String(contract.tag || ''))) {
+    errors.push('tag must be a valid XTend custom element tag');
+  }
+
+  RUNTIME_A11Y_REQUIRED_DOMAINS.forEach((domain) => {
+    if (!contract[domain]) {
+      errors.push(`missing domain: ${domain}`);
+    }
+  });
+
+  if (!Array.isArray(contract.profiles) || contract.profiles.some((profile) => !RUNTIME_A11Y_PROFILES.includes(profile))) {
+    errors.push(`profiles must use known values: ${RUNTIME_A11Y_PROFILES.join(', ')}`);
+  }
+  if (contract.semantics && contract.semantics.nativeFirst !== true) {
+    errors.push('semantics.nativeFirst must be true');
+  }
+  if (contract.accessibleName && contract.accessibleName.required !== true) {
+    errors.push('accessibleName.required must be true');
+  }
+  if (!contract.keyboard || contract.keyboard.required !== true || !normalizeArray(contract.keyboard.keys).includes('Tab')) {
+    errors.push('keyboard must be required and include Tab');
+  }
+  if (!contract.focus || contract.focus.visibleRequired !== true || contract.focus.deterministicOrderRequired !== true) {
+    errors.push('focus must require visible focus and deterministic order');
+  }
+  if (!contract.aria || contract.aria.mirrorVisualStates !== true) {
+    errors.push('aria.mirrorVisualStates must be true');
+  }
+  if (!contract.screenreader || contract.screenreader.schema !== SCREENREADER_SIGNALS_SCHEMA) {
+    errors.push(`screenreader.schema must be ${SCREENREADER_SIGNALS_SCHEMA}`);
+  }
+  if (contract.screenreader && !RUNTIME_A11Y_LIVE_REGION_MODES.includes(contract.screenreader.liveRegion)) {
+    errors.push(`screenreader.liveRegion must be one of: ${RUNTIME_A11Y_LIVE_REGION_MODES.join(', ')}`);
+  }
+  if (contract.motion && contract.motion.reducedMotionSafe !== true) {
+    errors.push('motion.reducedMotionSafe must be true');
+  }
+  if (contract.contrast && contract.contrast.noColorOnlyState !== true) {
+    errors.push('contrast.noColorOnlyState must be true');
+  }
+  if (contract.states && !RUNTIME_A11Y_REQUIRED_STATES.every((state) => normalizeArray(contract.states.requiredBehavior).includes(state))) {
+    errors.push(`states.requiredBehavior must include ${RUNTIME_A11Y_REQUIRED_STATES.join(', ')}`);
+  }
+  if (contract.rmt && contract.rmt.kernelBoundary !== KERNEL_BOUNDARY) {
+    errors.push('rmt.kernelBoundary must keep the RMT kernel decoupled from XTend types');
+  }
+  if (contract.fabric && contract.fabric.lane !== 'a11y') {
+    errors.push('fabric.lane must be a11y');
+  }
+  if (contract.compatibility && contract.compatibility.browserBehaviorRequired !== true) {
+    errors.push('compatibility.browserBehaviorRequired must be true');
+  }
+
+  return {
+    schema: RUNTIME_A11Y_REPORT_SCHEMA,
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+module.exports = {
+  RUNTIME_A11Y_CONTRACT_SCHEMA,
+  RUNTIME_A11Y_REPORT_SCHEMA,
+  RUNTIME_A11Y_WORKPACKAGE,
+  RUNTIME_A11Y_CONTRACT_DOC,
+  COMPONENT_SHELL_CONTRACT_SCHEMA,
+  COMPONENT_STYLING_CONTRACT_SCHEMA,
+  A11Y_COMPONENT_CONTRACT_SCHEMA,
+  SCREENREADER_SIGNALS_SCHEMA,
+  MOTION_CONTRAST_POLICY_SCHEMA,
+  RMT_A11Y_AUTHORING_SCHEMA,
+  FABRIC_BOUNDARY_SCHEMA,
+  KERNEL_BOUNDARY,
+  RUNTIME_A11Y_REQUIRED_DOMAINS,
+  RUNTIME_A11Y_PROFILES,
+  RUNTIME_A11Y_REQUIRED_ASSERTIONS,
+  RUNTIME_A11Y_REQUIRED_STATES,
+  RUNTIME_A11Y_KEYBOARD_KEYS,
+  RUNTIME_A11Y_FOCUS_BEHAVIORS,
+  RUNTIME_A11Y_LIVE_REGION_MODES,
+  createRuntimeA11yContract,
+  validateRuntimeA11yContract
+};