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
Application integrations
Laravel, PHP, WordPress and static HTML. Practical engineering and integration guidance for serious commercial applications.
Static HTML
Copy files from dist/ and use local href and src attributes. The framework has no database or web-server-specific rewrite rules. A static page can omit JS entirely if no interactive components are used.
Laravel Blade
Store files under public/assets/xshna/. Include with <link rel="stylesheet" href="{{ asset('assets/xshna/xshna.min.css') }}"> and <script defer src="{{ asset('assets/xshna/xshna.min.js') }}"></script>. Keep component markup in Blade templates and handle form validation on the server.
PHP templates
The framework works with server-rendered PHP. Escape untrusted user data using htmlspecialchars with ENT_QUOTES and UTF-8; do not treat CSS/JavaScript component helpers as HTML sanitizers.
WordPress
Enqueue CSS and JS using wp_enqueue_style and wp_enqueue_script from your theme or plugin. Do not embed Xshna wholesale on every page unless needed; scope markup to .xsh-app to avoid resets outside your feature.
Frontend frameworks
React/Vue/Svelte can use class names and data attributes but must coordinate state with Xshna methods. Use Xshna.refresh(root) after adding dynamic nodes and Xshna.destroy(document) on full runtime teardown. Avoid allowing both Xshna and your UI framework to manipulate the same subtree without a clear ownership contract.
Shared hosting safety
Never change account-wide home-directory permissions to install Xshna. Upload only the static assets and documentation into the intended directory. Basic CSS/JS delivery does not require chmod changes, custom PHP extensions or a server restart.
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.