ss-tools/.ai/standards/ui_design.md

[DEF:Std:UI_Svelte:Standard]

@TIER: CRITICAL

@PURPOSE: Unification of all Svelte components following GRACE-Poly (UX Edition).

@LAYER: UI

@INVARIANT: Every component MUST have <!-- [DEF:] --> anchors and UX tags.

@INVARIANT: Use Tailwind CSS for all styling (no custom CSS without justification).

1. UX PHILOSOPHY: RESOURCE-CENTRIC & SVELTE 5

• Version: Project uses Svelte 5.
• Runes: Use Svelte 5 Runes for reactivity: $state(), $derived(), $effect(), $props(). Traditional let (for reactivity) and export let (for props) are DEPRECATED in favor of runes.
• Definition: Navigation and actions revolve around Resources.
• Traceability: Every action must be linked to a Task ID with visible logs in the Task Drawer.

2. COMPONENT ARCHITECTURE: GLOBAL TASK DRAWER

• Role: A single, persistent slide-out panel (GlobalTaskDrawer.svelte) in +layout.svelte.
• Triggering: Opens automatically when a task starts or when a user clicks a status badge.
• Interaction: Interactive elements (Password prompts, Mapping tables) MUST be rendered INSIDE the Drawer, not as center-screen modals.

3. COMPONENT STRUCTURE & CORE RULES

• Styling: Tailwind CSS utility classes are MANDATORY. Minimize scoped <style>.
• Localization: All user-facing text must use $t from src/lib/i18n.
• API Calls: Use requestApi / fetchApi wrappers. Native fetch is FORBIDDEN.
• Anchors: Every component MUST have <!-- [DEF:] --> anchors and UX tags.

2. COMPONENT TEMPLATE

Each Svelte file must follow this structure:

<!-- [DEF:ComponentName:Component] -->
<script>
  /**
   * @TIER: [CRITICAL | STANDARD | TRIVIAL]
   * @PURPOSE: Brief description of the component purpose.
   * @LAYER: UI
   * @SEMANTICS: list, of, keywords
   * @RELATION: DEPENDS_ON -> [OtherComponent|Store]
   * 
   * @UX_STATE: [StateName] -> Visual behavior description.
   * @UX_FEEDBACK: System reaction (e.g., Toast, Shake).
   * @UX_RECOVERY: Error recovery mechanism.
   * @UX_TEST: [state] -> {action, expected}
   */
  import { ... } from "...";
  
  // Exports (Props)
  export let prop_name = "...";
  
  // Logic
</script>

<!-- HTML Template -->
<div class="...">
  ...
</div>

<style>
  /* Optional: Local styles using @apply only */
</style>
<!-- [/DEF:ComponentName:Component] -->

2. STATE MANAGEMENT & STORES

• Subscription: Use $ prefix for reactive store access (e.g., $sidebarStore).
• Data Flow: Mark store interactions in [DEF:] metadata:
  • # @RELATION: BINDS_TO -> store_id

3. UI/UX BEST PRACTICES

• Transitions: Use Svelte built-in transitions for UI state changes.
• Feedback: Always provide visual feedback for async actions (Loading spinners, skeleton loaders).
• Modularity: Break down components into "Atoms" (Trivial) and "Orchestrators" (Critical).

4. ACCESSIBILITY (A11Y)

• Ensure proper ARIA roles and keyboard navigation for interactive elements.
• Use semantic HTML tags (<nav>, <header>, <main>, <footer>).

[/DEF:Std:UI_Svelte]