@tcn/sb-blackcat-addon

A Storybook addon that provides enhanced accessibility features, layout direction controls, and design system integration for the Blackcat UI component library.

Overview

@tcn/sb-blackcat-addon is a specialized Storybook addon that enhances the development experience for Blackcat UI components. It provides accessibility testing tools, layout direction controls, and design system integration features that help developers build and test components with accessibility and internationalization in mind.

What's Included

Accessibility Features

• Scalar Controls: Adjust component sizes for accessibility testing
• Layout Direction: Test components in LTR and RTL layouts
• Color Customization: Test components with different accent and text colors
• Accessibility Testing: Tools for testing component accessibility

Design System Integration

• Color Palette: Predefined color schemes for consistent testing
• Scalar System: Size scaling for different accessibility needs
• Theme Integration: Seamless integration with Blackcat UI themes
• Component Decorators: Enhanced story presentation and testing

Storybook Enhancements

• Global Controls: Easy access to accessibility and design controls
• Story Decorators: Automatic application of accessibility features
• Preview Configuration: Enhanced story preview with accessibility tools
• Toolbar Integration: Quick access to accessibility controls

Key Features

• Accessibility First: Built-in accessibility testing and controls
• Layout Direction Support: Full LTR and RTL layout testing
• Scalar Controls: Size adjustment for accessibility compliance
• Color Customization: Flexible color scheme testing
• Storybook Integration: Seamless integration with Storybook
• Design System Support: Full integration with Blackcat UI components
• Performance Optimized: Efficient addon with minimal overhead

Usage

Basic Installation

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  // ... other config
  addons: [
    '@tcn/sb-blackcat-addon',
    // ... other addons
  ],
};

export default config;

Preview Configuration

// .storybook/preview.ts
import { preview } from '@tcn/sb-blackcat-addon/preview';

export default preview;

Using Accessibility Controls

// In your Storybook stories
export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    // Enable specific addon features
    blackcat: {
      enableScalar: true,
      enableDirection: true,
    },
  },
};

export const Primary = {
  args: {
    children: 'Primary Button',
    hierarchy: 'primary',
  },
};

Custom Color Schemes

// The addon automatically provides these color controls:
// - Accent Color: TCN, Cyan, Blue, Purple, Magenta, Red, Orange, Yellow, Green, Grey, Black, White
// - Text Color: Same color palette for text testing
// - Scalar: 0.75x, 0.875x, 1x, 1.125x, 1.25x
// - Direction: LTR, RTL

Addon Features

Accessibility Scalar

• Size Adjustment: Scale component sizes for accessibility testing
• User Preference Simulation: Test components at different size preferences
• Responsive Testing: Ensure components work at various scales
• Accessibility Compliance: Test WCAG size requirements

Layout Direction

• LTR Support: Test left-to-right layouts
• RTL Support: Test right-to-left layouts
• Component Adaptation: Ensure components work in both directions
• Internationalization: Test components for global markets

Color Customization

• Accent Colors: Test components with different brand colors
• Text Colors: Test readability with various text colors
• Contrast Testing: Ensure proper color contrast ratios
• Theme Testing: Test components across different color schemes

Story Decorators

• Automatic Application: All stories automatically get accessibility features
• Consistent Testing: Uniform accessibility testing across all components
• Enhanced Presentation: Better story presentation with accessibility tools
• Integration: Seamless integration with existing Storybook setup

Design System Integration

The addon automatically integrates with:

• Blackcat UI Components: Full support for all component types
• CSS Custom Properties: Dynamic color and size adjustments
• Theme System: Integration with Blackcat UI themes
• Layout Components: Support for all layout and spacing systems
• Typography: Consistent text sizing and color controls

Accessibility Features

Scalar Controls

• Extra Small: 0.75x scale for testing small text requirements
• Small: 0.875x scale for testing reduced size preferences
• Medium: 1x scale (default) for normal viewing
• Large: 1.125x scale for testing large text preferences
• Extra Large: 1.25x scale for testing maximum accessibility

Layout Direction

• LTR (Left-to-Right): Standard left-to-right layout testing
• RTL (Right-to-Left): Right-to-left layout testing for RTL languages
• Automatic Switching: Easy switching between layout directions
• Component Adaptation: Ensure components work in both directions

Color Testing

• High Contrast: Test components with high contrast color schemes
• Low Vision: Test components for users with low vision
• Color Blindness: Test components for color blind users
• Brand Consistency: Test components across different brand colors

When to Use

Choose @tcn/sb-blackcat-addon when you need:

• Accessibility testing for your components
• Layout direction testing (LTR/RTL)
• Component size scaling for accessibility
• Color scheme testing and validation
• Enhanced Storybook development experience
• Design system integration testing
• Internationalization testing support

Configuration

Enable Features

// .storybook/preview.ts
export const parameters = {
  blackcat: {
    enableScalar: true,      // Enable size scaling controls
    enableDirection: true,    // Enable layout direction controls
    enableColors: true,       // Enable color customization
  },
};

Custom Colors

// The addon provides a predefined color palette:
// TCN, Cyan, Blue, Purple, Magenta, Red, Orange, Yellow, Green, Grey, Black, White
// These colors are optimized for accessibility and design system consistency

Story Integration

// Individual stories can override addon settings
export const StoryWithCustomSettings = {
  parameters: {
    blackcat: {
      enableScalar: false,    // Disable scalar for this story
      enableDirection: true,  // Keep direction controls
    },
  },
};

Performance

• Efficient Rendering: Minimal impact on story performance
• Lazy Loading: Controls load only when needed
• Memory Management: Proper cleanup and resource management
• Bundle Optimization: Tree-shakeable addon features
• Fast Switching: Quick switching between accessibility settings

Browser Support

• Modern Browsers: Full support for modern browsers
• CSS Custom Properties: Leverages modern CSS features
• Responsive Design: Works across all screen sizes
• Touch Support: Optimized for touch devices
• Accessibility: Full accessibility compliance

License

Apache-2.0