chore: cursor utilities [CSS-1222] #5505

castastrophe · 2025-05-29T19:09:49Z

Description

Added structured rules configuration for Cursor to enforce consistent formatting in documentation and Jira tickets. This includes:

JSON configuration for enforcing text formatting rules
Standardized templates for Jira tickets
Automated validation of ticket structure and labels
Documentation for rule usage and maintenance

Motivation and context

This change provides automated enforcement of our documentation standards and Jira ticket formatting, ensuring consistency across the project. It helps team members create well-structured tickets and maintain consistent documentation formatting without manual oversight.

Related issue(s)

fixes CSS-1222

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have included updated documentation in the form of README.md and rules.json.

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

Verify Jira ticket formatting rules
1. Create a new Jira ticket
2. Attempt to use title case in headings
3. Verify Cursor enforces sentence case with appropriate exceptions
Verify template enforcement
1. Create a new bug report
2. Skip required fields
3. Verify Cursor requires all mandatory sections
Verify label validation
1. Add a non-standard label to a ticket
2. Verify Cursor flags invalid labels
3. Confirm allowed labels are accepted

changeset-bot · 2025-05-29T19:09:54Z

⚠️ No Changeset found

Latest commit: 2d1b585

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-05-29T19:11:48Z

Branch preview

Review the following VRT differences

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

github-actions · 2025-05-29T19:15:04Z

Tachometer results

Currently, no packages are changed by this PR...

blunteshwar · 2025-06-11T07:03:21Z

I am experiencing some confusion. Currently, Jira tickets are created by us- so will cursor create the jira tickets after merging this??

castastrophe · 2025-06-11T13:39:48Z

I am experiencing some confusion. Currently, Jira tickets are created by us- so will cursor create the jira tickets after merging this??

@blunteshwar No, there's no access tokens for our Jira instance at this time so it can't make them but it can output the template for you via a prompt. For example, I've attached this instruction guide and described what I'd like to create a ticket for in plain language and it's stubbed out the information appropriately using the template. Then, after some clean-up, I can copy and paste that content into Jira.

marissahuysentruyt

I had a couple of questions for you!

marissahuysentruyt · 2025-06-13T19:11:14Z

.cursor/README.md

+
+## Rule structure
+
+Rules are defined in `rules.json` and follow this structure:


Should this just say "Rules are defined in the rules directory? Or .cursor/rules directory? Or config.json? There's not a rules.json file, that's all.

Yes! Great call-out. I've clarified this in the README by calling out the rules directory and the config.json

marissahuysentruyt · 2025-06-13T19:17:56Z

.cursor/config.json

+    },
+    "validation": {
+        "jira_tickets": {
+            "title": {


What's the difference with one jira_tickets object being under validation, vs the other that's just on its own? They're almost identical, with really small differences (like one has title, while the other has title_format).

Oh I don't know, great question. I'm going to remove the validation section in favor of the top-level object.

marissahuysentruyt · 2025-06-13T19:21:00Z

.cursor/README.md

+
+To modify these rules:
+
+1. Edit `rules.json`


Could we say "Edit the desired rule files in the rules directory" instead, since rules.json isn't a thing?

Yes, I updated this as you suggested

.cursor/rules/jira-ticket.mdc

marissahuysentruyt · 2025-06-17T17:10:27Z

.cursor/rules/branch-naming.json

What is the reasoning behind this file being .json and the others being .mdc? I only saw .mdc in the docs.

With an extra prompt to use this file, I was able to get Cursor to suggest a branch name that looked more like what we use. The first time it returned feature/flexible-max-width-utility, but with the reference to use branch-naming.json, I got marissa/feat-flexible-max-width-utility

Nice call-out! I actually asked Cursor to fix this haha!

marissahuysentruyt · 2025-06-17T18:09:56Z

.cursor/README.md

+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
+


Would we like to say anything about @ mentioning the rules in a chat? I made changes to a file, and then put this into the chat: @text-formatting.mdc double check the changes i made in the new jira ticket file. so that cursor would basically lint my changes based on the text-formatting rules.

I had to @ mention the jira ticket MDC file as well. This definitely could be something I'm doing in the wrong order or something.

marissahuysentruyt

Ok I tried to do some validation for this.

Creating a Jira ticket 👇

[CSS] Add text-wrap:balance to improve text wrapping

Overview

Implement text-wrap:balance CSS property to improve text wrapping behavior in components like toast bodies and alert headings. This property provides better text balance and readability while maintaining current rendering as a fallback for browsers that don't support it.

Acceptance criteria

Implement text-wrap:balance in the following components:
- sp-toast body text
- sp-alert headings
Verify fallback behavior in unsupported browsers
Test across different text lengths and container widths
Document browser support and fallback behavior

Estimated internal impact

Minimal implementation effort (CSS property addition only)
No JavaScript changes required
No breaking changes to existing behavior

Estimated external impact

Improved readability of multi-line text
Better visual balance in constrained-width components
No negative impact on browsers that don't support the property

Anticipated reviewing audience

CSS team
Component maintainers
Design team

Proposed solutions

Add text-wrap:balance to the following components:

sp-toast {
    text-wrap: balance;
}

sp-alert {
    text-wrap: balance;
}

Supplementary documentation

Browser support: High (nearly fully interoperable)
MDN documentation: https://developer.mozilla.org/en-US/docs/Web/CSS/text-wrap
Current fallback behavior will be maintained for unsupported browsers

Labels

feature

Check text-formatting 👇

Creating a bug issue 👇
(I prompted it to use the bug-report.yaml template)

Code of conduct

I agree to follow this project's code of conduct.

Impacted component(s)
sp-toast, sp-alert

Expected behavior
Text in components with constrained widths should use text-wrap:balance for improved readability and visual balance. This property is nearly fully interoperable and provides graceful fallback to current rendering behavior.

Actual behavior
Components like sp-toast and sp-alert do not use text-wrap:balance CSS property, resulting in suboptimal text wrapping and poor visual balance in multi-line text content. Text wrapping follows default browser behavior with no specific text balance optimization for multi-line text.

Screenshots
N/A - This is a feature enhancement request rather than a visual bug

What browsers are you seeing the problem in?

Firefox
Chrome
Safari
Microsoft Edge

How can we reproduce this issue?

Create a toast or alert with multi-line text content
Observe the text wrapping behavior in constrained width containers
Compare with what the layout would look like with text-wrap:balance applied
Notice the suboptimal text balance

Sample code or abstract reproduction which illustrates the problem

<sp-toast open>
  This is a longer message that will wrap across multiple lines and could benefit from better text balance
</sp-toast>

<sp-alert>
  <div slot="heading">This is a longer heading that spans multiple lines</div>
  Alert content here
</sp-alert>

Severity
SEV 5

Logs taken while reproducing problem
N/A - No console errors, this is an enhancement request

Would you like to track this issue in Jira?

Yes, please tell me the ticket number!

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch from cfec722 to 4f1aeea Compare May 29, 2025 19:21

castastrophe changed the title ~~chore: cursor utilities~~ chore: cursor utilities [CSS-1222] May 29, 2025

castastrophe self-assigned this May 29, 2025

castastrophe added Tooling ready-for-review jira ticket created auto-update Rebase PR automatically labels May 29, 2025

castastrophe marked this pull request as ready for review May 29, 2025 19:49

castastrophe requested a review from a team as a code owner May 29, 2025 19:49

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch 4 times, most recently from 22e3fb9 to 679219a Compare May 30, 2025 15:42

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch 2 times, most recently from 8d00142 to c796a9d Compare June 10, 2025 20:49

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch from c796a9d to f271758 Compare June 11, 2025 13:37

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch 2 times, most recently from d868b45 to 45f7257 Compare June 12, 2025 14:47

marissahuysentruyt reviewed Jun 13, 2025

View reviewed changes

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch from 45f7257 to d53786b Compare June 16, 2025 18:57

marissahuysentruyt reviewed Jun 17, 2025

View reviewed changes

.cursor/rules/jira-ticket.mdc Show resolved Hide resolved

marissahuysentruyt reviewed Jun 17, 2025

View reviewed changes

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch from d53786b to 48a6930 Compare June 19, 2025 13:21

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch 4 times, most recently from 52ffaad to 28576b6 Compare June 23, 2025 14:56

chore: cursor utilities

2d1b585

castastrophe force-pushed the castastrophe/chore-cursor-utilities branch from 28576b6 to 2d1b585 Compare June 23, 2025 15:48


		## Rule structure

		Rules are defined in `rules.json` and follow this structure:

chore: cursor utilities [CSS-1222] #5505

Are you sure you want to change the base?

chore: cursor utilities [CSS-1222] #5505

Conversation

castastrophe commented May 29, 2025 • edited by marissahuysentruyt Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Author's checklist

Reviewer's checklist

Manual review test cases

Uh oh!

changeset-bot bot commented May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented May 29, 2025

Branch preview

Review the following VRT differences

Uh oh!

github-actions bot commented May 29, 2025

Tachometer results

Uh oh!

blunteshwar commented Jun 11, 2025

Uh oh!

castastrophe commented Jun 11, 2025

Uh oh!

marissahuysentruyt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marissahuysentruyt Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt left a comment

Choose a reason for hiding this comment

[CSS] Add text-wrap:balance to improve text wrapping

Overview

Acceptance criteria

Estimated internal impact

Estimated external impact

Anticipated reviewing audience

Proposed solutions

Supplementary documentation

Labels

Uh oh!

Uh oh!

castastrophe commented May 29, 2025 •

edited by marissahuysentruyt

Loading

changeset-bot bot commented May 29, 2025 •

edited

Loading

marissahuysentruyt Jun 17, 2025 •

edited

Loading