@andrsgrza/ui-library

A professional, modular React component library built with TypeScript and CSS variables for maximum flexibility and maintainability.

🚀 Quick Start

npm install @andrsgrza/ui-library

import { Button, Modal, Input } from "@andrsgrza/ui-library";
import "@andrsgrza/ui-library/dist/ui-library.css";

function App() {
  return (
    <div>
      <Button variant="primary" size="md">
        Click me!
      </Button>
    </div>
  );
}

📚 Documentation

For Developers

• ARCHITECTURE.md - Complete architecture guide, design principles, and patterns
• CONTRIBUTING.md - How to contribute components and changes
• CSS_VARIABLES.md - Complete reference of all CSS variables
• Component Catalog - Visual showcase of all components

For AI Agents

• AI_AGENT_GUIDE.md - Comprehensive guide for AI coding assistants

Migration & Publishing

• MIGRATION_GUIDE.md - Upgrading between major versions
• PUBLISHING.md - Publishing workflow and checklist

🎯 Core Principles

Regla Alfa (α): CSS Variables Only

All components use CSS variables exclusively. Hardcoded values are prohibited.

/* ✅ CORRECT */
.my-component {
  color: var(--ui-text-primary);
  padding: var(--ui-space-4);
}

/* ❌ INCORRECT */
.my-component {
  color: #333333;
  padding: 16px;
}

Regla Epsilon (ε): Generic Library, Specific Apps

The UI Library provides generic, reusable components. Application-specific features belong in consuming applications.

/* ✅ CORRECT - Generic variant with app theming */
<div className="quiz-theme">
  <Button variant="primary">Start Quiz</Button>
</div>

/* ❌ INCORRECT - App-specific variant in library */
<Button variant="quiz">Start Quiz</Button>

🏗️ Architecture

Modular CSS Structure

Each component has its own CSS file, imported directly in the component:

// Button.tsx
import React from "react";
import "./Button.css";  // Component-specific styles

export default function Button(props) { ... }

Benefits:

• ✅ Tree-shakeable (only load CSS for components you use)
• ✅ Co-located styles (CSS lives next to component)
• ✅ Maintainable (easy to find and modify styles)
• ✅ Scalable (no monolithic CSS file)

Global Variables File

ui-library.css contains only:

• CSS Custom Properties (variables)
• Global resets (html, body)
• Base utility classes (.ui-component-base, etc.)

Does NOT contain: Component-specific styles (those live in component CSS files)

📦 What's Included

Core Components

• Button, IconButton, LinkButton, ButtonBar, ButtonGroup
• ActionButtons, Switch, AuthFormCard
• LoginForm, RegistryForm, FlexibleAuthForm

Form Components

• Input, LabeledInput, LabeledTextarea, NativeSelect
• EditableTitle, FormLayout, FormRow
• QuestionAnswerForm, QuestionAnswerInterface
• MultiCategorySelector, NestedDragAndDropEditor

Data Display

• Accordion, Badge, Pill, PillsGrid, PillSelector
• Dropdown, OptionGrid, DateField, KeyValueList
• AddableList, CollapsibleSection, SelectibleList
• JsonTree, JsonTreeView, ModeSelector
• QuickActionsDropdown, SortFilterControls
• SectionedStepper, SummaryReport, GenericReport
• AutoNextToggle

Layout

• Card, ContentCard, PageLayout, AppLayout
• HeroSection, WelcomePanel, SidebarButtonContainer

Navigation

• TopBar, NavigationMenu, CollapsibleNavigationMenu
• CollapsibleSidebar, UserProfileMenu

Feedback

• Loader, Message, StatusIndicator
• Toast, ToastContainer, InfoBox, InfoTooltip

Overlays

• Modal (with ModalHeader, ModalBody, ModalFooter)
• ConfirmModal

🎨 Theming & Customization

Override CSS Variables

/* In your application's CSS */
:root {
  --ui-primary: #ff6b6b; /* Change primary color */
  --ui-font-primary: "Custom Font"; /* Change font */
  --ui-radius-md: 12px; /* Change border radius */
}

Use className for Custom Styling

<Button className="my-custom-button" variant="primary">
  Custom Styled Button
</Button>

/* In your app's CSS */
.my-custom-button {
  min-width: 200px;
  text-transform: uppercase;
}

Theme-Based Styling

<div className="dark-theme">
  <Button variant="primary">Dark Theme Button</Button>
</div>

.dark-theme {
  --ui-bg-primary: #1a1a1a;
  --ui-text-primary: #ffffff;
  --ui-text-secondary: #a0a0a0;
}

🔧 Development

Setup

git clone <repo-url>
cd ui-library
npm install

Build

npm run build          # Build library

Development Server (Docs)

cd docs
npm install
npm run dev           # Start catalog dev server

Publishing

npm version patch     # Bump version (patch|minor|major)
npm publish          # Publish to NPM

📊 CSS Variables System

The library provides a comprehensive set of CSS variables organized by category:

Colors

--ui-primary, --ui-secondary
--ui-success, --ui-warning, --ui-danger, --ui-info
--ui-text-primary, --ui-text-secondary, --ui-text-inverse
--ui-bg-primary, --ui-bg-secondary, --ui-bg-tertiary

Spacing (8pt Grid System)

--ui-space-1   /* 4px */
--ui-space-2   /* 8px */
--ui-space-3   /* 12px */
--ui-space-4   /* 16px */
/* ... up to space-20 */

Typography

--ui-text-xs, --ui-text-sm, --ui-text-base, --ui-text-lg, --ui-text-xl
--ui-font-primary
--ui-font-normal, --ui-font-medium, --ui-font-semibold, --ui-font-bold

Borders & Radius

--ui-radius-sm, --ui-radius-md, --ui-radius-lg, --ui-radius-pill
--ui-border-width, --ui-border-primary, --ui-border-secondary

Effects

--ui-shadow-sm, --ui-shadow-md, --ui-shadow-lg, --ui-shadow-xl
--ui-transition-fast, --ui-transition-normal, --ui-transition-slow

See CSS_VARIABLES.md for complete reference.

🧪 Usage Examples

Basic Button

import { Button } from "@andrsgrza/ui-library";

<Button variant="primary" size="md" onClick={() => alert("Clicked!")}>
  Click Me
</Button>;

Modal with Form

import {
  Modal,
  ModalHeader,
  ModalBody,
  ModalFooter,
  Button,
  Input,
} from "@andrsgrza/ui-library";

function MyModal({ isOpen, onClose }) {
  return (
    <Modal isOpen={isOpen} onClose={onClose}>
      <ModalHeader>Edit Profile</ModalHeader>
      <ModalBody>
        <Input placeholder="Name" />
        <Input placeholder="Email" type="email" />
      </ModalBody>
      <ModalFooter>
        <Button variant="outline" onClick={onClose}>
          Cancel
        </Button>
        <Button variant="primary" onClick={handleSave}>
          Save
        </Button>
      </ModalFooter>
    </Modal>
  );
}

Themed Components

<div className="quiz-theme">
  <Card>
    <Button variant="primary">Start Quiz</Button>
  </Card>
</div>

.quiz-theme {
  --ui-primary: #0ea5e9;
  --ui-primary-hover: #0284c7;
}

🤝 Contributing

We welcome contributions! Please read:

1. ARCHITECTURE.md - Understand the architecture
2. CONTRIBUTING.md - Follow contribution guidelines
3. AI_AGENT_GUIDE.md - For AI assistants

Quick Contribution Checklist

• Follow Regla Alfa (CSS variables only, no hardcoded values)
• Follow Regla Epsilon (generic library, no app-specific features)
• Component imports its CSS file
• TypeScript types are exported
• Component is added to index.tsx
• Build succeeds (npm run build)
• Documentation updated

📈 Version History

• v1.0.67 - Completed migration to modular CSS architecture
• v1.0.66 - Fixed background color issues, cleaned up legacy compatibility
• v1.0.64 - Refined CollapsibleNavigationMenu styling
• v1.0.50 - Major CSS refactoring and component additions

📄 License

[Your License Here]

🔗 Links

• NPM Package
• GitHub Repository
• Component Catalog

💡 Key Takeaways

1. CSS Variables Only: Never use hardcoded values
2. Modular CSS: Each component has its own CSS file
3. Generic Components: No app-specific features
4. Type-Safe: Full TypeScript support
5. Customizable: Override variables for theming
6. Tree-Shakeable: Import only what you need
7. Documented: Comprehensive guides for developers and AI agents

For detailed information, see ARCHITECTURE.md