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.ymlnew file mode 100644index 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: falsediff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.ymlnew file mode 100644index 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: truediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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.jsdiff --git a/apps/docsite/src/app/(site)/community/page.tsx b/apps/docsite/src/app/(site)/community/page.tsxindex 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'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'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 & 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'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 & 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><XDSLinklabel="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 & 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>