高保真界面原型

High-Quality UI Prototype Design

I. Core Goal

The goal is to create beautiful product interfaces that are also highly usable.

The output should resemble a real product completed by an experienced designer, not a generic prototype built from templates, stacked cards, or simple color swaps. Focus on the overall personality, visual hierarchy, typography, composition, color relationships, graphic language, motion, and level of detail.

• Aesthetics First, Without Sacrificing Usability: Design visuals and functionality together; do not remove features for the sake of superficial simplicity.
• Style is Dictated by the Product: Allow for restrained, refined, lively, avant-garde, opulent, or experimental styles. Do not treat "premium minimalism" as the only answer.
• Design Proactively: Do not wait for the user to provide colors, fonts, layout, or animation parameters. Understand the requirements and actively explore better solutions.
• Reject Template Feel: Do not default to common SaaS layouts, fixed color palettes, uniform cards, and generic component combinations.
• Independent Derivation: Even for the same product category, develop a unique visual expression based on its specific content and positioning. Do not mechanically reuse the visual scheme from the previous iteration.

Design Principles Reference

You may refer to the following established principles for design judgment, but do not copy their examples or translate them into fixed parameters:

• Visual hierarchy, proportion, balance, contrast, Gestalt principles, and visual focus.
• Grids, composition, rhythm, whitespace, unity, and brand identity.
• Consistency, discoverability, progressive disclosure, feedback, and accessibility.
• Font personality, typeface quality, reading context, and font pairing.
• Continuity in motion, natural easing, spatial relationships, and interaction feedback.

References: NNGroup Visual Design Principles · Figma UI Design Principles · IBM Design Language · Apple HIG Motion

Do Not Reuse Existing Pages

• For new pages, do not read, screenshot, or analyze existing pages in the ui/ directory. Do not copy their HTML/CSS/JS as a starting point.
• Do not reuse colors, fonts, layout structures, component combinations, or animation parameters from previous iterations. Design differences must go beyond simply swapping colors, copy, or images; rethink the information structure and visual expression.
• Only this skill, skills/ui-metadata/SKILL.md, the usage instructions for tools/, and the user's references provided in the current session are allowed.
• If the user explicitly requests modification of an existing page, only read that specific page.

II. Understand the Product First, Then Design

First, determine the product's positioning, target users, usage scenarios, content characteristics, and brand personality, and then define the visual direction. Do not treat the categories below as templates; they are merely design considerations:

Product Personality	Exploratory Design Expressions
International / English Brand	Concise copy, expressive typography, large-scale layout, kerning and whitespace, photography, and symbols
Trendy / Creative / Youthful	Bold composition, strong typeface personality, iconic symbols, geometric shapes, visualized data, and flexible color relationships
Professional Tool / Desktop Software	Clear information organization, refined typography, comfortable information density, detailed state feedback, and restrained colors
Tech / AI / Data Product	Modern fonts, data visualizations, structural graphics, dynamic feedback, and a distinctive tech aesthetic
Culture / Art / Content Brand	Editorial typography, serif or expressive fonts, photography, textures, whitespace, and emotionally evocative colors
High-End Consumer / Lifestyle	Refined typography, product imagery, texture and lighting, detailed craftsmanship, and understated yet distinctive brand expression

You can mix different directions or propose a completely original direction better suited to the product. Do not mechanically apply a specific style name.

Delivery Container

Type	Criteria	Frame & Scrolling	Canvas Boundary
A Software	Dashboard, tool, admin panel	Full window display; long lists and long text scroll within local areas	Locked within the window; overlays must not extend beyond it
B Web Page	Brand, landing, content site, portfolio	Natural document flow; full-page vertical scrolling	The viewport is the canvas; no boundary limits
C App	Mobile-first, explicitly an App / Phone / Mini Program	Phone frame; scroll only within the frame	Locked within the phone frame
D Component	Single control like player, lightbox, upload box	Natural size based on content; internal local scrolling	Locked within the component's box

If the user specifies a type, follow their request. If not, infer it from the functionality. The container only determines the display method, not the visual style.

Container Design Key Points

A Software

• Ensure the window, background, and content form a complete display relationship. The frame should serve the product; do not add unnecessary decoration for a floating effect.
• Prioritize the natural coexistence of primary information and common operations. Complex content should be handled through logical zoning and local scrolling.
• First, establish the spatial layout and responsive structure, then define scrolling areas. Do not mask layout issues with clipping, hidden scrollbars, or overall scaling.
• On narrow screens, prioritize rearrangement, grouping, and adjustment of information presentation. Core functionality must not disappear.
• Software width should not exceed 85% of the overall window, height 90%. Leave spacing on all sides and display it centered.

B Web Page

• Choose a structure based on content: long-form narrative, modular browsing, immersive hero section, or other suitable layouts.
• The page should have visual rhythm and content hierarchy. Avoid repeating the same layout for every section.
• Scroll-driven animations can be added based on narrative needs. Do not force scroll effects just to follow a rule.

C App

• Use navigation patterns, single-column or context-appropriate layouts, and easy-to-use controls that align with mobile habits.
• Visually customize native controls as needed, but do not harm accessibility or the operating experience.
• Touch targets, bottom navigation, and content scrolling should follow real mobile usage patterns.
• It is recommended to design using iPhone dimensions (creating a Dynamic Island or front camera is not required).

D Component

• Shape the component naturally based on its purpose and content; do not encase it in a full software shell.
• Focus on designing states: idle, hover, focus, loading, completed, error. All state transitions should be clear, coherent, and understandable.

The overlay boundaries for the four types above are unified in the next section.

Container Boundaries: Lock the UI in the Canvas (Mandatory for Software / App / Component)

This is a hard constraint, not a stylistic preference. For web pages, the boundary is the browser viewport. For software, apps, and components, they have their own boundaries. Outside the canvas is only the "stage" (the viewing background). Once a dialog, drawer, scrim, or blur effect extends beyond the canvas, the interface degrades from "a software application" to "a screenshot of a webpage" — this is the most common flaw in such prototypes.

Three-Layer Structure

Place the product interface inside the .canvas, with the .stage only responsible for centering and background. No product-related semantics should be on the .stage.

body > .stage          /* Stage: centering + background, does not hold product content */
       └ .canvas       /* Canvas: the interface boundary */
          ├ Product Content (title bar / main area / sidebar...)
          └ .layer      /* Layer group: dialog, drawer, dropdown, toast */
              ├ .scrim   /* Scrim: dim + blur */
              └ .dialog  /* Dialog box itself */

Key Properties (Pseudo-code):

.canvas {
  position: relative;    /* Positioning anchor for layers */
  contain: paint;        /* Clipping + anchors fixed descendants to canvas, essential */
  overflow: hidden;      /* Clip all overflow content */
  isolation: isolate;    /* Stacking and background sampling isolation within canvas */
  container-type: size;  /* Optional: enables internal cqw/cqh for sizing */
  width: min(1440px, 100%);
  height: min(900px, calc(100svh - 2 * var(--stage-pad))); /* Explicit width/height required when using container-type */
}

.layer  { position: absolute; inset: 0; }              /* Relative to canvas, never fixed */
.scrim  { position: absolute; inset: 0;               /* Size equals canvas size → blur range is strictly the canvas */
          background: rgb(8 10 14 / .45); backdrop-filter: blur(10px); }
.dialog { position: relative; width: min(720px, 78cqw); max-height: 82cqh;
          display: flex; flex-direction: column; }
.dialog-body { flex: 1; min-height: 0; overflow: auto; }  /* Only the content area scrolls */

Why contain: paint is Mandatory

Tested (Edge, 1400×1200): With only overflow: hidden, position: fixed elements inside the canvas are still positioned relative to the browser viewport and will escape. Only by adding contain: paint (or transform / filter / will-change: transform / contain: layout) will fixed elements anchor to the canvas and be clipped. container-type: size alone does not work; it must coexist with contain: paint. If cqw/cqh are not needed, container-type can be removed.

Prohibited Actions

• Using position: fixed for layers inside the canvas — the reference frame is the viewport, inherently causing overflow.
• Using vw / vh / dvh for sizing elements inside the canvas — viewport units will inevitably break the canvas boundaries.
• Applying scrims, blurs, or shadows to body, .stage, or elements outside the canvas.
• Using transform: scale() to shrink the entire canvas to "fit" the screen — text, blur, and shadows will all become blurry. The correct approach is min() for sizing + internal adaptation.
• Allowing product semantics (text descriptions, buttons, decorative graphics) to appear on the stage outside the canvas.

Dialog Box Size Specification (Mandatory for Software-type)

Default orientation: wider than tall. Software dialogs should prioritize widescreen designs.

Content Volume	Orientation	Recommended Size (relative to canvas)	Notes
High (tables, charts, long forms, editors)	Wider > Tall, take 16:9 or 4:3	Width 60%–80% canvas width, height ≤ 75% canvas height	Prioritize 16:9 for high content, then 4:3; horizontal space is needed for side-by-side layouts
Medium (settings panel, multi-field form)	Wider > Tall	Width 480–640px, height 320–420px	Keep horizontal but not full-width
Low (confirmation, single field, prompt)	Can be near-square	Width 320–420px, height 220–320px	Vertical is also acceptable; don't force width for the sake of proportion
Vertical List (long list, tree, selector)	Taller > Wide	Width 320–400px, height 60%–80% canvas height	Vertical is an allowed exception: single lists are naturally vertical
Workspace (calendar, kanban, full-screen editor)	Nearly full canvas size	16–24px margin within canvas	Still not fixed, still inside the canvas

Decision order: First ask, "Does the content need to be side-by-side?" If yes, or if horizontal readability is important (tables, charts, code, timelines) → horizontal. Single lists / tree structures / multi-step forms → can be vertical.

Implementation: Use aspect-ratio for proportion, max-height as a fallback, cqw for width, and cqh for height.

.dialog--wide   { width: min(72cqw, 860px); aspect-ratio: 16 / 9; max-height: 78cqh; }  /* High content */
.dialog--panel  { width: min(56cqw, 680px); aspect-ratio: 4 / 3;  max-height: 78cqh; }  /* High content, compact */
.dialog--compact{ width: min(32cqw, 380px); aspect-ratio: 5 / 4; }                        /* Low content */
.dialog--tall   { width: min(30cqw, 360px); height: min(72cqh, 620px); }                   /* Single vertical list */

When content is too tall, max-height applies, and the aspect ratio is allowed to break — this is intentional: it's better to slightly alter the proportion than to have content overflow the canvas.

Other Constraints:

• Dialogs should be centered within the canvas, with at least 24px of whitespace on all sides. Do not touch the edges or extend beyond the canvas.
• When content exceeds the dialog, only .dialog-body should scroll. The header and footer remain fixed.
• The dimming scrim should be rgb(0 0 0 / .35) to rgb(0 0 0 / .5), with a blur of 8–16px. Its scope must be strictly equal to the canvas.
• Dialogs in the same software should have a consistent sizing system (same size for same type). Do not have one 16:9 and another tall and narrow.

III. Design Process

Before starting, read skills/ui-metadata/SKILL.md and write metadata.json into the page directory according to its specifications.

0. Source Declaration for Image Input (imageToUI)

When the user provides "one or more images" as input (i.e., "create UI from images," "recreate from image," "AI replicate 1:1"), you must write an imageToUI field in metadata.json to record the source of the image. This allows the gallery card to reference the original image and lets users click to view it. Handle based on the input type:

• Input is an image URL (starts with http://, https://, or //): Write the link directly into imageToUI, e.g., "imageToUI": "https://dribbble.com/shots/15820088-Furniture-Board-Desktop-concept". The gallery will render an image icon, and clicking it will open the source in a new tab.

• Input is a base64-encoded string or a local image path: The AI must first ask the user to choose between two options, not handle it silently:

  1. Provide the source link address for the image (recommended for public references like Dribbble, Behance, or design file links); or
  2. Allow the AI to copy the image to the ui/<slug>/assets/ directory as a source archive (highly recommended — ensures traceability, offline viewing, and bundled publication with the prototype). Then write the imageToUI as a relative path, e.g., "./assets/source-<slug>.png".

  ⚠️ Prohibited from writing the base64 string or local absolute path directly into imageToUI: Local paths are unreachable on the gallery server, and base64 cannot be opened by a browser, causing the card icon to fail. Do not write this field until the user has made a clear choice.

Field value rules (parsed by the gallery catalog.mjs; see skills/ui-metadata/SKILL.md):

• If it starts with http:// / https:// / //: Treated as an external link; click to navigate.
• Other (e.g., ./assets/..., assets/...): Treated as a resource within the prototype directory; resolved to /prototypes/<slug>/... and opened in a new tab.
• Empty / not written: The card does not display this icon.

1. Clarify the Design Task

Determine the product positioning, user scenarios, core tasks, information priority, and hero section focus. Prepare realistic copy and reasonable data before designing the presentation. Avoid empty placeholder content.

2. Define the Visual Direction

Write a brief design statement clarifying the page's personality. It does not need to be a fixed format or parameter table. At a minimum, think through:

• The overall visual impression and brand character.
• How typography, composition, and information hierarchy express the content.
• How fonts build personality and quality.
• How colors establish atmosphere, identity, and emphasis.
• How icons, graphics, photography, or data visualizations contribute to the expression.
• Whether animation can enhance the experience, and what kind of motion language to adopt.

3. Establish the Design System

Create CSS variables and reusable styles based on the current page's needs. Colors, fonts, sizes, spacing, radii, borders, shadows, and motion effects should follow a consistent design logic, but there is no mandate for a fixed number, value, or ratio of variables.

Do not turn the design system into a parameter table that limits creativity. You can adjust flexibly, but every choice should serve the overall effect.

IV. Visual Design Key Points

4.1 Typography and Composition

• Guide the user's eye to where to look first, then allow them to naturally understand the rest of the information.
• Use type size, weight, font personality, color, position, whitespace, and alignment to establish hierarchy. Do not rely on stacking cards and borders.
• Explore grids, asymmetry, offsets, multi-column layouts, overlapping compositions, immersive layouts, editorial styles, or other approaches based on content.
• Allow for bold size contrasts, unconventional line breaks, and visual tension, but the overall design must be harmonious and legible.
• The page should have rhythm in terms of density, weight, and pace. Avoid giving equal emphasis to every area.
• Do not default to center-aligned, symmetrical, equal-width cards, or identical block arrangements.
• Visual design should help users understand and complete tasks, not just look good in a screenshot.

4.2 The Relationship Between Functionality and Simplicity

Functional completeness and visual beauty must be achieved together. Simplicity is not about removing features.

• Provide the complete capabilities a user would reasonably expect for the product category. Do not arbitrarily delete features to make the page look emptier, simpler, or better in a screenshot.
• Prioritize optimizing information architecture, feature grouping, entry points, interaction flow, and visual expression.
• Use progressive disclosure, contextual actions, quick entry points, icon-based expression, menus, and drawers to reduce visual burden.
• High-frequency features should be easy to discover and use. Low-frequency features can be tucked away but must not be hidden so well that they become undiscoverable.
• Icons can reduce the need for text but must be easy to understand. Important actions should retain text labels when necessary.
• Only delete a feature if the user explicitly asks for extreme minimalism or removal of redundant features, or if a feature is clearly outside the product's scope. Always explain the reason for the deletion.
• Feature entry points, states, and feedback must be complete. Do not create controls that visually exist but have no actual interaction.

4.3 Copy and Information Presentation

• The interface is not a manual. If something can be expressed concisely, do not write lengthy explanations. However, do not sacrifice necessary information just to use fewer words.
• The interface must not contain any text or graphics related to "demo / prototype / simulation." Do not write "Demo Mode," "Sample Data," "Mock Data," "Test Account," or "This is a prototype." Do not use bubble annotations, arrow indicators, numbered marks, teaching highlights, "schematic diagram," "placeholder image," "Lorem ipsum," or "to be added." Every character and icon in the interface must be content that would actually exist in the real product.
• Design the prototype as if it were a live, shipped product interface. Copy should read like real business data. Charts should have credible numerical relationships. Empty states should have the product's own guidance text. Error messages should reflect situations users will actually encounter. Any unimplementable parts (e.g., server-side APIs) should be documented in the delivery notes, not written into the interface.
• For English brands or international pages, use concise terms, short labels, large typography, and visual symbols.
• For trendy or creative pages, use more icons, symbols, graphics, and visualized numbers. For professional tools, prioritize clear information.
• Chinese copy should be natural and accurate. Do not force in English or meaningless abbreviations for decoration.
• Copy should be concrete and informative. Avoid empty marketing jargon, redundant titles, and self-referential guidance.
• For representing status, trends, processes, categories, and proportions, choose between icons, charts, diagrams, or text based on ease of understanding. Do not mandate one specific method.

4.4 Typography (Key Point)

Do not treat the default system font as the final solution. Except for long body text, dense information, or reading-priority scenarios, actively choose fonts.

• When aiming for a premium / design / brand feel, actively search for display fonts or font pairings. Do not fall back on the default font.
• Use different type personalities for headings, wordmarks, key numbers, body text, and auxiliary information, but ensure the combinations are harmonious. Do not use too many fonts.
• English: Geometric sans-serif, humanist sans-serif, Grotesk, serif, narrow/wide, Display, script, experimental — choose based on character. Do not default to Inter.
• Chinese: Modern heiti, song/serif, round, script, expressive display typefaces. Display typefaces should only be used for short headings; prioritize readability for long body text.
• Numbers: Baseline, cap height, width, and alignment should be consistent. Do not use artistic fonts with uneven widths.
• Weight, width, kerning, case, italics, and line breaks can all create design effects. Do not just swap font names.
• Default minimum font size is 12px (a lower bound, not a hard rule). Text embedded in small logos or icons can be smaller. For layout, rely on width-adaptive line wrapping; do not actively force line breaks.

See Section VI, "Resources," for font sources, CDN references, and handling slow loading.

4.5 Color Design

Do not fix a set of color values, color ratios, or accent colors. First, judge the product's personality, then boldly explore suitable color relationships.

Consider sophisticated grays, neutral colors, low-saturation colors, natural colors, warm/cool contrast, brand colors, bright contrasts, dark luxury, monochromatic systems, and other directions. Colors can be restrained or vibrant; the key is harmony, hierarchy, recognizability, and emotional expression.

Colors like sage green, teal, and misty blue (cool-toned cyan/teal) should not be placed at the forefront of color exploration — most AI-generated interfaces today use this palette, making them too easily conflated. Use them only as a last resort.

• Colors should have clear roles. Establish a clear relationship between background, content, text, emphasis, and states.
• The accent color does not need to be fixed; choose based on the brand and page content.
• Gradients, transparency, textures, and lighting effects can be used, but must have a design purpose. Do not treat gradients, glows, or glassmorphism as a default for "premium."
• Color contrast must ensure text and important controls are legible. Do not sacrifice readability for ambiance.
• Do not let the pursuit of low saturation or sophisticated grays cause the page to lose focus, hierarchy, or vitality.

4.6 Icons, Graphics, and Imagery

• Icons, symbols, geometric shapes, illustrations, photography, and data visualizations can all be part of the primary visual language. You are not limited to text and cards.
• Choose a graphic style based on product character. Ensure consistency in line weight, proportion, texture, and expression.
• Functional icons should prioritize easy recognition. Brand or creative graphics can be more distinctive.
• Do not mix icon libraries with significantly different styles. Do not use emoji in place of formal functional icons.
• Graphics must have a communicative purpose: aiding recognition, explaining relationships, conveying state, shaping brand, or enhancing visual tension.
• Images should have clear composition, color logic, and content rationale. Avoid arbitrary collages or irrelevant filler images.

4.7 Details and Polish

• Pay attention to font rendering, kerning, alignment, boundaries, icon proportions, hierarchy, interaction states, and content details.
• Use borders, dividers, shadows, radii, textures, and transparency effects as needed. Do not decorate for decoration's sake.
• Components should be consistent, but also allow for reasonable visual differences in key areas.
• A page is not just about the hero section. Scrolling areas, pop-ups, menus, empty states, and error states must also be fully designed.
• Do not sacrifice real-world readability, usability, or responsiveness for the sake of "looking like a design mockup."

4.8 Borders Must Not Be Clipped (Mandatory for Clipping Containers)

When a component with a border is placed inside a parent container that clips overflow, the parent container's padding must be ≥ the maximum border width of the component in any state. Otherwise, a part of the border will be cut off, causing the edge to feel missing, which looks like a rendering bug.

Mechanism

overflow: hidden clips the container's padding box (content box + padding):

• A container's padding can absorb child element outward overflow → if enough padding is left, the border will be visible.
• However, box-shadow outward spread and outline extend outside the border box, and padding cannot fix that.

Solutions (by Priority)

1. Global box-sizing: border-box (preferred) — eliminates the root cause of overflow:

*, *::before, *::after { box-sizing: border-box; }

2. Leave border margin in the parent container — padding ≥ border-width + 1px. Tested: With a 4px border, padding ≤ 6px causes the right border to be clipped; ≥ 7px keeps it intact. Having it exactly equal to the border width (4px) will still result in clipping; be sure to leave a margin.

3. Use inset box-shadow instead of a border — takes no space, never gets clipped:

.card { border: 0; box-shadow: inset 0 0 0 1px var(--line); }

Prohibited Actions

• Using outward-spreading box-shadow / outline as a permanent border (drawn outside the border box, easily clipped).
• Using negative margins to merge adjacent borders (will be cut off when there's clipping).

When Border Appears Only on Hover

Most common scenario: The default state looks fine, but on hover, a part of the border disappears. Use a transparent border to occupy the space, then change only the color. This avoids jumping or overflow on hover:

.item { border: 1px solid transparent; transition: border-color .18s; }
.item:hover { border-color: var(--line); }

Check each component; see Section IX, Self-Check, item 13.

4.9 Unify Native Control Styles

Browser-native controls (scrollbars, select dropdowns, input/textarea focus states, checkbox/radio/range accent colors, date pickers, etc.) are rendered by the system and look out of sync with custom UI. This is the most overlooked flaw that ruins the cohesive feel of a prototype. Any native control that appears on the page must be converged into the product's visual language, not left with the system default appearance.

• Scrollbar: Use ::-webkit-scrollbar* for WebKit and scrollbar-width/scrollbar-color for Firefox to unify the track and thumb colors, radius, and hover states. Apply only to local scrolling areas. Keep the width restrained (around 8–10px). Do not globally thicken.
• Inputs: Use appearance: none on input/textarea/select to implement custom borders, radii, and focus-visible states. Do not use the browser's default border and inner shadow.
• select Dropdown: The native option panel cannot be deeply customized. Use appearance: none + a custom drawn dropdown arrow, and use --control-* CSS variables to keep consistency with buttons and input fields. For search, grouping, or custom highlighting, replace native select with a custom-drawn dropdown.
• Accent Color: For checkbox/radio/range/progress, use accent-color: var(--brand). Do not keep the system blue.
• Composite Inputs: Panels for color, date, time, etc., cannot be customized. For important products, use custom-drawn inputs or restrict input format.

Key point: Padding, font size, radius, and focus states of all native controls should be assigned to design variables (e.g., --control-bg/--control-border/--control-radius/--control-focus). These should maintain the same visual language as cards and buttons, eliminating the "two-language system."

V. Animation Design and Implementation

Animation is a part of UI design. It's not just about adding hover effects to buttons. Based on the product's personality and user needs, actively determine the role of animation in the interface.

5.1 First, Determine Animation Needs

• If the user explicitly requests excellent animation, advanced motion effects, smooth animation, cool, flashy, immersive, cinematic, dynamic visuals, or similar requirements, treat animation as a key design element. Proactively use professional animation libraries like GSAP to implement complex effects. Do not just use simple CSS transitions.
• For brand websites, creative showcases, product launches, portfolios, interactive storytelling, or other pages suited for dynamic expression, actively design rhythmic entrances, scroll-triggered narratives, parallax effects, text animations, graphic morphing, mask reveals, layered motion, and coherent transitions.
• For professional tools, admin panels, and high-frequency operation interfaces, animation should help clarify state, establish spatial relationships, and provide feedback. It can be refined and smooth, but must not hinder efficiency.
• If the user has not explicitly requested complex animation, design moderately based on the product's character. Do not add meaningless effects just to show off.
• Do not make all elements do the same fade-in-up motion, nor allow every component to perform independently.

5.2 Animation Quality

• Avoid mechanical linear motion: Spatial movement, scaling, and interface transitions should typically use natural acceleration, deceleration, asymmetric easing, or spring effects. Linear is only suitable for constant-speed rotation, progress bars, continuous scrolling, and other specific scenarios where it is truly needed.
• Use quality easing curves: Choose ease-out, ease-in-out, power, expo, back, spring, and other curves based on motion distance, element mass, and context. Be restrained with exaggerated elastic effects to avoid cheap-looking bouncing.
• Incorporate damping where appropriate: Large panels, overlays, drag operations, following animations, magnetic snapping, and spatial transitions can have a sense of inertia, damping, bounce back, or spring for a more natural feel.
• Motion should have causality: Entrances, exits, expansions, collapses, switches, drags, and state changes should align with the user's intuition about space and objects.
• Orchestrate with rhythm: Use staggered, overlapping, sequential, and layered motions. There must be a clear primary focus; not all elements should move simultaneously and chaotically.
• Animations should respond to content and operations: Avoid meaningless perpetual loops, continuously floating elements, or background animations that distract the user.
• Prioritize performance: Favor compositor-friendly properties like transform and opacity. Use complex filters, blurs, and large-area real-time effects cautiously to avoid dropped frames.

5.3 Prioritize gsap-skills and GSAP

Before doing GSAP animations, check: If the current system/agent already has the gsap-skills skill installed, try to use it for animation design to get the latest API and syntax. If it is not installed, proactively ask the user for confirmation, recommending they run npx skills add https://github.com/greensock/gsap-skills to install it (the user decides). Then use it for animation design. Do not rely on memory to write outdated GSAP syntax.

For complex animations (narrative entrances, scroll-driven effects, timeline orchestration, interactive drag, multi-element coordination), prioritize GSAP:

• Use Timeline to orchestrate a group of animations (labels, overlaps, nesting, callbacks) rather than a bunch of unrelated delays.
• For scroll-driven effects, use ScrollTrigger. For smooth scrolling, word-by-word effects, path animations, flip effects, etc., import plugins as needed.
• Simple state feedback can be done with CSS transitions/keyframes. Do not import a library when not needed.
• Import via CDN (e.g., gsap@3) following the technical conventions in Section VIII. Manage animations in a modular way to facilitate play/pause/reverse/reset/cleanup.

5.4 Continuous Operations, Interruption, and Recovery

Interactive animations must account for continuous user operations: When a new operation arrives, transition smoothly from the current visual state, without flashing, jumping back to the initial position, or causing the animation state to become out of sync with the actual UI.

• Reversible states (expand/collapse, on/off): Reuse the same Timeline, use reverse() / play() for a natural reversal. Do not create a new one.
• Continuously changing target values (drag, cursor follow): Use gsap.quickTo() to keep the motion perpetually following the latest input. Do not create a new tween each time.
• Multi-sequence transitions: Use Timeline / nested Timelines / callbacks / state machines for unified management. Do not create independent animations that compete for the same property.
• Based on the interaction semantics, distinguish between "continue the sequence / play in reverse / transition to a new target / animate another property in parallel." Do not always append or always kill. Only overwrite properties that truly conflict (GSAP uses overwrite: "auto"; do not randomly kill() or set a global overwrite: true).

5.5 Accessibility and Performance

• Respect prefers-reduced-motion: reduce. Provide a solution that reduces motion effects. When reducing motion, information and functionality must remain complete.
• Do not use animation to hide critical content or delay information the user needs immediately.
• Avoid high-frequency flashing, rapid large-scale scaling, and parallax effects that may cause discomfort.
• Scroll animations must not interfere with normal scrolling, keyboard navigation, or touch operations.
• When a page exits or a component is destroyed, properly clean up event listeners, ScrollTrigger instances, and animation instances that are no longer needed.
• Core content on the hero section must not depend on the animation library being fully loaded before it is displayed.

References:

• GSAP Documentation
• GSAP Timeline
• GSAP Tween / overwrite
• Apple HIG Motion
• Material Motion

VI. Assets

Unified use of tools/resource-getter/get.py to fetch assets. Do not manually piece together site URLs or scatter a collection of unknown external links in the page. See tools/resource-getter/README.md for the full asset source matrix, licenses, and troubleshooting.

Selection Priority

1. Transparent Vector Illustrations: unDraw / Storyset / DiceBear / Doodle Ipsum
2. Isolated PNG Images: Pixabay (--transparent) / pngimg
3. Photography: Pixabay / Picsum / Unsplash / Pexels
4. Hand-drawn SVGs (geometric, decorative, charts)
5. AI-generated Images (last resort; see rules below)

Default to hotlinking; download if slow. The auto mode of get measures TTFB: if > 0.9s or read time > 2.5s, it is considered slow and must be downloaded to ui/<page>/assets/. Even if fast, do not cram twenty remote large images into the hero section.

...

[truncated for translation]