diff --git a/docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md b/docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md new file mode 100644 index 00000000..d25b0ee2 --- /dev/null +++ b/docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md @@ -0,0 +1,105 @@ +# Agent Task: Wire Web Apps to Import Generated CSS Tokens (Task 1.3) + +## Context + +The `@bytelyst/design-tokens` package now generates per-product CSS files in `packages/design-tokens/generated/`. Each file contains product-specific CSS custom properties with the correct prefix (e.g., `--cm-*` for ChronoMind, `--ng-*` for NomGap). + +Currently, each web app hand-maintains its own CSS custom properties in `globals.css`. This task replaces those handwritten vars with imports of the canonical generated files, ensuring a single source of truth. + +## Generated Token Files + +Location: `learning_ai_common_plat/packages/design-tokens/generated/` + +| Product | File | Prefix | Web App Repo | +| ----------- | ----------------- | --------- | ----------------------------------- | +| ChronoMind | `chronomind.css` | `--cm-*` | `learning_ai_clock/web/` | +| NomGap | `nomgap.css` | `--ng-*` | `learning_ai_fastgap/web/` | +| JarvisJr | `jarvisjr.css` | `--jj-*` | `learning_ai_jarvis_jr/web/` | +| ActionTrail | `actiontrail.css` | `--at-*` | `learning_ai_trails/web/` | +| FlowMonk | `flowmonk.css` | `--fm-*` | `learning_ai_flowmonk/web/` | +| NoteLett | `notelett.css` | `--nl-*` | `learning_ai_notes/web/` | +| LocalMemGPT | `localmemgpt.css` | `--lmg-*` | `learning_ai_local_memory_gpt/web/` | +| LocalLLMLab | `localllmlab.css` | `--llm-*` | `learning_ai_local_llms/dashboard/` | + +## Steps for Each Repo + +### 1. Read the generated CSS file for the product + +```bash +cat ../learning_ai_common_plat/packages/design-tokens/generated/.css +``` + +### 2. Read the app's current `globals.css` + +- Standard repos: `web/src/app/globals.css` +- LocalLLMLab: `dashboard/src/app/globals.css` + +### 3. Identify which `:root` variables in `globals.css` are token-equivalent + +Compare the handwritten vars against the generated file. Token-equivalent vars are those that define colors, spacing, radius, typography, elevation, or motion values in `:root` or `[data-theme]` blocks. + +### 4. Add an import of the generated CSS + +At the TOP of `globals.css` (before any other CSS), add: + +```css +/* Design tokens — auto-generated from @bytelyst/design-tokens */ +@import '../../../../learning_ai_common_plat/packages/design-tokens/generated/.css'; +``` + +> **NOTE:** The import path depends on the repo layout. For repos using `file:` refs in package.json, you may need to use `@bytelyst/design-tokens/generated/.css` instead. Check how the repo resolves `@bytelyst/*` packages (look at `package.json` for `file:` or registry refs). + +### 5. Remove duplicated vars from `globals.css` + +Delete any `:root` or `[data-theme]` variable definitions that now exist in the imported generated file. **Keep** any app-specific vars that are NOT in the generated file (e.g., layout-specific vars, component-specific vars). + +### 6. Verify the app still works + +```bash +cd web && npm run build -- --webpack # or: cd web && pnpm run build +``` + +If build fails, check for: + +- Missing vars that were removed but not in the generated file +- Import path resolution issues +- Vars used in Tailwind config that need updating + +### 7. Visual spot-check + +Start the dev server and verify colors/spacing haven't changed on the dashboard page. + +### 8. Commit and push + +```bash +git add web/src/app/globals.css +git commit -m "feat(design-system): wire generated CSS tokens from @bytelyst/design-tokens" +git push origin main +``` + +## Important Rules + +- **Do NOT modify the generated CSS files** — they are auto-generated +- **Do NOT change any component code** — only `globals.css` changes +- **Keep app-specific CSS** that isn't token-related (animations, layout, component styles) +- **Keep the focus-visible CSS** block that was recently added +- If the import doesn't work due to path resolution, fall back to **copying** the generated CSS content into `globals.css` inside a clearly marked block: + ```css + /* === BEGIN @bytelyst/design-tokens/.css === */ + ... + /* === END @bytelyst/design-tokens/.css === */ + ``` +- Commit message format: `feat(design-system): wire generated CSS tokens from @bytelyst/design-tokens` + +## Repos to Process (in order) + +1. `learning_ai_flowmonk` (simplest — fewer custom vars) +2. `learning_ai_trails` (simple) +3. `learning_ai_jarvis_jr` (simple) +4. `learning_ai_notes` (simple) +5. `learning_ai_local_memory_gpt` (simple) +6. `learning_ai_clock` (more custom vars) +7. `learning_ai_fastgap` (complex — has body viz vars) +8. `learning_ai_local_llms` (dashboard/ path differs) + +Do each repo one at a time, verify build, commit, push, then move to the next. diff --git a/docs/design-system-agents/AGENT_2_FIX_ML_PREFIX_LEAKS.md b/docs/design-system-agents/AGENT_2_FIX_ML_PREFIX_LEAKS.md new file mode 100644 index 00000000..1f6e5868 --- /dev/null +++ b/docs/design-system-agents/AGENT_2_FIX_ML_PREFIX_LEAKS.md @@ -0,0 +1,120 @@ +# Agent Task: Fix --ml-\* Prefix Leaks in NomGap and NoteLett (Task 1.4) + +## Context + +The shared design token generator (`packages/design-tokens/scripts/generate.ts`) historically used a hardcoded `--ml-*` prefix (MindLyst) for the shared semantic CSS output (`tokens.css`). Two product web apps — **NomGap** (`learning_ai_fastgap`) and **NoteLett** (`learning_ai_notes`) — copied this file or referenced it, inheriting `--ml-*` prefixed vars instead of their correct product prefixes (`--ng-*` and `--nl-*` respectively). + +This task audits both apps, finds every `--ml-*` reference, and replaces it with the correct product prefix. + +## Prefix Mapping + +| App | Repo | Correct Prefix | Wrong Prefix | +| -------- | --------------------- | -------------- | ------------ | +| NomGap | `learning_ai_fastgap` | `--ng-*` | `--ml-*` | +| NoteLett | `learning_ai_notes` | `--nl-*` | `--ml-*` | + +## Steps for Each Repo + +### 1. Find all `--ml-` references in the web directory + +```bash +cd +grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | head -100 +``` + +### 2. Categorize the findings + +For each `--ml-*` reference, determine: + +- **Token var usage** (e.g., `var(--ml-accent-primary)`) → Replace with product prefix (e.g., `var(--ng-accent-primary)`) +- **Token var definition** in `globals.css` (e.g., `--ml-accent-primary: #5A8CFF;`) → Replace prefix in the definition +- **False positives** — strings that happen to contain `--ml-` but aren't CSS vars (unlikely, but check) + +### 3. Replace in globals.css + +In `web/src/app/globals.css`, replace all `--ml-` prefixed variable **definitions** with the correct prefix: + +**NomGap:** `--ml-` → `--ng-` +**NoteLett:** `--ml-` → `--nl-` + +### 4. Replace in all component/lib files + +Search and replace all `var(--ml-` references in `.tsx`, `.ts`, and `.css` files: + +**NomGap:** + +```bash +# Dry run first +grep -rn 'var(--ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' + +# Then replace +find web/src -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.css' \) -exec sed -i '' 's/var(--ml-/var(--ng-/g' {} + +``` + +**NoteLett:** + +```bash +find web/src -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.css' \) -exec sed -i '' 's/var(--ml-/var(--nl-/g' {} + +``` + +### 5. Also fix any `--ml-` in style objects or template literals + +Some components use inline styles with template literals: + +```tsx +// WRONG +style={{ color: 'var(--ml-text-primary)' }} + +// NomGap CORRECT +style={{ color: 'var(--ng-text-primary)' }} +``` + +### 6. Verify no --ml- references remain + +```bash +grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' +# Should return 0 results +``` + +### 7. Verify globals.css `:root` block defines vars with correct prefix + +```bash +grep -c '\-\-ng-' web/src/app/globals.css # NomGap — should be > 0 +grep -c '\-\-ml-' web/src/app/globals.css # Should be 0 +``` + +### 8. Build verify + +```bash +cd web && npm run build -- --webpack # or: pnpm run build +``` + +### 9. Visual spot-check + +Start dev server, open dashboard. Colors/fonts/spacing should look identical to before the change. If anything breaks, a CSS var was renamed in usage but not in the `:root` definition (or vice versa). + +### 10. Commit and push + +```bash +git add -A +git commit -m "fix(design-system): replace --ml-* prefix leaks with correct product prefix" +git push origin main +``` + +## Important Rules + +- **ONLY change `--ml-` to the correct product prefix** — do NOT rename any other vars +- **Do NOT change var names** — only the prefix. `--ml-accent-primary` → `--ng-accent-primary`, not `--ng-primary` +- **Check Tailwind config** — if the app uses Tailwind with `var(--ml-*)` in `tailwind.config.ts`, fix those too +- **Check Next.js config** — `next.config.ts` sometimes has theme colors +- The `globals.css` definitions AND all usages must match — if you fix one, fix both +- If a file references `--ml-surface-card` but that var doesn't exist in the generated product CSS, it may be a shared semantic token. Keep it and add a TODO comment + +## Order + +1. **NomGap** (`learning_ai_fastgap`) first — likely has more leaks due to being an older app +2. **NoteLett** (`learning_ai_notes`) second + +## Dependency + +This task should run AFTER Agent 1 (Task 1.3) has wired the generated token imports. If Agent 1 hasn't completed yet, you can still fix the prefix leaks — the generated CSS already uses the correct prefixes, so the work is complementary. diff --git a/docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md b/docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md new file mode 100644 index 00000000..7116f1e6 --- /dev/null +++ b/docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md @@ -0,0 +1,133 @@ +# Agent Task: Wire ToastProvider into App Layouts (Task 3.5) + +## Context + +The `@bytelyst/ui` package (at `learning_ai_common_plat/packages/ui/`) now exports a `ToastProvider` component and a `toast()` function. Some product web apps already have their own toast implementations. This task wires `ToastProvider` into every app that's missing one, and documents which apps already have a custom implementation (leave those alone). + +## What Was Built + +```typescript +// From @bytelyst/ui +export { ToastProvider, toast, useToast, dismissToast } from './components/Toast.js'; +``` + +- `ToastProvider` — wraps `{children}`, renders a fixed toast container at bottom-right +- `toast({ type, title, description?, duration? })` — global function, no hook needed +- `useToast()` — returns `{ toast, dismiss }` for component-scoped usage +- Types: `success`, `error`, `warning`, `info` +- Auto-dismiss after 5s by default + +## Audit: Current Toast Status Per App + +Run this audit first for each repo to understand the current state: + +```bash +cd +grep -rn 'toast\|Toast' web/src/ --include='*.tsx' --include='*.ts' | grep -v node_modules | grep -v '.test.' | head -30 +``` + +### Expected Findings + +| Repo | Status | Action | +| ------------------------------ | -------------------------------------------------------- | ------------------------ | +| `learning_ai_clock` | Has custom `Toast.tsx` component | **Skip** — keep existing | +| `learning_ai_fastgap` | No toast system | **Add** ToastProvider | +| `learning_ai_jarvis_jr` | No toast system | **Add** ToastProvider | +| `learning_ai_trails` | Has custom `Toast.tsx` in `web/src/components/Toast.tsx` | **Skip** — keep existing | +| `learning_ai_flowmonk` | No toast system | **Add** ToastProvider | +| `learning_ai_notes` | No toast system | **Add** ToastProvider | +| `learning_ai_local_memory_gpt` | No toast system | **Add** ToastProvider | +| `learning_ai_local_llms` | No toast system | **Add** ToastProvider | + +> **IMPORTANT:** Verify the audit above before making changes. If an app already has a working toast, do NOT replace it. + +## Steps for Each Repo That Needs ToastProvider + +### 1. Add `@bytelyst/ui` dependency + +Check if the repo already has `@bytelyst/ui` in `package.json`. If not, add it: + +```json +// In web/package.json (or dashboard/package.json for local-llms) +{ + "dependencies": { + "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui" + } +} +``` + +Then run `pnpm install` (or `npm install`). + +### 2. Find the root layout file + +The ToastProvider must wrap the entire app. Find the correct layout: + +- **If the app has `web/src/app/layout.tsx`** — this is the root layout +- **If the app has `web/src/app/providers.tsx`** — add it there (preferred, keeps layout clean) +- **LocalLLMLab:** `dashboard/src/app/layout.tsx` + +### 3. Add ToastProvider to the layout + +**Pattern A: Direct in layout.tsx (if no providers.tsx exists)** + +```tsx +import { ToastProvider } from '@bytelyst/ui'; + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + {children} + + + ); +} +``` + +**Pattern B: In providers.tsx (if it exists)** + +```tsx +import { ToastProvider } from '@bytelyst/ui'; + +export function Providers({ children }: { children: React.ReactNode }) { + return ( + + {/* ...existing providers... */} + {children} + + ); +} +``` + +### 4. Verify build + +```bash +cd web && pnpm run build # or: npm run build -- --webpack +``` + +### 5. Commit and push + +```bash +git add -A +git commit -m "feat(design-system): wire ToastProvider from @bytelyst/ui into root layout" +git push origin main +``` + +## Important Rules + +- **Do NOT replace existing custom toast implementations** — ChronoMind and ActionTrail have their own. Leave them. +- **ToastProvider must be a client component** — it uses `useState`/`useEffect`. The layout.tsx is typically a server component. Either: + - Wrap `ToastProvider` in a `'use client'` providers file, OR + - Import it in an existing client-side providers wrapper +- **Do NOT add `'use client'` to layout.tsx** — that would break server components. Use a separate providers wrapper. +- If the repo doesn't resolve `@bytelyst/ui` (TS errors), ensure `pnpm install` was run after adding the dep +- Commit message: `feat(design-system): wire ToastProvider from @bytelyst/ui into root layout` + +## Order + +1. `learning_ai_flowmonk` (simplest layout) +2. `learning_ai_jarvis_jr` +3. `learning_ai_notes` +4. `learning_ai_fastgap` +5. `learning_ai_local_memory_gpt` +6. `learning_ai_local_llms` diff --git a/docs/design-system-agents/AGENT_4_ARIA_LABELS_ICON_BUTTONS.md b/docs/design-system-agents/AGENT_4_ARIA_LABELS_ICON_BUTTONS.md new file mode 100644 index 00000000..4f0f51f8 --- /dev/null +++ b/docs/design-system-agents/AGENT_4_ARIA_LABELS_ICON_BUTTONS.md @@ -0,0 +1,153 @@ +# Agent Task: Add ARIA Labels to Icon-Only Buttons (Task 4.2) + +## Context + +Across all ByteLyst product web apps, there are buttons that contain only an icon (no visible text). Screen readers cannot describe these buttons to users, causing WCAG 2.1 AA failures. This task audits every web app, finds icon-only buttons, and adds `aria-label` attributes. + +## What Counts as an Icon-Only Button + +A button is "icon-only" if it renders **no visible text** — only an SVG icon or a Lucide/icon component: + +```tsx +// BROKEN — no accessible name + + +// FIXED + +``` + +Also check for: + +- ` + +// AFTER + +``` + +### 4. Handle icon links (anchors styled as buttons) + +```tsx +// BEFORE + + +// AFTER + +``` + +### 5. Verify no icon-only buttons remain unlabeled + +```bash +# This heuristic finds buttons without aria-label that might be icon-only +grep -rn '[A-Za-z]' +``` + +Manual review is needed — the grep above will have false positives (buttons with text children). + +### 6. Build verify + +```bash +cd web && pnpm run build # or: npm run build -- --webpack +``` + +### 7. Commit and push + +```bash +git add -A +git commit -m "feat(a11y): add aria-label to icon-only buttons across web app" +git push origin main +``` + +## Important Rules + +- **Do NOT change any visual appearance** — only add `aria-label` attributes +- **Do NOT add aria-label to buttons that already have visible text** — that creates redundancy +- **Use context-specific labels** — `"Delete timer"` is better than `"Delete"` when context is clear +- **Do NOT add aria-label to decorative icons** — icons next to text (e.g., ` Add Item`) don't need labels on the icon; the button already has a text name +- **Check Sidebar.tsx first** — sidebars typically have the most icon-only buttons (collapse, nav icons) +- **Check dialog close buttons** — every Modal/Dialog has an X close button +- The `@bytelyst/ui` components (`Modal`, `ConfirmDialog`, `Toast`) already have aria-labels — don't duplicate +- Commit message: `feat(a11y): add aria-label to icon-only buttons across web app` + +## Order + +Process repos from simplest to most complex: + +1. `learning_ai_flowmonk` (~5-10 icon buttons) +2. `learning_ai_trails` (~10-15) +3. `learning_ai_jarvis_jr` (~10-15) +4. `learning_ai_notes` (~10-15) +5. `learning_ai_local_memory_gpt` (~15-20, chat UI has many) +6. `learning_ai_fastgap` (~15-20, body viz controls) +7. `learning_ai_clock` (~20+, timer controls, pomodoro) +8. `learning_ai_local_llms` (dashboard, ~10-15) +9. `learning_ai_common_plat` (admin-web + tracker-web, ~20 each) +10. `learning_voice_ai_agent` (user-dashboard-web, ~15)