component-contributor

name	component-contributor
description	Guides an AI agent through implementing a Stack-and-Flow design-system component from an approved issue/spec. Trigger: component implementation, implement this component, build a component, component issue URL, delegated from sdd-apply.
license	Apache-2.0
metadata	{"author":"stack-and-flow","version":"3.0"}

Activation Contract

Use this skill when implementing a new or changed component. This skill owns the contributor workflow; it does not duplicate component, story, test, or visual rule checklists.

When delegated from sdd-apply, skip contributor onboarding and return the SDD implementation-progress envelope requested by the orchestrator.

Required References

Load these before implementation:

1. skills/_shared/component-contract.md — structure, TypeScript, tokens, tests, stories, exports, Radix, accessibility gates.
2. skills/component-contributor/references/biome-rules.md — before writing any .ts/.tsx.
3. docs/DESIGN.md and src/styles/theme.css — before choosing tokens or judging visuals.
4. docs/COMPONENTS.md — for interactive/visual state rules when present.

Load by intent:

Need	Reference
Storybook	skills/component-contributor/references/stories.md
Tests	skills/component-contributor/references/testing.md
Native HTML element props	skills/component-contributor/references/html-extension.md
Radix primitive	skills/component-contributor/references/radix-patterns.md
className merging	skills/component-contributor/references/tailwind-merge.md
Contributor PR workflow	skills/component-contributor/references/git-workflow.md
Starting from a GitHub issue or board task	skills/github-project-tasks/SKILL.md — verify issue label status:approved and assignee ownership, then run START WORK before implementation

Workflow

Follow these phases in order. Do not skip gates because a component looks simple.

Non-negotiable approval gate: implementation must not start under any circumstance unless the linked GitHub issue has the exact label status:approved. Chat approval, assumptions, offline mode, or a local copy of the spec do not satisfy this gate.

Non-negotiable assignee gate: before reading the implementation spec in detail, planning, creating a branch/worktree, mutating GitHub, or writing code from a linked issue, verify current assignees. If the issue is assigned to someone other than the contributor/user, stop and tell the user they must get explicit permission before reassigning it.

Non-negotiable validated handoff gate: implementation intake must read ## Validated component spec plus the immediately following ## Cataloging decision from the same issue comment/update. Stop if either section is missing, standalone, ambiguous, contains blockers/questions, or conflicts with the other.

0 — Contributor onboarding

Only when working directly with a contributor: confirm they understand React + strict TypeScript, Tailwind v4 tokens, CVA, the 6-file pattern, Storybook as docs, and tests in .test.tsx. If not, teach briefly before proceeding.

1 — Approval gate, START WORK, then spec intake

If implementation will proceed from a GitHub issue or Project board card, first verify that the linked issue has the exact label status:approved and is not assigned to someone else. If the label is missing, stop and ask for maintainer/project lead approval; do not read the implementation spec in detail, plan, or code. If another assignee is present, stop before any action and tell the user they need explicit permission before reassigning the issue.

After the label and assignee gates pass, load skills/github-project-tasks/SKILL.md and run START WORK before spec intake, planning, or coding: verify assignees, assign the issue to the contributor/user, move Project status to In progress, and record the planned branch/worktree. Offline/no-network mode may only skip GitHub mutations after evidence confirms the issue already has status:approved and is unassigned or assigned to the contributor/user; it never bypasses the approval or assignee gates.

Then extract component name, tier, props, variants, states, accessibility behavior, reference URL, design notes, and the cataloging decision summary, reuse/extraction instructions, child issue candidates, and target issue. If the spec lives in a GitHub issue, read issue comments too; validated specs may live there.

Primitive tier specs may proceed only when the validated ## Cataloging decision explicitly approves primitive support and path. If the repo has no primitive implementation support or the decision does not explicitly approve it, stop and defer to the V1 inventory/recatalogation issue instead of silently implementing the component as an atom.

Stop and ask when the issue label status:approved is missing or cannot be verified, the issue is assigned to someone else without explicit reassignment permission, START WORK cannot be completed, the adjacent validated spec/cataloging handoff is missing or unresolved, the spec conflicts with the cataloging decision, primitive support is not explicitly approved for a primitive spec, or required behavior, accessibility, states, or variants are missing. Do not invent public API and do not begin implementation.

1.5 — Spec critique

Before planning, return:

## Spec Review — {ComponentName}

### Gaps found
- {missing requirement and impact}

### Cataloging decision summary
- Decision: {reuse existing / keep in parent / split/extract / needs child issue / defer to V1 inventory}
- Reuse/extraction: {summary}
- Child candidates: {none or list}

### Risks found
- {implementation/product risk and mitigation}

### Improvements proposed
- {specific improvement}

### Ready to proceed
{Yes / No — why}

Flag only meaningful issues: accessibility failures, undocumented keyboard/focus behavior, missing stories for documented variants, unclear defaults, broken composability, or token references that do not exist.

1.75 — Visual preflight

Map the component to the design system before coding:

• surface pattern: opaque, raised, tinted, or floating/frosted;
• relevant tokens from theme.css;
• action control-height scale (control-xs|sm|md|lg) for comparable action controls, or semantic form-field scale (form-field-sm|md|lg) when the component behaves like Input/Select with label/floating-label layout;
• whether the component uses visual control height tokens, form-field sizing, a separate touch-target-min, or a documented compact exception;
• base/hover/focus/active/disabled/loading/error/info states;
• focus ring, disabled treatment, touch target, contrast, reduced motion;
• allowed Radix primitive, if any.

2 — Plan

Present a concise plan and wait for confirmation unless SDD delegation already approved implementation:

## Implementation Plan

**Component**: {ComponentName}
**Tier**: primitives / atoms / molecules / organisms
**Directory**: `src/components/{tier}/{kebab-name}/` (primitive only when explicitly approved by the validated cataloging decision and supported by the repo)

### Files
1. `types.ts` — props, CVA variants, defaults
2. `useComponentName.ts` — logic, aria, handlers, className
3. `ComponentName.tsx` — JSX only
4. `ComponentName.test.tsx` — hook + behavior tests
5. `ComponentName.stories.tsx` — canonical Storybook examples
6. `index.ts` — named export + type exports

### Decisions
- Tokens: {list}
- Radix primitive: {yes/no; which one}
- Cataloging decision: {reuse/extraction/child candidates summary}
- States and accessibility: {summary}
- Validation: {tests/build/storybook/manual visual checks}

3 — Implement

Implement files in this order: types.ts → hook → component → tests → stories → index.ts.

After hook/component defaults are known, return to types.ts and verify every public prop with a runtime default has matching JSDoc @default metadata. Run node scripts/verify-prop-default-docs.mjs before handoff.

Use skills/_shared/component-contract.md as the contract for each file. If a local mature component contradicts the shared contract, stop and ask whether to follow current code or update the contract.

4 — Explain decisions

After each file, briefly explain the non-obvious decisions: CVA shape, token choices, ARIA behavior, Radix composition, and test/story coverage. Keep this short; do not write tutorial prose.

5 — Visual review

Load skills/visual-review/SKILL.md and run the full visual gate. Fix CRITICAL and MAJOR visual issues before claiming completion.

6 — Component audit before PR

Load skills/components-auditor/SKILL.md for the final component audit. Do not open a PR with CRITICAL or MAJOR findings.

7 — End work handoff

If the component work came from a GitHub issue or Project board card, use skills/github-project-tasks/SKILL.md END WORK only after validation evidence exists and the PR is merged or the maintainer/user explicitly approves closing the task. If working offline/no-network, return the END WORK follow-up instead of mutating GitHub.

Output Contract

For normal implementation, return:

## Component Implementation — {ComponentName}

**Files changed**: {list}
**Spec deviations**: {list or "None"}
**Validation**: {commands/checks and result}
**Visual review**: {PASS / issues}
**Component audit**: {PASS / issues}
**Remaining work**: {list or "None"}

For SDD delegation, use the SDD return envelope supplied by the parent.