From 5186cda2462ed13600075fe4469afa1e90732dc3 Mon Sep 17 00:00:00 2001 From: Benny Powers Date: Thu, 14 May 2026 15:55:50 +0300 Subject: [PATCH] docs(create-element): add README phase to element skills Add Phase 8 (README) to create-element and update-element skills, instructing agents to produce a divergences-from-React document for each element. Three tables: not implemented, changed API, and added. Includes accuracy rules to prevent false claims about shadow DOM. References elements/pf-v6-tooltip/README.md as example. Assisted-By: Claude Opus 4.6 (1M context) --- .claude/skills/create-element/SKILL.md | 38 +++++++++++++++++++++++++- .claude/skills/update-element/SKILL.md | 38 +++++++++++++++++++++++++- 2 files changed, 74 insertions(+), 2 deletions(-) diff --git a/.claude/skills/create-element/SKILL.md b/.claude/skills/create-element/SKILL.md index 7187327582..b00840b2b8 100644 --- a/.claude/skills/create-element/SKILL.md +++ b/.claude/skills/create-element/SKILL.md @@ -274,7 +274,43 @@ Write all tests from scratch: See `.claude/skills/review-api/SKILL.md` Phase 4 for full test checklist. -### Phase 8: Audit +### Phase 8: Write README + +Create `elements/pf-v6-{name}/README.md` documenting divergences from +the React component API. Structure: + +1. **Title and summary** -- element tag, one-line description +2. **Usage** -- 2-3 HTML snippets showing common patterns +3. **Divergences from React `{Name}`** -- three tables: + +#### "Not implemented" table (2 columns: React prop | Notes) +React props with no web component equivalent and no workaround. +Only truly absent features belong here. + +#### "Changed API" table (3 columns: React prop | Web component | Difference) +React props that have a web component equivalent but with different API shape. +Include props where: +- Name changed (e.g. `enableFlip` -> `no-flip`) +- Type changed (e.g. boolean -> enum, prop -> CSS custom property) +- Mechanism changed (e.g. callback -> DOM event, declarative -> imperative) +- Not configurable but has a fixed internal value (note "Not supported" or + "Hardcoded to X") + +**Omit** props that map 1:1 as camelCase properties with dash-case attributes +and identical semantics (e.g. React `entryDelay` -> attribute `entry-delay`). +These are standard web component conventions, not divergences. + +#### "Added" table (2 columns: Web component API | Notes) +Web-component-only APIs not present in React (events, methods, slots, CSS +custom properties). + +**Accuracy rule:** verify each claim against the actual CSS and TS source. +Don't claim CSS properties on the host affect shadow DOM internals. Check +whether values are actually configurable or hardcoded. + +See `elements/pf-v6-tooltip/README.md` for a reference example. + +### Phase 9: Audit Prompt the user to activate /review-api, /review-demos, and /review-a11y diff --git a/.claude/skills/update-element/SKILL.md b/.claude/skills/update-element/SKILL.md index bf0480f346..5779d9bf53 100644 --- a/.claude/skills/update-element/SKILL.md +++ b/.claude/skills/update-element/SKILL.md @@ -255,7 +255,43 @@ Update existing tests -- don't rewrite from scratch: See `.claude/skills/review-api/SKILL.md` Phase 4 for full test checklist. -### Phase 8: Audit +### Phase 8: Write README + +Create `elements/pf-v6-{name}/README.md` documenting divergences from +the React component API. Structure: + +1. **Title and summary** -- element tag, one-line description +2. **Usage** -- 2-3 HTML snippets showing common patterns +3. **Divergences from React `{Name}`** -- three tables: + +#### "Not implemented" table (2 columns: React prop | Notes) +React props with no web component equivalent and no workaround. +Only truly absent features belong here. + +#### "Changed API" table (3 columns: React prop | Web component | Difference) +React props that have a web component equivalent but with different API shape. +Include props where: +- Name changed (e.g. `enableFlip` -> `no-flip`) +- Type changed (e.g. boolean -> enum, prop -> CSS custom property) +- Mechanism changed (e.g. callback -> DOM event, declarative -> imperative) +- Not configurable but has a fixed internal value (note "Not supported" or + "Hardcoded to X") + +**Omit** props that map 1:1 as camelCase properties with dash-case attributes +and identical semantics (e.g. React `entryDelay` -> attribute `entry-delay`). +These are standard web component conventions, not divergences. + +#### "Added" table (2 columns: Web component API | Notes) +Web-component-only APIs not present in React (events, methods, slots, CSS +custom properties). + +**Accuracy rule:** verify each claim against the actual CSS and TS source. +Don't claim CSS properties on the host affect shadow DOM internals. Check +whether values are actually configurable or hardcoded. + +See `elements/pf-v6-tooltip/README.md` for a reference example. + +### Phase 9: Audit Prompt the user to activate /review-api, /review-demos, and /review-a11y