Gatzi UI – Configuration & Integration

• Install the UI package: Add @gatzi/ui to your project dependencies (usually via pnpm add @gatzi/ui or npm install @gatzi/ui).
• Import the CSS: In your app's globals.css, import the base styles from the UI package. You can either:
  • Directly import: @import '@gatzi/ui/globals.css';
  • Or copy and extend the CSS in your own globals.css for full control.
• Extend or override tokens: You can override color tokens, fonts, or any CSS variable in your project's :root or .dark selectors to match your brand.
• Extend Tailwind config: Import and merge the Tailwind config from @gatzi/ui into your project's tailwind.config.js to ensure all custom utilities and tokens are available.

Projects under app/ are set up to consume the shared UI package from packages/ui. This ensures all applications use the same design tokens, components, and configuration, promoting consistency and reducing duplication.

• Each app should import globals.css from the UI package or extend it in their own globals.css.
• Tailwind config should be extended to include the UI package's configuration and paths.
• All shared components (atoms, molecules, etc.) are imported from @ui/ aliases.

• You can override any CSS variable (token) in your project's :root or .dark selector to change colors, fonts, or other design aspects.
• To add new color utilities or variants, extend globals.css and update your Tailwind config accordingly.
• Custom utility classes (e.g., bg-surface-3/80) can be added or modified in your own CSS and referenced in JSX/TSX with the correct escape sequence.

The UI package provides a base Tailwind configuration with custom tokens, colors, and utilities. To use these in your app:

• Import the UI package's Tailwind config and merge it with your own in tailwind.config.js.
• Ensure the content array includes paths to both your app and the UI package components.
• Restart your dev server after making changes to the config.

To use imports like import { Heading } from '@ui/Headings';, you need to configure your project's module resolution:

• In tsconfig.json (or jsconfig.json), add a paths entry mapping @ui/* to the UI package source directory.
• Example:

  {
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "@repo/ui";: ["../packages/ui/src/*"]
      }
    }
  }

• Ensure your build tool (e.g., Next.js, Vite) also resolves these aliases if needed.
• Use these imports in any file under app/ or src/ to access shared UI components.