Grommet Component Contribution
Developmentgrommet-component-contributionGrommet Component Contribution is an Agent Skill for development published in the grommet/grommet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Build and contribute Grommet React components following official team conventions. Use when creating a new component from scratch, refactoring a component to align with Grommet conventions, preparing a PR for Grommet core contribution, or reviewing a component against acceptance criteria. Covers scaffolding, forwardRef, displayName, useThemeValue, FormContext, propTypes, TypeScript declarations, accessibility, i18n, and testing.
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/grommet/grommet/blob/HEAD/.github/skills/grommet-component-contribution/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/grommet-component-contribution, 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.
Grommet Component Contribution Skill
Use When
- Building a new Grommet component from scratch
- Refactoring a component to align with Grommet conventions
- Preparing a PR for Grommet core contribution
- Reviewing a component against the Grommet acceptance criteria
Workflow
- Discover: read the closest existing component, its tests, propTypes, types, and stories.
- Plan: define the value contract, commit model, minimum props, and composition boundaries.
- Scaffold: create the component files, register exports, and add docs/tests/stories.
- Implement: build pure utilities first, then the component with
forwardRef,useForwardedRef,useThemeValue, andFormContextintegration. - Test: start with accessibility, then value emission, form integration, keyboard, and edge cases.
- Stories: controlled usage,
FormFieldintegration, andCustomThemedonly if new theme tokens exist. - Validate: lint, full tests, and top-level
grommetexport coverage.
Non-Negotiable Principles
- Compose small primitives before building a monolith.
- Prefer native browser APIs such as
Intlover custom format/parse logic. - Put customization in theme tokens, not instance props.
- Keep accessibility, semantic HTML, and keyboard support mandatory.
- Use
onChangewith the{ value }shape for structured inputs.- Native element wrappers (TextInput, CheckBox) emit the standard React synthetic event via
onChange(event). - Structured inputs that own a parsed/formatted value (DateInput) emit
onChange({ value }).
- Native element wrappers (TextInput, CheckBox) emit the standard React synthetic event via
- Simple inputs emit on every meaningful interaction; structured inputs emit only when the composed value is valid.
- Spread
...restonto the root DOM element, though some components may be selective about placement.
Default API Shape
- Start with only truly universal props:
aria-label,id, and...rest. - Apply
disabledonly to value-input components (TextInput, CheckBox, Select, DateInput, etc.). - Do NOT add
disabledto non-interactive display components (Text, Heading, Anchor). - Use
genericPropsfor layout and style passthrough. - See REFERENCE.md for component-specific API shapes.
Implementation Checklist
React.forwardRefplusdisplayNameuseForwardedRef(refArg)instead of raw refsconst { theme, passThemeFlag } = useThemeValue()FormContextintegration viauseFormInputwhen the component participates in forms- TypeScript declarations in
index.d.ts propTypes.jsguarded for production- Component barrel export and top-level export registration
- Theme defaults live under a dedicated
theme.<componentName>namespace - Stories in CSF-3 format
- Tests use
@testing-library/user-event,jest-axe, and<Grommet>wrappers
When Unsure
- Check the nearest similar component.
- Check existing theme tokens.
- Check shared utilities or
FormContext. - Ask before inventing a new pattern.
- Read REFERENCE.md before making implementation decisions.
- Review EXAMPLES.md for a matching archetype before drafting new APIs.
Detailed Reference
- REFERENCE.md — anti-hallucination rules, implementation patterns, PR checklist, decision tree, and anti-patterns
- EXAMPLES.md — archetype code examples for all 4 component types (Simple Input, Drop/Modal, Display Only, Layout)
- references/architecture.md — forwardRef, useForwardedRef, useThemeValue, FormContext/useFormInput, directory structure, propTypes, TypeScript declarations
- references/styling.md — styled-components, styledComponentsConfig, theme token namespace, disabledStyle/readOnlyStyle, t-shirt sizing
- references/accessibility.md — Keyboard component, focus restore, aria-label, Escape handling, semantic HTML rules
- references/forms.md — FormContext.useFormInput(), FormField error surfacing, non-destructive UX
- references/i18n.md — MessageContext string keys, AnnounceContext live regions, polite vs assertive