rails_onboarding 0.6.1

data/app/assets/stylesheets/rails_onboarding/accessibility.css

@@ -0,0 +1,536 @@
+/* ======================
+   Accessibility Enhancements
+   ======================
+
+   Scoping: every rule here is confined to markup the engine owns, via
+   `:where(.onboarding-container)` (engine pages) or `:where(.onboarding-banner)`
+   (chrome rendered on host-app pages). `:where()` carries zero specificity, so
+   scoping a rule does not change how it competes in the cascade with the gem's
+   other stylesheets - mobile.css's media-query overrides still win the same ties
+   they won before.
+
+   Bare element selectors (`a`, `table`, `fieldset`, `[role="dialog"]`, ...) must
+   never appear unscoped in this file. Host apps bundle this stylesheet into
+   their global CSS, so an unscoped `a { text-decoration: underline }` restyles
+   every link in the host application.
+
+   Utility classes meant to be used outside the container (screen-reader text,
+   skip links) are namespaced with `onboarding-` instead of scoped, since they
+   are opt-in by class name and cannot collide unintentionally. */
+
+/* Skip links for keyboard navigation.
+   Deliberately unscoped: a skip link has to be the first focusable element in
+   the document, which puts it above .onboarding-container in the DOM. The
+   `onboarding-` prefix is what keeps it from colliding with host styles. */
+.onboarding-skip-link {
+  position: absolute;
+  top: -2.5rem;
+  left: var(--onboarding-space-md);
+  background: var(--onboarding-primary);
+  color: white;
+  padding: var(--onboarding-space-sm) var(--onboarding-space-md);
+  border-radius: 0.375rem;
+  text-decoration: none;
+  font-weight: 500;
+  z-index: 10000;
+  transition: top 0.3s ease;
+}
+
+.onboarding-skip-link:focus {
+  top: var(--onboarding-space-md);
+}
+
+/* Enhanced focus indicators */
+.onboarding-container *:focus-visible {
+  outline: 2px solid var(--onboarding-primary);
+  outline-offset: 2px;
+  border-radius: 0.25rem;
+}
+
+/* High contrast focus for interactive elements */
+:where(.onboarding-container) button:focus-visible,
+:where(.onboarding-container) input:focus-visible,
+:where(.onboarding-container) select:focus-visible,
+:where(.onboarding-container) textarea:focus-visible,
+:where(.onboarding-container) a:focus-visible,
+:where(.onboarding-container) [tabindex]:focus-visible {
+  outline: 3px solid var(--onboarding-primary);
+  outline-offset: 2px;
+}
+
+/* Ensure minimum touch target size */
+:where(.onboarding-container) button,
+:where(.onboarding-container) input[type="button"],
+:where(.onboarding-container) input[type="submit"],
+:where(.onboarding-container) input[type="reset"],
+:where(.onboarding-container) .primary-action,
+:where(.onboarding-container) .secondary-action,
+:where(.onboarding-container) .skip-action,
+:where(.onboarding-container) .help-action,
+:where(.onboarding-container) .feature-button,
+:where(.onboarding-container) .tooltip-action {
+  min-height: 2.75rem; /* 44px minimum touch target */
+  min-width: 2.75rem;
+}
+
+/* The banner renders on host-app pages, outside .onboarding-container, so its
+   controls need the touch-target floor applied on their own scope rather than
+   inheriting it from the rule above. */
+:where(.onboarding-banner) .onboarding-banner-continue,
+:where(.onboarding-banner) .onboarding-banner-skip {
+  min-height: 2.75rem;
+}
+
+/* Enhanced button states for better accessibility */
+:where(.onboarding-container) button:disabled,
+:where(.onboarding-container) input:disabled,
+:where(.onboarding-container) select:disabled,
+:where(.onboarding-container) textarea:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+  background-color: var(--onboarding-surface);
+  color: var(--onboarding-text-muted);
+}
+
+/* Better color contrast for text */
+.onboarding-text-high-contrast {
+  color: var(--onboarding-text);
+  font-weight: 500;
+}
+
+.onboarding-text-medium-contrast {
+  color: var(--onboarding-text-muted);
+  font-weight: 400;
+}
+
+/* ARIA live regions for dynamic content */
+.onboarding-live-region {
+  position: absolute;
+  left: -10000px;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+}
+
+/* Screen reader only content that can be focused.
+   Unscoped for the same reason as .onboarding-skip-link - these are opt-in
+   utilities that may be used outside the container. The base
+   `.onboarding-sr-only` lives in utilities.css. */
+.onboarding-sr-only-focusable:focus,
+.onboarding-sr-only-focusable:active {
+  position: static !important;
+  width: auto !important;
+  height: auto !important;
+  margin: 0 !important;
+  overflow: visible !important;
+  clip: auto !important;
+  white-space: normal !important;
+}
+
+/* Enhanced error messaging */
+:where(.onboarding-container) .onboarding-error-message {
+  color: var(--onboarding-danger);
+  font-size: var(--onboarding-text-sm);
+  margin-top: var(--onboarding-space-xs);
+  display: flex;
+  align-items: flex-start;
+  gap: var(--onboarding-space-xs);
+}
+
+:where(.onboarding-container) .onboarding-error-icon {
+  flex-shrink: 0;
+  margin-top: 0.125rem;
+  font-size: var(--onboarding-text-base);
+}
+
+/* Required field indicators */
+:where(.onboarding-container) .required-indicator {
+  color: var(--onboarding-danger);
+  margin-left: var(--onboarding-space-xs);
+  font-weight: 600;
+}
+
+/* Field descriptions and help text */
+:where(.onboarding-container) .field-description {
+  font-size: var(--onboarding-text-sm);
+  color: var(--onboarding-text-muted);
+  margin-top: var(--onboarding-space-xs);
+  line-height: 1.4;
+}
+
+/* Progress indicators with better semantics */
+:where(.onboarding-container, .onboarding-banner) .onboarding-progress-container[role="progressbar"] {
+  background: var(--onboarding-surface);
+  border: 1px solid var(--onboarding-border);
+  border-radius: 0.5rem;
+  overflow: hidden;
+}
+
+:where(.onboarding-container, .onboarding-banner) .onboarding-progress-container[role="progressbar"]::before {
+  content: attr(aria-label);
+  position: absolute;
+  left: -10000px;
+}
+
+/* Enhanced step indicators */
+:where(.onboarding-container) .step-marker[aria-current="step"] {
+  position: relative;
+}
+
+:where(.onboarding-container) .step-marker[aria-current="step"]::after {
+  content: '';
+  position: absolute;
+  top: -0.25rem;
+  left: -0.25rem;
+  right: -0.25rem;
+  bottom: -0.25rem;
+  border: 2px solid var(--onboarding-primary);
+  border-radius: 50%;
+  animation: onboarding-pulse-ring 2s infinite;
+}
+
+/* Keyframe names are a single global namespace shared with the host app, so
+   this one is prefixed like the custom properties are. */
+@keyframes onboarding-pulse-ring {
+  0% {
+    transform: scale(1);
+    opacity: 1;
+  }
+  100% {
+    transform: scale(1.2);
+    opacity: 0;
+  }
+}
+
+/* Enhanced tooltip accessibility */
+:where(.onboarding-container) .onboarding-tooltip[role="tooltip"] {
+  /* Ensure tooltips are announced by screen readers */
+  pointer-events: auto;
+}
+
+:where(.onboarding-container) .tooltip-trigger[aria-describedby] {
+  position: relative;
+}
+
+/* Enhanced form styling for accessibility */
+:where(.onboarding-container) fieldset {
+  border: 2px solid var(--onboarding-border);
+  border-radius: 0.5rem;
+  padding: var(--onboarding-space-lg);
+  margin: 0 0 var(--onboarding-space-lg);
+}
+
+:where(.onboarding-container) legend {
+  font-weight: 600;
+  color: var(--onboarding-text);
+  padding: 0 var(--onboarding-space-sm);
+}
+
+/* Radio and checkbox groups */
+:where(.onboarding-container) .onboarding-radio-group,
+:where(.onboarding-container) .onboarding-checkbox-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--onboarding-space-sm);
+}
+
+:where(.onboarding-container) .onboarding-radio-option,
+:where(.onboarding-container) .onboarding-checkbox-option {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--onboarding-space-sm);
+  cursor: pointer;
+  padding: var(--onboarding-space-sm);
+  border-radius: 0.375rem;
+  transition: var(--onboarding-transition);
+}
+
+:where(.onboarding-container) .onboarding-radio-option:hover,
+:where(.onboarding-container) .onboarding-checkbox-option:hover {
+  background: var(--onboarding-surface);
+}
+
+:where(.onboarding-container) .onboarding-radio-option:focus-within,
+:where(.onboarding-container) .onboarding-checkbox-option:focus-within {
+  background: var(--onboarding-surface);
+  outline: 2px solid var(--onboarding-primary);
+  outline-offset: 2px;
+}
+
+/* Enhanced table accessibility */
+:where(.onboarding-container) table {
+  border-collapse: collapse;
+  width: 100%;
+}
+
+:where(.onboarding-container) th {
+  text-align: left;
+  font-weight: 600;
+  background: var(--onboarding-surface);
+  padding: var(--onboarding-space-md);
+  border: 1px solid var(--onboarding-border);
+}
+
+:where(.onboarding-container) td {
+  padding: var(--onboarding-space-md);
+  border: 1px solid var(--onboarding-border);
+}
+
+/* Caption styling */
+:where(.onboarding-container) caption {
+  font-weight: 600;
+  margin-bottom: var(--onboarding-space-md);
+  text-align: left;
+}
+
+/* Enhanced link styling */
+:where(.onboarding-container) a:not(.primary-action):not(.secondary-action):not(.skip-action) {
+  color: var(--onboarding-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.125em;
+  transition: var(--onboarding-transition);
+}
+
+:where(.onboarding-container) a:not(.primary-action):not(.secondary-action):not(.skip-action):hover {
+  color: var(--onboarding-primary-hover);
+  text-decoration-thickness: 2px;
+}
+
+:where(.onboarding-container) a:not(.primary-action):not(.secondary-action):not(.skip-action):focus-visible {
+  outline: 2px solid var(--onboarding-primary);
+  outline-offset: 0.125em;
+  border-radius: 0.125rem;
+}
+
+/* High contrast mode enhancements.
+   The :root block only reassigns --onboarding-* custom properties, which
+   nothing outside this gem reads, so it stays unscoped. */
+@media (prefers-contrast: high) {
+  :root {
+    --onboarding-border: #000000;
+    --onboarding-text-muted: #000000;
+  }
+
+  .onboarding-container {
+    background: #ffffff;
+    color: #000000;
+  }
+
+  :where(.onboarding-container) .primary-action,
+  :where(.onboarding-container) .secondary-action {
+    border-width: 2px;
+    font-weight: 700;
+  }
+
+  :where(.onboarding-container, .onboarding-banner) .onboarding-progress-fill {
+    background: #000000;
+  }
+
+  :where(.onboarding-container) .step-marker {
+    border-width: 3px;
+  }
+
+  :where(.onboarding-container) .onboarding-tooltip {
+    border: 2px solid #000000;
+  }
+}
+
+/* Reduced motion preferences.
+   Scoped to the engine's own markup: honouring prefers-reduced-motion across
+   the whole page is the host application's call, not a mounted engine's. */
+@media (prefers-reduced-motion: reduce) {
+  :where(.onboarding-container, .onboarding-banner),
+  :where(.onboarding-container, .onboarding-banner) *,
+  :where(.onboarding-container, .onboarding-banner) *::before,
+  :where(.onboarding-container, .onboarding-banner) *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  :where(.onboarding-container) .step-marker[aria-current="step"]::after {
+    animation: none;
+  }
+
+  .onboarding-container[data-step-changed] .step-content {
+    animation: none;
+  }
+}
+
+/* Enhanced color contrast for dark mode - --onboarding-* properties only. */
+@media (prefers-color-scheme: dark) and (prefers-contrast: high) {
+  :root {
+    --onboarding-background: #000000;
+    --onboarding-text: #ffffff;
+    --onboarding-border: #ffffff;
+    --onboarding-surface: #1a1a1a;
+  }
+}
+
+/* Print accessibility */
+@media print {
+  .onboarding-skip-link,
+  .onboarding-live-region,
+  .onboarding-sr-only {
+    display: none;
+  }
+
+  :where(.onboarding-container) a {
+    color: #000000 !important;
+    text-decoration: underline !important;
+  }
+
+  :where(.onboarding-container) .primary-action,
+  :where(.onboarding-container) .secondary-action {
+    border: 2px solid #000000 !important;
+    background: transparent !important;
+    color: #000000 !important;
+  }
+}
+
+/* Screen reader improvements for interactive elements */
+:where(.onboarding-container) .interactive-element {
+  position: relative;
+}
+
+:where(.onboarding-container) .interactive-element::before {
+  content: attr(aria-label);
+  position: absolute;
+  left: -10000px;
+  top: auto;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+}
+
+/* Enhanced status messages */
+:where(.onboarding-container) .onboarding-status-message {
+  padding: var(--onboarding-space-md);
+  border-radius: 0.5rem;
+  margin: var(--onboarding-space-md) 0;
+  border: 1px solid;
+}
+
+:where(.onboarding-container) .onboarding-status-message.onboarding-status-success {
+  background: #f0fdf4;
+  border-color: var(--onboarding-success);
+  color: #166534;
+}
+
+:where(.onboarding-container) .onboarding-status-message.onboarding-status-error {
+  background: #fef2f2;
+  border-color: var(--onboarding-danger);
+  color: #dc2626;
+}
+
+:where(.onboarding-container) .onboarding-status-message.onboarding-status-warning {
+  background: #fffbeb;
+  border-color: var(--onboarding-warning);
+  color: #92400e;
+}
+
+:where(.onboarding-container) .onboarding-status-message.onboarding-status-info {
+  background: #eff6ff;
+  border-color: var(--onboarding-primary);
+  color: #1e40af;
+}
+
+/* Keyboard navigation indicators */
+.keyboard-user .onboarding-container :focus {
+  outline: 3px solid var(--onboarding-primary);
+  outline-offset: 2px;
+}
+
+.mouse-user .onboarding-container :focus {
+  outline: none;
+}
+
+/* Enhanced input validation states */
+:where(.onboarding-container) input:invalid,
+:where(.onboarding-container) select:invalid,
+:where(.onboarding-container) textarea:invalid {
+  border-color: var(--onboarding-danger);
+  box-shadow: inset 0 1px 2px rgba(239, 68, 68, 0.1);
+}
+
+:where(.onboarding-container) input:valid:not(:placeholder-shown),
+:where(.onboarding-container) select:valid,
+:where(.onboarding-container) textarea:valid:not(:placeholder-shown) {
+  border-color: var(--onboarding-success);
+}
+
+/* Loading state accessibility */
+:where(.onboarding-container) .loading-announcement {
+  position: absolute;
+  left: -10000px;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+}
+
+:where(.onboarding-container) [aria-busy="true"] {
+  position: relative;
+}
+
+:where(.onboarding-container) [aria-busy="true"]::after {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(255, 255, 255, 0.8);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1;
+}
+
+/* Enhanced dialog/modal accessibility */
+:where(.onboarding-container) [role="dialog"] {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 10000;
+  background: var(--onboarding-background);
+  border: 1px solid var(--onboarding-border);
+  border-radius: 0.75rem;
+  box-shadow: var(--onboarding-shadow-lg);
+  padding: var(--onboarding-space-xl);
+  max-width: 90vw;
+  max-height: 90vh;
+  overflow: auto;
+}
+
+:where(.onboarding-container) .dialog-backdrop {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: rgba(0, 0, 0, 0.5);
+  z-index: 9999;
+}
+
+/* Focus trap for modals */
+:where(.onboarding-container) .focus-trap {
+  outline: none;
+}
+
+/* Enhanced list accessibility */
+:where(.onboarding-container) ul[role="list"],
+:where(.onboarding-container) ol[role="list"] {
+  list-style: none;
+  padding: 0;
+}
+
+:where(.onboarding-container) li[role="listitem"] {
+  padding: var(--onboarding-space-sm) 0;
+  border-bottom: 1px solid var(--onboarding-border);
+}
+
+:where(.onboarding-container) li[role="listitem"]:last-child {
+  border-bottom: none;
+}