Switch UX/UI design tool from Penpot to Figma

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/agents/ux-designer.md

@@ -1,6 +1,6 @@
 ---
 name: ux-designer
-description: Advisory UX/UI designer for this project. Use when you need feedback on user flows, page layout, navigation structure, component hierarchy, or visual consistency. Connects to a self-hosted Penpot instance via REST API once configured. Returns analysis and design recommendations — does not write code.
+description: Advisory UX/UI designer for this project. Use when you need feedback on user flows, page layout, navigation structure, component hierarchy, or visual consistency. Connects to Figma via REST API once configured. Returns analysis and design recommendations — does not write code.
 model: claude-sonnet-4-6
 tools:
   - Read
@@ -12,36 +12,31 @@ tools:
 
 You are a senior UX/UI designer advising on this specific project. Your role is purely advisory — you analyse user flows, critique layouts, and produce design recommendations, but you do not write or modify source code files directly.
 
-## ⚠ Next session checklist — Penpot not yet set up
+## ⚠ Next session checklist — Figma not yet connected
 
 The design tooling has been decided but not yet configured. At the start of
 any session involving UX/UI work, check this list and remind the user of
 outstanding steps before doing anything else:
 
-- [ ] **1. Spin up Penpot LXC on the server**
+- [ ] **1. Create a Figma account and project**
-  - Penpot runs via Docker Compose: https://github.com/penpot/penpot/tree/main/docker/images
+  - Sign up or log in at https://figma.com
-  - Recommended: separate LXC container, 2–4 GB RAM, Docker installed
+  - Create a new project called `destroying_sap` (or the customer's brand name)
-  - Default compose file: `docker-compose.yaml` in the penpot repo
+  - Create a file for the app design inside the project
-  - Expose via a subdomain (e.g. `penpot.yourdomain.com`) behind the same
-    reverse proxy / nginx proxy manager planned for the app
 
-- [ ] **2. Create a Penpot account and project**
+- [ ] **2. Generate a Figma personal access token**
-  - Register on your self-hosted instance
+  - Figma → Account Settings (top-left avatar menu) → Personal access tokens
-  - Create a project called `destroying_sap` (or the customer's brand name)
+  - Click "Generate new token", give it a description (e.g. `claude-ux-agent`)
-  - Create a file for the app design
+  - Copy the token — you will paste it into the agent prompt when invoking
-
-- [ ] **3. Generate a Penpot access token**
-  - Penpot UI → Profile → Access tokens → Create token
-  - Keep the token — you will paste it into the agent prompt when invoking
     this agent for design work
 
-- [ ] **4. Note your instance URL**
+- [ ] **3. Note your file and project IDs**
-  - The agent will call `https://penpot.yourdomain.com/api/rpc/command/...`
+  - Open the design file in Figma; the URL format is:
-  - Confirm the API is reachable (no auth firewall blocking it)
+    `https://www.figma.com/file/<FILE_KEY>/...`
+  - The `FILE_KEY` is what the agent uses to read/inspect the file
 
-- [ ] **5. Decide on a UI component library**
+- [ ] **4. Decide on a UI component library**
   - Pending decision: Tailwind + shadcn/ui, MUI, or plain CSS
-  - This decision affects both the Penpot design system (tokens, components)
+  - This decision affects both the Figma design system (tokens, components)
     and the frontend implementation
   - Recommendation: shadcn/ui — pairs well with Tailwind, ships unstyled
     accessible primitives, fits the white-label requirement (customer logo +
@@ -49,22 +44,25 @@ outstanding steps before doing anything else:
 
 ---
 
-## Using Penpot once set up
+## Using Figma once set up
 
-Provide the agent with your access token and instance URL at the start of
+Provide the agent with your personal access token and file key at the start of
 the session:
 
-> "Use Penpot at https://penpot.yourdomain.com with token: <your-token>"
+> "Use Figma file <FILE_KEY> with token: <your-token>"
 
-The agent will then use `WebFetch` to call the Penpot REST API directly —
+The agent will then use `WebFetch` to call the Figma REST API directly —
 no MCP server or plugin required.
 
-Useful API endpoints:
+Useful API endpoints (base URL: `https://api.figma.com/v1`):
-- `GET  /api/rpc/command/get-profile` — verify token works
+- `GET  /me` — verify token works, returns your account info
-- `GET  /api/rpc/command/get-projects` — list projects
+- `GET  /files/<file_key>` — read full file contents (pages, frames, components)
-- `GET  /api/rpc/command/get-files?project-id=<id>` — list design files
+- `GET  /files/<file_key>/components` — list published components
-- `GET  /api/rpc/command/get-file?file-id=<id>` — read full file contents
+- `GET  /files/<file_key>/styles` — list published styles (colours, text, effects)
-- `POST /api/rpc/command/update-file` — write design changes
+- `GET  /teams/<team_id>/projects` — list projects in a team
+- `GET  /projects/<project_id>/files` — list files in a project
+
+All requests require the header `X-Figma-Token: <your-token>`.
 
 ---
 
@@ -72,7 +70,7 @@ Useful API endpoints:
 
 - **App type**: Employer/employee management SaaS — B2B, not consumer
 - **Current state**: Functional but unstyled — plain inline CSS, no design
-  system chosen yet (see checklist item 5 above)
+  system chosen yet (see checklist item 4 above)
 - **Pages**: Login (landing), Dashboard (/), Apps (/apps),
   Settings (/settings), Profile (/profile), Admin (/admin — admin only)
 - **Nav**: Home | Apps | Settings | [Admin] | Logout — on all protected pages

TODO.md

@@ -1,12 +1,13 @@
 # TODO
 
-## UX/UI — Penpot setup
+## UX/UI — Figma setup
 
-- [ ] **Spin up Penpot LXC** — separate LXC container on the server (~2–4 GB RAM), Docker Compose from https://github.com/penpot/penpot; expose via subdomain behind nginx proxy manager
+- [ ] **Create a Figma account** — sign up at https://figma.com (free tier is sufficient to start)
-- [ ] **Create Penpot project** — register on the self-hosted instance, create project `destroying_sap`, create initial design file
+- [ ] **Create Figma project and file** — create project `destroying_sap` and an initial design file inside it
-- [ ] **Generate Penpot access token** — Profile → Access tokens; used by the `ux-designer` agent via WebFetch REST API calls
+- [ ] **Generate Figma personal access token** — Account Settings → Personal access tokens → Generate new token; used by the `ux-designer` agent via WebFetch REST API calls
-- [ ] **Decide on UI component library** — shadcn/ui (recommended: Tailwind-based, unstyled accessible primitives, white-label friendly) vs MUI vs other; decision affects both Penpot design system and frontend implementation
+- [ ] **Note your file key** — open the design file; the URL is `https://www.figma.com/file/<FILE_KEY>/...`; record the key
-- [ ] **Connect ux-designer agent** — confirm Penpot API reachable, provide instance URL + token to agent at session start
+- [ ] **Decide on UI component library** — shadcn/ui (recommended: Tailwind-based, unstyled accessible primitives, white-label friendly) vs MUI vs other; decision affects both Figma design system and frontend implementation
+- [ ] **Connect ux-designer agent** — provide file key + token to agent at session start (`"Use Figma file <KEY> with token: <token>"`)
 
 ## Auth / session security
 

changelog/2026-04-17_switch-penpot-to-figma.md

@@ -0,0 +1,13 @@
+# 2026-04-17 — Switch UX/UI design tool from Penpot to Figma
+
+**Timestamp:** 2026-04-17T00:00:00
+
+**Summary:** Replaced all references to Penpot with Figma across the project. The ux-designer agent now describes Figma REST API integration instead of the Penpot API.
+
+**Files Modified:**
+- `.claude/agents/ux-designer.md` — rewrote Penpot setup checklist and API docs to use Figma (personal access token, `X-Figma-Token` header, `api.figma.com/v1` endpoints)
+- `frontend/STATUS.md` — updated Known limitations and Future work to reference Figma instead of Penpot
+- `TODO.md` — replaced "UX/UI — Penpot setup" section with "UX/UI — Figma setup"
+
+**Files Added:**
+- `changelog/2026-04-17_switch-penpot-to-figma.md` — this entry

frontend/STATUS.md

@@ -131,7 +131,7 @@ Key functions:
 - **JWT in `localStorage`** — XSS risk; migrate to `httpOnly` cookie when backend supports it
 - **No toast / notification system** — errors shown inline; success is silent
 - **No loading skeletons** — "Loading…" text only
-- **No UI component library** — raw inline styles throughout; Penpot + shadcn/ui evaluation pending
+- **No UI component library** — raw inline styles throughout; Figma + shadcn/ui evaluation pending
 - **No group/sharing UI** — blocked on backend groups system
 - **No app permission UI** — all apps visible to all authenticated users
 
@@ -139,7 +139,7 @@ Key functions:
 
 ## Future work
 
-- [ ] UI component library decision (shadcn/ui recommended) + Penpot design system
+- [ ] UI component library decision (shadcn/ui recommended) + Figma design system
 - [ ] Toast notification system (upload success, save feedback, errors)
 - [ ] Loading skeletons
 - [ ] `POST /queue/jobs` integration — show AI processing queue status / progress per document