busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

semantics

Browse Source
This commit is contained in:
busya
2026-03-27 21:27:31 +03:00
parent 7c85552132
commit 2ed66bfebc
182 changed files with 21186 additions and 10254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
specs/001-unify-frontend-style/contracts/modules.md
View File

@@ -1,65 +1,79 @@
# 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]
@RELATION: DEPENDS_ON -> [DEF:Std:Semantics]
@RELATION: BINDS_TO -> [DEF:StyleTokenGroup:Entity]
@RELATION: BINDS_TO -> [DEF:UIPatternRule:Entity]
@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]
# @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: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: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:StateFeedbackContract:Component]
@TIER: CRITICAL
@PURPOSE: Normalize loading/empty/error/success feedback rendering and wording across modules.
@RELATION: DEPENDS_ON -> [DEF:StatePresentationPattern:Entity]
@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: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:TerminologyConsistencyContract:Module]
@TIER: STANDARD
@PURPOSE: Keep user-facing wording consistent across page shells and state blocks.
@RELATION: DEPENDS_ON -> [DEF:Std:Constitution]
@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.
# [/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.
1. `RouteShellContract` ensures both pages keep identical shell rhythm and action placement.
@@ -67,4 +81,4 @@
3. `StateFeedbackContract` renders failure using canonical error block with explicit retry action.
4. `TerminologyConsistencyContract` ensures error wording and action labels are aligned across pages.
**Continuity Check**: No interface mismatch detected between shell-level structure and state-level feedback contracts.
**Continuity Check**: No interface mismatch detected between shell-level structure and state-level feedback contracts.