webui-code

WebUI: Coding Guidelines

General WebUI Guidelines

• Adhere to the official Chromium WebUI documentation. Read and follow the guidelines in these files:
  • For core architecture, Lit implementation details, and migration guides: docs/webui/webui_using_lit.md
  • For specific style rules, naming conventions, template guidelines, and safety standards: docs/webui/webui_lit_style_guide.md
• Adhering to the Chrome Design System. Reference component specs for relevant components using the chrome-components skill. Ensure code follows the guidelines for each component.
• As much as possible, prefer leverage existing WebUI components rather than creating new, bespoke components. Components are located under ui/webui/resources/cr_elements/ and ui/webui/resources/cr_components/.

Component Implementation

When implementing a new component, create these files.

File 1: <component_name>.ts

The main TypeScript file defining the element class. It must:

1. Extend CrLitElement.
2. Expose the static is getter (returning the kebab-case tag name).
3. Load the CSS and HTML template wrappers:

   import { getCss } from './<component_name>.css.js';
   import { getHtml } from './<component_name>.html.js';
   

Example Boilerplate: component_name.ts

File 2: <component_name>.html.ts

The HTML template containing the Lit markup.

1. Must wrap the template in html literal.
2. Must use slot elements correctly (e.g. slot="title", slot="body", slot="footer").

Example Boilerplate: component_name.html.ts

File 3: <component_name>.css

Stylesheet guidelines:

• Lit Compilation Metadata Headers: It must contain the Lit compilation metadata headers importing shared variables so that the build system can wrap it into a Lit stylesheet module.
• Chromium Stylelint Rules: It must follow the style lint rules for Chromium WebUI (//src/ui/webui/resources/tools/stylelint.config_base.mjs).
• Lint feedback loop: Run Chromium's stylelint script (below) and fix errors. Repeat until there are no more errors.

  python3 ui/webui/resources/tools/stylelint.py --config ui/webui/resources/tools/stylelint.config_base.mjs --in_folder <relative_folder_path> --in_files <file_name>.css --out_file /tmp/stylelint.out
  

• Token Fallback Chaining: Always declare Material 3 dynamic tokens using Chromium's shared fallback variables (var(--color-sys-<token>, var(--cr-fallback-color-<token>))):

  /* Preferred: Dynamic Material 3 token with Chromium fallback */
  background-color: var(--color-sys-surface2, var(--cr-fallback-color-surface2));
  
  /* Anti-pattern: Hardcoded hex fallbacks */
  background-color: var(--color-sys-surface2, #f3f6fc);