Component Rules
Developmentcomponent-rulesComponent Rules is an Agent Skill for development published in the digital-go-jp/design-system-example-components-react repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/digital-go-jp/design-system-example-components-react/blob/HEAD/.agents/skills/component-rules/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/component-rules, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
These are the project-wide rules for component code. Workflow skills (port-html-to-react, write-tests, write-component-docs) build on top of these — they don't restate them.
Before writing code
The codebase is the source of truth for style and structure. Read it before adding or changing components.
When adding a new component
- Skim
src/components/to see what is already there and how directories are organized. - Open one or two components of the same nature (form control, animated indicator, navigational, etc.) and read all their files —
.tsx,.stories.tsx,.test.tsx, plus any split-outtypes.ts/ hooks. Match their patterns rather than inventing new ones. - Skim
tailwind.config.jsand the@digital-go-jp/tailwind-theme-plugintokens so styles use existing tokens, not stock Tailwind values. - Read the HTML reference for the component (see
port-html-to-react).
When updating an existing component
- Read every file under
src/components/<Name>/first — including stories, tests, and any split-out hooks/utils. Subtle conventions live in those siblings. - Preserve the existing pattern (file split, prop shape, naming) unless the change explicitly requires breaking it.
Component design principles
Composition pattern
Use React children composition. Keep props and state minimal; let consumers assemble the structure.
// Good: consumers control the structure
<Dialog>
<DialogBody>
<h2>...</h2>
<p>...</p>
</DialogBody>
</Dialog>
// Bad: structure locked inside props
<Dialog body={<><h2></h2></>} />
Props
Base props on native element props. Add custom props only when necessary.
type ButtonProps = ComponentProps<'button'>;
// When extension is necessary:
type ButtonProps = ComponentProps<'button'> & {
size: Size;
variant: Variant;
};
No cross-component references or premature abstraction
- Component A must not import component B (Slot-like primitives excepted).
- Do not deduplicate similar UI code. No
BaseProps,CommonProps,BaseButton,BaseCard. - UI requirements diverge per project; shared base classes become liabilities.
No logic in the component body
- Component bodies must not contain logic (state, timers, effects, data fetching, etc.).
- Do not use
useState,useRef,useEffect, or other React hooks in the component body (keeps React Server Component compatibility). - When logic is needed, provide it one of these ways:
- Inline in the Story — demo-specific behavior (timers, demo state).
- Hook in a separate file (e.g.
useFooAnnouncer.ts) — imported when the consumer needs it. - Util in a separate file — pure functions, class-name helpers.
- When you split out a hook or util, add Vitest tests. See
src/components/FileUpload/FileUpload.test.tsxfor the pattern (Story reuse viacomposeStories+vitest-browser-react).
No dependencies on shared config
Components must be self-contained. Do not rely on:
- Per-component additions to
tailwind.config.js(e.g. extendingtheme.keyframesorcolorsfor a single component) - Additions to
global.cssor other shared stylesheets - Project-level PostCSS plugins or global CSS variables
If you need custom CSS (e.g. @keyframes), put it in a .css file inside the component directory and import it from the component's .tsx. A consumer should be able to copy the component folder and have it work.
File layout
Per component:
src/components/Foo/
├── Foo.tsx # Main implementation (sub-components can live here too)
├── Foo.stories.tsx # Storybook
├── Foo.test.tsx # Vitest (when hooks/utils are split out, or for UI behavior)
├── types.ts # Shared types (size, variant, etc.)
├── useFooSomething.ts # Component-specific hook (when needed)
└── index.ts # Public exports
- Start with everything in
Foo.tsx. - Do not split files preemptively. Once
Foo.tsxexceeds roughly 300 lines, propose a split to the user; do not do it unprompted. - Do not create new files (docs, READMEs, notes) unless explicitly requested.
Styling rules
Tailwind
- Use tokens from
@digital-go-jp/tailwind-theme-plugin(https://github.com/digital-go-jp/tailwind-theme-plugin). - Do not use stock Tailwind colors (
text-blue-500etc.).text-whiteandtext-blackare the only exceptions. - Do not use stock Tailwind font sizes (
text-xs,text-lg, etc.). Text styles are covered by thetext-std-*,text-dns-*,text-oln-*,text-mono-*token sets — these set font-size, weight, line-height, and letter-spacing together, so a single token usually replaces multiple classes (text-base leading-[1.3] tracking-normal→text-dns-16N-130). - For line-height alone, prefer the plugin's
leading-100…leading-175over arbitrary values likeleading-[1.3]. - Prefer Tailwind shorthand utilities over arbitrary-value brackets when one exists.
[margin-left:calc(...)]→ml-[calc(...)],[padding-left:1rem]→pl-4, etc. Reserve[property:value]for properties Tailwind has no shorthand for. - Mirror the HTML version's
prefers-reduced-motion: reduceandforced-colorshandling. - Match the styling conventions used in neighboring components. Before writing a new pattern (especially
focus-visible, hover, and other interaction states), grep for the same selector elsewhere insrc/components/and follow that form. Example:focus-visibleoutline + ring is expressed withfocus-visible:outline focus-visible:outline-4 focus-visible:outline-black focus-visible:ring-* focus-visible:ring-yellow-300— not as[box-shadow:...]arbitrary values.
Don't re-implement Preflight
The HTML reference is built without a CSS reset, so it explicitly normalizes <button>, <ul>, <a>, etc. (e.g. border: 0; background: transparent; padding: 0; margin: 0; list-style: none; font: inherit; text-decoration: none; color: inherit; box-sizing: border-box). This project uses Tailwind's Preflight, which already applies those resets globally.
Do not copy those reset declarations into the React port. Only add classes that change behavior beyond Preflight's defaults. Common offenders to omit:
m-0,p-0,pl-0on<ul>/<ol>(Preflight handles list margins/padding)list-noneon a<ul>that has no markersborder-0,bg-transparenton<button>text-inherit,[font:inherit],[letter-spacing:inherit]on form/interactive elementsno-underlineon<a>when the design wants the defaultbox-sizing: border-box(Preflight sets it)
data-* + group-data-[...] pattern
Represent state via data-* on the root; children react via group-data-[...]/name. Avoid branching className in JS.
<div
className='group/progress-indicator'
data-type={type}
data-indeterminate={isIndeterminate ? '' : undefined}
>
<svg className='group-data-[indeterminate]/progress-indicator:[animation:spin_2s_linear_infinite]' />
</div>
Accessibility
- Target WCAG 2.2 Level AA (and JIS X 8341-3:2016).
- Use the correct HTML element; prefer native semantics over ARIA.
- Keep WAI-ARIA usage minimal.
- Verify keyboard navigation and screen reader output.
- No
console.logor debug output in committed code.
Storybook conventions
- Every component has a
PlaygroundStory. Tests reuse it viacomposeStories. - Story export names match the HTML file names (
spinner-loop.html→SpinnerLoop, display name in Japanese). - For the docs page (a dedicated
<Name>.mdxfile), follow thewrite-component-docsskill.
Testing
All Vitest tests run in browser mode via Playwright + Chromium (see vite.config.ts). There is no jsdom environment.
- UI behavior (focus, ARIA, drag & drop, etc.) →
composeStories+vitest-browser-reactagainst Stories (storybookproject). - Pure hooks/utils → standard Vitest tests under
src/**/*.test.{ts,tsx}(unitproject — also browser-mode, but DOM globals are simply unused for pure logic). - For conventions (deterministic time, query patterns, what to cover), see the
write-testsskill. Reference implementation:src/components/FileUpload/FileUpload.test.tsx.