engine: sync editor rendering and ui changes

2026-04-08 16:09:15 +08:00
parent 31756847ab
commit 162f1cc12e
153 changed files with 4454 additions and 2990 deletions
--- a/tests/UI/Core/integration/CMakeLists.txt
+++ b/tests/UI/Core/integration/CMakeLists.txt
@@ -1,6 +1,7 @@
 add_subdirectory(shared)
 add_subdirectory(input)
 add_subdirectory(layout)
+add_subdirectory(render)
 add_subdirectory(style)
 add_subdirectory(text)

@@ -8,6 +9,7 @@ add_custom_target(core_ui_integration_tests
    DEPENDS
        core_ui_input_integration_tests
        core_ui_layout_integration_tests
+        core_ui_render_integration_tests
        core_ui_style_integration_tests
        core_ui_text_integration_tests
 )
--- a/tests/UI/Core/integration/render/CMakeLists.txt
+++ b/tests/UI/Core/integration/render/CMakeLists.txt
@@ -0,0 +1,6 @@
+add_subdirectory(draw_primitives_basic)
+
+add_custom_target(core_ui_render_integration_tests
+    DEPENDS
+        core_ui_render_draw_primitives_basic_validation
+)
--- a/tests/UI/Core/integration/render/draw_primitives_basic/CMakeLists.txt
+++ b/tests/UI/Core/integration/render/draw_primitives_basic/CMakeLists.txt
@@ -0,0 +1,27 @@
+add_executable(core_ui_render_draw_primitives_basic_validation WIN32
+    main.cpp
+)
+
+target_include_directories(core_ui_render_draw_primitives_basic_validation PRIVATE
+    ${CMAKE_SOURCE_DIR}/tests/UI/Core/integration/shared/src
+    ${CMAKE_SOURCE_DIR}/engine/include
+)
+
+target_compile_definitions(core_ui_render_draw_primitives_basic_validation PRIVATE
+    UNICODE
+    _UNICODE
+)
+
+if(MSVC)
+    target_compile_options(core_ui_render_draw_primitives_basic_validation PRIVATE /utf-8 /FS)
+    set_property(TARGET core_ui_render_draw_primitives_basic_validation PROPERTY
+        MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
+endif()
+
+target_link_libraries(core_ui_render_draw_primitives_basic_validation PRIVATE
+    core_ui_integration_host
+)
+
+set_target_properties(core_ui_render_draw_primitives_basic_validation PROPERTIES
+    OUTPUT_NAME "XCUICoreRenderDrawPrimitivesBasicValidation"
+)
--- a/tests/UI/Core/integration/render/draw_primitives_basic/main.cpp
+++ b/tests/UI/Core/integration/render/draw_primitives_basic/main.cpp
@@ -0,0 +1,465 @@
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+
+#include "AutoScreenshot.h"
+#include "NativeRenderer.h"
+
+#include <XCEngine/UI/DrawData.h>
+
+#include <windows.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstdlib>
+#include <filesystem>
+#include <string>
+
+#ifndef XCENGINE_CORE_UI_TESTS_REPO_ROOT
+#define XCENGINE_CORE_UI_TESTS_REPO_ROOT "."
+#endif
+
+namespace {
+
+using XCEngine::Tests::CoreUI::Host::AutoScreenshotController;
+using XCEngine::Tests::CoreUI::Host::NativeRenderer;
+using XCEngine::UI::UIColor;
+using XCEngine::UI::UIDrawData;
+using XCEngine::UI::UIDrawList;
+using XCEngine::UI::UILinearGradientDirection;
+using XCEngine::UI::UIPoint;
+using XCEngine::UI::UIRect;
+
+constexpr const wchar_t* kWindowClassName = L"XCUICoreRenderDrawPrimitivesBasicValidation";
+constexpr const wchar_t* kWindowTitle = L"XCUI Core | Draw Primitives Basic";
+
+constexpr UIColor kWindowColor(0.09f, 0.09f, 0.09f, 1.0f);
+constexpr UIColor kCardColor(0.15f, 0.15f, 0.15f, 1.0f);
+constexpr UIColor kCardBorderColor(0.26f, 0.26f, 0.26f, 1.0f);
+constexpr UIColor kTitleColor(0.95f, 0.95f, 0.95f, 1.0f);
+constexpr UIColor kBodyColor(0.82f, 0.82f, 0.82f, 1.0f);
+constexpr UIColor kMutedColor(0.64f, 0.64f, 0.64f, 1.0f);
+constexpr UIColor kCheckerLight(0.74f, 0.74f, 0.74f, 1.0f);
+constexpr UIColor kCheckerDark(0.46f, 0.46f, 0.46f, 1.0f);
+
+struct ScenarioLayout {
+    UIRect introRect = {};
+    UIRect stateRect = {};
+    UIRect previewRect = {};
+    UIRect gradientRowRect = {};
+    UIRect svRect = {};
+    UIRect hueStripRect = {};
+    UIRect closeButtonRect = {};
+    UIRect alphaPreviewRect = {};
+};
+
+std::filesystem::path ResolveRepoRootPath() {
+    std::string root = XCENGINE_CORE_UI_TESTS_REPO_ROOT;
+    if (root.size() >= 2u && root.front() == '"' && root.back() == '"') {
+        root = root.substr(1u, root.size() - 2u);
+    }
+    return std::filesystem::path(root).lexically_normal();
+}
+
+ScenarioLayout BuildScenarioLayout(float width, float height) {
+    constexpr float margin = 20.0f;
+    constexpr float gap = 16.0f;
+    constexpr float leftWidth = 430.0f;
+
+    ScenarioLayout layout = {};
+    layout.introRect = UIRect(margin, margin, leftWidth, 220.0f);
+    layout.stateRect = UIRect(
+        margin,
+        layout.introRect.y + layout.introRect.height + gap,
+        leftWidth,
+        (std::max)(240.0f, height - layout.introRect.height - gap - margin * 2.0f));
+    layout.previewRect = UIRect(
+        margin * 2.0f + leftWidth,
+        margin,
+        (std::max)(460.0f, width - leftWidth - margin * 3.0f),
+        height - margin * 2.0f);
+
+    const float contentX = layout.previewRect.x + 24.0f;
+    const float contentY = layout.previewRect.y + 58.0f;
+    layout.gradientRowRect = UIRect(contentX, contentY, 360.0f, 24.0f);
+    layout.svRect = UIRect(contentX, contentY + 52.0f, 208.0f, 208.0f);
+    layout.hueStripRect = UIRect(layout.svRect.x + layout.svRect.width + 18.0f, layout.svRect.y, 28.0f, layout.svRect.height);
+    layout.alphaPreviewRect = UIRect(layout.hueStripRect.x + layout.hueStripRect.width + 26.0f, layout.svRect.y, 96.0f, 48.0f);
+    layout.closeButtonRect = UIRect(
+        layout.previewRect.x + layout.previewRect.width - 42.0f,
+        layout.previewRect.y + 18.0f,
+        20.0f,
+        20.0f);
+    return layout;
+}
+
+bool ShouldAutoCaptureOnStartup() {
+    const char* value = std::getenv("XCUI_AUTO_CAPTURE_ON_STARTUP");
+    return value != nullptr && value[0] == '1' && value[1] == '\0';
+}
+
+void DrawCard(UIDrawList& drawList, const UIRect& rect) {
+    drawList.AddFilledRect(rect, kCardColor, 8.0f);
+    drawList.AddRectOutline(rect, kCardBorderColor, 1.0f, 8.0f);
+}
+
+void DrawCheckerboard(UIDrawList& drawList, const UIRect& rect, float cellSize) {
+    const int columns = static_cast<int>(std::ceil(rect.width / cellSize));
+    const int rows = static_cast<int>(std::ceil(rect.height / cellSize));
+    for (int row = 0; row < rows; ++row) {
+        for (int column = 0; column < columns; ++column) {
+            const bool light = ((row + column) & 1) == 0;
+            const float x = rect.x + cellSize * static_cast<float>(column);
+            const float y = rect.y + cellSize * static_cast<float>(row);
+            drawList.AddFilledRect(
+                UIRect(
+                    x,
+                    y,
+                    (std::min)(cellSize, rect.x + rect.width - x),
+                    (std::min)(cellSize, rect.y + rect.height - y)),
+                light ? kCheckerLight : kCheckerDark);
+        }
+    }
+}
+
+class ScenarioApp {
+public:
+    int Run(HINSTANCE hInstance, int nCmdShow) {
+        if (!Initialize(hInstance, nCmdShow)) {
+            Shutdown();
+            return 1;
+        }
+
+        MSG message = {};
+        while (message.message != WM_QUIT) {
+            if (PeekMessageW(&message, nullptr, 0U, 0U, PM_REMOVE)) {
+                TranslateMessage(&message);
+                DispatchMessageW(&message);
+                continue;
+            }
+
+            RenderFrame();
+            Sleep(8);
+        }
+
+        Shutdown();
+        return static_cast<int>(message.wParam);
+    }
+
+private:
+    static LRESULT CALLBACK WndProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam) {
+        if (message == WM_NCCREATE) {
+            const auto* createStruct = reinterpret_cast<CREATESTRUCTW*>(lParam);
+            auto* app = reinterpret_cast<ScenarioApp*>(createStruct->lpCreateParams);
+            SetWindowLongPtrW(hwnd, GWLP_USERDATA, reinterpret_cast<LONG_PTR>(app));
+            return TRUE;
+        }
+
+        auto* app = reinterpret_cast<ScenarioApp*>(GetWindowLongPtrW(hwnd, GWLP_USERDATA));
+        switch (message) {
+        case WM_SIZE:
+            if (app != nullptr && wParam != SIZE_MINIMIZED) {
+                app->m_renderer.Resize(static_cast<UINT>(LOWORD(lParam)), static_cast<UINT>(HIWORD(lParam)));
+            }
+            return 0;
+        case WM_KEYDOWN:
+        case WM_SYSKEYDOWN:
+            if (app != nullptr) {
+                if (wParam == VK_F12) {
+                    app->m_autoScreenshot.RequestCapture("manual_f12");
+                    app->m_lastStatus = "已请求截图，输出到 captures/latest.png";
+                    InvalidateRect(hwnd, nullptr, FALSE);
+                    return 0;
+                }
+                if (wParam == 'R') {
+                    app->ResetScenario();
+                    InvalidateRect(hwnd, nullptr, FALSE);
+                    return 0;
+                }
+            }
+            break;
+        case WM_PAINT:
+            if (app != nullptr) {
+                PAINTSTRUCT paintStruct = {};
+                BeginPaint(hwnd, &paintStruct);
+                app->RenderFrame();
+                EndPaint(hwnd, &paintStruct);
+                return 0;
+            }
+            break;
+        case WM_ERASEBKGND:
+            return 1;
+        case WM_DESTROY:
+            if (app != nullptr) {
+                app->m_hwnd = nullptr;
+            }
+            PostQuitMessage(0);
+            return 0;
+        default:
+            break;
+        }
+
+        return DefWindowProcW(hwnd, message, wParam, lParam);
+    }
+
+    bool Initialize(HINSTANCE hInstance, int nCmdShow) {
+        WNDCLASSEXW windowClass = {};
+        windowClass.cbSize = sizeof(windowClass);
+        windowClass.style = CS_HREDRAW | CS_VREDRAW;
+        windowClass.lpfnWndProc = &ScenarioApp::WndProc;
+        windowClass.hInstance = hInstance;
+        windowClass.hCursor = LoadCursorW(nullptr, IDC_ARROW);
+        windowClass.lpszClassName = kWindowClassName;
+
+        m_windowClassAtom = RegisterClassExW(&windowClass);
+        if (m_windowClassAtom == 0) {
+            return false;
+        }
+
+        m_hwnd = CreateWindowExW(
+            0,
+            kWindowClassName,
+            kWindowTitle,
+            WS_OVERLAPPEDWINDOW | WS_VISIBLE,
+            CW_USEDEFAULT,
+            CW_USEDEFAULT,
+            1440,
+            920,
+            nullptr,
+            nullptr,
+            hInstance,
+            this);
+        if (m_hwnd == nullptr || !m_renderer.Initialize(m_hwnd)) {
+            return false;
+        }
+
+        ShowWindow(m_hwnd, nCmdShow);
+        UpdateWindow(m_hwnd);
+
+        m_captureRoot =
+            ResolveRepoRootPath() / "tests/UI/Core/integration/render/draw_primitives_basic/captures";
+        m_autoScreenshot.Initialize(m_captureRoot);
+        ResetScenario();
+        if (ShouldAutoCaptureOnStartup()) {
+            m_autoScreenshot.RequestCapture("startup");
+            m_lastStatus = "已请求启动截图";
+        }
+        return true;
+    }
+
+    void Shutdown() {
+        m_autoScreenshot.Shutdown();
+        m_renderer.Shutdown();
+        if (m_hwnd != nullptr && IsWindow(m_hwnd)) {
+            DestroyWindow(m_hwnd);
+        }
+        if (m_windowClassAtom != 0) {
+            UnregisterClassW(kWindowClassName, GetModuleHandleW(nullptr));
+        }
+    }
+
+    void ResetScenario() {
+        m_lastStatus = "已重置到默认 Draw Primitives 场景";
+    }
+
+    void RenderFrame() {
+        RECT clientRect = {};
+        GetClientRect(m_hwnd, &clientRect);
+        const float width = static_cast<float>((std::max)(1L, clientRect.right - clientRect.left));
+        const float height = static_cast<float>((std::max)(1L, clientRect.bottom - clientRect.top));
+        const ScenarioLayout layout = BuildScenarioLayout(width, height);
+
+        UIDrawData drawData = {};
+        UIDrawList& drawList = drawData.EmplaceDrawList("CoreDrawPrimitives");
+        drawList.AddFilledRect(UIRect(0.0f, 0.0f, width, height), kWindowColor);
+
+        DrawCard(drawList, layout.introRect);
+        DrawCard(drawList, layout.stateRect);
+        DrawCard(drawList, layout.previewRect);
+
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 14.0f),
+            "这个测试在验证什么功能？",
+            kTitleColor,
+            17.0f);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 40.0f),
+            "只验证 UI Core 新增的 linear gradient / line / circle primitive 的真实渲染。",
+            kMutedColor,
+            12.0f);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 74.0f),
+            "1. 右侧横向和纵向 gradient 不能出现纯色退化或明显断层。",
+            kBodyColor,
+            12.0f);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 96.0f),
+            "2. SV 方块应由两层 gradient 叠加；白到主色、再由透明到黑。",
+            kBodyColor,
+            12.0f);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 118.0f),
+            "3. 手柄必须是圆形；关闭按钮 X 和标尺都必须是 line，不准用文字假冒。",
+            kBodyColor,
+            12.0f);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 140.0f),
+            "4. 按 F12 手动截图；设置 XCUI_AUTO_CAPTURE_ON_STARTUP=1 可自动截图；按 R 重置。",
+            kBodyColor,
+            12.0f);
+
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 14.0f),
+            "状态摘要",
+            kTitleColor,
+            17.0f);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 44.0f),
+            "Primitive: FilledRectLinearGradient / Line / FilledCircle / CircleOutline",
+            kBodyColor,
+            12.0f);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 68.0f),
+            "Preview: Gradient Row + SV Square + Hue Strip + Close Button + Alpha Preview",
+            kBodyColor,
+            12.0f);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 92.0f),
+            "Result: " + m_lastStatus,
+            kBodyColor,
+            12.0f);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 116.0f),
+            m_autoScreenshot.GetLastCaptureSummary().empty()
+                ? std::string("Capture: F12 -> tests/UI/Core/integration/render/draw_primitives_basic/captures/")
+                : ("Capture: " + m_autoScreenshot.GetLastCaptureSummary()),
+            kMutedColor,
+            12.0f);
+        if (!m_autoScreenshot.GetLastCaptureError().empty()) {
+            drawList.AddText(
+                UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 140.0f),
+                "Error: " + m_autoScreenshot.GetLastCaptureError(),
+                UIColor(0.95f, 0.56f, 0.56f, 1.0f),
+                12.0f);
+        }
+
+        drawList.AddText(
+            UIPoint(layout.previewRect.x + 16.0f, layout.previewRect.y + 14.0f),
+            "Draw Primitives 预览",
+            kTitleColor,
+            17.0f);
+        drawList.AddText(
+            UIPoint(layout.previewRect.x + 16.0f, layout.previewRect.y + 36.0f),
+            "这里不验证 ColorField 业务，只验证底层绘制 primitive 的像素效果。",
+            kMutedColor,
+            12.0f);
+
+        drawList.AddFilledRectLinearGradient(
+            layout.gradientRowRect,
+            UIColor(0.95f, 0.27f, 0.27f, 1.0f),
+            UIColor(0.14f, 0.72f, 0.94f, 1.0f),
+            UILinearGradientDirection::Horizontal,
+            3.0f);
+        drawList.AddRectOutline(layout.gradientRowRect, UIColor(0.12f, 0.12f, 0.12f, 1.0f), 1.0f, 3.0f);
+        const float markerX = layout.gradientRowRect.x + layout.gradientRowRect.width * 0.68f;
+        drawList.AddLine(
+            UIPoint(markerX, layout.gradientRowRect.y - 2.0f),
+            UIPoint(markerX, layout.gradientRowRect.y + layout.gradientRowRect.height + 2.0f),
+            UIColor(1.0f, 1.0f, 1.0f, 1.0f),
+            2.0f);
+
+        drawList.AddFilledRectLinearGradient(
+            layout.svRect,
+            UIColor(1.0f, 1.0f, 1.0f, 1.0f),
+            UIColor(0.23f, 0.64f, 0.98f, 1.0f),
+            UILinearGradientDirection::Horizontal,
+            2.0f);
+        drawList.AddFilledRectLinearGradient(
+            layout.svRect,
+            UIColor(0.0f, 0.0f, 0.0f, 0.0f),
+            UIColor(0.0f, 0.0f, 0.0f, 1.0f),
+            UILinearGradientDirection::Vertical,
+            2.0f);
+        drawList.AddRectOutline(layout.svRect, UIColor(0.12f, 0.12f, 0.12f, 1.0f), 1.0f, 2.0f);
+        const UIPoint svHandle(
+            layout.svRect.x + layout.svRect.width * 0.72f,
+            layout.svRect.y + layout.svRect.height * 0.34f);
+        drawList.AddFilledCircle(svHandle, 5.0f, UIColor(1.0f, 1.0f, 1.0f, 0.15f));
+        drawList.AddCircleOutline(svHandle, 7.0f, UIColor(1.0f, 1.0f, 1.0f, 1.0f), 2.0f);
+        drawList.AddCircleOutline(svHandle, 8.0f, UIColor(0.0f, 0.0f, 0.0f, 0.35f), 1.0f);
+
+        const float segmentHeight = layout.hueStripRect.height / 6.0f;
+        const UIColor hueStops[7] = {
+            UIColor(1.0f, 0.0f, 0.0f, 1.0f),
+            UIColor(1.0f, 1.0f, 0.0f, 1.0f),
+            UIColor(0.0f, 1.0f, 0.0f, 1.0f),
+            UIColor(0.0f, 1.0f, 1.0f, 1.0f),
+            UIColor(0.0f, 0.0f, 1.0f, 1.0f),
+            UIColor(1.0f, 0.0f, 1.0f, 1.0f),
+            UIColor(1.0f, 0.0f, 0.0f, 1.0f)
+        };
+        for (int index = 0; index < 6; ++index) {
+            drawList.AddFilledRectLinearGradient(
+                UIRect(
+                    layout.hueStripRect.x,
+                    layout.hueStripRect.y + segmentHeight * static_cast<float>(index),
+                    layout.hueStripRect.width,
+                    segmentHeight + 1.0f),
+                hueStops[index],
+                hueStops[index + 1],
+                UILinearGradientDirection::Vertical,
+                0.0f);
+        }
+        drawList.AddRectOutline(layout.hueStripRect, UIColor(0.12f, 0.12f, 0.12f, 1.0f), 1.0f, 2.0f);
+        const float hueMarkerY = layout.hueStripRect.y + layout.hueStripRect.height * 0.44f;
+        drawList.AddLine(
+            UIPoint(layout.hueStripRect.x - 4.0f, hueMarkerY),
+            UIPoint(layout.hueStripRect.x + layout.hueStripRect.width + 4.0f, hueMarkerY),
+            UIColor(1.0f, 1.0f, 1.0f, 1.0f),
+            2.0f);
+
+        DrawCheckerboard(drawList, layout.alphaPreviewRect, 6.0f);
+        drawList.AddFilledRect(
+            UIRect(
+                layout.alphaPreviewRect.x,
+                layout.alphaPreviewRect.y,
+                layout.alphaPreviewRect.width,
+                layout.alphaPreviewRect.height),
+            UIColor(0.23f, 0.64f, 0.98f, 0.55f),
+            2.0f);
+        drawList.AddRectOutline(layout.alphaPreviewRect, UIColor(0.12f, 0.12f, 0.12f, 1.0f), 1.0f, 2.0f);
+
+        drawList.AddRectOutline(layout.closeButtonRect, UIColor(0.38f, 0.38f, 0.38f, 1.0f), 1.0f, 2.0f);
+        drawList.AddLine(
+            UIPoint(layout.closeButtonRect.x + 5.0f, layout.closeButtonRect.y + 5.0f),
+            UIPoint(layout.closeButtonRect.x + layout.closeButtonRect.width - 5.0f, layout.closeButtonRect.y + layout.closeButtonRect.height - 5.0f),
+            UIColor(0.92f, 0.92f, 0.92f, 1.0f),
+            1.5f);
+        drawList.AddLine(
+            UIPoint(layout.closeButtonRect.x + layout.closeButtonRect.width - 5.0f, layout.closeButtonRect.y + 5.0f),
+            UIPoint(layout.closeButtonRect.x + 5.0f, layout.closeButtonRect.y + layout.closeButtonRect.height - 5.0f),
+            UIColor(0.92f, 0.92f, 0.92f, 1.0f),
+            1.5f);
+
+        const bool framePresented = m_renderer.Render(drawData);
+        m_autoScreenshot.CaptureIfRequested(
+            m_renderer,
+            drawData,
+            static_cast<unsigned int>(width),
+            static_cast<unsigned int>(height),
+            framePresented);
+    }
+
+    HWND m_hwnd = nullptr;
+    ATOM m_windowClassAtom = 0;
+    NativeRenderer m_renderer = {};
+    AutoScreenshotController m_autoScreenshot = {};
+    std::filesystem::path m_captureRoot = {};
+    std::string m_lastStatus = "等待检查";
+};
+
+} // namespace
+
+int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE, LPWSTR, int nCmdShow) {
+    return ScenarioApp().Run(hInstance, nCmdShow);
+}
--- a/tests/UI/Core/integration/shared/src/NativeRenderer.cpp
+++ b/tests/UI/Core/integration/shared/src/NativeRenderer.cpp
@@ -12,12 +12,57 @@ D2D1_RECT_F ToD2DRect(const ::XCEngine::UI::UIRect& rect) {
    return D2D1::RectF(rect.x, rect.y, rect.x + rect.width, rect.y + rect.height);
 }

+D2D1_COLOR_F ToD2DColorValue(const ::XCEngine::UI::UIColor& color) {
+    return D2D1::ColorF(color.r, color.g, color.b, color.a);
+}
+
 std::string HrToString(const char* operation, HRESULT hr) {
    char buffer[128] = {};
    sprintf_s(buffer, "%s failed with hr=0x%08X.", operation, static_cast<unsigned int>(hr));
    return buffer;
 }

+void FillLinearGradientRect(
+    ID2D1RenderTarget& renderTarget,
+    const ::XCEngine::UI::UIDrawCommand& command) {
+    const D2D1_RECT_F rect = ToD2DRect(command.rect);
+    const D2D1_GRADIENT_STOP stops[2] = {
+        D2D1::GradientStop(0.0f, ToD2DColorValue(command.color)),
+        D2D1::GradientStop(1.0f, ToD2DColorValue(command.secondaryColor))
+    };
+
+    Microsoft::WRL::ComPtr<ID2D1GradientStopCollection> stopCollection;
+    if (FAILED(renderTarget.CreateGradientStopCollection(
+            stops,
+            2u,
+            stopCollection.ReleaseAndGetAddressOf()))) {
+        return;
+    }
+
+    const D2D1_POINT_2F startPoint = D2D1::Point2F(rect.left, rect.top);
+    const D2D1_POINT_2F endPoint =
+        command.gradientDirection == ::XCEngine::UI::UILinearGradientDirection::Vertical
+            ? D2D1::Point2F(rect.left, rect.bottom)
+            : D2D1::Point2F(rect.right, rect.top);
+
+    Microsoft::WRL::ComPtr<ID2D1LinearGradientBrush> gradientBrush;
+    if (FAILED(renderTarget.CreateLinearGradientBrush(
+            D2D1::LinearGradientBrushProperties(startPoint, endPoint),
+            stopCollection.Get(),
+            gradientBrush.ReleaseAndGetAddressOf()))) {
+        return;
+    }
+
+    if (command.rounding > 0.0f) {
+        renderTarget.FillRoundedRectangle(
+            D2D1::RoundedRect(rect, command.rounding, command.rounding),
+            gradientBrush.Get());
+        return;
+    }
+
+    renderTarget.FillRectangle(rect, gradientBrush.Get());
+}
+
 } // namespace

 bool NativeRenderer::Initialize(HWND hwnd) {
@@ -345,6 +390,9 @@ void NativeRenderer::RenderCommand(
        }
        break;
    }
+    case ::XCEngine::UI::UIDrawCommandType::FilledRectLinearGradient:
+        FillLinearGradientRect(renderTarget, command);
+        break;
    case ::XCEngine::UI::UIDrawCommandType::RectOutline: {
        const D2D1_RECT_F rect = ToD2DRect(command.rect);
        const float thickness = command.thickness > 0.0f ? command.thickness : 1.0f;
@@ -358,6 +406,34 @@ void NativeRenderer::RenderCommand(
        }
        break;
    }
+    case ::XCEngine::UI::UIDrawCommandType::Line:
+        renderTarget.DrawLine(
+            D2D1::Point2F(command.position.x, command.position.y),
+            D2D1::Point2F(command.uvMin.x, command.uvMin.y),
+            &solidBrush,
+            command.thickness > 0.0f ? command.thickness : 1.0f);
+        break;
+    case ::XCEngine::UI::UIDrawCommandType::FilledCircle:
+        if (command.radius > 0.0f) {
+            renderTarget.FillEllipse(
+                D2D1::Ellipse(
+                    D2D1::Point2F(command.position.x, command.position.y),
+                    command.radius,
+                    command.radius),
+                &solidBrush);
+        }
+        break;
+    case ::XCEngine::UI::UIDrawCommandType::CircleOutline:
+        if (command.radius > 0.0f) {
+            renderTarget.DrawEllipse(
+                D2D1::Ellipse(
+                    D2D1::Point2F(command.position.x, command.position.y),
+                    command.radius,
+                    command.radius),
+                &solidBrush,
+                command.thickness > 0.0f ? command.thickness : 1.0f);
+        }
+        break;
    case ::XCEngine::UI::UIDrawCommandType::Text: {
        if (command.text.empty()) {
            break;
@@ -452,7 +528,7 @@ IDWriteTextFormat* NativeRenderer::GetTextFormat(float fontSize) {
 }

 D2D1_COLOR_F NativeRenderer::ToD2DColor(const ::XCEngine::UI::UIColor& color) {
-    return D2D1::ColorF(color.r, color.g, color.b, color.a);
+    return ToD2DColorValue(color);
 }

 std::wstring NativeRenderer::Utf8ToWide(std::string_view text) {
--- a/tests/UI/Core/unit/CMakeLists.txt
+++ b/tests/UI/Core/unit/CMakeLists.txt
@@ -3,12 +3,14 @@ set(CORE_UI_TEST_SOURCES
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_input_modifier_tracker.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_layout_engine.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_core.cpp
+    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_draw_data.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_expansion_model.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_flat_hierarchy_helpers.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_input_dispatcher.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_keyboard_navigation_model.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_popup_overlay_model.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_property_edit_model.cpp
+    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_scroll_model.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_selection_model.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_style_system.cpp
    ${CMAKE_SOURCE_DIR}/tests/UI/Core/unit/test_ui_shortcut_scope.cpp
--- a/tests/UI/Core/unit/test_ui_draw_data.cpp
+++ b/tests/UI/Core/unit/test_ui_draw_data.cpp
@@ -0,0 +1,82 @@
+#include <gtest/gtest.h>
+
+#include <XCEngine/UI/DrawData.h>
+
+namespace {
+
+using XCEngine::UI::UIColor;
+using XCEngine::UI::UIDrawCommandType;
+using XCEngine::UI::UIDrawData;
+using XCEngine::UI::UIDrawList;
+using XCEngine::UI::UILinearGradientDirection;
+using XCEngine::UI::UIPoint;
+using XCEngine::UI::UIRect;
+
+TEST(UIDrawDataTest, DrawListPreservesGradientLineAndCirclePayload) {
+    UIDrawList drawList("CorePrimitives");
+    drawList.AddFilledRectLinearGradient(
+        UIRect(10.0f, 20.0f, 140.0f, 24.0f),
+        UIColor(1.0f, 0.0f, 0.0f, 1.0f),
+        UIColor(0.0f, 0.0f, 1.0f, 1.0f),
+        UILinearGradientDirection::Vertical,
+        3.0f);
+    drawList.AddLine(
+        UIPoint(8.0f, 12.0f),
+        UIPoint(28.0f, 36.0f),
+        UIColor(0.9f, 0.9f, 0.9f, 1.0f),
+        2.0f);
+    drawList.AddFilledCircle(
+        UIPoint(48.0f, 52.0f),
+        6.0f,
+        UIColor(0.2f, 0.6f, 0.9f, 1.0f));
+    drawList.AddCircleOutline(
+        UIPoint(48.0f, 52.0f),
+        9.0f,
+        UIColor(1.0f, 1.0f, 1.0f, 1.0f),
+        1.5f);
+
+    ASSERT_EQ(drawList.GetCommandCount(), 4u);
+    const auto& commands = drawList.GetCommands();
+
+    EXPECT_EQ(commands[0].type, UIDrawCommandType::FilledRectLinearGradient);
+    EXPECT_FLOAT_EQ(commands[0].rect.width, 140.0f);
+    EXPECT_EQ(commands[0].gradientDirection, UILinearGradientDirection::Vertical);
+    EXPECT_FLOAT_EQ(commands[0].secondaryColor.b, 1.0f);
+    EXPECT_FLOAT_EQ(commands[0].rounding, 3.0f);
+
+    EXPECT_EQ(commands[1].type, UIDrawCommandType::Line);
+    EXPECT_FLOAT_EQ(commands[1].position.x, 8.0f);
+    EXPECT_FLOAT_EQ(commands[1].uvMin.x, 28.0f);
+    EXPECT_FLOAT_EQ(commands[1].thickness, 2.0f);
+
+    EXPECT_EQ(commands[2].type, UIDrawCommandType::FilledCircle);
+    EXPECT_FLOAT_EQ(commands[2].position.x, 48.0f);
+    EXPECT_FLOAT_EQ(commands[2].radius, 6.0f);
+
+    EXPECT_EQ(commands[3].type, UIDrawCommandType::CircleOutline);
+    EXPECT_FLOAT_EQ(commands[3].position.y, 52.0f);
+    EXPECT_FLOAT_EQ(commands[3].radius, 9.0f);
+    EXPECT_FLOAT_EQ(commands[3].thickness, 1.5f);
+}
+
+TEST(UIDrawDataTest, DrawDataAggregatesNewPrimitiveCommands) {
+    UIDrawData drawData = {};
+    auto& first = drawData.EmplaceDrawList("Gradients");
+    first.AddFilledRectLinearGradient(
+        UIRect(0.0f, 0.0f, 50.0f, 12.0f),
+        UIColor(0.0f, 0.0f, 0.0f, 1.0f),
+        UIColor(1.0f, 1.0f, 1.0f, 1.0f));
+
+    auto& second = drawData.EmplaceDrawList("Handles");
+    second.AddFilledCircle(UIPoint(12.0f, 12.0f), 4.0f, UIColor(1.0f, 0.0f, 0.0f, 1.0f));
+    second.AddCircleOutline(UIPoint(12.0f, 12.0f), 6.0f, UIColor(1.0f, 1.0f, 1.0f, 1.0f));
+    second.AddLine(
+        UIPoint(0.0f, 24.0f),
+        UIPoint(32.0f, 24.0f),
+        UIColor(0.7f, 0.7f, 0.7f, 1.0f));
+
+    EXPECT_EQ(drawData.GetDrawListCount(), 2u);
+    EXPECT_EQ(drawData.GetTotalCommandCount(), 4u);
+}
+
+} // namespace
--- a/tests/UI/Core/unit/test_ui_scroll_model.cpp
+++ b/tests/UI/Core/unit/test_ui_scroll_model.cpp
@@ -0,0 +1,53 @@
+#include <gtest/gtest.h>
+
+#include <XCEngine/UI/Widgets/UIScrollModel.h>
+
+namespace {
+
+using XCEngine::UI::Widgets::ApplyUIScrollWheel;
+using XCEngine::UI::Widgets::ClampUIScrollOffset;
+using XCEngine::UI::Widgets::ComputeUIScrollOverflow;
+using XCEngine::UI::Widgets::EnsureUIScrollOffsetVisible;
+
+TEST(UIScrollModelTest, OverflowAndClampUseViewportBounds) {
+    EXPECT_FLOAT_EQ(ComputeUIScrollOverflow(80.0f, 120.0f), 0.0f);
+    EXPECT_FLOAT_EQ(ComputeUIScrollOverflow(240.0f, 120.0f), 120.0f);
+
+    EXPECT_FLOAT_EQ(ClampUIScrollOffset(-20.0f, 240.0f, 120.0f), 0.0f);
+    EXPECT_FLOAT_EQ(ClampUIScrollOffset(40.0f, 240.0f, 120.0f), 40.0f);
+    EXPECT_FLOAT_EQ(ClampUIScrollOffset(180.0f, 240.0f, 120.0f), 120.0f);
+}
+
+TEST(UIScrollModelTest, WheelMutationUsesDefaultStepAndReportsClampedNoops) {
+    const auto scrollDown = ApplyUIScrollWheel(48.0f, -120.0f, 360.0f, 120.0f);
+    EXPECT_TRUE(scrollDown.changed);
+    EXPECT_FLOAT_EQ(scrollDown.overflow, 240.0f);
+    EXPECT_FLOAT_EQ(scrollDown.offsetBefore, 48.0f);
+    EXPECT_FLOAT_EQ(scrollDown.offsetAfter, 96.0f);
+
+    const auto clamped = ApplyUIScrollWheel(0.0f, 120.0f, 360.0f, 120.0f);
+    EXPECT_FALSE(clamped.changed);
+    EXPECT_FLOAT_EQ(clamped.offsetBefore, 0.0f);
+    EXPECT_FLOAT_EQ(clamped.offsetAfter, 0.0f);
+
+    const auto noOverflow = ApplyUIScrollWheel(0.0f, -120.0f, 80.0f, 120.0f);
+    EXPECT_FALSE(noOverflow.changed);
+    EXPECT_FLOAT_EQ(noOverflow.overflow, 0.0f);
+}
+
+TEST(UIScrollModelTest, EnsureVisibleKeepsRowsInsideViewport) {
+    EXPECT_FLOAT_EQ(
+        EnsureUIScrollOffsetVisible(24.0f, 12.0f, 20.0f, 300.0f, 120.0f),
+        12.0f);
+    EXPECT_FLOAT_EQ(
+        EnsureUIScrollOffsetVisible(24.0f, 96.0f, 36.0f, 300.0f, 120.0f),
+        24.0f);
+    EXPECT_FLOAT_EQ(
+        EnsureUIScrollOffsetVisible(24.0f, 164.0f, 28.0f, 300.0f, 120.0f),
+        72.0f);
+    EXPECT_FLOAT_EQ(
+        EnsureUIScrollOffsetVisible(180.0f, 260.0f, 60.0f, 300.0f, 120.0f),
+        180.0f);
+}
+
+} // namespace
--- a/tests/UI/Editor/integration/CMakeLists.txt
+++ b/tests/UI/Editor/integration/CMakeLists.txt
@@ -88,6 +88,11 @@ if(TARGET editor_ui_enum_field_basic_validation)
        editor_ui_enum_field_basic_validation)
 endif()

+if(TARGET editor_ui_color_field_basic_validation)
+    list(APPEND EDITOR_UI_INTEGRATION_TARGETS
+        editor_ui_color_field_basic_validation)
+endif()
+
 if(TARGET editor_ui_list_view_basic_validation)
    list(APPEND EDITOR_UI_INTEGRATION_TARGETS
        editor_ui_list_view_basic_validation)
--- a/tests/UI/Editor/integration/shell/CMakeLists.txt
+++ b/tests/UI/Editor/integration/shell/CMakeLists.txt
@@ -40,6 +40,9 @@ endif()
 if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/enum_field_basic/CMakeLists.txt")
    add_subdirectory(enum_field_basic)
 endif()
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/color_field_basic/CMakeLists.txt")
+    add_subdirectory(color_field_basic)
+endif()
 if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/tree_view_basic/CMakeLists.txt")
    add_subdirectory(tree_view_basic)
 endif()
--- a/tests/UI/Editor/integration/shell/color_field_basic/CMakeLists.txt
+++ b/tests/UI/Editor/integration/shell/color_field_basic/CMakeLists.txt
@@ -0,0 +1,31 @@
+add_executable(editor_ui_color_field_basic_validation WIN32
+    main.cpp
+)
+
+target_include_directories(editor_ui_color_field_basic_validation PRIVATE
+    ${CMAKE_SOURCE_DIR}/tests/UI/Editor/integration/shared/src
+    ${CMAKE_SOURCE_DIR}/new_editor/include
+    ${CMAKE_SOURCE_DIR}/new_editor/app
+    ${CMAKE_SOURCE_DIR}/engine/include
+)
+
+target_compile_definitions(editor_ui_color_field_basic_validation PRIVATE
+    UNICODE
+    _UNICODE
+    XCENGINE_EDITOR_UI_TESTS_REPO_ROOT="${XCENGINE_EDITOR_UI_TESTS_REPO_ROOT_PATH}"
+)
+
+if(MSVC)
+    target_compile_options(editor_ui_color_field_basic_validation PRIVATE /utf-8 /FS)
+    set_property(TARGET editor_ui_color_field_basic_validation PROPERTY
+        MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
+endif()
+
+target_link_libraries(editor_ui_color_field_basic_validation PRIVATE
+    XCUIEditorLib
+    XCUIEditorHost
+)
+
+set_target_properties(editor_ui_color_field_basic_validation PROPERTIES
+    OUTPUT_NAME "XCUIEditorColorFieldBasicValidation"
+)
--- a/tests/UI/Editor/integration/shell/color_field_basic/captures/.gitkeep
+++ b/tests/UI/Editor/integration/shell/color_field_basic/captures/.gitkeep
@@ -0,0 +1 @@
+
--- a/tests/UI/Editor/integration/shell/color_field_basic/captures/history/20260408_160549_1_startup.png
+++ b/tests/UI/Editor/integration/shell/color_field_basic/captures/history/20260408_160549_1_startup.png
--- a/tests/UI/Editor/integration/shell/color_field_basic/captures/latest.png
+++ b/tests/UI/Editor/integration/shell/color_field_basic/captures/latest.png
--- a/tests/UI/Editor/integration/shell/color_field_basic/main.cpp
+++ b/tests/UI/Editor/integration/shell/color_field_basic/main.cpp
@@ -0,0 +1,778 @@
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+
+#include <XCEditor/Core/UIEditorColorFieldInteraction.h>
+#include <XCEditor/Core/UIEditorTheme.h>
+#include <XCEditor/Widgets/UIEditorColorField.h>
+#include "EditorValidationTheme.h"
+#include "Host/AutoScreenshot.h"
+#include "Host/NativeRenderer.h"
+
+#include <XCEngine/UI/DrawData.h>
+
+#include <windows.h>
+#include <windowsx.h>
+
+#include <algorithm>
+#include <cctype>
+#include <cstdlib>
+#include <cstdio>
+#include <filesystem>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#ifndef XCENGINE_EDITOR_UI_TESTS_REPO_ROOT
+#define XCENGINE_EDITOR_UI_TESTS_REPO_ROOT "."
+#endif
+
+namespace {
+
+using XCEngine::UI::UIDrawData;
+using XCEngine::UI::UIDrawList;
+using XCEngine::UI::UIInputEvent;
+using XCEngine::UI::UIInputEventType;
+using XCEngine::UI::UIPoint;
+using XCEngine::UI::UIPointerButton;
+using XCEngine::UI::UIRect;
+using XCEngine::UI::Editor::Host::AutoScreenshotController;
+using XCEngine::UI::Editor::Host::NativeRenderer;
+using XCEngine::UI::Editor::UIEditorColorFieldInteractionFrame;
+using XCEngine::UI::Editor::UIEditorColorFieldInteractionResult;
+using XCEngine::UI::Editor::UIEditorColorFieldInteractionState;
+using XCEngine::UI::Editor::UpdateUIEditorColorFieldInteraction;
+using XCEngine::UI::Editor::Widgets::AppendUIEditorColorField;
+using XCEngine::UI::Editor::Widgets::FormatUIEditorColorFieldHexText;
+using XCEngine::UI::Editor::Widgets::HitTestUIEditorColorField;
+using XCEngine::UI::Editor::Widgets::UIEditorColorFieldHitTarget;
+using XCEngine::UI::Editor::Widgets::UIEditorColorFieldHitTargetKind;
+using XCEngine::UI::Editor::Widgets::UIEditorColorFieldSpec;
+namespace Style = XCEngine::UI::Style;
+
+constexpr const wchar_t* kWindowClassName = L"XCUIEditorColorFieldBasicValidation";
+constexpr const wchar_t* kWindowTitle = L"XCUI Editor | ColorField Basic";
+
+enum class ActionId : unsigned char {
+    Reset = 0,
+    Capture
+};
+
+struct ButtonLayout {
+    ActionId action = ActionId::Reset;
+    const char* label = "";
+    UIRect rect = {};
+};
+
+struct ScenarioLayout {
+    UIRect introRect = {};
+    UIRect controlRect = {};
+    UIRect stateRect = {};
+    UIRect previewRect = {};
+    UIRect fieldRect = {};
+    std::vector<ButtonLayout> buttons = {};
+};
+
+std::filesystem::path ResolveRepoRootPath() {
+    std::string root = XCENGINE_EDITOR_UI_TESTS_REPO_ROOT;
+    if (root.size() >= 2u && root.front() == '"' && root.back() == '"') {
+        root = root.substr(1u, root.size() - 2u);
+    }
+    return std::filesystem::path(root).lexically_normal();
+}
+
+std::filesystem::path ResolveValidationThemePath() {
+    return (ResolveRepoRootPath() / "tests/UI/Editor/integration/shared/themes/editor_validation.xctheme")
+        .lexically_normal();
+}
+
+bool IsTruthyEnvironmentFlag(const char* name) {
+    const char* value = std::getenv(name);
+    if (value == nullptr || value[0] == '\0') {
+        return false;
+    }
+
+    std::string normalized = value;
+    for (char& character : normalized) {
+        character = static_cast<char>(std::tolower(static_cast<unsigned char>(character)));
+    }
+
+    return normalized != "0" &&
+        normalized != "false" &&
+        normalized != "off" &&
+        normalized != "no";
+}
+
+bool ContainsPoint(const UIRect& rect, float x, float y) {
+    return x >= rect.x &&
+        x <= rect.x + rect.width &&
+        y >= rect.y &&
+        y <= rect.y + rect.height;
+}
+
+ScenarioLayout BuildScenarioLayout(
+    float width,
+    float height,
+    const XCEngine::Tests::EditorUI::EditorValidationShellMetrics& shellMetrics) {
+    const float margin = shellMetrics.margin;
+    constexpr float leftWidth = 456.0f;
+    const float gap = shellMetrics.gap;
+
+    ScenarioLayout layout = {};
+    layout.introRect = UIRect(margin, margin, leftWidth, 248.0f);
+    layout.controlRect = UIRect(margin, layout.introRect.y + layout.introRect.height + gap, leftWidth, 84.0f);
+    layout.stateRect = UIRect(
+        margin,
+        layout.controlRect.y + layout.controlRect.height + gap,
+        leftWidth,
+        (std::max)(250.0f, height - (layout.controlRect.y + layout.controlRect.height + gap) - margin));
+    layout.previewRect = UIRect(
+        leftWidth + margin * 2.0f,
+        margin,
+        (std::max)(520.0f, width - leftWidth - margin * 3.0f),
+        height - margin * 2.0f);
+    layout.fieldRect = UIRect(
+        layout.previewRect.x + 28.0f,
+        layout.previewRect.y + 72.0f,
+        360.0f,
+        32.0f);
+
+    const float buttonWidth = (layout.controlRect.width - 44.0f) * 0.5f;
+    const float buttonY = layout.controlRect.y + 32.0f;
+    layout.buttons = {
+        { ActionId::Reset, "重置", UIRect(layout.controlRect.x + 14.0f, buttonY, buttonWidth, 36.0f) },
+        { ActionId::Capture, "截图(F12)", UIRect(layout.controlRect.x + 26.0f + buttonWidth, buttonY, buttonWidth, 36.0f) }
+    };
+    return layout;
+}
+
+void DrawCard(
+    UIDrawList& drawList,
+    const UIRect& rect,
+    const XCEngine::Tests::EditorUI::EditorValidationShellPalette& shellPalette,
+    const XCEngine::Tests::EditorUI::EditorValidationShellMetrics& shellMetrics,
+    std::string_view title,
+    std::string_view subtitle = {}) {
+    drawList.AddFilledRect(rect, shellPalette.cardBackground, shellMetrics.cardRadius);
+    drawList.AddRectOutline(rect, shellPalette.cardBorder, 1.0f, shellMetrics.cardRadius);
+    drawList.AddText(
+        UIPoint(rect.x + 16.0f, rect.y + 14.0f),
+        std::string(title),
+        shellPalette.textPrimary,
+        shellMetrics.titleFontSize);
+    if (!subtitle.empty()) {
+        drawList.AddText(
+            UIPoint(rect.x + 16.0f, rect.y + 40.0f),
+            std::string(subtitle),
+            shellPalette.textMuted,
+            shellMetrics.bodyFontSize);
+    }
+}
+
+void DrawButton(
+    UIDrawList& drawList,
+    const ButtonLayout& button,
+    const XCEngine::Tests::EditorUI::EditorValidationShellPalette& shellPalette,
+    const XCEngine::Tests::EditorUI::EditorValidationShellMetrics& shellMetrics,
+    bool hovered) {
+    drawList.AddFilledRect(
+        button.rect,
+        hovered ? shellPalette.buttonHoverBackground : shellPalette.buttonBackground,
+        shellMetrics.buttonRadius);
+    drawList.AddRectOutline(button.rect, shellPalette.cardBorder, 1.0f, shellMetrics.buttonRadius);
+    drawList.AddText(
+        UIPoint(button.rect.x + 16.0f, button.rect.y + 10.0f),
+        button.label,
+        shellPalette.textPrimary,
+        shellMetrics.bodyFontSize);
+}
+
+std::string DescribeHitTarget(const UIEditorColorFieldHitTarget& hitTarget) {
+    switch (hitTarget.kind) {
+    case UIEditorColorFieldHitTargetKind::Swatch:
+        return "swatch";
+    case UIEditorColorFieldHitTargetKind::PopupCloseButton:
+        return "popup_close";
+    case UIEditorColorFieldHitTargetKind::HueWheel:
+        return "popup_hue_wheel";
+    case UIEditorColorFieldHitTargetKind::SaturationValue:
+        return "popup_sv_square";
+    case UIEditorColorFieldHitTargetKind::RedChannel:
+        return "popup_red_channel";
+    case UIEditorColorFieldHitTargetKind::GreenChannel:
+        return "popup_green_channel";
+    case UIEditorColorFieldHitTargetKind::BlueChannel:
+        return "popup_blue_channel";
+    case UIEditorColorFieldHitTargetKind::AlphaChannel:
+        return "popup_alpha_channel";
+    case UIEditorColorFieldHitTargetKind::PopupSurface:
+        return "popup_surface";
+    case UIEditorColorFieldHitTargetKind::Row:
+        return "row";
+    case UIEditorColorFieldHitTargetKind::None:
+    default:
+        return "none";
+    }
+}
+
+UIInputEvent MakePointerEvent(
+    UIInputEventType type,
+    const UIPoint& position,
+    UIPointerButton button = UIPointerButton::None) {
+    UIInputEvent event = {};
+    event.type = type;
+    event.position = position;
+    event.pointerButton = button;
+    return event;
+}
+
+class ScenarioApp {
+public:
+    int Run(HINSTANCE hInstance, int nCmdShow) {
+        if (!Initialize(hInstance, nCmdShow)) {
+            Shutdown();
+            return 1;
+        }
+
+        MSG message = {};
+        while (message.message != WM_QUIT) {
+            if (PeekMessageW(&message, nullptr, 0U, 0U, PM_REMOVE)) {
+                TranslateMessage(&message);
+                DispatchMessageW(&message);
+                continue;
+            }
+
+            RenderFrame();
+            Sleep(8);
+        }
+
+        Shutdown();
+        return static_cast<int>(message.wParam);
+    }
+
+private:
+    static LRESULT CALLBACK WndProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam) {
+        if (message == WM_NCCREATE) {
+            const auto* createStruct = reinterpret_cast<CREATESTRUCTW*>(lParam);
+            auto* app = reinterpret_cast<ScenarioApp*>(createStruct->lpCreateParams);
+            SetWindowLongPtrW(hwnd, GWLP_USERDATA, reinterpret_cast<LONG_PTR>(app));
+            return TRUE;
+        }
+
+        auto* app = reinterpret_cast<ScenarioApp*>(GetWindowLongPtrW(hwnd, GWLP_USERDATA));
+        switch (message) {
+        case WM_SIZE:
+            if (app != nullptr && wParam != SIZE_MINIMIZED) {
+                app->OnResize(static_cast<UINT>(LOWORD(lParam)), static_cast<UINT>(HIWORD(lParam)));
+            }
+            return 0;
+
+        case WM_MOUSEMOVE:
+            if (app != nullptr) {
+                app->HandleMouseMove(
+                    static_cast<float>(GET_X_LPARAM(lParam)),
+                    static_cast<float>(GET_Y_LPARAM(lParam)));
+                return 0;
+            }
+            break;
+
+        case WM_MOUSELEAVE:
+            if (app != nullptr) {
+                app->HandleMouseLeave();
+                return 0;
+            }
+            break;
+
+        case WM_LBUTTONDOWN:
+            if (app != nullptr) {
+                app->HandleLeftButtonDown(
+                    static_cast<float>(GET_X_LPARAM(lParam)),
+                    static_cast<float>(GET_Y_LPARAM(lParam)));
+                return 0;
+            }
+            break;
+
+        case WM_LBUTTONUP:
+            if (app != nullptr) {
+                app->HandleLeftButtonUp(
+                    static_cast<float>(GET_X_LPARAM(lParam)),
+                    static_cast<float>(GET_Y_LPARAM(lParam)));
+                return 0;
+            }
+            break;
+
+        case WM_KEYDOWN:
+        case WM_SYSKEYDOWN:
+            if (app != nullptr && wParam == VK_F12) {
+                app->m_autoScreenshot.RequestCapture("manual_f12");
+                app->m_lastResult = "已请求截图，输出到 captures/latest.png";
+                InvalidateRect(hwnd, nullptr, FALSE);
+                return 0;
+            }
+            break;
+
+        case WM_PAINT:
+            if (app != nullptr) {
+                PAINTSTRUCT paintStruct = {};
+                BeginPaint(hwnd, &paintStruct);
+                app->RenderFrame();
+                EndPaint(hwnd, &paintStruct);
+                return 0;
+            }
+            break;
+
+        case WM_ERASEBKGND:
+            return 1;
+
+        case WM_DESTROY:
+            if (app != nullptr) {
+                app->m_hwnd = nullptr;
+            }
+            PostQuitMessage(0);
+            return 0;
+
+        default:
+            break;
+        }
+
+        return DefWindowProcW(hwnd, message, wParam, lParam);
+    }
+
+    bool Initialize(HINSTANCE hInstance, int nCmdShow) {
+        WNDCLASSEXW windowClass = {};
+        windowClass.cbSize = sizeof(windowClass);
+        windowClass.style = CS_HREDRAW | CS_VREDRAW;
+        windowClass.lpfnWndProc = &ScenarioApp::WndProc;
+        windowClass.hInstance = hInstance;
+        windowClass.hCursor = LoadCursorW(nullptr, IDC_ARROW);
+        windowClass.lpszClassName = kWindowClassName;
+
+        m_windowClassAtom = RegisterClassExW(&windowClass);
+        if (m_windowClassAtom == 0) {
+            return false;
+        }
+
+        m_hwnd = CreateWindowExW(
+            0,
+            kWindowClassName,
+            kWindowTitle,
+            WS_OVERLAPPEDWINDOW | WS_VISIBLE,
+            CW_USEDEFAULT,
+            CW_USEDEFAULT,
+            1540,
+            940,
+            nullptr,
+            nullptr,
+            hInstance,
+            this);
+        if (m_hwnd == nullptr) {
+            return false;
+        }
+
+        ShowWindow(m_hwnd, nCmdShow);
+        UpdateWindow(m_hwnd);
+
+        if (!m_renderer.Initialize(m_hwnd)) {
+            return false;
+        }
+
+        m_captureRoot =
+            ResolveRepoRootPath() / "tests/UI/Editor/integration/shell/color_field_basic/captures";
+        m_autoScreenshot.Initialize(m_captureRoot);
+        const auto themeLoad =
+            XCEngine::Tests::EditorUI::LoadEditorValidationTheme(ResolveValidationThemePath());
+        if (themeLoad.succeeded) {
+            m_theme = themeLoad.theme;
+            m_themeStatus = "loaded";
+        } else {
+            m_themeStatus = themeLoad.error.empty() ? "fallback" : themeLoad.error;
+        }
+
+        ResetScenario();
+        if (IsTruthyEnvironmentFlag("XCUI_COLOR_FIELD_OPEN_POPUP_ON_STARTUP")) {
+            const UIPoint swatchPoint(
+                m_frame.layout.swatchRect.x + 4.0f,
+                m_frame.layout.swatchRect.y + 4.0f);
+            PumpEvents({
+                MakePointerEvent(
+                    UIInputEventType::PointerButtonDown,
+                    swatchPoint,
+                    UIPointerButton::Left),
+                MakePointerEvent(
+                    UIInputEventType::PointerButtonUp,
+                    swatchPoint,
+                    UIPointerButton::Left)
+            });
+            m_lastResult = "已自动打开 ColorField 弹窗";
+        }
+        return true;
+    }
+
+    void Shutdown() {
+        m_autoScreenshot.Shutdown();
+        m_renderer.Shutdown();
+
+        if (m_hwnd != nullptr && IsWindow(m_hwnd)) {
+            DestroyWindow(m_hwnd);
+        }
+        m_hwnd = nullptr;
+
+        if (m_windowClassAtom != 0) {
+            UnregisterClassW(kWindowClassName, GetModuleHandleW(nullptr));
+            m_windowClassAtom = 0;
+        }
+    }
+
+    ScenarioLayout GetLayout() const {
+        RECT clientRect = {};
+        GetClientRect(m_hwnd, &clientRect);
+        const float width = static_cast<float>((std::max)(1L, clientRect.right - clientRect.left));
+        const float height = static_cast<float>((std::max)(1L, clientRect.bottom - clientRect.top));
+        return BuildScenarioLayout(
+            width,
+            height,
+            XCEngine::Tests::EditorUI::ResolveEditorValidationShellMetrics(m_theme));
+    }
+
+    UIRect GetViewportRect() const {
+        RECT clientRect = {};
+        GetClientRect(m_hwnd, &clientRect);
+        return UIRect(
+            0.0f,
+            0.0f,
+            static_cast<float>((std::max)(1L, clientRect.right - clientRect.left)),
+            static_cast<float>((std::max)(1L, clientRect.bottom - clientRect.top)));
+    }
+
+    void ResetScenario() {
+        m_spec = {};
+        m_spec.fieldId = "tint";
+        m_spec.label = "Tint";
+        m_spec.value = XCEngine::UI::UIColor(0.84f, 0.42f, 0.28f, 0.65f);
+        m_spec.showAlpha = true;
+        m_interactionState = {};
+        m_interactionState.colorFieldState.focused = true;
+        m_mousePosition = UIPoint(-1000.0f, -1000.0f);
+        m_hoveredAction = ActionId::Reset;
+        m_hasHoveredAction = false;
+        m_lastResult = "已重置到默认 ColorField 状态";
+        RefreshFrame();
+    }
+
+    void RefreshFrame() {
+        if (m_hwnd == nullptr) {
+            return;
+        }
+
+        const ScenarioLayout layout = GetLayout();
+        const auto metrics = XCEngine::UI::Editor::ResolveUIEditorColorFieldMetrics(m_theme);
+        m_frame = UpdateUIEditorColorFieldInteraction(
+            m_interactionState,
+            m_spec,
+            layout.fieldRect,
+            {},
+            metrics,
+            GetViewportRect());
+    }
+
+    void OnResize(UINT width, UINT height) {
+        if (width == 0u || height == 0u) {
+            return;
+        }
+
+        m_renderer.Resize(width, height);
+        RefreshFrame();
+    }
+
+    void HandleMouseMove(float x, float y) {
+        m_mousePosition = UIPoint(x, y);
+        const ScenarioLayout layout = GetLayout();
+        UpdateHoveredAction(layout, x, y);
+
+        TRACKMOUSEEVENT trackEvent = {};
+        trackEvent.cbSize = sizeof(trackEvent);
+        trackEvent.dwFlags = TME_LEAVE;
+        trackEvent.hwndTrack = m_hwnd;
+        TrackMouseEvent(&trackEvent);
+
+        UpdateResultText(PumpEvents({ MakePointerEvent(UIInputEventType::PointerMove, m_mousePosition) }));
+        InvalidateRect(m_hwnd, nullptr, FALSE);
+    }
+
+    void HandleMouseLeave() {
+        m_mousePosition = UIPoint(-1000.0f, -1000.0f);
+        m_hasHoveredAction = false;
+        PumpEvents({ MakePointerEvent(UIInputEventType::PointerLeave, m_mousePosition) });
+        InvalidateRect(m_hwnd, nullptr, FALSE);
+    }
+
+    void HandleLeftButtonDown(float x, float y) {
+        m_mousePosition = UIPoint(x, y);
+        const ScenarioLayout layout = GetLayout();
+        if (HitTestAction(layout, x, y) != nullptr) {
+            UpdateHoveredAction(layout, x, y);
+            InvalidateRect(m_hwnd, nullptr, FALSE);
+            return;
+        }
+
+        UpdateResultText(
+            PumpEvents({ MakePointerEvent(UIInputEventType::PointerButtonDown, m_mousePosition, UIPointerButton::Left) }));
+        InvalidateRect(m_hwnd, nullptr, FALSE);
+    }
+
+    void HandleLeftButtonUp(float x, float y) {
+        m_mousePosition = UIPoint(x, y);
+        const ScenarioLayout layout = GetLayout();
+        const ButtonLayout* button = HitTestAction(layout, x, y);
+        if (button != nullptr) {
+            ExecuteAction(button->action);
+            UpdateHoveredAction(layout, x, y);
+            InvalidateRect(m_hwnd, nullptr, FALSE);
+            return;
+        }
+
+        UpdateResultText(
+            PumpEvents({ MakePointerEvent(UIInputEventType::PointerButtonUp, m_mousePosition, UIPointerButton::Left) }));
+        InvalidateRect(m_hwnd, nullptr, FALSE);
+    }
+
+    void UpdateHoveredAction(const ScenarioLayout& layout, float x, float y) {
+        const ButtonLayout* button = HitTestAction(layout, x, y);
+        if (button == nullptr) {
+            m_hasHoveredAction = false;
+            return;
+        }
+
+        m_hoveredAction = button->action;
+        m_hasHoveredAction = true;
+    }
+
+    const ButtonLayout* HitTestAction(const ScenarioLayout& layout, float x, float y) const {
+        for (const ButtonLayout& button : layout.buttons) {
+            if (ContainsPoint(button.rect, x, y)) {
+                return &button;
+            }
+        }
+        return nullptr;
+    }
+
+    UIEditorColorFieldInteractionResult PumpEvents(std::vector<UIInputEvent> events) {
+        const ScenarioLayout layout = GetLayout();
+        const auto metrics = XCEngine::UI::Editor::ResolveUIEditorColorFieldMetrics(m_theme);
+        m_frame = UpdateUIEditorColorFieldInteraction(
+            m_interactionState,
+            m_spec,
+            layout.fieldRect,
+            std::move(events),
+            metrics,
+            GetViewportRect());
+        return m_frame.result;
+    }
+
+    void UpdateResultText(const UIEditorColorFieldInteractionResult& result) {
+        if (result.colorChanged) {
+            m_lastResult = "颜色值已更新";
+            return;
+        }
+        if (result.popupOpened) {
+            m_lastResult = "已打开拾色弹窗";
+            return;
+        }
+        if (result.popupClosed) {
+            m_lastResult = "已关闭拾色弹窗";
+            return;
+        }
+        if (result.consumed) {
+            m_lastResult = "控件已消费输入";
+            return;
+        }
+        m_lastResult = "等待交互";
+    }
+
+    void ExecuteAction(ActionId action) {
+        switch (action) {
+        case ActionId::Reset:
+            ResetScenario();
+            break;
+        case ActionId::Capture:
+            m_autoScreenshot.RequestCapture("manual_button");
+            m_lastResult = "已请求截图，输出到 captures/latest.png";
+            break;
+        }
+    }
+
+    std::string BuildColorSummary() const {
+        char buffer[128] = {};
+        std::snprintf(
+            buffer,
+            sizeof(buffer),
+            "R %.3f  G %.3f  B %.3f  A %.3f",
+            m_spec.value.r,
+            m_spec.value.g,
+            m_spec.value.b,
+            m_spec.value.a);
+        return std::string(buffer);
+    }
+
+    void RenderFrame() {
+        if (m_hwnd == nullptr) {
+            return;
+        }
+
+        const UIRect viewportRect = GetViewportRect();
+        const auto shellMetrics = XCEngine::Tests::EditorUI::ResolveEditorValidationShellMetrics(m_theme);
+        const auto shellPalette = XCEngine::Tests::EditorUI::ResolveEditorValidationShellPalette(m_theme);
+        const ScenarioLayout layout = BuildScenarioLayout(viewportRect.width, viewportRect.height, shellMetrics);
+        RefreshFrame();
+
+        const UIEditorColorFieldHitTarget currentHit =
+            HitTestUIEditorColorField(
+                m_frame.layout,
+                m_interactionState.colorFieldState.popupOpen,
+                m_mousePosition);
+
+        const auto fieldMetrics = XCEngine::UI::Editor::ResolveUIEditorColorFieldMetrics(m_theme);
+        const auto fieldPalette = XCEngine::UI::Editor::ResolveUIEditorColorFieldPalette(m_theme);
+
+        UIDrawData drawData = {};
+        UIDrawList& drawList = drawData.EmplaceDrawList("EditorColorFieldBasic");
+        drawList.AddFilledRect(viewportRect, shellPalette.windowBackground);
+
+        DrawCard(
+            drawList,
+            layout.introRect,
+            shellPalette,
+            shellMetrics,
+            "这个测试在验证什么功能",
+            "只验证 Editor ColorField 的独立样式、弹窗结构和拾色交互，不混入 PropertyGrid。");
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 72.0f),
+            "1. 点击 swatch，检查 popup 是否在控件下方稳定展开。",
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 94.0f),
+            "2. 在 SV square 内拖拽，检查颜色是否连续变化。",
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 116.0f),
+            "3. 拖拽 hue wheel 与 R/G/B/A slider，检查颜色和透明度是否同步更新。",
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 138.0f),
+            "4. 点击右上角 close 或点击控件外部，检查 popup 是否关闭。",
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.introRect.x + 16.0f, layout.introRect.y + 160.0f),
+            "5. 检查 Hexadecimal、数值框、handle、checkerboard 与截图路径是否同步。",
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+
+        DrawCard(drawList, layout.controlRect, shellPalette, shellMetrics, "操作");
+        for (const ButtonLayout& button : layout.buttons) {
+            DrawButton(
+                drawList,
+                button,
+                shellPalette,
+                shellMetrics,
+                m_hasHoveredAction && m_hoveredAction == button.action);
+        }
+
+        DrawCard(
+            drawList,
+            layout.stateRect,
+            shellPalette,
+            shellMetrics,
+            "状态摘要",
+            "重点检查 hover / popup / result / hex / rgba。");
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 70.0f),
+            "Hover: " + DescribeHitTarget(currentHit),
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 94.0f),
+            std::string("Popup: ") + (m_interactionState.colorFieldState.popupOpen ? "open" : "closed"),
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 118.0f),
+            "Hex: " + FormatUIEditorColorFieldHexText(m_spec),
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 142.0f),
+            BuildColorSummary(),
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 166.0f),
+            "Result: " + m_lastResult,
+            shellPalette.textPrimary,
+            shellMetrics.bodyFontSize);
+        const std::string captureSummary =
+            m_autoScreenshot.HasPendingCapture()
+                ? "截图排队中..."
+                : (m_autoScreenshot.GetLastCaptureSummary().empty()
+                    ? std::string("F12 -> tests/UI/Editor/integration/shell/color_field_basic/captures/")
+                    : m_autoScreenshot.GetLastCaptureSummary());
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 190.0f),
+            captureSummary,
+            shellPalette.textWeak,
+            shellMetrics.bodyFontSize);
+        drawList.AddText(
+            UIPoint(layout.stateRect.x + 16.0f, layout.stateRect.y + 214.0f),
+            "Theme: " + m_themeStatus,
+            shellPalette.textWeak,
+            shellMetrics.bodyFontSize);
+
+        DrawCard(
+            drawList,
+            layout.previewRect,
+            shellPalette,
+            shellMetrics,
+            "ColorField 预览",
+            "这里只放一个独立 ColorField，便于单点检查样式与交互。");
+        AppendUIEditorColorField(
+            drawList,
+            layout.fieldRect,
+            m_spec,
+            m_interactionState.colorFieldState,
+            fieldPalette,
+            fieldMetrics,
+            viewportRect);
+
+        const bool framePresented = m_renderer.Render(drawData);
+        m_autoScreenshot.CaptureIfRequested(
+            m_renderer,
+            drawData,
+            static_cast<unsigned int>(viewportRect.width),
+            static_cast<unsigned int>(viewportRect.height),
+            framePresented);
+    }
+
+    HWND m_hwnd = nullptr;
+    ATOM m_windowClassAtom = 0;
+    NativeRenderer m_renderer = {};
+    AutoScreenshotController m_autoScreenshot = {};
+    std::filesystem::path m_captureRoot = {};
+    UIEditorColorFieldSpec m_spec = {};
+    UIEditorColorFieldInteractionState m_interactionState = {};
+    UIEditorColorFieldInteractionFrame m_frame = {};
+    Style::UITheme m_theme = {};
+    UIPoint m_mousePosition = UIPoint(-1000.0f, -1000.0f);
+    ActionId m_hoveredAction = ActionId::Reset;
+    bool m_hasHoveredAction = false;
+    std::string m_lastResult = {};
+    std::string m_themeStatus = "fallback";
+};
+
+} // namespace
+
+int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE, LPWSTR, int nCmdShow) {
+    return ScenarioApp().Run(hInstance, nCmdShow);
+}
--- a/tests/UI/Editor/integration/shell/dock_host_basic/captures/.gitkeep
+++ b/tests/UI/Editor/integration/shell/dock_host_basic/captures/.gitkeep
@@ -1 +0,0 @@
-
--- a/tests/UI/Editor/integration/shell/text_field_basic/captures/.gitkeep
+++ b/tests/UI/Editor/integration/shell/text_field_basic/captures/.gitkeep
@@ -0,0 +1 @@
+
--- a/tests/UI/Editor/integration/shell/vector2_field_basic/captures/.gitkeep
+++ b/tests/UI/Editor/integration/shell/vector2_field_basic/captures/.gitkeep
@@ -0,0 +1 @@
+
--- a/tests/UI/Editor/integration/shell/vector3_field_basic/captures/.gitkeep
+++ b/tests/UI/Editor/integration/shell/vector3_field_basic/captures/.gitkeep
@@ -0,0 +1 @@
+
--- a/tests/UI/Editor/unit/CMakeLists.txt
+++ b/tests/UI/Editor/unit/CMakeLists.txt
@@ -21,6 +21,8 @@ set(EDITOR_UI_UNIT_TEST_SOURCES
    test_ui_editor_theme.cpp
    test_ui_editor_bool_field.cpp
    test_ui_editor_bool_field_interaction.cpp
+    test_ui_editor_color_field.cpp
+    test_ui_editor_color_field_interaction.cpp
    test_ui_editor_dock_host.cpp
    test_ui_editor_list_view.cpp
    test_ui_editor_list_view_interaction.cpp
--- a/tests/UI/Editor/unit/test_ui_editor_color_field.cpp
+++ b/tests/UI/Editor/unit/test_ui_editor_color_field.cpp
@@ -0,0 +1,140 @@
+#include <gtest/gtest.h>
+
+#include <XCEngine/UI/DrawData.h>
+#include <XCEditor/Widgets/UIEditorColorField.h>
+
+namespace {
+
+using XCEngine::UI::UIDrawCommandType;
+using XCEngine::UI::UIPoint;
+using XCEngine::UI::UIRect;
+using XCEngine::UI::Editor::Widgets::AppendUIEditorColorField;
+using XCEngine::UI::Editor::Widgets::BuildUIEditorColorFieldLayout;
+using XCEngine::UI::Editor::Widgets::FormatUIEditorColorFieldHexText;
+using XCEngine::UI::Editor::Widgets::FormatUIEditorColorFieldRgbaText;
+using XCEngine::UI::Editor::Widgets::HitTestUIEditorColorField;
+using XCEngine::UI::Editor::Widgets::UIEditorColorFieldHitTargetKind;
+using XCEngine::UI::Editor::Widgets::UIEditorColorFieldSpec;
+using XCEngine::UI::Editor::Widgets::UIEditorColorFieldState;
+
+TEST(UIEditorColorFieldTest, FormatsHexTextWithAndWithoutAlpha) {
+    UIEditorColorFieldSpec spec = {};
+    spec.value = XCEngine::UI::UIColor(1.0f, 0.5f, 0.25f, 0.75f);
+    spec.showAlpha = true;
+
+    EXPECT_EQ(FormatUIEditorColorFieldHexText(spec), "#FF8040BF");
+
+    spec.showAlpha = false;
+    EXPECT_EQ(FormatUIEditorColorFieldHexText(spec), "#FF8040");
+}
+
+TEST(UIEditorColorFieldTest, FormatsRgbaReadoutForInspectorSummary) {
+    UIEditorColorFieldSpec spec = {};
+    spec.value = XCEngine::UI::UIColor(0.25f, 0.5f, 0.75f, 1.0f);
+
+    EXPECT_EQ(FormatUIEditorColorFieldRgbaText(spec), "RGBA 64, 128, 191, 255");
+}
+
+TEST(UIEditorColorFieldTest, LayoutKeepsInspectorColumnAndCompactSwatch) {
+    UIEditorColorFieldSpec spec = {};
+    spec.fieldId = "albedo";
+    spec.label = "Albedo";
+
+    const auto layout = BuildUIEditorColorFieldLayout(
+        UIRect(0.0f, 0.0f, 360.0f, 22.0f),
+        spec);
+
+    EXPECT_FLOAT_EQ(layout.swatchRect.x, 236.0f);
+    EXPECT_FLOAT_EQ(layout.swatchRect.width, 54.0f);
+    EXPECT_FLOAT_EQ(layout.swatchRect.height, 18.0f);
+    EXPECT_EQ(
+        HitTestUIEditorColorField(
+            layout,
+            false,
+            UIPoint(layout.swatchRect.x + 2.0f, layout.swatchRect.y + 2.0f)).kind,
+        UIEditorColorFieldHitTargetKind::Swatch);
+}
+
+TEST(UIEditorColorFieldTest, PopupLayoutExposesHueWheelAndChannelTargets) {
+    UIEditorColorFieldSpec spec = {};
+    spec.showAlpha = true;
+
+    const auto layout = BuildUIEditorColorFieldLayout(
+        UIRect(10.0f, 20.0f, 360.0f, 22.0f),
+        spec,
+        {},
+        UIRect(0.0f, 0.0f, 800.0f, 600.0f));
+
+    EXPECT_GT(layout.saturationValueRect.width, 0.0f);
+    EXPECT_GT(layout.hueWheelOuterRadius, layout.hueWheelInnerRadius);
+    EXPECT_GT(layout.redSliderRect.width, 0.0f);
+    EXPECT_GT(layout.alphaSliderRect.width, 0.0f);
+    EXPECT_EQ(
+        HitTestUIEditorColorField(
+            layout,
+            true,
+            UIPoint(
+                layout.hueWheelCenter.x + (layout.hueWheelInnerRadius + layout.hueWheelOuterRadius) * 0.5f,
+                layout.hueWheelCenter.y)).kind,
+        UIEditorColorFieldHitTargetKind::HueWheel);
+    EXPECT_EQ(
+        HitTestUIEditorColorField(
+            layout,
+            true,
+            UIPoint(layout.saturationValueRect.x + 5.0f, layout.saturationValueRect.y + 5.0f)).kind,
+        UIEditorColorFieldHitTargetKind::SaturationValue);
+    EXPECT_EQ(
+        HitTestUIEditorColorField(
+            layout,
+            true,
+            UIPoint(layout.redSliderRect.x + 2.0f, layout.redSliderRect.y + 2.0f)).kind,
+        UIEditorColorFieldHitTargetKind::RedChannel);
+    EXPECT_EQ(
+        HitTestUIEditorColorField(
+            layout,
+            true,
+            UIPoint(layout.alphaSliderRect.x + 2.0f, layout.alphaSliderRect.y + 2.0f)).kind,
+        UIEditorColorFieldHitTargetKind::AlphaChannel);
+}
+
+TEST(UIEditorColorFieldTest, PopupDrawEmitsHeaderWheelHandlesAndHexadecimalLabel) {
+    UIEditorColorFieldSpec spec = {};
+    spec.label = "Tint";
+    spec.value = XCEngine::UI::UIColor(0.8f, 0.4f, 0.2f, 0.5f);
+    spec.showAlpha = true;
+
+    UIEditorColorFieldState state = {};
+    state.popupOpen = true;
+
+    XCEngine::UI::UIDrawData drawData = {};
+    auto& drawList = drawData.EmplaceDrawList("ColorField");
+    AppendUIEditorColorField(
+        drawList,
+        UIRect(0.0f, 0.0f, 360.0f, 22.0f),
+        spec,
+        state,
+        {},
+        {},
+        UIRect(0.0f, 0.0f, 800.0f, 600.0f));
+
+    bool hasFilledCircle = false;
+    bool hasCircleOutline = false;
+    bool hasLine = false;
+    bool hasTitleText = false;
+    bool hasHexLabel = false;
+    for (const auto& command : drawList.GetCommands()) {
+        hasFilledCircle = hasFilledCircle || command.type == UIDrawCommandType::FilledCircle;
+        hasCircleOutline = hasCircleOutline || command.type == UIDrawCommandType::CircleOutline;
+        hasLine = hasLine || command.type == UIDrawCommandType::Line;
+        hasTitleText = hasTitleText || command.text == "Color";
+        hasHexLabel = hasHexLabel || command.text == "Hexadecimal";
+    }
+
+    EXPECT_TRUE(hasFilledCircle);
+    EXPECT_TRUE(hasCircleOutline);
+    EXPECT_TRUE(hasLine);
+    EXPECT_TRUE(hasTitleText);
+    EXPECT_TRUE(hasHexLabel);
+}
+
+} // namespace
--- a/tests/UI/Editor/unit/test_ui_editor_color_field_interaction.cpp
+++ b/tests/UI/Editor/unit/test_ui_editor_color_field_interaction.cpp
@@ -0,0 +1,138 @@
+#include <gtest/gtest.h>
+
+#include <XCEditor/Core/UIEditorColorFieldInteraction.h>
+
+#include <XCEngine/Input/InputTypes.h>
+
+namespace {
+
+using XCEngine::Input::KeyCode;
+using XCEngine::UI::UIInputEvent;
+using XCEngine::UI::UIInputEventType;
+using XCEngine::UI::UIPoint;
+using XCEngine::UI::UIPointerButton;
+using XCEngine::UI::UIRect;
+using XCEngine::UI::Editor::UIEditorColorFieldInteractionState;
+using XCEngine::UI::Editor::UpdateUIEditorColorFieldInteraction;
+using XCEngine::UI::Editor::Widgets::UIEditorColorFieldSpec;
+
+UIInputEvent MakePointer(UIInputEventType type, float x, float y, UIPointerButton button = UIPointerButton::None) {
+    UIInputEvent event = {};
+    event.type = type;
+    event.position = UIPoint(x, y);
+    event.pointerButton = button;
+    return event;
+}
+
+UIInputEvent MakeKey(KeyCode keyCode) {
+    UIInputEvent event = {};
+    event.type = UIInputEventType::KeyDown;
+    event.keyCode = static_cast<std::int32_t>(keyCode);
+    return event;
+}
+
+TEST(UIEditorColorFieldInteractionTest, ClickSwatchOpensPopupAndEscapeClosesIt) {
+    UIEditorColorFieldSpec spec = {};
+    spec.fieldId = "tint";
+    spec.label = "Tint";
+    spec.showAlpha = true;
+    spec.value = XCEngine::UI::UIColor(0.8f, 0.4f, 0.2f, 0.5f);
+
+    UIEditorColorFieldInteractionState state = {};
+    auto frame = UpdateUIEditorColorFieldInteraction(
+        state,
+        spec,
+        UIRect(0.0f, 0.0f, 360.0f, 32.0f),
+        {});
+
+    frame = UpdateUIEditorColorFieldInteraction(
+        state,
+        spec,
+        UIRect(0.0f, 0.0f, 360.0f, 32.0f),
+        {
+            MakePointer(
+                UIInputEventType::PointerButtonDown,
+                frame.layout.swatchRect.x + 2.0f,
+                frame.layout.swatchRect.y + 2.0f,
+                UIPointerButton::Left),
+            MakePointer(
+                UIInputEventType::PointerButtonUp,
+                frame.layout.swatchRect.x + 2.0f,
+                frame.layout.swatchRect.y + 2.0f,
+                UIPointerButton::Left)
+        });
+    EXPECT_TRUE(frame.result.popupOpened);
+    EXPECT_TRUE(state.colorFieldState.popupOpen);
+
+    frame = UpdateUIEditorColorFieldInteraction(
+        state,
+        spec,
+        UIRect(0.0f, 0.0f, 360.0f, 32.0f),
+        { MakeKey(KeyCode::Escape) });
+    EXPECT_TRUE(frame.result.popupClosed);
+    EXPECT_FALSE(state.colorFieldState.popupOpen);
+}
+
+TEST(UIEditorColorFieldInteractionTest, DraggingHueWheelAndAlphaChannelUpdatesColor) {
+    UIEditorColorFieldSpec spec = {};
+    spec.fieldId = "tint";
+    spec.label = "Tint";
+    spec.showAlpha = true;
+    spec.value = XCEngine::UI::UIColor(1.0f, 0.0f, 0.0f, 1.0f);
+
+    UIEditorColorFieldInteractionState state = {};
+    auto frame = UpdateUIEditorColorFieldInteraction(
+        state,
+        spec,
+        UIRect(0.0f, 0.0f, 360.0f, 32.0f),
+        {});
+
+    frame = UpdateUIEditorColorFieldInteraction(
+        state,
+        spec,
+        UIRect(0.0f, 0.0f, 360.0f, 32.0f),
+        {
+            MakePointer(
+                UIInputEventType::PointerButtonDown,
+                frame.layout.swatchRect.x + 2.0f,
+                frame.layout.swatchRect.y + 2.0f,
+                UIPointerButton::Left),
+            MakePointer(
+                UIInputEventType::PointerButtonUp,
+                frame.layout.swatchRect.x + 2.0f,
+                frame.layout.swatchRect.y + 2.0f,
+                UIPointerButton::Left)
+        });
+    ASSERT_TRUE(state.colorFieldState.popupOpen);
+
+    const float hueRadius = (frame.layout.hueWheelInnerRadius + frame.layout.hueWheelOuterRadius) * 0.5f;
+    const float hueX = frame.layout.hueWheelCenter.x - hueRadius;
+    const float hueY = frame.layout.hueWheelCenter.y;
+    frame = UpdateUIEditorColorFieldInteraction(
+        state,
+        spec,
+        UIRect(0.0f, 0.0f, 360.0f, 32.0f),
+        {
+            MakePointer(UIInputEventType::PointerButtonDown, hueX, hueY, UIPointerButton::Left),
+            MakePointer(UIInputEventType::PointerMove, hueX, hueY),
+            MakePointer(UIInputEventType::PointerButtonUp, hueX, hueY, UIPointerButton::Left)
+        });
+    EXPECT_TRUE(frame.result.colorChanged);
+    EXPECT_GT(spec.value.b, 0.0f);
+
+    const float alphaX = frame.layout.alphaSliderRect.x + frame.layout.alphaSliderRect.width * 0.25f;
+    const float alphaY = frame.layout.alphaSliderRect.y + frame.layout.alphaSliderRect.height * 0.5f;
+    frame = UpdateUIEditorColorFieldInteraction(
+        state,
+        spec,
+        UIRect(0.0f, 0.0f, 360.0f, 32.0f),
+        {
+            MakePointer(UIInputEventType::PointerButtonDown, alphaX, alphaY, UIPointerButton::Left),
+            MakePointer(UIInputEventType::PointerMove, alphaX, alphaY),
+            MakePointer(UIInputEventType::PointerButtonUp, alphaX, alphaY, UIPointerButton::Left)
+        });
+    EXPECT_TRUE(frame.result.colorChanged);
+    EXPECT_LT(spec.value.a, 0.5f);
+}
+
+} // namespace
--- a/tests/UI/Editor/unit/test_ui_editor_theme.cpp
+++ b/tests/UI/Editor/unit/test_ui_editor_theme.cpp
@@ -37,6 +37,28 @@ Style::UITheme BuildEditorFieldTheme() {
    definition.SetToken("editor.size.field.dropdown_arrow_width", Style::UIStyleValue(14.0f));
    definition.SetToken("editor.space.field.dropdown_arrow_inset_x", Style::UIStyleValue(4.0f));
    definition.SetToken("editor.space.field.dropdown_arrow_inset_y", Style::UIStyleValue(4.0f));
+    definition.SetToken("editor.size.field.color_popup_width", Style::UIStyleValue(320.0f));
+    definition.SetToken("editor.size.field.color_popup_top_row", Style::UIStyleValue(36.0f));
+    definition.SetToken("editor.size.field.color_preview_width", Style::UIStyleValue(108.0f));
+    definition.SetToken("editor.size.field.color_preview_height", Style::UIStyleValue(26.0f));
+    definition.SetToken("editor.size.field.color_wheel_outer_radius", Style::UIStyleValue(112.0f));
+    definition.SetToken("editor.size.field.color_wheel_ring_thickness", Style::UIStyleValue(22.0f));
+    definition.SetToken("editor.size.field.color_sv_square", Style::UIStyleValue(118.0f));
+    definition.SetToken("editor.size.field.color_wheel_region_height", Style::UIStyleValue(224.0f));
+    definition.SetToken("editor.size.field.color_channel_row_height", Style::UIStyleValue(21.0f));
+    definition.SetToken("editor.size.field.color_numeric_box_width", Style::UIStyleValue(66.0f));
+    definition.SetToken("editor.size.field.color_channel_label_width", Style::UIStyleValue(14.0f));
+    definition.SetToken("editor.size.field.color_hex_label_width", Style::UIStyleValue(90.0f));
+    definition.SetToken("editor.space.field.color_control_row_spacing", Style::UIStyleValue(7.0f));
+    definition.SetToken("editor.space.field.color_popup_field_inset", Style::UIStyleValue(5.0f));
+    definition.SetToken("editor.color.field.color_popup_surface", Style::UIStyleValue(Math::Color(0.22f, 0.22f, 0.22f, 1.0f)));
+    definition.SetToken("editor.color.field.color_popup_header", Style::UIStyleValue(Math::Color(0.48f, 0.28f, 0.10f, 1.0f)));
+    definition.SetToken("editor.color.field.color_popup_close", Style::UIStyleValue(Math::Color(0.74f, 0.34f, 0.32f, 1.0f)));
+    definition.SetToken("editor.color.field.color_popup_close_hover", Style::UIStyleValue(Math::Color(0.80f, 0.38f, 0.36f, 1.0f)));
+    definition.SetToken("editor.color.field.color_popup_slider_border", Style::UIStyleValue(Math::Color(0.11f, 0.11f, 0.11f, 1.0f)));
+    definition.SetToken("editor.color.field.color_popup_numeric_box", Style::UIStyleValue(Math::Color(0.17f, 0.17f, 0.17f, 1.0f)));
+    definition.SetToken("editor.color.field.color_popup_numeric_box_text", Style::UIStyleValue(Math::Color(0.93f, 0.93f, 0.93f, 1.0f)));
+    definition.SetToken("editor.color.field.color_popup_handle_outline", Style::UIStyleValue(Math::Color(0.10f, 0.10f, 0.10f, 0.5f)));
    definition.SetToken("editor.radius.field.row", Style::UIStyleValue(2.0f));
    definition.SetToken("editor.radius.field.control", Style::UIStyleValue(2.0f));
    definition.SetToken("editor.border.field", Style::UIStyleValue(1.0f));
@@ -244,6 +266,25 @@ TEST(UIEditorThemeTest, FieldResolversReadEditorThemeTokens) {
    EXPECT_FLOAT_EQ(enumMetrics.dropdownArrowFontSize, 10.0f);
    EXPECT_FLOAT_EQ(enumPalette.arrowColor.r, 0.88f);

+    const auto colorMetrics = Editor::ResolveUIEditorColorFieldMetrics(theme);
+    const auto colorPalette = Editor::ResolveUIEditorColorFieldPalette(theme);
+    EXPECT_FLOAT_EQ(colorMetrics.popupWidth, 320.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.popupTopRowHeight, 36.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.popupPreviewWidth, 108.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.wheelOuterRadius, 112.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.wheelRingThickness, 22.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.saturationValueSize, 118.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.channelRowHeight, 21.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.numericBoxWidth, 66.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.hexLabelWidth, 90.0f);
+    EXPECT_FLOAT_EQ(colorPalette.popupColor.r, 0.22f);
+    EXPECT_FLOAT_EQ(colorPalette.popupHeaderColor.r, 0.48f);
+    EXPECT_FLOAT_EQ(colorPalette.closeButtonColor.r, 0.74f);
+    EXPECT_FLOAT_EQ(colorPalette.closeButtonHoverColor.r, 0.80f);
+    EXPECT_FLOAT_EQ(colorPalette.sliderBorderColor.r, 0.11f);
+    EXPECT_FLOAT_EQ(colorPalette.numericBoxTextColor.r, 0.93f);
+    EXPECT_FLOAT_EQ(colorPalette.handleStrokeColor.r, 0.10f);
+
    const auto popupMetrics = Editor::ResolveUIEditorMenuPopupMetrics(theme);
    const auto popupPalette = Editor::ResolveUIEditorMenuPopupPalette(theme);
    EXPECT_FLOAT_EQ(popupMetrics.contentPaddingX, 6.0f);
@@ -386,6 +427,18 @@ TEST(UIEditorThemeTest, HostedFieldBuildersInheritPropertyGridMetricsAndPalette)
    EXPECT_FLOAT_EQ(enumMetrics.valueTextInsetX, 5.0f);
    EXPECT_FLOAT_EQ(enumMetrics.dropdownArrowFontSize, 12.0f);
    EXPECT_FLOAT_EQ(enumPalette.arrowColor.r, 0.9f);
+
+    const auto colorMetrics = Editor::BuildUIEditorHostedColorFieldMetrics(propertyMetrics);
+    const auto colorPalette = Editor::BuildUIEditorHostedColorFieldPalette(propertyPalette);
+    EXPECT_FLOAT_EQ(colorMetrics.controlTrailingInset, 5.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.swatchInsetY, 2.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.labelFontSize, 10.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.valueFontSize, 12.0f);
+    EXPECT_FLOAT_EQ(colorMetrics.popupHeaderHeight, 30.0f);
+    EXPECT_FLOAT_EQ(colorPalette.labelColor.r, 0.8f);
+    EXPECT_FLOAT_EQ(colorPalette.popupBorderColor.r, 0.15f);
+    EXPECT_FLOAT_EQ(colorPalette.popupHeaderColor.r, 0.43f);
+    EXPECT_FLOAT_EQ(colorPalette.swatchBorderColor.r, 0.5f);
 }

 } // namespace