Skip to content

🎨 Palette: [UX improvement] Enhance README accessibility and visualization #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Igor Holt (igor-holt) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

🎨 Palette: [UX improvement] Enhance README accessibility and visualization #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .Jules/palette.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,8 @@ This journal contains critical UX/accessibility learnings discovered during the
**Learning:** For infrastructure or backend projects without a functional frontend, the `README.md` serves as the primary User Experience (DX/UX). In these cases, micro-UX improvements shift from ARIA labels to scannability, clarity of project status, and informative (non-redundant) feature lists.

**Action:** Treat the `README.md` as the landing page. Use visual status indicators (badges), scannable bullet points with representative emojis, and ensure that headers provide a clear path for the user to understand the project's utility and maturity.

## 2026-05-19 - Visualizing System Mental Models
**Learning:** For infrastructure projects, technical architecture diagrams (e.g., Mermaid) are high-impact UX improvements. They allow users to quickly grasp the relationship between complex layers (like Bare-Metal and Kubernetes) which is often difficult to communicate through text alone.

**Action:** When a project involves multi-layered orchestration or hardware-to-software bridging, prioritize adding a Mermaid diagram with clear visual hierarchies (using subgraphs and styles) to help users build a correct mental model.
37 changes: 35 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
# ⚖️ arbiter

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Status: Experimental](https://img.shields.io/badge/Status-Experimental-orange)
[![License: MIT - Open source software license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Project Status: Experimental - Not recommended for production use](https://img.shields.io/badge/Status-Experimental-orange)

> [!CAUTION]
> This project is currently **Experimental** and is not recommended for production use.

Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM pinning) with quantum-accelerated Kubernetes scheduling.

Expand All @@ -16,6 +19,36 @@ Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM
- ⚛️ **Next-Gen Scheduling**: Leverages quantum-accelerated algorithms for complex Kubernetes workloads.
- ⚖️ **Unified Orchestration**: A single control plane for both hardware and cluster-level operations.

## 🏗️ Architecture

`arbiter` operates as a bridge between the physical hardware layer and the cloud-native orchestration layer.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The terminology used here is slightly inconsistent with the Mermaid diagram below. The diagram explicitly separates the "Cloud Native Layer" and the "Orchestration Layer". Referring to a "cloud-native orchestration layer" in the text might lead to confusion about which layer is being described. It would be clearer to use the terminology defined in the diagram's subgraphs.

Suggested change
`arbiter` operates as a bridge between the physical hardware layer and the cloud-native orchestration layer.
arbiter operates as a bridge between the physical infrastructure layer and the cloud-native layer.


```mermaid
graph TD
subgraph CloudNative [Cloud Native Layer]
K8s[Kubernetes Cluster]
Workloads[AI/ML Workloads]
end

subgraph Orchestration [Orchestration Layer]
Arbiter((Arbiter Core))
Scheduler[Quantum-Accelerated Scheduler]
end

subgraph Infrastructure [Infrastructure Layer]
BareMetal[Bare-Metal Hardware]
vGPU[Virtualized GPU / aSHARD]
end

Workloads --> K8s
K8s <--> Scheduler
Scheduler <--> Arbiter
Arbiter <--> vGPU
vGPU --> BareMetal

style Arbiter fill:#f96,stroke-width:4px
```
Comment on lines +26 to +50
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

While the PR successfully improves accessibility for badges, the newly added Mermaid architecture diagram is not accessible to screen readers. Since the PR's stated goal is to help users using screen readers quickly understand the project, providing a text-based alternative for this diagram is highly recommended. This can be achieved by adding a <details> block with a structured description of the architecture immediately following the diagram.

Example description:

Text description of the architecture

The architecture consists of three layers:

  1. Cloud Native Layer: AI/ML Workloads run on a Kubernetes Cluster.
  2. Orchestration Layer: The Arbiter Core coordinates between the Quantum-Accelerated Scheduler and the infrastructure. The Scheduler interacts with the Kubernetes Cluster.
  3. Infrastructure Layer: The Arbiter Core manages Virtualized GPUs (aSHARD), which run on Bare-Metal Hardware.


## ⚖️ License

This project is licensed under the [MIT License](LICENSE).