Web Components Assistant
Description
Specialized assistant for implementing and maintaining web components in the DWP Hours Tracker frontend. Provides guidance on creating reusable, encapsulated UI components using modern web standards, following MDN Web Components best practices.
Trigger
Activate when users need to:
- Create new custom elements or web components
- Implement Shadow DOM encapsulation
- Handle component lifecycle methods
- Manage component styling and theming
- Work with custom element APIs
- Convert existing UI elements to web components
- Implement component communication patterns
- Prevent memory leaks from event listeners
- Create base component classes for consistency
- Migrate components to use BaseComponent
- Organize component styles in css.ts files
- Implement responsive scaling with --scale-factor
Response Pattern
Follow this structured approach when implementing web components:
Component Analysis: Assess the component's purpose, props, state, and integration needs
CRITICAL: Static Imports Only - Never use
await import()or dynamic imports. All imports must be static at the top level. The build system uses esbuild to create a singleapp.jsbundle loaded by test.html pages.CRITICAL: Declarative Markup Priority - Always prefer declarative template strings returned from
render()over imperative DOM construction (manualinnerHTMLassignment,createElement,appendChild, IIFEs inside template literals). Therender()method should read like a description of what the component displays. Extract complex conditional sections into small helper methods that return partial template strings, keepingrender()itself a clear, top-level declaration of the component's structure.CRITICAL: Named Slots Over Component Embedding - Never create child web components inside a parent's shadow DOM template string. Instead, use
<slot name="...">in the parent's template and let the consumer compose children in light DOM. This keeps components loosely coupled, independently testable, and composable. The parent declares where children go; the consumer decides which children to provide.CSS Organization: Create a separate
css.tsfile with exportedstylestemplate stringDesign Tokens: Use CSS custom properties from
tokens.cssfor consistent themingResponsive Scaling: Use global
--scale-factorvariable for proportional scaling at small screensBase Class Selection: Extend BaseComponent for memory-safe, consistent components
Custom Element Definition: Create class extending BaseComponent with proper naming conventions
Shadow DOM Setup: Automatic shadow root creation via BaseComponent
Lifecycle Methods: Override connectedCallback, disconnectedCallback as needed (BaseComponent handles cleanup)
Template & Styling: Define component template and styles following MDN best practices
CRITICAL: Strongly-Typed Getter/Setter Properties with Attribute Backing - Use ES property getters/setters backed by the
attributescollection for primitive values only (string, number, boolean). The setter writes tosetAttribute(), andattributeChangedCallbackis the single point that callsrequestUpdate()— preventing double renders. The getter reads fromgetAttribute()and parses to the correct type. GuardattributeChangedCallbackwitholdValue === newValueto prevent cycles — this works reliably because primitives serialize to deterministic strings.Complex values (arrays, objects) must NOT use attributes. Use private fields with
get/setaccessors that callrequestUpdate()directly. Reasons:oldValue === newValuestring comparison fails for JSON — semantically identical objects can produce different serializations (key ordering, whitespace)- Serializing/deserializing on every access is wasteful
- Loses type safety (everything becomes
string | null)
// ── Primitives: attribute-backed ── // oldValue === newValue works because primitives serialize deterministically. static get observedAttributes() { return ["month", "year", "readonly"]; } get month(): number { return parseInt(this.getAttribute("month") || "1", 10); } set month(value: number) { this.setAttribute("month", value.toString()); } get readonly(): boolean { return this.getAttribute("readonly") === "true"; } set readonly(value: boolean) { this.setAttribute("readonly", value.toString()); } // Single render trigger for all attribute changes — no cycles attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) { if (oldValue === newValue) return; // ✅ Safe — primitives only this.requestUpdate(); } // ── Complex values: private field, bypasses attributes entirely ── // No JSON serialization, no attribute equality issues. private _ptoEntries: PTOEntry[] = []; get ptoEntries(): PTOEntry[] { return this._ptoEntries; } set ptoEntries(value: PTOEntry[]) { this._ptoEntries = value; this.requestUpdate(); // ✅ Direct — no attributeChangedCallback involved }CRITICAL: View-Model Rendering with Focus Preservation - Component state fields form a view-model.
render()is a pure function of this view-model. After eachrender()/requestUpdate()cycle, focus and input element state (cursor position, selection) must be restored.BaseComponent.renderTemplate()handles focus restore for elements with stableidattributes automatically. For elements identified bydata-*attributes (e.g., calendar days), overrideupdate()to restore focus from the view-model aftersuper.update(). Without focus preservation, re-rendering completely breaks UX (lost cursor position, dropped keyboard navigation).Event Handling: Use event delegation via handleDelegatedClick/handleDelegatedSubmit methods
Data Flow Architecture: Use event-driven data flow - components dispatch events for data requests, parent handles API calls and data injection via methods like setPtoData()
Memory Management: BaseComponent automatically handles event listener cleanup
Unit Testing: Create Vitest tests with happy-dom using seedData for mocking
Integration Testing: Test component in the DWP Hours Tracker context with Playwright E2E tests
Documentation: Update component usage documentation
Component Testing Pattern
When creating web components, follow this testing structure:
Test Files Structure
client/components/[component-name]/
├── index.ts # Component implementation
├── test.html # Manual testing page
├── test.ts # Automated test playground
└── [component-name].test.ts # Vitest unit tests (in tests/components/)
tests/components/
└── [component-name].test.ts # Vitest unit tests with happy-domVitest Unit Tests
Create comprehensive unit tests using Vitest with happy-dom environment:
- Mock API Responses: Use
shared/seedData.tsto provide realistic test data without network calls - Component Isolation: Test component logic, rendering, and event handling in isolation
- Data Injection Pattern: Use component methods (like
setPtoData()) to inject mock data - DOM Testing: Verify rendered output, CSS classes, and element interactions
- Event Testing: Assert that components dispatch correct custom events with proper detail objects
- Never call
render()directly:render()is a pure template method that returns a string — calling it directly is a no-op for BaseComponent subclasses. UserequestUpdate()to trigger re-renders, or use data injection methods (likesetData()) which callrequestUpdate()internally
Example Vitest test structure:
// @vitest-environment happy-dom
import { describe, it, expect } from "vitest";
import { ComponentName } from "../../client/components/[component-name]/index.js";
import { seedDataType } from "../../shared/seedData.js";
describe("ComponentName Component", () => {
it("should render correctly with mock data", () => {
const component = new ComponentName();
component.setData(mockDataFromSeed);
// Assert DOM structure and content
});
});Mocking with Seed Data: Always use shared/seedData.ts for realistic test data. Transform seed data into component-specific formats using data injection methods rather than simulating API calls. See testing-strategy/SKILL.md for detailed guidelines on seed data usage - only "test.ts" files should import seedData.ts directly.
Playwright E2E Tests
Create end-to-end tests using Playwright for integration testing:
- Real API Usage: Tests run against the actual application with real API calls (data provided by parent components)
- Screenshot Testing: Capture component states in various UI configurations
- Full Integration: Test components within the complete application context
- User Interactions: Verify click handlers, form submissions, and navigation
- Visual Regression: Ensure UI consistency across browser updates
Since components use event-driven architecture and don't make direct API calls, Playwright tests focus on:
- Component rendering in different parent contexts (like admin-panel test page)
- Event emission and handling by parent components
- Visual appearance and responsive behavior
- Integration with other UI elements
Example Playwright test:
test("component displays correctly in admin panel", async ({ page }) => {
// Navigate to test page with real data
await page.goto("/components/admin-panel/test.html");
// Take screenshots of different states
await expect(page.locator("component-name")).toHaveScreenshot();
});test.html Pattern
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Component Name Test</title>
<link rel="stylesheet" href="../../styles.css" />
</head>
<body>
<h1>Component Name Test</h1>
<div
id="test-output"
style="display: block; padding: 10px; border: 1px solid var(--color-border); margin: 10px 0; background: var(--color-surface); color: var(--color-text);"
></div>
<component-name id="component-id"></component-name>
<debug-console></debug-console>
<script type="module">
import { componentPlayground } from "/app.js";
componentPlayground();
</script>
</body>
</html>Design Constraints:
- CRITICAL: Static Imports Only -
await import()is strictly forbidden. All imports must be static at the top level of files. The project uses esbuild to create a singleapp.jsartifact loaded bytest.htmlpages. Dynamic imports break the build system and will cause runtime errors. - HTML test files must import
/app.jsto ensure all components are loaded and registered - HTML test files should import and call the
playgroundfunction from the correspondingtest.tsfile when complex test scenarios are needed - For simple component display testing, HTML test files may directly import and instantiate components in the script tag
- HTML test files must NOT contain inline attributes on web components (use script for configuration)
- HTML test files must NOT contain test logic or code beyond minimal imports and component instantiation
- All complex data configuration, test scenarios, and component manipulation should be in the corresponding test.ts file
- This ensures clean separation of concerns while allowing flexibility for simple component testing
- No extra logic goes into test.html pages - keep them simple with just component tags and minimal script for playground functions
- Debug console can be included directly in markup - add
<debug-console></debug-console>to the HTML for debugging output during manual testing
Note on Playground Functions: The componentPlayground function imported from /app.js is an alias defined in client/components/test.ts. Each component's test.ts file exports a playground function that is imported and re-exported with a component-specific name (e.g., ptoCalendar, employeeList) in the main test.ts file. This allows the test.html to call the appropriate playground function for interactive testing.
test.ts Pattern
import { querySingle } from "../test-utils.js";
export function playground() {
console.log("Starting component playground test...");
const component = querySingle<ComponentType>("component-name");
// Test component functionality
component.addEventListener("custom-event", (e: CustomEvent) => {
console.log("Event received:", e.detail);
querySingle("#test-output").textContent =
`Event: ${JSON.stringify(e.detail)}`;
});
// Additional test scenarios...
console.log("Component playground test initialized");
}Integration Steps
- Add component export to
client/components/index.ts - Add playground import/export to
client/components/test.ts - Create test.html following the pattern above
- Create test.ts with component-specific test logic
- Create Vitest unit tests in
tests/components/[component-name].test.ts - Add E2E test in
e2e/component-[name].spec.ts - Update component exports in main test.ts file
Data Flow Patterns
Event-Driven Data Flow
Components should not make direct API calls. Instead, use event-driven architecture:
// In component: dispatch event for data request
this.dispatchEvent(
new CustomEvent("pto-data-request", {
bubbles: true,
detail: { employeeId: this.employeeId },
}),
);
// In parent app: listen for event and handle data fetching
addEventListener("pto-data-request", (e: CustomEvent) => {
this.handlePtoDataRequest(e.detail);
});
// Parent injects data via component method
component.setPtoData(fetchedData);This pattern maintains separation of concerns and makes components more testable.
Component Communication Patterns
- Parent-to-Child: Use strongly-typed ES
get/setproperty accessors. Primitives are backed by attributes (getAttribute/setAttribute); complex values use private fields. Both provide type-safe APIs to callers (e.g.,calendar.month = 3,calendar.ptoEntries = [...]) - Child-to-Parent: Use custom events with detail objects for data requests and state changes
- Sibling Communication: Route through parent component using event bubbling
Composition via Named Slots (Preferred)
Components must never embed other web components by tag name inside their shadow DOM template. Instead, declare named <slot> elements and let consumers compose children in light DOM:
// CORRECT: Parent declares a slot
protected render(): string {
return `
<style>/* ... */</style>
<div class="card">
<h4>Monthly Accrual</h4>
<div class="grid"><!-- grid rows --></div>
<slot name="calendar"></slot> <!-- ✅ Consumer provides the calendar -->
</div>
`;
}
// Consumer composes in light DOM:
// <pto-accrual-card>
// <pto-calendar slot="calendar" month="3" year="2026"></pto-calendar>
// </pto-accrual-card>
// WRONG: Embedding child component in shadow DOM template
protected render(): string {
return `
<div class="card">
<pto-calendar month="3" year="2026"></pto-calendar> <!-- ❌ Tight coupling -->
</div>
`;
}This pattern keeps components independently testable and avoids tight coupling between parent and child shadow DOMs.
Reactive Update Cycle (Lit-Aligned)
BaseComponent follows the Lit reactive update cycle. Understanding this lifecycle is mandatory — violating it causes subtle bugs (silent no-ops, duplicate listeners, stale DOM).
The Update Cycle
Property change or requestUpdate()
│
▼
update() ← Called by the framework. Do NOT call directly.
│
├─ render() ← Pure template function. Returns a string. No side effects.
│
▼
renderTemplate() ← Applies the string to shadowRoot.innerHTML.
│
├─ cleanupEventListeners()
├─ shadowRoot.innerHTML = template
└─ setupEventDelegation()render() Contract
render() is a pure template method. It conforms to the Lit specification:
| Rule | Detail |
|---|---|
| Returns | An HTML template string |
| Side effects | None. Must not modify DOM, dispatch events, or call external APIs |
| Called by | update() only — never by application code, test code, or other components |
| Calling it directly | Returns the string but does NOT apply it to the DOM — a silent no-op |
| To trigger a re-render | Call requestUpdate() — this is the ONLY correct way |
// CORRECT: render() returns a template string, requestUpdate() triggers the cycle
protected render(): string {
return `<div>${this._data}</div>`;
}
setData(data: string) {
this._data = data;
this.requestUpdate(); // ✅ Triggers: update() → render() → renderTemplate()
}
// WRONG: Calling render() directly — return value is discarded, DOM unchanged
component.render(); // ❌ No-op
el.render(); // ❌ No-op in evaluate() blocks
form.render(); // ❌ No-op
this.render(); // ❌ No-op (inside component methods — use requestUpdate())Lifecycle Methods
Following Lit conventions:
| Method | Purpose | Call super? | Override? |
|---|---|---|---|
constructor() |
Initialize state, attach shadow root | Yes (automatic via BaseComponent) | Rarely |
connectedCallback() |
Start tasks, set up external listeners | Yes | When needed |
disconnectedCallback() |
Clean up external listeners | Yes | When needed |
render() |
Return template string | No | Always (abstract) |
requestUpdate() |
Schedule a re-render | No (just call it) | Never |
update() |
Orchestrate render cycle | — | Never |
setupEventDelegation() |
Register event listeners on shadowRoot | Yes | When adding custom event listeners |
handleDelegatedClick() |
Handle click events via delegation | — | When needed |
handleDelegatedSubmit() |
Handle form submit events via delegation | — | When needed |
setupEventDelegation() Contract
Listeners on shadowRoot survive innerHTML replacement (they're on the root node, not child elements). Therefore:
BaseComponentguards withisEventDelegationSetupto prevent duplicates from its own listeners- Subclass overrides MUST add their own guard (e.g.,
_customEventsSetup) to prevent listener accumulation across re-renders - Without this guard, every
requestUpdate()adds duplicate listeners → handler called N times per event
private _customEventsSetup = false;
protected setupEventDelegation() {
super.setupEventDelegation();
if (this._customEventsSetup) return; // ← REQUIRED guard
this._customEventsSetup = true;
this.shadowRoot.addEventListener("my-event", (e) => {
e.stopPropagation();
this.handleCustomEvent(e as CustomEvent);
});
}See the Happy DOM skill for the confirmed listener accumulation bug this pattern prevents.
Base Component Architecture
For consistency and memory leak prevention, all web components should extend the BaseComponent class located in client/components/base-component.ts.
BaseComponent Features
- Automatic Shadow DOM: Creates shadow root in constructor
- Event Delegation: Centralized event handling to prevent memory leaks
- Reactive Updates:
requestUpdate()method for triggering re-renders (the only correct way to update the DOM) - Memory Management: Automatic cleanup of event listeners in
disconnectedCallback - Lifecycle Safety: Proper connection state tracking
Component Implementation Pattern
import { BaseComponent } from "../base-component.js";
import { styles } from "./css.js";
export class MyComponent extends BaseComponent {
private _data: MyData[] = [];
// render() is a PURE TEMPLATE METHOD — returns string, no side effects.
// Prefer flat, declarative markup. Extract conditionals into helper methods
// that return partial template strings rather than embedding IIFEs or deep
// ternary chains.
protected render(): string {
return `
${styles}
<div class="my-component">
${this.renderItems()}
</div>
`;
}
// Helper: returns a declarative template fragment
private renderItems(): string {
if (!this._data.length) return `<div class="empty">No items</div>`;
return this._data.map((item) => `<div>${item.name}</div>`).join("");
}
protected handleDelegatedClick(e: Event): void {
const target = e.target as HTMLElement;
if (target.matches(".action-btn")) {
this.handleAction();
}
}
// Complex data: private field with typed accessor
private _data: MyData[] = [];
get data(): MyData[] {
return this._data;
}
set data(value: MyData[]) {
this._data = value;
this.requestUpdate(); // ✅ Triggers the full update cycle
}
}CSS Extensions
The project provides shared CSS extension libraries in client/css-extensions/. Each extension delivers a constructable stylesheet singleton and an adopt*() helper that safely adds it to a shadow root's adoptedStyleSheets. Import from the facade for convenience:
import { adoptAnimations, adoptToolbar } from "../../css-extensions/index.js";Or import from individual sub-modules for tree-shaking:
import { adoptAnimations } from "../../css-extensions/animations/index.js";
import { adoptToolbar } from "../../css-extensions/toolbar/index.js";Available Extensions
| Extension | Adopt Helper | CSS Classes / Features |
|---|---|---|
| Animations | adoptAnimations(root) |
.anim-fade-in, .anim-slide-in-right, .anim-slide-out-left, .anim-pop, etc. Plus JS helpers: animateSlide(), animateCarousel() |
| Toolbar | adoptToolbar(root) |
.toolbar — flex layout with justify-content: space-around for evenly distributed action buttons |
Usage in Components
Adopt extensions in connectedCallback() so the constructable stylesheet is added to the shadow root once:
import { adoptAnimations, adoptToolbar } from "../../css-extensions/index.js";
export class MyComponent extends BaseComponent {
connectedCallback() {
super.connectedCallback();
adoptAnimations(this.shadowRoot);
adoptToolbar(this.shadowRoot);
}
protected render(): string {
return `
<div class="toolbar">
<button>Action A</button>
<button>Action B</button>
</div>
`;
}
}Adding New Extensions
- Create a new folder under
client/css-extensions/<name>/ - Add
<name>.tswith the CSS source string (usevar()tokens, no hardcoded values) - Add
index.tswith a constructable stylesheet singleton andadopt<Name>()helper - Re-export from
client/css-extensions/index.ts
CSS Organization and Responsive Design
CSS Structure Pattern
All component styles should be defined in a separate css.ts file that exports a styles template string. This pattern provides:
- Separation of Concerns: Logic and styling are in separate files
- Type Safety: CSS variables and classes are checked at compile time
- Reusability: Styles can be imported and used across components
- Maintainability: Easier to modify styles without touching component logic
// css.ts - Component-specific styles
export const styles = `
.component-root {
padding: var(--space-md);
border-radius: var(--border-radius);
}
.component-header {
font-size: var(--font-size-lg);
font-weight: var(--font-weight-semibold);
}
`;// index.ts - Component implementation
import { styles } from "./css.js";
export class MyComponent extends BaseComponent {
protected render(): string {
return `
${styles}
<div class="component-root">
<h2 class="component-header">Title</h2>
</div>
`;
}
}Global Design Tokens
Use CSS custom properties from client/tokens.css for consistent theming:
- Color Tokens:
--color-primary,--color-text,--color-surface, etc. - Typography Tokens:
--font-size-sm,--font-weight-medium, etc. - Spacing Tokens:
--space-sm,--space-md, etc. - Border Tokens:
--border-width,--border-radius, etc.
Responsive Scaling with --scale-factor
Components can use the global --scale-factor CSS variable for proportional scaling at small screen sizes:
- Global Management: Set centrally in
app.tsbased on viewport width - Automatic Updates: Updates on window resize events
- Proportional Scaling:
scale(calc(100vw / 320))provides continuous scaling from 320px baseline - Component Usage: Apply in media queries for small screens
// In css.ts
export const styles = `
@media (max-width: 320px) {
.component-container {
transform: scale(var(--scale-factor));
transform-origin: top left;
}
}
`;This ensures all components scale consistently while maintaining proportions at super small resolutions.
Memory Leak Prevention
Problem: Components that replace innerHTML without cleaning up event listeners cause memory leaks.
Solution: BaseComponent uses event delegation and automatic cleanup:
- Event listeners attached to shadow root (persistent)
cleanupEventListeners()called before re-rendersdisconnectedCallback()ensures cleanup on removal- No orphaned listeners from dynamic DOM replacement
Migration from HTMLElement
Many existing components extend HTMLElement directly and define render() as a method that sets innerHTML. When migrating:
- Change
extends HTMLElementtoextends BaseComponent - Remove manual
attachShadow()calls - Change
render()to return a string instead of settingthis.shadowRoot.innerHTMLdirectly - Replace all
this.render()calls withthis.requestUpdate()— this is the most critical step - Refactor to attribute-backed getter/setter pattern — for primitive properties, use ES
get/setaccessors backed bygetAttribute()/setAttribute(), withattributeChangedCallbackas the singlerequestUpdate()trigger (guarded byoldValue === newValue). For complex properties (arrays, objects), use private fields withget/setaccessors that callrequestUpdate()directly. Remove anysetFoo()methods that duplicate this pattern. - Implement
handleDelegatedClick()andhandleDelegatedSubmit()for events - Remove manual event listener setup/cleanup code
- Add
_customEventsSetupguard if overridingsetupEventDelegation() - Ensure focus/input preservation —
BaseComponent.renderTemplate()handlesid-based focus restore. Fordata-*based focus (e.g., grids, lists), overrideupdate()to restore focus from view-model state aftersuper.update()
Unmigrated components (extending HTMLElement with imperative render()): pto-calendar, pto-request-queue, data-table, confirmation-dialog, prior-year-review, pto-entry-form, report-generator. These call this.render() directly, which works because their render() imperatively sets innerHTML. They will break if migrated to BaseComponent without replacing this.render() → this.requestUpdate(). They also typically use observedAttributes / attributeChangedCallback which should be replaced with setter methods during migration.
Migrated PTO cards (now extending BaseComponent with declarative render()): pto-employee-info-card, pto-summary-card, pto-pto-card, pto-bereavement-card, pto-sick-card, pto-jury-duty-card, pto-accrual-card. Shared CSS lives in utils/pto-card-css.ts (CARD_CSS), shared template helpers in utils/pto-card-helpers.ts (renderCardShell, renderRow, renderBucketBody, etc.). The old PtoSectionCard and SimplePtoBucketCard base classes in utils/pto-card-base.ts are deprecated.
Page-as-Controller Data Flow
Page components that wrap child web components should act as data controllers: they define the structural template (which child elements exist) in render(), and push data into those children via property setters and method calls — never by re-rendering the page's own shadow DOM.
Key Rules
requestUpdate()on a page should only be called when the page's own template structure changes (e.g., initial render inonRouteEnter(), or adding/removing child elements). It must not be called after data mutations (approve, reject, save) that only change the data flowing into existing children.After data mutations, fetch fresh data and push it directly to child components:
// CORRECT: targeted injection — child state preserved const queue = this.shadowRoot.querySelector( "pto-request-queue", ) as PtoRequestQueue; queue.requests = freshRequests; // queue's own setter triggers its internal re-render // WRONG: page re-render — destroys all child state this.requestUpdate(); // calendar expanded state, scroll position, animations lostChild components that need data should dispatch custom events (bubbles + composed); the parent page listens, fetches, and injects results via methods:
// Child dispatches request this.dispatchEvent( new CustomEvent("calendar-data-request", { bubbles: true, composed: true, detail: { employeeId, month }, }), ); // Page handles in setupEventDelegation() this.shadowRoot.addEventListener("calendar-data-request", (evt) => { const { employeeId, month } = (evt as CustomEvent).detail; // fetch data, then inject: queue.setCalendarEntries(employeeId, month, normalized); });
Reference Implementations
AdminMonthlyReviewPage— listens foradmin-monthly-review-requestandcalendar-month-data-request, fetches data, injects viasetEmployeeData()/setPtoEntries()/setMonthPtoEntries()AdminPtoRequestsPage— listens forcalendar-data-request, fetches scoped PTO entries, injects viaqueue.setCalendarEntries(); after approve/reject, setsqueue.requestsdirectly without callingthis.requestUpdate()
Examples
Common queries that should trigger this skill:
- "Create a web component for the PTO calendar"
- "How do I implement Shadow DOM for the employee list?"
- "Convert this HTML template to a web component"
- "Add custom events to the admin panel component"
- "Implement lifecycle methods for the hours tracker widget"
- "Style encapsulation for the PTO status component"
- "Prevent memory leaks in web components"
- "Migrate component to BaseComponent"
- "Fix event listener memory leaks"
- "Organize component styles in css.ts files"
- "Implement responsive scaling with --scale-factor"
- "Use design tokens in component styling"
Additional Context
- Project Integration: Components should integrate with the existing TypeScript build system and follow project naming conventions
- Browser Support: Ensure compatibility with the project's target browsers
- Performance: Follow MDN performance guidelines for web components
- Memory Management: All components must extend BaseComponent to prevent memory leaks from event listeners
- CSS Organization: Use separate
css.tsfiles with exportedstylestemplate strings for maintainable, type-safe styling - Design Tokens: Leverage CSS custom properties from
tokens.cssfor consistent theming across all components - Responsive Scaling: Use the global
--scale-factorvariable for proportional scaling at small screen sizes - Consistency: Use BaseComponent's event delegation and reactive update patterns for all components. Follow the Lit reactive update cycle —
render()is a pure template method;requestUpdate()is the only way to trigger DOM updates - Declarative First: Always prefer declarative template strings over imperative DOM construction.
render()should read as a flat, top-level description of what the component displays. Complex sections should be extracted into helper methods returning template fragments — never use IIFEs, deeply nested ternaries, or manualinnerHTMLassignment in component logic. - Composition Over Embedding: Never embed child web components by tag name inside a parent's shadow DOM template string. Use named
<slot>elements so consumers compose children in light DOM. This ensures loose coupling and independent testability. - Flat Inheritance: Prefer extending
BaseComponentdirectly over deep inheritance chains. Share behavior via exported utility functions and CSS constants in TypeScript files rather than intermediate base classes. - Accessibility: Implement ARIA attributes and keyboard navigation as per MDN accessibility guidelines
- Testing: Components should have both Vitest unit tests (with seedData mocking) and Playwright E2E tests (with screenshot testing)
- Dependencies: Avoid external component libraries; use native web components with BaseComponent for better performance and smaller bundle size
- Related Skills: Works with
task-implementation-assistantfor admin panel tasks,code-review-qafor component quality checks</content> <parameter name="filePath">/home/ca0v/code/ca0v/dwp-hours/.github/skills/web-components-assistant/SKILL.md