docs(fast-html): add AttributeMap documentation to DESIGN.md and README.md

Document the dash-removal convention (foo-bar attribute → foobar property),
leaf-binding eligibility rules, and usage pattern in both files.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: janechu

packages/fast-html/DESIGN.md

@@ -89,6 +89,17 @@ An optional layer that uses the `Schema` to automatically:
 
 Enabled via `TemplateElement.options({ "my-element": { observerMap: "all" } })`.
 
+### `AttributeMap` — automatic `@attr` definitions
+
+An optional layer that uses the `Schema` to automatically register `@attr`-style reactive properties for every **leaf binding** in the template — i.e. simple expressions like `{{foo}}` or `id="{{foo-bar}}"` that have no nested properties, no explicit type, and no child element references.
+
+- The **attribute name** is the binding key exactly as written in the template (e.g. `foo-bar`).
+- The **property name** is derived by removing all dashes (e.g. `foo-bar` → `foobar`).
+- Properties already decorated with `@attr` or `@observable` are left untouched.
+- `FASTElementDefinition.attributeLookup` and `propertyLookup` are patched so `attributeChangedCallback` correctly delegates to the new `AttributeDefinition`.
+
+Enabled via `TemplateElement.options({ "my-element": { attributeMap: "all" } })`.
+
 ### Syntax constants (`syntax.ts`)
 
 All delimiters used by the parser are defined in a single `Syntax` interface and exported as named constants from `syntax.ts`. This makes the syntax pluggable and easy to audit.
@@ -284,6 +295,15 @@ flowchart LR
 
 For a deep dive into the schema structure, context tracking, and proxy system see [SCHEMA_OBSERVER_MAP.md](./SCHEMA_OBSERVER_MAP.md).
 
+### AttributeMap and leaf bindings
+
+When `attributeMap: "all"` is set, `AttributeMap.defineProperties()` is called after parsing. It iterates `Schema.getRootProperties()` and skips any property whose schema entry contains `properties`, `type`, or `anyOf` — keeping only plain leaf bindings. For each leaf:
+
+1. The schema key (e.g. `foo-bar`) is used as the **attribute name**.
+2. Dashes are removed to form the **JS property name** (e.g. `foobar`).
+3. A new `AttributeDefinition` is registered via `Observable.defineProperty`.
+4. `FASTElementDefinition.attributeLookup` and `propertyLookup` are updated so `attributeChangedCallback` can route attribute changes to the correct property.
+
 ---
 
 ## Lifecycle

packages/fast-html/README.md

@@ -217,6 +217,33 @@ if (process.env.NODE_ENV === 'development') {
 }
 ```
 
+#### `attributeMap`
+
+When `attributeMap: "all"` is configured for an element, `@microsoft/fast-html` automatically creates reactive `@attr` properties for every **leaf binding** in the template — simple expressions like `{{foo}}` or `id="{{foo-bar}}"` that have no nested properties.
+
+The **attribute name** is the binding key as written in the template. The **property name** is derived by removing all dashes (`foo-bar` → `foobar`). Properties already decorated with `@attr` or `@observable` on the class are left untouched.
+
+```typescript
+TemplateElement.options({
+    "my-element": {
+        attributeMap: "all",
+    },
+});
+```
+
+With the template:
+
+```html
+<f-template name="my-element">
+    <template>
+        <p>{{greeting}}</p>
+        <p>{{first-name}}</p>
+    </template>
+</f-template>
+```
+
+This registers `greeting` (attribute `greeting`, property `greeting`) and `first-name` (attribute `first-name`, property `firstname`) as `@attr` properties on the element prototype, enabling `setAttribute("first-name", "Jane")` to trigger a template re-render automatically.
+
 ### Syntax
 
 All bindings use a handlebars-like syntax.