# sfossl/color-ergonomics architecture

> Architecture diagram of the GitHub repository sfossl/color-ergonomics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sfossl/color-ergonomics
- Repository: https://github.com/sfossl/color-ergonomics

## Overview

Invariant Color Ergonomics combines a browser visualizer for interactive OKLCH color and contrast exploration with a standard-library Python simulator for analytical checks and token output. In the visualizer, user controls update application state, which resolves colors and contrast through the math module and updates the page. The simulator exposes separate command-line analyses. The excerpts show the browser’s math and content usage, but not its HTML loading order or the simulator’s command-dispatch calls; those documented simulator capabilities are therefore represented without inferred internal call edges.

Main entry points: [`code/simulator/simulator.py`](https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py) (Simulator CLI), [`code/web/js/app.js`](https://github.com/sfossl/color-ergonomics/blob/main/code/web/js/app.js) (Visualizer logic), [`code/web/js/colorMath.js`](https://github.com/sfossl/color-ergonomics/blob/main/code/web/js/colorMath.js) (Color math), [`code/web/config/content.js`](https://github.com/sfossl/color-ergonomics/blob/main/code/web/config/content.js) (Interface content)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser visualizer"]
  node_controls["Color controls<br/>[app.js]"]
  node_visualizer["Visualizer logic<br/>[app.js]"]
  node_content["Interface content<br/>[content.js]"]
  node_color_math["Color math<br/>[colorMath.js]"]
  node_page["Rendered page"]
end

subgraph group_sim["Color analysis"]
  node_sim_cli["Simulator CLI<br/>[simulator.py]"]
  node_color_conversion["OKLCH conversion<br/>[simulator.py]"]
  node_luminance_checks["Luminance benchmarks<br/>[simulator.py]"]
  node_gamut_checks["Gamut closure<br/>[simulator.py]"]
  node_cvd_projection["Vision projections<br/>[simulator.py]"]
  node_token_output["CSS tokens<br/>[simulator.py]"]
end

node_visitor(("Visitor"))
node_cli_user(("CLI user"))

node_visitor -->|"changes inputs"| node_controls
node_controls -->|"triggers render"| node_visualizer
node_visualizer -->|"reads content"| node_content
node_visualizer -->|"resolves colors"| node_color_math
node_visualizer -->|"measures contrast"| node_color_math
node_visualizer -->|"updates styles"| node_page
node_cli_user -->|"runs analysis"| node_sim_cli
node_sim_cli -->|"runs benchmarks"| node_luminance_checks
node_sim_cli -->|"checks gamut"| node_gamut_checks
node_sim_cli -->|"projects vision"| node_cvd_projection
node_sim_cli -->|"calculates color"| node_color_conversion
node_sim_cli -->|"emits CSS"| node_token_output

click node_controls "https://github.com/sfossl/color-ergonomics/blob/main/code/web/js/app.js"
click node_visualizer "https://github.com/sfossl/color-ergonomics/blob/main/code/web/js/app.js"
click node_content "https://github.com/sfossl/color-ergonomics/blob/main/code/web/config/content.js"
click node_color_math "https://github.com/sfossl/color-ergonomics/blob/main/code/web/js/colorMath.js"
click node_sim_cli "https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py"
click node_color_conversion "https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py"
click node_luminance_checks "https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py"
click node_gamut_checks "https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py"
click node_cvd_projection "https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py"
click node_token_output "https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controls,node_visualizer,node_content,node_color_math,node_page,node_cli_user toneBlue
class node_sim_cli,node_color_conversion,node_luminance_checks,node_gamut_checks,node_cvd_projection,node_token_output toneAmber
class node_visitor toneIndigo
```

## Components

### Browser visualizer

- [Color controls](https://github.com/sfossl/color-ergonomics/blob/main/code/web/js/app.js): `code/web/js/app.js`
- [Visualizer logic](https://github.com/sfossl/color-ergonomics/blob/main/code/web/js/app.js): `code/web/js/app.js`
- [Interface content](https://github.com/sfossl/color-ergonomics/blob/main/code/web/config/content.js): `code/web/config/content.js`
- [Color math](https://github.com/sfossl/color-ergonomics/blob/main/code/web/js/colorMath.js): `code/web/js/colorMath.js`
- **Rendered page**

### Color analysis

- [Simulator CLI](https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py): `code/simulator/simulator.py`
- [OKLCH conversion](https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py): `code/simulator/simulator.py`
- [Luminance benchmarks](https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py): `code/simulator/simulator.py`
- [Gamut closure](https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py): `code/simulator/simulator.py`
- [Vision projections](https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py): `code/simulator/simulator.py`
- [CSS tokens](https://github.com/sfossl/color-ergonomics/blob/main/code/simulator/simulator.py): `code/simulator/simulator.py`

### Other components

- **Visitor**
- **CLI user**

## Connections

- Visitor → Color controls: changes inputs (evidence: `code/web/js/app.js`)
- Color controls → Visualizer logic: triggers render (evidence: `code/web/js/app.js`)
- Visualizer logic → Interface content: reads content (evidence: `code/web/js/app.js`)
- Visualizer logic → Color math: resolves colors (evidence: `code/web/js/app.js`)
- Visualizer logic → Color math: measures contrast (evidence: `code/web/js/app.js`)
- Visualizer logic → Rendered page: updates styles (evidence: `code/web/js/app.js`)
- CLI user → Simulator CLI: runs analysis (evidence: `README.md`)
- Simulator CLI → Luminance benchmarks: runs benchmarks (evidence: `README.md`)
- Simulator CLI → Gamut closure: checks gamut (evidence: `README.md`)
- Simulator CLI → Vision projections: projects vision (evidence: `README.md`)
- Simulator CLI → OKLCH conversion: calculates color (evidence: `README.md`)
- Simulator CLI → CSS tokens: emits CSS (evidence: `README.md`)
