Files
webstudio/apps/builder/e2e/flows/data-variables.ts
Oleg Isonen f6c524572d feat: add Builder dark theme and rebuild colors
## Summary

Rebuilds Webstudio’s color system, migrates the entire Builder to it,
and introduces a complete dark theme.

A small set of theme colors and contrast controls now drives the
interface through relative CSS colors:

```text
Theme colors and contrast
    ↓
Light/dark derivation bounds
    ↓
Derived color families
    ↓
Reusable semantic colors
    ↓
Component composition
    ↓
Builder interface
```

CSS is the runtime source of truth. Light and dark modes share the same
theme inputs, so changing a theme color automatically updates its
surfaces, content, borders, states, and component presentation. The
refactor turns dark mode into a first-class Builder theme rather than a
separately maintained palette.

This is an atomic migration. Legacy color names and compatibility
aliases will not remain after all consumers have moved.

## Scope

- The color source, derivation model, semantic vocabulary, validation,
typing, and Storybook overview.
- Every design-system component.
- Builder, dashboard, authentication, shared UI, Query Builder, stories,
and tests that consume the legacy color scale.
- Removal of the legacy Stitches color scale after its final consumer is
migrated.
- A complete dark theme across application UI while keeping authored
canvas content independent.
- Complete light and dark visual verification.
- Unified browser-test infrastructure: Vitest Browser Mode for Design
System browser contracts and standard Playwright Test for all Builder
E2E workflows.

Literal colors remain only where color is the actual content or belongs
to a deliberately separate system, such as user-authored values,
external previews, brand artwork, data visualization, functional canvas
overlays, and source assets. Every remaining exception must have an
explicit owner.

## Architecture decisions

- Theme authors control six color families and three bounded contrast
controls.
- Relative CSS colors derive the rest of the system.
- Dark mode changes derivation bounds instead of maintaining a second
independent palette.
- Components consume a small reusable semantic vocabulary.
- Component states and exceptional presentation are composed inside
components.
- Builder-specific categorical meaning uses focused composite recipes,
not intent semantics or a larger global vocabulary.
- TypeScript validates public semantic CSS-variable names but does not
generate runtime colors.
- No token-manager dependency, compatibility aliases, or
component-specific public color tokens.
- A new semantic or theme variable is added only when existing semantics
and local composition cannot represent a reusable cross-feature
decision.

## Todo

### Color-system foundation

- [x] Establish direct CSS as the runtime source of truth.
- [x] Define bounded theme colors and contrast controls.
- [x] Derive light and dark modes from the same theme inputs.
- [x] Reduce the semantic inventory to reusable decisions and explicit
accessibility pairs.
- [x] Generate only TypeScript names for public semantic CSS variables.
- [x] Validate layers, references, cycles, consumption, naming,
generated types, and browser-computed contrast.
- [x] Add the Storybook color-system overview and theme controls.
- [x] Document the architecture and its relationship to the public Craft
specification.

### Design-system migration

- [x] Replace every active legacy color consumer in design-system
components and Storybook chrome.
- [x] Compose component states locally without component-specific public
tokens.
- [x] Preserve intentional preview and sample-content colors.
- [x] Add complete positive, negative, warning, informative, and accent
accessibility pairings.
- [x] Validate light and dark scheme-bound references independently.
- [x] Verify the design-system package with typecheck, lint, formatting,
Storybook, and 222 tests.

### Inventory and contract

- [x] Inventory all 319 legacy references across 107 Builder, Query
Builder, story, test, and design-system files.
- [x] Classify every reference as a direct semantic replacement, local
composite recipe, documented literal exception, or removable code.
- [x] Record the intentional authored-content, external-preview,
functional-preview, data-visualization, brand, and source-asset
exceptions.
- [x] Treat the public semantic vocabulary as closed by default and
justify any proposed addition by cross-feature reuse and accessibility
need.
- [x] Keep Builder code limited to typed public variables accepted by
`cssVar()`.

### Theme infrastructure

- [x] Add `system` (default), `light`, and `dark` application
preferences.
- [x] Persist the preference in existing client settings and resolve
`system` through `matchMedia`.
- [x] Apply the resolved scheme before paint and respond to
operating-system changes.
- [x] Expose the persisted theme control under **View → Color scheme**.
- [x] Keep authored canvas documents independent from the application
theme.
- [x] Ensure portals, overlays, embedded surfaces, and third-party
controls receive the correct interface scheme.

### Generic interface migration

- [x] Migrate shared dialogs, project settings, notifications, controls,
and Query Builder.
- [x] Migrate dashboard, authentication, publishing, and shared
application UI.
- [x] Migrate the Builder loading state, topbar, sidebars, navigator,
workspace, footer, settings, pages, alerts, and menus.
- [x] Replace fixed interface literals alongside their owning surfaces.
- [x] Remove the old scrollbar variable and hardcoded loading color.

### Style panel and style-source recipes

- [x] Migrate ordinary style-panel inputs, labels, layouts, spacing,
alignment, menus, property states, and value editors.
- [x] Model style-source provenance, kind, interaction, and error as
separate axes.
- [x] Compose categorical style-source colors from neutral and
accent-relative colors.
- [x] Use negative semantics only for actual errors, not overwritten
provenance.
- [x] Reuse one feature-owned recipe across style-source controls,
badges, menus, and values without adding global tokens.

### Canvas and editors

- [x] Migrate canvas selection, reusable outlines, grid guides, resize
handles, labels, badges, and overlays.
- [x] Keep collaborator colors as data visualization while guaranteeing
readable labels.
- [x] Prevent Builder theme values from leaking into authored content.
- [x] Migrate editor surfaces, selections, autocomplete, lint states,
and tooltips.
- [x] Derive syntax visualization from neutral and accent-relative
colors; reserve intent colors for diagnostics.

### Explicit color domains

- [x] Isolate external search and social previews from the application
scheme.
- [x] Preserve user-authored CSS values, functional color previews, and
checkerboards.
- [x] Review brand surfaces independently in both schemes.
- [x] Document every retained literal in the exception ledger.

### Stories, tests, and legacy removal

- [x] Migrate all affected Builder stories and tests.
- [x] Replace the design-system test that intentionally references the
legacy scale.
- [x] Add theme-preference and scheme-resolution behavior tests.
- [x] Remove the legacy `design-tokens.color` registry.
- [x] Remove the Stitches `colors` scale and `rawTheme.colors`.
- [x] Remove color-name conversion code that exists only for the legacy
scale.
- [x] Add a focused repository check that rejects legacy references.
- [x] Confirm no compatibility mappings or deprecated aliases remain.

### Browser-test infrastructure

- [x] Run pure Design System tests in Node and browser-dependent tests
in Vitest Browser Mode with Playwright Chromium.
- [x] Migrate all 79 Builder E2E workflows from the custom harness to
standard Playwright Test.
- [x] Replace filename-based shard discovery with standard Playwright
sharding.
- [x] Preserve clean-backend shard retries and upload Playwright failure
artifacts in CI.
- [x] Remove the custom runner, registry, and timeout infrastructure.

### Verification and documentation

- [x] Compare light-mode visual regressions directly with `main`; review
every difference rather than accepting snapshots wholesale.
- [x] Add representative dark coverage for dashboard, Builder shell,
style panel, dialogs, editors, canvas tools, and status states.
- [x] Test default and extreme custom-theme presets.
- [x] Verify semantic and categorical-recipe contrast.
- [x] Test first paint, persistence, system changes, portals, and canvas
isolation.
- [x] Run affected tests, typechecks, lint, formatting, and Storybook
checks.
- [x] Review fixture impact; no fixture inputs or generated outputs are
affected.
- [x] Review authoritative `docs/` content and update it where needed.
- [x] Review the final diff and make this checklist reflect delivered
scope.

## Current verification

- Design-system typecheck and generated-type freshness: passed.
- Design-system tests: 222 passed, including the full theme-parameter
contrast sweep and browser component coverage.
- Builder typecheck and production build: passed.
- Theme preference and scheme-resolution tests: 10 passed.
- Scoped Oxlint, formatting, and diff checks: passed.
- Design-system Storybook build and representative light/dark visual
review: passed.
- Builder E2E: 80/80 Playwright entries passed (setup plus 79
workflows).

Ref #3818
Closes #6267
2026-08-30 03:24:56 +01:00

213 lines
6.3 KiB
TypeScript

import { createServer } from "node:http";
import type { Page } from "@playwright/test";
import { selectCanvasTextInstance } from "./canvas-selection";
import { waitForChangeToBeSaved, waitForSyncStatus } from "./sync-status";
const getVariableForm = (page: Page) =>
page
.locator("form")
.filter({ has: page.locator('input[name="name"]') })
.last();
const closeVariablePanelAndWaitForSave = async ({ page }: { page: Page }) => {
const save = waitForChangeToBeSaved({ page });
await page.getByRole("button", { name: "Close" }).last().click();
await save;
await page
.getByText("New variable", { exact: true })
.waitFor({ state: "hidden" });
await waitForSyncStatus({ page, status: "idle" });
};
const openNewVariablePanel = async ({ page }: { page: Page }) => {
await page.getByRole("tab", { name: "Settings" }).click();
await page.getByRole("button", { name: "Add data variable" }).click();
await page.getByText("New variable", { exact: true }).waitFor();
};
const selectVariableType = async ({
page,
next,
}: {
page: Page;
next: string;
}) => {
await page
.getByText("Type", { exact: true })
.locator("xpath=following::button[1]")
.click();
await page
.getByRole("option", { name: new RegExp(`^${next}( Pro)?$`) })
.click();
};
const fillVariableName = async ({
page,
name,
}: {
page: Page;
name: string;
}) => {
await getVariableForm(page).locator('input[name="name"]').fill(name);
};
export const selectContentInstance = async ({ page }: { page: Page }) => {
await selectCanvasTextInstance({ page, text: "Initial content" });
await page
.getByText("No instance selected", { exact: true })
.waitFor({ state: "hidden" });
await page.getByRole("tab", { name: "Settings" }).click();
await page
.getByRole("button", { name: "Add data variable" })
.waitFor({ state: "visible" });
};
export const bindSelectedTextContentToExpression = async ({
page,
expression,
}: {
page: Page;
expression: string;
}) => {
await page.getByText("Text Content", { exact: true }).waitFor();
await page.getByText("Text Content", { exact: true }).hover();
await page
.getByText("Text Content", { exact: true })
.locator("xpath=following::button[@data-variant][1]")
.click();
const bindingDialog = page.getByRole("dialog", { name: "Binding" });
await bindingDialog.waitFor();
const expressionEditor = bindingDialog.locator(".cm-content").last();
await expressionEditor.click();
await page.keyboard.press("ControlOrMeta+A");
await page.keyboard.insertText(expression);
const save = waitForChangeToBeSaved({ page });
try {
await page.keyboard.press("ControlOrMeta+Enter");
await save;
} catch (error) {
const dialogText = await bindingDialog.innerText().catch(() => "");
throw new Error(
`Expected Text Content binding ${JSON.stringify(expression)} to save. Binding dialog: ${dialogText}`,
{ cause: error }
);
}
await waitForSyncStatus({ page, status: "idle" });
await page.keyboard.press("Escape");
};
export const createHttpResourceVariable = async ({
page,
name,
url,
}: {
page: Page;
name: string;
url: string;
}) => {
await openNewVariablePanel({ page });
await fillVariableName({ page, name });
await selectVariableType({ page, next: "Resource" });
await page.getByRole("textbox", { name: "URL" }).fill(url);
await closeVariablePanelAndWaitForSave({ page });
};
export const createGraphqlResourceVariable = async ({
page,
name,
url,
query,
}: {
page: Page;
name: string;
url: string;
query: string;
}) => {
await openNewVariablePanel({ page });
await fillVariableName({ page, name });
await selectVariableType({ page, next: "GraphQL" });
await page.getByRole("textbox", { name: "URL" }).fill(url);
await page.getByRole("textbox", { name: "Query" }).fill(query);
await closeVariablePanelAndWaitForSave({ page });
};
export const createSystemResourceVariable = async ({
page,
name,
resource = "Sitemap",
}: {
page: Page;
name: string;
resource?: "Sitemap" | "Current date" | "Assets";
}) => {
await openNewVariablePanel({ page });
await fillVariableName({ page, name });
await selectVariableType({ page, next: "System resource" });
if (resource !== "Sitemap") {
await getVariableForm(page)
.getByText("Resource", { exact: true })
.locator("xpath=following::button[1]")
.click();
await page.getByRole("option", { name: resource, exact: true }).click();
}
await closeVariablePanelAndWaitForSave({ page });
};
export const startJsonResourceServer = async ({ title }: { title: string }) => {
const server = createServer((_request, response) => {
response.writeHead(200, {
"Access-Control-Allow-Origin": "*",
"Content-Type": "application/json",
});
response.end(JSON.stringify({ title }));
});
await new Promise<void>((resolve, reject) => {
server.once("error", reject);
server.listen(0, "127.0.0.1", () => resolve());
});
const address = server.address();
if (address === null || typeof address === "string") {
await new Promise<void>((resolve) => server.close(() => resolve()));
throw new Error("Expected a numeric local resource server port.");
}
return {
url: `http://127.0.0.1:${address.port}/posts`,
close: async () =>
await new Promise<void>((resolve) => server.close(() => resolve())),
};
};
export const startGraphqlResourceServer = async ({
title,
}: {
title: string;
}) => {
const server = createServer((request, response) => {
if (request.method !== "POST") {
response.writeHead(405).end();
return;
}
response.writeHead(200, {
"Access-Control-Allow-Origin": "*",
"Content-Type": "application/json",
});
response.end(JSON.stringify({ data: { post: { title } } }));
});
await new Promise<void>((resolve, reject) => {
server.once("error", reject);
server.listen(0, "127.0.0.1", () => resolve());
});
const address = server.address();
if (address === null || typeof address === "string") {
await new Promise<void>((resolve) => server.close(() => resolve()));
throw new Error("Expected a numeric local GraphQL server port.");
}
return {
url: `http://127.0.0.1:${address.port}/graphql`,
close: async () =>
await new Promise<void>((resolve) => server.close(() => resolve())),
};
};