Card anatomy and composition

Live component example

The following semantic HTML uses shipped class names. Interactive application behavior, when required, is provided by the optional JavaScript layer or your application.

<div class="xsh-app xsh-grid xsh-grid-cols-2 xsh-gap-4"><article class="xsh-card xsh-card-interactive"><h3 class="xsh-h3">Projects</h3><p>Adaptive composition</p></article><article class="xsh-card xsh-card-inset"><h3 class="xsh-h3">Activity</h3><p>Inset treatment</p></article></div>

Installation and dependencies

Place dist/xshna.min.css in your site's assets directory. For declarative interactive components, also load dist/xshna.min.js with defer. Individual icon assets are available as SVG files in dist/icons/svg/. Copy the files you use, or deploy the complete icon directory. No Node.js is required on the hosting server.

Public selectors and related configuration

Relevant names or configuration points for this pattern are documented below. Names are composable; not every combination implies a distinct behavior.

Composition, states and responsive behavior

Prefer intrinsic sizing, grid or flexible wrapping. Test minimum viewport widths of 320px, 375px and 768px, and narrow component containers. Long labels must wrap or be truncated intentionally without making essential content unavailable.

For stateful controls, apply the correct native disabled, required, checked or aria attributes. States must be conveyed in text or accessible names, rather than by color alone. Avoid nesting interactive elements inside interactive controls.

Keyboard and screen-reader contract

Use the native semantic HTML element first: a button for an action, a link for navigation, a label associated with each input and a real table for tabular data. Keyboard interaction should preserve visible focus and predictable Tab order. Inspect the rendered UI with actual assistive technology before certifying accessibility.

Themes, density, RTL and motion

Apply data-xsh-theme for light/dark/high-contrast themes, data-xsh-design for a Design DNA personality and data-xsh-density for comfortable or dense presentations. Prefer logical properties so the pattern works when the document direction changes.

Respect prefers-reduced-motion and provide a static presentation for content that would otherwise depend on animation. A personality is a coordinated visual preset, not a guarantee that arbitrary custom colors satisfy WCAG contrast requirements.

Performance and source ownership

This pattern is built from static classes. Use Xshna Extract for application-specific CSS reduction, or ship the complete distribution when simplicity matters more than transfer size. Application data, authentication and persistence remain the responsibility of your application.

Common problems and troubleshooting

If styles are missing, confirm that the CSS URL resolves and the root has class="xsh-app". For missing icons, verify that the self-hosted SVG files exist under dist/icons/svg/ and that image paths resolve correctly. If a dynamic class disappears after extraction, add the class to the Extract safelist and regenerate the bundle.

Version and limitations

This reference applies to Xshna.css 1.0.0-beta.2. Beta APIs may change. See the accompanying release notes and test report for verified browser coverage and known limitations.