gilde

← All craftbooks

Reusable Web Component

Build: interactive and webevalv1.0.0released 2026-06-05workflow: build-loop

Build a reusable custom element as a standards-based Web Component — a rating widget, toggle, accordion, modal, or color-picker — using the Custom Elements API and Shadow DOM with encapsulated styles, attributes, properties, and custom events. Designs the component's public API (tag name, observed attributes, properties, events, slots) first, then implements the class with a demo page proving it works. Components fail when the API is inconsistent or styles leak, so the api-design phase locks the contract before any code, the ordering that yields a genuinely reusable element rather than a one-off.

Steps

Entry step: api-design. Each step names the specialist role it wants; the full working prompt is expandable.

  1. API designdeveloperentry

    tag, attributes, properties, events, slots

    Show working prompt
    Design the component's PUBLIC API before any implementation. (1) Choose the custom-element tag name (must contain a hyphen, e.g. <star-rating>). (2) List the observed attributes (reflected to/from properties) and their types/defaults. (3) List the JS properties and methods consumers use. (4) Define the custom events it dispatches (name + detail payload). (5) Decide slots for projected content and the encapsulated style approach (Shadow DOM). (6) Write an acceptance-criteria checklist of 5-8 items, e.g. 'the element upgrades when added to the DOM', 'setting the observed attribute updates the rendering (attributeChangedCallback)', 'interacting dispatches the documented event with the right detail', 'styles are encapsulated in shadow DOM (no leakage)', 'a slot projects content', 'the demo shows it working', 'no console errors'. Write to notes/api-design.md and via write_task_note. No implementation yet.
  2. Builddeveloper

    implement the element + a demo in index.html

    Show working prompt
    Implement the component and a demo in index.html (inline). (1) Define a class extending HTMLElement; attachShadow({mode:'open'}) and render template + encapsulated <style> in the constructor/connectedCallback. (2) Declare static observedAttributes and implement attributeChangedCallback to re-render on change; reflect attributes<->properties per the API. (3) Wire interaction to dispatch the documented CustomEvent(detail). (4) customElements.define the tag. (5) Add a demo section that uses the element, sets attributes, listens for its event, and shows the result. Vanilla JS, no CDN. On a loop-back, fix only the named gaps without regressing passing criteria. write_task_note the path and passing criteria.
  3. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Evaluate the component against its API. Open index.html if possible and interact via the demo; else read the class. Check EACH criterion from notes/api-design.md and write PASS/FAIL with a reason: does the element upgrade and render, does changing the observed attribute update it (attributeChangedCallback fires), does interacting dispatch the documented event with the right detail, are styles encapsulated in Shadow DOM (no global leakage), does a slot project content, does the demo work, zero console errors? An attribute that does not re-render, or leaked styles, is a FAIL — loop back to build.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  4. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license