egg/DashBoard
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
main
DashBoard/openspec/specs/style-isolation-and-token-enforcement/spec.md
egg 7cb0985b12 feat(modernization): full architecture blueprint with hardening follow-up 
Implement phased modernization infrastructure for transitioning from
multi-page legacy routing to SPA portal-shell architecture, plus
post-delivery hardening fixes for policy loading, fallback consistency,
and governance drift detection.

Key changes:
- Add route contract enrichment with scope/visibility/compatibility policies
- Canonical 302 redirects from legacy direct-entry to /portal-shell/ routes
- Asset readiness enforcement and runtime fallback retirement for in-scope routes
- Shared feature-flag helpers (env > config > default) replacing duplicated _to_bool
- Defensive copy for lru_cached policy payloads preventing mutation corruption
- Unified retired-fallback response helper across app and blueprint routes
- Frontend/backend route-contract cross-validation in governance gates
- Shell CSS token fallback values for routes rendered outside shell scope
- Local-safe .env.example defaults with production recommendation comments
- Legacy contract fallback warning logging and single-hop redirect optimization

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 11:26:02 +08:00

2.6 KiB
Raw Permalink Blame History

style-isolation-and-token-enforcement Specification

Purpose

TBD - created by archiving change full-modernization-architecture-blueprint. Update Purpose after archive.

Requirements

Requirement: In-scope pages SHALL enforce style isolation boundaries

In-scope modernization pages SHALL avoid page-global selectors for page-local concerns and SHALL keep style concerns scoped to route-level containers or shared design-system layers.

Scenario: Global selector control

  • WHEN style governance checks analyze in-scope page styles
  • THEN page-local style changes SHALL NOT introduce new :root or body rules for route-local presentation concerns
  • THEN shared cross-route concerns SHALL be authored in designated shared style layers

Requirement: In-scope shared semantics SHALL be token-first

Shared UI semantics in in-scope routes SHALL be implemented with token-backed Tailwind/shared-style primitives before page-local overrides are allowed.

Scenario: Token-first UI pattern adoption

  • WHEN an in-scope route introduces or updates shared UI semantics (layout shell, card, filter, action, status)
  • THEN the route SHALL consume token-backed shared primitives
  • THEN page-local hard-coded visual values SHALL require explicit exception justification

Requirement: Legacy style exceptions SHALL be tracked and sunset

Legacy CSS exceptions for in-scope routes SHALL be tracked with ownership and removal milestones.

Scenario: Exception registry requirement

  • WHEN an in-scope route cannot yet remove legacy style behavior
  • THEN the route SHALL be registered with an exception owner and planned removal milestone
  • THEN unresolved exceptions past milestone SHALL fail modernization governance review

Requirement: Route-local token usage SHALL include fallback values outside shell scope

Route-level styles that reference shell-provided token variables SHALL define fallback values to preserve rendering correctness when rendered outside shell variable scope.

Scenario: Route rendered outside portal shell variable scope

  • WHEN a route-local stylesheet references shell token variables and the page is rendered without shell-level CSS variables
  • THEN visual-critical properties (for example header gradients) SHALL still resolve through explicit fallback token values

Scenario: Style governance check for unresolved shell variables

  • WHEN style-governance validation inspects in-scope route styles
  • THEN unresolved shell-variable references without fallback SHALL be flagged as governance failures or approved exceptions