Hikari Architecture

This document provides an overview of the Hikari project architecture, including package relationships, design patterns, technology choices, and future roadmap.

Table of Contents

Overview

Hikari is a modular Rust UI framework built around Tairitsu, following a workspace-based architecture. The project is organized into several focused packages, each with a specific responsibility:

mermaid

Design Philosophy

Hikari follows three core design principles:

  1. 1
    Modularity - Each package has a single, well-defined responsibility
  2. 2
    Composability - Packages can be used independently or combined
  3. 3
    Type Safety - Leverage Rust's type system for compile-time guarantees

Architecture Principles

1. Separation of Concerns

Each package handles a specific aspect of the framework:

2. Dependency Inversion

Packages depend on abstractions, not concrete implementations:

mermaid

This creates a clear dependency hierarchy and prevents circular dependencies.

3. Library over Framework

Hikari is designed as a library, not a framework:

Package Architecture

Dependency Graph

mermaid

Package Responsibilities

hikari-palette

Purpose: Color system foundation

Responsibilities:

Dependencies: None (foundation package)

Exports:

rust
1
2
pub use colors::*;
pub use palettes::*;

hikari-theme

Purpose: Theme management and CSS generation

Responsibilities:

Dependencies:

Exports:

rust
1
2
pub use context::*;
pub use provider::*;

hikari-components

Purpose: Core UI component library (rendered components)

Responsibilities:

Design approach: Tairitsu rsx! macro-based rendered components with reactive hooks (use_signal, use_effect), StyledComponent trait for CSS embedding, and typed CSS class enums from hikari-palette.

Dependencies:

Exports:

rust
1
2
3
4
5
6
7
8
pub use basic::*;
pub use feedback::*;
pub use navigation::*;
pub use data::*;
pub use display::*;
pub use layout::*;
pub use entry::*;
pub use production::*;

hikari-extra-components

Purpose: Framework-agnostic data models for advanced UI scenarios

Responsibilities:

Design approach: Pure Rust structs with serde support — no rendering framework dependency. These models can be used with any frontend framework (Tairitsu, Yew, Leptos) or in SSR/testing contexts without pulling in a DOM library.

Dependencies:

Exports:

rust
1
2
pub use extra::*;
pub use node_graph::*;

Note: Some types share names across hikari-components and hikari-extra-components (e.g., TimelinePosition, GuideStep). The components versions are rendered tairitsu-style components with Element children and event handlers; the extra-components versions are pure data structs with String fields and serde derives. Import with explicit module paths to disambiguate.

hikari-animation

Purpose: Animation engine and presets

Responsibilities:

Dependencies:

Exports:

rust
1
2
3
pub use presets::*;
pub use core::{AnimationEngine, Tween, TweenId};
pub use easing::EasingFunction;

hikari-icons

Purpose: Material Design Icons integration

Responsibilities:

Dependencies:

Exports:

rust
1
2
pub use Icon;
pub use IconSize;

Technology Stack

Frontend

Styling

Server (for SSR in examples)

Build System

Tooling

Design Patterns

1. Builder Pattern

Used extensively for configuration:

rust
1
2
3
4
5
let app = HikariSsrPlugin::new()
    .static_assets("./dist")
    .add_route("/api/health", get(health))
    .state("app_name", "Hikari App")
    .build()?;

Benefits:

2. Component Pattern

Tairitsu components follow React-like patterns:

rust
1
2
3
4
5
6
#[component]
fn Button(props: ButtonProps) -> Element {
    rsx! {
        button { class: "{props.class}", {props.children} }
    }
}

Benefits:

3. Context Pattern

Theme and state management:

rust
1
2
3
4
5
6
rsx! {
    ThemeProvider { initial_palette: "hikari",
        // All children have access to theme
        Button { "Themed Button" }
    }
}

Benefits:

4. Module Pattern

Component organization:

mermaid

Benefits:

5. Provider Pattern

Theme provision to component tree:

rust
1
2
3
4
5
6
7
8
9
#[component]
pub fn ThemeProvider(props: ThemeProviderProps) -> Element {
    rsx! {
        div {
            "data-theme": "{props.palette}",
            {props.children}
        }
    }
}

Benefits:

Data Flow

Component Data Flow

mermaid

Theme Data Flow

mermaid

SSR Data Flow (examples/website)

mermaid

Component Architecture

Component Hierarchy

mermaid

Component Lifecycle

  1. 1
    Mount: Component is created and added to DOM
  2. 2
    Update: Props or state change triggers re-render
  3. 3
    UnMount: Component is removed from DOM

State Management

Theme System Architecture

Theme Structure

mermaid

Theme Application

  1. 1
    Rust Side: ThemeProvider sets data-theme attribute
  2. 2
    CSS Side: CSS variables scoped to [data-theme="..."]
  3. 3
    Component Side: Components use CSS variables

Build and Bundle System

Cargo Workspace

toml
1
2
3
4
5
6
7
8
9
[workspace]
members = [
    "packages/palette",
    "packages/theme",
    "packages/animation",
    "packages/components",
    "packages/extra-components",
    "packages/icons",
]

Benefits:

Build Profiles

toml
1
2
3
4
5
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
strip = true

Benefits:

Just Commands

makefile
1
2
3
4
5
build:        # Build all packages
test:         # Run tests
fmt:          # Format code
clippy:       # Run linter
dev:          # Start dev server

Benefits:

Testing Strategy

Unit Tests

Package-level unit tests:

rust
1
2
3
4
5
6
7
8
9
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_color_rgb() {
        assert_eq!(石青.rgb, (23, 89, 168));
    }
}

Integration Tests

Cross-package integration:

rust
1
2
3
4
#[tokio::test]
async fn test_theme_provider() {
    // Test theme provider with components
}

Example Tests

Example applications serve as integration tests:

mermaid

Future Roadmap

Phase 4: hikari-components (Current)

Phase 5: hikari-extra-components

Phase 6: Examples

Phase 7: Documentation

Phase 8: Ecosystem

Long-term Vision

Architectural Decisions

Dual-Layer Package Architecture: components vs extra-components

Hikari intentionally splits its component offerings into two packages with complementary responsibilities:

mermaid

Why two packages?

Concernhikari-componentshikari-extra-components
Renderingrsx! macro, reactive hooksNone (framework-agnostic)
State managementuse_signal(), use_effect()Plain mutable struct fields
Event handlingEventHandler<T> closuresdata-action attributes + external wiring
CSS embeddingStyledComponent traitpub const *_STYLES: &str
SerializationNot requiredserde derives on all state types
DOM dependencyRequires Tairitsu frameworkNone
Use caseLive UI rendering in Tairitsu appsSSR, testing, state persistence, non-Tairitsu frameworks

Overlapping component domains (e.g., Timeline, DragLayer, UserGuide, ZoomControls, VideoPlayer, RichTextEditor, CodeHighlight) exist in both packages by design:

When to use which:

Type name disambiguation:

Some types exist in both packages (e.g., TimelinePosition, GuideStep). Import with explicit paths:

rust,ignore
1
2
3
4
5
use hikari_extra_components::extra::TimelineState;     // pure data model
use hikari_components::display::Timeline;              // rendered component

use hikari_extra_components::extra::ZoomControlsState; // pure state
use hikari_components::display::ZoomControls;          // rendered component

CSS class naming: The two packages use different CSS class names for the same conceptual elements. This is intentional — components uses typed class enums from hikari-palette (e.g., ZoomControlsClass::Button), while extra-components uses hardcoded strings or computed methods. When both packages are used together, each renders with its own class set.

Why Tairitsu?

Why Axum?

Why SCSS?

Why Workspace?

Performance Considerations

WASM Optimization

Runtime Performance

Bundle Size

Security Considerations

Static Files

SSR

Conclusion

Hikari's architecture is designed to be:

The architecture supports the project's goals of providing a modern, type-safe UI framework that blends traditional Chinese aesthetics with futuristic design elements.