Mas Frontend UI

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:

1. Inspect the target page and adjacent pages to learn the module's real layout, spacing, component usage, and wording.
2. Confirm the project uses Ant Design Vue and @ant-design/icons-vue, not Element Plus, Naive UI, Arco, or Ant Design React.
3. Confirm theme variables come from src/style.css and src/composables/useTheme.ts.
4. Prefer existing components, layout classes, theme tokens, and wording before adding new ones.
5. Check both light and dark mode for readability when UI colors, borders, backgrounds, or status colors change.
6. Keep the UI inside the existing Electron desktop business-product language.

Visual Direction

1. Treat pages as desktop operational tools, not marketing pages.
2. Prefer clarity, scanability, consistency, and low distraction.
3. Do not create page-specific color systems, button systems, radii, shadows, decorative gradients, ornamental backgrounds, or business-irrelevant illustrations.
4. Use page structure appropriate to the app: title, query/filter area, action area, table/list/card content, pagination or footer actions.
5. Keep page margins at 24px or 32px unless a local pattern requires otherwise.
6. Avoid nested cards except for repeated list items or genuinely framed subtools.
7. Do not use marketing-style hero sections, decorative gradients, ornamental backgrounds, or unrelated illustrations in business screens.

Ant Design Vue Usage

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:

1. Keep the override inside scoped styles.
2. Use :deep() under the current component root class.
3. Avoid global .ant-* overrides unless the task is a deliberate project-wide token or global fix.
4. Avoid !important; if unavoidable, document the reason.

Tokens And Styling

1. Use Ant Design tokens or existing CSS variables for colors, backgrounds, borders, spacing, radius, shadow, and text.
2. Main spacing should follow 4px/8px multiples: 8, 16, 24, 32 are the usual anchors.
3. Use restrained type scales: 12, 14, 16, 18, 20, 24 for normal business pages.
4. Cards and modals usually use 8px or 12px radius; controls use Ant Design defaults.
5. Use light shadows sparingly; backend pages should not feel floaty.
6. Styles default to scoped and semantic kebab-case classes.

Theme And Dark Mode

1. The single theme source of truth is src/composables/useTheme.ts: it toggles the dark class on <html> and injects all --ant-* variables on :root. ConfigProvider runs without cssVar, so AntD token variables do not exist at runtime unless useTheme defines them.
2. In CSS, prefer --ant-* tokens that already adapt to the theme. When a distinct dark value is unavoidable, key it on the html.dark ancestor selector inside scoped styles. Never use @media (prefers-color-scheme: ...) in components; it follows the OS instead of the app theme.
3. Never invent theme hooks such as [data-theme='dark'] or a .light class; nothing in the codebase sets them, so such rules are dead code.
4. In JS/TS, derive theme-dependent values from the reactive isDark exported by useTheme. Never read window.matchMedia('(prefers-color-scheme: ...)') outside useTheme.ts; a matchMedia call inside a computed is non-reactive and will not update on theme or OS changes.
5. Reference only --ant-* names defined by useTheme.updateCSSVariables(). Every --ant-* definition must map to the matching antTokens.<token> value derived from the same Ant Design algorithm and seed used by ConfigProvider; never approximate Ant Design tokens with hand-written light/dark values. Use a literal name in each setProperty call so the variable stays greppable.
6. Reserve --app-* for project-specific shared values that have no Ant Design token equivalent. Derive those values from the app theme in useTheme.ts, with explicit light/dark behavior where needed.
7. 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

1. Use one primary action per main page region.
2. Use danger for delete, stop, disable, clear, or irreversible actions.
3. High-risk actions require Modal.confirm.
4. Async submit/search/start/stop/export actions need loading or confirm-loading.
5. Icon-only buttons need accessible naming such as aria-label when context is not enough.

Forms

1. Use a-form; complex configuration pages prefer layout="vertical".
2. Use rules and required; do not rely on placeholder as validation.
3. Placeholder text should describe user action.
4. Long forms should be grouped by business meaning.
5. Submit failures must preserve user input and show a concrete reason.
6. Similar create/edit flows should reuse an edit component with isEdit or route parameters.
7. Read-only detail views must not reuse editable controls in an active editing state.

Tables And Lists

1. Standard data lists prefer a-table; use custom lists for drag, complex cards, or virtual logs.
2. Specify widths for ID, status, time, and action columns.
3. Keep row actions stable; use a More menu when there are more than three actions.
4. Show loading and empty states.
5. Use a-tag only for finite enum statuses or scan-friendly categories.
6. Time format is YYYY-MM-DD HH:mm:ss unless a local pattern differs.
7. 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.
8. 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.
9. Search may expand matching groups for discoverability, but must not overwrite the user's persisted collapse preference.

Modals And Drawers

1. Use Modal.confirm for destructive confirmation.
2. Use a-modal for short forms and simple flows.
3. Prefer Drawer or a full page for long configuration, complex details, or logs.
4. Titles use concrete wording such as "新增 XX", "编辑 XX", "查看 XX", "删除确认".
5. Footer buttons follow "取消 / 确定" or "取消 / 保存".
6. Avoid browser-native alert and confirm.
7. Close protection is required when dismissing a form would lose unsaved changes.
8. 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.
9. Inspect the title bar height and stacking context before setting overlay z-index. Keep normal business overlays below the title bar or reserve its space; only an intentional startup or shutdown safety layer may block window controls.
10. 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.