@hacksur/native-design-system v0.0.1-70fa88f3d4d0

Nobak Native Design System

Overview

The Nobak Native Design System is a comprehensive UI component library designed to provide consistent, reusable, and accessible components for Nobak applications.

Component Documentation Status

See COMPONENT_STATUS.md for the complete and up-to-date documentation and implementation status of all components in the design system.

Chat & Transaction UI Components

ChatBubble

Renders a single chat message bubble, supporting different styles for sent/received messages and optional attachments.

ChatContainer

The root conversational interface, orchestrating message flow and embedding all chat-related components. Integrates MessageList, ChatInput, QuickActionBar, ChatLoading, and ChatEmptyState.

ChatInput

Input field for sending chat messages, commands, or initiating transactions. Supports attachments and command suggestions.

TransactionCard

Displays a summary of a transaction, including asset, amount, counterparty, and status.

ConversationHeader

Header for a chat or transaction conversation, showing participant info and context actions.

QuickActionBar

Toolbar providing shortcuts to frequent chat or transaction actions (e.g., send, request, swap).

StellarTransactionPreview

Preview of a Stellar network transaction, showing operations, fees, and expected results before confirmation.

ChatEmptyState

Visually communicates an empty or starting state in the chat wallet, guiding users to begin a conversation or transaction.

ChatLoading

Indicates loading or processing states within the chat interface, ensuring users are aware of ongoing operations.

IntentChip

Represents suggested intents or actions in a compact, tappable format, streamlining conversational workflows and transaction initiation.

Component Stories

Components by Category

Existing Core Components

• AccountActions: A control panel displaying account balance and providing quick access to core financial actions such as deposit, withdraw, and swap.
• AccountCard: Presents user account details, including name, public key, balance, and status indicators, in a visually organized card format.
• AppCard: Showcases application information or app-related content with a title, description, and optional call-to-action.
• Button: A versatile, accessible button supporting multiple variants and sizes for triggering user actions throughout the app.
• Checkbox: An interactive element allowing users to select or deselect options, with clear visual feedback for checked and unchecked states.
• DigitalDisplay: Renders text and numbers in a digital, segmented style, ideal for displaying codes or time-sensitive information.
• Form: A flexible form container for grouping and managing input fields, validation, and submission logic.
• Header: The top navigation and branding bar, featuring the Nobak logo, developer mode indicator, and a prominent action button (e.g., QR scan).
• Icon: A collection of scalable vector icons for consistent visual language across the application.
• InfoCard: Displays informational content with a title, description, and optional symbol or call-to-action for user guidance.
• Input: A customizable text input field supporting various types, validation, and accessibility features.
• Layout: Provides structural containers and safe area handling to ensure consistent, adaptive layouts across devices.
• Logo: Renders the Nobak brand logo in multiple variants and themes for use in headers, splash screens, and branding areas.
• MethodCard: Presents contact or authentication methods, showing their status and allowing user interaction or verification.
• Modal: Overlays content in a dialog, blocking background interaction and focusing user attention on critical tasks or information.
• PromoCard: Highlights promotional offers or important updates with a visually engaging card and clear call-to-action.
• QR: Generates and displays QR codes for sharing or scanning secure information within the app.
• RCIInput: Specialized input for entering multi-digit codes, such as verification or recovery codes, with individual digit fields and auto-focus.
• ServerCard: Summarizes server status, uptime, and authentication state, providing controls for server selection and management.
• ServerList: Displays a scrollable list of server cards, enabling users to view and select multiple servers efficiently.
• Symbol: Renders decorative SVG-based symbols to enhance UI elements and convey meaning visually.
• SymbolButton: An interactive button that features a symbol, ideal for icon-based actions or navigation.
• TabButton: A navigation tab element combining a symbol and label, visually indicating active state for tabbed interfaces.

Chat & Conversation Interface

• ChatContainer: The primary wrapper for chat-based wallet interactions, managing the flow and display of messages, actions, and transaction previews in a secure conversational environment.
• ChatBubble: Displays user and system messages in a conversational format, supporting multiple content types including text, transaction details, and interactive elements with appropriate visual styling for sender context.
• ChatInput: Provides a secure, user-friendly input field for composing and sending messages or transaction instructions within the chat wallet.
• ChatEmptyState: Visually communicates an empty or starting state in the chat wallet, guiding users to begin a conversation or transaction.
• ChatLoading: Indicates loading or processing states within the chat interface, ensuring users are aware of ongoing operations.
• IntentChip: Represents suggested intents or actions in a compact, tappable format, streamlining conversational workflows and transaction initiation.
• MessageList: Manages and displays a chronological list of all messages and transactions in the conversation.
• MessageGroup: Groups related messages by time, sender, or transaction context for better readability.
• TypingIndicator: Shows when the AI assistant is processing or composing a response.
• CommandSuggestionList: Displays contextually relevant command suggestions based on conversation state.
• ChatScrollController: Manages scrolling behavior, history navigation, and message visibility.
• ActivityTimeline: Provides a visual timeline of transaction and conversation activity.
• ChatContextProvider: Manages chat state, session context, and security boundaries.

Transaction Components

• TransactionCard: Summarizes transaction details or requests within the chat, offering clear context and actionable options for the user.
• StellarTransactionPreview: Presents Stellar transaction details in a conversational context, showing amount, recipient, fees, and network information with clear approval actions for user confirmation.
• AmountInput: Specialized input for entering and formatting currency amounts with denomination handling.
• AssetSelector: Interface for browsing and selecting from available Stellar assets.
• RecipientSelector: Interface for choosing transaction recipients from contacts or recent recipients, with search and QR scan options.
• FeeSelector: Options for selecting transaction fee levels based on priority and network conditions.
• TransactionSummary: Comprehensive overview of all transaction details before confirmation.
• TransactionConfirmationModal: Final verification step before signing a transaction.
• TransactionSuccess: Animated confirmation of successfully completed transactions.
• TransactionError: Error handling and recovery options for failed transactions.
• MultiSignatureRequest: Interface for managing transactions requiring multiple signatures.
• BatchTransactionBuilder: Interface for creating and managing multiple transactions.

Navigation & Controls

• ConversationHeader: Presents chat participant information, status, and context-specific actions at the top of the conversational interface.
• QuickActionBar: Offers context-aware shortcuts and actions, enabling users to quickly initiate common tasks or responses during chat interactions.
• SettingsMenu: Navigation menu for accessing various application settings and preferences.
• SearchBar: Interface for finding messages, transactions, or commands within the conversation.

Authentication & Security

• BiometricPrompt: Native biometric authentication interface for secure transaction signing.
• PINPad: Secure numeric PIN entry component for authentication and transaction signing.
• SecurityLevelIndicator: Visual representation of current security context and transaction risk.
• AuthenticationFlow: Manages authentication steps and requirements based on transaction risk.
• RecoveryPhraseVerifier: Interface for verifying seed phrases during backup and recovery.

Asset Management

• AssetBalanceDisplay: Shows current balances with appropriate formatting and denomination handling.
• AssetCard: Displays individual asset information, balance, and available actions.
• AssetGraph: Visualizes asset performance and transaction history over time.
• AssetDetailModal: Provides in-depth information about a specific asset and its properties.

User Profile & Settings

• ProfileCard: Displays user information, verification status, and profile management options.
• NotificationPreferences: Controls for configuring alert types, frequency, and delivery methods.
• ThemeSelector: Interface for customizing the application's visual theme and appearance.
• LanguageSelector: Interface for setting language preferences across the application.
• AIPreferences: Controls for configuring AI assistant behavior and capabilities.

Stellar-Specific Components

• StellarAddressValidator: Validates Stellar addresses in real-time with feedback.
• StellarMemoField: Interface for adding and managing transaction memos.
• StellarPathDisplay: Shows payment path information for cross-asset payments.
• AnchorServiceSelector: Interface for selecting and connecting to Stellar anchor services.
• StellarDEXOrderbook: Display of current Stellar DEX trading opportunities and history.
• ExchangeRateCard: Shows current exchange rates between assets with trend indicators.

Educational Components

• TutorialCard: Step-by-step guidance for new users learning wallet features.
• CommandDictionary: Reference guide for available chat commands and their usage.
• ContextualHelpButton: Access to relevant help content based on current screen context.
• GlossaryTooltip: In-context explanations of technical terms and concepts.

Utility Components

• QRGenerator: Creates shareable QR codes for addresses or payment requests.
• QRScanner: Reads and processes QR codes for addresses or payment requests.
• CopyButton: One-tap copying of addresses or information with confirmation.
• ShareSheet: Integration with native sharing capabilities for transaction details.
• OfflineIndicator: Shows connection status and available offline capabilities.

State Management Components

• NetworkStatusMonitor: Tracks Stellar network connectivity and health.
• SyncStatusIndicator: Shows synchronization progress with the blockchain.
• DataBackupController: Manages secure backup processes for wallet data.
• ErrorBoundary: Provides graceful handling of component failures with recovery options.

Composable Chat Modules

• PaymentIntent: Conversation flow and logic for sending assets to recipients.
• ExchangeIntent: Conversation flow and logic for trading assets on the DEX.
• HistoryIntent: Conversation flow and logic for reviewing transaction history.
• InfoIntent: Conversation flow and logic for requesting wallet or asset information.
• SettingsIntent: Conversation flow and logic for changing wallet preferences.

Nobak Chat Wallet User Stories and Component Requirements (Table)

Chat Wallet Component Relationships

The following diagram outlines how the chat wallet components interact:

• ChatContainer: The root conversational interface, orchestrating message flow and embedding all chat-related components.
  • Contains MessageList which renders multiple ChatBubble components for each message.
  • Integrates ChatInput at the bottom for user entry.
  • Displays ChatLoading during async operations and ChatEmptyState when no messages are present.
  • Shows QuickActionBar above the input for fast actions.
  • Renders StellarTransactionPreview and TransactionCard within the chat for transaction-related interactions.
  • Uses IntentChip to suggest next actions.
  • ConversationHeader sits at the top, providing context and controls for the chat session.
  • Utilizes ChatContextProvider for state management across all components.

Documentation Roadmap

Our goal is to provide comprehensive documentation for all components. The next milestone is to complete detailed documentation for the chat wallet components:

• May 2025: Draft and review READMEs for all chat wallet components
• June 2025: Integrate finalized documentation into the main design system and Storybook
• July 2025: Begin documentation for all newly planned components
• Ongoing: Update documentation as new conversational features and wallet capabilities are added

Documentation Template

Each component should have a README.md file in its directory with the following sections:

1. Overview - Brief description of the component
2. Features - Key capabilities and functionality
3. Props - Detailed prop documentation with types and descriptions
4. Usage Examples - Code snippets showing common use cases
5. Implementation Considerations - Important notes for developers

Nobak Chat Wallet User Stories and Component Requirements

Overview

This document outlines key user stories for the Nobak Chat Wallet, mapping each story to the specific components required for implementation. These stories are designed to satisfy real user needs and accomplish definable goals within the wallet ecosystem.

Transaction Management Stories

1. Send Assets to a Contact

As a user, I want to send assets to someone in my contacts through a natural language request, so I can transfer funds without dealing with complex interfaces.

Components Required:

• ChatInput
• ChatBubble
• RecipientSelector
• AssetSelector
• AmountInput
• TransactionSummary
• TransactionConfirmationModal
• BiometricPrompt
• TransactionSuccess
• StellarTransactionPreview

2. Convert Between Assets

As a user, I want to convert one asset to another through a simple chat command, so I can optimize my portfolio without navigating complex DEX interfaces.

Components Required:

• ChatInput
• IntentChip
• ExchangeIntent
• AssetSelector (source)
• AssetSelector (destination)
• StellarDEXOrderbook
• ExchangeRateCard
• TransactionConfirmationModal
• TransactionSuccess

3. View Transaction History

As a user, I want to view my recent transaction history in a conversational format, so I can easily understand my financial activity.

Components Required:

• ChatInput
• HistoryIntent
• MessageList
• ActivityTimeline
• TransactionCard
• SearchBar
• DateRangePicker

4. Set Up Recurring Payments

As a user, I want to schedule recurring payments through chat commands, so I can automate regular transactions.

Components Required:

• ChatInput
• PaymentIntent
• RecipientSelector
• AssetSelector
• AmountInput
• RecurrenceSelector
• TransactionSummary
• TransactionConfirmationModal

5. Request Payment

As a user, I want to generate a payment request to share with others, so I can receive funds seamlessly.

Components Required:

• ChatInput
• PaymentIntent
• AssetSelector
• AmountInput
• QRGenerator
• ShareSheet
• TransactionCard

Account Management Stories

6. Monitor Asset Portfolio

As a user, I want to ask for a summary of my asset portfolio, so I can quickly understand my current financial position.

Components Required:

• ChatInput
• InfoIntent
• AssetBalanceDisplay
• AssetCard
• AssetGraph
• MessageGroup

7. Add and Verify Recovery Methods

As a user, I want to add and verify account recovery methods through guided chat flows, so I can secure my wallet access.

Components Required:

• ChatInput
• SettingsIntent
• AuthenticationFlow
• MethodCard
• RCIInput
• DigitalDisplay
• SecurityLevelIndicator

8. Set Up Multi-Signature Requirements

As a user, I want to configure multi-signature requirements for high-value transactions, so I can add an extra layer of security.

Components Required:

• ChatInput
• SettingsIntent
• MultiSignatureRequest
• SecurityLevelIndicator
• RecipientSelector (co-signers)
• TransactionConfirmationModal

9. Update Account Preferences

As a user, I want to update my account preferences through simple chat commands, so I can personalize my experience easily.

Components Required:

• ChatInput
• SettingsIntent
• ThemeSelector
• LanguageSelector
• NotificationPreferences
• AIPreferences

10. Backup and Restore Wallet

As a user, I want to securely backup and restore my wallet through guided conversations, so I can protect my assets from device loss.

Components Required:

• ChatInput
• InfoIntent
• RecoveryPhraseVerifier
• DigitalDisplay
• SecurityLevelIndicator
• BiometricPrompt
• DataBackupController

Network and Market Stories

11. Check Asset Information and Market Data

As a user, I want to inquire about asset information and market trends through chat, so I can make informed decisions.

Components Required:

• ChatInput
• InfoIntent
• AssetDetailModal
• AssetGraph
• ExchangeRateCard
• CommandSuggestionList

12. Connect to Stellar Anchors

As a user, I want to connect to Stellar anchors through conversational guidance, so I can on/off ramp fiat currencies easily.

Components Required:

• ChatInput
• AnchorServiceSelector
• ServerCard
• ServerList
• TransactionCard
• AuthenticationFlow

13. Monitor Network Status

As a user, I want to check the status of the Stellar network through simple inquiries, so I can understand if there are any issues affecting my transactions.

Components Required:

• ChatInput
• InfoIntent
• NetworkStatusMonitor
• SyncStatusIndicator
• ServerCard

14. Set Network Preferences

As a user, I want to toggle between testnet and mainnet through clear conversational controls, so I can test features safely.

Components Required:

• ChatInput
• SettingsIntent
• ServerSelector
• SecurityLevelIndicator
• TransactionConfirmationModal

15. Track Payment Path

As a user, I want to visualize the path my payment takes through the Stellar network, so I can understand how my assets move.

Components Required:

• ChatInput
• InfoIntent
• StellarPathDisplay
• StellarTransactionPreview
• TransactionCard

User Education and Support Stories

16. Learn Wallet Functionality

As a user, I want to ask how to perform specific actions and get guided tutorials, so I can learn as I use the wallet.

Components Required:

• ChatInput
• InfoIntent
• TutorialCard
• CommandDictionary
• ContextualHelpButton
• GlossaryTooltip

17. Understand Transaction Fees

As a user, I want to understand transaction fees before confirming, so I can make informed decisions about my transactions.

Components Required:

• ChatInput
• FeeSelector
• StellarTransactionPreview
• InfoIntent
• GlossaryTooltip

18. Receive Security Alerts

As a user, I want to receive proactive security alerts about my account, so I can quickly address potential issues.

Components Required:

• ChatBubble
• SecurityLevelIndicator
• TransactionCard
• NotificationPreferences
• QuickActionBar

19. Get Help with Failed Transactions

As a user, I want to understand why a transaction failed and how to resolve it, so I can complete my intended action.

Components Required:

• ChatBubble
• TransactionError
• InfoIntent
• StellarTransactionPreview
• ContextualHelpButton

20. Access FAQ and Common Issues

As a user, I want to ask common questions about the wallet and Stellar, so I can better understand the ecosystem.

Components Required:

• ChatInput
• InfoIntent
• CommandDictionary
• GlossaryTooltip
• QuickActionBar

Advanced Functionality Stories

21. Execute Smart Contracts

As a user, I want to interact with Stellar smart contracts through natural language, so I can access advanced functionality without technical knowledge.

Components Required:

• ChatInput
• CommandSuggestionList
• StellarTransactionPreview
• TransactionConfirmationModal
• TransactionCard
• SecurityLevelIndicator

22. Manage Asset Trustlines

As a user, I want to add, remove, or modify trustlines for various assets, so I can control which assets I can hold.

Components Required:

• ChatInput
• AssetSelector
• TransactionConfirmationModal
• TransactionSuccess
• StellarTransactionPreview
• InfoIntent

23. Create and Manage Offers on the DEX

As a user, I want to create, modify, and cancel offers on the Stellar DEX through conversation, so I can trade assets efficiently.

Components Required:

• ChatInput
• ExchangeIntent
• StellarDEXOrderbook
• AssetSelector
• AmountInput
• TransactionConfirmationModal
• TransactionCard

24. Set Account Flags and Settings

As a user, I want to manage Stellar account flags and settings through guided conversations, so I can optimize my account configuration.

Components Required:

• ChatInput
• SettingsIntent
• SecurityLevelIndicator
• TransactionConfirmationModal
• InfoIntent
• GlossaryTooltip

25. Participate in Governance Votes

As a user, I want to participate in on-chain governance through conversational guidance, so I can contribute to network decisions.

Components Required:

• ChatInput
• InfoIntent
• TransactionConfirmationModal
• StellarTransactionPreview
• ChatContextProvider
• SecurityLevelIndicator

Integration Stories

26. Connect External Applications

As a user, I want to connect to external applications via WalletConnect through conversational guidance, so I can interact with the broader ecosystem.

Components Required:

• ChatInput
• QRScanner
• AppCard
• TransactionCard
• SecurityLevelIndicator
• TransactionConfirmationModal

27. Import/Export Transaction Data

As a user, I want to import or export my transaction history, so I can use it for reporting or backup purposes.

Components Required:

• ChatInput
• InfoIntent
• ActivityTimeline
• ShareSheet
• FileInput
• DataBackupController

28. Share Payment Information

As a user, I want to share payment information with others through multiple channels, so they can easily send me assets.

Components Required:

• ChatInput
• QRGenerator
• ShareSheet
• CopyButton
• QR
• InfoIntent

29. Integrate with Calendar for Scheduled Payments

As a user, I want to sync scheduled payments with my calendar, so I can stay aware of upcoming financial commitments.

Components Required:

• ChatInput
• PaymentIntent
• RecurrenceSelector
• CalendarIntegration
• ShareSheet
• NotificationPreferences

30. Control Third-Party Application Permissions

As a user, I want to manage which external applications have access to my wallet, so I can maintain security and privacy.

Components Required:

• ChatInput
• SettingsIntent
• AppCard
• SecurityLevelIndicator
• ServerList
• TransactionConfirmationModal

Implementation Priority Matrix

Chat Wallet Component Relationships

The following diagram outlines how the chat wallet components interact:

• ChatContainer: The root conversational interface, orchestrating message flow and embedding all chat-related components.
  • Contains MessageList which renders multiple ChatBubble components for each message.
  • Integrates ChatInput at the bottom for user entry.
  • Displays ChatLoading during async operations and ChatEmptyState when no messages are present.
  • Shows QuickActionBar above the input for fast actions.
  • Renders StellarTransactionPreview and TransactionCard within the chat for transaction-related interactions.
  • Uses IntentChip to suggest next actions.
  • ConversationHeader sits at the top, providing context and controls for the chat session.
  • Utilizes ChatContextProvider for state management across all components.