Phi
Phi
Accessibility
@dicehub/phiv1.0.0

Accessibility

Build and test accessible interfaces with Phi components.

Component foundations

Phi uses native HTML and Ark UI primitives for many interactive components. These provide a starting point for semantics, keyboard behavior, and focus management. Your application supplies meaningful labels, content, and a logical page structure.

Check the complete interface after you compose components or change styles. Using Phi does not by itself establish WCAG conformance. Use the accessibility notes on each component page for its specific API and behavior.

Labels and errors

Give each control an accessible name. Prefer a visible label for form fields. Placeholder text disappears during input and must not replace a label. See the WAI guide to labeling controls.

Input connects its label, description, and error text to the control. Use the label and description props for this common case:

<script setup>
import { Input } from "@dicehub/phi/components/input";
</script>

<template>
  <Input
    label="Email"
    name="email"
    type="email"
    autocomplete="email"
    description="We will send your receipt here."
    required
  />
</template>

Supply validation results with error. State what went wrong and how to correct it. Phi displays the message and marks the field invalid; your application performs the validation.

<Input
  label="Email"
  type="email"
  default-value="invalid-email"
  error="Enter an email address, such as [email protected]."
/>

When composing a custom field with Field, give the Field and its control the same id. If a control has no visible label, supply aria-label or aria-labelledby.

Name icon buttons by their action and hide decorative icons from assistive technology. A tooltip can provide extra help, but the control still needs its own accessible name.

<script setup>
import { Button } from "@dicehub/phi/components/button";
import { PhTrash } from "@phosphor-icons/vue";
</script>

<template>
  <Button type="button" shape="square" aria-label="Delete file">
    <PhTrash aria-hidden="true" />
  </Button>
</template>

Keyboard and focus

  • Use buttons for actions and links with an href for navigation. Keep the DOM order aligned with the visual reading order.
  • Use Tab and Shift+Tab to move between controls. Composite widgets such as Tabs and Radio use arrow keys within the group.
  • Keep focus indicators visible. Avoid positive tabindex values and CSS that removes outlines without a visible replacement.
  • When you remove a focused item or change the page, move focus to a logical destination. Check customized keyboard handlers for conflicts with the component's own behavior.

Follow the ARIA keyboard interface guidance when building a custom interaction.

Dialogs and overlays

Give a Dialog a Dialog.Title. Use Dialog.Description for a short explanation when needed and provide a visible close or cancel control. The default modal dialog traps focus and restores it on close; check both behaviors in your application.

Set initialFocusEl on Dialog.Root when the first focus target needs to change, such as focusing Cancel in a destructive confirmation. If the trigger is removed after an action, move focus to the next logical control.

Keep essential instructions visible. A Tooltip is for supplementary text; use a Popover or Dialog for interactive content. Test nested overlays with both keyboard and pointer input.

Color and motion

Start with the semantic color tokens, then check the actual foreground and background combinations in each theme. For WCAG AA, normal text requires at least 4.5:1 contrast; large text requires 3:1. See the WCAG contrast guidance for definitions and exceptions.

  • Pair color with text or another visible cue for errors, status, and selected states.
  • Check focus indicators, disabled states, and custom colors in light and dark themes.
  • Respect prefers-reduced-motion in animations you add.
  • Give charts a text summary or data table so the values and meaning are available without color or pointer hover.

Test your interface

  1. Complete the main task using only the keyboard. Check focus order, visible focus, selection keys, and Escape where dismissal is supported.
  2. Use a screen reader, such as NVDA or VoiceOver. Check control names, roles, states, descriptions, and error announcements.
  3. Zoom the browser to 200% and test a narrow viewport. Confirm that content and controls remain readable and usable.
  4. Test light and dark themes, reduced motion, and the browsers your application supports.
  5. Run automated accessibility checks and add browser regressions for failures. Automated checks cannot verify every interaction or the clarity of your content.

The WAI Easy Checks provide an initial manual review. For changes to Phi itself, also run the contribution checks.

Report a problem

Open a GitHub issue with the Phi version, component, reproduction steps, and expected behavior. Include the browser, operating system, and assistive technology and version when relevant.