hello-ui

This skill is not the sole source of UI quality. The currently loaded HelloAGENTS UI quality baseline is responsible for the baseline standard of all UI tasks; this skill adds clearer contract execution, implementation mapping, and visual acceptance in explicit UI workflows, host global mode, and complex UI tasks. .helloagents/ In this skill, uniformly understand this as the project-level storage path: session evidence uses the current state_path in the directory where it is located artifacts/*.json; if project_store_mode=repo-shared，DESIGN.md and the solution package are resolved according to the project knowledge/solution directory already injected in the current context.

Applicable Boundaries

Read this skill when an explicit UI planning/implementation/verification path has been entered, for UI tasks in host global mode, or when the current project has been initialized and the task involves creating a whole page, a visual overhaul across multiple components, a design system overhaul, or interface tasks requiring screenshot acceptance. For ordinary UI requests in standard mode and when the project is not initialized, they remain constrained only by the currently loaded HelloAGENTS UI quality baseline; tasks such as fixing bugs, adjusting copy, or changing business logic that do not involve visual changes do not read this skill. When working in an existing design system, preserve the established patterns, structure, and visual language.

Design Contract Priority

When entering UI-related planning, implementation, and verification, make design decisions in the following order:

The currently active solution package plan.md or the confirmed UI decisions in the PRD
.helloagents/DESIGN.md(resolved according to the current project storage mode)
The specific UI aesthetic and implementation rules of this skill that have been read All UI tasks must satisfy the UI quality baseline; only when upper-layer artifacts are missing may lower-layer rules be relied on directly; general aesthetics must not be used to override confirmed project contracts.

Core Responsibilities

Follow upstream contracts: treat the confirmed UI decisions in plan.md / PRD / DESIGN.md as hard constraints, not suggestions
Handle optional UI contracts: if contract.json enables ui.styleAdvisor, reuse the current session artifacts/advisor.json to record design direction review evidence; if ui.visualValidationis enabled, use the current session artifacts/visual.json to record visual acceptance evidence
Map to code structure: clarify where tokens are placed, how component boundaries are divided, how state components are organized, and how motion and themes are implemented
Close the visual acceptance loop: prioritize screenshot/browser tools for desktop and mobile checks; when no tools are available, still complete a structured visual self-check
Write back stable decisions: only sync design system rules that hold stably across features back to .helloagents/DESIGN.md(resolved according to the current project storage mode), and do not write all one-off page details into project-level contracts

Design Brief (must be clear before coding)

Understand the context first, then make bold and intentional design decisions:

Purpose: What problem does this interface solve? Who uses it? In what scenario? On what platform?
Aesthetic direction: Choose a distinct direction and stick with it. Do not apply fixed style labels; instead, based on the project's audience, scenario, and emotional goals, create a unique style that is faithful to the context. First ask clearly: what emotion do this product's users expect? What visual language can convey that emotion?
Memorable point: What one feature will users remember when they see this design?
Differentiation: When the task explicitly calls for exploration, or when ready-made design constraints are lacking, proactively avoid slipping into common default styles; differentiation must serve product semantics, brand boundaries, and usability, not change for change's sake.
Design tokens: Establish a variable/token system as early as possible—background color/surface color/primary color/muted color/accent color + font roles for display/heading/body/caption text. Use CSS variables for the web, and the corresponding theme system for desktop/mobile platforms.
Constraint definition: Define specific constraints for the current project (such as at most how many sections, how many fonts, how many accent colors, and the number of CTAs on the first screen), using constraints to help unleash creativity.
Real content: Use real copy, product information, and project context; do not use Lorem ipsum or generic placeholders. Real content more easily helps make design decisions that fit the context.

Execution order requirements:

When the current project already has local project storage and .helloagents/DESIGN.mdexists (resolved according to the current project storage mode), upon entering a real UI task, read it first, then expand the plan or implementation
If the design direction has been confirmed through a solution package or PRD, execute according to the confirmed direction, and take the UI decisions in plan.md / PRD as the highest priority
When the current project already has local project storage, and the current task is a full-page creation, design system overhaul, or visual redesign spanning multiple components, but .helloagents/DESIGN.md(resolved according to the current project storage mode) does not exist, first follow templates/DESIGN.md to create a minimal design contract (covering at least product surfaces, design tokens, components and patterns, state coverage, accessibility requirements, and prohibited items), then continue with large-scale implementation
For tasks without a solution package and without DESIGN.md , based on the above rules, make design decisions and execute by combining task requirements and project context

Implementation mapping (must be clarified before entering coding)

Token placement: Which token / theme file colors, fonts, spacing, corner radius, shadows, and motion parameters respectively go into
Component boundaries: Which capabilities become reusable components, and which remain only on the current page; avoid extracting one-off layouts into incorrect "generic components"
State matrix: How loading, empty, error, success, disabled, and danger states involved in the current interface are respectively presented
Theme and adaptation: How light/dark mode, responsive breakpoints or platform sizes, safe areas, and minimum window/minimum viewport are handled
Acceptance evidence: What are the key viewports, key states, and key screenshot points that need to be checked this time

Structural rules

The following rules concern composition and information architecture, and apply according to page type.

Showcase pages (landing pages, marketing pages, product showcase pages)

First-screen composition:

The first screen must be a complete composition, and the brand/product name must be the most obvious recognition point
Brand test: If the first screen could belong to any brand after removing the navigation bar, the brand feel is too weak

Hero area:

The hero image must be an edge-to-edge key visual plane or background
Hero budget: The first screen usually contains only the brand, one headline, one supporting sentence, one set of CTAs, and one main image
Do not place secondary content in the hero area, and do not overlay floating elements on the hero media

Page narrative:

Hero — establish identity and promise
Supporting imagery — show context or environment
Product details — explain the product/service
Social proof — build credibility
Final CTA — turn interest into action

Application-type pages (Dashboard, admin backend, tool-type apps)

Information density first: display data efficiently, use space sensibly
Clear navigation hierarchy: main navigation/sidebar/breadcrumbs so users always know where they are
Action discoverability: key actions are prominent and reachable, secondary actions go into menus
Status at a glance: use color/icons/badges to convey status, reduce users' cognitive load

General rules (all page types)

Card restraint: by default do not use cards; cards are used only when serving as interactive containers. If removing the border/shadow/background/rounded corners does not affect comprehension, it should not be a card
Section discipline: each section does only one thing; avoid piling up tag clusters, stat bars, icon rows, and multiple competing text blocks
Real visual focus: images should show the product, place, atmosphere, or context; decorative gradients and abstract backgrounds do not count as the main visual

Visual execution

Typography

Choose expressive, purposeful fonts. Display fonts paired with body fonts should have contrast (serif + sans-serif, or bold + light). Avoid default font stacks. Prioritize variable fonts (fewer requests, support for fine adjustments) and currently popular high-quality fonts.

Color scheme

Choose a clear visual direction and use a token system to establish consistency. A bold primary color + sharp accent color is better than timid even distribution. Dark themes use desaturated tone variants, not simple inversion. Prioritize perceptually uniform color spaces (such as OKLCH) to generate harmonious color scales.

Layout

Conscious use of space. Asymmetry, overlap, diagonal flow, and rule-breaking elements are all good tools. Establish a consistent spacing system and maintain a global rhythm. Prioritize the target platform's current latest layout capabilities to implement responsive design.

Motion

Use motion to create presence and hierarchy, not noise. One carefully choreographed entrance animation (with staggered delays) is better than scattered micro-interactions. Duration reference: instant feedback < 100ms, micro-interactions 150-300ms, complex transitions ≤400ms. At least 2-3 intentional motion effects. Animations must be interruptible and must not block user input. Support reduced motion preference settings. Prioritize the platform's native animation capabilities, and introduce animation libraries only for complex scenarios.

Atmosphere and texture

Do not rely on solid-color backgrounds. Gradient meshes, noise textures, geometric patterns, transparent overlays, dramatic shadows, grain overlays — choose techniques that match the overall aesthetic to create a sense of depth.

Implementation standards

Accessibility (highest priority, all platforms)

Color contrast ratio ≥ 4.5:1 (body text), ≥ 3:1 (large text)
All interactive elements support keyboard/assistive technology operation
Do not convey information by color alone (add icons or text)
Support system-level reduced motion settings
Web: semantic HTML, aria-label, visible focus ring
Desktop/mobile: use platform-native accessibility APIs (VoiceOver/TalkBack/Narrator)

Responsiveness and adaptation

Web: determine the primary target viewport based on the product's main usage scenario (design desktop-first for desktop products, mobile-first for mobile products), then adapt to other viewports. Prioritize component-level responsiveness rather than relying only on viewport breakpoints, ensuring all target viewports can be used normally
Desktop apps: support free window resizing, a reasonable minimum window size, and adaptive content
Mobile apps: adapt to different screen sizes, respect safe areas (notch/gesture bar), support portrait and landscape orientation
General: body text minimum 16px/pt, touch/click targets ≥ 44px/pt

Interaction Feedback

Loading states: skeleton screens > spinner > blank waiting
Empty states, loading states, and error states must all have corresponding UI
Mobile: use haptic feedback appropriately (confirmations, important actions)
Desktop: support common keyboard shortcuts

Platform Conventions

Web: prefer platform-native animation capabilities (CSS animations, native transition APIs); only bring in animation libraries for complex scenarios
iOS: follow HIG (bottom Tab Bar, swipe back, Dynamic Type)
Android: follow Material Design (top App Bar, ripple feedback, predictive back)
Desktop: follow the platform's native control style unless branding requires customization
Game UI: prioritize readability and operational efficiency; the HUD must not obstruct core content
General: consult the target platform's latest current design guidelines and APIs; do not rely on outdated knowledge

Forms

Every input field must have a visible label
Error messages displayed adjacent to the field
Validate on blur
On submit: button disabled + loading indicator + success/failure feedback
Long forms automatically save drafts; multi-step forms show a progress indicator
Destructive actions use semantic danger colors and are visually separated from regular actions

Charts and Data Visualization

Chart type matches data type (trend → line chart, comparison → bar chart, proportion → pie/donut chart)
Provide legends and interactive tooltips
Use accessible color schemes (distinguish data not by color alone, but also with patterns or labels)
Use virtual scrolling or aggregated display for large datasets

Interaction Logic

State Completeness

Every asynchronous operation must cover four states: loading, success, error, and empty data. Missing any one of them is an interaction defect. Error messages must be specific and actionable (explain the cause + how to fix it); generic prompts like "Something went wrong" are not acceptable.

Focus Management

Focus must never disappear or become unexpectedly trapped
Tab/Shift+Tab moves between controls; arrow keys navigate within composite controls
When a modal opens, focus is trapped inside; when it closes, focus returns to the triggering element
After a page/route change, focus moves to the main content area
After a submission error, focus automatically moves to the first error field

Modals and Dialogs

Use only when it is necessary to interrupt the user's flow; not for displaying non-critical information
Must support closing with Escape; have a clear close/cancel entry point
Do not nest modals
Confirm before closing when there is unsaved content

Navigation

Users always know where they are (highlight the current position, breadcrumbs, title)
Back behavior is predictable and consistent; preserve scroll position and filter state
Primary navigation remains reachable on deep pages
Destructive actions (delete account, log out) are visually and spatially separated from regular navigation items

Lists and Data

Pagination suits comparison/location scenarios, infinite scroll suits discovery/browsing scenarios
The search box must be prominent and reachable in content-intensive applications
Filters adjust dynamically with the query context (disable options with zero results)
Sortable tables indicate the current sort state

Progressive disclosure

Present complex features step by step, not all options at once
Collapse advanced settings or move them into a secondary entry point
Guide new users to discover features gradually, rather than showing everything at once

Complexity matching

Implementation complexity must match the design goal. Interfaces that need strong expressiveness can use richer implementation; interfaces that need restraint should stay simple and precise. Don't pile on effects for the sake of effects, and don't flatten the design just to play it safe—instead, make unexpected but reasonable choices based on context, showing genuine creativity.

Delivery check

Checklist

Typography: expressive, with contrasting pairings
Color: a cohesive color system with consistent tokens
Composition: complete above the fold, strong brand feel (showcase pages) / clear information hierarchy (application pages)
Structure: single responsibility per section, with overall rhythm
Motion: at least 2-3 intentional animations, interruptible, respecting reduced-motion settings
Atmosphere: background has depth
Memorable point: there is one design feature that makes it memorable
Contract consistency: confirmed plan.md / PRD / DESIGN.md decisions are consistent with implementation; new stable design decisions have been synced back to DESIGN.md
State coverage: every asynchronous operation has loading/success/error/empty states
Focus management: reasonable Tab order, focus trapped in modals, focus returns to the trigger element after closing
Accessibility: contrast meets standards, assistive technologies usable
Adaptation: works properly on target platforms
Technical modernity: the technical solutions used comply with HelloAGENTS technical selection principles and engineering quality floor; if the current mode has not loaded the engineering quality floor in the implementation requirements, then at least satisfy the technical selection principles and have no outdated dependencies
Does not use outdated patterns explicitly prohibited by the currently loaded HelloAGENTS rules; if the current mode has not loaded that section, then at least avoid the listed outdated patterns such as default purple gradients, stacked white cards, default font stacks, and emoji icons

Design self-assessment

Score each of the following dimensions from 1-10; any dimension below 8 must be iteratively improved:

Typography expressiveness and pairing quality
Color cohesion and brand feel
Composition and visual hierarchy
Motion intentionality and smoothness
Overall atmosphere and memorable point
Technical modernity and performance

For dimensions still below 8 after 3-5 rounds of iteration, record the reasons and discuss with the user.

Visual self-check

If browser tools are available (Playwright MCP, etc.):

Screenshot the rendered result (desktop + mobile viewports)
Review the screenshots against the design principles: Is the composition complete? Is the brand feel in place? Is the color consistent?
Find issues → fix → screenshot again to verify
If the current contract requires ui.visualValidation.required=true, call scripts/visual-state.mjs write to write the current session artifacts/visual.json, recording reason、tooling、screensChecked、statesChecked、status and summary
Only report completion after confirming the screenshot matches the design intent

When there is no browser tool, carefully review the generated code to confirm that the implementation of styles, layout, and animations matches the design intent. If the current contract requires ui.visualValidation.required=true, you still need to use a structured conclusion to call scripts/visual-state.mjs write to write the current session artifacts/visual.json, and clearly mark the tooling used and the screens / states that have been checked.