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
Browser support matrix
Progressive enhancement and verification status. Practical engineering and integration guidance for serious commercial applications.
Baseline targets
Support current evergreen Chrome, Edge, Firefox and Safari. CSS Grid, Flexbox, custom properties and modern selectors are baseline assumptions; media/container queries and native dialogs provide enhanced behavior. Ensure the basic content remains useful when unsupported CSS features are ignored.
Observed verification
The bundled tests exercise Chromium for major components and tools. A passing Chromium run is not evidence of Safari/Firefox compatibility, assistive-technology conformance, iOS keyboard behavior or WCAG certification. Check TEST_REPORT.md for the exact tested environments and cases.
Manual test matrix
Use latest stable Chrome/Edge on Windows, Firefox on Windows/Linux, Safari on macOS and iOS, and Chrome on Android. Test keyboard navigation, focus return on dialogs, dropdown escape, combobox arrow keys, input labels, native validation, zoom to 400%, forced-colors where available, RTL content and touch input.
Failure and fallback behavior
If container queries are unavailable, the layouts should default to stacked and readable content. If the optional JavaScript is absent, native inputs, buttons and ordinary links retain their semantics; enhanced dropdowns/comboboxes/wizards will not be operational. Use server-driven alternatives for core business workflows.
Release blocking defects
Treat loss of keyboard access, unreadable content at supported zoom, application-breaking layout overflow, broken navigation, unsafe DOM injection or incorrect data disclosure as blockers. Defer optional animation refinement and marketing transitions behind user-impacting issues.
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.