XSHNA.CSS 3.0 / PRODUCTION HANDBOOK

Performance and delivery

Budgeting CSS, JS and runtime impact. Practical engineering and integration guidance for serious commercial applications.

V1 BETA / DOCUMENTEDLive variants · API · Accessibility · Responsive guidance

Core-first adoption

Use only xshna-core.css and xshna-components.css when your application does not need utility classes. Add xshna-utilities.css when using utility names. The complete xshna.min.css is the easiest option; optimize later with Extract only when actual page coverage warrants it.

Profiling metrics

Measure critical CSS bytes compressed and uncompressed, JavaScript transfer and parse/execute time, style recalculation, layout shifts, Interaction to Next Paint, Largest Contentful Paint and memory growth in a representative application. Test low-end Android as well as desktop.

Caching

Serve immutable assets from versioned filenames or cache-busted paths. CSS and JS must use matching framework versions. Configure MIME types: text/css for CSS, text/javascript or application/javascript for JS, image/svg+xml for the optional sprite.

Icons

The shipped examples and icon gallery now embed small SVG paths directly to eliminate external sprite lookup failures. The optional xshna-icons.js generates allowlisted inline icons on [data-xsh-icon] placeholders. The sprite remains available for developers using a same-origin HTTP(S) URL.

Validation command

python3 scripts/release.py
python3 -m unittest discover -s tests -v
sha256sum -c SHA256SUMS

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.

REFERENCE CONTRACT

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

ENGINEERING AND INTEGRATION

Implementation details

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.

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.

ACCEPTANCE CHECKLIST

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.