From 6eca7a90ad39bd02df282ae7d6aaf1e16d1b4212 Mon Sep 17 00:00:00 2001
From: Armaan Gupta <armaang@Armaans-MacBook-Pro.local>
Date: Tue, 2 Jun 2026 15:50:30 +0530
Subject: [PATCH 1/4] added create headless component skills

---
 .claude/skills/create-component.md | 514 +++++++++++++++++++++++++++++
 1 file changed, 514 insertions(+)
 create mode 100644 .claude/skills/create-component.md

diff --git a/.claude/skills/create-component.md b/.claude/skills/create-component.md
new file mode 100644
index 0000000..07f3c0b
--- /dev/null
+++ b/.claude/skills/create-component.md
@@ -0,0 +1,514 @@
+# Skill: create-component
+
+## Trigger
+Use this skill when the user asks to **create a new headless form component** for the `react-vanilla-components` package. They will typically provide a component name and a CRISP JSON (AEM Core Components schema) that describes the component's properties, constraints, and resource type.
+
+If no CRISP JSON is provided, ask for it. If the user does not have one, ask them to describe the component's fields so you can infer the correct mapping.
+
+---
+
+## What this skill produces
+
+1. `packages/react-vanilla-components/src/components/{ComponentName}.tsx` — component source
+2. `packages/react-vanilla-components/__tests__/components/{ComponentName}.test.tsx` — test suite
+3. `src/utils/mappings.ts` — updated with the new component's field type and resource type keys
+4. `src/index.ts` — updated to import and re-export the component
+
+---
+
+## Step 0 — Understand the CRISP JSON before writing any code
+
+Before writing the component, extract and reason about these fields:
+
+| CRISP field | What to derive from it |
+|---|---|
+| `fieldType` | Primary key in `mappings.ts` |
+| `":type"` | Secondary key in `mappings.ts` (resource type string) |
+| `type` + `format` | HTML element type (see table below) |
+| Constraint fields (`minimum`, `maximum`, `minLength`, etc.) | **Do not assume they reach props** — verify against af-core state (see af-core state contract below) |
+| `default` | Becomes `props.value` on first render — check format compatibility with the HTML input |
+| `enum` / `enumNames` | Indicates a select-type component |
+| `items` present | Container component — use `withRuleEnginePanel` instead of `withRuleEngine` |
+| `properties['afs:layout']` | Passed through to `props.layout` by `withRuleEngine` — use as a general-purpose side-channel for data af-core may strip |
+
+### `type` + `format` → HTML element
+
+| `type` | `format` | HTML element / `type` attribute |
+|---|---|---|
+| `string` | _(none)_ | `<input type="text">` |
+| `string` | `date` | `<input type="date">` |
+| `string` | `date-time` | `<input type="datetime-local">` |
+| `string` | `time` | `<input type="time">` |
+| `string` | `email` | `<input type="email">` |
+| `string` | `uri` | `<input type="url">` |
+| `number` / `integer` | _(any)_ | `<input type="number">` |
+| `boolean` | _(any)_ | `<input type="checkbox">` |
+| with `enum`/`enumNames` | _(any)_ | `<select>` (add `multiple` if `isMultiSelect`) |
+| multiline | _(any)_ | `<textarea>` |
+
+Derive the **BEM block name**: `cmp-adaptiveform-{lowercasecomponentname}` (e.g. `RatingInput` → `cmp-adaptiveform-ratinginput`).
+
+Derive the **`data-cmp-is`** value: `adaptiveForm{PascalCaseComponentName}`.
+
+---
+
+## af-core state contract — what actually reaches props
+
+`withRuleEngine` passes the af-core **state snapshot** to the component as props. The state is not a raw copy of the CRISP JSON — af-core shapes it. **Always verify what is actually in state before using a field from props.**
+
+### How to verify
+
+Run a quick node check before writing the component:
+
+```bash
+node -e "
+const {createFormInstance} = require('@aemforms/af-core');
+const form = createFormInstance({items:[/* paste CRISP JSON item here */]});
+console.log(JSON.stringify(form.items[0].getState(), null, 2));
+"
+```
+
+Read the output and confirm which fields are present and what their values look like. Do this especially for constraint fields and default values.
+
+### Known af-core state shaping rules
+
+**`minimum` / `maximum` in state:**
+- af-core only preserves these in state for `type: 'number'`, `type: 'integer'`, and `type: 'string'` with `format: 'date'`.
+- For any other `type`+`format` combination, af-core explicitly clears them from state (`Field.js` line ~148). The validation engine still uses them internally and `constraintMessages` still fires, but the component never sees the raw values.
+- **Impact:** if you need `min`/`max` HTML attributes for a non-numeric, non-date field, the values will not be in `props`. Use the `afs:layout` side-channel (see below).
+
+**`constraintMessages`:** always present in state as-is. af-core sets `props.errorMessage` automatically when a constraint is violated. The component does not handle constraint messages — `FieldWrapper` renders `props.errorMessage`.
+
+**`default` value format:** the CRISP JSON `default` becomes `props.value` on first render. af-core may store it differently from what the HTML input requires (e.g. a string value may have a different date/time separator or include seconds). Always check the actual value in state and normalise if needed.
+
+**`properties` object:** passes through to state unchanged. `withRuleEngine` additionally maps `properties['afs:layout']` → `props.layout` as `{[key: string]: any}`.
+
+**Props not in the `PROPS` TypeScript type:** some state fields exist at runtime but are absent from the `FieldJson` typings. If you need them, access via `(props as any).fieldName`. Do this only when the state check confirms the field exists.
+
+### `afs:layout` as a general side-channel
+
+When a CRISP JSON constraint is cleared by af-core and you still need its value in the component (e.g. for an HTML attribute), the author can duplicate the value into `properties['afs:layout']` under a custom key. `withRuleEngine` maps the entire `afs:layout` object to `props.layout`, so any custom key placed there survives af-core processing intact.
+
+```json
+"properties": {
+  "afs:layout": {
+    "myConstraintValue": "..."
+  }
+}
+```
+
+```tsx
+const myValue = layout?.myConstraintValue;
+```
+
+Name the custom key clearly (e.g. `sliderMin`, `sliderMax`) to distinguish it from standard af-core layout keys.
+
+---
+
+## Step 1 — Create the component file
+
+File: `packages/react-vanilla-components/src/components/{ComponentName}.tsx`
+
+### Base template (adapt per component type)
+
+```tsx
+// *******************************************************************************
+//  * Copyright 2023 Adobe
+//  *
+//  * Licensed under the Apache License, Version 2.0 (the "License");
+//  * you may not use this file except in compliance with the License.
+//  * You may obtain a copy of the License at
+//  *
+//  *     http://www.apache.org/licenses/LICENSE-2.0
+//  *
+//  * Unless required by applicable law or agreed to in writing, software
+//  * distributed under the License is distributed on an "AS IS" BASIS,
+//  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  * See the License for the specific language governing permissions and
+//  * limitations under the License.
+//  *
+//  * BEM markup follows AEM core form components guidelines.
+//  * LINK- https://github.com/adobe/aem-core-forms-components
+//  ******************************************************************************
+
+import React, { useCallback } from 'react';
+import { withRuleEngine } from '../utils/withRuleEngine';
+import { PROPS } from '../utils/type';
+import FieldWrapper from './common/FieldWrapper';
+import { syncAriaDescribedBy } from '../utils/utils';
+
+const {ComponentName} = (props: PROPS) => {
+  const {
+    id,
+    value,
+    label,
+    required,
+    readOnly = false,
+    placeholder,
+    enabled,
+    visible,
+    name,
+    appliedCssClassNames,
+    valid,
+    layout,
+    // destructure additional PROPS-typed fields here (minimum, maximum, minLength, maxLength, pattern, etc.)
+    // for runtime-only state fields not in PROPS typings, use: const x = (props as any).fieldName;
+  } = props;
+
+  // Normalise value if the HTML input format differs from af-core's stored format.
+  // Example: number → ensure it's a string; date-time → replace space separator with T.
+  const finalValue = value === undefined ? '' : value;
+
+  const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    props.dispatchChange(e.target.value);
+  }, [props.dispatchChange]);
+
+  // dispatchBlur: call with no argument for most field types.
+  // Call with the current value (e.target.value) only when the field needs to
+  // re-submit its value on blur (e.g. text-input, date-input). Match the pattern
+  // of the closest existing similar component.
+  const handleBlur = useCallback(() => {
+    props.dispatchBlur();
+  }, [props.dispatchBlur]);
+
+  const handleFocus = useCallback(() => {
+    props.dispatchFocus();
+  }, [props.dispatchFocus]);
+
+  return (
+    <div
+      className={`{bemBlock} {bemBlock}--${value ? 'filled' : 'empty'} ${appliedCssClassNames || ''}`}
+      data-cmp-is="{dataCmpIs}"
+      data-cmp-visible={visible}
+      data-cmp-enabled={enabled}
+      data-cmp-required={required}
+      data-cmp-valid={valid}
+    >
+      <FieldWrapper
+        bemBlock='{bemBlock}'
+        label={label}
+        id={id}
+        tooltip={props.tooltip}
+        description={props.description}
+        isError={props.isError}
+        errorMessage={props.errorMessage}
+      >
+        <input
+          type="{htmlInputType}"
+          id={`${id}-widget`}
+          className='{bemBlock}__widget'
+          title={props.tooltipText || ''}
+          value={finalValue}
+          name={name}
+          required={required}
+          readOnly={readOnly}
+          placeholder={placeholder}
+          disabled={!enabled}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          aria-label={label?.value}
+          aria-invalid={!valid}
+          aria-describedby={syncAriaDescribedBy(id, props.tooltip, props.description, props.errorMessage)}
+          // add constraint HTML attributes derived from state check:
+          // min / max / minLength / maxLength / step / pattern / accept / multiple
+        />
+      </FieldWrapper>
+    </div>
+  );
+};
+
+export default withRuleEngine({ComponentName});
+```
+
+### Adaptation rules by component category
+
+**Text inputs** (`<input type="text/email/url/tel/password">`):
+- `dispatchBlur(event.target.value)` — text inputs re-submit value on blur.
+- Destructure `minLength`, `maxLength`, `pattern` from `props` (all typed in `PROPS`).
+
+**Numeric inputs** (`<input type="number">`):
+- `minimum` and `maximum` are typed as `number` in `PROPS` — destructure directly.
+- Map to `min` / `max` HTML attributes.
+- Include `step` if present.
+
+**Date inputs** (`<input type="date">`):
+- `minimum` / `maximum` are surfaced as strings in state for `format: 'date'`.
+- Map to `min` / `max` HTML attributes.
+
+**Select / options** (components with `enum`/`enumNames`):
+- Render `<select>` with `<option>` per enum value.
+- Use `isMultiSelect` (from props, set by `withRuleEngine`) to conditionally add `multiple`.
+- `handleChange` dispatches `event.target.value`; for multi-select, collect `Array.from(event.target.selectedOptions, o => o.value)`.
+
+**Checkbox / Switch** (`<input type="checkbox">`):
+- `value` is boolean — `handleChange` dispatches `event.target.checked`.
+- State class modifier: `--checked` / `--unchecked`, not `--filled` / `--empty`.
+
+**Textarea** (`<textarea>`):
+- Map `minLength`, `maxLength`, `rows`, `cols` from state/CRISP JSON.
+- `dispatchChange(event.target.value)`.
+
+**Container components** (CRISP JSON has `items`):
+- Use `withRuleEnginePanel` instead of `withRuleEngine`.
+- Accept `PROPS_PANEL` type.
+- Render children via the AEM renderer. Follow `Panel.tsx` or `Accordion/Accordion.tsx` as the pattern.
+
+**Display-only components** (no user input — e.g. `PlainText`, `Image`):
+- Omit all handlers and `FieldWrapper`.
+- Render only the relevant markup using props directly.
+
+**Constraints cleared by af-core** (verify via state check — see af-core contract above):
+- If a constraint the component needs is not in state, read it from `props.layout` using the `afs:layout` side-channel pattern.
+- Name the layout key clearly to distinguish it from standard af-core layout keys.
+
+**Value format mismatch** (verify via state check):
+- If `props.value` does not match the format required by the HTML input, write a pure normalisation helper function and apply it to `finalValue`.
+- Keep the helper small and self-contained next to the component.
+
+---
+
+## Step 2 — Register in `mappings.ts`
+
+File: `packages/react-vanilla-components/src/utils/mappings.ts`
+
+Add an import (maintain alphabetical order):
+```ts
+import {ComponentName} from '../components/{ComponentName}';
+```
+
+Add entries in the `mappings` object:
+```ts
+'{fieldType}': {ComponentName},
+// If CRISP JSON includes a ":type" resource type string:
+'{":type" value}': {ComponentName},
+```
+
+Keep simple `fieldType` keys grouped together; core-components resource-type strings grouped together — match the existing file structure.
+
+---
+
+## Step 3 — Export from `src/index.ts`
+
+File: `packages/react-vanilla-components/src/index.ts`
+
+Add import (maintain alphabetical order):
+```ts
+import {ComponentName} from './components/{ComponentName}';
+```
+
+Add to the `export { ... }` block:
+```ts
+{ComponentName},
+```
+
+---
+
+## Step 4 — Create the test file
+
+File: `packages/react-vanilla-components/__tests__/components/{ComponentName}.test.tsx`
+
+### Core testing rules
+
+**1. Value input — choose the right API by input type**
+
+| Input type | Method | Reason |
+|---|---|---|
+| `text`, `email`, `tel`, `url`, `password` | `userEvent.type(input, value)` | JSDOM simulates keystrokes correctly |
+| `date`, `datetime-local`, `time`, `number`, `range` | `fireEvent.change(input, { target: { value } })` | JSDOM doesn't simulate native picker events; `userEvent.type` produces undefined in model |
+| `checkbox` | `userEvent.click(input)` | Toggles checked state correctly |
+| `select` | `fireEvent.change(select, { target: { value } })` | Most reliable for select elements |
+
+**2. Label/input linking**
+The `FieldWrapper` sets `label.for = input.id = "${id}-widget"`. Assert them directly:
+```tsx
+expect(input.getAttribute('id')).toEqual(label.getAttribute('for'));
+// Do NOT manually append '-widget' to label.for — it is already the full id
+```
+
+**3. Finding inputs that have no placeholder**
+Use `querySelector` with the element type:
+```tsx
+const input = renderResponse.container.querySelector('input[type="text"]') as HTMLInputElement;
+```
+
+**4. Constraint attributes**
+Test constraint HTML attributes by passing the constraint in the field object. Only include constraints that your state check confirmed actually reach props. If a constraint is read from `props.layout`, pass it under `properties['afs:layout']` in the test field object.
+
+**5. Value normalisation**
+If you wrote a normalisation helper in the component, add a dedicated test that passes a raw af-core-style value (as confirmed by the state check) and asserts the HTML input shows the normalised form.
+
+**6. Full CRISP JSON smoke test**
+Always include a `fullField` object that mirrors the complete CRISP JSON exactly as provided, and a test that renders it without errors.
+
+### Test template
+
+```tsx
+/*
+ * Copyright 2023 Adobe, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import {ComponentName} from '../../src/components/{ComponentName}';
+import userEvent from '@testing-library/user-event';
+import { fireEvent } from '@testing-library/react';
+import { renderComponent, DEFAULT_ERROR_MESSAGE } from '../utils';
+import '@testing-library/jest-dom/extend-expect';
+
+// Minimal field — only the properties needed to render the component
+const field = {
+  name: '{fieldName}',
+  label: { value: '{Human Readable Label}', visible: true },
+  fieldType: '{fieldType}',
+  type: '{type}',
+  // format: '{format}',  // include if present in CRISP JSON
+  visible: true,
+  required: true,
+  enabled: true,
+  readOnly: false,
+};
+
+// Full CRISP JSON — all properties exactly as provided. Include workaround keys
+// (e.g. in properties['afs:layout']) for any constraints cleared by af-core.
+const fullField = {
+  // paste full CRISP JSON item here
+};
+
+const helper = renderComponent({ComponentName});
+
+describe('{ComponentName}', () => {
+
+  test('value changed by user is set in model', async () => {
+    const { renderResponse, element } = await helper(field);
+    // Choose method based on input type — see testing rules above
+    const input = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
+    fireEvent.change(input, { target: { value: '{sampleValue}' } });
+    expect(element.getState().value).toEqual('{sampleValue}');
+  });
+
+  test('it should handle visible property', async () => {
+    const { renderResponse } = await helper({ ...field, visible: false });
+    expect(renderResponse.queryByText(field.label.value)).toBeNull();
+  });
+
+  test('error message element exists when the field is invalid', async () => {
+    const { renderResponse } = await helper({ ...field, valid: false, errorMessage: DEFAULT_ERROR_MESSAGE });
+    expect(renderResponse.queryByText(DEFAULT_ERROR_MESSAGE)).not.toBeNull();
+  });
+
+  test('labels and inputs are linked with for and id attribute', async () => {
+    const { renderResponse } = await helper(field);
+    const input = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
+    const label = renderResponse.queryByText(field.label.value);
+    expect(input?.getAttribute('id')).toEqual(label?.getAttribute('for'));
+  });
+
+  test('disabled attribute is set when enabled is false', async () => {
+    const { renderResponse } = await helper({ ...field, enabled: false });
+    const input = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
+    expect(input).toBeDisabled();
+  });
+
+  test('tooltip and description toggle correctly', async () => {
+    const f = {
+      ...field,
+      tooltip: 'Short Description',
+      description: 'Long Description',
+      properties: { 'afs:layout': { tooltipVisible: true } },
+    };
+    const { renderResponse } = await helper(f);
+    expect(renderResponse.getByText('Short Description')).not.toBeNull();
+    const button = renderResponse.container.getElementsByClassName('{bemBlock}__questionmark');
+    userEvent.click(button[0]);
+    expect(renderResponse.getByText('Long Description')).not.toBeNull();
+  });
+
+  test('aria-describedby contains long and short description ids when both are present', async () => {
+    const f = {
+      ...field,
+      id: '{fieldName}-123',
+      tooltip: 'short desc',
+      description: 'long desc',
+      properties: { 'afs:layout': { tooltipVisible: true } },
+    };
+    const { renderResponse } = await helper(f);
+    const widget = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
+    expect(widget).toHaveAttribute('aria-describedby', `${f.id}__longdescription ${f.id}__shortdescription`);
+  });
+
+  test('html in the label should be rendered for rich text', async () => {
+    const f = {
+      ...field,
+      label: { value: '<strong>{Human Readable Label}</strong>', richText: true, visible: true },
+    };
+    const { renderResponse } = await helper(f);
+    expect(renderResponse.container.innerHTML).toContain('<strong>{Human Readable Label}</strong>');
+  });
+
+  // Add constraint-specific tests based on what your state check confirmed reaches props:
+  // - min/max: test({ ...field, minimum: X, maximum: Y }) → expect(input).toHaveAttribute('min', X)
+  // - minLength/maxLength: type a long string, assert model value is capped
+  // - pattern: assert the attribute is on the input element
+  // - accept (file): assert the attribute is on the input element
+  // - Value normalisation: pass raw af-core value, assert input.value shows normalised form
+
+  test('full CRISP JSON renders without errors', async () => {
+    const { renderResponse } = await helper(fullField);
+    expect(renderResponse.container.querySelector('input[type="{htmlInputType}"]')).not.toBeNull();
+    expect(renderResponse.queryByText('{Human Readable Label}')).not.toBeNull();
+  });
+});
+```
+
+---
+
+## Step 5 — Verify
+
+Run **from inside the package directory** (critical — see troubleshooting below):
+
+```bash
+cd packages/react-vanilla-components
+npm run build
+npx jest __tests__/components/{ComponentName}.test.tsx --no-coverage
+```
+
+Fix all errors before reporting done.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Property 'X' does not exist on type 'PROPS'` | State field exists at runtime but is absent from TypeScript typings | Access via `(props as any).X` |
+| Test fails: `value` is `undefined` after `userEvent.type` | Input type doesn't accept keystroke simulation in JSDOM | Switch to `fireEvent.change` |
+| Test fails: label/input ID mismatch with double `-widget` | Assertion manually appended `-widget` to `label.for` which already contains it | Assert `input.id === label.for` directly |
+| Test fails: `Missing semicolon` on `as Type` cast | Jest ran from repo root, picked up Babel config without TS support | Always `cd packages/react-vanilla-components` first |
+| Constraint (min/max/etc.) is `undefined` in props despite being in CRISP JSON | af-core clears it from state for this `type`+`format` combination | Run state check; use `afs:layout` side-channel if value is needed as HTML attribute |
+| HTML input shows wrong value format | af-core stores default/value in a different format than the input requires | Add a normalisation helper; verify expected format with state check |
+
+---
+
+## Checklist before finishing
+
+- [ ] State check run (`createFormInstance` + `getState()`) before writing the component — props match state, not raw CRISP JSON
+- [ ] BEM block name: `cmp-adaptiveform-{lowercasename}`; `data-cmp-is`: `adaptiveForm{PascalName}`
+- [ ] Outer `<div>` has all five `data-cmp-*` attributes
+- [ ] `<input>` / `<select>` / `<textarea>` has `id="${id}-widget"`, `aria-label`, `aria-invalid`, `aria-describedby`
+- [ ] `FieldWrapper` receives `bemBlock`, `label`, `id`, `tooltip`, `description`, `isError`, `errorMessage`
+- [ ] Constraint props: typed ones destructured from `props`; runtime-only ones via `(props as any).X` or `props.layout.X`
+- [ ] `dispatchBlur` called correctly for the field type (with or without value argument)
+- [ ] Default export is `withRuleEngine({ComponentName})`, not the bare component function
+- [ ] `mappings.ts` has entries for `fieldType` and `":type"` resource type (if present)
+- [ ] `src/index.ts` imports and re-exports the component
+- [ ] Value normalisation applied if state check showed format mismatch
+- [ ] Test uses correct input method per input type (see testing rules table)
+- [ ] Test label/input linking: `input.id === label.for` (no manual `-widget` suffix)
+- [ ] `fullField` smoke test covers the complete CRISP JSON
+- [ ] `npm run build` clean (no TS errors) — run from inside package dir
+- [ ] All Jest tests pass — run from inside package dir

From e67ae25ddd6dce140ed8cf42fcfc422853c96f5e Mon Sep 17 00:00:00 2001
From: Armaan Gupta <armaang@Armaans-MacBook-Pro.local>
Date: Tue, 2 Jun 2026 15:50:51 +0530
Subject: [PATCH 2/4] updated claude.md

---
 CLAUDE.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7d71846..284a6b5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,3 +82,24 @@ Strict mode. All components and utilities are typed. Output compiled to `lib/` (
 
 - PRs to `main`/`dev` → `.github/workflows/checks.yaml` (build + test on Node 16)
 - Merges to `main` → `.github/workflows/publish.yaml` (Lerna patch version bump, npm publish, pushes version tag)
+
+## Claude Code Skills
+
+### `/create-component`
+
+Scaffolds a complete new headless form component for `react-vanilla-components`. Invoke with:
+
+```
+/create-component
+
+I want to add a RatingInput component. Here is the CRISP JSON:
+{ ... }
+```
+
+The skill generates:
+- `src/components/{ComponentName}.tsx` — component following BEM + `withRuleEngine` patterns
+- `__tests__/components/{ComponentName}.test.tsx` — test suite covering value binding, visibility, errors, a11y
+- Updates `src/utils/mappings.ts` to register the field type / resource type
+- Updates `src/index.ts` to export the component
+
+If you do not have a CRISP JSON, describe the component's properties and the skill will infer a reasonable implementation.

From 579689ef9567924d3360bacf4cceeafb1c95d9a9 Mon Sep 17 00:00:00 2001
From: Armaan Gupta <armaang@Armaans-MacBook-Pro.local>
Date: Wed, 12 Aug 2026 12:42:35 +0530
Subject: [PATCH 3/4] feat(skill) : added a create core component skill for
 headless components

---
 .claude/commands/create-component.md | 690 +++++++++++++++++++++++++++
 .claude/skills/create-component.md   | 461 ++++++++++++------
 README.md                            |  60 +++
 3 files changed, 1066 insertions(+), 145 deletions(-)
 create mode 100644 .claude/commands/create-component.md

diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.md
new file mode 100644
index 0000000..5b873e7
--- /dev/null
+++ b/.claude/commands/create-component.md
@@ -0,0 +1,690 @@
+---
+description: Scaffold a complete new headless form component for react-vanilla-components — interactive, reads HTL from aem-core-forms-components for exact BEM markup, runs af-core state check, generates component + tests + mappings registration.
+allowed-tools: Read, Edit, Write, Bash
+---
+
+# Skill: create-component
+
+## Trigger
+Invoked when the user asks to **create a new headless form component** for the `react-vanilla-components` package. This skill is interactive — it gathers information in phases, confirms interpretation before writing code, then generates the component, tests, and registration.
+
+---
+
+## Phase 0 — Gather required information (interactive)
+
+Do NOT write any code until you have completed this phase.
+
+### 0a — Component name
+
+If the user did not provide a component name, ask:
+> What is the component name? (PascalCase, e.g. `RatingInput`, `ColorPicker`, `PhoneInput`)
+
+### 0b — model.json item
+
+Ask the user to paste the **model.json item** for the component. Explain what this is if they look unsure:
+
+> The model.json is the JSON output AEM Core Components returns when you render a form and call the form's `.model.json` endpoint (e.g. `http://localhost:4502/content/forms/af/<form-name>.model.json`).
+>
+> From the response, find the `items` array and paste the single **object that represents this field**. It will look like:
+> ```json
+> {
+>   "id": "telephoneinput-abc123",
+>   "fieldType": "text-input",
+>   ":type": "core/fd/components/form/telephoneinput/v1/telephoneinput",
+>   "name": "telephoneInput1",
+>   "label": { "value": "Phone Number", "visible": true },
+>   "type": "string",
+>   "visible": true,
+>   "required": false,
+>   "enabled": true,
+>   "readOnly": false,
+>   "constraintMessages": {},
+>   "properties": {
+>     "afs:layout": { "tooltipVisible": false },
+>     "fd:path": "/content/forms/af/myform/jcr:content/guideContainer/telephoneinput"
+>   }
+> }
+> ```
+>
+> If you don't have access to an AEM instance, describe the component's intended behavior and known properties and I'll infer the field shape.
+
+**If the user provides a model.json item:** proceed to Phase 1.
+**If the user describes the component instead:** construct a best-guess field object, show it to the user, and ask them to confirm or correct it before proceeding.
+
+### 0c — Special behaviors
+
+After receiving the model.json, ask:
+
+> Does this component have any of the following special behaviors? (answer all that apply)
+> - **Modal / dialog** (opens a popup for input — like Scribble's canvas dialog)
+> - **Canvas drawing** (draws on an HTML canvas)
+> - **Rich options list** (custom option rendering beyond a plain `<select>`)
+> - **File upload** (file picker + upload flow)
+> - **External state** (uses `useRef`, `useState` beyond simple value binding)
+> - **Display only** (renders data, no user input)
+> - **Container** (wraps other fields — like Panel, Accordion)
+> - **None of the above** (simple input field — text, number, date, select, checkbox, etc.)
+
+This determines the component template and which HOC (`withRuleEngine` vs `withRuleEnginePanel`) to use.
+
+### 0d — Reference component
+
+Ask:
+> Is there an existing component in this repo that is most similar? (e.g. "similar to DateTimeInput", "similar to Scribble", "similar to DropDown")
+>
+> If unsure, say "none" and I'll pick the closest match automatically.
+
+Look at `packages/react-vanilla-components/src/components/` and pick the closest existing component as a reference for the implementation style.
+
+### 0e — Read core components HTL for ground-truth markup
+
+The HTL template in `aem-core-forms-components` is the authoritative source for BEM class names, `data-cmp-*` attributes, CSS modifier classes, and widget element structure. Read it before writing any code.
+
+Derive the component folder name from the `":type"` resource type path. For example:
+- `":type": "core/fd/components/form/telephoneinput/v1/telephoneinput"` → folder `telephoneinput`
+- `":type": "core/fd/components/form/ratinginput/v1/ratinginput"` → folder `ratinginput`
+
+If `":type"` is absent, derive from the component name lowercased.
+
+**Step 1 — Check for local sibling repo:**
+```bash
+ls ../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/ 2>/dev/null | head -5
+```
+
+**Step 2a — If local repo exists, read HTL directly:**
+```bash
+cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/{componentfolder}.html"
+```
+
+Also read the CRISP JSON (component dialog / schema definition) if present:
+```bash
+cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/.content.xml" 2>/dev/null
+# or look for _cq_dialog or model JSON files in the component folder
+ls "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/"
+```
+
+**Step 2b — If local repo does not exist, fetch from GitHub:**
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/{componentfolder}.html" \
+  --jq '.content' | base64 -d
+```
+
+If `gh` is unavailable, fall back to listing the folder to find the right filename:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}" \
+  --jq '.[].name'
+```
+
+**Step 3 — Extract from HTL:**
+
+Read the HTL output and extract:
+
+| HTL element | What to record |
+|---|---|
+| Root `<div>` class string | Exact BEM block name (e.g. `cmp-adaptiveform-telephoneinput`) |
+| `data-cmp-is` value | Exact `data-cmp-is` string (e.g. `adaptiveFormTelephoneInput`) |
+| All `data-cmp-*` attributes | Any beyond the standard five — note names and values |
+| State modifier classes | `--filled`/`--empty`, `--checked`/`--unchecked`, `--disabled`, custom |
+| Widget element | Tag name, nesting depth, wrapper divs, class names |
+| Extra wrapper divs | e.g. `__input-wrapper`, `__options-wrapper` present in DateTimeInput |
+| CSS custom properties | Any `--cmp-*` CSS variables set inline |
+
+If the HTL file is not found (new/private component), fall back to inferring BEM names from the model.json `fieldType` and component name. State this explicitly in the Phase 1 confirmation.
+
+**Step 4 — Read the existing headless implementation if any:**
+
+Check if a reference headless component for this field type already exists (e.g. a partial or older implementation):
+```bash
+ls packages/react-vanilla-components/src/components/ | grep -i {componentfolder}
+```
+
+---
+
+## Phase 1 — Analyze the model.json (before writing code)
+
+Extract and verify these fields from the model.json item. Show your analysis to the user before proceeding.
+
+### 1a — Key fields to extract
+
+| model.json field | What to derive |
+|---|---|
+| `fieldType` | Primary key in `mappings.ts` |
+| `":type"` | Secondary key in `mappings.ts` (resource type string) — may be absent if custom |
+| `type` + `format` | HTML element and input type (see table below) |
+| `enum` / `enumNames` | Indicates select-type component |
+| `items` present | Container component — use `withRuleEnginePanel` |
+| `minimum` / `maximum` | Check type compatibility (see af-core contract) |
+| `constraintMessages` | Lists which constraints are active |
+| `properties['afs:layout']` | Layout side-channel keys the author already uses |
+| `default` | Becomes `props.value` on first render — check format compatibility |
+
+### 1b — `type` + `format` → HTML element
+
+| `type` | `format` | HTML element / `type` attr |
+|---|---|---|
+| `string` | _(none)_ | `<input type="text">` |
+| `string` | `date` | `<input type="date">` |
+| `string` | `date-time` | `<input type="datetime-local">` |
+| `string` | `time` | `<input type="time">` |
+| `string` | `email` | `<input type="email">` |
+| `string` | `uri` | `<input type="url">` |
+| `string` | `tel` | `<input type="tel">` |
+| `number` / `integer` | _(any)_ | `<input type="number">` |
+| `boolean` | _(any)_ | `<input type="checkbox">` |
+| with `enum`/`enumNames` | _(any)_ | `<select>` |
+| multiline | _(any)_ | `<textarea>` |
+
+### 1c — Naming derivations
+
+Use values read from the HTL template (Phase 0e) as the authoritative source. Fall back to inference only when HTL was unavailable.
+
+- **BEM block**: read from HTL root `<div>` class — e.g. `cmp-adaptiveform-telephoneinput`
+- **`data-cmp-is`**: read from HTL `data-cmp-is` attribute — e.g. `adaptiveFormTelephoneInput`
+- **Extra wrapper divs**: any `__input-wrapper` or similar nesting present in HTL must be reproduced in the React component
+- **State modifier classes**: use exactly the modifiers from HTL (`--filled`/`--empty`, `--checked`, etc.)
+- **File name**: `{ComponentName}.tsx`
+
+If HTL was not available, infer: BEM block = `cmp-adaptiveform-{lowercasename}`, `data-cmp-is` = `adaptiveForm{PascalName}`, and flag this in the confirmation.
+
+### 1d — Show analysis and confirm
+
+Before writing any code, output a confirmation block like this:
+
+```
+Component: RatingInput
+File: src/components/RatingInput.tsx
+fieldType: "rating-input"
+":type": "core/fd/components/form/ratinginput/v1/ratinginput"  (or absent)
+HTML element: <input type="number">
+BEM block: cmp-adaptiveform-ratinginput          ← from HTL (or inferred)
+data-cmp-is: adaptiveFormRatingInput             ← from HTL (or inferred)
+Extra wrappers: none                             ← or e.g. "__input-wrapper div present"
+State modifiers: --filled / --empty              ← from HTL
+HOC: withRuleEngine
+Reference component: NumberField.tsx
+
+Constraints present: minimum, maximum
+Constraints af-core may clear: none for type=number
+Value normalisation needed: no
+afs:layout side-channel needed: no
+
+Special behaviors: none
+
+HTL source: local sibling repo  (or: GitHub fetch, or: not found — inferred)
+
+Does this look right? Any corrections before I proceed?
+```
+
+**Wait for user to confirm or correct before proceeding to Phase 2.**
+
+---
+
+## Phase 2 — af-core state check
+
+Run this check to confirm which fields actually reach props at runtime (af-core shapes the state — it is not a raw copy of model.json):
+
+```bash
+cd packages/react-vanilla-components
+node -e "
+const {createFormInstance} = require('@aemforms/af-core');
+const form = createFormInstance({items:[
+  /* paste the model.json item here */
+]});
+console.log(JSON.stringify(form.items[0].getState(), null, 2));
+"
+```
+
+### Known af-core state shaping rules
+
+**`minimum` / `maximum`:**
+- Preserved in state for `type: 'number'`, `type: 'integer'`, and `type: 'string'` with `format: 'date'`.
+- **Cleared from state** for all other `type`+`format` combinations. The validation engine still fires internally, but the component never sees the raw values as props.
+- If the component needs these as HTML attributes and they are cleared, use the `afs:layout` side-channel (see below).
+
+**`constraintMessages`:** always present in state as-is. af-core sets `props.errorMessage` when a constraint fires. The component never handles this — `FieldWrapper` renders it.
+
+**`default` value format:** af-core may store the default in a different format than the HTML input requires (e.g. `datetime-local` requires `YYYY-MM-DDTHH:MM` but af-core may surface `YYYY-MM-DD HH:MM:SS`). Always check the actual state value and normalise if needed.
+
+**`properties` object:** passes through to state unchanged. `withRuleEngine` additionally maps `properties['afs:layout']` → `props.layout` as `{[key: string]: any}`.
+
+### `afs:layout` side-channel
+
+When af-core clears a constraint that the component still needs for an HTML attribute, the author duplicates the value into `properties['afs:layout']` under a named key. `withRuleEngine` maps the entire `afs:layout` object to `props.layout`, so it survives af-core processing.
+
+```json
+"properties": {
+  "afs:layout": {
+    "sliderMin": 1,
+    "sliderMax": 10
+  }
+}
+```
+
+```tsx
+const sliderMin = layout?.sliderMin;
+const sliderMax = layout?.sliderMax;
+```
+
+Name custom keys clearly (e.g. `sliderMin`, not `min`) to distinguish from standard af-core layout keys.
+
+### After running the state check
+
+Report to the user:
+- Which fields are present in state and their actual types/values
+- Which fields from model.json are absent from state
+- Whether value normalisation is needed
+- Whether any constraints need the `afs:layout` side-channel
+
+**If the state check output contradicts the model.json analysis, update Phase 1 confirmation before generating code.**
+
+---
+
+## Phase 3 — Generate the component file
+
+File: `packages/react-vanilla-components/src/components/{ComponentName}.tsx`
+
+Use the **exact** BEM block, `data-cmp-is`, wrapper div structure, and state modifier classes extracted from the HTL in Phase 0e. Do not invent or guess these — they must match the core components markup so that the existing core component CSS applies correctly to the headless output.
+
+### License header (always include)
+
+```tsx
+// *******************************************************************************
+//  * Copyright 2026 Adobe
+//  *
+//  * Licensed under the Apache License, Version 2.0 (the "License");
+//  * you may not use this file except in compliance with the License.
+//  * You may obtain a copy of the License at
+//  *
+//  *     http://www.apache.org/licenses/LICENSE-2.0
+//  *
+//  * Unless required by applicable law or agreed to in writing, software
+//  * distributed under the License is distributed on an "AS IS" BASIS,
+//  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  * See the License for the specific language governing permissions and
+//  * limitations under the License.
+//  *
+//  * BEM markup follows AEM core form components guidelines.
+//  * LINK- https://github.com/adobe/aem-core-forms-components
+//  ******************************************************************************
+```
+
+### Base template (simple input field)
+
+```tsx
+import React, { useCallback } from 'react';
+import { withRuleEngine } from '../utils/withRuleEngine';
+import { PROPS } from '../utils/type';
+import FieldWrapper from './common/FieldWrapper';
+import { syncAriaDescribedBy } from '../utils/utils';
+
+const {ComponentName} = (props: PROPS) => {
+  const {
+    id,
+    value,
+    label,
+    required,
+    readOnly = false,
+    placeholder,
+    enabled,
+    visible,
+    name,
+    appliedCssClassNames,
+    valid,
+    layout,
+    // add constraint props confirmed by state check:
+    // minimum, maximum, minLength, maxLength, pattern, etc.
+    // for runtime-only fields not in PROPS typings: const x = (props as any).fieldName;
+  } = props;
+
+  // Normalise value if the HTML input format differs from af-core's stored format.
+  const finalValue = value === undefined ? '' : value;
+
+  const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    props.dispatchChange(e.target.value);
+  }, [props.dispatchChange]);
+
+  // dispatchBlur: call with e.target.value for text-like inputs that re-submit on blur.
+  // Call with no argument for date, number, select, checkbox, file inputs.
+  const handleBlur = useCallback(() => {
+    props.dispatchBlur();
+  }, [props.dispatchBlur]);
+
+  const handleFocus = useCallback(() => {
+    props.dispatchFocus();
+  }, [props.dispatchFocus]);
+
+  return (
+    <div
+      className={`{bemBlock} {bemBlock}--${value ? 'filled' : 'empty'} ${appliedCssClassNames || ''}`}
+      data-cmp-is="{dataCmpIs}"
+      data-cmp-visible={visible}
+      data-cmp-enabled={enabled}
+      data-cmp-required={required}
+      data-cmp-valid={valid}
+    >
+      <FieldWrapper
+        bemBlock='{bemBlock}'
+        label={label}
+        id={id}
+        tooltip={props.tooltip}
+        description={props.description}
+        isError={props.isError}
+        errorMessage={props.errorMessage}
+      >
+        <input
+          type="{htmlInputType}"
+          id={`${id}-widget`}
+          className='{bemBlock}__widget'
+          title={props.tooltipText || ''}
+          value={finalValue}
+          name={name}
+          required={required}
+          readOnly={readOnly}
+          placeholder={placeholder}
+          disabled={!enabled}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          aria-label={label?.value}
+          aria-invalid={!valid}
+          aria-describedby={syncAriaDescribedBy(id, props.tooltip, props.description, props.errorMessage)}
+          // constraint HTML attributes confirmed by state check:
+          // min / max / minLength / maxLength / step / pattern / accept / multiple
+        />
+      </FieldWrapper>
+    </div>
+  );
+};
+
+export default withRuleEngine({ComponentName});
+```
+
+### Adaptation rules by category
+
+**Text inputs** (`type="text/email/url/tel/password"`):
+- `dispatchBlur(event.target.value)` — text inputs re-submit value on blur
+- Destructure `minLength`, `maxLength`, `pattern` from `props`
+
+**Numeric inputs** (`type="number"`):
+- `minimum` and `maximum` typed as `number` in `PROPS` — destructure directly
+- Map to `min` / `max` HTML attributes
+- Include `step` if present in state
+
+**Date inputs** (`type="date"`):
+- `minimum` / `maximum` surfaced as strings for `format: 'date'`
+- Map to `min` / `max` HTML attributes
+
+**datetime-local** (`type="datetime-local"`):
+- af-core stores value with space separator and seconds (`YYYY-MM-DD HH:MM:SS`)
+- datetime-local input requires `YYYY-MM-DDTHH:MM` — write normalisation helper
+- `minimum` / `maximum` may be cleared by af-core — use `afs:layout` side-channel or verify via state check
+
+**Select / options** (with `enum`/`enumNames`):
+- Render `<select>` with `<option>` per enum value
+- Use `isMultiSelect` from props for conditional `multiple` attribute
+- Multi-select: `Array.from(event.target.selectedOptions, o => o.value)`
+
+**Checkbox / Switch** (`type="checkbox"`):
+- `value` is boolean — dispatch `event.target.checked`
+- State class modifier: `--checked` / `--unchecked` (not `--filled` / `--empty`)
+
+**Textarea** (`<textarea>`):
+- Map `minLength`, `maxLength`, `rows`, `cols` from state
+- `dispatchChange(event.target.value)`
+
+**Container components** (model.json has `items` array):
+- Import and use `withRuleEnginePanel` instead of `withRuleEngine`
+- Accept `PROPS_PANEL` type instead of `PROPS`
+- Render children via the AEM renderer — use `Panel.tsx` or `Accordion/Accordion.tsx` as reference
+
+**Display-only components** (no user input — e.g. PlainText, Image):
+- Omit all event handlers and `FieldWrapper`
+- Render only relevant markup from props directly
+
+**Complex input with modal / canvas** (e.g. Scribble):
+- Use `useRef`, `useState` for internal state beyond value binding
+- Keep the modal markup inside the same component file
+- Use `dispatchChange(dataUrl)` or similar when user confirms the input
+- Reference `Scribble.tsx` as the pattern
+
+---
+
+## Phase 4 — Register in `mappings.ts`
+
+File: `packages/react-vanilla-components/src/utils/mappings.ts`
+
+Add import (alphabetical order):
+```ts
+import {ComponentName} from '../components/{ComponentName}';
+```
+
+Add entries in the `mappings` object:
+```ts
+'{fieldType}': {ComponentName},
+// If model.json has a ":type" resource type string:
+'{":type" value}': {ComponentName},
+```
+
+Keep simple `fieldType` keys grouped; resource-type strings grouped — match existing file structure.
+
+---
+
+## Phase 5 — Export from `src/index.ts`
+
+File: `packages/react-vanilla-components/src/index.ts`
+
+Add import (alphabetical order):
+```ts
+import {ComponentName} from './components/{ComponentName}';
+```
+
+Add to the `export { ... }` block:
+```ts
+{ComponentName},
+```
+
+---
+
+## Phase 6 — Generate the test file
+
+File: `packages/react-vanilla-components/__tests__/components/{ComponentName}.test.tsx`
+
+### Core testing rules
+
+**1. Input method by type**
+
+| Input type | Method | Reason |
+|---|---|---|
+| `text`, `email`, `tel`, `url`, `password` | `userEvent.type(input, value)` | JSDOM simulates keystrokes |
+| `date`, `datetime-local`, `time`, `number`, `range` | `fireEvent.change(input, { target: { value } })` | Native picker events not simulated in JSDOM |
+| `checkbox` | `userEvent.click(input)` | Toggles checked state |
+| `select` | `fireEvent.change(select, { target: { value } })` | Most reliable for select |
+
+**2. Label/input linking**
+`FieldWrapper` sets `label.for = input.id = "${id}-widget"`. Assert directly:
+```tsx
+expect(input.getAttribute('id')).toEqual(label.getAttribute('for'));
+// Do NOT manually append '-widget' to label.for — it is already the full id
+```
+
+**3. Finding inputs without placeholder**
+```tsx
+const input = renderResponse.container.querySelector('input[type="text"]') as HTMLInputElement;
+```
+
+**4. Constraint attributes**
+Only test constraints confirmed by state check. For constraints read from `props.layout`, pass them under `properties['afs:layout']` in the test field object.
+
+**5. Value normalisation**
+If the component normalises the value, write a dedicated test: pass the raw af-core format, assert the HTML input shows the normalised form.
+
+**6. Use the model.json item as `fullField`**
+Use the exact model.json item provided by the user as the `fullField` object. This is the most realistic test fixture — it mirrors what AEM will actually send.
+
+### Test template
+
+```tsx
+/*
+ * Copyright 2026 Adobe, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import {ComponentName} from '../../src/components/{ComponentName}';
+import userEvent from '@testing-library/user-event';
+import { fireEvent } from '@testing-library/react';
+import { renderComponent, DEFAULT_ERROR_MESSAGE } from '../utils';
+import '@testing-library/jest-dom/extend-expect';
+
+// Minimal field — only properties needed to render
+const field = {
+  name: '{fieldName}',
+  label: { value: '{Human Readable Label}', visible: true },
+  fieldType: '{fieldType}',
+  type: '{type}',
+  // format: '{format}',  // include if present in model.json
+  visible: true,
+  required: true,
+  enabled: true,
+  readOnly: false,
+};
+
+// Full field — exact model.json item as provided by the user.
+// This is what AEM will actually send at runtime.
+const fullField = {
+  // paste model.json item here exactly
+};
+
+const helper = renderComponent({ComponentName});
+
+describe('{ComponentName}', () => {
+
+  test('value changed by user is set in model', async () => {
+    const { renderResponse, element } = await helper(field);
+    const input = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
+    fireEvent.change(input, { target: { value: '{sampleValue}' } });
+    expect(element.getState().value).toEqual('{sampleValue}');
+  });
+
+  test('it should handle visible property', async () => {
+    const { renderResponse } = await helper({ ...field, visible: false });
+    expect(renderResponse.queryByText(field.label.value)).toBeNull();
+  });
+
+  test('error message element exists when the field is invalid', async () => {
+    const { renderResponse } = await helper({ ...field, valid: false, errorMessage: DEFAULT_ERROR_MESSAGE });
+    expect(renderResponse.queryByText(DEFAULT_ERROR_MESSAGE)).not.toBeNull();
+  });
+
+  test('labels and inputs are linked with for and id attribute', async () => {
+    const { renderResponse } = await helper(field);
+    const input = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
+    const label = renderResponse.queryByText(field.label.value);
+    expect(input?.getAttribute('id')).toEqual(label?.getAttribute('for'));
+  });
+
+  test('disabled attribute is set when enabled is false', async () => {
+    const { renderResponse } = await helper({ ...field, enabled: false });
+    const input = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
+    expect(input).toBeDisabled();
+  });
+
+  test('tooltip and description toggle correctly', async () => {
+    const f = {
+      ...field,
+      tooltip: 'Short Description',
+      description: 'Long Description',
+      properties: { 'afs:layout': { tooltipVisible: true } },
+    };
+    const { renderResponse } = await helper(f);
+    expect(renderResponse.getByText('Short Description')).not.toBeNull();
+    const button = renderResponse.container.getElementsByClassName('{bemBlock}__questionmark');
+    userEvent.click(button[0]);
+    expect(renderResponse.getByText('Long Description')).not.toBeNull();
+  });
+
+  test('aria-describedby contains long and short description ids when both are present', async () => {
+    const f = {
+      ...field,
+      id: '{fieldName}-123',
+      tooltip: 'short desc',
+      description: 'long desc',
+      properties: { 'afs:layout': { tooltipVisible: true } },
+    };
+    const { renderResponse } = await helper(f);
+    const widget = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
+    expect(widget).toHaveAttribute('aria-describedby', `${f.id}__longdescription ${f.id}__shortdescription`);
+  });
+
+  test('html in the label should be rendered for rich text', async () => {
+    const f = {
+      ...field,
+      label: { value: '<strong>{Human Readable Label}</strong>', richText: true, visible: true },
+    };
+    const { renderResponse } = await helper(f);
+    expect(renderResponse.container.innerHTML).toContain('<strong>{Human Readable Label}</strong>');
+  });
+
+  // Add constraint-specific tests based on state check results:
+  // - min/max: helper({ ...field, minimum: X, maximum: Y }) → expect(input).toHaveAttribute('min', String(X))
+  // - minLength/maxLength: type a long string, assert model value is capped
+  // - pattern: expect(input).toHaveAttribute('pattern', '...')
+  // - Value normalisation: pass raw af-core value, assert input.value shows normalised form
+  // - afs:layout side-channel: pass properties['afs:layout'] key, assert HTML attribute is set
+
+  test('full model.json field renders without errors', async () => {
+    const { renderResponse } = await helper(fullField);
+    expect(renderResponse.container.querySelector('input[type="{htmlInputType}"]')).not.toBeNull();
+    expect(renderResponse.queryByText('{Human Readable Label}')).not.toBeNull();
+  });
+});
+```
+
+---
+
+## Phase 7 — Verify
+
+Run **from inside the package directory**:
+
+```bash
+cd packages/react-vanilla-components
+npm run build
+npx jest __tests__/components/{ComponentName}.test.tsx --no-coverage
+```
+
+Fix all errors before reporting done. Common failures and their causes:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Property 'X' does not exist on type 'PROPS'` | Runtime state field not in TS typings | `(props as any).X` |
+| `value` is `undefined` after `userEvent.type` | Input type doesn't accept keystroke simulation in JSDOM | Switch to `fireEvent.change` |
+| Label/input ID mismatch with double `-widget` | Assertion manually appended `-widget` to `label.for` | Assert `input.id === label.for` directly — `label.for` already is the full id |
+| `Missing semicolon` on `as Type` cast | Jest ran from repo root — Babel config without TS support | Always `cd packages/react-vanilla-components` first |
+| Constraint is `undefined` in props | af-core cleared it from state | Run state check; use `afs:layout` if HTML attribute is needed |
+| HTML input shows wrong value format | af-core stores value in different format | Add normalisation helper; confirm expected format via state check |
+
+---
+
+## Checklist before finishing
+
+- [ ] model.json item analysed and confirmed with user before writing any code
+- [ ] af-core state check run — props match actual state, not raw model.json
+- [ ] BEM block: `cmp-adaptiveform-{lowercasename}` — `data-cmp-is`: `adaptiveForm{PascalName}`
+- [ ] Outer `<div>` has all five `data-cmp-*` attributes
+- [ ] Widget element (`input`/`select`/`textarea`/custom) has `id="${id}-widget"`, `aria-label`, `aria-invalid`, `aria-describedby`
+- [ ] `FieldWrapper` receives `bemBlock`, `label`, `id`, `tooltip`, `description`, `isError`, `errorMessage`
+- [ ] Typed constraint props destructured from `props`; runtime-only ones via `(props as any).X` or `props.layout.X`
+- [ ] `dispatchBlur` called correctly — with value for text-like inputs, without for others
+- [ ] Default export is `withRuleEngine({ComponentName})` (or `withRuleEnginePanel` for containers), not the bare function
+- [ ] `mappings.ts` has entries for `fieldType` and `":type"` resource type (if present in model.json)
+- [ ] `src/index.ts` imports and re-exports the component
+- [ ] Value normalisation applied if state check showed format mismatch
+- [ ] Test uses correct input method per input type
+- [ ] Test label/input linking: `input.id === label.for` (no manual `-widget` suffix)
+- [ ] `fullField` in tests uses the exact model.json item provided by the user
+- [ ] `npm run build` clean — run from inside package dir
+- [ ] All Jest tests pass — run from inside package dir
diff --git a/.claude/skills/create-component.md b/.claude/skills/create-component.md
index 07f3c0b..f98af41 100644
--- a/.claude/skills/create-component.md
+++ b/.claude/skills/create-component.md
@@ -1,39 +1,161 @@
 # Skill: create-component
 
 ## Trigger
-Use this skill when the user asks to **create a new headless form component** for the `react-vanilla-components` package. They will typically provide a component name and a CRISP JSON (AEM Core Components schema) that describes the component's properties, constraints, and resource type.
-
-If no CRISP JSON is provided, ask for it. If the user does not have one, ask them to describe the component's fields so you can infer the correct mapping.
+Invoked when the user asks to **create a new headless form component** for the `react-vanilla-components` package. This skill is interactive — it gathers information in phases, confirms interpretation before writing code, then generates the component, tests, and registration.
 
 ---
 
-## What this skill produces
+## Phase 0 — Gather required information (interactive)
 
-1. `packages/react-vanilla-components/src/components/{ComponentName}.tsx` — component source
-2. `packages/react-vanilla-components/__tests__/components/{ComponentName}.test.tsx` — test suite
-3. `src/utils/mappings.ts` — updated with the new component's field type and resource type keys
-4. `src/index.ts` — updated to import and re-export the component
+Do NOT write any code until you have completed this phase.
 
----
+### 0a — Component name
+
+If the user did not provide a component name, ask:
+> What is the component name? (PascalCase, e.g. `RatingInput`, `ColorPicker`, `PhoneInput`)
+
+### 0b — model.json item
+
+Ask the user to paste the **model.json item** for the component. Explain what this is if they look unsure:
+
+> The model.json is the JSON output AEM Core Components returns when you render a form and call the form's `.model.json` endpoint (e.g. `http://localhost:4502/content/forms/af/<form-name>.model.json`).
+>
+> From the response, find the `items` array and paste the single **object that represents this field**. It will look like:
+> ```json
+> {
+>   "id": "telephoneinput-abc123",
+>   "fieldType": "text-input",
+>   ":type": "core/fd/components/form/telephoneinput/v1/telephoneinput",
+>   "name": "telephoneInput1",
+>   "label": { "value": "Phone Number", "visible": true },
+>   "type": "string",
+>   "visible": true,
+>   "required": false,
+>   "enabled": true,
+>   "readOnly": false,
+>   "constraintMessages": {},
+>   "properties": {
+>     "afs:layout": { "tooltipVisible": false },
+>     "fd:path": "/content/forms/af/myform/jcr:content/guideContainer/telephoneinput"
+>   }
+> }
+> ```
+>
+> If you don't have access to an AEM instance, describe the component's intended behavior and known properties and I'll infer the field shape.
+
+**If the user provides a model.json item:** proceed to Phase 1.
+**If the user describes the component instead:** construct a best-guess field object, show it to the user, and ask them to confirm or correct it before proceeding.
+
+### 0c — Special behaviors
+
+After receiving the model.json, ask:
+
+> Does this component have any of the following special behaviors? (answer all that apply)
+> - **Modal / dialog** (opens a popup for input — like Scribble's canvas dialog)
+> - **Canvas drawing** (draws on an HTML canvas)
+> - **Rich options list** (custom option rendering beyond a plain `<select>`)
+> - **File upload** (file picker + upload flow)
+> - **External state** (uses `useRef`, `useState` beyond simple value binding)
+> - **Display only** (renders data, no user input)
+> - **Container** (wraps other fields — like Panel, Accordion)
+> - **None of the above** (simple input field — text, number, date, select, checkbox, etc.)
+
+This determines the component template and which HOC (`withRuleEngine` vs `withRuleEnginePanel`) to use.
+
+### 0d — Reference component
+
+Ask:
+> Is there an existing component in this repo that is most similar? (e.g. "similar to DateTimeInput", "similar to Scribble", "similar to DropDown")
+>
+> If unsure, say "none" and I'll pick the closest match automatically.
+
+Look at `packages/react-vanilla-components/src/components/` and pick the closest existing component as a reference for the implementation style.
+
+### 0e — Read core components HTL for ground-truth markup
+
+The HTL template in `aem-core-forms-components` is the authoritative source for BEM class names, `data-cmp-*` attributes, CSS modifier classes, and widget element structure. Read it before writing any code.
+
+Derive the component folder name from the `":type"` resource type path. For example:
+- `":type": "core/fd/components/form/telephoneinput/v1/telephoneinput"` → folder `telephoneinput`
+- `":type": "core/fd/components/form/ratinginput/v1/ratinginput"` → folder `ratinginput`
 
-## Step 0 — Understand the CRISP JSON before writing any code
+If `":type"` is absent, derive from the component name lowercased.
 
-Before writing the component, extract and reason about these fields:
+**Step 1 — Check for local sibling repo:**
+```bash
+ls ../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/ 2>/dev/null | head -5
+```
+
+**Step 2a — If local repo exists, read HTL directly:**
+```bash
+cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/{componentfolder}.html"
+```
 
-| CRISP field | What to derive from it |
+Also read the CRISP JSON (component dialog / schema definition) if present:
+```bash
+cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/.content.xml" 2>/dev/null
+# or look for _cq_dialog or model JSON files in the component folder
+ls "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/"
+```
+
+**Step 2b — If local repo does not exist, fetch from GitHub:**
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/{componentfolder}.html" \
+  --jq '.content' | base64 -d
+```
+
+If `gh` is unavailable, fall back to listing the folder to find the right filename:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}" \
+  --jq '.[].name'
+```
+
+**Step 3 — Extract from HTL:**
+
+Read the HTL output and extract:
+
+| HTL element | What to record |
 |---|---|
-| `fieldType` | Primary key in `mappings.ts` |
-| `":type"` | Secondary key in `mappings.ts` (resource type string) |
-| `type` + `format` | HTML element type (see table below) |
-| Constraint fields (`minimum`, `maximum`, `minLength`, etc.) | **Do not assume they reach props** — verify against af-core state (see af-core state contract below) |
-| `default` | Becomes `props.value` on first render — check format compatibility with the HTML input |
-| `enum` / `enumNames` | Indicates a select-type component |
-| `items` present | Container component — use `withRuleEnginePanel` instead of `withRuleEngine` |
-| `properties['afs:layout']` | Passed through to `props.layout` by `withRuleEngine` — use as a general-purpose side-channel for data af-core may strip |
+| Root `<div>` class string | Exact BEM block name (e.g. `cmp-adaptiveform-telephoneinput`) |
+| `data-cmp-is` value | Exact `data-cmp-is` string (e.g. `adaptiveFormTelephoneInput`) |
+| All `data-cmp-*` attributes | Any beyond the standard five — note names and values |
+| State modifier classes | `--filled`/`--empty`, `--checked`/`--unchecked`, `--disabled`, custom |
+| Widget element | Tag name, nesting depth, wrapper divs, class names |
+| Extra wrapper divs | e.g. `__input-wrapper`, `__options-wrapper` present in DateTimeInput |
+| CSS custom properties | Any `--cmp-*` CSS variables set inline |
 
-### `type` + `format` → HTML element
+If the HTL file is not found (new/private component), fall back to inferring BEM names from the model.json `fieldType` and component name. State this explicitly in the Phase 1 confirmation.
 
-| `type` | `format` | HTML element / `type` attribute |
+**Step 4 — Read the existing headless implementation if any:**
+
+Check if a reference headless component for this field type already exists (e.g. a partial or older implementation):
+```bash
+ls packages/react-vanilla-components/src/components/ | grep -i {componentfolder}
+```
+
+---
+
+## Phase 1 — Analyze the model.json (before writing code)
+
+Extract and verify these fields from the model.json item. Show your analysis to the user before proceeding.
+
+### 1a — Key fields to extract
+
+| model.json field | What to derive |
+|---|---|
+| `fieldType` | Primary key in `mappings.ts` |
+| `":type"` | Secondary key in `mappings.ts` (resource type string) — may be absent if custom |
+| `type` + `format` | HTML element and input type (see table below) |
+| `enum` / `enumNames` | Indicates select-type component |
+| `items` present | Container component — use `withRuleEnginePanel` |
+| `minimum` / `maximum` | Check type compatibility (see af-core contract) |
+| `constraintMessages` | Lists which constraints are active |
+| `properties['afs:layout']` | Layout side-channel keys the author already uses |
+| `default` | Becomes `props.value` on first render — check format compatibility |
+
+### 1b — `type` + `format` → HTML element
+
+| `type` | `format` | HTML element / `type` attr |
 |---|---|---|
 | `string` | _(none)_ | `<input type="text">` |
 | `string` | `date` | `<input type="date">` |
@@ -41,79 +163,128 @@ Before writing the component, extract and reason about these fields:
 | `string` | `time` | `<input type="time">` |
 | `string` | `email` | `<input type="email">` |
 | `string` | `uri` | `<input type="url">` |
+| `string` | `tel` | `<input type="tel">` |
 | `number` / `integer` | _(any)_ | `<input type="number">` |
 | `boolean` | _(any)_ | `<input type="checkbox">` |
-| with `enum`/`enumNames` | _(any)_ | `<select>` (add `multiple` if `isMultiSelect`) |
+| with `enum`/`enumNames` | _(any)_ | `<select>` |
 | multiline | _(any)_ | `<textarea>` |
 
-Derive the **BEM block name**: `cmp-adaptiveform-{lowercasecomponentname}` (e.g. `RatingInput` → `cmp-adaptiveform-ratinginput`).
+### 1c — Naming derivations
 
-Derive the **`data-cmp-is`** value: `adaptiveForm{PascalCaseComponentName}`.
+Use values read from the HTL template (Phase 0e) as the authoritative source. Fall back to inference only when HTL was unavailable.
 
----
+- **BEM block**: read from HTL root `<div>` class — e.g. `cmp-adaptiveform-telephoneinput`
+- **`data-cmp-is`**: read from HTL `data-cmp-is` attribute — e.g. `adaptiveFormTelephoneInput`
+- **Extra wrapper divs**: any `__input-wrapper` or similar nesting present in HTL must be reproduced in the React component
+- **State modifier classes**: use exactly the modifiers from HTL (`--filled`/`--empty`, `--checked`, etc.)
+- **File name**: `{ComponentName}.tsx`
+
+If HTL was not available, infer: BEM block = `cmp-adaptiveform-{lowercasename}`, `data-cmp-is` = `adaptiveForm{PascalName}`, and flag this in the confirmation.
+
+### 1d — Show analysis and confirm
+
+Before writing any code, output a confirmation block like this:
+
+```
+Component: RatingInput
+File: src/components/RatingInput.tsx
+fieldType: "rating-input"
+":type": "core/fd/components/form/ratinginput/v1/ratinginput"  (or absent)
+HTML element: <input type="number">
+BEM block: cmp-adaptiveform-ratinginput          ← from HTL (or inferred)
+data-cmp-is: adaptiveFormRatingInput             ← from HTL (or inferred)
+Extra wrappers: none                             ← or e.g. "__input-wrapper div present"
+State modifiers: --filled / --empty              ← from HTL
+HOC: withRuleEngine
+Reference component: NumberField.tsx
+
+Constraints present: minimum, maximum
+Constraints af-core may clear: none for type=number
+Value normalisation needed: no
+afs:layout side-channel needed: no
+
+Special behaviors: none
+
+HTL source: local sibling repo  (or: GitHub fetch, or: not found — inferred)
+
+Does this look right? Any corrections before I proceed?
+```
 
-## af-core state contract — what actually reaches props
+**Wait for user to confirm or correct before proceeding to Phase 2.**
 
-`withRuleEngine` passes the af-core **state snapshot** to the component as props. The state is not a raw copy of the CRISP JSON — af-core shapes it. **Always verify what is actually in state before using a field from props.**
+---
 
-### How to verify
+## Phase 2 — af-core state check
 
-Run a quick node check before writing the component:
+Run this check to confirm which fields actually reach props at runtime (af-core shapes the state — it is not a raw copy of model.json):
 
 ```bash
+cd packages/react-vanilla-components
 node -e "
 const {createFormInstance} = require('@aemforms/af-core');
-const form = createFormInstance({items:[/* paste CRISP JSON item here */]});
+const form = createFormInstance({items:[
+  /* paste the model.json item here */
+]});
 console.log(JSON.stringify(form.items[0].getState(), null, 2));
 "
 ```
 
-Read the output and confirm which fields are present and what their values look like. Do this especially for constraint fields and default values.
-
 ### Known af-core state shaping rules
 
-**`minimum` / `maximum` in state:**
-- af-core only preserves these in state for `type: 'number'`, `type: 'integer'`, and `type: 'string'` with `format: 'date'`.
-- For any other `type`+`format` combination, af-core explicitly clears them from state (`Field.js` line ~148). The validation engine still uses them internally and `constraintMessages` still fires, but the component never sees the raw values.
-- **Impact:** if you need `min`/`max` HTML attributes for a non-numeric, non-date field, the values will not be in `props`. Use the `afs:layout` side-channel (see below).
+**`minimum` / `maximum`:**
+- Preserved in state for `type: 'number'`, `type: 'integer'`, and `type: 'string'` with `format: 'date'`.
+- **Cleared from state** for all other `type`+`format` combinations. The validation engine still fires internally, but the component never sees the raw values as props.
+- If the component needs these as HTML attributes and they are cleared, use the `afs:layout` side-channel (see below).
 
-**`constraintMessages`:** always present in state as-is. af-core sets `props.errorMessage` automatically when a constraint is violated. The component does not handle constraint messages — `FieldWrapper` renders `props.errorMessage`.
+**`constraintMessages`:** always present in state as-is. af-core sets `props.errorMessage` when a constraint fires. The component never handles this — `FieldWrapper` renders it.
 
-**`default` value format:** the CRISP JSON `default` becomes `props.value` on first render. af-core may store it differently from what the HTML input requires (e.g. a string value may have a different date/time separator or include seconds). Always check the actual value in state and normalise if needed.
+**`default` value format:** af-core may store the default in a different format than the HTML input requires (e.g. `datetime-local` requires `YYYY-MM-DDTHH:MM` but af-core may surface `YYYY-MM-DD HH:MM:SS`). Always check the actual state value and normalise if needed.
 
 **`properties` object:** passes through to state unchanged. `withRuleEngine` additionally maps `properties['afs:layout']` → `props.layout` as `{[key: string]: any}`.
 
-**Props not in the `PROPS` TypeScript type:** some state fields exist at runtime but are absent from the `FieldJson` typings. If you need them, access via `(props as any).fieldName`. Do this only when the state check confirms the field exists.
-
-### `afs:layout` as a general side-channel
+### `afs:layout` side-channel
 
-When a CRISP JSON constraint is cleared by af-core and you still need its value in the component (e.g. for an HTML attribute), the author can duplicate the value into `properties['afs:layout']` under a custom key. `withRuleEngine` maps the entire `afs:layout` object to `props.layout`, so any custom key placed there survives af-core processing intact.
+When af-core clears a constraint that the component still needs for an HTML attribute, the author duplicates the value into `properties['afs:layout']` under a named key. `withRuleEngine` maps the entire `afs:layout` object to `props.layout`, so it survives af-core processing.
 
 ```json
 "properties": {
   "afs:layout": {
-    "myConstraintValue": "..."
+    "sliderMin": 1,
+    "sliderMax": 10
   }
 }
 ```
 
 ```tsx
-const myValue = layout?.myConstraintValue;
+const sliderMin = layout?.sliderMin;
+const sliderMax = layout?.sliderMax;
 ```
 
-Name the custom key clearly (e.g. `sliderMin`, `sliderMax`) to distinguish it from standard af-core layout keys.
+Name custom keys clearly (e.g. `sliderMin`, not `min`) to distinguish from standard af-core layout keys.
+
+### After running the state check
+
+Report to the user:
+- Which fields are present in state and their actual types/values
+- Which fields from model.json are absent from state
+- Whether value normalisation is needed
+- Whether any constraints need the `afs:layout` side-channel
+
+**If the state check output contradicts the model.json analysis, update Phase 1 confirmation before generating code.**
 
 ---
 
-## Step 1 — Create the component file
+## Phase 3 — Generate the component file
 
 File: `packages/react-vanilla-components/src/components/{ComponentName}.tsx`
 
-### Base template (adapt per component type)
+Use the **exact** BEM block, `data-cmp-is`, wrapper div structure, and state modifier classes extracted from the HTL in Phase 0e. Do not invent or guess these — they must match the core components markup so that the existing core component CSS applies correctly to the headless output.
+
+### License header (always include)
 
 ```tsx
 // *******************************************************************************
-//  * Copyright 2023 Adobe
+//  * Copyright 2026 Adobe
 //  *
 //  * Licensed under the Apache License, Version 2.0 (the "License");
 //  * you may not use this file except in compliance with the License.
@@ -130,7 +301,11 @@ File: `packages/react-vanilla-components/src/components/{ComponentName}.tsx`
 //  * BEM markup follows AEM core form components guidelines.
 //  * LINK- https://github.com/adobe/aem-core-forms-components
 //  ******************************************************************************
+```
+
+### Base template (simple input field)
 
+```tsx
 import React, { useCallback } from 'react';
 import { withRuleEngine } from '../utils/withRuleEngine';
 import { PROPS } from '../utils/type';
@@ -151,22 +326,20 @@ const {ComponentName} = (props: PROPS) => {
     appliedCssClassNames,
     valid,
     layout,
-    // destructure additional PROPS-typed fields here (minimum, maximum, minLength, maxLength, pattern, etc.)
-    // for runtime-only state fields not in PROPS typings, use: const x = (props as any).fieldName;
+    // add constraint props confirmed by state check:
+    // minimum, maximum, minLength, maxLength, pattern, etc.
+    // for runtime-only fields not in PROPS typings: const x = (props as any).fieldName;
   } = props;
 
   // Normalise value if the HTML input format differs from af-core's stored format.
-  // Example: number → ensure it's a string; date-time → replace space separator with T.
   const finalValue = value === undefined ? '' : value;
 
   const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
     props.dispatchChange(e.target.value);
   }, [props.dispatchChange]);
 
-  // dispatchBlur: call with no argument for most field types.
-  // Call with the current value (e.target.value) only when the field needs to
-  // re-submit its value on blur (e.g. text-input, date-input). Match the pattern
-  // of the closest existing similar component.
+  // dispatchBlur: call with e.target.value for text-like inputs that re-submit on blur.
+  // Call with no argument for date, number, select, checkbox, file inputs.
   const handleBlur = useCallback(() => {
     props.dispatchBlur();
   }, [props.dispatchBlur]);
@@ -210,7 +383,7 @@ const {ComponentName} = (props: PROPS) => {
           aria-label={label?.value}
           aria-invalid={!valid}
           aria-describedby={syncAriaDescribedBy(id, props.tooltip, props.description, props.errorMessage)}
-          // add constraint HTML attributes derived from state check:
+          // constraint HTML attributes confirmed by state check:
           // min / max / minLength / maxLength / step / pattern / accept / multiple
         />
       </FieldWrapper>
@@ -221,58 +394,61 @@ const {ComponentName} = (props: PROPS) => {
 export default withRuleEngine({ComponentName});
 ```
 
-### Adaptation rules by component category
+### Adaptation rules by category
 
-**Text inputs** (`<input type="text/email/url/tel/password">`):
-- `dispatchBlur(event.target.value)` — text inputs re-submit value on blur.
-- Destructure `minLength`, `maxLength`, `pattern` from `props` (all typed in `PROPS`).
+**Text inputs** (`type="text/email/url/tel/password"`):
+- `dispatchBlur(event.target.value)` — text inputs re-submit value on blur
+- Destructure `minLength`, `maxLength`, `pattern` from `props`
 
-**Numeric inputs** (`<input type="number">`):
-- `minimum` and `maximum` are typed as `number` in `PROPS` — destructure directly.
-- Map to `min` / `max` HTML attributes.
-- Include `step` if present.
+**Numeric inputs** (`type="number"`):
+- `minimum` and `maximum` typed as `number` in `PROPS` — destructure directly
+- Map to `min` / `max` HTML attributes
+- Include `step` if present in state
 
-**Date inputs** (`<input type="date">`):
-- `minimum` / `maximum` are surfaced as strings in state for `format: 'date'`.
-- Map to `min` / `max` HTML attributes.
+**Date inputs** (`type="date"`):
+- `minimum` / `maximum` surfaced as strings for `format: 'date'`
+- Map to `min` / `max` HTML attributes
 
-**Select / options** (components with `enum`/`enumNames`):
-- Render `<select>` with `<option>` per enum value.
-- Use `isMultiSelect` (from props, set by `withRuleEngine`) to conditionally add `multiple`.
-- `handleChange` dispatches `event.target.value`; for multi-select, collect `Array.from(event.target.selectedOptions, o => o.value)`.
+**datetime-local** (`type="datetime-local"`):
+- af-core stores value with space separator and seconds (`YYYY-MM-DD HH:MM:SS`)
+- datetime-local input requires `YYYY-MM-DDTHH:MM` — write normalisation helper
+- `minimum` / `maximum` may be cleared by af-core — use `afs:layout` side-channel or verify via state check
 
-**Checkbox / Switch** (`<input type="checkbox">`):
-- `value` is boolean — `handleChange` dispatches `event.target.checked`.
-- State class modifier: `--checked` / `--unchecked`, not `--filled` / `--empty`.
+**Select / options** (with `enum`/`enumNames`):
+- Render `<select>` with `<option>` per enum value
+- Use `isMultiSelect` from props for conditional `multiple` attribute
+- Multi-select: `Array.from(event.target.selectedOptions, o => o.value)`
 
-**Textarea** (`<textarea>`):
-- Map `minLength`, `maxLength`, `rows`, `cols` from state/CRISP JSON.
-- `dispatchChange(event.target.value)`.
+**Checkbox / Switch** (`type="checkbox"`):
+- `value` is boolean — dispatch `event.target.checked`
+- State class modifier: `--checked` / `--unchecked` (not `--filled` / `--empty`)
 
-**Container components** (CRISP JSON has `items`):
-- Use `withRuleEnginePanel` instead of `withRuleEngine`.
-- Accept `PROPS_PANEL` type.
-- Render children via the AEM renderer. Follow `Panel.tsx` or `Accordion/Accordion.tsx` as the pattern.
+**Textarea** (`<textarea>`):
+- Map `minLength`, `maxLength`, `rows`, `cols` from state
+- `dispatchChange(event.target.value)`
 
-**Display-only components** (no user input — e.g. `PlainText`, `Image`):
-- Omit all handlers and `FieldWrapper`.
-- Render only the relevant markup using props directly.
+**Container components** (model.json has `items` array):
+- Import and use `withRuleEnginePanel` instead of `withRuleEngine`
+- Accept `PROPS_PANEL` type instead of `PROPS`
+- Render children via the AEM renderer — use `Panel.tsx` or `Accordion/Accordion.tsx` as reference
 
-**Constraints cleared by af-core** (verify via state check — see af-core contract above):
-- If a constraint the component needs is not in state, read it from `props.layout` using the `afs:layout` side-channel pattern.
-- Name the layout key clearly to distinguish it from standard af-core layout keys.
+**Display-only components** (no user input — e.g. PlainText, Image):
+- Omit all event handlers and `FieldWrapper`
+- Render only relevant markup from props directly
 
-**Value format mismatch** (verify via state check):
-- If `props.value` does not match the format required by the HTML input, write a pure normalisation helper function and apply it to `finalValue`.
-- Keep the helper small and self-contained next to the component.
+**Complex input with modal / canvas** (e.g. Scribble):
+- Use `useRef`, `useState` for internal state beyond value binding
+- Keep the modal markup inside the same component file
+- Use `dispatchChange(dataUrl)` or similar when user confirms the input
+- Reference `Scribble.tsx` as the pattern
 
 ---
 
-## Step 2 — Register in `mappings.ts`
+## Phase 4 — Register in `mappings.ts`
 
 File: `packages/react-vanilla-components/src/utils/mappings.ts`
 
-Add an import (maintain alphabetical order):
+Add import (alphabetical order):
 ```ts
 import {ComponentName} from '../components/{ComponentName}';
 ```
@@ -280,19 +456,19 @@ import {ComponentName} from '../components/{ComponentName}';
 Add entries in the `mappings` object:
 ```ts
 '{fieldType}': {ComponentName},
-// If CRISP JSON includes a ":type" resource type string:
+// If model.json has a ":type" resource type string:
 '{":type" value}': {ComponentName},
 ```
 
-Keep simple `fieldType` keys grouped together; core-components resource-type strings grouped together — match the existing file structure.
+Keep simple `fieldType` keys grouped; resource-type strings grouped — match existing file structure.
 
 ---
 
-## Step 3 — Export from `src/index.ts`
+## Phase 5 — Export from `src/index.ts`
 
 File: `packages/react-vanilla-components/src/index.ts`
 
-Add import (maintain alphabetical order):
+Add import (alphabetical order):
 ```ts
 import {ComponentName} from './components/{ComponentName}';
 ```
@@ -304,48 +480,47 @@ Add to the `export { ... }` block:
 
 ---
 
-## Step 4 — Create the test file
+## Phase 6 — Generate the test file
 
 File: `packages/react-vanilla-components/__tests__/components/{ComponentName}.test.tsx`
 
 ### Core testing rules
 
-**1. Value input — choose the right API by input type**
+**1. Input method by type**
 
 | Input type | Method | Reason |
 |---|---|---|
-| `text`, `email`, `tel`, `url`, `password` | `userEvent.type(input, value)` | JSDOM simulates keystrokes correctly |
-| `date`, `datetime-local`, `time`, `number`, `range` | `fireEvent.change(input, { target: { value } })` | JSDOM doesn't simulate native picker events; `userEvent.type` produces undefined in model |
-| `checkbox` | `userEvent.click(input)` | Toggles checked state correctly |
-| `select` | `fireEvent.change(select, { target: { value } })` | Most reliable for select elements |
+| `text`, `email`, `tel`, `url`, `password` | `userEvent.type(input, value)` | JSDOM simulates keystrokes |
+| `date`, `datetime-local`, `time`, `number`, `range` | `fireEvent.change(input, { target: { value } })` | Native picker events not simulated in JSDOM |
+| `checkbox` | `userEvent.click(input)` | Toggles checked state |
+| `select` | `fireEvent.change(select, { target: { value } })` | Most reliable for select |
 
 **2. Label/input linking**
-The `FieldWrapper` sets `label.for = input.id = "${id}-widget"`. Assert them directly:
+`FieldWrapper` sets `label.for = input.id = "${id}-widget"`. Assert directly:
 ```tsx
 expect(input.getAttribute('id')).toEqual(label.getAttribute('for'));
 // Do NOT manually append '-widget' to label.for — it is already the full id
 ```
 
-**3. Finding inputs that have no placeholder**
-Use `querySelector` with the element type:
+**3. Finding inputs without placeholder**
 ```tsx
 const input = renderResponse.container.querySelector('input[type="text"]') as HTMLInputElement;
 ```
 
 **4. Constraint attributes**
-Test constraint HTML attributes by passing the constraint in the field object. Only include constraints that your state check confirmed actually reach props. If a constraint is read from `props.layout`, pass it under `properties['afs:layout']` in the test field object.
+Only test constraints confirmed by state check. For constraints read from `props.layout`, pass them under `properties['afs:layout']` in the test field object.
 
 **5. Value normalisation**
-If you wrote a normalisation helper in the component, add a dedicated test that passes a raw af-core-style value (as confirmed by the state check) and asserts the HTML input shows the normalised form.
+If the component normalises the value, write a dedicated test: pass the raw af-core format, assert the HTML input shows the normalised form.
 
-**6. Full CRISP JSON smoke test**
-Always include a `fullField` object that mirrors the complete CRISP JSON exactly as provided, and a test that renders it without errors.
+**6. Use the model.json item as `fullField`**
+Use the exact model.json item provided by the user as the `fullField` object. This is the most realistic test fixture — it mirrors what AEM will actually send.
 
 ### Test template
 
 ```tsx
 /*
- * Copyright 2023 Adobe, Inc.
+ * Copyright 2026 Adobe, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -360,23 +535,23 @@ import { fireEvent } from '@testing-library/react';
 import { renderComponent, DEFAULT_ERROR_MESSAGE } from '../utils';
 import '@testing-library/jest-dom/extend-expect';
 
-// Minimal field — only the properties needed to render the component
+// Minimal field — only properties needed to render
 const field = {
   name: '{fieldName}',
   label: { value: '{Human Readable Label}', visible: true },
   fieldType: '{fieldType}',
   type: '{type}',
-  // format: '{format}',  // include if present in CRISP JSON
+  // format: '{format}',  // include if present in model.json
   visible: true,
   required: true,
   enabled: true,
   readOnly: false,
 };
 
-// Full CRISP JSON — all properties exactly as provided. Include workaround keys
-// (e.g. in properties['afs:layout']) for any constraints cleared by af-core.
+// Full field — exact model.json item as provided by the user.
+// This is what AEM will actually send at runtime.
 const fullField = {
-  // paste full CRISP JSON item here
+  // paste model.json item here exactly
 };
 
 const helper = renderComponent({ComponentName});
@@ -385,7 +560,6 @@ describe('{ComponentName}', () => {
 
   test('value changed by user is set in model', async () => {
     const { renderResponse, element } = await helper(field);
-    // Choose method based on input type — see testing rules above
     const input = renderResponse.container.querySelector('input[type="{htmlInputType}"]') as HTMLInputElement;
     fireEvent.change(input, { target: { value: '{sampleValue}' } });
     expect(element.getState().value).toEqual('{sampleValue}');
@@ -450,14 +624,14 @@ describe('{ComponentName}', () => {
     expect(renderResponse.container.innerHTML).toContain('<strong>{Human Readable Label}</strong>');
   });
 
-  // Add constraint-specific tests based on what your state check confirmed reaches props:
-  // - min/max: test({ ...field, minimum: X, maximum: Y }) → expect(input).toHaveAttribute('min', X)
+  // Add constraint-specific tests based on state check results:
+  // - min/max: helper({ ...field, minimum: X, maximum: Y }) → expect(input).toHaveAttribute('min', String(X))
   // - minLength/maxLength: type a long string, assert model value is capped
-  // - pattern: assert the attribute is on the input element
-  // - accept (file): assert the attribute is on the input element
+  // - pattern: expect(input).toHaveAttribute('pattern', '...')
   // - Value normalisation: pass raw af-core value, assert input.value shows normalised form
+  // - afs:layout side-channel: pass properties['afs:layout'] key, assert HTML attribute is set
 
-  test('full CRISP JSON renders without errors', async () => {
+  test('full model.json field renders without errors', async () => {
     const { renderResponse } = await helper(fullField);
     expect(renderResponse.container.querySelector('input[type="{htmlInputType}"]')).not.toBeNull();
     expect(renderResponse.queryByText('{Human Readable Label}')).not.toBeNull();
@@ -467,9 +641,9 @@ describe('{ComponentName}', () => {
 
 ---
 
-## Step 5 — Verify
+## Phase 7 — Verify
 
-Run **from inside the package directory** (critical — see troubleshooting below):
+Run **from inside the package directory**:
 
 ```bash
 cd packages/react-vanilla-components
@@ -477,38 +651,35 @@ npm run build
 npx jest __tests__/components/{ComponentName}.test.tsx --no-coverage
 ```
 
-Fix all errors before reporting done.
-
----
-
-## Troubleshooting
+Fix all errors before reporting done. Common failures and their causes:
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `Property 'X' does not exist on type 'PROPS'` | State field exists at runtime but is absent from TypeScript typings | Access via `(props as any).X` |
-| Test fails: `value` is `undefined` after `userEvent.type` | Input type doesn't accept keystroke simulation in JSDOM | Switch to `fireEvent.change` |
-| Test fails: label/input ID mismatch with double `-widget` | Assertion manually appended `-widget` to `label.for` which already contains it | Assert `input.id === label.for` directly |
-| Test fails: `Missing semicolon` on `as Type` cast | Jest ran from repo root, picked up Babel config without TS support | Always `cd packages/react-vanilla-components` first |
-| Constraint (min/max/etc.) is `undefined` in props despite being in CRISP JSON | af-core clears it from state for this `type`+`format` combination | Run state check; use `afs:layout` side-channel if value is needed as HTML attribute |
-| HTML input shows wrong value format | af-core stores default/value in a different format than the input requires | Add a normalisation helper; verify expected format with state check |
+| `Property 'X' does not exist on type 'PROPS'` | Runtime state field not in TS typings | `(props as any).X` |
+| `value` is `undefined` after `userEvent.type` | Input type doesn't accept keystroke simulation in JSDOM | Switch to `fireEvent.change` |
+| Label/input ID mismatch with double `-widget` | Assertion manually appended `-widget` to `label.for` | Assert `input.id === label.for` directly — `label.for` already is the full id |
+| `Missing semicolon` on `as Type` cast | Jest ran from repo root — Babel config without TS support | Always `cd packages/react-vanilla-components` first |
+| Constraint is `undefined` in props | af-core cleared it from state | Run state check; use `afs:layout` if HTML attribute is needed |
+| HTML input shows wrong value format | af-core stores value in different format | Add normalisation helper; confirm expected format via state check |
 
 ---
 
 ## Checklist before finishing
 
-- [ ] State check run (`createFormInstance` + `getState()`) before writing the component — props match state, not raw CRISP JSON
-- [ ] BEM block name: `cmp-adaptiveform-{lowercasename}`; `data-cmp-is`: `adaptiveForm{PascalName}`
+- [ ] model.json item analysed and confirmed with user before writing any code
+- [ ] af-core state check run — props match actual state, not raw model.json
+- [ ] BEM block: `cmp-adaptiveform-{lowercasename}` — `data-cmp-is`: `adaptiveForm{PascalName}`
 - [ ] Outer `<div>` has all five `data-cmp-*` attributes
-- [ ] `<input>` / `<select>` / `<textarea>` has `id="${id}-widget"`, `aria-label`, `aria-invalid`, `aria-describedby`
+- [ ] Widget element (`input`/`select`/`textarea`/custom) has `id="${id}-widget"`, `aria-label`, `aria-invalid`, `aria-describedby`
 - [ ] `FieldWrapper` receives `bemBlock`, `label`, `id`, `tooltip`, `description`, `isError`, `errorMessage`
-- [ ] Constraint props: typed ones destructured from `props`; runtime-only ones via `(props as any).X` or `props.layout.X`
-- [ ] `dispatchBlur` called correctly for the field type (with or without value argument)
-- [ ] Default export is `withRuleEngine({ComponentName})`, not the bare component function
-- [ ] `mappings.ts` has entries for `fieldType` and `":type"` resource type (if present)
+- [ ] Typed constraint props destructured from `props`; runtime-only ones via `(props as any).X` or `props.layout.X`
+- [ ] `dispatchBlur` called correctly — with value for text-like inputs, without for others
+- [ ] Default export is `withRuleEngine({ComponentName})` (or `withRuleEnginePanel` for containers), not the bare function
+- [ ] `mappings.ts` has entries for `fieldType` and `":type"` resource type (if present in model.json)
 - [ ] `src/index.ts` imports and re-exports the component
 - [ ] Value normalisation applied if state check showed format mismatch
-- [ ] Test uses correct input method per input type (see testing rules table)
+- [ ] Test uses correct input method per input type
 - [ ] Test label/input linking: `input.id === label.for` (no manual `-widget` suffix)
-- [ ] `fullField` smoke test covers the complete CRISP JSON
-- [ ] `npm run build` clean (no TS errors) — run from inside package dir
+- [ ] `fullField` in tests uses the exact model.json item provided by the user
+- [ ] `npm run build` clean — run from inside package dir
 - [ ] All Jest tests pass — run from inside package dir
diff --git a/README.md b/README.md
index 9326b94..4845ccd 100644
--- a/README.md
+++ b/README.md
@@ -45,3 +45,63 @@ npx lerna run test
 # Contributing
 
 Please raise an issue and a PR.
+
+---
+
+# Claude Code Skills
+
+This repo ships Claude Code skills for accelerating component development. Requires [Claude Code](https://claude.ai/code).
+
+## `/create-component` — Scaffold a new headless form component
+
+Generates a complete new component for `react-vanilla-components`: component source, test suite, `mappings.ts` registration, and `index.ts` export.
+
+### Prerequisites
+
+- Claude Code installed and running inside this repo
+- AEM instance available **or** ability to describe the component (Claude will infer the field shape)
+- (Optional but recommended) `aem-core-forms-components` cloned as a sibling directory — Claude reads the HTL template from it for exact BEM class names and markup structure:
+
+```
+parent/
+├── aem-forms-headless-components/   ← this repo
+└── aem-core-forms-components/       ← sibling (optional)
+```
+
+If the sibling repo is absent, Claude fetches the HTL from GitHub automatically via `gh` CLI.
+
+### How to invoke
+
+Type in the Claude Code prompt (no arguments required — the skill is interactive):
+
+```
+/create-component
+```
+
+### What the skill asks for (interactively)
+
+1. **Component name** — PascalCase, e.g. `RatingInput`
+2. **model.json item** — paste the field object from your AEM form's `.model.json` endpoint:
+   ```
+   http://localhost:4502/content/forms/af/<form-name>.model.json
+   ```
+   Find the `items` array and paste the object for your field. If you have no AEM instance, describe the component and Claude infers the shape.
+3. **Special behaviors** — modal, canvas, file upload, display-only, container, or none
+4. **Reference component** — closest existing component to use as style reference (or "none")
+
+### What Claude does automatically
+
+- Reads the HTL template from `aem-core-forms-components` (local or GitHub) for exact BEM names
+- Runs an af-core state check to confirm which props actually arrive at runtime
+- Shows a confirmation summary — you approve before any code is written
+- Generates the component, tests, and registration files
+- Runs `npm run build` and Jest — fixes errors before reporting done
+
+### What gets generated
+
+| File | Description |
+|---|---|
+| `packages/react-vanilla-components/src/components/{Name}.tsx` | Component source |
+| `packages/react-vanilla-components/__tests__/components/{Name}.test.tsx` | Test suite |
+| `packages/react-vanilla-components/src/utils/mappings.ts` | Updated with new fieldType / resource type keys |
+| `packages/react-vanilla-components/src/index.ts` | Updated export |

From 154a9f94a09fba0012f70037d897f2963763e524 Mon Sep 17 00:00:00 2001
From: Armaan Gupta <armaang@Armaans-MacBook-Pro.local>
Date: Sat, 15 Aug 2026 23:08:10 +0530
Subject: [PATCH 4/4] feat(skill) : improved create core component skill to
 handle complex components like table

---
 .claude/commands/create-component.md | 249 ++++++++++++++++-----------
 .claude/skills/create-component.md   | 247 ++++++++++++++++----------
 2 files changed, 306 insertions(+), 190 deletions(-)

diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.md
index 5b873e7..1374d72 100644
--- a/.claude/commands/create-component.md
+++ b/.claude/commands/create-component.md
@@ -3,8 +3,6 @@ description: Scaffold a complete new headless form component for react-vanilla-c
 allowed-tools: Read, Edit, Write, Bash
 ---
 
-# Skill: create-component
-
 ## Trigger
 Invoked when the user asks to **create a new headless form component** for the `react-vanilla-components` package. This skill is interactive — it gathers information in phases, confirms interpretation before writing code, then generates the component, tests, and registration.
 
@@ -19,41 +17,9 @@ Do NOT write any code until you have completed this phase.
 If the user did not provide a component name, ask:
 > What is the component name? (PascalCase, e.g. `RatingInput`, `ColorPicker`, `PhoneInput`)
 
-### 0b — model.json item
-
-Ask the user to paste the **model.json item** for the component. Explain what this is if they look unsure:
-
-> The model.json is the JSON output AEM Core Components returns when you render a form and call the form's `.model.json` endpoint (e.g. `http://localhost:4502/content/forms/af/<form-name>.model.json`).
->
-> From the response, find the `items` array and paste the single **object that represents this field**. It will look like:
-> ```json
-> {
->   "id": "telephoneinput-abc123",
->   "fieldType": "text-input",
->   ":type": "core/fd/components/form/telephoneinput/v1/telephoneinput",
->   "name": "telephoneInput1",
->   "label": { "value": "Phone Number", "visible": true },
->   "type": "string",
->   "visible": true,
->   "required": false,
->   "enabled": true,
->   "readOnly": false,
->   "constraintMessages": {},
->   "properties": {
->     "afs:layout": { "tooltipVisible": false },
->     "fd:path": "/content/forms/af/myform/jcr:content/guideContainer/telephoneinput"
->   }
-> }
-> ```
->
-> If you don't have access to an AEM instance, describe the component's intended behavior and known properties and I'll infer the field shape.
-
-**If the user provides a model.json item:** proceed to Phase 1.
-**If the user describes the component instead:** construct a best-guess field object, show it to the user, and ask them to confirm or correct it before proceeding.
+### 0b — Special behaviors
 
-### 0c — Special behaviors
-
-After receiving the model.json, ask:
+Ask:
 
 > Does this component have any of the following special behaviors? (answer all that apply)
 > - **Modal / dialog** (opens a popup for input — like Scribble's canvas dialog)
@@ -67,7 +33,7 @@ After receiving the model.json, ask:
 
 This determines the component template and which HOC (`withRuleEngine` vs `withRuleEnginePanel`) to use.
 
-### 0d — Reference component
+### 0c — Reference component
 
 Ask:
 > Is there an existing component in this repo that is most similar? (e.g. "similar to DateTimeInput", "similar to Scribble", "similar to DropDown")
@@ -76,15 +42,11 @@ Ask:
 
 Look at `packages/react-vanilla-components/src/components/` and pick the closest existing component as a reference for the implementation style.
 
-### 0e — Read core components HTL for ground-truth markup
+### 0d — Read HTL from core components for ground-truth markup
 
 The HTL template in `aem-core-forms-components` is the authoritative source for BEM class names, `data-cmp-*` attributes, CSS modifier classes, and widget element structure. Read it before writing any code.
 
-Derive the component folder name from the `":type"` resource type path. For example:
-- `":type": "core/fd/components/form/telephoneinput/v1/telephoneinput"` → folder `telephoneinput`
-- `":type": "core/fd/components/form/ratinginput/v1/ratinginput"` → folder `ratinginput`
-
-If `":type"` is absent, derive from the component name lowercased.
+Derive the component folder name from the component name lowercased (e.g. `RatingInput` → `ratinginput`).
 
 **Step 1 — Check for local sibling repo:**
 ```bash
@@ -96,20 +58,13 @@ ls ../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/f
 cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/{componentfolder}.html"
 ```
 
-Also read the CRISP JSON (component dialog / schema definition) if present:
-```bash
-cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/.content.xml" 2>/dev/null
-# or look for _cq_dialog or model JSON files in the component folder
-ls "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/"
-```
-
 **Step 2b — If local repo does not exist, fetch from GitHub:**
 ```bash
 gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/{componentfolder}.html" \
   --jq '.content' | base64 -d
 ```
 
-If `gh` is unavailable, fall back to listing the folder to find the right filename:
+If `gh` is unavailable, list the folder first:
 ```bash
 gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}" \
   --jq '.[].name'
@@ -117,8 +72,6 @@ gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/conte
 
 **Step 3 — Extract from HTL:**
 
-Read the HTL output and extract:
-
 | HTL element | What to record |
 |---|---|
 | Root `<div>` class string | Exact BEM block name (e.g. `cmp-adaptiveform-telephoneinput`) |
@@ -126,37 +79,128 @@ Read the HTL output and extract:
 | All `data-cmp-*` attributes | Any beyond the standard five — note names and values |
 | State modifier classes | `--filled`/`--empty`, `--checked`/`--unchecked`, `--disabled`, custom |
 | Widget element | Tag name, nesting depth, wrapper divs, class names |
-| Extra wrapper divs | e.g. `__input-wrapper`, `__options-wrapper` present in DateTimeInput |
+| Extra wrapper divs | e.g. `__input-wrapper`, `__options-wrapper` |
 | CSS custom properties | Any `--cmp-*` CSS variables set inline |
 
-If the HTL file is not found (new/private component), fall back to inferring BEM names from the model.json `fieldType` and component name. State this explicitly in the Phase 1 confirmation.
+If HTL not found (new/private component), fall back to inferring BEM from component name. State this explicitly.
+
+### 0e — Read Sling Model from core components for ground-truth schema
+
+The Sling Model interface is the authoritative source for what properties, constraints, and `fieldType`/`":type"` the component exports to JSON. This replaces asking the user for form-specific model.json.
 
-**Step 4 — Read the existing headless implementation if any:**
+**Step 1 — Find the Java model interface:**
+
+```bash
+# Local repo
+find ../aem-core-forms-components/core/src/main/java -name "{ComponentName}.java" 2>/dev/null
+# or
+ls ../aem-core-forms-components/core/src/main/java/com/adobe/cq/forms/core/components/models/form/ 2>/dev/null | grep -i {componentfolder}
+```
+
+If local repo absent, fetch from GitHub:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/core/src/main/java/com/adobe/cq/forms/core/components/models/form" \
+  --jq '.[].name' | grep -i {componentfolder}
+```
+
+Then read the interface file:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/core/src/main/java/com/adobe/cq/forms/core/components/models/form/{ComponentName}.java" \
+  --jq '.content' | base64 -d
+```
+
+**Step 2 — Also read the Sling Model implementation:**
+
+```bash
+# Local
+find ../aem-core-forms-components/core/src/main/java -name "{ComponentName}Impl.java" 2>/dev/null | head -3
+```
+
+Or from GitHub:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/core/src/main/java/com/adobe/cq/forms/core/components/internal/models/v1/form/{ComponentName}Impl.java" \
+  --jq '.content' | base64 -d
+```
+
+**Step 3 — Extract from Sling Model:**
+
+| Java annotation / method | What to record |
+|---|---|
+| `@Model` `resourceType` | The `":type"` string registered in mappings |
+| Methods returning `String fieldType()` | The `fieldType` key for mappings |
+| `@Default` on getters | Default values for props |
+| Getter return types | Prop types (`String`, `Boolean`, `Number`, `String[]`) |
+| Methods named `getMinimum`, `getMaximum`, `getMinLength`, etc. | Active constraints |
+| `getType()` / `getFormat()` | Data type and format — determines HTML input type |
+| `getEnum()` / `getEnumNames()` | Present → select-type component |
+| `getItems()` | Present → container component |
+| `getProperties()` | Extra properties passed through `afs:layout` |
+
+**Step 4 — Read component `.content.xml` for `fieldType` and `resourceType` if not in Java:**
+
+```bash
+# Local
+cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/.content.xml" 2>/dev/null
+```
+
+Or GitHub:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/.content.xml" \
+  --jq '.content' | base64 -d
+```
+
+**Step 5 — Construct the minimal field object from code:**
+
+Using what you read from HTL + Sling Model, construct the field schema. This is NOT form-specific — it is the canonical shape of what the component exports:
+
+```json
+{
+  "fieldType": "<from Sling Model / .content.xml>",
+  ":type": "core/fd/components/form/{componentfolder}/v1/{componentfolder}",
+  "type": "<string|number|integer|boolean>",
+  "format": "<date|date-time|time|email|uri|tel — if applicable>",
+  "name": "{componentfolder}1",
+  "label": { "value": "<ComponentName>", "visible": true },
+  "visible": true,
+  "required": false,
+  "enabled": true,
+  "readOnly": false,
+  "constraintMessages": {}
+  // add minimum, maximum, minLength, maxLength, pattern, enum, enumNames
+  // only if Sling Model exposes those getters
+}
+```
+
+If the Sling Model / HTL files are not found, ask:
+> I couldn't find the component in `aem-core-forms-components`. Do you have a model.json item from an AEM instance, or can you describe the component's properties?
+
+Only fall back to user-provided model.json when the code is genuinely unavailable.
+
+**Step 6 — Read the existing headless implementation if any:**
 
-Check if a reference headless component for this field type already exists (e.g. a partial or older implementation):
 ```bash
 ls packages/react-vanilla-components/src/components/ | grep -i {componentfolder}
 ```
 
 ---
 
-## Phase 1 — Analyze the model.json (before writing code)
+## Phase 1 — Analyze the component schema (before writing code)
 
-Extract and verify these fields from the model.json item. Show your analysis to the user before proceeding.
+Using the field schema derived from code (Phase 0e), show your analysis to the user before proceeding.
 
 ### 1a — Key fields to extract
 
-| model.json field | What to derive |
+| Schema field | What to derive |
 |---|---|
 | `fieldType` | Primary key in `mappings.ts` |
-| `":type"` | Secondary key in `mappings.ts` (resource type string) — may be absent if custom |
+| `":type"` | Secondary key in `mappings.ts` (resource type string) |
 | `type` + `format` | HTML element and input type (see table below) |
-| `enum` / `enumNames` | Indicates select-type component |
+| `enum` / `enumNames` present | Select-type component |
 | `items` present | Container component — use `withRuleEnginePanel` |
-| `minimum` / `maximum` | Check type compatibility (see af-core contract) |
+| `minimum` / `maximum` getters | Check type compatibility (see af-core contract) |
 | `constraintMessages` | Lists which constraints are active |
-| `properties['afs:layout']` | Layout side-channel keys the author already uses |
-| `default` | Becomes `props.value` on first render — check format compatibility |
+| `properties['afs:layout']` | Layout side-channel keys |
+| `default` getter | Becomes `props.value` on first render — check format compatibility |
 
 ### 1b — `type` + `format` → HTML element
 
@@ -176,7 +220,7 @@ Extract and verify these fields from the model.json item. Show your analysis to
 
 ### 1c — Naming derivations
 
-Use values read from the HTL template (Phase 0e) as the authoritative source. Fall back to inference only when HTL was unavailable.
+Use values read from the HTL template (Phase 0d) as the authoritative source. Fall back to inference only when HTL was unavailable.
 
 - **BEM block**: read from HTL root `<div>` class — e.g. `cmp-adaptiveform-telephoneinput`
 - **`data-cmp-is`**: read from HTL `data-cmp-is` attribute — e.g. `adaptiveFormTelephoneInput`
@@ -184,7 +228,7 @@ Use values read from the HTL template (Phase 0e) as the authoritative source. Fa
 - **State modifier classes**: use exactly the modifiers from HTL (`--filled`/`--empty`, `--checked`, etc.)
 - **File name**: `{ComponentName}.tsx`
 
-If HTL was not available, infer: BEM block = `cmp-adaptiveform-{lowercasename}`, `data-cmp-is` = `adaptiveForm{PascalName}`, and flag this in the confirmation.
+If HTL was not available, infer: BEM block = `cmp-adaptiveform-{lowercasename}`, `data-cmp-is` = `adaptiveForm{PascalName}`, and flag this.
 
 ### 1d — Show analysis and confirm
 
@@ -193,24 +237,25 @@ Before writing any code, output a confirmation block like this:
 ```
 Component: RatingInput
 File: src/components/RatingInput.tsx
-fieldType: "rating-input"
-":type": "core/fd/components/form/ratinginput/v1/ratinginput"  (or absent)
+fieldType: "rating-input"                              ← from Sling Model / .content.xml
+":type": "core/fd/components/form/ratinginput/v1/ratinginput"   ← from Sling Model resourceType
 HTML element: <input type="number">
-BEM block: cmp-adaptiveform-ratinginput          ← from HTL (or inferred)
-data-cmp-is: adaptiveFormRatingInput             ← from HTL (or inferred)
-Extra wrappers: none                             ← or e.g. "__input-wrapper div present"
-State modifiers: --filled / --empty              ← from HTL
+BEM block: cmp-adaptiveform-ratinginput               ← from HTL
+data-cmp-is: adaptiveFormRatingInput                  ← from HTL
+Extra wrappers: none
+State modifiers: --filled / --empty                   ← from HTL
 HOC: withRuleEngine
 Reference component: NumberField.tsx
 
-Constraints present: minimum, maximum
+Constraints present in Sling Model: minimum, maximum
 Constraints af-core may clear: none for type=number
 Value normalisation needed: no
 afs:layout side-channel needed: no
 
 Special behaviors: none
 
-HTL source: local sibling repo  (or: GitHub fetch, or: not found — inferred)
+Schema source: Sling Model (local repo)  [or: GitHub, or: not found — inferred]
+HTL source: local sibling repo           [or: GitHub, or: not found — inferred]
 
 Does this look right? Any corrections before I proceed?
 ```
@@ -221,14 +266,14 @@ Does this look right? Any corrections before I proceed?
 
 ## Phase 2 — af-core state check
 
-Run this check to confirm which fields actually reach props at runtime (af-core shapes the state — it is not a raw copy of model.json):
+Run this check to confirm which fields actually reach props at runtime (af-core shapes the state — it is not a raw pass-through of the JSON):
 
 ```bash
 cd packages/react-vanilla-components
 node -e "
 const {createFormInstance} = require('@aemforms/af-core');
 const form = createFormInstance({items:[
-  /* paste the model.json item here */
+  /* paste the minimal field object constructed in Phase 0e Step 5 */
 ]});
 console.log(JSON.stringify(form.items[0].getState(), null, 2));
 "
@@ -271,11 +316,11 @@ Name custom keys clearly (e.g. `sliderMin`, not `min`) to distinguish from stand
 
 Report to the user:
 - Which fields are present in state and their actual types/values
-- Which fields from model.json are absent from state
+- Which fields from the constructed schema are absent from state
 - Whether value normalisation is needed
 - Whether any constraints need the `afs:layout` side-channel
 
-**If the state check output contradicts the model.json analysis, update Phase 1 confirmation before generating code.**
+**If the state check output contradicts the schema analysis, update Phase 1 confirmation before generating code.**
 
 ---
 
@@ -283,7 +328,7 @@ Report to the user:
 
 File: `packages/react-vanilla-components/src/components/{ComponentName}.tsx`
 
-Use the **exact** BEM block, `data-cmp-is`, wrapper div structure, and state modifier classes extracted from the HTL in Phase 0e. Do not invent or guess these — they must match the core components markup so that the existing core component CSS applies correctly to the headless output.
+Use the **exact** BEM block, `data-cmp-is`, wrapper div structure, and state modifier classes extracted from the HTL in Phase 0d. Do not invent or guess these — they must match the core components markup so that the existing core component CSS applies correctly to the headless output.
 
 ### License header (always include)
 
@@ -432,7 +477,7 @@ export default withRuleEngine({ComponentName});
 - Map `minLength`, `maxLength`, `rows`, `cols` from state
 - `dispatchChange(event.target.value)`
 
-**Container components** (model.json has `items` array):
+**Container components** (Sling Model has `getItems()`):
 - Import and use `withRuleEnginePanel` instead of `withRuleEngine`
 - Accept `PROPS_PANEL` type instead of `PROPS`
 - Render children via the AEM renderer — use `Panel.tsx` or `Accordion/Accordion.tsx` as reference
@@ -461,8 +506,8 @@ import {ComponentName} from '../components/{ComponentName}';
 Add entries in the `mappings` object:
 ```ts
 '{fieldType}': {ComponentName},
-// If model.json has a ":type" resource type string:
-'{":type" value}': {ComponentName},
+// Resource type string from Sling Model @Model resourceType:
+'core/fd/components/form/{componentfolder}/v1/{componentfolder}': {ComponentName},
 ```
 
 Keep simple `fieldType` keys grouped; resource-type strings grouped — match existing file structure.
@@ -518,8 +563,8 @@ Only test constraints confirmed by state check. For constraints read from `props
 **5. Value normalisation**
 If the component normalises the value, write a dedicated test: pass the raw af-core format, assert the HTML input shows the normalised form.
 
-**6. Use the model.json item as `fullField`**
-Use the exact model.json item provided by the user as the `fullField` object. This is the most realistic test fixture — it mirrors what AEM will actually send.
+**6. `fullField` — use the canonical schema constructed from code**
+`fullField` is the minimal field object constructed in Phase 0e Step 5, not a user-pasted form-specific JSON. This keeps tests stable across different AEM form instances.
 
 ### Test template
 
@@ -546,17 +591,29 @@ const field = {
   label: { value: '{Human Readable Label}', visible: true },
   fieldType: '{fieldType}',
   type: '{type}',
-  // format: '{format}',  // include if present in model.json
+  // format: '{format}',  // include if present in schema
   visible: true,
   required: true,
   enabled: true,
   readOnly: false,
 };
 
-// Full field — exact model.json item as provided by the user.
-// This is what AEM will actually send at runtime.
+// Full field — canonical schema derived from Sling Model + HTL.
+// Stable across form instances — not a user-pasted model.json snippet.
 const fullField = {
-  // paste model.json item here exactly
+  fieldType: '{fieldType}',
+  ':type': 'core/fd/components/form/{componentfolder}/v1/{componentfolder}',
+  name: '{fieldName}',
+  label: { value: '{Human Readable Label}', visible: true },
+  type: '{type}',
+  // format: '{format}',
+  visible: true,
+  required: false,
+  enabled: true,
+  readOnly: false,
+  constraintMessages: {},
+  // include only constraints confirmed by Sling Model getters + state check:
+  // minimum: ..., maximum: ..., minLength: ..., maxLength: ..., pattern: ...
 };
 
 const helper = renderComponent({ComponentName});
@@ -636,7 +693,7 @@ describe('{ComponentName}', () => {
   // - Value normalisation: pass raw af-core value, assert input.value shows normalised form
   // - afs:layout side-channel: pass properties['afs:layout'] key, assert HTML attribute is set
 
-  test('full model.json field renders without errors', async () => {
+  test('full canonical schema field renders without errors', async () => {
     const { renderResponse } = await helper(fullField);
     expect(renderResponse.container.querySelector('input[type="{htmlInputType}"]')).not.toBeNull();
     expect(renderResponse.queryByText('{Human Readable Label}')).not.toBeNull();
@@ -671,20 +728,20 @@ Fix all errors before reporting done. Common failures and their causes:
 
 ## Checklist before finishing
 
-- [ ] model.json item analysed and confirmed with user before writing any code
-- [ ] af-core state check run — props match actual state, not raw model.json
-- [ ] BEM block: `cmp-adaptiveform-{lowercasename}` — `data-cmp-is`: `adaptiveForm{PascalName}`
+- [ ] Component schema derived from Sling Model + HTL, NOT from user-pasted model.json
+- [ ] af-core state check run using the code-derived minimal field — props match actual state
+- [ ] BEM block and `data-cmp-is` read from HTL (not inferred), or flagged as inferred if HTL unavailable
 - [ ] Outer `<div>` has all five `data-cmp-*` attributes
-- [ ] Widget element (`input`/`select`/`textarea`/custom) has `id="${id}-widget"`, `aria-label`, `aria-invalid`, `aria-describedby`
+- [ ] Widget element has `id="${id}-widget"`, `aria-label`, `aria-invalid`, `aria-describedby`
 - [ ] `FieldWrapper` receives `bemBlock`, `label`, `id`, `tooltip`, `description`, `isError`, `errorMessage`
 - [ ] Typed constraint props destructured from `props`; runtime-only ones via `(props as any).X` or `props.layout.X`
 - [ ] `dispatchBlur` called correctly — with value for text-like inputs, without for others
 - [ ] Default export is `withRuleEngine({ComponentName})` (or `withRuleEnginePanel` for containers), not the bare function
-- [ ] `mappings.ts` has entries for `fieldType` and `":type"` resource type (if present in model.json)
+- [ ] `mappings.ts` has entries for `fieldType` and resource type string from Sling Model `@Model` annotation
 - [ ] `src/index.ts` imports and re-exports the component
 - [ ] Value normalisation applied if state check showed format mismatch
 - [ ] Test uses correct input method per input type
 - [ ] Test label/input linking: `input.id === label.for` (no manual `-widget` suffix)
-- [ ] `fullField` in tests uses the exact model.json item provided by the user
+- [ ] `fullField` in tests uses canonical schema from code, not a form-specific model.json snippet
 - [ ] `npm run build` clean — run from inside package dir
 - [ ] All Jest tests pass — run from inside package dir
diff --git a/.claude/skills/create-component.md b/.claude/skills/create-component.md
index f98af41..529d9db 100644
--- a/.claude/skills/create-component.md
+++ b/.claude/skills/create-component.md
@@ -14,41 +14,9 @@ Do NOT write any code until you have completed this phase.
 If the user did not provide a component name, ask:
 > What is the component name? (PascalCase, e.g. `RatingInput`, `ColorPicker`, `PhoneInput`)
 
-### 0b — model.json item
+### 0b — Special behaviors
 
-Ask the user to paste the **model.json item** for the component. Explain what this is if they look unsure:
-
-> The model.json is the JSON output AEM Core Components returns when you render a form and call the form's `.model.json` endpoint (e.g. `http://localhost:4502/content/forms/af/<form-name>.model.json`).
->
-> From the response, find the `items` array and paste the single **object that represents this field**. It will look like:
-> ```json
-> {
->   "id": "telephoneinput-abc123",
->   "fieldType": "text-input",
->   ":type": "core/fd/components/form/telephoneinput/v1/telephoneinput",
->   "name": "telephoneInput1",
->   "label": { "value": "Phone Number", "visible": true },
->   "type": "string",
->   "visible": true,
->   "required": false,
->   "enabled": true,
->   "readOnly": false,
->   "constraintMessages": {},
->   "properties": {
->     "afs:layout": { "tooltipVisible": false },
->     "fd:path": "/content/forms/af/myform/jcr:content/guideContainer/telephoneinput"
->   }
-> }
-> ```
->
-> If you don't have access to an AEM instance, describe the component's intended behavior and known properties and I'll infer the field shape.
-
-**If the user provides a model.json item:** proceed to Phase 1.
-**If the user describes the component instead:** construct a best-guess field object, show it to the user, and ask them to confirm or correct it before proceeding.
-
-### 0c — Special behaviors
-
-After receiving the model.json, ask:
+Ask:
 
 > Does this component have any of the following special behaviors? (answer all that apply)
 > - **Modal / dialog** (opens a popup for input — like Scribble's canvas dialog)
@@ -62,7 +30,7 @@ After receiving the model.json, ask:
 
 This determines the component template and which HOC (`withRuleEngine` vs `withRuleEnginePanel`) to use.
 
-### 0d — Reference component
+### 0c — Reference component
 
 Ask:
 > Is there an existing component in this repo that is most similar? (e.g. "similar to DateTimeInput", "similar to Scribble", "similar to DropDown")
@@ -71,15 +39,11 @@ Ask:
 
 Look at `packages/react-vanilla-components/src/components/` and pick the closest existing component as a reference for the implementation style.
 
-### 0e — Read core components HTL for ground-truth markup
+### 0d — Read HTL from core components for ground-truth markup
 
 The HTL template in `aem-core-forms-components` is the authoritative source for BEM class names, `data-cmp-*` attributes, CSS modifier classes, and widget element structure. Read it before writing any code.
 
-Derive the component folder name from the `":type"` resource type path. For example:
-- `":type": "core/fd/components/form/telephoneinput/v1/telephoneinput"` → folder `telephoneinput`
-- `":type": "core/fd/components/form/ratinginput/v1/ratinginput"` → folder `ratinginput`
-
-If `":type"` is absent, derive from the component name lowercased.
+Derive the component folder name from the component name lowercased (e.g. `RatingInput` → `ratinginput`).
 
 **Step 1 — Check for local sibling repo:**
 ```bash
@@ -91,20 +55,13 @@ ls ../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/f
 cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/{componentfolder}.html"
 ```
 
-Also read the CRISP JSON (component dialog / schema definition) if present:
-```bash
-cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/.content.xml" 2>/dev/null
-# or look for _cq_dialog or model JSON files in the component folder
-ls "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/"
-```
-
 **Step 2b — If local repo does not exist, fetch from GitHub:**
 ```bash
 gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/{componentfolder}.html" \
   --jq '.content' | base64 -d
 ```
 
-If `gh` is unavailable, fall back to listing the folder to find the right filename:
+If `gh` is unavailable, list the folder first:
 ```bash
 gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}" \
   --jq '.[].name'
@@ -112,8 +69,6 @@ gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/conte
 
 **Step 3 — Extract from HTL:**
 
-Read the HTL output and extract:
-
 | HTL element | What to record |
 |---|---|
 | Root `<div>` class string | Exact BEM block name (e.g. `cmp-adaptiveform-telephoneinput`) |
@@ -121,37 +76,128 @@ Read the HTL output and extract:
 | All `data-cmp-*` attributes | Any beyond the standard five — note names and values |
 | State modifier classes | `--filled`/`--empty`, `--checked`/`--unchecked`, `--disabled`, custom |
 | Widget element | Tag name, nesting depth, wrapper divs, class names |
-| Extra wrapper divs | e.g. `__input-wrapper`, `__options-wrapper` present in DateTimeInput |
+| Extra wrapper divs | e.g. `__input-wrapper`, `__options-wrapper` |
 | CSS custom properties | Any `--cmp-*` CSS variables set inline |
 
-If the HTL file is not found (new/private component), fall back to inferring BEM names from the model.json `fieldType` and component name. State this explicitly in the Phase 1 confirmation.
+If HTL not found (new/private component), fall back to inferring BEM from component name. State this explicitly.
+
+### 0e — Read Sling Model from core components for ground-truth schema
+
+The Sling Model interface is the authoritative source for what properties, constraints, and `fieldType`/`":type"` the component exports to JSON. This replaces asking the user for form-specific model.json.
+
+**Step 1 — Find the Java model interface:**
+
+```bash
+# Local repo
+find ../aem-core-forms-components/core/src/main/java -name "{ComponentName}.java" 2>/dev/null
+# or
+ls ../aem-core-forms-components/core/src/main/java/com/adobe/cq/forms/core/components/models/form/ 2>/dev/null | grep -i {componentfolder}
+```
+
+If local repo absent, fetch from GitHub:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/core/src/main/java/com/adobe/cq/forms/core/components/models/form" \
+  --jq '.[].name' | grep -i {componentfolder}
+```
+
+Then read the interface file:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/core/src/main/java/com/adobe/cq/forms/core/components/models/form/{ComponentName}.java" \
+  --jq '.content' | base64 -d
+```
+
+**Step 2 — Also read the Sling Model implementation:**
+
+```bash
+# Local
+find ../aem-core-forms-components/core/src/main/java -name "{ComponentName}Impl.java" 2>/dev/null | head -3
+```
+
+Or from GitHub:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/core/src/main/java/com/adobe/cq/forms/core/components/internal/models/v1/form/{ComponentName}Impl.java" \
+  --jq '.content' | base64 -d
+```
+
+**Step 3 — Extract from Sling Model:**
+
+| Java annotation / method | What to record |
+|---|---|
+| `@Model` `resourceType` | The `":type"` string registered in mappings |
+| Methods returning `String fieldType()` | The `fieldType` key for mappings |
+| `@Default` on getters | Default values for props |
+| Getter return types | Prop types (`String`, `Boolean`, `Number`, `String[]`) |
+| Methods named `getMinimum`, `getMaximum`, `getMinLength`, etc. | Active constraints |
+| `getType()` / `getFormat()` | Data type and format — determines HTML input type |
+| `getEnum()` / `getEnumNames()` | Present → select-type component |
+| `getItems()` | Present → container component |
+| `getProperties()` | Extra properties passed through `afs:layout` |
+
+**Step 4 — Read component `.content.xml` for `fieldType` and `resourceType` if not in Java:**
+
+```bash
+# Local
+cat "../aem-core-forms-components/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/.content.xml" 2>/dev/null
+```
+
+Or GitHub:
+```bash
+gh api "repos/adobe/aem-core-forms-components/contents/ui.af.apps/src/main/content/jcr_root/apps/core/fd/components/form/{componentfolder}/v1/{componentfolder}/.content.xml" \
+  --jq '.content' | base64 -d
+```
+
+**Step 5 — Construct the minimal field object from code:**
+
+Using what you read from HTL + Sling Model, construct the field schema. This is NOT form-specific — it is the canonical shape of what the component exports:
+
+```json
+{
+  "fieldType": "<from Sling Model / .content.xml>",
+  ":type": "core/fd/components/form/{componentfolder}/v1/{componentfolder}",
+  "type": "<string|number|integer|boolean>",
+  "format": "<date|date-time|time|email|uri|tel — if applicable>",
+  "name": "{componentfolder}1",
+  "label": { "value": "<ComponentName>", "visible": true },
+  "visible": true,
+  "required": false,
+  "enabled": true,
+  "readOnly": false,
+  "constraintMessages": {}
+  // add minimum, maximum, minLength, maxLength, pattern, enum, enumNames
+  // only if Sling Model exposes those getters
+}
+```
+
+If the Sling Model / HTL files are not found, ask:
+> I couldn't find the component in `aem-core-forms-components`. Do you have a model.json item from an AEM instance, or can you describe the component's properties?
+
+Only fall back to user-provided model.json when the code is genuinely unavailable.
 
-**Step 4 — Read the existing headless implementation if any:**
+**Step 6 — Read the existing headless implementation if any:**
 
-Check if a reference headless component for this field type already exists (e.g. a partial or older implementation):
 ```bash
 ls packages/react-vanilla-components/src/components/ | grep -i {componentfolder}
 ```
 
 ---
 
-## Phase 1 — Analyze the model.json (before writing code)
+## Phase 1 — Analyze the component schema (before writing code)
 
-Extract and verify these fields from the model.json item. Show your analysis to the user before proceeding.
+Using the field schema derived from code (Phase 0e), show your analysis to the user before proceeding.
 
 ### 1a — Key fields to extract
 
-| model.json field | What to derive |
+| Schema field | What to derive |
 |---|---|
 | `fieldType` | Primary key in `mappings.ts` |
-| `":type"` | Secondary key in `mappings.ts` (resource type string) — may be absent if custom |
+| `":type"` | Secondary key in `mappings.ts` (resource type string) |
 | `type` + `format` | HTML element and input type (see table below) |
-| `enum` / `enumNames` | Indicates select-type component |
+| `enum` / `enumNames` present | Select-type component |
 | `items` present | Container component — use `withRuleEnginePanel` |
-| `minimum` / `maximum` | Check type compatibility (see af-core contract) |
+| `minimum` / `maximum` getters | Check type compatibility (see af-core contract) |
 | `constraintMessages` | Lists which constraints are active |
-| `properties['afs:layout']` | Layout side-channel keys the author already uses |
-| `default` | Becomes `props.value` on first render — check format compatibility |
+| `properties['afs:layout']` | Layout side-channel keys |
+| `default` getter | Becomes `props.value` on first render — check format compatibility |
 
 ### 1b — `type` + `format` → HTML element
 
@@ -171,7 +217,7 @@ Extract and verify these fields from the model.json item. Show your analysis to
 
 ### 1c — Naming derivations
 
-Use values read from the HTL template (Phase 0e) as the authoritative source. Fall back to inference only when HTL was unavailable.
+Use values read from the HTL template (Phase 0d) as the authoritative source. Fall back to inference only when HTL was unavailable.
 
 - **BEM block**: read from HTL root `<div>` class — e.g. `cmp-adaptiveform-telephoneinput`
 - **`data-cmp-is`**: read from HTL `data-cmp-is` attribute — e.g. `adaptiveFormTelephoneInput`
@@ -179,7 +225,7 @@ Use values read from the HTL template (Phase 0e) as the authoritative source. Fa
 - **State modifier classes**: use exactly the modifiers from HTL (`--filled`/`--empty`, `--checked`, etc.)
 - **File name**: `{ComponentName}.tsx`
 
-If HTL was not available, infer: BEM block = `cmp-adaptiveform-{lowercasename}`, `data-cmp-is` = `adaptiveForm{PascalName}`, and flag this in the confirmation.
+If HTL was not available, infer: BEM block = `cmp-adaptiveform-{lowercasename}`, `data-cmp-is` = `adaptiveForm{PascalName}`, and flag this.
 
 ### 1d — Show analysis and confirm
 
@@ -188,24 +234,25 @@ Before writing any code, output a confirmation block like this:
 ```
 Component: RatingInput
 File: src/components/RatingInput.tsx
-fieldType: "rating-input"
-":type": "core/fd/components/form/ratinginput/v1/ratinginput"  (or absent)
+fieldType: "rating-input"                              ← from Sling Model / .content.xml
+":type": "core/fd/components/form/ratinginput/v1/ratinginput"   ← from Sling Model resourceType
 HTML element: <input type="number">
-BEM block: cmp-adaptiveform-ratinginput          ← from HTL (or inferred)
-data-cmp-is: adaptiveFormRatingInput             ← from HTL (or inferred)
-Extra wrappers: none                             ← or e.g. "__input-wrapper div present"
-State modifiers: --filled / --empty              ← from HTL
+BEM block: cmp-adaptiveform-ratinginput               ← from HTL
+data-cmp-is: adaptiveFormRatingInput                  ← from HTL
+Extra wrappers: none
+State modifiers: --filled / --empty                   ← from HTL
 HOC: withRuleEngine
 Reference component: NumberField.tsx
 
-Constraints present: minimum, maximum
+Constraints present in Sling Model: minimum, maximum
 Constraints af-core may clear: none for type=number
 Value normalisation needed: no
 afs:layout side-channel needed: no
 
 Special behaviors: none
 
-HTL source: local sibling repo  (or: GitHub fetch, or: not found — inferred)
+Schema source: Sling Model (local repo)  [or: GitHub, or: not found — inferred]
+HTL source: local sibling repo           [or: GitHub, or: not found — inferred]
 
 Does this look right? Any corrections before I proceed?
 ```
@@ -216,14 +263,14 @@ Does this look right? Any corrections before I proceed?
 
 ## Phase 2 — af-core state check
 
-Run this check to confirm which fields actually reach props at runtime (af-core shapes the state — it is not a raw copy of model.json):
+Run this check to confirm which fields actually reach props at runtime (af-core shapes the state — it is not a raw pass-through of the JSON):
 
 ```bash
 cd packages/react-vanilla-components
 node -e "
 const {createFormInstance} = require('@aemforms/af-core');
 const form = createFormInstance({items:[
-  /* paste the model.json item here */
+  /* paste the minimal field object constructed in Phase 0e Step 5 */
 ]});
 console.log(JSON.stringify(form.items[0].getState(), null, 2));
 "
@@ -266,11 +313,11 @@ Name custom keys clearly (e.g. `sliderMin`, not `min`) to distinguish from stand
 
 Report to the user:
 - Which fields are present in state and their actual types/values
-- Which fields from model.json are absent from state
+- Which fields from the constructed schema are absent from state
 - Whether value normalisation is needed
 - Whether any constraints need the `afs:layout` side-channel
 
-**If the state check output contradicts the model.json analysis, update Phase 1 confirmation before generating code.**
+**If the state check output contradicts the schema analysis, update Phase 1 confirmation before generating code.**
 
 ---
 
@@ -278,7 +325,7 @@ Report to the user:
 
 File: `packages/react-vanilla-components/src/components/{ComponentName}.tsx`
 
-Use the **exact** BEM block, `data-cmp-is`, wrapper div structure, and state modifier classes extracted from the HTL in Phase 0e. Do not invent or guess these — they must match the core components markup so that the existing core component CSS applies correctly to the headless output.
+Use the **exact** BEM block, `data-cmp-is`, wrapper div structure, and state modifier classes extracted from the HTL in Phase 0d. Do not invent or guess these — they must match the core components markup so that the existing core component CSS applies correctly to the headless output.
 
 ### License header (always include)
 
@@ -427,7 +474,7 @@ export default withRuleEngine({ComponentName});
 - Map `minLength`, `maxLength`, `rows`, `cols` from state
 - `dispatchChange(event.target.value)`
 
-**Container components** (model.json has `items` array):
+**Container components** (Sling Model has `getItems()`):
 - Import and use `withRuleEnginePanel` instead of `withRuleEngine`
 - Accept `PROPS_PANEL` type instead of `PROPS`
 - Render children via the AEM renderer — use `Panel.tsx` or `Accordion/Accordion.tsx` as reference
@@ -456,8 +503,8 @@ import {ComponentName} from '../components/{ComponentName}';
 Add entries in the `mappings` object:
 ```ts
 '{fieldType}': {ComponentName},
-// If model.json has a ":type" resource type string:
-'{":type" value}': {ComponentName},
+// Resource type string from Sling Model @Model resourceType:
+'core/fd/components/form/{componentfolder}/v1/{componentfolder}': {ComponentName},
 ```
 
 Keep simple `fieldType` keys grouped; resource-type strings grouped — match existing file structure.
@@ -513,8 +560,8 @@ Only test constraints confirmed by state check. For constraints read from `props
 **5. Value normalisation**
 If the component normalises the value, write a dedicated test: pass the raw af-core format, assert the HTML input shows the normalised form.
 
-**6. Use the model.json item as `fullField`**
-Use the exact model.json item provided by the user as the `fullField` object. This is the most realistic test fixture — it mirrors what AEM will actually send.
+**6. `fullField` — use the canonical schema constructed from code**
+`fullField` is the minimal field object constructed in Phase 0e Step 5, not a user-pasted form-specific JSON. This keeps tests stable across different AEM form instances.
 
 ### Test template
 
@@ -541,17 +588,29 @@ const field = {
   label: { value: '{Human Readable Label}', visible: true },
   fieldType: '{fieldType}',
   type: '{type}',
-  // format: '{format}',  // include if present in model.json
+  // format: '{format}',  // include if present in schema
   visible: true,
   required: true,
   enabled: true,
   readOnly: false,
 };
 
-// Full field — exact model.json item as provided by the user.
-// This is what AEM will actually send at runtime.
+// Full field — canonical schema derived from Sling Model + HTL.
+// Stable across form instances — not a user-pasted model.json snippet.
 const fullField = {
-  // paste model.json item here exactly
+  fieldType: '{fieldType}',
+  ':type': 'core/fd/components/form/{componentfolder}/v1/{componentfolder}',
+  name: '{fieldName}',
+  label: { value: '{Human Readable Label}', visible: true },
+  type: '{type}',
+  // format: '{format}',
+  visible: true,
+  required: false,
+  enabled: true,
+  readOnly: false,
+  constraintMessages: {},
+  // include only constraints confirmed by Sling Model getters + state check:
+  // minimum: ..., maximum: ..., minLength: ..., maxLength: ..., pattern: ...
 };
 
 const helper = renderComponent({ComponentName});
@@ -631,7 +690,7 @@ describe('{ComponentName}', () => {
   // - Value normalisation: pass raw af-core value, assert input.value shows normalised form
   // - afs:layout side-channel: pass properties['afs:layout'] key, assert HTML attribute is set
 
-  test('full model.json field renders without errors', async () => {
+  test('full canonical schema field renders without errors', async () => {
     const { renderResponse } = await helper(fullField);
     expect(renderResponse.container.querySelector('input[type="{htmlInputType}"]')).not.toBeNull();
     expect(renderResponse.queryByText('{Human Readable Label}')).not.toBeNull();
@@ -666,20 +725,20 @@ Fix all errors before reporting done. Common failures and their causes:
 
 ## Checklist before finishing
 
-- [ ] model.json item analysed and confirmed with user before writing any code
-- [ ] af-core state check run — props match actual state, not raw model.json
-- [ ] BEM block: `cmp-adaptiveform-{lowercasename}` — `data-cmp-is`: `adaptiveForm{PascalName}`
+- [ ] Component schema derived from Sling Model + HTL, NOT from user-pasted model.json
+- [ ] af-core state check run using the code-derived minimal field — props match actual state
+- [ ] BEM block and `data-cmp-is` read from HTL (not inferred), or flagged as inferred if HTL unavailable
 - [ ] Outer `<div>` has all five `data-cmp-*` attributes
-- [ ] Widget element (`input`/`select`/`textarea`/custom) has `id="${id}-widget"`, `aria-label`, `aria-invalid`, `aria-describedby`
+- [ ] Widget element has `id="${id}-widget"`, `aria-label`, `aria-invalid`, `aria-describedby`
 - [ ] `FieldWrapper` receives `bemBlock`, `label`, `id`, `tooltip`, `description`, `isError`, `errorMessage`
 - [ ] Typed constraint props destructured from `props`; runtime-only ones via `(props as any).X` or `props.layout.X`
 - [ ] `dispatchBlur` called correctly — with value for text-like inputs, without for others
 - [ ] Default export is `withRuleEngine({ComponentName})` (or `withRuleEnginePanel` for containers), not the bare function
-- [ ] `mappings.ts` has entries for `fieldType` and `":type"` resource type (if present in model.json)
+- [ ] `mappings.ts` has entries for `fieldType` and resource type string from Sling Model `@Model` annotation
 - [ ] `src/index.ts` imports and re-exports the component
 - [ ] Value normalisation applied if state check showed format mismatch
 - [ ] Test uses correct input method per input type
 - [ ] Test label/input linking: `input.id === label.for` (no manual `-widget` suffix)
-- [ ] `fullField` in tests uses the exact model.json item provided by the user
+- [ ] `fullField` in tests uses canonical schema from code, not a form-specific model.json snippet
 - [ ] `npm run build` clean — run from inside package dir
 - [ ] All Jest tests pass — run from inside package dir