feat: FIT-469: Introduce Cursor Rules for UX Standards #8067
Conversation
✅ Deploy Preview for label-studio-docs-new-theme canceled.
|
✅ Deploy Preview for heartex-docs canceled.
|
✅ Deploy Preview for label-studio-storybook canceled.
|
✅ Deploy Preview for label-studio-playground canceled.
|
.cursor/rules/ux-standards.mdc
Outdated
|
|
||
| ### Writing Guidelines | ||
| - Generate simple, concise language (aim for 7th-grade reading level or lower) | ||
| - Avoid jargon, acronyms (unless commonly known, spell out first use), and abbreviations (e.g., use "Upload Dataset" instead of "Initiate Data Ingestion Process") |
There was a problem hiding this comment.
example in parenthesis is confusing — how is it connected to acronyms or jargon?
.cursor/rules/ux-standards.mdc
Outdated
| - Importantly, explain what actions the user can take to remedy the issue, if any | ||
| - Display error messages close to the element causing the issue (e.g., inline validation errors for form fields) | ||
| - Provide a link to documentation that explains how to work with the desired entity (e.g. "See docs.") | ||
| - Ensure that doc links point to the correct Community or Enterprise URL (using an existing utility if the link would be available on both) |
There was a problem hiding this comment.
Here we should properly refer to /web/libs/editor/src/utils/docs.ts
| - Avoid relying solely on tooltips for critical information, as they may be missed by some users | ||
|
|
||
|
|
||
| ### Loading States, Progress, and Recovery |
There was a problem hiding this comment.
I would add advice to avoid jumping states when user might click on a wrong place because layout shifted right after the loading is finished
| - Use zebra striping or subtle borders for row separation to improve readability | ||
| - Include bulk selection patterns with clear action buttons | ||
| - Show loading states for individual table cells when applicable | ||
| - Display helpful metadata (e.g., "Showing 10 of 245 results" or "Last updated 2 minutes ago") |
There was a problem hiding this comment.
relative dates should always have a title/tooltip with absolute date and time
| ### Keyboard Navigation | ||
| - Ensure all interactive elements are keyboard focusable with logical tab order and clearly visible focus indicators | ||
| - Support standard keyboard shortcuts (e.g., ensure users can navigate through all form fields, buttons, and interactive elements using only the Tab key, and activate them with Enter or Space) | ||
| - Only show the focus outline when navigating using tab or assistive devices |
There was a problem hiding this comment.
This can be achieved by setting the tabindex parameter on HTML elements to define a logical order (which is heavily dependent on how elements flow on the screen). There are several caveats to this so we can expand these rules further.
The focus outline should only be displayed when navigating the pages in this manner. Currently we display it when interacting with the mouse which isn't best practice.
There was a problem hiding this comment.
Yeah, I know about tabIndex :)
The question is exactly about distinguishing focus from mouse and from keyboard navigation. I never heard of this distinction in real apps and don't know how to achieve it with css. I'd suggest to remove this rule.
There was a problem hiding this comment.
Also if we are going to remove focus after mouse interaction it would actually be against accessibility — keeping focus and highlighting it is important part of it.
| - Implement optimistic UI updates where safe (show expected result immediately, rollback if fails) | ||
| - Provide immediate feedback for user actions, even if processing takes time | ||
| - Use progressive image loading with appropriate placeholders | ||
| - Batch API calls to reduce perceived loading time |
There was a problem hiding this comment.
I think we use and tend to use the opposite: chained or paralleled requests so users will see the first available update as soon as possible and the rest of info will come later
There was a problem hiding this comment.
How would you rewrite this? @hlomzik
.cursor/rules/ux-standards.mdc
Outdated
| - Use consistent terminology for all UI elements (e.g., "category" not "type") | ||
|
|
||
| ### Tone and Voice | ||
| - **Enterprise version**: Maintain a professional, clear, and efficient tone (e.g., "All tasks labeled successfully") |
There was a problem hiding this comment.
Kind of nit-picky, but "All tasks labeled successfully" is passive, and but then we say it needs to use active voice. We also go on to ask it to "use contractions to foster a conversational tone." But formal for Enterprise? Seems contradictory.
I also don't see why Enterprise needs to be more formal? I think the OSS tone works fine for LSE.
There was a problem hiding this comment.
In a nutshell, Enterprise and Open Source cater to different target audiences. Enterprise users operate in business contexts where credibility and trust are paramount. We need to strategically convey robustness, quality, efficiency, professionalism and reliability in our language, as that helps differentiate and position the enterprise offering appropriately.
Open Source should be friendly, encouraging, open, appealing to individuals or small teams.
One great example of how we tone down the informality is by using Heidi minimally across the Enterprise application.
I'll be making adjustments to ensure that is properly conveyed.
.cursor/rules/ux-standards.mdc
Outdated
| - Provide explanations when features are disabled (see Tooltips section for implementation guidance) | ||
|
|
||
| ### Destructive Actions | ||
| - Use clear, explicit labels (e.g., "Delete Permanently" instead of "Delete") |
There was a problem hiding this comment.
I feel like our button text guidance - "Delete Permanently" and "Save Changes" instead of "Delete" and "Save" kind of goes against our standard of being succinct.
There was a problem hiding this comment.
Buttons should be concise, true, but they also need to be meaningful. Generic button labels can be too abstract in some scenarios, specially in important or destructive ones.
Button labels of important actions should be composed of a verb and the exact action that will occur for complete clarity.
Delete Permanently is in retrospective a bad example in this case, and perhaps "Delete Annotation" would be a better one.
|
|
||
| ### Destructive Actions | ||
| - Use clear, explicit labels (e.g., "Delete Permanently" instead of "Delete") | ||
| - Always require user confirmation (e.g., a modal) for destructive actions to prevent accidental data loss |
There was a problem hiding this comment.
If the modal clarifies that the action cannot be undone, we don't need the button to say "Delete Permanently"
|
|
||
| ### External Links & Documentation Links | ||
| - For all external links or links to documentation, use `target="_blank"` to open in a new tab | ||
| - Always include `rel="noopener noreferrer"` for security and performance best practices when opening links in a new tab (e.g., `<a href="https://docs.example.com" target="_blank" rel="noopener noreferrer">View Documentation</a>`) |
There was a problem hiding this comment.
Should we add a rule about how doc links in Enterprise should go to a different target than doc links in LSO?
Co-authored-by: Andrew <hlomzik@gmail.com>
Co-authored-by: C L W <caitlin@humansignal.com>
Co-authored-by: Andrew <hlomzik@gmail.com>
Co-authored-by: Andrew <hlomzik@gmail.com>
Co-authored-by: C L W <caitlin@humansignal.com>
…ased on feedback. Fixes incorrect examples in passive voice. Fixes poor example under Destructive Actions. Adds reference to getDocsUrl utility.
…s://github.com/heartexlabs/label-studio into fb-fit-469/introduce-cursor-rules-ux-standards
This PR introduces Cursor Rules for UX Standards.