AW Components Development Guide

Expert guidance for developing and maintaining the AW Components project - a dual-framework web component library (Stencil + Lit) with Three.js/WebGL integration and Contentful CMS compatibility.

Overview

This skill provides context-aware development assistance for the AW Components project, which consists of two parallel web component libraries:

The project includes a unified canvas system with native WebGL shaders, block-based content components, and theme integration.

Project Context

When working on this project, you have access to:

1. **Dual Framework Architecture**: Stencil for base components, Lit for advanced features

2. **Build Tools**: TypeScript, Rollup, Vite, Storybook

3. **Graphics Stack**: Three.js, native WebGL shaders, unified canvas system

4. **Content System**: Block components for Contentful CMS integration

5. **Testing**: Jest, Playwright E2E tests

6. **Development Servers**: Separate dev environments for each framework

Key Instructions

1. Understand Project Structure

Before making changes, familiarize yourself with:

```

aw-components/ # Stencil base components (production ready)

src/components/ # 20+ AW convention components

stencil.config.ts # Stencil build configuration

aw-components-lit/ # Lit advanced components

src/components/ # Lit web components with Three.js

src/lib/ # Unified canvas system, WebGL shaders

vite.config.ts # Vite build configuration

```

2. Follow AW Naming Conventions

All components must follow strict naming patterns:

3. TypeScript Type Safety

Apply these patterns consistently:

```typescript

// Aria labels: string | null (not undefined)

@property({ type: String }) ariaLabel: string | null = null;

// Canvas contexts: null check before use

const ctx = canvas.getContext('2d');

if (!ctx) return;

// Optional chaining for nullable properties

this.element?.classList.add('active');

// State variables: comment out if unused

// @state() private focusedPosition: { x: number; y: number } | null = null;

```

4. Build and Test Workflow

**Stencil Components:**

```bash

cd aw-components

npm run build # Must pass

npm run test # Run tests

npm run storybook # View components

```

**Lit Components:**

```bash

cd aw-components-lit

npm run build # Check for errors

npm run dev # Development server

npm run storybook # Component showcase

```

5. Unified Canvas System

When working with the canvas system:

6. Block Components

When implementing block components:

**Completed:** intro, article, articles, quote, code, list, tags, video, image

**Pending:** embed, images, hotspot-image

7. Code Quality Standards

8. Theme Integration

Configure components via theme system:

```typescript

// Theme configuration

heroBackground: 'canvasPlaneShader' | 'canvasImage' | 'image' | 'cssgradient' | 'none'

heroShaderEffect: 'halftone' | 'noise' | 'pixelation' | 'dithering' | 'none'

```

9. Problem-Solving Approach

When encountering issues:

1. **Check build output**: Run `npm run build` to see all errors

2. **Fix systematically**: Start with critical TypeScript errors

3. **Test incrementally**: Verify fixes don't break other components

4. **Document changes**: Update CLAUDE.md with session progress

5. **Parallel development**: Use agents for Stencil/Lit parity

10. Session Management

Track progress using the todo list format in CLAUDE.md:

Common Tasks

Fix TypeScript Errors

1. Read the component file

2. Identify type mismatches and null handling issues

3. Apply consistent patterns (see section 3)

4. Run build to verify fix

5. Update documentation

Add New Block Component

1. Create Lit version in `aw-components-lit/src/components/blocks/`

2. Launch parallel Stencil implementation agent

3. Add JSDoc documentation

4. Configure Storybook story

5. Update completion count in CLAUDE.md

Optimize WebGL Performance

1. Review shader code for compilation errors

2. Implement geometry caching

3. Reuse uniforms across frames

4. Add performance monitoring

5. Test on target devices

Update Theme Configuration

1. Modify theme types in shared interfaces

2. Update UnifiedCanvas to handle new options

3. Test all background/effect combinations

4. Update Storybook controls

5. Document in theme guide

Production Readiness Checklist

Before marking components production-ready:

Key Files Reference

Notes