GAIA UI

GAIA UI is a collection of accessible, beautifully designed components intended to be copied and pasted directly into your applications. It is built using Radix UI primitives for accessibility and Tailwind CSS for styling, allowing for easy customization to match your brand.

Key features include:

• WCAG compliance: Built on Radix UI primitives.
• Customizable styling: Uses Tailwind CSS.
• Type safety: Built with TypeScript.
• Dark mode: Supported out of the box.
• Responsive design: Mobile-first approach.
• Low overhead: Optimized for performance with minimal bundle size.

The navbar-menu component provides several built-in capabilities:

• Smooth Animations: Uses Framer Motion for enter/exit animations.
• Flexible Grid Layouts: Customize grid layouts per section (e.g., 2-col, 3-col).
• Featured Items: Support for large featured items using backgroundImage and rowSpan.
• Icon Support: Add icons to any menu item.
• External Links: Automatically handles external links with proper attributes.
• Responsive & Accessible: Works on all screen sizes and includes keyboard navigation and ARIA attributes.

GAIA UI is currently in beta. This means the library is actively evolving, and users should expect:

• Frequent updates: New components are added regularly as they are refined in production.
• Potential breaking changes: APIs and component designs are being stabilized, which may lead to breaking changes before the v1.0 release.
• Active development: The library is being continuously improved based on production needs and community feedback.

What to expect in v1.0: Once the library reaches v1.0, it will provide stable semantic versioning, no breaking changes without major version bumps, comprehensive documentation, full TypeScript support, and full accessibility compliance.

The EmailComposeCard is an AI-ready component designed for composing and sending emails within an AI interface. Key features include:

• Chip-based recipient input: Includes built-in validation for email addresses.
• Dual Modes: Supports both "edit" and "view" modes for reviewing content.
• Smart Inputs: Dedicated fields for Subject and Body.
• AI Integration: Designed to work with AI-generated content through the recipientQuery prop and callback hooks for content updates.

GAIA UI components are built using the following technologies:

• React: UI library
• Tailwind CSS: Styling
• Radix UI: Accessible component primitives
• TypeScript: Type safety
• Next.js: React framework

The GAIA UI component library is undergoing a migration to ensure high compatibility with modern development workflows. Key architectural shifts include:

• shadcn/ui Compatibility: Components are being refactored to be compatible with the shadcn CLI and other component registries.
• HeroUI Replacement: The library is moving away from HeroUI in favor of shadcn-compatible components to reduce dependency bloat.
• Reduced Styling Layers: Unnecessary styling, animations, and functionality specific to GAIA's internal needs are being stripped out to minimize bundle size and increase general utility.
• Production-First Design: Components are designed to be 'battle-tested,' meaning they are derived from components used in GAIA's production environments, focusing on accessibility, keyboard navigation, and edge-case handling.

The component fetches metadata directly from the frontend by requesting the URL and extracting information from:

• Open Graph tags (og:title, og:description, og:image)
• Twitter Card tags (twitter:title, twitter:description, twitter:image)
• Standard HTML meta tags and <title> elements
• Favicons and site names

Important: CORS Restrictions Because metadata is fetched directly from the client, you may encounter CORS (Cross-Origin Resource Sharing) restrictions on many websites. For production environments, it is highly recommended to use a backend proxy or a dedicated metadata service to fetch this information.

The WaveSpinner is built with accessibility in mind:

• It uses role="status" automatically.
• You can provide a descriptive label using the aria-label prop.
• It respects the prefers-reduced-motion media query to minimize animations for users who prefer reduced motion.

<WaveSpinner aria-label="Loading user data..." />

The GitHubStarsButton uses GitHub's public API to fetch star counts.

Important Considerations:

• Rate Limiting: Unauthenticated requests to the GitHub API are limited to 60 requests per hour.
• Fetch Lifecycle: The star count is fetched once when the component mounts.
• Cleanup: The component automatically cleans up on unmount to prevent memory leaks.

To ensure your implementation aligns with the GAIA UI design philosophy, avoid the following patterns:

• Library Aesthetics: Avoid the visual language of MUI or Chakra UI (heavy component borders, municipal color palettes, or utility-first aesthetics).
• SaaS Templates: Avoid common SaaS patterns such as gradient hero blobs, gradient-clipped text (background-clip: text), or identical feature-benefit card grids.
• Excessive Chromaticism: Do not introduce colors outside of the defined electric blue and CTA blue roles.

The Message Bubble is a signature component for conversational interfaces, mimicking iOS-style iMessage bubbles with specific tail geometry.

• Received (AI): Uses a zinc-300 fill with black text. The tail exits on the left side. Conveys that the message is from an external source.
• Sent (User): Uses the electric-blue (#00bbff) fill with black text. The tail exits on the right side. This is the most prominent use of color in the system.
• Geometry: Uses a base radius of 20px. For grouped messages, the radius morphs to 5px on the stacking sides, and tails are hidden on non-terminal bubbles to suggest continuity.

The PricingCard component is added to your project using the shadcn CLI by pointing to the Gaia UI registry URL.

npx shadcn@latest add "https://ui.heygaia.io/r/pricing-card"