style: introduce design system

.github/workflows/chromatic.yml

@@ -0,0 +1,38 @@
+name: "Chromatic"
+
+on:
+  workflow_dispatch:
+  push:
+    branches: main
+  pull_request:
+    branches: "*"
+
+jobs:
+  chromatic:
+    name: Run Chromatic
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./frontend
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.ref }}
+        env:
+          CHROMATIC_BRANCH: ${{ github.event.pull_request.head.ref || github.ref_name }}
+          CHROMATIC_SHA: ${{ github.event.pull_request.head.sha || github.ref }}
+          CHROMATIC_SLUG: ${{ github.repository }}
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24.14.0
+      - name: Install dependencies
+        # ⚠️ See your package manager's documentation for the correct command to install dependencies in a CI environment.
+        run: npm ci
+      - name: Run Chromatic
+        uses: chromaui/action@latest
+        with:
+          # ⚠️ Make sure to configure a `CHROMATIC_PROJECT_TOKEN` repository secret
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          workingDir: frontend

.gitignore

@@ -151,3 +151,6 @@ notifications.yaml
 
 # Local VSCode settings
 .vscode/
+
+*storybook.log
+storybook-static

CLAUDE.md

@@ -84,6 +84,13 @@ View the app at http://localhost:7878
 | `pixi run migrate` | Run database migrations |
 | `pixi run migrate-create` | Create new migration |
 
+### Storybook
+
+| Command | Description |
+|---------|-------------|
+| `pixi run storybook` | Start Storybook dev server on port 6006 |
+| `pixi run storybook-build` | Build static Storybook site |
+
 ### Container Development
 
 | Command | Description |

frontend/.storybook/main.ts

@@ -0,0 +1,17 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/components/designSystem/**/*.stories.tsx'],
+  addons: [
+    '@storybook/addon-a11y',
+    '@storybook/addon-docs',
+    '@storybook/addon-themes',
+    '@storybook/addon-vitest',
+    '@chromatic-com/storybook'
+  ],
+  framework: '@storybook/react-vite',
+  core: {
+    disableTelemetry: true
+  }
+};
+export default config;

frontend/.storybook/preview.ts

@@ -0,0 +1,40 @@
+import { createElement } from 'react';
+import { MemoryRouter } from 'react-router';
+import { withThemeByClassName } from '@storybook/addon-themes';
+import type { Preview } from '@storybook/react-vite';
+import '../src/index.css';
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i
+      }
+    },
+
+    a11y: {
+      // 'todo' - show a11y violations in the test UI only
+      // 'error' - fail CI on a11y violations
+      // 'off' - skip a11y checks entirely
+      test: 'todo'
+    }
+  },
+
+  decorators: [
+    // Wrap all stories in MemoryRouter so FgLink (react-router <Link>) works
+    Story => createElement(MemoryRouter, null, createElement(Story)),
+
+    // Dark mode toggle in the Storybook toolbar
+    withThemeByClassName({
+      themes: {
+        light: '',
+        dark: 'dark'
+      },
+      defaultTheme: 'light',
+      parentSelector: 'html'
+    })
+  ]
+};
+
+export default preview;

frontend/CLAUDE.md

@@ -340,15 +340,15 @@ export function useUpdateMyData() {
 
 ### Routing
 
-- **Base path**: `/fg/` (configured in `vite.config.ts`)
+- **Base path**: `/` (configured in `vite.config.ts`)
 - **Routes**:
-  - `/fg/` - Dashboard/Browse (default)
-  - `/fg/browse` - File browser
-  - `/fg/jobs` - Background jobs
-  - `/fg/links` - Data links management
-  - `/fg/help` - Help/support
-  - `/fg/preferences` - User preferences
-  - `/fg/notifications` - Notifications
+  - `/` - Dashboard/Browse (default)
+  - `/browse` - File browser
+  - `/jobs` - Background jobs
+  - `/links` - Data links management
+  - `/help` - Help/support
+  - `/preferences` - User preferences
+  - `/notifications` - Notifications
 - **Route definitions**: See `src/App.tsx`
 - **Navigation**: Use React Router's `useNavigate()`, `Link`, or `NavLink`
 
@@ -453,15 +453,26 @@ export function useUpdateMyData() {
 ## Build Output
 
 - **Development build**: Outputs to `../fileglancer/ui/`
-- **Served by**: FastAPI backend at `/fg/` path
-- **Static assets**: `/fg/assets/` (Vite asset hashing applied)
+- **Served by**: FastAPI backend at `/` path
+- **Static assets**: `/assets/` (Vite asset hashing applied)
 
 ## Environment Variables
 
 - `.env` - Local environment configuration
 - Variables must be prefixed with `VITE_` to be exposed to frontend
 - Access via `import.meta.env.VITE_VAR_NAME`
 
+## Storybook
+
+Component documentation lives in Storybook, not in-app routes.
+
+```bash
+pixi run storybook              # Start dev server on port 6006
+pixi run storybook-build        # Build static site
+```
+
+Stories are co-located with components: `FgButton.stories.tsx` next to `FgButton.tsx`.
+
 ## Troubleshooting
 
 **Build issues:**

frontend/chromatic.config.json

@@ -0,0 +1,6 @@
+{
+  "onlyChanged": true,
+  "projectId": "Project:69fb7ec1c131fc88e729a9a6",
+  "storybookBaseDir": "frontend",
+  "zip": true
+}

frontend/eslint.config.mjs

@@ -1,10 +1,11 @@
+import storybook from 'eslint-plugin-storybook';
+
 import js from '@eslint/js';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
-import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
-
-import react from 'eslint-plugin-react';
 import json from '@eslint/json';
+import react from 'eslint-plugin-react';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
 import reactHooks from 'eslint-plugin-react-hooks';
 import css from '@eslint/css';
 import { defineConfig, globalIgnores } from 'eslint/config';
@@ -117,5 +118,6 @@ export default defineConfig([
       'react/prop-types': 'off',
       'react/prefer-read-only-props': 'warn'
     }
-  }
+  },
+  ...storybook.configs['flat/recommended']
 ]);