Align ColorCraft’s trust-sensitive copy and analysis behavior

[Artsen]

Summary

Align ColorCraft’s production behavior, contracts, documentation, and tests so measured results are clearly separated from design guidance. This change keeps the existing Create, Review, Export, and Library workflow while correcting upload-limit, contrast, temperature, suggestion, runtime-status, and SVG-label behavior.

Base commit: 22f41e35d2bcd721e8aec3826724b49077fe14fd

Trust and correctness problems corrected

• Aligns the browser’s visible and enforced upload boundary with the API’s existing 10 MB limit through one frontend constant. The shared validation is used by initial upload and change-image flows.
• Replaces palette “validation” overclaims with property-specific review and measurement language.
• Derives the shell’s Loopback only or LAN enabled badge from resolved backend runtime metadata instead of displaying a static claim.
• Chooses black or white SVG swatch labels using measured relative-luminance contrast rather than an HSL-lightness cutoff.
• Qualifies generated color suggestions as transformations and optional design directions rather than measured palette quality.

Contract changes

Breaking response changes are intentional and applied across Pydantic models, Zod schemas, TypeScript consumers, tests, and documentation:

• HarmonySuggestion.mood / mood is removed and replaced by common_associations / commonAssociations. No hidden legacy field is retained.
• Temperature responses add transitional_count / transitionalCount and transitional_ratio / transitionalRatio.
• Temperature balance removes balanced and now permits warm, transitional, cool, mixed, or neutral.
• Application metadata adds the required machine-readable network_mode / networkMode field with loopback or lan.

The existing extraction and analysis envelope shapes remain intact. The static dashboard manifest remains compatible; live metadata is authoritative for network exposure.

Contrast behavior changes

• Adds a typed text, nonText, or focus discriminator to each role check.
• Text checks retain AA/AAA thresholds of 4.5:1, 3:1, 7:1, and 4.5:1.
• Border checks show only a 3:1 non-text component-color result and explain that other component requirements are not evaluated.
• Focus checks show only a 3:1 adjacent-color result for both page and surface contexts and explicitly exclude size, area, thickness, visibility, and focused-versus-unfocused appearance.
• The advanced matrix is explicitly labeled as all-pairs text-contrast exploration.
• Shared vectors verify frontend ratios and thresholds against backend-known values.

Temperature behavior changes

Every meaningful chromatic hue now belongs to exactly one category:

• warm: 300–360 and 0–60 degrees
• transitional: greater than 60 and less than 120 degrees
• cool: 120 through less than 300 degrees

Low-saturation colors remain excluded. Ratios use the total categorized chromatic count. A category is dominant only above 70%; otherwise the result is mixed. neutral means there is no meaningful chromatic evidence.

Suggestion-language changes

Suggestion descriptions now lead with measured hue, saturation, or lightness transformations. The UI uses Common associations and Common applications, explains that suitability depends on context and assigned roles, and directs users to review role contrast before use.

Runtime metadata changes

GET /metadata now reports networkMode from the resolved web/API hosts, allowed origins, and configured browser API URL. The shell exposes the result accessibly as Loopback only or LAN enabled, with a factual unavailable fallback if metadata cannot be read.

Validation

Passed the complete repository gate from the committed LF-clean tree:

python check.py
[1] frontend format
[2] frontend lint
[3] frontend typecheck
[4] frontend coverage — 78 passed, 91.46% statements
[5] frontend build
[6] backend format
[7] backend lint
[8] backend typecheck
[9] backend tests and coverage — 69 passed, 86% total
[10] browser E2E and accessibility — 3 passed
ColorCraft validation passed.

Additional checks:

• deterministic screenshot workflow: 1 passed
• git diff --check: passed
• axe covers changed Review Contrast and Suggestions states, plus representative Create and Library states
• upload tests cover immediately below, exactly at, and immediately above 10 MB
• assigned ports remain disjoint from Web Video Optimizer: ColorCraft 5174/4100; WVO 5173/4000

Screenshots

Review Overview and runtime status

Typed role contrast

Qualified suggestions

Remaining limitations

• Contrast checks measure selected color pairs only; they do not prove complete WCAG conformance or overall component accessibility.
• Focus checks do not evaluate geometry or state transitions.
• Suggestions remain conventional design guidance, not aesthetic scoring.
• Temperature classification is an HSL-category heuristic; displayed ratios are rounded.
• LAN mode remains an explicit trusted-network configuration without authentication, which is unchanged and outside this PR.