update

2026-01-13 01:38:15 -05:00
parent b67235b93d
commit d9db2a771d
10 changed files with 334 additions and 0 deletions
--- a/static/components/AGENT_GUIDE.md
+++ b/static/components/AGENT_GUIDE.md
@@ -0,0 +1,101 @@
+# 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.