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 multiple valid UX directions remain and the choice materially affects user workflow or safety, ask the user. Make minor reversible choices independently.

Prioritize UI/UX decisions in this order:

Visual polish must never reduce usability.

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