菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Canonical design token registry — colors, typography, spacing, sizing, border radius, shadows, z-index, breakpoints, motion, and focus tokens. Used by ui-best-practices rules and all agents that implement or review UI components. Includes CSS variable template for quick project setup.
Accessibility auditing and remediation skill for Vue 3 + Reka UI. Use when reviewing components, verifying WCAG 2.1 AA, fixing ARIA issues, or validating keyboard navigation in Reka UI components.
Audit of existing Vue components in the project. Use when reviewing Vue design system consistency, identifying duplicate patterns, evaluating legacy components (Options API), or before implementing something new.
Documentation, standardization, and governance of the Vue + shadcn-vue design system. Use when creating component documentation, auditing consistency, defining naming conventions, or generating usage guides for the team.
Bidirectional Figma skill — read designs and write back to Figma. READ: extract tokens, map Vue/Reka UI components, translate Auto Layout to Tailwind. WRITE: push components, screens, and design tokens from code to Figma. Requires /figma:figma-use skill before every use_figma call.
Skill for direct usage of Reka UI v2 headless primitives (the foundation of shadcn-vue). Use when you need to compose custom components beyond those available in shadcn-vue, understand asChild/as, controlled state, portals, or migrate from Radix Vue.
| 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. |
You will receive a series of UI/UX improvement suggestions to apply to the product we are developing.
Your workflow:
Priority levels used in this document:
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 reviewP0Always 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.
P0Never use hardcoded hex values in components. All colors must come from semantic tokens defined in theme.colors:
--background, --card, --popover, --muted--foreground, --muted-foreground--primary, --secondary, --accent--success, --warning, --destructive, --info--border, --input, --ringEvery foreground token has a paired background token. Components use both: bg-primary text-primary-foreground.
P0Green, 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.
P1Use 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.
P1Prefer 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.
P1Border 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.
P1Use 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%.
P1For 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.
P0Default 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.
P0Adjacent 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.
P2Use 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).
P0All spacing values must be multiples of 4px. Use tokens from theme.spacing. Arbitrary values like 13px or 37px break rhythm and create visual inconsistency.
P1Card 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.
P1All 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.
P1In 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.
P0Buttons 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).
P2Match 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.
P2Narrow 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).
P0Every 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.
P0In 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".
P1The 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.
P1The 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.
P2Implement 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.
P1P1If 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.
P1When 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.
P0The 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.
P2In top menus: primary items left, secondary items right. In sidebars: primary items top, secondary items bottom. Spatial position is an implicit priority signal.
P2If 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.
P2Items follow either process order (Register → Configure → Execute → Analyze) or frequency order (most used first). Pick one logic and apply consistently.
P1See theme.breakpoints for responsive trigger points.
P0When 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.
P2If 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.
P2If 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.
P1Show 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.
P2More than 6 horizontal tabs causes overflow and readability issues. Switch to vertical tabs or a side submenu.
P1Actions 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.
P1Tables 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.
P1Tables 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).
P1Include 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).
P1When 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.
P1When 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.
P1The "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.
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.
P2If 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.
P2Save 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.
P0Never 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.
P0Always show a confirmation dialog before deletion. State the consequences clearly: "This will permanently remove the project and 12 associated tasks."
P0For high-impact deletions (account, workspace, irrecoverable data), require the user to type the object name or a confirmation phrase. Protects against accidental clicks.
P2Easy-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).
P1Whenever possible, support undo via:
P2The 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.
P0When the user is redirected to login, preserve the original URL via ?redirect=/path. After authentication, redirect there — never to a generic dashboard.
P2While the user fills the signup form, use the remaining space for screenshots, testimonials, and key benefits. Reaffirms the decision and reduces abandonment.
P1Step 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.
P1Apply automatic formatting masks to fields with predictable formats: phone, CPF, CNPJ, ZIP code, credit card. Reduces errors, speeds up input, conveys professionalism.
P1Offer at minimum Google login for B2B SaaS. Add GitHub, Microsoft, or Apple depending on the niche. Always maintain email/password fallback.
P2Replace the "confirm password" field with a show/hide toggle button. Less friction, more effective, works well with password managers.
P1Guide 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.
P2Deduce and auto-fill information whenever possible. The user reviews and confirms instead of writing from scratch. Passive confirmation is easier than active input.
P2New 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.
P3When 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.
P3Identify behaviors correlated with lower churn. Reward those behaviors with points, badges, and levels. Gamification is a retention strategy, not a decoration.
P3Record brief, focused videos showing exactly how each key feature works. Place them near the feature in the UI — not buried in a help center.
P3Automate onboarding messages (email or in-app): Day 1 welcome, Day 3 first integration, Day 7 advanced tip, Day 14 hidden features. Education reduces churn.
P3Videos 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.
P1Long 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.
P1Label each step with its purpose: "Personal Data", "Address", "Payment". Avoid generic labels like "Step 2" or "50% complete".
P2Match 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.
P1When 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.
P2P2When the flow builds something visual (a site, a card, a document), show a live preview as the user progresses. Concrete progress motivates completion.
P0In irreversible flows (payment, contract, permanent registration), add a final review step. Show all data in summary format with "Edit" links next to each section.
P2After critical actions (payment, contract, booking), send a summary via email, WhatsApp, or SMS. Reinforces trust and serves as a receipt.
P1Interview 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.
P1Most important content at top-left. Follow this order: KPIs first → simple charts → complex charts → tables/lists.
P1Humans 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%).
P1P1If 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.
P2To 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.
P2When 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.
P1An 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.
P1Charts 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.
P2Offer shortcut filters: "This week", "Last week", "This month", "Last 30 days", plus a custom date range picker.
P3If measurable: show "time saved", "cost reduced", "revenue added" — the concrete impact of your product. When users see tangible ROI, canceling becomes much harder.
P0Validate on blur or on input — not only on form submit. Users should correct errors immediately, not discover them all at once at the end.
P1For 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.
P0Never 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").
P1On 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".
P2If 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.
P0Always compress images before serving. Prefer .webp — significantly lighter than PNG/JPG at equivalent quality. Heavy images are the #1 perceived performance killer.
P0Lists with 20+ items must be paginated or virtualized. Beyond performance concerns, unpaginated lists harm navigation and scanning. Keep the interface fast and controllable.
P1Use 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.
P1For batch operations (100+ items), show: progress bar, counter ("142 of 300"), percentage, and estimated time remaining. Never show only "Please wait...".
P0Always honor prefers-reduced-motion: reduce. Disable or minimize all animations and transitions for users who request it. See theme.motion for duration tokens.
P2Use duration tokens from theme.motion:
--duration-fast (150ms)--duration-normal (200ms)--duration-slow (300ms)P0All 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.
P0All 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.
P1Use 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).