Architecture

Architecture

This document covers cross-cutting technical principles that apply to all CORE-OWNED code in the theme.

JavaScript Minimization (REQ-00010)

Zero-JS by default. Every Astro component renders static HTML and CSS unless interactivity is explicitly required and justified.

• Vanilla TypeScript is the interactivity layer for islands. Scripts are loaded only on pages that use them.
• Interactive behavior is added only with a documented reason. “It’s easier” is not sufficient.
• Progressive enhancement: every interactive feature must be functional (or gracefully degraded) without JavaScript. JS enhances; it does not gatekeep.
• Avoid bundling large libraries client-side. If a feature requires a significant JS payload, reconsider whether it belongs in a static theme.

Reduced Motion (REQ-00085)

All CSS animations and transitions must respect prefers-reduced-motion.

/* Correct pattern */
@media (prefers-reduced-motion: no-preference) {
  .animated-element {
    transition: transform 200ms ease;
  }
}

• Never use prefers-reduced-motion: reduce as the condition for adding animation — use no-preference as the condition for enabling it.
• CSS transitions driven by data-state toggles are suppressed by the rule above for motion-sensitive users automatically.
• Animated elements must convey state through non-animated means (e.g., color, text change) — animation is enhancement, not the only signal.

Touch Target Sizes (REQ-00088)

Interactive elements must meet WCAG 2.5.5 minimum touch target size: 44×44 CSS pixels.

• Use --pt-space-* tokens for padding on buttons and links to ensure sufficient tap area.
• Small visual elements (icon-only buttons, checkboxes, radio inputs) must have an invisible hit area expanded to the minimum size, typically via padding or a pseudo-element.
• Do not rely on default browser button sizing — explicitly set padding.

Accessibility Scope (REQ-00090)

Accessibility requirements apply equally to all three surfaces:

1. Theme UI — navigation, footer, modals, interactive components
2. Content UI — article pages, doc pages, marketing landing pages
3. Documentation/requirements UI — this site’s own docs and requirements pages

No surface is exempt. A component that passes axe on a showcase page but fails in a content context is still a violation. The lint:a11y:axe audit covers all showcase surfaces; manual verification covers the rest.