browser/openspec/changes/polish-theme-frame-accessories/specs/platform-web-theme-accessories/spec.md

platform-web-theme-accessories Specification

ADDED Requirements

Requirement: Theme frame accessories

Shared platform web framed surfaces SHALL render theme-specific ornamental accessories.

Scenario: Black mecha theme is active

• WHEN the active palette is mecha-black
• THEN shared framed surfaces include mecha accessory motifs such as spacecraft, robot hardware, radar, planet, or cockpit details
• AND the motifs are provided through shared theme variables rather than page-local decorative DOM

Scenario: Magical-girl theme is active

• WHEN the active palette is magical-girl
• THEN shared framed surfaces include magical accessory motifs such as hearts, stars, magic wands, ribbons, or magic circles
• AND the motifs are provided through shared theme variables rather than page-local decorative DOM
• AND repeated sibling items rotate through distinct motifs instead of repeating one identical accessory
• AND each framed item uses one compact edge badge rather than multiple oversized illustrations

Requirement: Navigation active frame accessories

Active sidebar navigation entries SHALL inherit the active theme's frame accessory language.

Scenario: User changes theme while a route is active

• WHEN a sidebar route is active
• AND the user switches between first-party themes
• THEN the active sidebar frame changes accessory motifs to match the selected theme
• AND route order and labels remain unchanged

Requirement: Live theme isolation

Theme switching SHALL replace the complete active palette without retaining visual variables or shell labels from the previous palette.

Scenario: User switches from magical-girl to black mecha

• WHEN the active palette is magical-girl
• AND the user selects mecha-black
• THEN the root theme marker, shared surface materials, sidebar subtitle, and palette strip update to black mecha immediately
• AND magical-girl accessory variables from the previous palette do not remain active on mecha surfaces

Requirement: Single frame ownership

An operational content region SHALL render at most one ornamental frame at each visual hierarchy level.

Scenario: State view is nested inside a shared framed surface

• WHEN an empty, loading, or error state is rendered inside a console-panel, card, table wrapper, plugin group, or operation item
• THEN the parent surface retains the active theme frame and accessory
• AND the nested state view renders as unframed content without a second border, panel fill, or accessory pseudo-element

Requirement: Uploaded background frame visibility

Uploaded backgrounds SHALL remain visually legible while preserving the selected theme's frame identity.

Scenario: Magical-girl theme uses an uploaded background

• WHEN the active palette is magical-girl
• AND the user has configured an uploaded background
• THEN shared foreground surfaces use translucent neutral-pink crystal glass rather than an opaque maroon color mask
• AND the uploaded image remains recognizable behind the foreground surfaces
• AND compact heart, star, wand, moon, ribbon, crystal, and magic-circle accessories visibly cross the panel border instead of being hidden inside the panel
• AND accessory pseudo-elements do not add a color wash over the configured background

Scenario: Magical-girl theme uses a built-in background

• WHEN the active palette is magical-girl
• AND no uploaded background is configured
• THEN shared framed surfaces retain compact, immediately visible magical accessories that extend beyond their borders without crowding content