Skip to main content

Accessibility, Responsive Design, and Troubleshooting

Thyris UI provides accessible foundations, but production quality still depends on correct consumer composition, content, and state management.

Accessibility Checklist​

Controls​

  • Give every icon-only button an aria-label or equivalent accessible name.
  • Associate every form control with a persistent visible label.
  • Connect help and error text through the form or field composition.
  • Keep disabled and pending states explicit.
  • Preserve visible keyboard focus styles.

Dialogs and Overlays​

  • Include DialogTitle in every dialog.
  • Use DialogDescription when the purpose or consequence is not obvious.
  • Keep close and cancel behavior predictable.
  • Do not nest dialogs.
  • Do not place essential instructions only inside a tooltip.

Status and Data​

  • State status in text; color is supplementary.
  • Use real table headers and an associated heading or caption.
  • Provide chart units and a text summary or table.
  • Make deliberately scrollable interactive regions keyboard reachable and name them when needed.
  • Use links for destinations and buttons for actions.
  • Mark the active sidebar destination and current breadcrumb page.
  • Keep all collapsed navigation controls named.
  • Preserve Radix keyboard and focus behavior rather than replacing it with click-only logic.

Responsive Checklist​

Verify components at narrow mobile, tablet, and desktop widths with:

  • Long labels, identifiers, URLs, and translated content.
  • Browser zoom and increased operating-system text size.
  • Touch input and keyboard input.
  • No hover capability.
  • Tables and charts wider than the viewport.
  • Dialogs with long content and stacked footer actions.
  • Expanded, collapsed, and mobile sidebar states.

Use min-w-0, break-words, flex-wrap, and deliberate overflow containers. Do not remove essential information only to make a narrow layout fit.

Common Problems​

Components Render Without Styling​

Confirm all three requirements:

  1. @thyris/ui/tokens.css is loaded before Tailwind layers.
  2. Tailwind scans the installed package output.
  3. tailwindcss-animate is enabled.

Restart the development process after changing Tailwind content paths.

Semantic Utilities Do Not Exist​

Importing token CSS only defines variables. The consuming Tailwind configuration must map the variables to utilities such as bg-background, text-foreground, bg-card, and ring-ring.

Dark Mode Changes Only Part of the Page​

Check that:

  • darkMode is set to "class".
  • One theme owner toggles dark on a shared ancestor.
  • Application shells and custom components use semantic colors.
  • Literal bg-white, text-black, or gray palette classes are not overriding the theme.
  • Portaled content inherits or receives the active theme class.

React Hook or Context Errors​

Ensure that the consumer resolves one React and React DOM installation compatible with the package peer range. A second React runtime can break hooks, context, Radix components, and React Hook Form.

Import Works Locally but Fails in a Release​

Use only root or documented subpath exports. Imports from src bypass the package contract and can disappear from the built archive.

// Supported
import {Button} from "@thyris/ui"
import {Button} from "@thyris/ui/button"

// Unsupported
import {Button} from "@thyris/ui/src/button"

Pattern Types Do Not Match API Responses​

Create a presentation adapter. Do not weaken types or pass backend models directly into a pattern.

const presentationRows = response.items.map(toProviderPresentation)

This boundary keeps API evolution, formatting, permissions, and product behavior inside the application.

Dialog Content Exceeds the Viewport​

Use ResponsiveDialogContent with ResponsiveDialogHeader, ResponsiveDialogBody, and ResponsiveDialogFooter. Keep scrolling in the body rather than the entire page.

Tables Break Narrow Layouts​

Use the shared Table, which supplies an overflow wrapper, and avoid fixed widths on low-priority columns. Ensure the overflow region remains keyboard usable and essential row identity stays visible.

Upgrade Checklist​

When replacing the installed package version:

  1. Keep @thyris/ui and @thyris/ui-patterns on the same version.
  2. Review both changelogs and migration notes.
  3. Replace the versioned archives according to the internal release process.
  4. Reinstall dependencies without leaving an old package copy in the lockfile or cache.
  5. Run TypeScript checks and the production build.
  6. Verify light and dark themes.
  7. Run keyboard, accessibility, and visual regression checks for affected components.

Public export removals, renamed props, semantic changes, and deprecations require an explicit migration plan. Do not copy individual component source files into a consumer to avoid an upgrade.

Consumer Release Gate​

  • Production TypeScript build passes in strict mode.
  • No unsupported src imports exist.
  • Both themes have readable text and focus contrast.
  • Dialog, menu, select, and sidebar keyboard behavior works.
  • Forms expose labels and errors correctly.
  • Tables and charts remain usable at narrow widths.
  • Essential status and chart meaning is available without color or hover.
  • No product API, route, permission, or credential logic has moved into a shared component.