draw-tools/static/components/AGENT_GUIDE.md

Agent Guide – Front‑End Web Components

Purpose

This guide defines the conventions we follow for building the front‑end of the draw‑tools project using custom HTML web components.

Rules

1. Only custom web components

   • All UI elements must be implemented as native HTML custom elements (<my‑component>).
   • No third‑party UI libraries (e.g., React, Vue) are used.

2. Self‑contained components

   • Each component lives in its own folder under static/components.
   • The folder contains:
     • my-component.html – the HTML template (including <template> tag).
     • my-component.js – the class definition that registers the element.
     • Optional my-component.css – scoped styles imported by the HTML template.
     • README.md – usage instructions and a change‑log for that component.

3. One markdown file per component

   • Inside each component folder, README.md documents:
     • How to import the component in a page.
     • Public attributes, properties, and events.
     • Example markup.
     • A chronological Change Log (date, author, description).

4. Directory structure & naming

   draw-tools/
   └─ static/
      └─ components/
         ├─ my-button/
         │   ├─ my-button.html
         │   ├─ my-button.js
         │   ├─ my-button.css   (optional)
         │   └─ README.md
         ├─ my-card/
         │   └─ … (same pattern)
         └─ AGENT_GUIDE.md      ← this file
   

   • Folder name = kebab‑case version of the component name.
   • File names match the component name (e.g., my-button.html).

5. Component registration

   class MyButton extends HTMLElement {
     constructor() { super(); /* … */ }
     /* lifecycle callbacks, methods, etc. */
   }
   customElements.define('my-button', MyButton);
   

   • The registration must happen once per component (usually at the end of the .js file).

6. Styling

   • Use the Shadow DOM to encapsulate styles.
   • If a separate .css file is present, import it inside the HTML template:

     <style>@import "./my-button.css";</style>
     

7. Documentation updates

   • Whenever a component is added, modified, or removed, update its README.md and the Change Log section at the bottom of the file.
   • Keep this AGENT_GUIDE.md up‑to‑date with any new rules.

Example Component Layout

static/components/my-button/
│
├─ my-button.html      ← <template> with markup and optional <style>
├─ my-button.js        ← class definition + registration
├─ my-button.css       ← (optional) scoped CSS
└─ README.md           ← usage guide & change log

Sample README.md (inside my-button)

# MyButton Component

## Usage
```html
<script type="module" src="/static/components/my-button/my-button.js"></script>
<my-button label="Click me"></my-button>

Attributes / Properties

• label (string) – Text displayed inside the button.

Events

• click – dispatched when the button is pressed.

Change Log

Date	Author	Change
2026‑01‑11	Thomas	Initial creation

---

**Keep this guide** in the repo root of the components folder so any new team member can quickly understand the structure and expectations.