diff --git a/shared/rules/ui-ux/index.md b/shared/rules/ui-ux/index.md index 7b154da..ee990fb 100644 --- a/shared/rules/ui-ux/index.md +++ b/shared/rules/ui-ux/index.md @@ -1,64 +1,13 @@ -# UI & UX Guidelines +# UI and UX Rules -* 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. +For interface design or interaction changes, load the principles and only the focused topic rules relevant to the user flow. -## 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 multiple valid UX directions remain and the choice materially affects user workflow or safety, ask the user. Make minor reversible choices independently. - -## 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 | +| Topic | Codex rule | Claude skill | +| --- | --- | --- | +| General design principles and trade-offs | `references/principles-and-priorities.md` | `rules-ui-ux-principles-and-priorities` | +| Navigation and actions | `references/navigation-and-actions.md` | `rules-ui-ux-navigation-and-actions` | +| Forms and validation | `references/forms.md` | `rules-ui-ux-forms` | +| Content and feedback | `references/content-and-feedback.md` | `rules-ui-ux-content-and-feedback` | +| Visual design and accessibility | `references/visual-and-accessibility.md` | `rules-ui-ux-visual-and-accessibility` | +| Tables, search, and dialogs | `references/tables-search-dialogs.md` | `rules-ui-ux-tables-search-dialogs` | +| Destructive actions and error prevention | `references/destructive-and-error-prevention.md` | `rules-ui-ux-destructive-and-error-prevention` | diff --git a/shared/rules/ui-ux/references/principles-and-priorities.md b/shared/rules/ui-ux/references/principles-and-priorities.md new file mode 100644 index 0000000..e1d197a --- /dev/null +++ b/shared/rules/ui-ux/references/principles-and-priorities.md @@ -0,0 +1,12 @@ +# UI and UX Principles + +Apply these principles across interface work. Use the other UI/UX rules only for the affected screen or interaction. + +* Design for clarity and low cognitive load. Give each screen a clear purpose and make important actions easy to discover. +* Prefer familiar, predictable patterns. Keep layouts calm, group related content, and use hierarchy, spacing, typography, and color consistently. +* Minimize steps for common tasks. Remove decorative elements, choices, and interactions that do not help users complete a task. +* Make primary actions distinct from secondary actions. Keep related information and actions close, and keep important information visible without unnecessary scrolling. +* Every interaction adds cognitive cost. Prefer fewer clear choices and predictable behavior over clever or surprising automation. +* Prioritize correctness, clarity, safety, accessibility, user control, task efficiency, consistency, and responsiveness before visual polish. +* Do not let visual polish reduce readability, accessibility, or task completion. +* If multiple UX directions remain and the choice materially changes a user's workflow or safety, ask for the decision. Make minor reversible choices independently.