76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# [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:
|
|
```html
|
|
<!-- [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]
|