Alego Client UI UX

Alego Client UI/UX

This skill is guidance, not a complete checklist. It covers judgment calls that lint, typecheck, and the i18n gate cannot make: where feedback appears, what gets reused, and how surfaces behave at window edges and across platforms. Copy quality itself follows alego-prose-standard; locale ownership follows the locale-owned copy decision; styling ownership and token rules live in docs/web-styling.md and the ui-primitives component catalog — this skill adds judgment on top of those rules, not a second copy of them.

Visual foundation

• Use existing tokens for color, radius, and spacing. Before introducing a literal value, search the target page and its nearest established sibling (the Plugins page is the usual reference for full-page surfaces) for the token or value already in use, and adopt it. The same applies to whole treatments — toasts, menus, in-message artifact previews, sidebar tab layout, colors, clearance rules, page padding: reuse the established component or rule wherever one exists instead of inventing a parallel one.
• Verify every color in both light and dark mode. An ink/background pair must stay readable under both themes before it ships. Dimmed tones are the standing counter-example: they suit decorative surfaces, but on text they routinely fall below readability in one theme — never put a dimmed color on text without checking both.
• Font weight tops out at 500 in feature CSS you add or change. Do not use 600+ for emphasis; differentiate with size or ink instead. The markdown typography tokens owned by ui-theme are the standing exception.
• Pick font sizes from the theme typography variables when an existing role matches, otherwise from the page's existing scale. Parallel content shares one size; never invent a size for a single element, and keep the number of distinct sizes on a page small (13px is the established row/detail size). When the page itself has no precedent, borrow the size and spacing ratios of the most similar existing page or element.
• Icons, text, and neighbouring elements stay proportionate and aligned. Every element lines up with its siblings along a deliberate axis (baseline, vertical center, or shared edge), and an icon's size stays in proportion to the text beside it; never ship an element that aligns to nothing or visibly outweighs its neighbours.

Reuse before adding

• Extend an existing component, container, or interaction before creating a new one. A new capability that fits an existing surface (an extra menu item, a new prop on an existing primitive) beats a parallel element stacked beside it.
• Icons come from the existing icon library. Pick the semantically closest existing icon; a new glyph requires designer approval before it lands — when reviewing a PR that adds one, suggest requesting a designer review.
• Right-sidebar content registers a slot in the existing sidebar, never a separate sidebar. Every sidebar tab declares a tab icon matching its meaning.
• Icon-only actions whose meaning is not obvious get a Tooltip. Informational content the pointer must rest on or select uses HoverCard instead. Prefer these shared primitives over ad-hoc title attributes.

Feedback surfaces

Choose the surface by the lifetime of the message relative to the surface that produced it:

• Transient operation outcomes use the app-wide Toast primitive, not in-place notices, and the toast's state and rendering live in a host that outlives the reporting surface (a shell.overlay entry, as RowActionToast does) — a toast rendered by the panel itself unmounts with that panel. A deletion can close the panel or tab that requested it; only a toast held outside that surface survives the close. Report success and failure; do not report still-pending states.
• A failed operation keeps the data visible. A failed deletion keeps its row; the toast announces the failure. Never blank content to show an error for a transient operation.
• In-place notices are for states tied to the surface itself: a query failure with its Retry action, field validation on the form that owns the field. A populated panel keeps a compact notice beside its retained content; only an empty panel centers a full error state.
• Error copy is plain language, and short. No internal jargon or technical nouns unless an error code must be exposed for debugging. Prefer one clear sentence; anything explainable in two sentences must not grow into paragraphs. A Chinese notice of at most two sentences omits the trailing 句号（。）. The notice must not break the existing layout — reserve its space or overlay it; never shift neighbouring elements.