color_schema_commit pins the correction to the exported color pattern. Migration map.

design_theme_apply — set tone and primary colors

Apply the requested tone and/or primary color changes together. Read design_theme_get first and copy its target code and revision. Tone changes, color changes, and resets are options of this tool; they do not require separate business methods.

Input

Supply at least one of tone, brandColor, or onBrandColor, even if its value already matches. The object is strict; extra fields and null are invalid. Named colors, whitespace, alpha hex colors, and lowercase tone names are invalid.

Earlier workflow validation already accepted both cases, but its case-insensitive regex flag was absent from the exported JSON Schema.

A connected server may still run an earlier revision. Inspect that server's discovery schema; if it advertises the older lowercase-only color pattern, use lowercase hex digits for a new request. Keep the exact saved inputs when resuming an existing request ID.

{
  "requestId":"example-theme-change-001",
  "channelCode":"selected-channel-code",
  "expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000",
  "tone":"LIGHT",
  "brandColor":"#123",
  "onBrandColor":"#ffffff",
  "dryRun":true
}

The code and zero revision are placeholders. Replace them with actual values from the current get result; this example is not an executed transcript. Inspect the plan, then preserve the ID and all business inputs and change only dryRun to false.

Preservation, reset, and normalization

Omission preserves the corresponding tone/color. A tone change does not clear custom colors. To restore a tone's default color, explicitly send an empty string for that color; the workflow stores an empty value rather than deleting the palette key. Other palette keys remain in the complete palette submitted to the service.

Comparison and revision calculation normalize equivalent hex representations. Replacing #123 with #112233 can be a no-op even though the input spelling differs. A saved task's fingerprint still uses its exact parsed input, so do not change color notation, revision, or other inputs while reusing its request ID.

Plan and execution

The access requirements match the get tool: current connection, matching selected channel, OWNER/DELEGATEE account role, selected-channel credential, and configured CHANNEL_ENV origin. Hosted calls must use the bound selected channel.

For a new request, the workflow checks expectedRevision against the current theme. It initializes missing settings only during real execution, then derives the requested changes from the returned initial settings. It applies a necessary tone patch before a necessary palette patch, reading after each step and finally comparing the full expected theme.

Theme initialization is POST /seller/api/v1/channel-management/custom with {}. Updates use PUT /seller/api/v1/channel-management/custom/experimentals with a tone or complete preserved-palette patch. These requests use the CHANNEL_ENV origin, selected channel bearer and channel-ID header. The tool does not refresh credentials or publish a separate site release.

The calls are sequential, not a server transaction. Revision checks detect observed conflicts, but do not atomically prevent an external editor from writing between the last read and a write. Earlier changes can remain after a later failure. No automatic rollback is provided.

Plan and completion payloads

The completed theme view contains initialized, revision, tone, both stored colors, and both effective colors described by the get tool. changed means the saved plan contains at least one tone/palette step, not that this call necessarily sent a write. changed:false can still follow initialization of previously absent settings; it is not a guarantee of zero side effects. A non-demo result can include the theme console link.

A completed replay returns the stored historical theme result. Apply/resume still resolve the channel context before returning it, but do not freshly verify the theme. Use get for present values. Readback establishes the expected stored state, not causal attribution, visitor rendering, or effective access.

Recovery and failures

Use the original ID and taskType:design-theme with task_status and, when continuing the original operation, task_resume. Preserve the original connection, channel, inputs and job storage. A new dry run has no saved job.

Definite rejected/not-sent update failures restore the affected step to prepared. Unknown or unclassified failures retain the uncertain state. Status returns the phase, saved step-state array and last result; pending does not mean a background worker is running.

Other access, origin, connection and HTTP failures follow the get tool's rules. Internal failures can include phase and completedSteps; outer failures may omit them. An error's outcome describes the failed request, not a guarantee that earlier steps made no changes. Do not generate a new request ID to force an uncertain change to repeat.

Saved plan replay

An existing matching task's dryRun returns historical saved plan/progress, historical:true, replayed:true and false current verification. It has no current console/action link and does not read present business state, repeat effects or change the journal. Saved phase/progress and existingPhase aliases remain where applicable. Follow nextStep for a current observation; retain the original task ID for uncertain-outcome recovery. A new task keeps normal fresh-plan validation.

nextStep: design_theme_get retains the original channel; saved tone/palette steps are not a fresh theme read.

Saved record identity

For this workflow, existing apply/dry-run calls and task status/resume require both the saved task ID and saved input requestId to match the requested ID. A mismatching or malformed saved identity returns TASK_STATE_UNVERIFIED before workflow context or business-state reads. Preserve the original record for inspection; do not rename/edit it, try its embedded ID or create a replacement request to bypass the error. No stored record is repaired or resent. Valid matching records retain the recovery behavior described above.

Saved step consistency

Existing theme tasks must retain the original input fingerprint, derived ordered patches, preserved palette values, progress and expected final state. Inconsistent records return TASK_STATE_UNVERIFIED before context/business calls and remain unchanged. Generic missing/invalid completion still uses TASK_COMPLETION_UNVERIFIED. Historical success is not a fresh theme observation.

Inputs