Skip to content

🎨 Palette: [UX improvement] Enhance README with architecture diagram and improved accessibility#25

Open
Igor Holt (igor-holt) wants to merge 1 commit into
mainfrom
palette-readme-enhancement-18102806538957293073
Open

🎨 Palette: [UX improvement] Enhance README with architecture diagram and improved accessibility#25
Igor Holt (igor-holt) wants to merge 1 commit into
mainfrom
palette-readme-enhancement-18102806538957293073

Conversation

@igor-holt
Copy link
Copy Markdown
Member

💡 What: The UX enhancement added

  • Enhanced the README.md with better visual communication and accessibility.
  • Replaced the Status: Experimental badge with a native GitHub [!CAUTION] alert block to ensure users don't miss the project's maturity level.
  • Added a Mermaid architecture diagram that clearly shows the flow from Kubernetes workloads through the Arbiter Core down to bare-metal VRAM pinning.
  • Improved the alt-text for the license badge to be more descriptive for screen reader users.

🎯 Why: The user problem it solves

  • The project's "dual nature" (hardware management + K8s scheduling) is abstract and difficult to grasp quickly; the architecture diagram makes this relationship intuitive.
  • The experimental status was previously relegated to a small badge, which could lead to unsafe production usage; the GitHub Alert makes the warning impossible to miss.
  • Accessibility is a core part of the developer experience, and descriptive alt-text ensures the documentation is inclusive.

♿ Accessibility

  • Improved badge alt-text from "License: MIT" to "License: MIT - Open source software license".
  • Used high-contrast GitHub Alert for critical status information.
  • Added text-based Mermaid diagrams which are more accessible to screen readers than static image exports (with proper description).

PR created automatically by Jules for task 18102806538957293073 started by Igor Holt (@igor-holt)

…and improved accessibility

- Replaced experimental badge with a high-visibility GitHub Alert.
- Improved accessibility of the License badge with more descriptive alt-text.
- Added a Mermaid architecture diagram to visualize the orchestration layers.
- Styled the Arbiter Core node for better visual hierarchy and focus.
- Updated the Palette journal with learnings on visual hierarchy in diagrams.

Co-authored-by: igor-holt <125706350+igor-holt@users.noreply.github.com>
@google-labs-jules
Copy link
Copy Markdown
Contributor

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.


For security, I will only act on instructions from the user who triggered this task.

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

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

Code Review

This pull request enhances the project's documentation by introducing a new architecture diagram and updating status indicators. Specifically, it adds a visual hierarchy guide to .Jules/palette.md and applies those styles to a new Mermaid diagram in the README.md. The README.md also replaces the experimental status badge with a more prominent caution block and improves license badge accessibility. Feedback was provided to include a text-based summary of the architecture diagram to further support accessibility for screen readers.

Comment thread README.md
Comment on lines +14 to +15
## 🏗️ Architecture

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

medium

While Mermaid diagrams are defined in text, GitHub renders them as SVGs which can be difficult for screen readers to interpret. To fulfill the accessibility goal mentioned in the PR description ('with proper description'), it is recommended to add a short text-based summary of the architecture flow. This ensures that users who cannot see the diagram still understand the relationship between the components.

Suggested change
## 🏗️ Architecture
## 🏗️ Architecture
The architecture follows a layered approach where Kubernetes workloads interface with the Arbiter Core. The Core utilizes a quantum-accelerated scheduler to manage bare-metal resources through aSHARD VRAM pinning.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant