@koehler8/cms 1.0.0-beta.16 → 1.0.0-beta.18

package/README.md

@@ -5,6 +5,12 @@
 
 Vertex CMS is a lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support.
 
+## Accessibility
+
+Vertex CMS targets **[WCAG 2.2 Level AA](https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_overview&versions=2.2&levels=aaa)** as a hard requirement for the bundled components, the `base` theme, and the page wrapper. Sites that ship on this framework with the bundled pieces inherit a skip link, single `<main>` landmark, real form labels with `aria-live` errors, visible focus rings, modal focus trap+restore, AA-verified palette contrast, and `prefers-reduced-motion` support out of the box.
+
+When extending or theming, **don't regress AA**. See the "Accessibility" section of [CLAUDE.md](CLAUDE.md#accessibility-wcag-22-level-aa--hard-requirement) for the requirements, the token naming conventions for safe colors, and the audit checklist to run when changing palette/markup/CSS.
+
 ## Quick Start
 
 ### 1. Create a site repo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.16",
+  "version": "1.0.0-beta.18",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",

package/src/components/ComingSoonModal.vue

@@ -68,6 +68,7 @@ const props = defineProps({
 const emit = defineEmits(['close']);
 
 const dialogRef = ref(null);
+const previousFocusedElement = ref(null);
 const focusableSelector = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
 const dialogTitleId = computed(() => 'coming-soon-title');
 const dialogDescriptionId = computed(() => 'coming-soon-message');
@@ -76,6 +77,13 @@ const emitClose = () => {
   emit('close');
 };
 
+const onDocumentKeydown = (event) => {
+  if (event.key === 'Escape' || event.key === 'Esc') {
+    event.preventDefault();
+    emitClose();
+  }
+};
+
 const trapFocus = (event) => {
   if (!props.open) return;
   if (typeof document === 'undefined') return;
@@ -103,6 +111,9 @@ watch(
   (isOpen) => {
     if (typeof document === 'undefined') return;
     if (isOpen) {
+      // Capture whatever was focused before the modal opened so we can
+      // restore focus on close (WCAG 2.4.3 Focus Order).
+      previousFocusedElement.value = document.activeElement;
       if (typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function') {
         window.requestAnimationFrame(() => {
           dialogRef.value?.focus();
@@ -111,8 +122,15 @@ watch(
         dialogRef.value?.focus();
       }
       document.addEventListener('keydown', trapFocus);
+      document.addEventListener('keydown', onDocumentKeydown);
     } else {
       document.removeEventListener('keydown', trapFocus);
+      document.removeEventListener('keydown', onDocumentKeydown);
+      const previous = previousFocusedElement.value;
+      if (previous && typeof previous.focus === 'function') {
+        previous.focus();
+      }
+      previousFocusedElement.value = null;
     }
   }
 );
@@ -121,12 +139,14 @@ onMounted(() => {
   if (typeof document === 'undefined') return;
   if (props.open) {
     document.addEventListener('keydown', trapFocus);
+    document.addEventListener('keydown', onDocumentKeydown);
   }
 });
 
 onBeforeUnmount(() => {
   if (typeof document === 'undefined') return;
   document.removeEventListener('keydown', trapFocus);
+  document.removeEventListener('keydown', onDocumentKeydown);
 });
 </script>
 
@@ -212,19 +232,31 @@ onBeforeUnmount(() => {
 
 .coming-soon-close {
   position: absolute;
-  top: 0.75rem;
-  right: 0.75rem;
+  top: 0.5rem;
+  right: 0.5rem;
   background: transparent;
   border: none;
   font-size: 1.5rem;
   line-height: 1;
   cursor: pointer;
-  color: #888;
-  padding: 0.25rem;
+  /* AA-safe color (#595959 = 7:1 on white) and a 32×32 hit area for
+     2.5.8 Target Size (Minimum). */
+  color: #595959;
+  padding: 0;
+  min-width: 32px;
+  min-height: 32px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 6px;
 }
 
 .coming-soon-close:hover,
-.coming-soon-close:focus {
+.coming-soon-close:focus-visible {
   color: #111111;
 }
+.coming-soon-close:focus-visible {
+  outline: 2px solid #1f2a44;
+  outline-offset: 2px;
+}
 </style>

package/src/components/Contact.vue

@@ -21,43 +21,104 @@
 
           <div class="contact-grid">
             <div class="contact-field">
-              <input class="ui-form-control" type="text" :placeholder="placeholders.name" name="entry.757423084" required>
+              <label class="contact-label ui-label-sm" for="contact-name">
+                {{ placeholders.name }}<span class="contact-required" aria-hidden="true">*</span>
+              </label>
+              <input
+                id="contact-name"
+                class="ui-form-control"
+                type="text"
+                :placeholder="placeholders.name"
+                name="entry.757423084"
+                autocomplete="name"
+                required
+                aria-required="true"
+              >
             </div>
             <div class="contact-field">
-              <input class="ui-form-control" type="email" :placeholder="placeholders.email" name="entry.886201522" required>
+              <label class="contact-label ui-label-sm" for="contact-email">
+                {{ placeholders.email }}<span class="contact-required" aria-hidden="true">*</span>
+              </label>
+              <input
+                id="contact-email"
+                class="ui-form-control"
+                type="email"
+                :placeholder="placeholders.email"
+                name="entry.886201522"
+                autocomplete="email"
+                required
+                aria-required="true"
+              >
             </div>
             <div class="contact-field">
-              <input class="ui-form-control" type="text" :placeholder="placeholders.subject" name="entry.270717970">
+              <label class="contact-label ui-label-sm" for="contact-subject">{{ placeholders.subject }}</label>
+              <input
+                id="contact-subject"
+                class="ui-form-control"
+                type="text"
+                :placeholder="placeholders.subject"
+                name="entry.270717970"
+              >
             </div>
             <div class="contact-field">
-              <input class="ui-form-control" type="tel" :placeholder="placeholders.phone" name="entry.1570175907">
+              <label class="contact-label ui-label-sm" for="contact-phone">{{ placeholders.phone }}</label>
+              <input
+                id="contact-phone"
+                class="ui-form-control"
+                type="tel"
+                :placeholder="placeholders.phone"
+                name="entry.1570175907"
+                autocomplete="tel"
+              >
             </div>
             <div class="contact-field contact-field--full">
-              <textarea class="ui-form-control ui-form-textarea" rows="6" :placeholder="placeholders.message" name="entry.1743462629" required></textarea>
+              <label class="contact-label ui-label-sm" for="contact-message">
+                {{ placeholders.message }}<span class="contact-required" aria-hidden="true">*</span>
+              </label>
+              <textarea
+                id="contact-message"
+                class="ui-form-control ui-form-textarea"
+                rows="6"
+                :placeholder="placeholders.message"
+                name="entry.1743462629"
+                required
+                aria-required="true"
+              ></textarea>
             </div>
             <div class="contact-field contact-field--full">
-              <label class="contact-label ui-label-sm">{{ challenge.label }}</label>
+              <label class="contact-label ui-label-sm" for="contact-challenge">
+                {{ challenge.label }}<span class="contact-required" aria-hidden="true">*</span>
+              </label>
               <small
                 v-if="challenge.instructions"
+                id="contact-challenge-hint"
                 class="contact-hint ui-form-hint"
                 :class="{ 'contact-hint--inline': challenge.label.length < 18 }"
               >
                 {{ challenge.instructions }}
               </small>
               <div class="ui-input-group">
-                <span class="ui-input-group__addon">{{ challenge.question }}</span>
+                <span class="ui-input-group__addon" id="contact-challenge-prompt">{{ challenge.question }}</span>
                 <input
+                  id="contact-challenge"
                   type="text"
                   class="ui-input-group__input"
                   :placeholder="challenge.placeholder"
                   v-model="challengeAnswer"
                   autocomplete="off"
                   required
+                  aria-required="true"
+                  :aria-describedby="challengeDescribedBy"
+                  :aria-invalid="hasChallengeError ? 'true' : null"
                 >
               </div>
             </div>
           </div>
 
+          <p class="contact-required-note">
+            <span class="contact-required" aria-hidden="true">*</span> Required fields
+          </p>
+
           <div class="contact-actions">
             <div
               v-if="isConfirmationVisible"
@@ -69,7 +130,7 @@
             </div>
             <button class="primary-button contact-submit" type="submit">{{ submitLabel }}</button>
           </div>
-          <small id="msg" class="contact-feedback"></small>
+          <p id="msg" class="contact-feedback" role="status" aria-live="polite" aria-atomic="true"></p>
         </form>
       </div>
     </div>
@@ -77,7 +138,7 @@
 </template>
 
 <script setup>
-import { inject, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
+import { computed, inject, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
 import { trackEvent } from '../utils/analytics.js';
 
 const title = ref('Contact Us')
@@ -129,6 +190,14 @@ const challenge = reactive({
 })
 
 const challengeAnswer = ref('')
+const hasChallengeError = ref(false)
+
+const challengeDescribedBy = computed(() => {
+  const ids = ['contact-challenge-prompt']
+  if (challenge.instructions) ids.push('contact-challenge-hint')
+  if (hasChallengeError.value) ids.push('msg')
+  return ids.join(' ')
+})
 
 let expectedChallengeAnswer = ''
 let activeChallengeType = 'arithmetic'
@@ -405,12 +474,14 @@ onMounted(() => {
 
     if (!isChallengeAnswerCorrect(challengeAnswer.value)) {
       msg.textContent = challenge.errorMessage
+      hasChallengeError.value = true
       emitSubmitEvent('challenge_failed')
       challengeAnswer.value = ''
       generateChallenge()
       return
     }
 
+    hasChallengeError.value = false
     msg.textContent = pendingMessage.value
 
     try {
@@ -491,6 +562,17 @@ onUnmounted(() => {
   color: var(--contact-label-color, var(--ui-text-primary, #1f2a44));
 }
 
+.contact-required {
+  margin-left: 0.2em;
+  color: var(--contact-required-color, #a83838); /* AA-safe critical text */
+}
+
+.contact-required-note {
+  margin: -8px 0 0;
+  font-size: 0.8rem;
+  color: var(--contact-required-note-color, var(--ui-text-muted, #54627b));
+}
+
 .contact-hint--inline {
   display: inline-block;
   margin-left: 6px;

package/src/components/DraftGate.vue

@@ -0,0 +1,212 @@
+<template>
+  <section
+    class="draft-gate"
+    role="dialog"
+    aria-modal="true"
+    aria-labelledby="draft-gate-title"
+    aria-describedby="draft-gate-description"
+  >
+    <div class="draft-gate-card" ref="cardRef" tabindex="-1">
+      <p class="draft-gate-eyebrow">Draft</p>
+      <h1 id="draft-gate-title" class="draft-gate-title">
+        This page is not yet public
+      </h1>
+      <p id="draft-gate-description" class="draft-gate-body">
+        {{ bodyText }}
+      </p>
+      <form class="draft-gate-form" @submit.prevent="handleSubmit" novalidate>
+        <label class="draft-gate-label" for="draft-gate-password">
+          Password
+        </label>
+        <input
+          id="draft-gate-password"
+          ref="inputRef"
+          v-model="passwordInput"
+          type="password"
+          autocomplete="current-password"
+          autocapitalize="off"
+          autocorrect="off"
+          spellcheck="false"
+          :aria-invalid="hasError ? 'true' : 'false'"
+          aria-describedby="draft-gate-error"
+          class="draft-gate-input"
+        />
+        <p
+          id="draft-gate-error"
+          class="draft-gate-error"
+          aria-live="polite"
+          role="status"
+        >
+          {{ errorMessage }}
+        </p>
+        <button type="submit" class="draft-gate-submit">
+          {{ submitLabel }}
+        </button>
+      </form>
+    </div>
+  </section>
+</template>
+
+<script setup>
+import { computed, nextTick, onMounted, ref } from 'vue';
+
+const props = defineProps({
+  hasPassword: {
+    type: Boolean,
+    default: false,
+  },
+  errorMessage: {
+    type: String,
+    default: '',
+  },
+});
+
+const emit = defineEmits(['submit']);
+
+const passwordInput = ref('');
+const inputRef = ref(null);
+const cardRef = ref(null);
+const hasError = computed(() => Boolean(props.errorMessage));
+
+const bodyText = computed(() =>
+  props.hasPassword
+    ? 'Enter the password to preview this content.'
+    : 'No password is required — submit to continue.',
+);
+
+const submitLabel = computed(() => (props.hasPassword ? 'Unlock' : 'Continue'));
+
+function handleSubmit() {
+  emit('submit', passwordInput.value);
+}
+
+onMounted(() => {
+  if (import.meta.env.SSR) return;
+  nextTick(() => {
+    inputRef.value?.focus();
+  });
+});
+</script>
+
+<style scoped>
+.draft-gate {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100dvh;
+  padding: clamp(1.5rem, 5vw, 3rem);
+  background: var(--brand-surface, #f7f7f8);
+  color: var(--brand-text, #1f2a44);
+  font-family: var(--ui-font-body, system-ui, -apple-system, sans-serif);
+}
+
+.draft-gate-card {
+  width: 100%;
+  max-width: 28rem;
+  padding: clamp(1.75rem, 4vw, 2.5rem);
+  background: var(--brand-surface-elevated, #ffffff);
+  border: 1px solid var(--brand-border, rgba(31, 42, 68, 0.12));
+  border-radius: clamp(12px, 2vw, 18px);
+  box-shadow: 0 18px 38px rgba(15, 22, 42, 0.08);
+  outline: none;
+}
+
+.draft-gate-eyebrow {
+  margin: 0 0 0.5rem;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: var(--brand-text-muted, rgba(31, 42, 68, 0.6));
+}
+
+.draft-gate-title {
+  margin: 0 0 0.75rem;
+  font-size: clamp(1.4rem, 2.6vw, 1.75rem);
+  line-height: 1.2;
+  font-weight: 700;
+}
+
+.draft-gate-body {
+  margin: 0 0 1.5rem;
+  font-size: 1rem;
+  line-height: 1.55;
+  color: var(--brand-text-muted, rgba(31, 42, 68, 0.75));
+}
+
+.draft-gate-form {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.draft-gate-label {
+  font-size: 0.85rem;
+  font-weight: 600;
+  color: var(--brand-text, #1f2a44);
+}
+
+.draft-gate-input {
+  width: 100%;
+  min-height: 2.75rem;
+  padding: 0.65rem 0.85rem;
+  font-size: 1rem;
+  font-family: inherit;
+  background: var(--brand-surface, #ffffff);
+  color: inherit;
+  border: 1px solid var(--brand-border, rgba(31, 42, 68, 0.25));
+  border-radius: var(--brand-input-radius, 8px);
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.draft-gate-input:focus-visible {
+  outline: 2px solid var(--brand-primary, #1f2a44);
+  outline-offset: 2px;
+  border-color: var(--brand-primary, #1f2a44);
+}
+
+.draft-gate-input[aria-invalid='true'] {
+  border-color: var(--brand-criticalText, #b3261e);
+}
+
+.draft-gate-error {
+  min-height: 1.25rem;
+  margin: 0;
+  font-size: 0.85rem;
+  color: var(--brand-criticalText, #b3261e);
+}
+
+.draft-gate-submit {
+  margin-top: 0.5rem;
+  min-height: 2.75rem;
+  padding: 0.7rem 1.4rem;
+  font-size: 1rem;
+  font-family: inherit;
+  font-weight: 600;
+  color: var(--brand-primary-cta-text, #ffffff);
+  background: var(--brand-primary-cta, var(--brand-primary, #1f2a44));
+  border: none;
+  border-radius: var(--brand-button-radius, 10px);
+  cursor: pointer;
+  transition: transform 0.15s ease, box-shadow 0.15s ease, background 0.15s ease;
+}
+
+.draft-gate-submit:hover {
+  transform: translateY(-1px);
+}
+
+.draft-gate-submit:focus-visible {
+  outline: 2px solid var(--brand-primary, #1f2a44);
+  outline-offset: 3px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .draft-gate-submit,
+  .draft-gate-input {
+    transition: none;
+  }
+  .draft-gate-submit:hover {
+    transform: none;
+  }
+}
+</style>

package/src/components/Footer.vue

@@ -2,10 +2,10 @@
   <footer class="site-footer ui-footer" data-analytics-section="footer">
     <div class="container ui-footer__grid">
       <div class="ui-footer__brand">
-        <a class="ui-footer__logo" href="/" aria-label="Return home">
+        <a class="ui-footer__logo" href="/">
           <img
             :src="logoSrc"
-            :alt="siteName"
+            :alt="`${siteName} – home`"
             class="site-footer__logo-img"
             loading="lazy"
             decoding="async"
@@ -25,6 +25,7 @@
                 rel="noopener noreferrer"
               >
                 <span>{{ link.text }}</span>
+                <span class="ui-footer__sr-only">(opens in a new tab)</span>
                 <span class="ui-footer__link-icon" aria-hidden="true">&gt;</span>
               </a>
             </li>
@@ -62,4 +63,16 @@ const footerLinks = computed(() =>
 .ui-footer__text {
   margin-bottom: 0;
 }
+
+.ui-footer__sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
 </style>

package/src/components/FooterMinimal.vue

@@ -3,7 +3,7 @@
     <div class="container" role="presentation">
       <div class="footer-grid">
         <a class="footer-logo" href="/">
-          <img :src="logoSrc" :alt="siteName" class="img-fluid" />
+          <img :src="logoSrc" :alt="`${siteName} – home`" class="img-fluid" />
         </a>
         <p class="footer-text">{{ footerText }}</p>
         <p v-if="footerDisclaimer" class="footer-disclaimer">
@@ -78,7 +78,10 @@ const footerDisclaimer = computed(() => footerContent.value?.disclaimer || '');
     --footer-bg,
     color-mix(in srgb, var(--brand-bg-900, #070410) 88%, var(--brand-bg-800, #120b1f) 12%)
   );
-  color: var(--footer-text, var(--ui-text-primary, var(--brand-card-text, #f0eaf3)));
+  /* Read from --brand-footer-text (defined by the theme via tokens.footer.text)
+     so the default light/text-on-dark pairing always holds. The intermediate
+     --footer-text exists for site-level overrides. */
+  color: var(--footer-text, var(--brand-footer-text, #f0eaf3));
   padding: 48px 0 28px;
 }
 
@@ -96,7 +99,7 @@ const footerDisclaimer = computed(() => footerContent.value?.disclaimer || '');
 .footer-text {
   max-width: 520px;
   margin: 0;
-  color: var(--footer-text, var(--ui-text-primary, var(--brand-card-text, #f0eaf3)));
+  color: var(--footer-text, var(--brand-footer-text, #f0eaf3));
   font-size: 0.9rem;
   line-height: 1.55;
 }
@@ -107,10 +110,7 @@ const footerDisclaimer = computed(() => footerContent.value?.disclaimer || '');
   font-size: 0.75rem;
   font-style: italic;
   line-height: 1.6;
-  color: var(
-    --footer-disclaimer,
-    color-mix(in srgb, var(--ui-text-muted, var(--brand-card-text, #f0eaf3)) 70%, transparent)
-  );
+  color: var(--footer-disclaimer, var(--brand-footer-text-muted, #c8c2cf));
 }
 
 .footer-links {
@@ -124,19 +124,20 @@ const footerDisclaimer = computed(() => footerContent.value?.disclaimer || '');
 }
 
 .footer-link {
-  color: var(
-    --footer-link-color,
-    color-mix(in srgb, var(--ui-text-primary, var(--brand-card-text, #f0eaf3)) 75%, transparent)
-  );
+  color: var(--footer-link-color, var(--brand-footer-link-color, #f0eaf3));
   text-decoration: none;
   transition: color 0.2s ease, text-decoration 0.2s ease;
 }
 
 .footer-link:hover,
 .footer-link:focus-visible {
-  color: var(--footer-link-hover, var(--brand-accent-electric, #27f3ff));
+  color: var(--footer-link-hover, var(--brand-footer-link-hover, #ffffff));
   text-decoration: underline;
 }
+.footer-link:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 3px;
+}
 
 @media (prefers-reduced-motion: reduce) {
   .footer-link {

package/src/components/Header.vue

@@ -8,10 +8,10 @@
       class="site-header__section ui-header__section"
       :class="{ 'ui-header__section--compact': isHeaderCompact }"
     >
-      <nav class="site-header__nav">
+      <nav class="site-header__nav" aria-label="Primary">
         <div class="container">
           <div class="site-header__inner">
-            <a href="/" ref="logoLinkRef" class="site-header__logo logo-flash-trigger">
+            <a href="/" ref="logoLinkRef" class="site-header__logo logo-flash-trigger" :aria-label="`${siteName || 'Home'} – home`">
               <!--
                 Logo slot. Default rendering: <img> if site/assets/img/logo.png
                 exists or `content.header.logoSrc` is set, otherwise text from
@@ -56,6 +56,8 @@
               v-if="showLocaleLinks && availableLocales.length > 1"
               ref="localeWrapperRef"
               class="locale-wrapper"
+              @keydown.esc="closeLocaleMenu($event, 'escape')"
+              @focusout="onLocaleWrapperFocusOut"
             >
               <button
                 id="languages-dropdown-invoker-2"
@@ -63,8 +65,8 @@
                 class="locale-toggle"
                 type="button"
                 aria-controls="languages-dropdown-2"
-                aria-haspopup="true"
                 :aria-expanded="isLangOpen ? 'true' : 'false'"
+                aria-label="Change language"
                 @click="toggleLocaleMenu"
               >
                 <span class="locale-flag" aria-hidden="true">
@@ -221,6 +223,37 @@ const updateLocaleMenuPosition = () => {
     }
   };
 
+  // Closes the dropdown and (for keyboard dismissal) returns focus to the
+  // toggle button. Without focus restoration, ESC would leave focus on a
+  // hidden menu item — failing 1.4.13 (Content on Hover or Focus).
+  const closeLocaleMenu = (event, trigger = 'escape') => {
+    if (!isLangOpen.value) return;
+    if (event) {
+      event.preventDefault?.();
+      event.stopPropagation?.();
+    }
+    isLangOpen.value = false;
+    trackEvent('header_locale_menu_toggle', {
+      state: 'close',
+      trigger,
+      active_locale: currentLocale.value || 'en',
+    });
+    if (trigger === 'escape') {
+      nextTick(() => langButtonRef.value?.focus());
+    }
+  };
+
+  // Closes the menu when keyboard focus leaves the wrapper entirely.
+  // Without this, Tab would walk past the dropdown but leave it visible
+  // and clickable — also fails 1.4.13's "dismissable" requirement.
+  const onLocaleWrapperFocusOut = (event) => {
+    if (!isLangOpen.value) return;
+    const wrapper = localeWrapperRef.value;
+    const next = event.relatedTarget;
+    if (wrapper && next && wrapper.contains(next)) return;
+    closeLocaleMenu(null, 'focusout');
+  };
+
   const prefersReducedMotion = () =>
     typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;