# 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**  
   ```js
   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:
     ```html
     <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`)

```markdown
# 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.