diff --git a/.cursor/README.md b/.cursor/README.md new file mode 100644 index 0000000000..49b733b610 --- /dev/null +++ b/.cursor/README.md @@ -0,0 +1,59 @@ +# Cursor rules documentation + +This directory contains rules that Cursor uses to enforce consistent formatting and structure in our codebase. + +## Rule structure + +Rules defined in the `config.json` follow this structure: + +```json +{ + "version": 1, + "rules": { + "category": { + "rule_name": { + "enabled": true, + "pattern": "regex_pattern", + "message": "Error message" + } + } + } +} +``` + +Additional, more specific rules can be found in the `rules` directory in either a `json` or `mdc` format. + +## Available rules + +### Text formatting + +- **heading_case**: Enforces sentence case in headings with specific exceptions + - Applies to: `.md`, `.txt`, `.mdx` files + - Exceptions: Technical terms and acronyms + +### Jira tickets + +- **ticket_title**: Validates Jira ticket title format + - Optional component in brackets + - Max length: 80 characters +- **required_sections**: Ensures required sections are present +- **templates**: Enforces template structure for different ticket types +- **labels**: Validates that only allowed labels are used +- **issue_types**: Ensures correct issue type selection + +## Usage + +1. Cursor will automatically enforce these rules while editing relevant files; however, if you wish to enable a rule that is not triggered by default, you can do so by `@` mentioning it in the chat. +2. Rules can be toggled using the `enabled` flag +3. Custom error messages will be shown when rules are violated +4. Exceptions are handled through the `exceptions` field in relevant rules + +## Updating rules + +To modify these rules: + +1. Edit the `config.json` or the appropriate file in the `rules` directory +2. Try to follow the existing structure and format where possible +3. Ensure valid regex patterns, where applicable +4. Include clear error messages +5. Test changes before committing diff --git a/.cursor/config.json b/.cursor/config.json new file mode 100644 index 0000000000..83f77a4bfa --- /dev/null +++ b/.cursor/config.json @@ -0,0 +1,149 @@ +{ + "text_formatting": { + "headings": { + "case": "sentence", + "files": ["**/*.md", "**/*.txt", "**/*.mdx"], + "message": "Use sentence case (capitalize only the first word and proper nouns/acronyms)", + "inline": true + }, + "patterns": ["**/*.md", "**/*.txt", "**/*.mdx"] + }, + "jira_tickets": { + "title_format": { + "pattern": "^\\[?[A-Za-z0-9-]+\\]?\\s.+$", + "max_length": 80 + }, + "required_sections": ["Acceptance case", "Overview"], + "labels": { + "a11y": "Accessibility issues", + "API": "Component API changes", + "docs": "Documentation updates", + "engineering-processes": "Engineering workflow improvements", + "feature": "New features", + "hold": "Suspended tickets", + "i18n": "Internationalization work", + "iOS": "iOS-specific issues", + "mobile": "Mobile platform issues", + "necromancy": "Old backlog tickets (>2 years)", + "product-processes": "Product team process improvements", + "refactor": "Code restructuring", + "research": "Investigation tasks", + "RFC": "Request for Comments", + "s2foundations": "S2 Foundations work", + "spectrum2": "Spectrum 2 tasks", + "team-processes": "Team workflow improvements", + "testing": "Test implementation", + "triage": "Needs assessment", + "VoiceOver": "VoiceOver specific issues" + }, + "issue_types": ["Bug", "Epic", "Story", "Task"], + "templates": { + "bug": { + "required_fields": [ + "Expected behaviour", + "Actual behaviour", + "Reproduction steps", + "Severity" + ] + }, + "feature": { + "required_fields": ["Overview", "Acceptance criteria"], + "optional_fields": [ + "Estimated internal impact", + "Estimated external impact", + "Anticipated reviewing audience", + "Proposed solutions", + "Supplementary documentation" + ] + } + } + }, + "git": { + "branchNameTemplate": "{username}/{type}-{description}{?-{issue}}", + "types": [ + "feat", + "fix", + "docs", + "style", + "refactor", + "perf", + "test", + "build", + "ci", + "chore", + "revert" + ], + "promptForIssueNumber": true, + "allowEmptyIssueNumber": true, + "transformDescription": "lowercase-dashed", + "validationPattern": "^[a-z0-9]+\\/(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)-[a-z0-9-]+(-swc-[0-9]+)?$", + "validationMessage": "Branch name should follow format: username/type-description[-swc-issue]" + }, + "editor": { + "formatOnSave": true, + "defaultFormatter": "prettier", + "tabSize": 4, + "insertSpaces": true, + "endOfLine": "auto", + "charset": "utf-8" + }, + "language": { + "typescript": { + "formatOnSave": true, + "organizeImportsOnSave": true, + "addMissingImports": "prompt", + "defaultFormatter": "eslint" + }, + "javascript": { + "formatOnSave": true, + "defaultFormatter": "eslint", + "organizeImportsOnSave": true, + "addMissingImports": "prompt", + "moduleResolution": "auto", + "snippets": { + "newScript": { + "detectModuleFormat": true, + "preferESM": true + } + } + }, + "css": { + "formatOnSave": true, + "defaultFormatter": "stylelint" + } + }, + "terminal": { + "defaultProfile": "${os.shell}", + "integrated": { + "fontFamily": "${os.monospace}", + "fontSize": 12, + "shell": { + "windows": "powershell.exe", + "linux": "bash", + "osx": "bash" + } + } + }, + "search": { + "exclude": { + "**/node_modules": true, + "**/dist": true, + "**/.git": true, + "**/.vs": true, + "**/.idea": true, + "**/*.css.js": true, + "**/*.css.ts": true, + "**/*.d.ts": true, + "**/coverage": true, + "**/.wireit": true, + "**/*.tsbuildinfo": true, + "**/custom-elements.json": true, + "**/test/benchmark/results": true, + "**/storybook-static": true, + "**/*.min.*": true, + "**/*.map": true + }, + "useGitIgnore": true, + "followSymlinks": false + } +} diff --git a/.cursor/rules/branch-naming.mdc b/.cursor/rules/branch-naming.mdc new file mode 100644 index 0000000000..288e704f69 --- /dev/null +++ b/.cursor/rules/branch-naming.mdc @@ -0,0 +1,53 @@ +--- +description: +globs: +alwaysApply: true +--- +# Branch naming format + +Suggests the ideal branch naming format for Spectrum Web Components contributions. + +## Pattern +``` +^[a-z0-9]+\/(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)-[a-z0-9-]+(-swc-[0-9]+)?$ +``` + +## Message +Consider following the preferred branch naming format: `/-[-swc-]` + +Username will be automatically pulled from your git config settings. + +### Guidelines +- Use lowercase letters and numbers only +- Separate words with dashes (not camelCase) +- Use conventional commit types: + • **feat**: New feature + • **fix**: Bug fix + • **docs**: Documentation only + • **style**: Code style/formatting + • **refactor**: Code change that neither fixes a bug nor adds a feature + • **perf**: Code change that improves performance + • **test**: Adding missing tests or correcting existing tests + • **build**: Changes that affect the build system or external dependencies + • **ci**: Changes to CI configuration files and scripts + • **chore**: Other changes that don't modify src or test files + • **revert**: Reverts a previous commit +- Optional issue number format: `-swc-XXX` + +### Good examples +- `johndoe/feat-add-new-button-swc-123` +- `janedoe/fix-dropdown-alignment` +- `alice/refactor-component-structure` +- `bob/perf-optimize-rendering` + +### Avoid +- `johnDoe/feat-addNewButton` (no camelCase) +- `jane/fix-Dropdown-Bug` (no uppercase) + +This is a recommended format to maintain consistency, but not required. + +## Severity +warning + +## Scope +git_branch diff --git a/.cursor/rules/github-description.mdc b/.cursor/rules/github-description.mdc new file mode 100644 index 0000000000..b3de3947ee --- /dev/null +++ b/.cursor/rules/github-description.mdc @@ -0,0 +1,217 @@ +# GitHub description guidelines + +Note for Cursor: If a ticket (GitHub issue or Jira ticket) is not provided by the prompt, prompt the user to supply one before generating the description or pull request content. + +When prompted to create a GitHub description, output the following: + +- Title +- Labels +- Description + +Output results in the chat window in a way that can be copied and pasted into GitHub. + +## GitHub markdown formatting rules + +Use these syntax rules when writing GitHub descriptions: + +- `##` through `######` - Headings (use `##` for main, `###` for secondary, etc.) +- `**text**` - Bold text +- `` `code` `` - Inline code +- ```` ```language` ``` - Language-specific code blocks +- `[text](url)` - Links +- `-` - Bullet points +- `1.` - Numbered list items +- `>` - Blockquotes for important notes +- `~~text~~` - Strikethrough for deprecated content + +## Title format + +- Use the format: `[Component] Brief description of change or issue` +- Keep titles concise but descriptive (under 80 characters) +- Use present tense for the description (e.g., "Add" not "Added") +- For PRs, include the component name in brackets if applicable + +## Description structure + +- Present title, labels, and type before description content +- Include links to related issues, RFCs, or documentation when applicable +- All descriptions must include clear acceptance criteria or expected outcomes +- Provide enough context so anyone can understand the objective +- Use prefixes in titles: [Bug], [Fix], [Docs], [Refactor], [Research], [S2], [Test] + +Examples: + +- [bug]: +- [Bug(component)]: +- [fix]: +- [Fix(component)]: +- [docs]: +- [Docs(component)]: + +## Severity classification + +- SEV1: Critical - System down, data loss, security breach +- SEV2: High - Major feature broken, significant user impact +- SEV3: Medium - Feature partially broken, moderate impact +- SEV4: Low - Minor issues, minimal user impact +- SEV5: Trivial - Cosmetic issues, no functional impact + +## Best practices + +- Link to relevant issues using the format: `#issue-number` +- Include component name in brackets if applicable: `[sp-button]` +- Add relevant labels for easier filtering +- Attach screenshots or videos for visual changes +- Reference design specs or documentation when available +- Use descriptive commit messages when linking to PRs +- Include reproduction steps for bugs +- Add environment information when relevant + +## Acceptance criteria + +- Write criteria in "Given/When/Then" format +- Make criteria specific and testable +- Include edge cases and error scenarios +- Consider accessibility requirements +- Include performance considerations when relevant + +## Labels + +Use the following labels to categorize pull requests. Only use labels that exist in the repository: + +### Priority and release labels + +- `1.0.0`: Issues that should be addressed for a 1.0 release +- `2.0.0`: Issues for 2.0 release +- `Breaking`: Breaking changes + +### Platform and browser labels + +- `Android`: Android-specific issues +- `Browser: Chrome`: Chrome browser issues +- `Browser: Edge (Legacy)`: Issue with pre-chromium Edge +- `Browser: FireFox`: Firefox browser issues +- `Browser: Safari`: Safari browser issues + +### Development and process labels + +- `a11y`: Issues related to accessibility +- `API`: Changes to component APIs or interfaces + +### Additional labels (partial list) + +Note: The repository has 160 labels total. For a complete list, visit [https://github.com/adobe/spectrum-web-components/labels](https://github.com/adobe/spectrum-web-components/labels) + +Common additional labels include: + +- `chore`: Routine tasks, maintenance, or non-feature changes +- `dependencies`: Updates or changes to project dependencies +- `docs`: Documentation updates or improvements +- `enhancement`: Improvements to existing features +- `feature`: New feature implementations +- `i18n`: Internationalization and localization work +- `iOS`: iOS-specific issues and bugs +- `mobile`: Mobile platform issues and responsive design +- `performance`: Performance-related improvements or regressions +- `refactor`: Code restructuring and refactoring work +- `regression`: Previously working functionality that is now broken +- `release`: Release process or versioning changes +- `research`: Tasks requiring investigation or research +- `RFC`: Request for Comments or design discussions +- `testing`: Test implementation or testing infrastructure work + +## Pull request guidelines + +- Use conventional commit messages +- Keep PRs focused and small when possible +- Include tests for new features +- Update documentation when APIs change +- Add screenshots for visual changes +- Link to related issues using keywords like "Fixes #123" or "Closes #456" +- Request reviews from appropriate team members +- Use draft PRs for work in progress + +## Templates + +### Pull request template + +**Note:** All pull requests should include the `ready-for-review` label. + +**When returning the template, check off the author requirements in the Author's checklist section. Do not check off the Manual review test cases or Device review sections as these are for reviewers to complete.** + +```markdown + + +## Description + + + +## Motivation and context + + + +## Related issue(s) + + + +- fixes [Issue Number] + +## Screenshots (if appropriate) + + +## Author's checklist + + + +- [ ] I have read the **[CONTRIBUTING](<(https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTING.md)>)** and **[PULL_REQUESTS](<(https://github.com/adobe/spectrum-web-components/blob/main/PULL_REQUESTS.md)>)** documents. +- [ ] I have reviewed at the Accessibility Practices for this feature, see: [Aria Practices](https://www.w3.org/TR/wai-aria-practices/) +- [ ] I have added automated tests to cover my changes. +- [ ] I have included a well-written changeset if my change needs to be published. +- [ ] I have included updated documentation if my change required it. + + +## Reviewer's checklist + +- [ ] Includes a Github Issue with appropriate flag or Jira ticket number without a link +- [ ] Includes thoughtfully written changeset if changes suggested include `patch`, `minor`, or `major` features +- [ ] Automated tests cover all use cases and follow best practices for writing +- [ ] Validated on all supported browsers +- [ ] All VRTs are approved before the author can update Golden Hash + +### Manual review test cases + + + +- [ ] _Descriptive Test Statement_ + + 1. Go [here](url) + 2. Do this action + 3. Expect this result + +- [ ] _Descriptive Test Statement_ + 1. Go [here](url) + 2. Do this action + 3. Expect this result + +### Device review + + + +- [ ] Did it pass in Desktop? +- [ ] Did it pass in (emulated) Mobile? +- [ ] Did it pass in (emulated) iPad? + +``` diff --git a/.cursor/rules/jira-ticket.mdc b/.cursor/rules/jira-ticket.mdc new file mode 100644 index 0000000000..7d618120b4 --- /dev/null +++ b/.cursor/rules/jira-ticket.mdc @@ -0,0 +1,199 @@ +--- +description: Guidelines for drafting and formatting Jira tickets +alwaysApply: false +--- +# Jira ticket guidelines + +When prompted to create a Jira ticket, output the following: + +- Title +- Labels +- Severity +- Description + +Output results in the chat window in a way that can be copied and pasted into Jira. + +## Jira syntax formatting rules + +Use these syntax rules when writing Jira tickets: + +- `h2.` through `h6.` - Headings (use `h2.` for main, `h3.` for secondary, etc. - avoid `h1.` in descriptions) +- `{*}{*}` - Bold text +- `{code}{code}` - Inline code +- `{code:language}{code}` - Language-specific code blocks +- `[text|url]` - Links +- ` - ` - Bullet points +- `#` - Numbered list items + +## Title format + +- Use the format: `[Component] Brief description of change or issue` +- Keep titles concise but descriptive (under 80 characters) +- Use present tense for the description (e.g., "Add" not "Added") + +## Description structure + +- Present title, labels, and severity before description content +- Include links to GitHub pull requests or RFCs when applicable (prompt if not provided) +- All tickets must include acceptance criteria +- Provide enough context so anyone can understand the objective +- Use prefixes in titles: [Bug], [Fix], [Docs], [Refactor], [Research], [S2], [Test] + +Examples: + +- [Bug(component)]: +- [bug]: +- [Fix(component)]: +- [fix]: +- [Docs(component)]: +- [docs]: +- [Documentation]: +- [Refactor(component)]: +- [Research(component)]: +- [discovery]: +- [RFC(component)]: +- [S2 Foundations]: +- [S2]: +- [Test(component)]: + +## More specific templates + +### General Jira ticket template + +``` +h2. Acceptance criteria +(how we ensure that the work is complete) + +h2. Overview +(plain language explaining the ticket) + +h2. Technical notes/resources +(any technical notes/links/etc) + +h2. QA +(steps someone will use to be sure that the work fulfills the ticket's request and that everything's working properly) + +h2. Design specs +(are there any design specs/files/mock-ups we can include here? Any other design notes?) +``` + +### Bug reporting template + +``` +{*}Link to original issue:{*} (Add a link to the original issue in GitHub if applicable) + +h2. Expected behavior +(Description of what the user would expect to happen) + +h2. Actual behavior +(The actual behavior observed by the user) + +h2. Screenshots +(Screenshots of the problem if applicable) + +h2. How can we reproduce the issue? + +# Go to '...' +# Click on '....' +# Scroll to '....' +# Check console +# See error + +h2. Sample code or abstract reproduction which illustrates the problem +(are there any design specs/files/mock-ups we can include here? Any other design notes?) + +h2. Severity +(The severity of the issue according to the [documentation|https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTING.md#issue-severity-classification]) +``` + +### RFC or feature ticket template + +This ticket template is for tracking work for RFCs, new features, new components, or research tickets. This template is not a substitute for the deliverable itself; rather, it's setting expectations for what the deliverable might look like and gives a high-level overview of the problem being tackled so that others can understand what is being worked on. + +Items with an asterisk are optional depending on the context. + +``` +h2. Link to original issue +(Add a link to the original issue in GitHub if applicable) + +h2. Overview +(The problem you're looking to explore solutions for or do research on) + +h2. Acceptance criteria +(What is the desired outcome of this RFC or research process? What would make this ticket "done"? What follow-up work would be required? Refer to the RFC guide for examples.) + +h2. Estimated internal impact +(If implemented, what impact would this work have on other APIs, other components, the project structure, or team initiatives? Refer to the impact diagram for details.) + +h2. Estimated external impact +(If implemented, what impact would this work have on consumers or downstream/upstream dependencies?) + +h2. Anticipated reviewing audience +(Who would you like to provide feedback on your RFC/research? Your immediate team, your partners, or a wider consumer audience? What are their roles?) + +h2. Proposed solutions +(Pseudocode or short description that outlines what the solution might look like. You may not have any solutions yet.) + +h2. Supplementary documentation +(Has this feature or component been implemented in existing design specs or in another project? Share those here to paint a bigger picture of the end result. For architectural changes, have you seen this done in other libraries? Are there any tools you're looking at trying out to solve your problem?) + +h2. Additional context +(Add any other context, drafts, etc. if you have them) +``` + +## Severity classification + +- SEV1: Critical - System down, data loss, security breach +- SEV2: High - Major feature broken, significant user impact +- SEV3: Medium - Feature partially broken, moderate impact +- SEV4: Low - Minor issues, minimal user impact +- SEV5: Trivial - Cosmetic issues, no functional impact + +## Best practices + +- Link to relevant GitHub issues or pull requests using the format: `GH-{number}` +- Include component name in brackets if applicable: `[sp-button]` +- Add relevant labels for easier filtering +- Attach screenshots or videos for visual changes +- Reference design specs or documentation when available + +## Acceptance criteria + +- Write criteria in "Given/When/Then" format +- Make criteria specific and testable +- Include edge cases and error scenarios +- Consider accessibility requirements + +## Labels + +Use the following labels to categorize tickets appropriately: + +- `a11y`: Accessibility-related issues and improvements +- `API`: Changes to component APIs or interfaces +- `docs`: Documentation updates or docs site changes +- `engineering-processes`: Engineering workflow and process improvements +- `feature`: New feature implementations +- `hold`: Tickets temporarily suspended or blocked +- `i18n`: Internationalization and localization work +- `iOS`: iOS-specific issues and bugs +- `mobile`: Mobile platform issues and responsive design +- `necromancy`: Backlog tickets older than 2 years requiring revival +- `product-processes`: Process improvements for product team collaboration +- `refactor`: Code restructuring and refactoring work +- `research`: Tasks requiring investigation or research +- `RFC`: Request for Comments documentation +- `s2foundations`: Spectrum 2 Foundations related work +- `spectrum2`: Spectrum 2 platform specific tasks +- `team-processes`: Internal team workflow improvements +- `testing`: Test implementation or testing infrastructure work +- `triage`: New tickets requiring team assessment and prioritization +- `VoiceOver`: VoiceOver screen reader specific issues + +## Issue type + +Jira includes the following issue types: + +- Bug: For something in the code that needs to be fixed. +- Epic: For tickets that are larger than 8 story points and need to be broken up into multiple issues. +- Story: For tickets that tie to code deliverables. Whether that's research, an RFC, or a pull request, it counts! If you don't know what your issue type should be, this is a safe bet. +- Task: For work that doesn't relate to a code deliverable. diff --git a/.cursor/rules/styles.mdc b/.cursor/rules/styles.mdc new file mode 100644 index 0000000000..9f4b7a475d --- /dev/null +++ b/.cursor/rules/styles.mdc @@ -0,0 +1,14 @@ +--- +description: Rules for consistent styling in component CSS +globs: *.css +alwaysApply: true +--- + +1. Follow rules outlined in the `../../STYLING.md` file. +2. Auto-fix results based on settings defined by the `../../stylelint.config.js` unless it requires rewriting more than 30% of the line. Changes that impact more than 30% of the original content should prompt for update. +3. Copyrights should reflect the current year. +4. Comments added should always use sentence, never title case. +5. Any files removed should also be removed from the exports of the component's package.json. +6. Never rename a custom property without prompting for approval first or being expressly asked to update the custom property name. +7. Sort high-contrast and other media queries to the bottom of the CSS file. +8. Warn about or suggest fixes for duplicate properties; always opt to keep the definition that honors the CSS cascade. diff --git a/.cursor/rules/text-formatting.mdc b/.cursor/rules/text-formatting.mdc new file mode 100644 index 0000000000..5e588c51d9 --- /dev/null +++ b/.cursor/rules/text-formatting.mdc @@ -0,0 +1,46 @@ +--- +description: Text formatting and capitalization rules for documentation and tickets +globs: **/*.md, **/*.txt,**/*.mdx +alwaysApply: true +--- + +# Text formatting conventions + +## Capitalization rules + +- Use sentence case for all headings and section titles (capitalize first word only) + - Correct: "Getting started with components" + - Incorrect: "Getting Started With Components" +- Exceptions: Proper nouns, acronyms, and technical terms should maintain their standard capitalization (e.g., JavaScript, CSS, HTML, GitHub) +- Never use all caps except for: + - Established acronyms (e.g., API, HTML, CSS) + - Severity levels (e.g., SEV1, SEV2) + +## Markdown formatting + +- Use backticks (`) for: + - Code snippets + - File names + - Component names + - Technical terms +- Use bold (**) for: + - Section headers in structured content + - Important terms on first use + - UI element names +- Use italics (*) sparingly, only for: + - Term definitions + - Emphasis in technical explanations + +## Lists and bullets + +- Start each bullet point with a capital letter +- End each bullet point consistently (either all with periods or all without) +- Use parallel structure in lists (all items should be same grammatical form) + +## Technical writing style + +- Use present tense +- Use active voice +- Be concise and direct +- Avoid jargon unless technically necessary +- Define abbreviations on first use