Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: add RFC/bug issue templates and update community page (#2360)

Cindy Zhangbc67ff41cf9e
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
new file mode 100644
index 0000000000..dfe24e46b3
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,44 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+
+name: Bug Report
+description: Report a bug in an XDS component.
+title: "[Bug] "
+labels: ["bug"]
+body:
+ - type: textarea
+ id: description
+ attributes:
+ label: Description
+ description: What happened? What did you expect to happen?
+ validations:
+ required: true
+
+ - type: textarea
+ id: reproduction
+ attributes:
+ label: Reproduction
+ description: |
+ Steps to reproduce, a minimal code example, or a link to a sandbox/Storybook story that demonstrates the issue.
+ placeholder: |
+ 1. Render `<XDSButton variant="primary" />`
+ 2. Click the button while in loading state
+ 3. Focus is lost
+ validations:
+ required: true
+
+ - type: input
+ id: version
+ attributes:
+ label: XDS Version
+ placeholder: "@xds/[email protected]"
+ validations:
+ required: true
+
+ - type: textarea
+ id: environment
+ attributes:
+ label: Environment
+ description: Browser, OS, assistive technology (if applicable).
+ placeholder: "Chrome 125, macOS 15, VoiceOver"
+ validations:
+ required: false
diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
new file mode 100644
index 0000000000..19607ea1b1
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/rfc.yml
@@ -0,0 +1,101 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+
+name: "RFC: Component or Feature Proposal"
+description: Propose a new component, feature, or significant API change for XDS.
+title: "[RFC] "
+labels: ["rfc"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ ## Before you submit
+
+ An RFC is a **problem statement and demand signal** — not a design proposal we evaluate as-written. Read the [contributing guide](https://github.com/facebookexperimental/xds/wiki/Contributing) before submitting.
+
+ After acceptance, either of us drives the [specification protocol](https://github.com/facebookexperimental/xds/wiki/Component-Specification-Protocol) — you can front-load research and API exploration in this RFC at your own risk if we haven't responded yet.
+
+ **Response time:** We aim to respond within 1 week — either accepting, requesting more information, or declining with rationale.
+
+ - type: textarea
+ id: problem
+ attributes:
+ label: Problem Statement
+ description: What use case are you solving? Describe the user experience gap, not the component you want.
+ placeholder: "Users need to [do X] and currently can't because [Y]. This shows up when building [Z]."
+ validations:
+ required: true
+
+ - type: textarea
+ id: evidence
+ attributes:
+ label: Evidence of Demand
+ description: |
+ Where does this pattern appear? The more concrete, the better.
+ - Screenshots or wireframes from distinct products/surfaces
+ - Links to external systems that ship this (Radix, Chakra, MUI, Ant Design)
+ - Frequency — how often does this pattern come up?
+ placeholder: "This pattern appears in [A], [B], and [C]. Here are examples: ..."
+ validations:
+ required: true
+
+ - type: textarea
+ id: existing
+ attributes:
+ label: Why Existing Components Don't Cover This
+ description: |
+ What have you tried with current XDS components? Show the composition attempt and where it breaks down. "I tried X but it requires Y lines of boilerplate / breaks accessibility / doesn't theme correctly."
+ placeholder: "I attempted to compose this using XDSCard + XDSVStack + ... but ..."
+ validations:
+ required: true
+
+ - type: textarea
+ id: approaches
+ attributes:
+ label: Rough Approaches Considered
+ description: |
+ One or more ideas for how this could work — not as implementation proposals, but to show you've thought through the design space. Include consumer code examples if possible.
+ placeholder: |
+ Option A: A new XDSFoo component that...
+ ```tsx
+ <XDSFoo prop={value}>...</XDSFoo>
+ ```
+
+ Option B: A hook that...
+ ```tsx
+ const fooProps = useXDSFoo({...});
+ <div {...fooProps}>...</div>
+ ```
+ validations:
+ required: false
+
+ - type: textarea
+ id: accessibility
+ attributes:
+ label: Accessibility Considerations
+ description: What ARIA pattern does this map to? What keyboard interactions are expected? Who benefits?
+ placeholder: "This maps to the ARIA [pattern] role. Users should be able to [keyboard interaction]."
+ validations:
+ required: true
+
+ - type: textarea
+ id: performance
+ attributes:
+ label: Performance Considerations
+ description: Only required for components that render multiple items (lists, tables, grids). Address DOM node counts, virtualization, and measurement strategy.
+ placeholder: "For N items, this renders [X] DOM nodes. Virtualization strategy: ..."
+ validations:
+ required: false
+
+ - type: checkboxes
+ id: checklist
+ attributes:
+ label: Pre-submission Checklist
+ options:
+ - label: I have read the [Contributing guide](https://github.com/facebookexperimental/xds/wiki/Contributing)
+ required: true
+ - label: I have read the [API Conventions](https://github.com/facebookexperimental/xds/wiki/API-Conventions)
+ required: true
+ - label: I have checked that existing XDS components cannot compose to solve this
+ required: true
+ - label: This is a general-purpose UI pattern (not specific to one product)
+ required: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b0a2a0b5c5..5318ea7775 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,17 @@
# Contributing to XDS
+For the full contribution process — what we accept, how to propose new components, and how API decisions are made — read the **[Contributing wiki](https://github.com/facebookexperimental/xds/wiki/Contributing)**.
+
+Key pages:
+- **[API Conventions](https://github.com/facebookexperimental/xds/wiki/API-Conventions)** — naming, prop patterns, composition rules (read before submitting an RFC)
+- **[Specification Protocol](https://github.com/facebookexperimental/xds/wiki/Component-Specification-Protocol)** — the 9-phase process for new components
+- **[API Arbitration](https://github.com/facebookexperimental/xds/wiki/API-Arbitration)** — how we resolve API design questions
+- **[Contributing with AI](https://github.com/facebookexperimental/xds/wiki/Contributing-with-AI-Assistants)** — safe zones, spec protocol, and working with AI tools
+
+This file covers local development setup.
+
+---
+
## Prerequisites
### Node.js
diff --git a/apps/docsite/src/app/(site)/community/page.tsx b/apps/docsite/src/app/(site)/community/page.tsx
index f6c598a997..1f3a0b0ef0 100644
--- a/apps/docsite/src/app/(site)/community/page.tsx
+++ b/apps/docsite/src/app/(site)/community/page.tsx
@@ -14,6 +14,8 @@ import {XDSDivider} from '@xds/core/Divider';
import * as stylex from '@stylexjs/stylex';
import {GITHUB_REPO} from '../../../constants';
+const WIKI_BASE = `${GITHUB_REPO}/wiki`;
+
const styles = stylex.create({
avatar: {
width: 48,
@@ -26,14 +28,6 @@ const styles = stylex.create({
alignItems: 'center',
gap: 12,
},
- badge: {
- fontSize: 12,
- fontWeight: 600,
- backgroundColor: 'var(--color-background-muted)',
- borderRadius: 12,
- paddingInline: 8,
- paddingBlock: 2,
- },
});
interface Contributor {
@@ -66,30 +60,158 @@ export default async function CommunityPage() {
<XDSVStack gap={8}>
{/* Welcome */}
<XDSVStack gap={3}>
- <XDSHeading level={1}>Community</XDSHeading>
+ <XDSHeading level={1}>Contributing</XDSHeading>
<XDSText type="large" color="secondary">
- XDS is built in the open. We welcome contributions of all
- kinds—whether it&apos;s fixing a typo, proposing a new component, or
- improving documentation.
+ XDS has a high bar for what goes in and a clear process for getting
+ there. We accept bug fixes, templates, themes, and new components
+ via RFC.
</XDSText>
</XDSVStack>
- {/* Links */}
+ {/* Process overview */}
<XDSVStack gap={3}>
- <XDSHeading level={2}>Get Involved</XDSHeading>
+ <XDSHeading level={2}>How It Works</XDSHeading>
+ <XDSText type="body">
+ Contributing to XDS means contributing to the system — not to a
+ single component. Once something is in, it belongs to the
+ system&apos;s coherence. API decisions are resolved through vibe
+ testing and documented conventions, making them objective and
+ reproducible.
+ </XDSText>
<XDSGrid columns={{minWidth: 250, repeat: 'fill'}} gap={3}>
<XDSCard padding={4}>
<XDSVStack gap={1}>
<XDSText type="body" weight="bold">
- Contribution Guide
+ 1. Propose via RFC
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Describe the problem and evidence of demand. We respond within
+ 1 week with acceptance or decline.
+ </XDSText>
+ <XDSLink
+ label="Submit an RFC"
+ href={`${GITHUB_REPO}/issues/new?template=rfc.yml`}
+ isExternalLink>
+ Submit an RFC
+ </XDSLink>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ 2. Drive the Spec Protocol
</XDSText>
<XDSText type="supporting" color="secondary">
- Learn how to set up the repo, write components, and submit
- pull requests.
+ Either of us drives research, use case enumeration, and API
+ exploration. Contributors can front-load this work.
+ </XDSText>
+ <XDSLink
+ label="Spec protocol"
+ href={`${WIKI_BASE}/Component-Specification-Protocol`}
+ isExternalLink>
+ Spec protocol
+ </XDSLink>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ 3. Implement &amp; Land in Lab
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Build to the design brief. Contributions land in lab for
+ testing. Graduation to core when battle-tested and hardened.
+ </XDSText>
+ </XDSVStack>
+ </XDSCard>
+ </XDSGrid>
+ </XDSVStack>
+
+ {/* Safe zones */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Start Here (No RFC Needed)</XDSHeading>
+ <XDSText type="body" color="secondary">
+ These areas are open for direct contributions and don&apos;t require
+ the full RFC process:
+ </XDSText>
+ <XDSGrid columns={{minWidth: 250, repeat: 'fill'}} gap={3}>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Bug Fixes
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Open an issue to confirm the behaviour is a bug, then submit a
+ PR with a test or reproduction case.
+ </XDSText>
+ <XDSLink
+ label="Report a bug"
+ href={`${GITHUB_REPO}/issues/new?template=bug.yml`}
+ isExternalLink>
+ Report a bug
+ </XDSLink>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Templates &amp; Stories
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Show components in realistic context. Templates are training
+ signal for both humans and LLMs.
+ </XDSText>
+ <XDSLink
+ label="Template guide"
+ href={`${WIKI_BASE}/Contributing-Templates`}
+ isExternalLink>
+ Template guide
+ </XDSLink>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Themes
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Full visual control through defineTheme(). Token values,
+ component overrides, and mode switching.
+ </XDSText>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Documentation
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Fix typos, improve examples, fill gaps. Reviewed for
+ correctness — precision over comprehensiveness.
+ </XDSText>
+ </XDSVStack>
+ </XDSCard>
+ </XDSGrid>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Resources */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Resources</XDSHeading>
+ <XDSGrid columns={{minWidth: 250, repeat: 'fill'}} gap={3}>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Contributing Guide
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ The full process — what we accept, how API review works, and
+ what to expect.
</XDSText>
<XDSLink
label="Read the guide"
- href={`${GITHUB_REPO}/blob/main/CONTRIBUTING.md`}
+ href={`${WIKI_BASE}/Contributing`}
isExternalLink>
Read the guide
</XDSLink>
@@ -98,49 +220,100 @@ export default async function CommunityPage() {
<XDSCard padding={4}>
<XDSVStack gap={1}>
<XDSText type="body" weight="bold">
- Code of Conduct
+ Contributing with AI
</XDSText>
<XDSText type="supporting" color="secondary">
- Our community standards and expectations for respectful
- collaboration.
+ Using AI assistants effectively within XDS conventions. Safe
+ zones, spec protocol, and common pitfalls.
</XDSText>
<XDSLink
- label="View code of conduct"
- href={`${GITHUB_REPO}/blob/main/CODE_OF_CONDUCT.md`}
+ label="AI guide"
+ href={`${WIKI_BASE}/Contributing-with-AI-Assistants`}
isExternalLink>
- View code of conduct
+ AI guide
</XDSLink>
</XDSVStack>
</XDSCard>
<XDSCard padding={4}>
<XDSVStack gap={1}>
<XDSText type="body" weight="bold">
- License
+ API Conventions
</XDSText>
<XDSText type="supporting" color="secondary">
- XDS is released under the MIT License.
+ Naming rules, prop patterns, composition model. Read before
+ submitting an RFC.
</XDSText>
<XDSLink
- label="View license"
- href={`${GITHUB_REPO}/blob/main/LICENSE`}
+ label="Conventions"
+ href={`${WIKI_BASE}/API-Conventions`}
isExternalLink>
- View license
+ Conventions
+ </XDSLink>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ API Arbitration
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ How we resolve API design disputes with vibe testing. Includes
+ a sample prompt for running your own.
+ </XDSText>
+ <XDSLink
+ label="Arbitration process"
+ href={`${WIKI_BASE}/API-Arbitration`}
+ isExternalLink>
+ Arbitration process
+ </XDSLink>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Dev Setup
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Clone, install, build, and run Storybook. Everything you need
+ to start developing.
+ </XDSText>
+ <XDSLink
+ label="Setup guide"
+ href={`${GITHUB_REPO}/blob/main/CONTRIBUTING.md`}
+ isExternalLink>
+ Setup guide
+ </XDSLink>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard padding={4}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Code of Conduct
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Community standards for respectful collaboration.
+ </XDSText>
+ <XDSLink
+ label="View code of conduct"
+ href={`${GITHUB_REPO}/blob/main/CODE_OF_CONDUCT.md`}
+ isExternalLink>
+ View code of conduct
</XDSLink>
</XDSVStack>
</XDSCard>
<XDSCard padding={4}>
<XDSVStack gap={1}>
<XDSText type="body" weight="bold">
- Issues &amp; Discussions
+ License
</XDSText>
<XDSText type="supporting" color="secondary">
- Report bugs, request features, or ask questions on GitHub.
+ XDS is released under the MIT License.
</XDSText>
<XDSLink
- label="Open an issue"
- href={`${GITHUB_REPO}/issues`}
+ label="View license"
+ href={`${GITHUB_REPO}/blob/main/LICENSE`}
isExternalLink>
- Open an issue
+ View license
</XDSLink>
</XDSVStack>
</XDSCard>