4.2 KiB
4.2 KiB
Module Contracts: Frontend Style Unification
[DEF:FrontendStyleSystem:Module]
@TIER: CRITICAL
@PURPOSE: Define and enforce unified visual primitives and page-shell rules across targeted frontend routes.
@RELATION: DEPENDS_ON -> [DEF:Std:UI_Svelte:Standard]
@RELATION: DEPENDS_ON -> [DEF:Std:Semantics:Standard]
@RELATION: BINDS_TO -> [DEF:StyleTokenGroup:Block]
@RELATION: BINDS_TO -> [DEF:UIPatternRule:Block]
@PRE: Target routes/components for unification are identified and included in scope.
@PRE: Existing behavior-critical user flows remain available for validation.
@POST: Shared visual primitives and shell patterns are applied consistently in targeted scope.
@POST: No critical functional flow is removed by style refactor.
@UX_STATE: Default -> Users see consistent hierarchy (title/actions/content) across targeted pages.
@UX_STATE: Loading -> Loading visuals appear in consistent zones without disruptive layout jumps.
@UX_STATE: Error -> Error blocks use consistent emphasis and include a clear recovery action.
@UX_STATE: Success -> Confirmation messages follow one tone/placement pattern.
@INVARIANT: Unified styling must not regress accessibility-visible focus and readable contrast behavior.
[/DEF:FrontendStyleSystem:Module]
[DEF:RouteShellContract:Component]
@TIER: CRITICAL
@PURPOSE: Standardize route shell structure for primary pages (dashboards, tasks, reports, settings).
@RELATION: DEPENDS_ON -> [DEF:FrontendStyleSystem:Module]
@PRE: Route provides title context and action area metadata.
@POST: Route renders canonical shell order: context/breadcrumbs, title block, action region, content container.
@UX_STATE: Default -> Primary action location is discoverable quickly and consistently.
@UX_STATE: Empty -> Empty-state container is visually aligned with shell and includes next-step guidance.
@UX_RECOVERY: Empty -> User can recover using explicit action (refresh/filter adjust/create flow).
[/DEF:RouteShellContract:Component]
[DEF:StateFeedbackContract:Component]
@TIER: CRITICAL
@PURPOSE: Normalize loading/empty/error/success feedback rendering and wording across modules.
@RELATION: DEPENDS_ON -> [DEF:StatePresentationPattern:Block]
@PRE: Module can expose current state category (loading/empty/error/success).
@POST: State-specific UI uses canonical placement, tone, and recovery behavior.
@UX_STATE: Loading -> Consistent indicator style and placement with stable layout rhythm.
@UX_STATE: Empty -> Neutral message + guidance action rendered in standard block.
@UX_STATE: Error -> Actionable error messaging with retry/fix path.
@UX_STATE: Success -> Concise confirmation in standard visual language.
@UX_FEEDBACK: Error -> Emphasis clearly distinguishes failure from neutral status.
@UX_RECOVERY: Error -> Retry or corrective action is always visible when recoverable.
@INVARIANT: State texts use canonical terminology and remain i18n-compatible.
[/DEF:StateFeedbackContract:Component]
[DEF:TerminologyConsistencyContract:Module]
@TIER: STANDARD
@PURPOSE: Keep user-facing wording consistent across page shells and state blocks.
@RELATION: DEPENDS_ON -> [DEF:Std:Constitution:Standard]
@PRE: Canonical term list for targeted flows is defined.
@POST: Targeted modules avoid mixed synonyms for the same concept.
@UX_STATE: Default -> UI labels and status texts remain concise and confidence-building.
@INVARIANT: User-facing text remains compatible with existing localization workflow.
Contract Usage Simulation (Key Scenario)
[/DEF:TerminologyConsistencyContract:Module]
Scenario: User navigates from dashboards to reports and encounters a failed data load.
RouteShellContractensures both pages keep identical shell rhythm and action placement.FrontendStyleSystemensures shared primitives (spacing/typography/cards/buttons) are consistent.StateFeedbackContractrenders failure using canonical error block with explicit retry action.TerminologyConsistencyContractensures error wording and action labels are aligned across pages.
Continuity Check: No interface mismatch detected between shell-level structure and state-level feedback contracts.