refactor(rules): split ui-ux.md into index + references

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-09-16 15:34:43 +02:00
1 parent a2b9a9f5c4
commit 01220cebd4
@@ -1,306 +0,0 @@
 # UI & UX Guidelines
 * Design for clarity first.
 * Prefer simple, modern and predictable interfaces.
 * Optimize for fast understanding and low cognitive load.
 * Every screen should have a clear primary purpose.
 * Every important action should be easy to discover.
 * Prefer familiar interaction patterns over novel ones.
 * Do not require users to learn unnecessary custom behavior.
 * Keep layouts visually calm and structured.
 * Use consistent spacing, typography, colors and interaction patterns.
 * Avoid visual noise.
 * Avoid decorative elements that do not improve usability.
 * Avoid unnecessary complexity in navigation and workflows.
 * Minimize the number of steps required to complete common tasks.
 * Keep related information and actions close together.
 * Group content logically.
 * Use clear visual hierarchy.
 * Make primary actions visually distinct from secondary actions.
 * Avoid giving multiple actions equal visual priority when one is clearly more important.
 * Use whitespace intentionally.
 * Prefer readable line lengths and sufficient spacing.
 * Avoid dense walls of content.
 * Avoid oversized empty areas that reduce information efficiency.
 * Keep important information visible without unnecessary scrolling where practical.
 ## Navigation
 * Navigation must be predictable and consistent.
 * Users should always understand where they are.
 * Users should always understand how to go back.
 * Avoid hidden navigation when visible navigation is practical.
 * Keep navigation depth shallow where possible.
 * Use clear and descriptive navigation labels.
 * Do not use ambiguous icons without labels when meaning is not obvious.
 * Preserve navigation state when users return to a previous view where practical.
 * Avoid resetting filters, search state or scroll position unnecessarily.
 * Avoid unexpected redirects.
 * Do not change navigation behavior between similar screens without a clear reason.
 ## Actions
 * Use clear action labels.
 * Prefer verbs that describe the actual outcome.
 * Avoid vague labels such as `OK`, `Submit`, `Proceed` or `Execute` when a more specific label is possible.
 * Make destructive actions clearly distinguishable.
 * Keep dangerous actions away from common actions.
 * Require confirmation for destructive or difficult-to-reverse actions.
 * Do not require unnecessary confirmation for safe, reversible actions.
 * Disable unavailable actions when the reason is obvious.
 * Explain why an action is unavailable when it is not obvious.
 * Avoid actions that appear clickable but are not.
 * Provide immediate visual feedback after user actions.
 * Prevent accidental duplicate submissions.
 * Make loading, success and failure states visible.
 ## Forms
 * Keep forms as short as practical.
 * Ask only for information that is actually required.
 * Group related fields together.
 * Use clear field labels.
 * Do not rely on placeholders as the only label.
 * Use appropriate input controls for the expected value.
 * Provide useful defaults where safe and predictable.
 * Preserve user input when validation or network errors occur.
 * Validate fields at useful moments without interrupting normal input.
 * Show validation errors close to the affected field.
 * Explain how to fix invalid input.
 * Avoid technical validation messages.
 * Clearly mark optional fields where useful.
 * Avoid asking the same information multiple times.
 * Use autocomplete and autofill where appropriate.
 * Make keyboard navigation logical.
 * Use sensible tab order.
 * Support Enter and Escape behavior where users expect it.
 ## Content and Language
 * Use plain, concise language.
 * Prefer user terminology over internal technical terminology.
 * Avoid jargon unless the target users are expected to understand it.
 * Use consistent naming for the same concepts.
 * Do not rename concepts between screens.
 * Keep button labels, headings and descriptions concise.
 * Put the most important information first.
 * Avoid unnecessary explanatory text.
 * Add explanation only where users may reasonably be confused.
 * Error messages should explain what happened and what the user can do next.
 * Avoid blaming the user.
 * Avoid exposing stack traces, exception names or internal implementation details.
 ## Feedback and System State
 * Always communicate important system state.
 * Show loading states for operations that are not immediate.
 * Avoid indefinite loading indicators without context.
 * Use progress indicators for longer operations where progress can be measured.
 * Clearly distinguish loading, empty, error and success states.
 * Do not leave blank screens where an empty state is expected.
 * Empty states should explain what the user can do next.
 * Show success feedback when the result is not otherwise obvious.
 * Keep transient notifications concise.
 * Do not hide important errors in temporary notifications.
 * Preserve actionable errors until the user has had a chance to understand them.
 * Do not silently fail.
 * Do not silently discard user input.
 ## Responsiveness
 * The interface should feel responsive at all times.
 * Provide immediate feedback after interaction.
 * Avoid blocking the entire interface when only one section is loading.
 * Prefer localized loading states.
 * Use optimistic UI only when failures can be handled safely.
 * Avoid layout jumps during loading.
 * Reserve space for content where practical.
 * Keep animations short and functional.
 * Do not use animations that delay task completion.
 * Respect reduced-motion preferences.
 * Avoid unnecessary transitions and visual effects.
 ## Visual Design
 * Prefer modern, clean and restrained visual design.
 * Use a consistent design system.
 * Keep typography hierarchy clear.
 * Maintain sufficient contrast.
 * Use color intentionally.
 * Do not rely on color alone to communicate state.
 * Keep the number of accent colors limited.
 * Avoid excessive gradients, shadows and decorative effects.
 * Use rounded corners, borders and elevation consistently.
 * Keep icons stylistically consistent.
 * Use familiar icons for familiar actions.
 * Pair unclear icons with text labels.
 * Avoid tiny click targets.
 * Keep interactive targets large enough for comfortable use.
 * Maintain consistent alignment.
 * Avoid arbitrary spacing values.
 * Prefer reusable spacing and sizing tokens.
 ## Accessibility
 * Accessibility is part of the default design, not an optional enhancement.
 * Use semantic controls and elements.
 * Ensure full keyboard usability.
 * Maintain visible focus indicators.
 * Use sufficient color contrast.
 * Do not rely solely on hover interactions.
 * Do not rely solely on color to indicate status.
 * Provide accessible names for controls.
 * Keep focus order logical.
 * Move focus intentionally after dialogs, navigation or major state changes.
 * Support screen readers where applicable.
 * Use ARIA only when native semantics are insufficient.
 * Respect reduced-motion and system accessibility preferences.
 * Avoid flashing or distracting content.
 ## Responsive Design
 * Design for the available viewport instead of fixed screen sizes.
 * Prioritize important content on smaller screens.
 * Avoid horizontal scrolling unless the content genuinely requires it.
 * Keep controls usable on touch devices.
 * Do not simply shrink desktop layouts.
 * Adapt navigation and layout intentionally for smaller screens.
 * Preserve core functionality across supported screen sizes.
 * Avoid hiding important actions solely because space is limited.
 * Test common breakpoints and extreme content lengths.
 ## Tables and Data-Dense Views
 * Use tables only for genuinely tabular data.
 * Keep column names concise.
 * Align numeric data consistently.
 * Make sorting and filtering discoverable.
 * Preserve filter and sort state where useful.
 * Do not overload tables with too many actions.
 * Prefer a clear primary row action and secondary contextual actions.
 * Keep important columns visible.
 * Allow horizontal scrolling only when necessary.
 * Use pagination, virtualization or incremental loading for large data sets.
 * Provide clear empty states.
 * Avoid showing unnecessary columns by default.
 * Use sensible formatting for dates, numbers and units.
 ## Search and Filtering
 * Search should behave predictably.
 * Make active filters visible.
 * Make filters easy to remove.
 * Provide a clear way to reset filters.
 * Preserve search and filter state when navigating back where practical.
 * Avoid requiring users to configure many filters before seeing results.
 * Use sensible defaults.
 * Clearly distinguish no results from loading or errors.
 * Suggest recovery options when no results are found.
 ## Dialogs and Modals
 * Use dialogs only when interruption is justified.
 * Avoid stacking dialogs.
 * Keep dialogs focused on one decision or task.
 * Use clear titles.
 * Keep primary and secondary actions obvious.
 * Make cancellation easy.
 * Support Escape where appropriate.
 * Do not use dialogs for information that belongs inline.
 * Avoid large workflows inside modal dialogs.
 * Do not close dialogs unexpectedly while users are entering data.
 ## Destructive Actions
 * Clearly label destructive actions.
 * Use confirmations for irreversible or high-impact operations.
 * Explain the consequence before confirmation.
 * Prefer reversible actions when possible.
 * Offer undo where practical.
 * Do not use generic confirmation text for destructive operations.
 * Make the safe action visually distinct.
 * Do not preselect destructive choices.
 ## Error Prevention
 * Prevent invalid actions before they occur where practical.
 * Use constraints and suitable controls instead of relying only on validation errors.
 * Provide sensible defaults.
 * Confirm only high-impact decisions.
 * Warn users before losing unsaved changes.
 * Do not clear entered data unexpectedly.
 * Avoid ambiguous state transitions.
 * Make dependencies between fields or actions visible.
 ## Consistency
 * Similar problems should have similar UI solutions.
 * Similar actions should use the same wording and placement.
 * Do not introduce custom patterns when an existing pattern already solves the problem.
 * Reuse components and design tokens.
 * Keep interaction behavior consistent across the application.
 * Preserve platform conventions unless there is a strong reason not to.
 ## User Control
 * Keep users in control of important actions.
 * Do not perform surprising destructive actions automatically.
 * Do not change user data without a clear action or established behavior.
 * Make automatic behavior visible when it materially affects the user.
 * Allow users to cancel long-running operations where practical.
 * Allow recovery from mistakes where possible.
 * Avoid dark patterns.
 * Never manipulate users into actions they did not intend.
 ## Progressive Disclosure
 * Show the most important options first.
 * Hide advanced complexity until it is needed.
 * Do not overwhelm users with every possible setting at once.
 * Keep advanced options discoverable.
 * Avoid forcing expert workflows on normal users.
 * Avoid hiding frequently used functionality behind excessive menus.
 ## Performance Perception
 * Optimize perceived performance as well as actual performance.
 * Show useful content as early as possible.
 * Avoid blocking initial rendering on non-critical data.
 * Use skeletons only when they improve comprehension.
 * Avoid fake progress.
 * Do not use loading animations to mask avoidable slowness.
 * Keep interactions responsive even while background work continues.
 ## Defaults
 * Choose safe and sensible defaults.
 * Defaults should match the most common expected user intent.
 * Avoid defaults with destructive consequences.
 * Preserve user preferences when appropriate.
 * Do not force repeated configuration for common workflows.
 ## Design Decision Rule
 * Every UI element should have a clear purpose.
 * Every additional interaction adds cognitive cost.
 * Prefer removing complexity over explaining unnecessary complexity.
 * Prefer familiar patterns over clever ones.
 * Prefer fewer clear choices over many ambiguous choices.
 * Prefer predictable behavior over surprising automation.
 * If a design decision introduces ambiguity, unnecessary complexity, or multiple equally valid UX directions, ask the user instead of deciding autonomously.
 ## Priority Order
 Prioritize UI/UX decisions in this order:
 * Correctness
 * Clarity
 * Safety
 * Accessibility
 * User control
 * Task efficiency
 * Consistency
 * Responsiveness
 * Visual polish
 Visual polish must never reduce usability.
@@ -0,0 +1,64 @@
 # UI & UX Guidelines
 * Design for clarity first.
 * Prefer simple, modern and predictable interfaces.
 * Optimize for fast understanding and low cognitive load.
 * Every screen should have a clear primary purpose.
 * Every important action should be easy to discover.
 * Prefer familiar interaction patterns over novel ones.
 * Do not require users to learn unnecessary custom behavior.
 * Keep layouts visually calm and structured.
 * Use consistent spacing, typography, colors and interaction patterns.
 * Avoid visual noise.
 * Avoid decorative elements that do not improve usability.
 * Avoid unnecessary complexity in navigation and workflows.
 * Minimize the number of steps required to complete common tasks.
 * Keep related information and actions close together.
 * Group content logically.
 * Use clear visual hierarchy.
 * Make primary actions visually distinct from secondary actions.
 * Avoid giving multiple actions equal visual priority when one is clearly more important.
 * Use whitespace intentionally.
 * Prefer readable line lengths and sufficient spacing.
 * Avoid dense walls of content.
 * Avoid oversized empty areas that reduce information efficiency.
 * Keep important information visible without unnecessary scrolling where practical.
 ## Design Decision Rule
 * Every UI element should have a clear purpose.
 * Every additional interaction adds cognitive cost.
 * Prefer removing complexity over explaining unnecessary complexity.
 * Prefer familiar patterns over clever ones.
 * Prefer fewer clear choices over many ambiguous choices.
 * Prefer predictable behavior over surprising automation.
 * If a design decision introduces ambiguity, unnecessary complexity, or multiple equally valid UX directions, ask the user instead of deciding autonomously.
 ## Priority Order
 Prioritize UI/UX decisions in this order:
 * Correctness
 * Clarity
 * Safety
 * Accessibility
 * User control
 * Task efficiency
 * Consistency
 * Responsiveness
 * Visual polish
 Visual polish must never reduce usability.
 ## Detailed guidance
 Read the matching reference file before working in that area:
 | Read this reference for... | ...this kind of work |
 | --- | --- |
 | `references/navigation-and-actions.md` | Navigation structure, action labeling and placement |
 | `references/forms.md` | Form design and validation UX |
 | `references/content-and-feedback.md` | Copy, loading/empty/error states, responsiveness |
 | `references/visual-and-accessibility.md` | Visual design, accessibility, responsive layout |
 | `references/tables-search-dialogs.md` | Data-dense views, search/filtering, dialogs/modals |
 | `references/destructive-and-error-prevention.md` | Destructive actions, error prevention, consistency, user control, progressive disclosure, perceived performance, defaults |
@@ -0,0 +1,44 @@
 ## Content and Language
 * Use plain, concise language.
 * Prefer user terminology over internal technical terminology.
 * Avoid jargon unless the target users are expected to understand it.
 * Use consistent naming for the same concepts.
 * Do not rename concepts between screens.
 * Keep button labels, headings and descriptions concise.
 * Put the most important information first.
 * Avoid unnecessary explanatory text.
 * Add explanation only where users may reasonably be confused.
 * Error messages should explain what happened and what the user can do next.
 * Avoid blaming the user.
 * Avoid exposing stack traces, exception names or internal implementation details.
 ## Feedback and System State
 * Always communicate important system state.
 * Show loading states for operations that are not immediate.
 * Avoid indefinite loading indicators without context.
 * Use progress indicators for longer operations where progress can be measured.
 * Clearly distinguish loading, empty, error and success states.
 * Do not leave blank screens where an empty state is expected.
 * Empty states should explain what the user can do next.
 * Show success feedback when the result is not otherwise obvious.
 * Keep transient notifications concise.
 * Do not hide important errors in temporary notifications.
 * Preserve actionable errors until the user has had a chance to understand them.
 * Do not silently fail.
 * Do not silently discard user input.
 ## Responsiveness
 * The interface should feel responsive at all times.
 * Provide immediate feedback after interaction.
 * Avoid blocking the entire interface when only one section is loading.
 * Prefer localized loading states.
 * Use optimistic UI only when failures can be handled safely.
 * Avoid layout jumps during loading.
 * Reserve space for content where practical.
 * Keep animations short and functional.
 * Do not use animations that delay task completion.
 * Respect reduced-motion preferences.
 * Avoid unnecessary transitions and visual effects.
@@ -0,0 +1,68 @@
 ## Destructive Actions
 * Clearly label destructive actions.
 * Use confirmations for irreversible or high-impact operations.
 * Explain the consequence before confirmation.
 * Prefer reversible actions when possible.
 * Offer undo where practical.
 * Do not use generic confirmation text for destructive operations.
 * Make the safe action visually distinct.
 * Do not preselect destructive choices.
 ## Error Prevention
 * Prevent invalid actions before they occur where practical.
 * Use constraints and suitable controls instead of relying only on validation errors.
 * Provide sensible defaults.
 * Confirm only high-impact decisions.
 * Warn users before losing unsaved changes.
 * Do not clear entered data unexpectedly.
 * Avoid ambiguous state transitions.
 * Make dependencies between fields or actions visible.
 ## Consistency
 * Similar problems should have similar UI solutions.
 * Similar actions should use the same wording and placement.
 * Do not introduce custom patterns when an existing pattern already solves the problem.
 * Reuse components and design tokens.
 * Keep interaction behavior consistent across the application.
 * Preserve platform conventions unless there is a strong reason not to.
 ## User Control
 * Keep users in control of important actions.
 * Do not perform surprising destructive actions automatically.
 * Do not change user data without a clear action or established behavior.
 * Make automatic behavior visible when it materially affects the user.
 * Allow users to cancel long-running operations where practical.
 * Allow recovery from mistakes where possible.
 * Avoid dark patterns.
 * Never manipulate users into actions they did not intend.
 ## Progressive Disclosure
 * Show the most important options first.
 * Hide advanced complexity until it is needed.
 * Do not overwhelm users with every possible setting at once.
 * Keep advanced options discoverable.
 * Avoid forcing expert workflows on normal users.
 * Avoid hiding frequently used functionality behind excessive menus.
 ## Performance Perception
 * Optimize perceived performance as well as actual performance.
 * Show useful content as early as possible.
 * Avoid blocking initial rendering on non-critical data.
 * Use skeletons only when they improve comprehension.
 * Avoid fake progress.
 * Do not use loading animations to mask avoidable slowness.
 * Keep interactions responsive even while background work continues.
 ## Defaults
 * Choose safe and sensible defaults.
 * Defaults should match the most common expected user intent.
 * Avoid defaults with destructive consequences.
 * Preserve user preferences when appropriate.
 * Do not force repeated configuration for common workflows.
@@ -0,0 +1,20 @@
 ## Forms
 * Keep forms as short as practical.
 * Ask only for information that is actually required.
 * Group related fields together.
 * Use clear field labels.
 * Do not rely on placeholders as the only label.
 * Use appropriate input controls for the expected value.
 * Provide useful defaults where safe and predictable.
 * Preserve user input when validation or network errors occur.
 * Validate fields at useful moments without interrupting normal input.
 * Show validation errors close to the affected field.
 * Explain how to fix invalid input.
 * Avoid technical validation messages.
 * Clearly mark optional fields where useful.
 * Avoid asking the same information multiple times.
 * Use autocomplete and autofill where appropriate.
 * Make keyboard navigation logical.
 * Use sensible tab order.
 * Support Enter and Escape behavior where users expect it.
@@ -0,0 +1,29 @@
 ## Navigation
 * Navigation must be predictable and consistent.
 * Users should always understand where they are.
 * Users should always understand how to go back.
 * Avoid hidden navigation when visible navigation is practical.
 * Keep navigation depth shallow where possible.
 * Use clear and descriptive navigation labels.
 * Do not use ambiguous icons without labels when meaning is not obvious.
 * Preserve navigation state when users return to a previous view where practical.
 * Avoid resetting filters, search state or scroll position unnecessarily.
 * Avoid unexpected redirects.
 * Do not change navigation behavior between similar screens without a clear reason.
 ## Actions
 * Use clear action labels.
 * Prefer verbs that describe the actual outcome.
 * Avoid vague labels such as `OK`, `Submit`, `Proceed` or `Execute` when a more specific label is possible.
 * Make destructive actions clearly distinguishable.
 * Keep dangerous actions away from common actions.
 * Require confirmation for destructive or difficult-to-reverse actions.
 * Do not require unnecessary confirmation for safe, reversible actions.
 * Disable unavailable actions when the reason is obvious.
 * Explain why an action is unavailable when it is not obvious.
 * Avoid actions that appear clickable but are not.
 * Provide immediate visual feedback after user actions.
 * Prevent accidental duplicate submissions.
 * Make loading, success and failure states visible.
@@ -0,0 +1,40 @@
 ## Tables and Data-Dense Views
 * Use tables only for genuinely tabular data.
 * Keep column names concise.
 * Align numeric data consistently.
 * Make sorting and filtering discoverable.
 * Preserve filter and sort state where useful.
 * Do not overload tables with too many actions.
 * Prefer a clear primary row action and secondary contextual actions.
 * Keep important columns visible.
 * Allow horizontal scrolling only when necessary.
 * Use pagination, virtualization or incremental loading for large data sets.
 * Provide clear empty states.
 * Avoid showing unnecessary columns by default.
 * Use sensible formatting for dates, numbers and units.
 ## Search and Filtering
 * Search should behave predictably.
 * Make active filters visible.
 * Make filters easy to remove.
 * Provide a clear way to reset filters.
 * Preserve search and filter state when navigating back where practical.
 * Avoid requiring users to configure many filters before seeing results.
 * Use sensible defaults.
 * Clearly distinguish no results from loading or errors.
 * Suggest recovery options when no results are found.
 ## Dialogs and Modals
 * Use dialogs only when interruption is justified.
 * Avoid stacking dialogs.
 * Keep dialogs focused on one decision or task.
 * Use clear titles.
 * Keep primary and secondary actions obvious.
 * Make cancellation easy.
 * Support Escape where appropriate.
 * Do not use dialogs for information that belongs inline.
 * Avoid large workflows inside modal dialogs.
 * Do not close dialogs unexpectedly while users are entering data.
@@ -0,0 +1,48 @@
 ## Visual Design
 * Prefer modern, clean and restrained visual design.
 * Use a consistent design system.
 * Keep typography hierarchy clear.
 * Maintain sufficient contrast.
 * Use color intentionally.
 * Do not rely on color alone to communicate state.
 * Keep the number of accent colors limited.
 * Avoid excessive gradients, shadows and decorative effects.
 * Use rounded corners, borders and elevation consistently.
 * Keep icons stylistically consistent.
 * Use familiar icons for familiar actions.
 * Pair unclear icons with text labels.
 * Avoid tiny click targets.
 * Keep interactive targets large enough for comfortable use.
 * Maintain consistent alignment.
 * Avoid arbitrary spacing values.
 * Prefer reusable spacing and sizing tokens.
 ## Accessibility
 * Accessibility is part of the default design, not an optional enhancement.
 * Use semantic controls and elements.
 * Ensure full keyboard usability.
 * Maintain visible focus indicators.
 * Use sufficient color contrast.
 * Do not rely solely on hover interactions.
 * Do not rely solely on color to indicate status.
 * Provide accessible names for controls.
 * Keep focus order logical.
 * Move focus intentionally after dialogs, navigation or major state changes.
 * Support screen readers where applicable.
 * Use ARIA only when native semantics are insufficient.
 * Respect reduced-motion and system accessibility preferences.
 * Avoid flashing or distracting content.
 ## Responsive Design
 * Design for the available viewport instead of fixed screen sizes.
 * Prioritize important content on smaller screens.
 * Avoid horizontal scrolling unless the content genuinely requires it.
 * Keep controls usable on touch devices.
 * Do not simply shrink desktop layouts.
 * Adapt navigation and layout intentionally for smaller screens.
 * Preserve core functionality across supported screen sizes.
 * Avoid hiding important actions solely because space is limited.
 * Test common breakpoints and extreme content lengths.