browser/libs/components/CLAUDE.md

Component Library - Development Guidelines

Storybook Documentation

ALWAYS write Storybook stories for each component:

• Create stories for all visual variants (sizes, colors, states)
• Document common use cases and integration patterns
• Stories serve two purposes:
  1. Visual regression test coverage
  2. Engineering documentation and usage examples

Example structure:

• Default story - Basic usage
• AllVariants story - Visual comparison of all variants
• AllSizes story - Size options
• Use case-specific stories (e.g., InFormContext, WithValidation)

Testing Strategy

Unit test components and services with complex logic:

• Test business logic, calculations, and state management
• Test component interactions and event handling
• Test accessibility attributes and keyboard navigation
• DO NOT test framework behavior (e.g., "Angular renders templates")
• DO NOT test trivial getters or simple property assignments

Focus on:

• Custom validators and form logic
• Conditional rendering logic
• User interaction flows
• Error handling and edge cases

Accessibility Requirements

All components MUST meet WCAG 2.1 Level AA guidelines:

• Provide proper ARIA labels and roles for semantic elements
• Ensure keyboard navigation support
• Maintain minimum color contrast ratios
• Support screen reader announcements for dynamic content
• Test with screen readers during development

Architecture Patterns

Favor composition over inheritance:

• Use content projection (ng-content) for flexibility
• Create small, focused components that compose well together
• Avoid deep component hierarchies
• Prefer directives for reusable behavior

Angular Best Practices

Follow modern Angular patterns:

• Reference the angular-modernization skill for guidance on writing modern Angular code
• Use standalone components
• Prefer signals over RxJS when appropriate (see ADR-0027)
• Use computed() for derived state
• Use effect() sparingly and only for side effects

Naming Conventions

Component selector naming:

• Use bit- prefix for all components in the component library
• Example: bit-button, bit-form-field, bit-icon-tile
• This prefix distinguishes CL components from feature team components

---

• have claude create a component to test the context in this file
• continue to refine context in this file
• have claude try to make new kitchen sink stories using the guidelines for consumers
• continue to refine context in top-level claude.md for consumers

• find and describe usage of a given component or service/function to help with migration tasks. can claude break down the usage of different inputs on a given component? i.e. to help answer questions like "do we still need x variant of this component or can we deprecate it?"

• finding if a component already exists -- when making something new, check if something similar already exists in the CL or can otherwise be accomplished using CL utilities. specify the steps the user would take to find an existing component rather than list all existing components
• skill for figuring out when to load and use angular context