# **SYSTEM UI/UX Specification**

## 1. Introduction

This document defines the user experience goals, information architecture, user flows, and visual design specifications for the **SYSTEM** user interface. It serves as the foundation for visual design and frontend development, ensuring a cohesive and user-centered experience that aligns with the project's unique thematic and technical requirements.

### Overall UX Goals & Principles

*   **Target User Personas:**
    *   **The "Initiator":** The first user, responsible for setting up the "Община". Values clarity and a straightforward setup process.
    *   **The "Citizen":** A tech-savvy member of a high-trust community. Values efficiency for daily tasks, absolute transparency in financial matters, and an engaging, unique user experience.
*   **Usability Goals:**
    *   **Efficiency:** Common tasks like creating a "Cell" must be low-friction and achievable in minimal steps.
    *   **Trust & Transparency:** The UI must visually reinforce the integrity of the underlying cryptographic ledger. Users should "feel" the security and immutability.
    *   **Learnability:** The system's unique concepts ("Cells", "The Vault") must be explained through clear, intuitive interfaces and onboarding cues.
*   **Design Principles:**
    1.  **Clarity over Concealment:** Be explicit about processes. Show when a transaction is signed, when it's pending, and when it's finalized.
    2.  **Thematic Integrity:** The UI should consistently reflect the chosen retro-futuristic, dystopian/communistic aesthetic through terminology, typography, and color.
    3.  **Seamless Security:** Make the act of cryptographic signing feel powerful, not tedious.
    4.  **Mobile-First & Responsive:** The experience must be flawless on both mobile and desktop browsers.

### Change Log

| Date | Version | Description | Author |
| :--- | :--- | :--- | :--- |
| 2025-08-31 | 1.0 | Initial UI/UX Spec draft | UX Expert (Sally) |

---

## 2. Information Architecture (IA)

### Site Map / Screen Inventory

The SYSTEM application is a single-page application (SPA) with distinct views managed by a router. The information architecture is designed to be flat and task-oriented, ensuring Citizens can access key functions quickly.

```mermaid
graph TD
    A[Entry Point] --> B{Is Община Created?};
    B -->|No| C[Onboarding (Create Община)];
    B -->|Yes| D{Is Citizen Authenticated?};
    C --> F[Dashboard];

    D -->|No| E{Has Invite Token?};
    D -->|Yes| F;

    E -->|Yes| G[Onboarding (Join Община)];
    E -->|No| H[Authentication View];
    G --> F;
    H --> F;

    F --> F1[Active "Cells" List];
    F --> F2[Create "Cell" Button];
    F1 --> I[Cell Detail View];
    F2 --> J[Create "Cell" Form];

    F --> K[Profile & Settings];
    K --> L[Vault Management];
    K --> M[Social Recovery View];
```

### Navigation Structure

*   **Primary Navigation:** Since this is a focused application, there will be no complex primary navigation bar. The main "Dashboard" will serve as the root view. A single icon or user avatar in the corner will lead to the "Profile & Settings" area.
*   **Breadcrumb Strategy:** Not required for the MVP due to the flat architecture. Context will be maintained within the views themselves (e.g., "Cell Detail View" will clearly display the "Common Good" it belongs to).

---

## 3. User Flows

### Flow 1: Onboarding the First Citizen (Initiator)

*   **User Goal:** To set up the "Община" and create their own identity.
*   **Entry Points:** Accessing the root URL of the self-hosted application for the first time.
*   **Success Criteria:** The user has successfully created an identity, saved their private key, and is logged into the main dashboard.

```mermaid
graph TD
    A[User opens the app] --> B{Is `Registry` table empty?};
    B -->|Yes| C[Show "Create Община" screen];
    C --> D[User clicks "Create"];
    D --> E[Client-side: Generate key pair];
    E --> F[Show Private Key with strong warnings];
    F --> G[User confirms they saved the key];
    G --> H[Ask for Citizen's name];
    H --> I[User enters name and submits];
    I --> J[Sign `CITIZEN_CREATED` transaction];
    J --> K[Send to server];
    K --> L[Server validates & saves to Ledger];
    L --> M[Redirect to Dashboard];

    B -->|No| N[Show Authentication View];
```

### Flow 2: Creating and Participating in a "Cell"

*   **User Goal:** To initiate a shared expense and have others join and pay their share.
*   **Entry Points:** Clicking the "Create Cell" button on the Dashboard.
*   **Success Criteria:** The "Cell" is created, participants have joined, and all payments are confirmed by the "Executors".

```mermaid
graph TD
    subgraph Citizen A (Initiator)
        A[Clicks "Create Cell"] --> B[Fills out "Cell" details: purpose, items, costs];
        B --> C[Submits form];
        C --> D[Signs `CREATE_CELL` transaction];
        D --> E[Cell appears on Dashboard];
    end

    subgraph Citizen B (Executor)
        F[Sees new "Cell" on Dashboard] --> G[Opens "Cell" details];
        G --> H[Clicks "Become Executor" for an item];
        H --> I[Signs `JOIN_AS_EXECUTOR` transaction];
    end

    subgraph Citizen C (Consumer)
        J[Opens "Cell" details] --> K[Sees calculated share];
        K --> L[Clicks "Join as Consumer"];
        L --> M[Signs `JOIN_AS_CONSUMER` transaction];
        M --> N[Physically sends money to Citizen B];
    end

    subgraph Citizen B (Executor)
        O[Receives money] --> P[Clicks "Confirm Payment" for Citizen C];
        P --> Q[Signs `CONFIRM_PAYMENT` transaction];
        Q --> R[UI updates to show debt is cleared];
    end
```

---

## 4. Wireframes & Mockups

*   **Primary Design Files:** Since this is a developer-led project, we will not use external design tools like Figma. The **UI/UX Specification** and the **PrimeVue component documentation** will serve as the primary source of truth for design. The final look and feel will be a direct result of applying the defined theme (`Aura`), typography, and color palette to the PrimeVue components.

### Key Screen Layouts

*   **Dashboard View:**
    *   **Purpose:** To provide a central overview of all active financial matters.
    *   **Key Elements:**
        1.  A prominent "Create Cell" button.
        2.  A list/grid of active "Cells", each showing its title, total amount, and progress (e.g., "3/5 participants confirmed").
        3.  A summary panel showing what "I Owe" and what "Is Owed to Me".
        4.  A corner link/icon to access the "Profile & Settings" page.
    *   **Interaction Notes:** Clicking a "Cell" card navigates to its `Cell Detail View`.
*   **Cell Detail View:**
    *   **Purpose:** To show a complete, transparent breakdown of a single shared expense.
    *   **Key Elements:**
        1.  Header with the "Common Good" title and total value.
        2.  A section for "Executors", listing who is buying what, and for how much.
        3.  A section for "Consumers", showing each person's share and their payment status relative to each Executor (e.g., "Owes 50 to Citizen B"). A "Confirm Payment" button is visible here for Executors.
        4.  A simple, immutable log of all transactions related to this "Cell", pulled directly from "The Main Ledger".
    *   **Interaction Notes:** The view is dynamic, updating in real-time as new transactions are confirmed.
*   **Profile & Settings View:**
    *   **Purpose:** To manage Citizen identity and application settings.
    *   **Key Elements:**
        1.  Display of the Citizen's name and their full public key.
        2.  A button to copy the public key.
        3.  A section to manage the "Vault" (create a vault account, initiate recovery).
        4.  (Post-MVP) A section for notification preferences.

## 5. Component Library / Design System

*   **Design System Approach:** We will adopt a **Component-Driven** approach using **PrimeVue** as our core component library. We will not build basic components (buttons, inputs) from scratch. Instead, we will use PrimeVue components and customize them globally using the `Aura` theme, Tailwind CSS utilities, and custom SCSS.
*   **Core Components (PrimeVue):**
    *   **Button:** For all clickable actions (`p-button`).
    *   **InputText, InputNumber, Textarea:** For all forms (`p-inputtext`, etc.).
    *   **Card, Panel:** To encapsulate sections like "Cell" overviews on the dashboard (`p-card`, `p-panel`).
    *   **DataTable, DataView:** To display lists of participants and transactions (`p-datatable`).
    *   **Toast:** For non-blocking notifications (e.g., "Transaction Signed") (`p-toast`).
    *   **Dialog:** For modal confirmations (`p-dialog`).

---

## 6. Branding & Style Guide

*   **Visual Identity:** The brand identity is "SYSTEM" — a blend of retro-futuristic console, dystopian minimalism, and communistic propaganda aesthetics. It should feel functional, slightly stark, but highly trustworthy.
*   **Color Palette:**
    *   We will use the **Aura theme from PrimeVue** as the base. The theme's default colors provide a modern, clean look that can be subtly customized.
*   We will define a primary accent color for all interactive elements to align with the "SYSTEM" theme. Let's start with a strong but not overpowering red.

| Color Type | Hex Code (Example) | Usage | 
| :--- | :--- | :--- |
| Primary | `#BF3636` (A deep red) | Buttons, links, active states, key highlights |
| Surface | Aura Theme Defaults | Backgrounds, cards, panels (e.g., `surface-0` to `surface-900`) |
| Text | Aura Theme Defaults | Primary and secondary text colors |
| Success | `#22C55E` (Green) | Confirmation messages, success states |
| Warning | `#F59E0B` (Amber) | Non-critical alerts, warnings |
| Error | `#EF4444` (Red) | Error messages, destructive action confirmations |
*   **Typography:**
    *   **Primary Font:** `Inter` (already configured in `nuxt.config.ts`). This is a clean, modern, and highly readable sans-serif font that works well for UI.
    *   **Monospace Font:** We will add a standard monospace font (e.g., `Fira Code`, `JetBrains Mono`) for displaying cryptographic data like keys and hashes to reinforce the "console" aesthetic.
*   **Iconography:**
    *   **Icon Library:** `primeicons` (comes with PrimeVue).
    *   **Usage Guidelines:** Icons should be used sparingly and functionally to guide the user, not for decoration.

## 7. Accessibility Requirements

*   **Compliance Target:** The application will adhere to **WCAG 2.1 Level AA** standards.
*   **Key Requirements:**
    *   **Visual:** All text must meet a 4.5:1 contrast ratio against its background. All interactive elements must have clear focus indicators.
    *   **Interaction:** The entire application must be navigable and operable using only a keyboard. All components must be screen-reader friendly.
    *   **Content:** All form inputs must have associated labels. Dynamic content updates must be announced to screen readers.

## 8. Responsiveness Strategy

*   **Breakpoints:** We will use the default Tailwind CSS breakpoints (`sm`, `md`, `lg`, `xl`, `2xl`), which provide a robust mobile-first foundation.
*   **Adaptation Patterns:**
    *   **Layout:** On mobile, use a single-column layout. On larger screens, transition to multi-column layouts (e.g., dashboard with a side panel for settings).
    *   **Navigation:** Mobile navigation will be handled by a slide-out panel or a tab bar if needed. Desktop will have a simple, persistent sidebar.
    *   **Data Display:** Tables (`p-datatable`) will switch to a stacked "card" layout on mobile for better readability.

---