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
Engineering handbook
Architecture and stable contracts. Practical engineering and integration guidance for serious commercial applications.
Release invariants
Xshna applications are scoped by .xsh-app. Public classes, attributes, keyframes, custom properties, SVG IDs and custom events are namespaced. Style overrides should use CSS custom properties rather than depending on undocumented selector ordering. The runtime must be optional: static pages remain functional without JavaScript.
Build-time versus runtime
Projects consume precompiled dist assets on ordinary static hosting. Framework maintainers may use Python 3 to regenerate fixed utilities, docs, icons and release archives. Do not install Node.js, compile files, or run a background service on customer hosting. CSS supports progressive enhancement for modern browsers.
Cascade and extensibility
Use the declared layers xsh.reset, xsh.tokens, xsh.base, xsh.layout, xsh.components, xsh.motion, xsh.utilities and xsh.overrides. To override a framework rule predictably, create a new unlayered CSS file loaded after xshna.min.css, or add your own cascade layer after the Xshna layers. Avoid !important unless dealing with accessibility exceptions.
Integration example
<link rel="stylesheet" href="/assets/xshna.min.css?v=1.0.0-beta.2">
<link rel="stylesheet" href="/assets/site.css">
<main class="xsh-app" data-xsh-design="precision" data-xsh-theme="light">
<article class="xsh-card">...</article>
</main>
<script defer src="/assets/xshna.min.js?v=1.0.0-beta.2"></script>Library compatibility
Never rely on another framework being globally absent. Do not reset body, h1, button or .container outside .xsh-app. Third-party style collision is still possible when a site uses the reserved xsh- namespace or assigns unusually strong global selectors. Integration tests should exercise the framework next to the host site styles.
Known boundaries
Xshna is a presentation and interaction framework, not a substitute for authentication, authorization, server-side validation, data persistence, sanitization, state management or a payment system. Do not claim that CSS alone can infer document semantics or guarantee accessibility.
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.