101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
# 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. |