mirror of
https://github.com/bitwarden/browser
synced 2026-01-28 15:23:53 +00:00
wip claude context for uif
This commit is contained in:
Vicki League
@@ -97,6 +97,88 @@ enum CipherType {
|
||||
|
||||
Example: `/libs/common/src/vault/enums/cipher-type.ts`
|
||||
|
||||
## Library Dependencies
|
||||
|
||||
**Dependency Rules:**
|
||||
|
||||
- `libs/common` - Core library that CANNOT depend on Angular or platform-specific code
|
||||
- `libs/angular` - Angular-specific utilities that depend on `@angular/*`
|
||||
- `libs/components` - UI component library built with Angular standalone components
|
||||
- Apps can depend on libs, but libs SHOULD NOT depend on apps
|
||||
- Circular dependencies are blocked by ESLint rules in `eslint.config.mjs`
|
||||
|
||||
When adding imports:
|
||||
|
||||
1. Check if the import violates dependency boundaries (ESLint will error)
|
||||
2. Consider if code should be moved to a different library
|
||||
3. Use dependency injection rather than direct imports when possible
|
||||
|
||||
## Testing Patterns
|
||||
|
||||
**Unit Tests:**
|
||||
|
||||
- Place test files next to source files: `foo.service.ts` → `foo.service.spec.ts`
|
||||
- Use `jest-mock-extended` for type-safe mocks
|
||||
- Use `BehaviorSubject` for testing Observable streams
|
||||
- For Angular components, use `ComponentFixture` from `@angular/core/testing`
|
||||
|
||||
**Test Utilities:**
|
||||
|
||||
- `libs/core-test-utils` - Core testing utilities
|
||||
- `libs/state-test-utils` - State management testing utilities
|
||||
- `libs/storage-test-utils` - Storage testing utilities
|
||||
|
||||
**Coverage:**
|
||||
|
||||
- Coverage is collected automatically in CI
|
||||
- Aim for meaningful tests, not just coverage metrics
|
||||
- Don't test framework code (Angular lifecycle, etc.)
|
||||
|
||||
## App-Specific and Lib-Specific Notes
|
||||
|
||||
Apps and libs may have their own CLAUDE.md with specific rules:
|
||||
|
||||
- `apps/browser/CLAUDE.md` - Browser extension (cross-browser compatibility, MV3)
|
||||
- `apps/web/CLAUDE.md` - Web vault (multi-tenant, no extension APIs)
|
||||
- `apps/desktop/CLAUDE.md` - Electron app (main vs renderer process)
|
||||
- `apps/cli/CLAUDE.md` - CLI (JSON output, environment variables)
|
||||
- `libs/components/CLAUDE.md` - Component Library (UI components and shared utilities)
|
||||
|
||||
**Always check the app- or lib-specific CLAUDE.md when working in that directory.**
|
||||
|
||||
## Using the Component Library in Feature Code
|
||||
|
||||
**When building features that consume the Component Library:**
|
||||
|
||||
### Storybook for Custom Components
|
||||
|
||||
- Add Storybook stories for custom components owned by feature teams
|
||||
- Add stories for larger UI compositions that combine multiple CL components
|
||||
- Custom feature team components should **NOT** use the `bit-` prefix
|
||||
- Example: `app-user-settings`, `vault-item-card`, `send-form`
|
||||
|
||||
### Component Library Usage Guidelines
|
||||
|
||||
**DO:**
|
||||
|
||||
- Use existing CL components instead of writing bespoke HTML/CSS
|
||||
- Read the component library documentation in Storybook for usage guidelines and examples
|
||||
- Compose CL components together to build feature-specific UI
|
||||
- Follow the component API contracts (inputs, outputs, content projection)
|
||||
|
||||
**DO NOT:**
|
||||
|
||||
- Add custom CSS classes to override CL component styles
|
||||
- Copy/paste CL component markup to create variations
|
||||
- Modify CL component internals from feature code
|
||||
- Create duplicate components when a CL component already exists
|
||||
|
||||
If a CL component doesn't meet your needs:
|
||||
|
||||
1. Check if composition can solve the problem
|
||||
2. Consult with the UIF team about extending the CL component
|
||||
3. Propose a new component or variant through the proper channels
|
||||
|
||||
## References
|
||||
|
||||
- [Web Clients Architecture](https://contributing.bitwarden.com/architecture/clients)
|
||||
|
||||
90
libs/components/CLAUDE.md
Normal file
90
libs/components/CLAUDE.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# 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
|
||||
|
||||
---
|
||||
|
||||
<!-- next steps -->
|
||||
|
||||
- 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
|
||||
|
||||
<!-- other skill/command ideas for UIF-specific usage -->
|
||||
|
||||
- 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?"
|
||||
|
||||
<!-- skill/command ideas for teams to use -->
|
||||
|
||||
- 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
|
||||
Reference in New Issue
Block a user