phantom-ui

The engine includes specialized logic for common icon rendering patterns:

• Mask-image Icons: Many design systems use CSS mask-image with a background-color to render icons. phantom-ui detects these at runtime via getComputedStyle and hides them along with other media during the loading state.
• SVG Bounding Boxes: For <svg> elements, the engine captures the outer bounding box of the SVG rather than individual paths or internal shapes.
• Pseudo-elements: The engine can detect and hide icons rendered via ::before or ::after pseudo-elements that use CSS masks.

Use mode="overlay" when you are in a stale-while-revalidate state (refetching data you already have). Unlike the default skeleton mode which hides content, overlay keeps the existing content visible but dimmed while a light glint sweeps over the elements.

• Behavior: Content is dimmed (controlled by --phantom-content-opacity, default 0.5) and becomes non-clickable (pointer-events: none) to prevent users from interacting with stale data.
• Accessibility: The host element automatically sets aria-busy to announce the update.
• Animations: The sweep uses the shimmer animation. If pulse or breathe is selected, the light is held as a steady veil instead of a sweep.
• Note: count and count-gap attributes do not apply in overlay mode.

<phantom-ui loading mode="overlay">
  <div class="grid"><!-- the previous result --></div>
</phantom-ui>

To achieve instant theme updates without component re-renders, pass a var() reference directly into the component's HTML attributes. This keeps the value unresolved until the browser paints, allowing the component to re-resolve the color live whenever the referenced CSS variable changes (e.g., when toggling a .dark class on an ancestor).

<phantom-ui shimmer-color="var(--brand-shimmer)" background-color="var(--brand-bg)">

<style>
:root {
  --brand-shimmer: rgba(0, 0, 0, 0.08);
  --brand-bg: rgba(0, 0, 0, 0.06);
}

.dark {
  --brand-shimmer: rgba(255, 255, 255, 0.3);
  --brand-bg: rgba(255, 255, 255, 0.08);
}
</style>

The following items are not covered by the stability guarantee and may change in minor or patch releases without a major version bump:

• The exact pixel output of generated shimmer blocks (heuristic-based).
• Internal class names used inside the Shadow DOM.
• The structure of the Custom Elements Manifest.
• Behavior in undocumented edge cases.

During the loading state, phantom-ui ensures the application remains accessible and follows best practices for screen readers and keyboard navigation:

• aria-busy: The host component is marked with aria-busy while loading.
• inert attribute: Slotted content is made inert to remove it from the tab order and the accessibility tree. This prevents users from interacting with invisible placeholder elements.
• Smart inert application: To maintain performance and allow for specific interactive areas, phantom-ui only applies inert to the largest subtrees that do not contain a data-shimmer-ignore element. This allows elements marked with data-shimmer-ignore to remain interactive.
• SSR Compatibility: Because inert is applied via JavaScript, during Server-Side Rendering (SSR) before hydration, only the visual hiding (transparency/opacity) applies.

This project uses Qwik with QwikCity for directory-based routing and layouts. The core directory structure is:

• src/routes: Contains the directory-based routing. Pages are defined by index.tsx files, while layout.tsx files provide hierarchical layouts. index.ts files are used to define endpoints.
• src/components: The recommended location for reusable components.
• public: Stores static assets like images.

Starlight projects follow a specific directory structure for content and assets:

• src/content/docs/: The primary location for documentation. Starlight automatically exposes .md or .mdx files in this directory as routes based on their filenames.
• src/assets/: Place images here to embed them in Markdown using relative links.
• public/: Use this directory for static assets that do not need processing, such as favicons.
• astro.config.mjs: The configuration file for the Astro project.
• src/content.config.ts: Configuration for content collections.

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   └── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

Because phantom-ui relies on browser-specific APIs (getBoundingClientRect, ResizeObserver, and customElements) to perform DOM measurements, the package must be imported on the client-side only.

The <phantom-ui> HTML tag is safe to include in server-rendered markup. The browser treats it as an unknown element until hydration occurs, at which point the Web Component activates. This allows content to render normally on the server, which is beneficial for SEO.