---
name: port-html-to-react
description: "Port a component from the HTML reference (digital-go-jp/design-system-example-components-html) to this React + Storybook project."
---
## Context
- HTML reference repo: https://github.com/digital-go-jp/design-system-example-components-html
- Target directory pattern: `src/components//`
- **Read [`component-rules`](../component-rules/SKILL.md) first.** This skill assumes its rules (component design, file layout, styling, accessibility, Storybook conventions, testing) and only adds the port-specific flow on top.
## Steps
1. **Read the spec and the codebase**
- Fetch the component's reference files from the HTML repo. **Use `curl` via Bash, not `WebFetch`** — `WebFetch` summarizes content past a quote limit and will silently truncate the spec/markup/CSS. Example:
```sh
mkdir -p /tmp/-html && cd /tmp/-html
for f in .mdx .html .css .js .stories.ts .test.js .vrt.js .unit.js; do
curl -sSL "https://raw.githubusercontent.com/digital-go-jp/design-system-example-components-html/main/src/components//$f" -o "$f"
done
```
Then read the files locally. Test file roles in the HTML reference:
- `.test.js` — behavior tests (interaction, ARIA wiring, etc.)
- `.vrt.js` — visual regression tests for the reset-CSS variant
- `.unit.js` — jsdom-based unit tests for any logic split out of the component
Not every component has all three. A 404 from `curl` just means that file doesn't exist; ignore it and move on.
- Run through [`component-rules`](../component-rules/SKILL.md) § _Before writing code_ — read a similar existing component's full file set to pick up patterns before writing anything.
2. **Read the HTML reference implementation**
- Markup and styles. The HTML reference uses **plain CSS with BEM-style class names** (`dads-`, `dads-__`) in a sibling `.css` — not Tailwind. Translate those rules into Tailwind utility classes (with theme-plugin tokens) on the React side; don't carry the BEM class names over.
- **Read the companion Custom Element JS** (e.g. `progress-indicator.js`) carefully. Behavior is _not_ inline in the HTML — it lives in a `class Foo extends HTMLElement` / `customElements.define('dads-foo', Foo)` file. That file is where you'll find:
- Attribute reactions (`observedAttributes`, `attributeChangedCallback`) — what state changes the component responds to.
- Lifecycle work (`connectedCallback` / `disconnectedCallback`) — ARIA wiring (`role`, `aria-valuenow`, `aria-labelledby`), live-region announcers, timers/intervals, validation.
- Public properties / methods (`get value()`, `start()`, `stop()`, etc.) — the imperative API consumers use.
- `[data-js-*]` selectors — these are **JS-only hooks** for `querySelector`. The React port doesn't need them; express the same wiring through component structure / props instead.
- The React port has to reproduce this behavior **without** `useState` / `useEffect` / `useRef` in the component body (see [`component-rules`](../component-rules/SKILL.md) § _No logic in the component body_). Plan where each piece goes: Story-side demo state, a separate hook file (`useFooAnnouncer.ts` etc.), or pure `data-*` + CSS.
- Note `prefers-reduced-motion: reduce` and `forced-colors` handling — mirror them as-is.
- **Don't port the reset CSS** that the HTML reference uses to normalize elements — Preflight already covers it. See [`component-rules`](../component-rules/SKILL.md) § _Don't re-implement Preflight_.
3. **Write a port plan and get user approval before coding** — required.
- After Steps 1–2, write `src/components//component-spec.md` (template at the end of this file). Cover at minimum:
- **Component design**: which sub-components / props / `data-*` attributes you'll expose, how children compose, what is intentionally _not_ in the component API (e.g. placeholder icons — see below).
- **File layout**: which files you'll create. Default to one `.tsx` with Tailwind classes inline in the JSX; only propose `types.ts` / a hook file when the complexity actually warrants it (see [`component-rules`](../component-rules/SKILL.md) § _File layout_).
- **Story plan**: which Stories to mirror from the HTML version (one per HTML file, plus `Playground`).
- **Test plan**: whether tests are needed, with reasoning, and the target cases if any. Decision rule: [`write-tests`](../write-tests/SKILL.md).
- **Intentional deviations from the HTML reference**: anything you plan to do differently from the HTML version (and why).
- Present the plan to the user and **wait for confirmation before writing component code**. The plan exists so the user can redirect file layout, prop shape, and Story/test scope before code is written, not after.
- **Commit `component-spec.md` to the repo as a deliverable.** It's not a throwaway working doc — it's the artifact reviewers use to evaluate the port on the PR. Commit it as part of the port (typically the first commit on the branch, before the implementation), and keep it in sync if the design changes during implementation. Don't leave it untracked or add it as an after-the-fact follow-up commit.
**Defaults to bake into the plan:**
- Start with everything in `.tsx`. Do not split files preemptively.
- **Don't componentize placeholder icons.** When the HTML reference shows decorative or example SVGs at icon slots (front/tail/end icons, illustrative glyphs in demos), do not create wrapper components like `` for them. Consumers bring their own icons of unknown shape/size, so the component can't usefully fix `width`/`viewBox`/`fill`. Instead, the component contributes only the layout / behavior classes via the slot's container, and the Story renders raw `