@birhaus/primitives

Base components for the BIRHAUS design system implementing cognitive load reduction and Spanish-first internationalization.

Installation

npm install @birhaus/primitives

Key Features

• Spanish-first design: All components support labelEs/labelEn and tituloEs/tituloEn patterns
• Cognitive load optimization: Miller's Law (7±2) compliance built-in
• Accessibility by design: WCAG AA+ compliance with semantic HTML
• Undo-over-confirm patterns: No annoying confirmation dialogs
• Performance optimized: Virtual scrolling and optimistic updates
• TypeScript first: Full type safety with strict mode

Components

Core Components

• BirhausButton - Spanish-first buttons with undo patterns
• BirhausInput - Accessible form inputs with cognitive validation
• BirhausCard - Progressive disclosure containers
• BirhausTable - Data tables with virtual scrolling
• BirhausSelect - Dropdowns with Miller's Law compliance

New Components (v0.8.0)

• BirhausSearchableList - Virtual scrolling list with search
• BirhausResourceCard - Progressive disclosure for complex data
• BirhausBadge - Semantic status indicators
• BirhausDataTable - Advanced data management
• BirhausBulkActionBar - Bulk operations with undo support

Layout & Navigation

• BirhausPageLayout - Standard page structure
• BirhausContainer - Consistent spacing containers
• BirhausPageHeader - Page headers with breadcrumbs

Usage

import { BirhausButton, BirhausCard } from '@birhaus/primitives'

function DonationForm() {
  return (
    <BirhausCard
      titleEs="Nueva Donación"
      titleEn="New Donation"
      status="info"
    >
      <BirhausButton
        labelEs="Guardar Donación"
        labelEn="Save Donation"
        variant="primary"
        undoConfig={{
          enabled: true,
          messageEs: "Donación guardada",
          messageEn: "Donation saved"
        }}
        onClick={handleSave}
      />
    </BirhausCard>
  )
}

BIRHAUS Principles

This package implements all core BIRHAUS principles:

1. Spanish-first: Primary labels in Spanish, English as fallback
2. Miller's Law: Maximum 7±2 items in lists, forms, navigation
3. Undo over Confirm: No confirmation dialogs, implement undo instead
4. Progressive Disclosure: Show details on demand
5. Accessibility = Dignity: WCAG AA+ baseline, semantic HTML
6. Performance Constraints: TTI < 2s, FCP < 1s

Real-world Usage

Perfect for:

• Church administration systems (IPU PY Admin)
• Financial management dashboards
• Educational platforms
• Spanish-speaking user interfaces
• Applications requiring high accessibility

API Documentation

All components support:

• Spanish-first labeling (labelEs, labelEn)
• Accessibility props (aria-*, role)
• Consistent sizing (sm, md, lg)
• Theme integration with @birhaus/themes

Testing

Use @birhaus/test-utils for BIRHAUS-specific testing:

import { expectBirhausCompliance } from '@birhaus/test-utils'

test('component follows BIRHAUS principles', async () => {
  render(<BirhausButton labelEs="Guardar" labelEn="Save" />)
  await expectBirhausCompliance(screen.getByRole('button'))
})

Contributing

See the main repository for contribution guidelines.

License

MIT - see LICENSE for details.