npm package: @folksam/ui-styles
Description: A comprehensive CSS utility library providing responsive breakpoints, typography styles, animations, and layout helpers. Built for modern web applications with performance and developer experience in mind.
Latest version: 0.2.4

# @folksam/ui-styles

A comprehensive CSS utility library providing responsive breakpoints, typography styles, animations, and layout helpers. Built for modern web applications with performance and developer experience in mind.

## Features

✨ **Responsive Utilities**: Mobile-first breakpoint system with consistent naming  
🎨 **Typography Styles**: Pre-built text styles that integrate with design tokens  
⚡ **Performance Optimized**: Zero-runtime CSS utilities with minimal bundle impact  
🎯 **Type Safe**: Full TypeScript support for breakpoints and utility functions  
♿ **Accessibility Helpers**: Screen reader utilities and focus management styles

## Installation

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

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

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

## Quick Start

```tsx
import { mediaQueries, textStyles, srOnlyClass } from '@folksam/ui-styles';
import { css } from '@pigment-css/react';
import { theme } from '@folksam/ui-design-tokens';

// Responsive design with breakpoints
const responsiveContainer = css({
  padding: theme.spacing_medium,

  [mediaQueries.tablet]: {
    padding: theme.spacing_large,
  },

  [mediaQueries.desktop]: {
    padding: theme.spacing_xl,
  },
});

// Pre-built typography styles
const headingStyle = css(textStyles.header_l);

// Accessibility utilities
const visuallyHidden = css(srOnlyClass);
```

## Core Utilities

### 📱 Responsive Breakpoints

Mobile-first breakpoint system with consistent naming:

```tsx
import { mediaQueries } from '@folksam/ui-styles';

const responsiveGrid = css({
  display: 'grid',
  gridTemplateColumns: '1fr',
  gap: theme.spacing_medium,

  // Tablet and up (768px+)
  [mediaQueries.tablet]: {
    gridTemplateColumns: '1fr 1fr',
    gap: theme.spacing_large,
  },

  // Desktop and up (1024px+)
  [mediaQueries.desktop]: {
    gridTemplateColumns: 'repeat(3, 1fr)',
  },

  // Large desktop and up (1280px+)
  [mediaQueries.desktopLarge]: {
    gridTemplateColumns: 'repeat(4, 1fr)',
  },
});
```

### 📝 Typography Styles

Pre-built text styles that integrate seamlessly with design tokens:

```tsx
import { textStyles } from '@folksam/ui-styles';

// Heading styles (largest to smallest)
const heroTitle = css(textStyles.header_xxxl); // Hero/display headings
const pageTitle = css(textStyles.header_xxl); // Page titles
const sectionTitle = css(textStyles.header_xl); // Section headings
const subsectionTitle = css(textStyles.header_l); // Subsection headings
const cardTitle = css(textStyles.header_m); // Card/component titles
const smallTitle = css(textStyles.header_s); // Small headings
const tinyTitle = css(textStyles.header_xs); // Tiny headings

// Body text styles
const bodyLarge = css(textStyles.body_l); // Large body text
const bodyMedium = css(textStyles.body_m); // Default body text
const bodySmall = css(textStyles.body_s); // Small body text

// Emphasis text styles (bold variants)
const emphasisLarge = css(textStyles.emphasis_l); // Large emphasis text
const emphasisMedium = css(textStyles.emphasis_m); // Medium emphasis text
const emphasisSmall = css(textStyles.emphasis_s); // Small emphasis text
```

**Typography Features:**

- 🎯 **Consistent Sizing**: Based on modular scale from design tokens
- 📱 **Responsive**: Font sizes adapt across breakpoints
- ♿ **Accessible**: Proper line heights and contrast ratios
- 🎨 **Customizable**: Easy to override with additional styles

### 🎪 Animation Utilities

Smooth, performant animations and transitions:

```tsx
import {
  slideInKeyframes,
  slideOutKeyframes,
  fadeInKeyframes,
} from '@folksam/ui-styles';

// Slide animations for modals and drawers
const slideInModal = css({
  animation: `${slideInKeyframes} 0.3s ease-out`,
});

const slideOutModal = css({
  animation: `${slideOutKeyframes} 0.3s ease-in`,
});

// Fade animations for tooltips and overlays
const fadeInTooltip = css({
  animation: `${fadeInKeyframes} 0.2s ease-out`,
});

// Custom transition utilities
const smoothTransition = css({
  transition: 'all 0.2s ease-in-out',
});
```

**Animation Features:**

- ⚡ **Performance Optimized**: GPU-accelerated transforms
- 🎭 **Accessible**: Respects `prefers-reduced-motion`
- 🎯 **Purpose-Built**: Animations designed for common UI patterns
- 🎨 **Customizable**: Easy to modify timing and easing

### ♿ Accessibility Utilities

Essential accessibility helpers and utilities:

```tsx
import { srOnlyClass, focusRingStyles } from '@folksam/ui-styles';

// Screen reader only content
const skipLink = css(srOnlyClass);

// Focus management
const customButton = css({
  ...focusRingStyles,
  backgroundColor: theme.color_primary,
  '&:focus-visible': {
    outline: `2px solid ${theme.color_focus}`,
    outlineOffset: '2px',
  },
});

// High contrast support
const highContrastText = css({
  '@media (prefers-contrast: high)': {
    color: theme.text_high_contrast,
    borderColor: theme.border_high_contrast,
  },
});
```

**Accessibility Features:**

- 🔊 **Screen Reader Support**: Proper hiding and announcement utilities
- ⌨️ **Keyboard Navigation**: Focus ring styles and tab management
- 🎯 **High Contrast**: Support for high contrast mode preferences
- 👀 **Reduced Motion**: Animation utilities that respect motion preferences

## Advanced Usage

### Custom Breakpoints

Extend the breakpoint system for specific needs:

```tsx
import { media } from '@folksam/ui-styles';

// Combine breakpoints for specific ranges
const tabletOnly = css({
  [media.tablet]: {
    display: 'block',
  },
  [media.desktop]: {
    display: 'none',
  },
});
```

### Typography Customization

Build on existing text styles:

```tsx
import { textStyles } from '@folksam/ui-styles';

// Extend existing styles
const brandHeading = css({
  ...textStyles.header_l,
  color: theme.color_brand_primary,
  fontWeight: theme.font_weight_bold,
  letterSpacing: theme.letter_spacing_wide,
});

// Create variants
const errorText = css({
  ...textStyles.body_m,
  color: theme.color_error,
  fontWeight: theme.font_weight_medium,
});
```

## Related Packages

- [`@folksam/ui-components`](https://www.npmjs.com/package/@folksam/ui-components) - React component library
- [`@folksam/ui-design-tokens`](https://www.npmjs.com/package/@folksam/ui-design-tokens) - Design system tokens

---

**Built with ❤️ by the Folksam Design System Team**