CogJS - Cognitive-Oriented Web Accessibility Toolkit

cog-hint

cog-hint is a declarative attribute that adds contextual guidance or helper text to form fields and interactive elements. It’s ideal for reducing ambiguity, helping users stay on task, and lowering cognitive load during complex interactions.

What It Does

When added to a label or input container, cog-hint="Your helper text here" displays a non-intrusive tooltip-style hint on focus or idle. It’s especially helpful for neurodivergent users who benefit from extra clarity without overwhelming the interface.

<label cog-hint="Your email before the @ symbol">
  Username:
  <input type="text" name="username">
</label>

How It Works

• Hints are shown when the target element receives focus or when the user pauses
• They disappear automatically on blur or after interaction resumes
• Tooltips are rendered with accessible roles and positioning logic

Styling and Placement

CogJS includes default styles for positioning and appearance, but you can override them using cogConfig or your own CSS.

.cog-hint-bubble {
  background-color: #f9f9f9;
  border: 1px solid #ccc;
  color: #333;
  padding: 0.5rem;
  border-radius: 0.5rem;
  font-size: 0.9rem;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.1);
}

Accessibility Considerations

• Non-Intrusive: Does not interrupt task flow-only appears when needed
• Screen Reader Friendly: Rendered with aria-describedby where appropriate
• Visual Clarity: Contrasts well with backgrounds and remains readable

Testing cog-hint

// Test Checklist
// - Add cog-hint to a form label or input container
// - Tab to the input and confirm the hint appears
// - Ensure the hint is readable and dismisses on blur
// - Confirm it does not block form validation or input

Best Practices for cog-hint

• Be Specific: Write hints that clarify the field’s expected format or purpose
• Use Plain Language: Avoid jargon or overly technical instructions
• Limit Length: Keep hints short and focused to reduce distraction
• Test With Users: Confirm that hints actually help with understanding, not clutter
• Combine With cog-chunk: Use hints in multi-step forms for smoother progression