dusk-network / dusk-network/duskit

refactor(components): migrate interactive states from BEM modifiers to ARIA attributes and native pseudo-classes

Open
#319 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

need:feedback
Dominant language
JavaScript
Stars
2
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Description
Rationale

Currently, our components manage interactive and behavioral states using custom BEM modifier classes (e.g., .dusk-tab--selected, .dusk-button--pressed). This approach introduces a dangerous duplication of the source of truth. It decouples the visual presentation governed by CSS from the actual functional and semantic state declared in the DOM for assistive technologies (such as screen readers).

To eliminate this synchronization overhead and prevent accessibility drift, we are shifting to a hybrid architectural model:

  • Anatomy & Taxonomy: Governed strictly by BEM conventions (e.g., blocks, elements, and structural variants like .dusk-button--variant--naked).
  • State & Behavior: Governed exclusively by native CSS pseudo-classes (:disabled, :invalid) and standard ARIA attributes ([aria-selected="true"], [aria-expanded="true"]).

By linking our style rules directly to ARIA attributes and native states, the visual interface can never lie about its operational state.

Scope of Work & Component Audit Checklist

We need to audit @duskit/components and migrate the following state patterns from BEM modifiers to semantic DOM attributes:

  1. Button States (Button.css / Button.svelte)
  • Target: Compressed toggles and disabled anchors.
  • Migration: Replace .dusk-button--pressed with [aria-pressed="true"]. Replace .dusk-anchor-button--disabled with [aria-disabled="true"].
  1. Selection States (Tabs, Segmented Controls, Listbox)
  • Target: Actively selected interactive items.
  • Migration: Search for patterns like .dusk-tab--selected or .dusk-list-item--active and refactor the CSS to match [aria-selected="true"].
  1. Expansion States (Accordion, Dropdown, Menu)
  • Target: Visibility toggles for disclosure structures.
  • Migration: Search for classes like .dusk-dropdown--open or .dusk-accordion--expanded and bind the styles directly to [aria-expanded="true"].
  1. Validation States (Input, Select, Textarea)
  • Target: Form controls reflecting validation failures.
  • Migration: Remove custom modifiers like .dusk-input--error or .dusk-input--invalid. Rely on the native :invalid pseudo-class for HTML5 constraints or [aria-invalid="true"] for custom business logic validation.
  1. Activation States (Toggle, Switch)
  • Target: Binary state controls without hidden native inputs.
  • Migration: Eliminate classes such as .dusk-switch--on or .dusk-switch--checked in favor of [aria-checked="true"].
  1. Navigation States (Navigation menus, Link lists)
  • Target: Highlighting the link corresponding to the current location.
  • Migration: Replace semantic markers like .dusk-nav-link--current with the official standard [aria-current="page"] (or applicable token values like step, location).

IMPORTANT: the Table component is using a duskit-table__cell--hidden class instead of an aria attribute. Correct this and check for similar cases.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by auditing @duskit/components, beginning with Button.css and Button.svelte, then inspect the listed selection, expansion, validation, activation, navigation, and Table components for state modifier classes. Replace the specified visual-state selectors with the corresponding ARIA attributes or native pseudo-classes, including the Table hidden-cell case. Done means the audited components use semantic state selectors without the old state modifiers.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
accessibility, frontend
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.