Skip to content

[NO-JIRA] Update Constitution Principle V to align with React 19 #4508

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Vincent Liu (xiaogliu) merged 5 commits into from
May 25, 2026
Merged

[NO-JIRA] Update Constitution Principle V to align with React 19 #4508

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3b631e2
[NO-JIRA] Update Constitution Principle V for React 19 alignment
May 20, 2026
4a57294
Merge branch 'main' into xiaogliu/constitution-v-update
xiaogliu May 21, 2026
8aad215
Merge branch 'main' into xiaogliu/constitution-v-update
xiaogliu May 21, 2026
5637c8c
[NO-JIRA] Address Copilot review feedback on Principle V wording
May 21, 2026
8a1e7af
[NO-JIRA] Address Principle V follow-up review feedback
May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 18 additions & 17 deletions .specify/memory/constitution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,16 @@
<!--
Sync Impact Report:
Version: 1.0.1 → 1.0.2 (PATCH - Template improvements and example corrections)
Modified principles: None (content clarifications only)
Version: 1.0.2 → 1.1.0 (MINOR - Principle V guidance updated for React 19 alignment)
Modified principles:
- V. TypeScript Migration & Type Safety: replaced "maintain both TypeScript types
and prop-types during migration" with explicit guidance to remove prop-types
and function-component defaultProps in favour of TypeScript types and ES6
destructuring defaults, aligning with React 19 (which removed both APIs).
Copy link
Copy Markdown
Contributor

@RichardSyq Richard-Shen (RichardSyq) May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small wording suggestion: could we tighten this summary to match the more precise wording in the principle body?

“React 19 (which removed both APIs)” still sounds like both propTypes and defaultProps APIs were removed wholesale. The React 19 upgrade guide is narrower: React now ignores propTypes checks, and defaultProps no longer applies to function components, while class components still support defaultProps.

Maybe:

aligning with React 19, which ignores propTypes checks and no longer applies defaultProps for function components.

Copy link
Copy Markdown
Contributor Author

@xiaogliu Vincent Liu (xiaogliu) May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed — the summary was still too strong. Updated in 8a1e7af to mirror the body wording: "aligning with React 19, which ignores propTypes checks and no longer applies defaultProps for function components."

Added sections: None
Removed sections: None
Changes made:
- Updated component name placeholders from BpkComponentName to Bpk[ComponentName] format across all templates for consistency
- Changed color token examples from $bpk-color-primary to $bpk-color-white for better visual contrast demonstration
- Added "e.g." prefix to all examples for clarity
- Removed package.json references from templates (components don't have individual package.json in Monorepo)
- Corrected Storybook examples structure (stories.tsx, examples.tsx in examples/ directory)
- Adjusted task numbering in tasks-template.md after package.json removal
Templates status:
- ✅ .specify/templates/spec-template.md - Updated with Bpk[ComponentName] format and corrected examples
- ✅ .specify/templates/plan-template.md - Updated structure and removed package.json reference
- ✅ .specify/templates/tasks-template.md - Updated with correct task sequence and examples
Follow-up TODOs: None - all templates aligned and corrected
- ✅ No template changes required
Copy link
Copy Markdown
Contributor

@RichardSyq Richard-Shen (RichardSyq) May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: could we update the task template in the same PR?

Principle V now says migrated components should replace prop-types with TypeScript types and use ES6 defaults instead of function-component defaultProps, but .specify/templates/tasks-template.md still generates a task to “Add prop-types for runtime validation” and a Constitution Check for “TypeScript types + prop-types during migration”.

That leaves newly generated tasks contradicting the updated constitution. I think T015 should be reworded to match the new guidance, and this Sync Impact Report should no longer say “No template changes required”.

Copy link
Copy Markdown
Contributor Author

@xiaogliu Vincent Liu (xiaogliu) May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch — fixed in 8a1e7af. Updated .specify/templates/tasks-template.md T015 to drop the "Add prop-types for runtime validation" sub-step and reworded its Constitution Check to match the new Principle V (TypeScript types REQUIRED; prop-types and function-component defaultProps MUST NOT be used). Also corrected the Sync Impact Report to list this template change instead of "No template changes required".

Follow-up TODOs: None
-->

# Backpack Design System Constitution
Expand Down Expand Up @@ -164,7 +159,9 @@ Every public-facing component MUST meet WCAG 2.1 Level AA standards:
All new code MUST be written in TypeScript:

- Use TypeScript for all new components and utilities
- Maintain both TypeScript types and prop-types during migration
- When migrating a component, replace `prop-types` with TypeScript types and replace
function-component `defaultProps` with ES6 destructuring defaults. Class-component
`defaultProps` may remain (no ES6 equivalent exists)
Comment thread
xiaogliu marked this conversation as resolved.
Outdated
- Generate `.d.ts` declaration files for published packages
- Use JSDoc `@deprecated` tags for deprecated APIs
- Add console warnings for deprecated prop usage at runtime
Expand All @@ -178,7 +175,7 @@ type MyCompProps = {
}
```

**Rationale**: TypeScript provides type safety, better IDE support, and catches errors at compile time. See `decisions/ts-deprecating-props.md`.
**Rationale**: TypeScript provides type safety, better IDE support, and catches errors at compile time. React 19 removes `propTypes` and function-component `defaultProps` from the React package ([upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#removed-proptypes-and-defaultprops)), so retaining them during migration is either no-op or actively broken. See `decisions/ts-deprecating-props.md`.
Comment thread
xiaogliu marked this conversation as resolved.
Outdated

### VI. Semantic Versioning (SemVer)

Expand Down Expand Up @@ -500,11 +497,15 @@ Constitution amendments require:

### Version History

- **Version**: 1.0.2
- **Version**: 1.1.0
- **Ratified**: 2025-12-22
- **Last Amended**: 2026-01-19
- **Last Amended**: 2026-05-20

**Changelog**:
- v1.1.0 (2026-05-20): Updated Principle V (TypeScript Migration & Type Safety) to align with React 19
- Replaced "maintain both TypeScript types and prop-types during migration" guidance with explicit instruction to remove `prop-types` and function-component `defaultProps` in favour of TypeScript types and ES6 destructuring defaults
- Added React 19 upgrade guide reference in Rationale
- Reflects current migration practice (BpkProgress, BpkRadio, BpkFormValidation, BpkAutosuggest, BpkPagination)
- v1.0.2 (2026-01-19): Template improvements and example corrections
- Standardized component name placeholders to `Bpk[ComponentName]` format
- Updated color token examples to use `$bpk-color-white` for better contrast demonstration
Expand Down
Loading