webstatus-frontend

name	webstatus-frontend
description	Use when modifying the frontend SPA, working with TypeScript, Lit web components, Shoelace components, or frontend tests.

webstatus-frontend

This skill provides architectural guidance and conventions for the frontend/ directory in webstatus.dev.

Architecture & Technology

• Framework: Built with TypeScript, Lit, and Web Components.
• UI Library: Utilizes Shoelace component library.
• State Management: Uses Lit Context for dependency injection and state management via a service container pattern (<webstatus-services-container>).
• API Interaction: Communicates with the Go backend using TypeScript types generated from the OpenAPI specification (make node-openapi).

Architecture

For a technical breakdown of the Lit component hierarchy, frontend identity flows, and theming patterns, see references/architecture.md.

Guidelines (Do's and Don'ts)

• DO cross-reference all TypeScript and CSS against the official Google TypeScript/HTML/CSS Style Guides. If you are unsure about a specific style rule, DO NOT assume; you MUST ask the user for clarification.
• DO create new UI elements as custom elements extending Lit's LitElement.
• DO leverage Shoelace components for common UI patterns.
• DON'T introduce other UI frameworks like React or Vue.
• DO use Lit Context to access shared services.
• DON'T create new global state management solutions.
• DON'T render the full page layout (header, sidebar, etc.) inside a page component. Page components should focus on route-specific content; webstatus-app provides the shell.
• DON'T add generic class names to shared-css.ts. DO leverage Shadow DOM encapsulation and use composition with slots for reusable layout patterns.
• DO write unit tests for all component logic.
• DO place application-wide service providers within WebstatusServicesContainer to ensure a stable context hierarchy.
• DO use specialized child components (the "Context Bridge" pattern) to consume global context if high-level components (like WebstatusHeader) don't reliably subscribe to context changes due to slotting or complex rendering lifecycles.
• DO use Shoelace semantic CSS variables (e.g., --sl-color-neutral-0) for themeable properties to ensure cross-browser inheritance (Firefox/WebKit) without relying on unsupported selectors like :host-context.
• DON'T directly use Shoelace variables (starting with --sl-) in component stylesheets. DO use custom variables defined in _theme-css.ts (e.g., --color-background, --table-padding) that act as a project-specific abstraction layer.
• DO type routerContext cleanly as createContext<Router | undefined>('router') without referencing AnyObject (Router<AnyObject, AnyObject>), as @vaadin/router v2.0+ removed AnyObject.
• DON'T use // @ts-ignore to silence TypeScript warnings around decorated Lit properties (@provide({context: routerContext})). Properly type the property/context so it passes tsc --noEmit without @typescript-eslint/ban-ts-comment warnings.
• DON'T add redundant as Type[] assertions (@typescript-eslint/no-unnecessary-type-assertion) when assigning API data from openapi-fetch client helpers that already infer the paginated return type.

Testing & Linting

• Test Execution: npm run test -w frontend.
• Linting: Run make node-lint to run ESLint and Prettier for the frontend code, or make lint-fix to attempt auto-fixing. make style-lint is also available for CSS.
• ES Module Testing: When testing components that use ES module exports directly (e.g. Firebase Auth), use a helper property (e.g. credentialGetter) that can be overridden with a Sinon stub.
• Typing: Use generic arguments for querySelector in tests (e.g. querySelector<HTMLSlotElement>(...)) for type safety.

Theming & Inheritance

• Global Classes: The WebstatusThemeService toggles the .sl-theme-dark class on the document.documentElement.
• Inheritance: Shoelace variables (e.g., --sl-color-neutral-0) automatically switch values based on the root class. Our custom theme variables in _theme-css.ts should derive from these semantic Shoelace variables to inherit fixed values across Shadow DOM boundaries consistently.
• Abstraction Layer: Components should exclusively use custom variables from _theme-css.ts. Mapping these to Shoelace variables should only happen in the central theme file. This ensures that a library or color palette change can be managed in one place.
• Avoid Unsupported Selectors: Do not use :host-context for theme overrides as it lacks support in Firefox and WebKit. Use root-inherited variables instead.

Debugging Frontend Tests

If a frontend unit test is timing out or failing mysteriously, Web Test Runner's console output is often unhelpful.

• Watch Mode: Instruct the user to run npm run test:watch -w frontend in their own terminal.
• Visual Debugging: Ask the user to open the provided localhost URL (e.g., http://localhost:8000/) in their web browser and inspect the developer console/DOM to see where the test is getting stuck.
• DON'T arbitrarily increase the timeout in web-test-runner.config.mjs to fix timeout issues. Address the root cause of the hang instead.

Documentation Updates

When making significant architectural changes to the frontend or introducing new state management patterns:

• Trigger the "Updating the Knowledge Base" prompt in GEMINI.md.
• Update docs/ARCHITECTURE.md if the system boundaries change.
• Update these very skills files if you introduce new established patterns.