Feat/ux case study

docs/SETUP-WSL.md

@@ -0,0 +1,120 @@
+# Cosmo setup on WSL
+
+This guide follows the standard Cosmo setup steps with **WSL-specific notes**. Run all commands from your WSL terminal (e.g. Ubuntu).
+
+## 1. Clone the repo
+
+```bash
+git clone https://github.com/wundergraph/cosmo.git
+cd cosmo
+```
+
+## 2. Prerequisites (in WSL)
+
+Install and verify:
+
+| Tool | Version | Install / check |
+|------|---------|-----------------|
+| **Go** | ≥ 1.25 | `sudo apt install golang-go` or [go.dev/dl](https://go.dev/dl/). Ensure `$HOME/go/bin` is on PATH: `export PATH="$PATH:$(go env GOPATH)/bin"` (add to `~/.bashrc` or `~/.zshrc`) |
+| **Node.js** | ≥ 22.11.0 | `nvm install 22 && nvm use 22` (install [nvm](https://github.com/nvm-sh/nvm) first if needed) |
+| **pnpm** | 9 | `npm install -g pnpm@9` |
+| **Docker** | Engine + Compose V2 | Use **Docker Desktop for Windows** with WSL 2 backend, or [Docker Engine inside WSL](https://docs.docker.com/desktop/wsl/). From WSL, run `docker -v` and `docker compose version` |
+
+Quick check:
+
+```bash
+go version
+node -v   # expect v22.x
+pnpm -v  # expect 9.x
+docker -v
+docker compose version
+```
+
+## 3. Copy environment files
+
+```bash
+cp controlplane/.env.example controlplane/.env
+cp studio/.env.local.example studio/.env.local
+cp cli/.env.example cli/.env
+```
+
+Edit the files if you need to change defaults (e.g. ports or URLs).
+
+## 4. Docker: enable host networking
+
+**Why:** Keycloak rejects non-HTTPS traffic from non-localhost. Host networking makes requests appear as localhost inside the container.
+
+- **Docker Desktop:** Settings → Resources → Network → enable **“Enable host networking”**.
+- **Docker Engine in WSL:** If you use `dockerd` directly, ensure host network mode is available and that Keycloak is reached as localhost (e.g. via `network_mode: host` in compose if you use it).
+
+Restart Docker after changing settings.
+
+## 5. Bootstrap the repo
+
+From the repo root **in WSL** (do not run `make` from Git Bash, PowerShell, or CMD—Unix scripts in the repo will fail):
+
+```bash
+make
+```
+
+This installs dependencies, generates code, starts infra containers (Postgres, Keycloak, etc.), and builds libraries. It can take several minutes.
+
+## 6. Wait for Keycloak
+
+Open [http://localhost:8080](http://localhost:8080/) in your browser. Wait until you see the Keycloak sign-in page.
+
+If 8080 isn’t reachable from Windows, use WSL’s IP or `localhost` from inside WSL (`curl http://localhost:8080`).
+
+## 7. Migrations and seed
+
+```bash
+make migrate && make seed
+```
+
+## 8. Start the control plane (Terminal 1)
+
+**Studio needs the control plane to be running** so it can call `/v1/auth/session` (port 3001). If you skip this or stop it, Studio will show connection errors and auth will fail.
+
+```bash
+make start-cp
+```
+
+Leave this running.
+
+## 9. Start Studio (Terminal 2)
+
+Open a second WSL terminal, `cd` to the repo root, then:
+
+```bash
+make start-studio
+```
+
+## 10. Log in to Studio
+
+Open [http://localhost:3000](http://localhost:3000/) and sign in with:
+
+- **Username:** `foo@wundergraph.com`
+- **Password:** `wunder@123`
+
+## 11. Verify
+
+Confirm Studio loads and that UI updates when you change components under `studio/`.
+
+---
+
+## WSL tips
+
+- **Store the repo on the WSL filesystem** (e.g. `~/cosmo` or `/home/<user>/cosmo`) for best performance with Node/pnpm/Docker.
+- **Ports:** If `localhost` from Windows doesn’t reach a service, try `http://<wsl-ip>:3000` or use the same browser from inside WSL (e.g. WSLg).
+- **Cleanup:** To tear down infra and volumes: `make infra-down-v`. Then you can run `make` again to bootstrap from scratch.
+
+For full local dev (demos, subgraphs, router), see [CONTRIBUTING.md](./CONTRIBUTING.md#local-development).
+
+### Seed hangs with no output
+
+`make seed` connects to Keycloak first; if you see no output, it is usually waiting on Keycloak or the database.
+
+1. **Confirm infra is up:** `docker compose -f docker-compose.yml --profile dev ps` — postgres and keycloak should be "Up".
+2. **Confirm Keycloak is ready:** In a browser or from WSL run `curl -s -o /dev/null -w "%{http_code}" http://localhost:8080` — you want `200` or `302`. If it fails or hangs, Keycloak is not ready or not reachable; wait a minute after `make` and try again.
+3. **Confirm controlplane env:** In `controlplane/.env`, `KC_API_URL` should be `http://localhost:8080` and `DB_URL` should point at `localhost:5432` when running from WSL.
+4. After the change in seed, you should see `Seed: connecting to Keycloak and database...` as soon as the script starts; if that appears and then it hangs, the hang is at Keycloak or Postgres.

docs/case-study/SETUP-WSL.md

@@ -0,0 +1,120 @@
+# Cosmo setup on WSL
+
+This guide follows the standard Cosmo setup steps with **WSL-specific notes**. Run all commands from your WSL terminal (e.g. Ubuntu).
+
+## 1. Clone the repo
+
+```bash
+git clone https://github.com/wundergraph/cosmo.git
+cd cosmo
+```
+
+## 2. Prerequisites (in WSL)
+
+Install and verify:
+
+| Tool | Version | Install / check |
+|------|---------|-----------------|
+| **Go** | ≥ 1.25 | `sudo apt install golang-go` or [go.dev/dl](https://go.dev/dl/). Ensure `$HOME/go/bin` is on PATH: `export PATH="$PATH:$(go env GOPATH)/bin"` (add to `~/.bashrc` or `~/.zshrc`) |
+| **Node.js** | ≥ 22.11.0 | `nvm install 22 && nvm use 22` (install [nvm](https://github.com/nvm-sh/nvm) first if needed) |
+| **pnpm** | 9 | `npm install -g pnpm@9` |
+| **Docker** | Engine + Compose V2 | Use **Docker Desktop for Windows** with WSL 2 backend, or [Docker Engine inside WSL](https://docs.docker.com/desktop/wsl/). From WSL, run `docker -v` and `docker compose version` |
+
+Quick check:
+
+```bash
+go version
+node -v   # expect v22.x
+pnpm -v  # expect 9.x
+docker -v
+docker compose version
+```
+
+## 3. Copy environment files
+
+```bash
+cp controlplane/.env.example controlplane/.env
+cp studio/.env.local.example studio/.env.local
+cp cli/.env.example cli/.env
+```
+
+Edit the files if you need to change defaults (e.g. ports or URLs).
+
+## 4. Docker: enable host networking
+
+**Why:** Keycloak rejects non-HTTPS traffic from non-localhost. Host networking makes requests appear as localhost inside the container.
+
+- **Docker Desktop:** Settings → Resources → Network → enable **“Enable host networking”**.
+- **Docker Engine in WSL:** If you use `dockerd` directly, ensure host network mode is available and that Keycloak is reached as localhost (e.g. via `network_mode: host` in compose if you use it).
+
+Restart Docker after changing settings.
+
+## 5. Bootstrap the repo
+
+From the repo root **in WSL** (do not run `make` from Git Bash, PowerShell, or CMD—Unix scripts in the repo will fail):
+
+```bash
+make
+```
+
+This installs dependencies, generates code, starts infra containers (Postgres, Keycloak, etc.), and builds libraries. It can take several minutes.
+
+## 6. Wait for Keycloak
+
+Open [http://localhost:8080](http://localhost:8080/) in your browser. Wait until you see the Keycloak sign-in page.
+
+If 8080 isn’t reachable from Windows, use WSL’s IP or `localhost` from inside WSL (`curl http://localhost:8080`).
+
+## 7. Migrations and seed
+
+```bash
+make migrate && make seed
+```
+
+## 8. Start the control plane (Terminal 1)
+
+**Studio needs the control plane to be running** so it can call `/v1/auth/session` (port 3001). If you skip this or stop it, Studio will show connection errors and auth will fail.
+
+```bash
+make start-cp
+```
+
+Leave this running.
+
+## 9. Start Studio (Terminal 2)
+
+Open a second WSL terminal, `cd` to the repo root, then:
+
+```bash
+make start-studio
+```
+
+## 10. Log in to Studio
+
+Open [http://localhost:3000](http://localhost:3000/) and sign in with:
+
+- **Username:** `foo@wundergraph.com`
+- **Password:** `wunder@123`
+
+## 11. Verify
+
+Confirm Studio loads and that UI updates when you change components under `studio/`.
+
+---
+
+## WSL tips
+
+- **Store the repo on the WSL filesystem** (e.g. `~/cosmo` or `/home/<user>/cosmo`) for best performance with Node/pnpm/Docker.
+- **Ports:** If `localhost` from Windows doesn’t reach a service, try `http://<wsl-ip>:3000` or use the same browser from inside WSL (e.g. WSLg).
+- **Cleanup:** To tear down infra and volumes: `make infra-down-v`. Then you can run `make` again to bootstrap from scratch.
+
+For full local dev (demos, subgraphs, router), see [CONTRIBUTING.md](./CONTRIBUTING.md#local-development).
+
+### Seed hangs with no output
+
+`make seed` connects to Keycloak first; if you see no output, it is usually waiting on Keycloak or the database.
+
+1. **Confirm infra is up:** `docker compose -f docker-compose.yml --profile dev ps` — postgres and keycloak should be "Up".
+2. **Confirm Keycloak is ready:** In a browser or from WSL run `curl -s -o /dev/null -w "%{http_code}" http://localhost:8080` — you want `200` or `302`. If it fails or hangs, Keycloak is not ready or not reachable; wait a minute after `make` and try again.
+3. **Confirm controlplane env:** In `controlplane/.env`, `KC_API_URL` should be `http://localhost:8080` and `DB_URL` should point at `localhost:5432` when running from WSL.
+4. After the change in seed, you should see `Seed: connecting to Keycloak and database...` as soon as the script starts; if that appears and then it hangs, the hang is at Keycloak or Postgres.

docs/case-study/nav-ux-case-study-checklist.md

@@ -0,0 +1,107 @@
+## Cosmo Studio Navigation & Layout – UX Case Study Checklist
+
+### 1. Setup & Context
+
+- [x] **Confirm local environment is running**
+  - [x] Start control plane (`make start-cp`)
+  - [x] Start Studio (`make start-studio`)
+- [x] **Identify target user flows (via header/sidebar/footer)**
+  - [x] “From landing → use sidebar/header to find a specific graph/service → inspect its health”
+  - [x] “From anywhere → use sidebar/header to access and change org/project settings; confirm footer links support help/docs”
+- [x] **Define success goals (header / footer / sidebar)**
+  - [x] Header/sidebar/footer are **more readable** (clear labels, typography, spacing)
+  - [x] Navigation structure is **more logical** (grouping, ordering, and context make sense)
+  - [x] Shell is **visually better designed** while staying consistent with the design system
+  - [x] Unnecessary items, links, or clutter in header/footer/sidebar are **removed or consolidated**
+
+### 2. Audit Current Navigation & Layout
+
+- [x] **Global navigation & IA**
+  - [x] List all top-level nav items and destinations
+  - [x] Capture how graphs/projects/environments are surfaced
+  - [x] Note redundant or confusing entry points
+- [x] **Wayfinding & context**
+  - [x] Capture current “you are here” cues (active states, titles, breadcrumbs)
+  - [x] Note mismatches between nav label and page title/content
+  - [x] Identify where users may lose track of org/project/graph context
+- [x] **Layout & hierarchy**
+  - [x] Screenshot main overview/dashboard, detail, and settings pages
+  - [x] Mark what appears primary vs secondary on each
+  - [x] List areas where critical information is visually de-emphasised
+- [x] **Responsiveness & accessibility**
+  - [x] Test shell and sidebar at small/medium/large breakpoints
+  - [x] Note any overflow, clipping, or unusable nav on smaller widths
+  - [x] Check keyboard focus and basic contrast on nav items
+
+### 3. Prioritise Problems
+
+- [x] **Create issue list**
+  - [x] For each finding, write a short problem statement
+  - [x] Tag each with impact (High/Med/Low) and effort (S/M/L)
+- [x] **Cluster into themes**
+  - [x] Navigation clarity & IA
+  - [x] Wayfinding & current context
+  - [x] Layout density & hierarchy (including footer + scroll issues)
+- [x] **Select focus areas**
+  - [x] Choose 1–2 themes/surfaces to tackle (e.g. global shell + main overview)
+  - [x] Document why they are highest leverage for Cosmo Studio and why footer cleanup was chosen as the first implementation slice
+
+### 4. Design the Improved Navigation & Layout
+
+- [x] **Define design goals & principles**
+  - [x] Write 3–5 high-level goals for the nav/layout redesign
+  - [x] Capture guiding principles (stable shell, clear context, progressive disclosure)
+- [x] **Information architecture**
+  - [x] Draft a nav structure (sections, groupings, labels) in Figma/Miro
+  - [x] Decide which items live in sidebar vs footer (Legal moved to sidebar “Help & legal”)
+- [x] **Layout shell**
+  - [x] Design updated shell in Figma (desktop breakpoint)
+  - [x] Include sidebar, header, and legal/help section in the shell
+  - [x] Capture a second breakpoint / responsive behaviour in screenshots
+- [x] **States & edge cases**
+  - [x] Show hover/active states for sidebar and legal links
+  - [x] Consider empty/first-time state implications in the shell
+  - [x] Note how the shell scales with more projects/graphs/features
+
+### 5. Choose Implementation Slice
+
+- [x] **Pick one significant improvement to build**
+  - [x] Remove the marketing‑style footer from the Studio shell and relocate its legal/help links into a compact “Help & legal” area (e.g. in the sidebar).
+- [x] **Decide scope of affected routes**
+  - [x] Apply the change to the shared Studio layout so all pages that previously used the footer now share the cleaner shell.
+
+### 6. Implement Navigation/Layout Changes
+
+- [x] **Locate existing layout components**
+  - [x] Identify global layout file(s) used by Studio
+  - [x] Find sidebar/top bar/nav components and any shared config
+- [x] **Introduce or update layout shell**
+  - [x] Remove the marketing-style `Footer` from the shared layout
+  - [x] Add a compact “Help & legal” section in the sidebar using existing patterns
+- [x] **Implement UI per design system**
+  - [x] Reuse existing design system components (buttons, links, typography)
+  - [x] Apply spacing, typography, and color tokens consistently
+  - [x] Ensure semantic structure: `<nav>`, `<header>`, `<main>`, headings
+- [x] **Responsiveness & accessibility**
+  - [x] Keep sidebar behaviour consistent on narrow viewports
+  - [x] Verify keyboard navigation and visible focus across the shell
+  - [x] Check contrast and ARIA attributes for new legal links
+
+### 7. Test, Document, and Submit
+
+- [ ] **Verification**
+  - [ ] Run lint and tests, fix introduced issues
+  - [ ] Manually walk key flows and verify nav, context, and layout
+  - [ ] Spot-check performance and visual polish
+- [ ] **Case study write-up**
+  - [ ] Document audit findings with screenshots
+  - [ ] Summarise prioritisation and chosen focus areas
+  - [ ] Explain design decisions and expected impact
+- [ ] **Implementation documentation**
+  - [ ] Describe implemented changes and how to test them locally
+  - [ ] Note trade-offs, limitations, and potential follow-ups
+- [ ] **Repository & submission**
+  - [ ] Ensure branch `feat/ux-case-study` contains code and docs
+  - [ ] Create a PR in your private fork with a clear summary
+  - [ ] Share fork + design proposal links and brief summary via email
+