Gatzi UI Documentation

Gatzi UI is a modern, scalable, and highly customizable design system for building consistent, accessible, and high-performance interfaces in React and Next.js. This documentation provides a comprehensive overview of the system's vision, architecture, and theming capabilities, empowering you to create beautiful and maintainable applications with ease.

Vision

The driving principles and goals behind Gatzi UI.

Gatzi UI was created to solve the challenges of modern web development: design consistency, rapid prototyping, and effortless theming. Our vision is to provide a robust atomic design system that empowers teams to build delightful user experiences, while maintaining flexibility and scalability for any project size.

  • Unify design and code with a single source of truth for tokens and components.
  • Promote accessibility and best practices by default.
  • Enable rapid iteration with utility-first CSS and composable React components.
  • Support dark mode, theming, and full customization via CSS variables and Tailwind.
Vision

Architecture

Modular, atomic, and token-driven structure for maintainability and scalability.

Gatzi UI is built on the principles of atomic design, modularity, and reusability. The system is organized into atoms (basic UI elements), molecules (combinations of atoms), and organisms (complex components), all styled with Tailwind CSS and powered by a flexible token system.

  • Atomic Components: Each UI element is a standalone, reusable React component, designed for composability and clarity.
  • Token-Driven: All colors, spacing, typography, and effects are managed via CSS custom properties (tokens), ensuring global consistency and easy theming.
  • Utility-First Styling: Tailwind CSS is used for rapid prototyping and fine-grained control, with custom utilities for advanced use cases.
  • Dark Mode & Accessibility: Every component and token supports dark mode and is built with accessibility in mind.
Architecture

Themes & Tokens

Colors, surfaces, and full customization for your product.

Theming in Gatzi UI is powered by a comprehensive set of CSS variables (tokens) defined in globals.css. These tokens control every aspect of the design system, from brand colors and surface backgrounds to typography, spacing, and shadows. You can easily override or extend these tokens to match your brand or product requirements.

  • Color Tokens: Primary, secondary, accent, info, success, warning, error, and their variants (50-900), all mapped to CSS variables for light and dark modes.
  • Surface Tokens: Surface-1 to Surface-4 provide layered backgrounds for cards, modals, and UI elements, supporting translucency and elevation.
  • Text Tokens: Primary, secondary, muted, disabled, and light text colors for optimal readability in all themes.
  • Shadow & Radius: Customizable shadows and border radii for consistent depth and shape across the UI.
  • Utility Classes: Use custom classes like bg-surface-3/80, border-surface-2/40, and ring-surface-4/60 for fine-grained control, leveraging the full power of your token system.

Dark mode is fully supported. All tokens automatically adapt to the active theme, ensuring a seamless and accessible experience for all users.

Themes