// Port a component from the HTML reference (digital-go-jp/design-system-example-components-html) to this React + Storybook project.
| 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. |
src/components/<Name>/component-rules first. This skill assumes its rules (component design, file layout, styling, accessibility, Storybook conventions, testing) and only adds the port-specific flow on top.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:
mkdir -p /tmp/<component>-html && cd /tmp/<component>-html
for f in <component>.mdx <component>.html <component>.css <component>.js <component>.stories.ts <component>.test.js <component>.vrt.js <component>.unit.js; do
curl -sSL "https://raw.githubusercontent.com/digital-go-jp/design-system-example-components-html/main/src/components/<component>/$f" -o "$f"
done
Then read the files locally. Test file roles in the HTML reference:
<component>.test.js — behavior tests (interaction, ARIA wiring, etc.)<component>.vrt.js — visual regression tests for the reset-CSS variant<component>.unit.js — jsdom-based unit tests for any logic split out of the componentNot 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 § Before writing code — read a similar existing component's full file set to pick up patterns before writing anything.
Read the HTML reference implementation
dads-<name>, dads-<name>__<part>) in a sibling <component>.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.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:
observedAttributes, attributeChangedCallback) — what state changes the component responds to.connectedCallback / disconnectedCallback) — ARIA wiring (role, aria-valuenow, aria-labelledby), live-region announcers, timers/intervals, validation.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.useState / useEffect / useRef in the component body (see component-rules § 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.prefers-reduced-motion: reduce and forced-colors handling — mirror them as-is.component-rules § Don't re-implement Preflight.Write a port plan and get user approval before coding — required.
src/components/<Name>/component-spec.md (template at the end of this file). Cover at minimum:
data-* attributes you'll expose, how children compose, what is intentionally not in the component API (e.g. placeholder icons — see below).<Name>.tsx with Tailwind classes inline in the JSX; only propose types.ts / a hook file when the complexity actually warrants it (see component-rules § File layout).Playground).write-tests.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:
<Name>.tsx. Do not split files preemptively.<FooFrontIcon> 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 <svg> elements with the required slot classes attached directly. Document the required classes for each slot in the autodocs page so consumers know what to attach.<span class="dads-menu-list__label">) and that class is replaced by Tailwind utilities in the React port, the wrapper has nothing left to do. Don't expose it as a sub-component (<MenuListItemLabel>) — apply the Tailwind classes directly on the parent's children, or have consumers pass the inner content as a prop / children. A wrapper is only justified when it owns layout / data-* / behavior that consumers can't sensibly attach themselves.Implement the React component (only after the user approves the plan from Step 3)
component-rules (composition, native-prop extension, no logic in body, no cross-component imports, no shared config additions, styling tokens, data-* + group-data-[...] pattern).Build the Storybook entries
component-rules § Storybook conventions for the basics (Playground Story, tags: ['autodocs'], export-name → HTML-file-name mapping).name in Japanese.docs.page) following the write-component-docs skill..storybook/preview.ts story sort order, in Japanese 50音順 (gojūon). The list under parameters.options.storySort.order > 'Component' is ordered by each title's kana reading — insert the new title at the right position (e.g. ボタン falls after プログレスインジケーター (ぷ) and before 見出し (み), not next to パンくずリスト). Re-read the surrounding entries to confirm placement.src/index.ts with export * from './components/<Name>';, keeping the list alphabetized.Tests
write-tests (see § When to skip tests entirely for the skip rule).Run the pre-completion checklist
pre-completion-check skill.feature/<component-name> (lowercase, hyphenated).feat(ProgressIndicator): ....This checklist covers only the port-specific items. The general rules in component-rules (component design, styling, accessibility, Storybook conventions, testing, code style) apply on top — verify against that skill as well, do not assume.
src/components/<Name>/component-spec.md was written after Steps 1–2 and approved by the user before any component code was written.component-spec.md is committed to the branch (typically the first commit, before the implementation), not left untracked or added as a follow-up.component-spec.md.<svg> with the slot classes documented in the autodocs page.children).component-rules § Don't re-implement Preflight).prefers-reduced-motion: reduce and forced-colors handling mirror the HTML reference.component-spec.md if used).spinner-loop.html → SpinnerLoop)..storybook/preview.ts story sort order in 50音順.src/index.ts re-exports the new component (export * from './components/<Name>';), kept alphabetized.write-tests, including its § When to skip tests entirely rule.pre-completion-check skill (lint / markup lint / build / test).Write this at src/components/<Name>/component-spec.md after Steps 1–2 and before writing any component code. The point is to surface design decisions early so the user can redirect them. Keep it brief — bullets, not prose. component-spec.md is a required, committed deliverable (see Step 3) — commit it as part of the port (typically the first commit, before the implementation) and keep it in sync when the design changes during implementation.
# <Component> 移植計画
## HTML reference
- Source: https://github.com/digital-go-jp/design-system-example-components-html/tree/<sha-or-branch>/<path>
- 関連ファイル:
- `<component>.mdx` / `<component>.html` / `<component>.css` / `<component>.js`
- `<component>.stories.ts` (Storybook)
- `<component>.test.js`（機能テスト） / `<component>.vrt.js`（リセット CSS VRT） / `<component>.unit.js`（jsdom ユニット） — 存在するもの
## コンポーネント設計
- 公開する構成要素（例: `Foo`, `FooItem`, `FooLabel`）
- 各要素の props（型・必須/任意・デフォルト）
- ルートで持たせる `data-*` 属性とその役割
- 子要素が反応する `group-data-[...]/name` の対応関係
- コンポーネント API に**入れない**もの（プレースホルダーアイコン、アニメーション一時停止、その他）
## ファイル構成
- `<Name>.tsx`（基本これ1つ。Tailwind クラスは JSX に直書き）
- 分割が必要なら理由とともに（`types.ts` / `useFooXxx.ts` / `<Name>.css`）
## Story 構成
- HTML 版にある Story 一覧 → React 版の export 名と表示名
- 追加で必要な Story（`Playground` など）
- autodocs ページに載せる項目（仕様表、必要クラス一覧など）
## テスト方針
- テストを書く / 書かない、と理由
- 書く場合は対象ケース（focus、keyboard、event payload など）
## HTML 版との意図的な差異
- 何を / なぜ
Rules and conventions for building React components in this repo (composition pattern, no logic in component body, styling tokens, file layout, etc.). Read this before writing or editing any component.
Stage files, generate a commit message in this repo's Conventional Commits style, and commit after user approval.
Run the pre-completion checks before declaring a task done. Executes lint, markup lint, build (tsc), tests, and reminds the user to verify Storybook visually.
Review changed code in this repo against the project's review checklist (readability, maintainability, performance, security, consistency).
Author component documentation in this project. Docs live inside the component's *.stories.tsx (Storybook autodocs), translated from the HTML reference's MDX structure into JSX, in Japanese.
Write tests for components in this project. Covers Storybook-based UI tests (composeStories + vitest-browser-react), unit tests for hooks/utils, and the conventions that keep tests deterministic and meaningful.