Custom Astro components, landing, and directory pages
Apply these rules—alongside the universal standards in ../SKILL.md—when authoring or editing custom Astro components (docs/site/src/components/), site styles (docs/site/src/styles/), marketing/landing pages, or curated directory and overview pages.
Astro component styling and layout hygiene
- Never use
<style is:inline>:<style is:inline>disables Astro's component CSS scoping and leaks rules into the global document, causing regressions across unrelated Starlight pages. Always use standard scoped<style>blocks. - Use CSS container queries instead of viewport media queries: Components rendered inside documentation pages live next to collapsible sidebars of varying widths. Declare
container-type: inline-sizeon the outer wrapper and use@container (min-width: ...)rules rather than@media (min-width: ...)so cards reflow cleanly inside narrow content columns. - Use design system tokens (
src/styles/tokens.css):- Never hardcode font families or ad-hoc hex palettes; use
var(--font-body),var(--font-heading),var(--a2-surface),var(--a2-border),--text-muted-ds, and--text-subtlealongside Starlight variables (--sl-color-*). - Provide explicit light-mode overrides under
:root[data-theme='light']and verify contrast in both dark and light themes.
- Never hardcode font families or ad-hoc hex palettes; use
- Wrap documentation diagrams in
DiagramCard: Any visual architecture or structural component embedded in documentation pages must wrap its markup in<DiagramCard title="..." mermaid={mermaidSpec}>(src/components/docs/common/DiagramCard.astro) sollms-full.txtand assistive technologies receive a clean structural representation. - Visual viewport verification: Inspect rendered components in a browser (or via captured screenshots) across mobile (
375px), tablet, and desktop widths to confirm labels do not overflow containers, badges do not overlap, and interactive controls remain accessible.
Client-side script safety and interactivity
Interactive widgets (theme switchers, interactive comparison sliders, copy-prompt buttons, hero animations, media lightboxes) must handle restricted environments and synthetic test events safely:
- Guard
localStorageandsessionStoragewithtry...catch: Direct storage reads/writes throw aSecurityErrorinside sandboxed iframes and strict privacy modes. When persisting theme changes, synchronize botha2ui-themeandstarlight-themekeys inside atry...catchblock. - Guard pointer capture with
if (e.isTrusted): Before callingel.setPointerCapture(e.pointerId)orel.releasePointerCapture(e.pointerId)in drag/scrub handlers, checkif (e.isTrusted)so syntheticPointerEvents dispatched in automated browser tests do not throwNotFoundError. - Copy-button hygiene:
- Keep single-line copyable shell commands on a single line in the
.astrotemplate; multi-line source indentation inside inline<code>tags can be captured as extra whitespace when users copy text. - Store and
clearTimeoutany active label-reset timer before starting a new one so rapid clicks do not reset the"Copied!"state prematurely.
- Keep single-line copyable shell commands on a single line in the
- Dialog and media lightbox cleanup: When closing a
<dialog>or media modal, clearsrcattributes on<video>/<img>elements to prevent a flash of stale media on reopen, and restore keyboard focus to the trigger element (lastTrigger?.focus()). - Base-path and OS portability in component code:
- Never hardcode root
/path/URLs inside.astroanchor or asset attributes; use relative URLs or prefix routes withimport.meta.env.BASE_URLso components passASTRO_BASEcontainment checks under/preview/and/pr-preview/pr-<N>/. - Fall back to
'https://a2ui.org'when readingimport.meta.env.SITEso generated URLs remain valid in local dev builds. - Use
\r?\nrather than\nwhen splitting template or file strings in component/build scripts so Windows CRLF checkouts do not break builds.
- Never hardcode root
- Clean MDX extraction: Ensure custom components imported into
.mdxpages do not leak raw JSX fragments whenscripts/emit-markdown-bundle.mjsgeneratesllms-full.txt. - Automated tests: When adding nontrivial interactive logic, URL helpers, or build utilities, add unit tests under
docs/site/tests/(executed vianpm --prefix docs/site test).
Landing, overview, and directory pages
- Direct opening sentences on directory and overview pages: Even on curated resource directories or high-level overview pages, avoid meta-openings like "This page lists..." or "Here you will find...". State what the collection or overview provides directly (for example, "Community renderers, agent libraries, and developer tools extend A2UI across additional UI frameworks and runtimes.").
- Pair interactive visuals with sequential prose: When overview pages use interactive comparison matrices or lifecycle visualizations, accompany them with clear prose descriptions of each stage or category so screen readers and coding agents can read the complete content sequentially.
- Verified external links and package claims: Confirm external repository URLs, visual assets, and CLI or package install commands are live and published before listing them on public directory or landing pages.