Semantic structure
Use the documented Xshna classes with semantic HTML rather than replacing native elements unnecessarily.
Compose existing xsh- classes on the appropriate HTML element. Keep content order meaningful when CSS is disabled.
XSHNA.CSS 3.0 / PRODUCTION HANDBOOK
Accessibility acceptance
Keyboard, screen readers and responsive behavior. Practical engineering and integration guidance for serious commercial applications.
Keyboard navigation
Every interactive control must be reachable without a mouse. Test logical tab order, visible focus, Enter/Space activation, Escape to close overlays, focus return after modal close, arrow-key tab/combobox traversal, and no keyboard traps outside intentional modal dialogs.
Screen readers
Test NVDA + Firefox/Chrome on Windows and VoiceOver + Safari on macOS/iOS. Validate announced names, roles, values, status messages, dialog title, form errors, expanded/collapsed states, tables with headers and user-friendly page headings. Test component states, not just default rendering.
Visual reflow
At 320 CSS pixels wide and at 400% zoom, text must remain readable and interactive elements usable without unexpected two-dimensional scrolling, except where genuinely necessary for complex data visualizations. Validate both light and dark themes, high contrast settings, reduced motion and RTL content.
Custom branding
Brand color token conversion selects a primary on-color, but contrast remains the integrator’s responsibility across disabled controls, alerts, links, icons, focus rings and real backgrounds. Check at least WCAG 2.2 AA where that is your target, with human review of content and interaction flow.
Documenting exceptions
Record inaccessible third-party embeds, intentionally dense expert controls and unavoidable horizontal tables as known constraints. Provide alternative views and a remediation plan rather than presenting an unverified accessibility badge.
Release status: Use the acceptance checklist before representing any feature as independently certified or accessible in all browsers. Tests delivered with the package are evidence of only the checks actually performed.
Files, tokens and configuration
| Surface | Source of truth | What to check |
|---|---|---|
dist/xshna.min.css | Compiled framework | Styling and responsive behavior |
dist/xshna.min.js | Optional interactions | Lifecycle, event handling and teardown |
src/css/ | Readable source | Public class names and token definitions |
src/contracts/ | Published component contracts where available | State, configuration and behavioral support |
Implementation details
Interactive behavior
Verify focus order, disabled behavior and descriptive labels for interactive patterns.
Load xshna.min.js only if the documented interaction needs it. Your application remains responsible for data, persistence and business rules.
Responsive and localization
Test narrow containers, long translations and user-defined text sizes.
Test 320px-wide viewports, container-constrained instances, keyboard zoom, longer translations and right-to-left text where relevant.
Theme and customization
Use --xsh-* CSS variables for theme values and data-xsh-design / data-xsh-density on the xsh-app root.
Prefer design tokens over hard-coded overrides so components remain coherent across personalities.
What to verify before shipping
- Confirm every documented class used by the feature exists in the release CSS.
- Navigate controls using Tab, Shift+Tab, Enter, Space and Escape where appropriate.
- Test with reduced motion, high contrast, 200% text zoom and a narrow mobile viewport.
- Verify disabled, loading, empty, error and long-content states where relevant.
- Check actual application behavior independently of the preview: these examples use illustrative data.