@folksam/ui-components

A comprehensive, production-ready React component library built with TypeScript and Pigment CSS. This library provides a complete set of accessible, customizable, and performant UI components following modern design system principles.

Features

✨ Modern Stack: Built with TypeScript, React 19+, and Pigment CSS for zero-runtime CSS-in-JS
🎨 Design System Integration: Seamlessly integrates with @folksam/ui-design-tokens
🎯 Type Safe: Full TypeScript support with comprehensive prop typing
⚡ Performance Optimized: Tree-shakeable exports and minimal bundle impact
📚 Comprehensive Documentation: Extensive examples and API documentation

Installation

# Using npm
npm install @folksam/ui-components @folksam/ui-design-tokens @folksam/ui-styles

# Using pnpm
pnpm add @folksam/ui-components @folksam/ui-design-tokens @folksam/ui-styles

# Using yarn
yarn add @folksam/ui-components @folksam/ui-design-tokens @folksam/ui-styles

Quick Start

import { UiButton, UiForm, UiFormInput, UiModal } from '@folksam/ui-components';
import { globalCssBaseline } from '@folksam/ui-styles';
import '@folksam/ui-design-tokens/css/theme.css';

// This adds font styles and a very aggressive reset
globalCssBaseline();

function App() {
  return (
    <div>
      <UiButton uiVariant="primary" onClick={() => alert('Hello!')}>
        Click me
      </UiButton>

      <UiForm>
        <UiFormInput
          uiLabel="Email address"
          type="email"
          placeholder="Enter your email"
          required
        />
      </UiForm>
    </div>
  );
}

Architecture & Design Principles

Naming Convention

All components follow a consistent naming pattern: Ui{Category!}{Name?}{Specifier?}

// Category-based naming
UiFormInput; // Form category, Input component
UiFormInputRadio; // Form category, Input component, Radio specifier
UiNavigationTabs; // Navigation category, Tabs component
UiTypographyHeading; // Typography category, Heading component

// Exception: When category equals name
UiForm; // Not UiFormForm
UiModal; // Not UiModalModal

Benefits:

• 🔍 Excellent IntelliSense: Type Ui and get categorized autocompletion
• 📁 Clear Organization: Components grouped by category in file structure
• 🎯 Predictable API: Easy to guess component names based on usage
• 🚫 No Conflicts: Unique naming prevents conflicts with other libraries

Prop Naming Convention

All custom props are prefixed with ui to distinguish them from native HTML attributes:

<UiButton
  uiVariant="primary" // Our custom variant prop
  uiSize="large" // Our custom size prop
  type="submit" // Native HTML attribute
  disabled // Native HTML attribute
  className="custom-class" // Standard React prop
>
  Submit Form
</UiButton>

Benefits:

• ✨ Clear Separation: Instantly identify custom vs. native props
• 📚 Better Documentation: API docs clearly show component-specific features
• 🔧 Easier Maintenance: Refactor custom props without affecting native behavior
• 🎯 Enhanced Developer Experience: Autocomplete groups related props together

TypeScript Integration

Full TypeScript support with comprehensive type definitions:

import type { UiButtonProps } from '@folksam/ui-components';

// Strict typing for component props
function MyButton(props: UiButtonProps) {
  return <UiButton {...props}>{children}</UiButton>;
}

// Union types for controlled APIs
type ButtonVariant = 'primary' | 'secondary' | 'destructive' | 'ghost';
type ButtonSize = 'small' | 'medium' | 'large';

Accessibility Standards

• ♿ WCAG 2.1 AA Compliant: All components is actively worked on to meet accessibility guidelines and regulations
• ⌨️ Keyboard Navigation: Full keyboard support with proper focus management
• 🔊 Screen Reader Support: ARIA labels, descriptions, and live regions
• 🎯 Focus Management: Logical tab order and focus trapping in modals
• 🏷️ Semantic HTML: Proper HTML structure and landmark usage

// Accessibility built-in
<UiFormInput
  uiLabel="Password"
  type="password"
  uiDescription="Must be at least 8 characters"
  uiErrorMessage="Password is too short"
  required
  aria-describedby="password-help"
/>

Advanced Usage

Theming & Customization

Components automatically inherit from your design token system:

import { css } from '@pigment-css/react';
import { theme } from '@folksam/ui-design-tokens';

// Custom styling with design tokens
const customButton = css({
  backgroundColor: theme.button_primary_surface,
  borderRadius: theme.radius_l,
  padding: `${theme.spacing_m} ${theme.spacing_l}`,
  '&:hover': {
    backgroundColor: theme.button_primary_surface_hover,
  },
});

<UiButton className={customButton}>Custom Styled Button</UiButton>;

Related Packages

• @folksam/ui-design-tokens - Design system tokens
• @folksam/ui-styles - Utility styles and responsive helpers

Built with ❤️ by the Folksam Design System Team