ui-best-practices

name	ui-best-practices
description	Canonical UI/UX best practices ruleset with 14 sections and 70+ rules prioritized P0–P3. Use when implementing, reviewing, or auditing UI components. P0 rules are mandatory — violations are bugs. All rules reference tokens from ui-theme-reference.

Critical Instructions

You will receive a series of UI/UX improvement suggestions to apply to the product we are developing.

Your workflow:

1. Read all rules below and evaluate which ones apply to our current context
2. Confirm with me before applying changes that affect backend, performance, security, or shared infrastructure
3. Proceed one by one — do not batch-apply without alignment
4. Break work into stages if needed, but cover all rules across stages

Priority levels used in this document:

• P0 — Mandatory: violations are bugs. Always apply.
• P1 — Strong default: apply unless there is an explicit, documented reason not to.
• P2 — Recommended: apply when context allows; skip with justification.
• P3 — Contextual: evaluate case by case; most relevant for specific product types.

Theme reference: all token values (colors, sizes, spacing, shadows) are defined in the ui-theme-reference skill. Rules below reference tokens as theme.<section>.<token> — never hardcode raw values in components.

Related plugin commands:

• /pwdev-uiux:theme — create or update the theme token system
• /pwdev-uiux:scan — audit existing UI against these rules
• /pwdev-uiux:review — run accessibility + UX review

---

1. Visual Foundation

1.1 Light and Dark Mode P0

Always support both light and dark mode. Default to the user's OS preference via prefers-color-scheme. Users who have their device in dark mode must enter with the correct experience without manual configuration.

Both modes must be defined in the theme — see theme.colors.surfaces for the full token set.

1.2 Semantic Color Tokens P0

Never use hardcoded hex values in components. All colors must come from semantic tokens defined in theme.colors:

• Surfaces: --background, --card, --popover, --muted
• Text: --foreground, --muted-foreground
• Interactive: --primary, --secondary, --accent
• Feedback: --success, --warning, --destructive, --info
• Structure: --border, --input, --ring

Every foreground token has a paired background token. Components use both: bg-primary text-primary-foreground.

1.3 Reserved Semantic Colors P0

Green, orange, and red carry universal meaning across all interfaces:

Color	Meaning	Token
Green	Positive / success / complete	--success
Orange	Caution / attention needed	--warning
Red	Error / danger / destructive	--destructive

Never repurpose these for decoration, categories, or branding. For data visualization, use the dedicated theme.colors.chart-palette.

1.4 Vector Icons Only P1

Use SVG icons from a consistent library (Lucide, Heroicons, Phosphor) instead of emojis. Emojis render differently across OS and break visual consistency. Choose one icon library and use it throughout the entire product.

1.5 Flat Visual Style P1

Prefer solid colors and flat surfaces with minimal, soft shadows. Avoid gradients on buttons, backgrounds, text, or dividers — they age quickly and create visual noise. Use theme.shadows tokens for elevation instead.

Exception: subtle gradients on hero/marketing sections are acceptable if the design system explicitly allows it.

1.6 Consistent Border Radius P1

Border radius communicates brand personality. Define theme.radius.--radius once and derive all variants from it:

Brand Style	Base radius
Modern / trendy	12–16px
Neutral / corporate	8px (safe default)
Enterprise / dense	4px
Sharp / editorial	0–2px

All elements (buttons, inputs, cards, modals) must use the same radius scale. See theme.border-radius.

1.7 Shadow System P1

Use shadows only from theme.shadows — black with opacity between 5% and 12% for light mode:

Level	Usage
--shadow-xs	Inputs, badges (subtle lift)
--shadow-sm	Cards at rest
--shadow-md	Elevated cards, dropdowns
--shadow-lg	Modals, popovers
--shadow-xl	Command palette, overlays

Never use colored shadows or opacity above 12%.

---

2. Typography

2.1 Sans-Serif Font Stack P1

For SaaS interfaces, use a clean sans-serif font. Default: Inter (free, universal, excellent readability). Alternatives: Roboto, Manrope, Segoe UI, Helvetica Neue.

Define in theme.typography.--font-sans. Use theme.typography.--font-mono for code blocks.

2.2 Minimum Font Size: 12px P0

Default body text: 14px (theme.typography.--text-sm). Never use fonts smaller than 12px (theme.typography.--text-xs). The 12px minimum is an accessibility requirement, allowed only for footnotes, captions, and very secondary labels.

2.3 Progressive Type Scale P0

Adjacent text elements must not skip more than 2 steps in the type scale. Jumping from 30px directly to 14px creates jarring contrast.

Use the scale defined in theme.typography.type-scale: 36 → 30 → 24 → 20 → 18 → 16 → 14 → 12. Each transition should feel gradual.

2.4 Consistent Font Weights P2

Use no more than 3–4 font weights across the interface. Stick to the scale in theme.typography.font-weights: normal (400), medium (500), semibold (600), bold (700).

---

3. Layout & Spacing

3.1 4px Spacing Grid P0

All spacing values must be multiples of 4px. Use tokens from theme.spacing. Arbitrary values like 13px or 37px break rhythm and create visual inconsistency.

3.2 Proportional Card Padding P1

Card padding should range from 16px to 24px (see theme.spacing.card-padding-rule). More important cards get larger padding. Never exceed 32px — excessive padding makes cards feel empty.

3.3 Homogeneous Alignment P1

All elements on a page must follow the same alignment logic. If titles and inputs are left-aligned, buttons are left-aligned. If everything is centered, buttons are centered. Never mix alignments without clear visual intent.

3.4 Button Sizing P1

In wide forms (700–1000px), buttons should have content-adjusted width, not width: 100%. Maximum button width: theme.sizing.--max-w-button (400px). In narrow mobile forms, full-width buttons are acceptable.

3.5 Input and Button Height Parity P0

Buttons and inputs must share the same height: theme.sizing.--height-input (40px). This ensures visual harmony when placed side by side in forms. Use --height-button-sm (32px) only in compact contexts (tables, toolbars).

3.6 Textarea Proportional Height P2

Match textarea height to expected content length. A tagline field: ~2 rows. A description field: ~4–5 rows. A feedback field: ~6–8 rows. Always enable auto-resize. See theme.sizing.textarea-height.

3.7 Form Width Influences Perception P2

Narrow forms feel quick and simple — use during onboarding. Wide forms feel like more effort — useful for discouraging cancellation flows. Max form width: theme.sizing.--max-w-form (560px).

---

4. Button Hierarchy

4.1 Action Weight Mapping P0

Every button must visually reflect its action weight:

Level	Style	Examples
Primary	bg-primary text-primary-foreground	Save, Confirm, Submit
Secondary	border-border outline, no fill	Cancel, Dismiss
Tertiary	Text only, no border	Go back, Skip, Learn more
Destructive	Same hierarchy levels, using --destructive	Delete, Remove, Revoke

Never give two buttons on the same view the same visual weight unless they are truly equal options.

4.2 Unambiguous Button Labels P0

In confirmation dialogs, button text must describe the specific action — not generic "Confirm" / "Cancel". If the destructive action is "Cancel subscription", the buttons should read "Go back" and "Yes, cancel subscription".

---

5. Navigation

5.1 Home as Control Center P1

The home page must be the user's operational hub: shortcuts to frequent actions, key metrics/insights, and product updates. The user should never need to "hunt" for what to do next.

5.2 Menu Shows Only the Operational Routine P1

The main menu contains only actions the user performs every session. Infrequent actions (settings, integrations, billing, support) go in secondary menus — the avatar dropdown or a "More" section.

5.3 Global Search (Cmd+K) P2

Implement a universal search (actions, pages, data) accessible via Cmd+K / Ctrl+K. Power users navigate significantly faster with this pattern. Follows theme.z-index.--z-command for layering.

5.4 Sidebar for 4+ Items, Top Bar for Fewer P1

• 4+ navigation items: sidebar (more vertical space, supports grouping, always visible)
• Up to 4 items: top bar (cleaner, full content width)

5.5 Separate Routine vs. Occasional P1

If the menu has many items, split by frequency: daily-use items at the top, always visible. Occasional items (settings, integrations) grouped at the bottom or in a submenu.

5.6 Group Items into Sections and Submenus P1

When the menu has many items, divide them into logical sections with clear titles or collapsible submenus. Instead of processing 12 loose items, the user sees 3 organized groups. Use visual separators or section labels to reduce cognitive load.

5.7 Active Item Indicator P0

The currently active menu item must be visually distinct: highlight color, differentiated background, colored sidebar accent, or a combination. The user must always know where they are.

5.8 Position Communicates Hierarchy P2

In top menus: primary items left, secondary items right. In sidebars: primary items top, secondary items bottom. Spatial position is an implicit priority signal.

5.9 Main CTA in the Menu P2

If there is a high-frequency action (e.g., "New project", "Create task"), add a CTA button directly in the navigation. Eliminates extra clicks to reach the most important action.

5.10 Menu Order: Process or Frequency P2

Items follow either process order (Register → Configure → Execute → Analyze) or frequency order (most used first). Pick one logic and apply consistently.

5.11 Mobile Navigation P1

• Up to 4–5 functions: bottom bar (thumb-reachable)
• Complex menus: hamburger in top bar, aligned right
• Maximum 4 visible items on mobile — group the rest under "More"

See theme.breakpoints for responsive trigger points.

---

6. Tabs

6.1 Always Define a Default Tab P0

When a page has tabs, one must always be pre-selected. Never show an empty tab state on load. The default tab is the most relevant or the first in the flow.

6.2 Few Tabs with Short Content = Sections P2

If you have only 2–3 tabs with short content each, consider removing tabs and showing everything as scrollable sections on one page. Reduces clicks, gives a complete overview.

6.3 Constant Tab Switching = Merge P2

If users constantly switch between tabs to compare data, that content belongs on the same page. "Back and forth" tab navigation signals the need for consolidation.

6.4 Pending Badges on Tabs P1

Show badges, numbers, or dot indicators on tabs that have pending items or status changes. The user should see that a tab needs attention without opening it.

6.5 6+ Tabs = Vertical Tabs or Submenu P2

More than 6 horizontal tabs causes overflow and readability issues. Switch to vertical tabs or a side submenu.

6.6 Object Actions vs. Tab Actions P1

Actions affecting the whole object (save, delete, archive) belong in the page header — outside tabs. Actions specific to one tab (add member, new comment) stay inside that tab. Mixing the two confuses users.

---

7. Data Interactions

7.1 Listings Show the Minimum P1

Tables and card lists should show just enough to identify the object and decide whether to open it. Save details for the internal view. Over-displaying data clutters the interface and slows scanning.

7.2 Table Default, Cards for Visual Content P1

Tables are denser, more scannable, and more efficient — use as default. Use cards when visual identification matters (products with photos, templates with previews, posts with thumbnails).

7.3 Quick Actions in Listings P1

Include 2–3 frequent actions directly in the listing (duplicate, delete, publish). Prevents opening each item just to perform a simple action. For more actions, use a kebab menu (three dots).

7.4 Many Actions = Overflow Menu P1

When an object has many available actions, showing all of them clutters the interface. Surface the 2–3 most frequent actions inline and group the rest in a kebab menu (three dots). The interface stays clean without losing functionality.

7.5 Complex Objects Need Tabs or Sections P1

When an object has many data fields and relationships, do not dump everything on a single scrollable page. Use tabs or well-defined sections to organize information by context — e.g., "General", "History", "Settings". This reduces cognitive load and improves navigation.

7.6 Place the Create Button Where Most Visible P1

The "create new" button can live in the page header, sidebar, or between cards. What matters most is that it is visible and accessible in the context where the user needs it. Never bury the primary creation action.

7.7 Click Behavior Proportional to Data P1

Data volume	Open with
3–5 fields	Modal / popup
Intermediate	Drawer (side panel)
Complex / many relations	Dedicated page

A full page for 3 fields is wasteful; a popup for 20 fields is suffocating.

7.8 Creation: Popup First, Page Later P2

If an object has many fields but few are required, start with a popup asking only the essentials (name, type). After creation, redirect to the full detail page. Reduces initial friction.

7.9 Auto-Save When Safe P2

Save automatically when edits are local and have no side effects. Show subtle feedback: "Saved" / "Saving...". When edits trigger emails, affect integrations, or impact other users, require an explicit "Save changes" button.

7.10 Empty State = Guidance P0

Never show a blank table. Empty states must include: an illustration or visual, a clear explanation of what belongs here, and a prominent CTA ("Create your first project"). Optionally: a short video or link to docs.

---

8. Deletion & Destructive Actions

8.1 Confirm Before Deleting P0

Always show a confirmation dialog before deletion. State the consequences clearly: "This will permanently remove the project and 12 associated tasks."

8.2 Critical Deletion Requires Extra Friction P0

For high-impact deletions (account, workspace, irrecoverable data), require the user to type the object name or a confirmation phrase. Protects against accidental clicks.

8.3 Simple Objects Can Skip Confirmation P2

Easy-to-recreate, non-critical items (drafts, tags, saved filters) can be deleted directly — but always offer an undo option (toast with "Undo" button for 5–10 seconds).

8.4 Allow Undoing Deletions P1

Whenever possible, support undo via:

• A toast notification with "Undo" button (5–10 seconds), or
• A trash/archive where deleted items remain recoverable for a defined period (e.g., 30 days)

---

9. Access & Onboarding

9.1 Login Screen Shows Updates P2

The login screen is visited by every returning user. Use a sidebar column to show product news, feature launches, and improvements. Transforms a "dead" moment into a communication channel.

9.2 Redirect to Intended Destination P0

When the user is redirected to login, preserve the original URL via ?redirect=/path. After authentication, redirect there — never to a generic dashboard.

9.3 Signup Screen Sells the Product P2

While the user fills the signup form, use the remaining space for screenshots, testimonials, and key benefits. Reaffirms the decision and reduces abandonment.

9.4 Multi-Step Signup P1

Step 1: email + password only (minimum to not lose the lead). Subsequent steps: name, company, phone. If the user abandons at step 2, you still have their email to follow up.

9.5 Input Masks P1

Apply automatic formatting masks to fields with predictable formats: phone, CPF, CNPJ, ZIP code, credit card. Reduces errors, speeds up input, conveys professionalism.

9.6 Social Login P1

Offer at minimum Google login for B2B SaaS. Add GitHub, Microsoft, or Apple depending on the niche. Always maintain email/password fallback.

9.7 No Password Confirmation Field P2

Replace the "confirm password" field with a show/hide toggle button. Less friction, more effective, works well with password managers.

9.8 Onboarding Wizard P1

Guide new users through essential setup in a step-by-step wizard with a progress bar. The goal: reach the Aha Moment — when the user first perceives real value — as quickly as possible.

9.9 Pre-Populate Fields P2

Deduce and auto-fill information whenever possible. The user reviews and confirms instead of writing from scratch. Passive confirmation is easier than active input.

9.10 Demo Data on First Launch P2

New users who see an empty interface don't know where to start. Seed realistic demo data (projects, tasks, reports marked "demo") so the tool feels alive from the first second.

9.11 Suggest Upgrade on Cheapest Plan P3

When the user picks the cheapest plan, show a subtle popup with 2–3 benefits of the next tier and the price difference. Not aggressive — informational. Many users upgrade at this point.

9.12 Gamification for Retention P3

Identify behaviors correlated with lower churn. Reward those behaviors with points, badges, and levels. Gamification is a retention strategy, not a decoration.

9.13 Short Demo Videos (30s–2min) P3

Record brief, focused videos showing exactly how each key feature works. Place them near the feature in the UI — not buried in a help center.

9.14 Educational Message Sequences P3

Automate onboarding messages (email or in-app): Day 1 welcome, Day 3 first integration, Day 7 advanced tip, Day 14 hidden features. Education reduces churn.

9.15 Human Face in Demo Videos P3

Videos featuring a real person create a human connection with the user. Beyond improving content retention, they convey the feeling of personalized support behind the tool. Include a visible webcam overlay in screencasts when possible.

---

10. Forms & Long Flows

10.1 Break Into Short Steps P1

Long forms scare users. Break into focused steps with clear objectives. Progress bars and step labels reduce anxiety. Each step should be completable in under 60 seconds.

10.2 Name Steps by Objective P1

Label each step with its purpose: "Personal Data", "Address", "Payment". Avoid generic labels like "Step 2" or "50% complete".

10.3 Field Height Sets Expectation P2

Match input field height to the expected content length. A name field should be slim; a feedback or description field should be taller to encourage longer responses. Tall fields signal "write more here", short fields signal "keep it brief". Always enable auto-resize for textareas.

10.4 Tooltips on Complex Fields P1

When a field requires reasoning or is easily misunderstood, add a ? tooltip next to the label. Prevents abandonment without cluttering the UI with visible help text.

10.5 Show or Hide Progress Strategically P2

• Transparency priority: show progress (Step X of Y) with labeled stages
• Conversion priority: consider hiding progress to prevent "there's still a lot left" abandonment

10.6 Real-Time Preview P2

When the flow builds something visual (a site, a card, a document), show a live preview as the user progresses. Concrete progress motivates completion.

10.7 Review Step in Critical Flows P0

In irreversible flows (payment, contract, permanent registration), add a final review step. Show all data in summary format with "Edit" links next to each section.

10.8 Confirmation via External Channel P2

After critical actions (payment, contract, booking), send a summary via email, WhatsApp, or SMS. Reinforces trust and serves as a receipt.

---

11. Reports & Dashboards

11.1 Dashboards from Real User Needs P1

Interview users to understand which metrics matter. The dashboard is a living artifact — collect feedback continuously and iterate. Never define dashboard content based solely on team assumptions.

11.2 Presentation Hierarchy P1

Most important content at top-left. Follow this order: KPIs first → simple charts → complex charts → tables/lists.

11.3 Avoid Pie Charts P1

Humans struggle to compare angles and areas. Bar charts provide clearer, more precise readings of the same data in virtually all cases. Use pie charts only when showing a single dominant proportion (e.g., 92% vs 8%).

11.4 Chart Type by Data Nature P1

• Continuous data (revenue over time, traffic trends): line chart
• Discrete data (sales by plan, tickets by category): bar chart
• Long X-axis labels: horizontal bar chart

11.5 The 3-Second Rule P1

If a chart takes more than 3 seconds to understand, it is too complex. Avoid dual Y-axes, too many overlapping series, or logarithmic scales. Simplify or split into smaller charts.

11.6 Highlight One Series, Gray the Rest P2

To draw attention to a specific data series, use a highlight color for that series and theme.colors.--chart-muted for all others. The eye goes directly to the highlighted data.

11.7 Remove Y-Axis for Few Data Points P2

When a chart has 12 or fewer points, remove the Y-axis and label values directly on each bar or point. Reduces noise and enables immediate reading.

11.8 KPIs with Comparison Reference P1

An isolated number says little. Accompany KPIs with: period-over-period comparison, industry benchmark, or long-term average. Add directional arrows and color from theme.colors.feedback for instant reading.

11.9 Chart Visual Consistency P1

Charts must use the product's font family, minimum 12px labels, and the primary color for emphasis. Charts should look like part of the product — not a foreign element.

11.10 Practical Period Filters P2

Offer shortcut filters: "This week", "Last week", "This month", "Last 30 days", plus a custom date range picker.

11.11 Value-Added Metrics P3

If measurable: show "time saved", "cost reduced", "revenue added" — the concrete impact of your product. When users see tangible ROI, canceling becomes much harder.

---

12. Errors & Validation

12.1 Real-Time Field Validation P0

Validate on blur or on input — not only on form submit. Users should correct errors immediately, not discover them all at once at the end.

12.2 Visible Rules Checklist P1

For fields with rules (min length, special characters), show a checklist with real-time visual feedback (green check per rule met) before the user starts typing.

12.3 Always Report Backend Errors P0

Never leave the UI silent on server errors. Display a clear, visible message in plain language. Suggest a resolution when possible ("try again" or "contact support"). No raw error codes ("Error 500").

12.4 Proactive Support on Critical Errors P1

On critical failures (payment error, data loss, broken integration), proactively open the support chat with a pre-filled message describing the problem. The user just clicks "Send".

12.5 Auto-Correct Obvious Intent P2

If the user's intent is unambiguous, fix it automatically instead of showing an error. Classic examples: prepend https:// to bare domains, format phone numbers with masks, strip extra spaces.

---

13. Performance & Loading

13.1 Compress Images, Use WebP P0

Always compress images before serving. Prefer .webp — significantly lighter than PNG/JPG at equivalent quality. Heavy images are the #1 perceived performance killer.

13.2 Paginate Long Lists P0

Lists with 20+ items must be paginated or virtualized. Beyond performance concerns, unpaginated lists harm navigation and scanning. Keep the interface fast and controllable.

13.3 Skeleton Loading Over Spinners P1

Use skeleton placeholders (gray shapes mimicking the real layout) instead of generic spinners. The brain starts processing the page structure before content arrives, reducing perceived wait time.

13.4 Visual Feedback on Bulk Actions P1

For batch operations (100+ items), show: progress bar, counter ("142 of 300"), percentage, and estimated time remaining. Never show only "Please wait...".

---

14. Motion & Focus

14.1 Respect Reduced Motion P0

Always honor prefers-reduced-motion: reduce. Disable or minimize all animations and transitions for users who request it. See theme.motion for duration tokens.

14.2 Consistent Animation Durations P2

Use duration tokens from theme.motion:

• Hover/toggle: --duration-fast (150ms)
• Dropdown/tooltip: --duration-normal (200ms)
• Drawer/modal: --duration-slow (300ms)

14.3 Visible Focus Indicators P0

All interactive elements must show a visible focus ring when navigated via keyboard. Use theme.focus tokens: --ring-width (2px), --ring-offset (2px), --ring-color.

Never remove :focus-visible outlines without providing a custom alternative.

14.4 Minimum Touch Target P0

All tappable elements must be at least 44x44px on touch devices (WCAG 2.5.8). This applies to buttons, links, checkboxes, and icon actions. The visual size can be smaller if the tap area is padded.

14.5 Z-Index Management P1

Use the managed scale from theme.z-index. Never use arbitrary z-index values (999, 99999). Every layer has a defined token — dropdown (10), sticky (20), drawer (30), modal (40), toast (60), command palette (70).