AUTO-MAS-Project/AUTO-MAS / .agents/skills/mas-frontend-ui
mas-frontend-ui
VerifiedUse when working on AUTO-MAS frontend UI, Ant Design Vue components, page layout, forms, tables, modals, drawers, feedback, empty/loading/error states, drag interactions, dark mode, or visual polish.
MAS Frontend UI
Objective
Keep AUTO-MAS UI changes consistent with an Electron desktop business operations platform: dense enough for repeated work, quiet enough for long sessions, and aligned with Ant Design Vue 4.x.
Authority
This skill is self-contained for AUTO-MAS UI rules. Nearby existing pages are still the authority for module-specific layout, wording, and visual rhythm when they do not conflict with this skill.
UI Intake
Before editing UI:
- Inspect the target page and adjacent pages to learn the module's real layout, spacing, component usage, and wording.
- Confirm the project uses Ant Design Vue and
@ant-design/icons-vue, not Element Plus, Naive UI, Arco, or Ant Design React. - Confirm theme variables come from
src/style.cssandsrc/composables/useTheme.ts. - Prefer existing components, layout classes, theme tokens, and wording before adding new ones.
- Check both light and dark mode for readability when UI colors, borders, backgrounds, or status colors change.
- Keep the UI inside the existing Electron desktop business-product language.
Visual Direction
- Treat pages as desktop operational tools, not marketing pages.
- Prefer clarity, scanability, consistency, and low distraction.
- Do not create page-specific color systems, button systems, radii, shadows, decorative gradients, ornamental backgrounds, or business-irrelevant illustrations.
- Use page structure appropriate to the app: title, query/filter area, action area, table/list/card content, pagination or footer actions.
- Keep page margins at 24px or 32px unless a local pattern requires otherwise.
- Avoid nested cards except for repeated list items or genuinely framed subtools.
- Do not use marketing-style hero sections, decorative gradients, ornamental backgrounds, or unrelated illustrations in business screens.
Ant Design Vue Usage
| Need | Prefer |
|---|---|
| Layout | a-layout, a-menu, a-tabs, a-card, a-space, a-flex, a-row, a-col |
| Form input | a-form, a-form-item, a-input, a-input-number, a-select, a-switch, a-checkbox, a-radio, a-date-picker |
| Data display | a-table, a-tag, a-empty, a-statistic, a-typography |
| Feedback | a-modal, Modal.confirm, message, a-spin, a-progress, a-alert |
| Icons | @ant-design/icons-vue |
Use default component styles, official props, slots, layout components, and theme tokens first. Custom CSS is for local layout constraints or real readability needs.
When overriding Ant Design Vue internals:
- Keep the override inside scoped styles.
- Use
:deep()under the current component root class only when the rendered DOM is actually its descendant. Ant Design portal shells may lack the component scope attribute; inspect the DOM and computed styles, then use a narrowly namespaced:global(.module-modal .ant-modal-body)when needed. - Avoid global
.ant-*overrides unless the task is a deliberate project-wide token or global fix. - Avoid
!important; if unavoidable, document the reason.
Tokens And Styling
- Use Ant Design tokens or existing CSS variables for colors, backgrounds, borders, spacing, radius, shadow, and text.
- Main spacing should follow 4px/8px multiples: 8, 16, 24, 32 are the usual anchors.
- Use restrained type scales: 12, 14, 16, 18, 20, 24 for normal business pages.
- Cards and modals usually use 8px or 12px radius; controls use Ant Design defaults.
- Use light shadows sparingly; backend pages should not feel floaty.
- Styles default to scoped and semantic kebab-case classes.
Theme And Dark Mode
- The single theme source of truth is
src/composables/useTheme.ts: it toggles thedarkclass on<html>and injects all--ant-*variables on:root.ConfigProviderruns withoutcssVar, so AntD token variables do not exist at runtime unlessuseThemedefines them. - In CSS, prefer
--ant-*tokens that already adapt to the theme. When a distinct dark value is unavoidable, key it on thehtml.darkancestor selector inside scoped styles. Never use@media (prefers-color-scheme: ...)in components; it follows the OS instead of the app theme. - Never invent theme hooks such as
[data-theme='dark']or a.lightclass; nothing in the codebase sets them, so such rules are dead code. - In JS/TS, derive theme-dependent values from the reactive
isDarkexported byuseTheme. Never readwindow.matchMedia('(prefers-color-scheme: ...)')outsideuseTheme.ts; a matchMedia call inside a computed is non-reactive and will not update on theme or OS changes. - Reference only
--ant-*names defined byuseTheme.updateCSSVariables(). Every--ant-*definition must map to the matchingantTokens.<token>value derived from the same Ant Design algorithm and seed used byConfigProvider; never approximate Ant Design tokens with hand-written light/dark values. Use a literal name in eachsetPropertycall so the variable stays greppable. - Reserve
--app-*for project-specific shared values that have no Ant Design token equivalent. Derive those values from the app theme inuseTheme.ts, with explicit light/dark behavior where needed. - When adding theme-aware styles, verify both themes with the app's own theme switch, not the OS setting.
CSS Variable Audit
Before completing styling work that touches colors, borders, backgrounds, or adds var() references, run the undefined-CSS-variable audit in references/css-variable-audit.md. Fix every reported variable by correcting it to an existing token, mapping a missing --ant-* variable to its matching antTokens.<token>, or defining a genuinely project-specific --app-* variable.
Component Patterns
Buttons
- Use one primary action per main page region.
- Use
dangerfor delete, stop, disable, clear, or irreversible actions. - High-risk actions require
Modal.confirm. - Async submit/search/start/stop/export actions need
loadingorconfirm-loading. - Icon-only buttons need accessible naming such as
aria-labelwhen context is not enough.
Forms
- Use
a-form; complex configuration pages preferlayout="vertical". - Use
rulesandrequired; do not rely on placeholder as validation. - Placeholder text should describe user action.
- Long forms should be grouped by business meaning.
- Submit failures must preserve user input and show a concrete reason.
- Similar create/edit flows should reuse an edit component with
isEditor route parameters. - Read-only detail views must not reuse editable controls in an active editing state.
Tables And Lists
- Standard data lists prefer
a-table; use custom lists for drag, complex cards, or virtual logs. - Specify widths for ID, status, time, and action columns.
- Keep row actions stable; use a More menu when there are more than three actions.
- Show loading and empty states.
- Use
a-tagonly for finite enum statuses or scan-friendly categories. - Time format is
YYYY-MM-DD HH:mm:ssunless a local pattern differs. - Parent-child search must define its matching semantics: a parent match may retain all children, while a child match should retain the parent and only the matching children unless the product explicitly needs broader results.
- Do not write filtered subsets back through full-list drag-sort APIs. Disable reordering while searching, or explicitly map the result back to the complete source list.
- Search may expand matching groups for discoverability, but must not overwrite the user's persisted collapse preference.
Modals And Drawers
- Use
Modal.confirmfor destructive confirmation. - Use
a-modalfor short forms and simple flows. - Prefer Drawer or a full page for long configuration, complex details, or logs.
- Titles use concrete wording such as "新增 XX", "编辑 XX", "查看 XX", "删除确认".
- Footer buttons follow "取消 / 确定" or "取消 / 保存".
- Avoid browser-native
alertandconfirm. - Close protection is required when dismissing a form would lose unsaved changes.
- In the frameless Electron window, treat the title bar and its minimize, maximize, and close buttons as reserved application chrome. Ordinary modals, masks, drawers, and popovers must not cover or block those controls.
- Inspect the title bar height and stacking context before setting overlay
z-index. Prefer reserving the title bar height plus normal spacing; do not raisez-indexto repair positioning. Reserve the chrome for both the overlay wrapper and its mask, since moving only the dialog does not keep window controls clickable. Only an intentional startup or shutdown safety layer may block window controls. - At low window heights, constrain the dialog to the usable viewport and choose exactly one vertical scroll owner for the flow, normally the dialog body or content region. Ordinary child lists and grids must expand inside that scroller instead of adding another
overflow-y: auto; nested scrolling is reserved for deliberately independent panes. Do not make the page body or the modal wrapper provide the overflow, and keep close and footer actions reachable. - For title-bar spacing, portal styling, or dialog overflow work, read Electron overlay layout. Inventory related template modals, composable/static confirmations, and nested dialogs before declaring the feature fixed.
Scrollbars
- Define scrollbar width, track, thumb, and hover colors in the shared global stylesheet or shared tokens; do not repeat browser-specific scrollbar rules in individual pages.
- Scrollbars must support both light and dark themes. Tracks should be transparent or theme-matched, and a dark surface must never expose a hard-coded white track.
- Local scrollbar overrides are allowed only when a component has genuinely different interaction needs, and should reuse shared variables where possible.
- Do not hide scrollbars globally. Hidden scrollbars are acceptable only for deliberate containers that remain operable by wheel, touchpad, keyboard, and other supported input methods.
Page States
Every page or major panel should account for:
- First load.
- Loading.
- Failure with reason and retry when useful.
- Empty state with context.
- Data state.
- Disabled state where relevant.
- Success and failure feedback for async operations.
Loading indicators for an otherwise empty panel or dialog step must sit in a container with explicit usable size and centered alignment. Do not place an overlay spinner around zero-height conditional content, which leaves the indicator anchored at the container origin.
For WebSocket, scheduler, download, backend startup, and other process flows, distinguish connecting, connected, disconnected, reconnecting, timeout, processing, success, and failure when those states exist.
Issue 128 UX Constraints
Drag Interactions
- Draggable rows must expose a visible drag handle such as
MenuOutlinedorDragOutlined. - The drag hot zone belongs to the handle area, not the whole row.
- Buttons, inputs, switches, selects, and links inside rows must remain clickable.
- Use
grabon handles andgrabbingwhile dragging. - Use one drag feedback style, not multiple placeholder or ghost effects at once.
Tooltip And Toast
- Use Tooltip only when an icon is unclear, a rule is complex, or an operation is risky.
- Do not add Tooltip that repeats visible button text.
- Do not show success Toast for trivial reversible toggles when the component state is already clear.
- Always show error feedback for failed toggles, saves, and API exceptions.
Tag And Status
- Tags are for finite statuses or categories, not usernames, paths, IDs, timestamps, free text, or progress text.
- One object should have one primary status at a time.
- Use green for success, red for failure, orange/gold for warning, blue for processing.
- Do not show success and failure with similar weight on the same object.
Navigation And Dialog Flow
- Breadcrumbs must reflect real reachable navigation, not invented hierarchy.
- Detail and edit pages need a clear return path.
- If selecting an item necessarily advances to the next step, advance directly instead of adding a redundant confirm button.
Verification Gate
Before declaring UI work complete:
- Check light mode and dark mode when visual styling changes.
- Confirm text does not overlap, clip important actions, or overflow containers at common desktop widths.
- Confirm loading, empty, error, disabled, success, and failure states affected by the task.
- Run the relevant project verification from
mas-frontend-standards. - If UI cannot be visually checked, state what was not checked and why.
- Confirm interactive elements are visually discoverable and disabled elements are clearly non-interactive.
- For overlays in Electron, follow the representative viewport and interaction checks in Electron overlay layout. Verify window-control hit targets and clicks while a dialog and its nested confirmation are open; a visible title bar alone does not prove it is usable.
- When scrollbar styling changes, inspect both light and dark themes on an actually scrollable surface.
- Confirm
prefers-color-schemeappears only insrc/composables/useTheme.ts; grep for it when touching theme-related styles. - Run the CSS variable audit from
references/css-variable-audit.mdand confirm zero undefined references.
Red Lines
| Temptation | Reality |
|---|---|
| "This page can have its own style." | AUTO-MAS uses a shared desktop business UI language. |
| "A custom button/input/table is faster." | Use Ant Design Vue and existing project components first. |
| "A tag makes short text look neat." | Tags are only for finite statuses or categories. |
| "Hover cursor is enough for drag." | Draggable items need visible handles and protected inner controls. |
| "Success/failure messages can be generic." | Feedback should state the concrete result or reason. |
| "Dark mode can wait." | Color and token changes must remain readable in both themes. |
| "prefers-color-scheme is the standard way." | The app theme overrides the OS theme; components must key on html.dark or tokens, never media queries. |
| "Any --ant-* name will work." | AntD does not emit CSS variables here; only names defined in useTheme.updateCSSVariables() resolve. |
Final Response
For UI tasks, report:
- UI change scope.
- Ant Design Vue and token usage.
- State handling touched by the task.
- Light/dark mode checks or why they were not run.
- Verification commands and results.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |