Why Hybrid Astro UI Exists

This project was born from a simple idea: bring to Astro a collection of components and patterns that prioritize static rendering, accessibility, and performance, adding interactivity only when necessary via Web Components. It’s influenced by the spirit of shadcn/ui —composition, clarity, and ergonomics— but built for a hybrid approach tailored to Astro: zero JS by default, opt‑in JS only when it truly adds value.

• This is not an official Astro product.
• It’s an independent, open, and educational project.
• The primary goal is to provide practical value to the Astro ecosystem and learn along the way.

Why this project for Astro

• Astro-first. Many solutions are optimized for SPA runtimes. In Astro, the goal is to ship minimal client-side code and prioritize HTML. We focus on the HTML you send first, not hydration as the starting point.
• Measured interactivity. Most UI can be static and accessible. When state or behavior is needed, small, isolated Web Components are enough—and portable.
• Composition without lock-in. Copy‑adaptable building blocks you can shape to your needs, without tying you to a styling system, a runtime, or rigid conventions.

Inspired by shadcn/ui, with our own direction

• Composition over magic. Favor readable, editable pieces. Nothing hidden.
• Web standards first. We lean on HTML, CSS, and Web Components—native, durable technologies.
• Clear DX, low debt. Types, patterns, and practical examples without over‑engineering or heavy dependencies.

What “hybrid model” means

• Static rendering by default. Astro generates optimized, accessible HTML—improving performance, SEO, and stability.
• Progressive enhancement. If a component needs interaction, add a small, isolated Web Component. Nothing more.
• Minimal payloads. You don’t pay JS for elements that don’t need it—faster loads and smoother UX.

Key benefits

• Real performance. Less JS, less blocking, better LCP/TTI. Interactivity cost is explicit and opt‑in.
• Built-in accessibility. Semantics, roles, and ARIA by design—not as an afterthought.
• Portable and future-proof. Standards-based blocks that work within and beyond Astro.
• Style-agnostic. Use utilities (e.g., Tailwind) or your own tokens/variables—no lock-in.
• Maintainability. Small units, no global runtime, clear and testable surface.
• Developer experience. Typing, predictable patterns, and real examples accelerate adoption without dependency traps.

What this project is not

• Not an official Astro product. Community-driven and open.
• Not a new UI framework. Reusable blocks and patterns based on standards.
• Not a forced replacement. Meant to complement your current stack, not override it.

Design philosophy

• Simplicity. Start with the minimum useful; scale only when needed.
• Transparency. Readable code, no magic—change what you need.
• Style-agnostic. Tokens and utilities, not impositions.
• Accessibility by default. Inclusive by requirement, not as an extra.
• Copy, adapt, learn. Documentation and examples you can use today.

Who it’s for

• Teams and devs who value performance and accessibility over runtime glitter.
• People using Astro who want targeted interactivity without turning everything into a SPA.
• Learners seeking solid UI patterns with web standards and zero lock‑in.

Contribution to the ecosystem

• Realistic examples you can copy and adapt confidently.
• Reusable patterns for common cases (navigation, forms, states, modals, etc.).
• Clear decision criteria: when 100% Astro is enough, when a Web Component makes sense, and why.
• A culture of performance and a11y centered in component design.

Inspiration and acknowledgments

• The shadcn/ui ethos for its emphasis on composition and DX.
• The Astro community and the broader web ecosystem for championing the simple and durable.

---

This project exists to show that, with Astro and web standards, we can build beautiful, fast, and accessible interfaces without shipping more than necessary. If it helps you, use it. If you have ideas, contribute. If you learn something, it’s already worth it.