From 9a42a30d99eb5f41d6d4f627b1558d4123c64672 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Fri, 27 Mar 2026 17:43:03 -0700 Subject: [PATCH] docs(design-system): rewrite agent prompts with parallel-safety, pre-flight checks, build gates, rollback recipes --- .../AGENT_1_WIRE_GENERATED_TOKENS.md | 225 +++++++++++---- .../AGENT_2_FIX_ML_PREFIX_LEAKS.md | 260 ++++++++++++----- .../AGENT_3_TOAST_PROVIDER_WIRING.md | 273 +++++++++++++----- .../AGENT_4_ARIA_LABELS_ICON_BUTTONS.md | 254 ++++++++++------ 4 files changed, 721 insertions(+), 291 deletions(-) diff --git a/docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md b/docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md index d25b0ee2..5da25924 100644 --- a/docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md +++ b/docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md @@ -1,75 +1,167 @@ # Agent Task: Wire Web Apps to Import Generated CSS Tokens (Task 1.3) +> **Parallel execution:** SAFE to run alongside Agents 3 and 4. +> **Conflict with Agent 2:** Agent 2 touches NomGap + NoteLett `globals.css` too. +> **Resolution:** This agent **SKIPS** `learning_ai_fastgap` and `learning_ai_notes` — Agent 2 will handle those two after this agent finishes the other 6. + +--- + +## Pre-Flight Checklist (run BEFORE starting any repo) + +```bash +# 1. Ensure git is clean in every repo you'll touch +for repo in learning_ai_flowmonk learning_ai_trails learning_ai_jarvis_jr learning_ai_local_memory_gpt learning_ai_clock learning_ai_local_llms; do + echo "=== $repo ===" && cd /Users/sd9235/code/mygh/$repo && git status --short +done + +# 2. Pull latest on all repos (other agents may have pushed) +for repo in learning_ai_flowmonk learning_ai_trails learning_ai_jarvis_jr learning_ai_local_memory_gpt learning_ai_clock learning_ai_local_llms; do + cd /Users/sd9235/code/mygh/$repo && git pull --ff-only origin main 2>&1 | tail -1 +done + +# 3. Verify generated token files exist +ls /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/*.css +``` + +**STOP condition:** If any repo has uncommitted changes, stash or commit them first. Do NOT proceed with a dirty working tree. + +--- + ## 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. +The `@bytelyst/design-tokens` package generates per-product CSS files in `packages/design-tokens/generated/`. Each file contains product-specific CSS custom properties with the correct prefix. Currently each web app hand-maintains its own vars in `globals.css`. This task replaces handwritten token vars with the canonical generated content. ## 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/` | +| Product | File | Prefix | Web App Repo | CSS Path | +| ----------- | ----------------- | --------- | ------------------------------ | ------------------------------- | +| FlowMonk | `flowmonk.css` | `--fm-*` | `learning_ai_flowmonk` | `web/src/app/globals.css` | +| ActionTrail | `actiontrail.css` | `--at-*` | `learning_ai_trails` | `web/src/app/globals.css` | +| JarvisJr | `jarvisjr.css` | `--jj-*` | `learning_ai_jarvis_jr` | `web/src/app/globals.css` | +| LocalMemGPT | `localmemgpt.css` | `--lmg-*` | `learning_ai_local_memory_gpt` | `web/src/app/globals.css` | +| ChronoMind | `chronomind.css` | `--cm-*` | `learning_ai_clock` | `web/src/app/globals.css` | +| LocalLLMLab | `localllmlab.css` | `--llm-*` | `learning_ai_local_llms` | `dashboard/src/app/globals.css` | -## Steps for Each Repo +**NOT in scope:** NomGap and NoteLett — handled by Agent 2. -### 1. Read the generated CSS file for the product +--- + +## Per-Repo Procedure (repeat for each repo) + +### Step 0: Backup the current globals.css ```bash -cat ../learning_ai_common_plat/packages/design-tokens/generated/.css +cp web/src/app/globals.css web/src/app/globals.css.backup ``` -### 2. Read the app's current `globals.css` +This backup enables instant rollback. Delete it after successful push. -- Standard repos: `web/src/app/globals.css` -- LocalLLMLab: `dashboard/src/app/globals.css` +### Step 1: Read both files side-by-side -### 3. Identify which `:root` variables in `globals.css` are token-equivalent +Read the generated CSS file for this product: -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. +```bash +cat /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/.css +``` -### 4. Add an import of the generated CSS +Read the app's current globals.css: -At the TOP of `globals.css` (before any other CSS), add: +```bash +cat web/src/app/globals.css +``` + +### Step 2: Build a var inventory (DRY RUN — no edits yet) + +Create two lists: + +1. **OVERLAP** — vars defined in BOTH globals.css AND the generated file (these will be removed from globals.css) +2. **APP-ONLY** — vars defined in globals.css but NOT in the generated file (these MUST be kept) + +```bash +# Extract var names from generated file +grep -oP '--[a-z][-a-z0-9]*' /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/.css | sort -u > /tmp/generated-vars.txt + +# Extract var names from globals.css :root blocks +grep -oP '--[a-z][-a-z0-9]*(?=\s*:)' web/src/app/globals.css | sort -u > /tmp/app-vars.txt + +# Show overlap (safe to remove from globals.css) +comm -12 /tmp/generated-vars.txt /tmp/app-vars.txt + +# Show app-only (MUST KEEP) +comm -23 /tmp/app-vars.txt /tmp/generated-vars.txt +``` + +**STOP condition:** If the overlap list is empty (0 vars match), the generated file may use different naming. Inspect manually before proceeding. + +### Step 3: Insert generated token content into globals.css + +Since CSS `@import` from a sibling repo may not resolve in Next.js builds, use the **inline copy** approach — paste the generated CSS content at the TOP of globals.css in a clearly marked block: ```css -/* Design tokens — auto-generated from @bytelyst/design-tokens */ -@import '../../../../learning_ai_common_plat/packages/design-tokens/generated/.css'; +/* ============================================================ + Design tokens — auto-generated from @bytelyst/design-tokens + Source: packages/design-tokens/generated/.css + DO NOT EDIT — regenerate with: npx tsx packages/design-tokens/scripts/generate.ts + ============================================================ */ + +/* paste generated CSS content here */ + +/* === END design tokens === */ ``` -> **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). +### Step 4: Remove overlapping var definitions -### 5. Remove duplicated vars from `globals.css` +For each var in the OVERLAP list from Step 2, remove its definition from the app's own `:root` / `[data-theme]` blocks. **Do NOT remove:** -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). +- Any var in the APP-ONLY list +- The `/* Focus-visible */` block +- Any `@tailwind` directives +- Any `@layer` blocks +- Any `@keyframes` or animation definitions +- Any component-specific or layout-specific CSS rules -### 6. Verify the app still works +### Step 5: Verify all var usages still resolve ```bash -cd web && npm run build -- --webpack # or: cd web && pnpm run build +# Extract all var(--xxx) usages across the web codebase +grep -rhoP 'var\(--[a-z][-a-z0-9]*' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | sort -u | sed 's/var(//' > /tmp/used-vars.txt + +# Extract all var definitions in the updated globals.css +grep -oP '--[a-z][-a-z0-9]*(?=\s*:)' web/src/app/globals.css | sort -u > /tmp/defined-vars.txt + +# Find vars that are USED but NOT DEFINED (potential breakage!) +comm -23 /tmp/used-vars.txt /tmp/defined-vars.txt ``` -If build fails, check for: +**STOP condition:** If any vars appear in usages but not in definitions, you either: -- Missing vars that were removed but not in the generated file -- Import path resolution issues -- Vars used in Tailwind config that need updating +- Removed a var you shouldn't have → restore it from the backup +- The var is defined in a component-level CSS file → safe, proceed -### 7. Visual spot-check +### Step 6: Build gate (MANDATORY) -Start the dev server and verify colors/spacing haven't changed on the dashboard page. +```bash +cd web && pnpm run build 2>&1 | tail -20 +# or for repos using npm: +cd web && npm run build -- --webpack 2>&1 | tail -20 +``` -### 8. Commit and push +**If build fails:** + +1. Read the error message +2. Most likely a missing CSS var — check Step 5 output +3. Restore from backup: `cp web/src/app/globals.css.backup web/src/app/globals.css` +4. Fix the specific issue, then retry from Step 4 + +**STOP condition:** If build fails more than twice, restore backup, commit nothing, and move to the next repo. Leave a TODO comment at the top of globals.css: + +```css +/* TODO: Wire generated tokens — build failed, needs manual review */ +``` + +### Step 7: Commit and push ```bash git add web/src/app/globals.css @@ -77,29 +169,44 @@ git commit -m "feat(design-system): wire generated CSS tokens from @bytelyst/des git push origin main ``` -## Important Rules +### Step 8: Cleanup -- **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` +```bash +rm web/src/app/globals.css.backup +rm -f /tmp/generated-vars.txt /tmp/app-vars.txt /tmp/used-vars.txt /tmp/defined-vars.txt +``` -## 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) +## Rollback Recipe -Do each repo one at a time, verify build, commit, push, then move to the next. +If anything goes wrong after commit: + +```bash +git revert HEAD --no-edit +git push origin main +``` + +--- + +## Repos to Process (in order, easiest first) + +1. `learning_ai_flowmonk` — few custom vars, simple layout +2. `learning_ai_trails` — few custom vars +3. `learning_ai_jarvis_jr` — few custom vars +4. `learning_ai_local_memory_gpt` — few custom vars +5. `learning_ai_clock` — more custom vars (timer-specific) +6. `learning_ai_local_llms` — `dashboard/src/app/globals.css` (different path!) + +**SKIP:** `learning_ai_fastgap` (NomGap) and `learning_ai_notes` (NoteLett) — Agent 2 handles these. + +--- + +## Rules + +- **ONLY touch `globals.css`** — no component files, no config files +- **Do NOT modify generated CSS files** in the common-plat repo +- **Keep ALL non-token CSS** (animations, keyframes, component styles, focus-visible, Tailwind directives) +- **One repo at a time** — build must pass before moving to next +- **Backup before every edit** — restore if build fails +- Commit message: `feat(design-system): wire generated CSS tokens from @bytelyst/design-tokens` 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 index 1f6e5868..ba91d1cc 100644 --- a/docs/design-system-agents/AGENT_2_FIX_ML_PREFIX_LEAKS.md +++ b/docs/design-system-agents/AGENT_2_FIX_ML_PREFIX_LEAKS.md @@ -1,10 +1,40 @@ -# Agent Task: Fix --ml-\* Prefix Leaks in NomGap and NoteLett (Task 1.4) +# Agent Task: Fix --ml-\* Prefix Leaks in NomGap and NoteLett (Task 1.4 + 1.3 for these 2 repos) + +> **Parallel execution:** SAFE to run alongside Agents 3 and 4. +> **Conflict with Agent 1:** Agent 1 wires generated tokens into `globals.css` for OTHER repos but **SKIPS NomGap and NoteLett**. +> **This agent OWNS:** `learning_ai_fastgap` (NomGap) and `learning_ai_notes` (NoteLett) — both `globals.css` AND component files. +> **No other agent touches these two repos' CSS.** + +--- + +## Pre-Flight Checklist + +```bash +# 1. Ensure git is clean +for repo in learning_ai_fastgap learning_ai_notes; do + echo "=== $repo ===" && cd /Users/sd9235/code/mygh/$repo && git status --short +done + +# 2. Pull latest +for repo in learning_ai_fastgap learning_ai_notes; do + cd /Users/sd9235/code/mygh/$repo && git pull --ff-only origin main 2>&1 | tail -1 +done + +# 3. Verify generated token files exist for both products +cat /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/nomgap.css | head -5 +cat /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/notelett.css | head -5 +``` + +**STOP condition:** If either repo has uncommitted changes, stash or commit them first. + +--- ## 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). +Two apps historically inherited `--ml-*` (MindLyst) prefixed CSS vars from a shared tokens file. They should use their own product prefixes. This agent does TWO things per repo: -This task audits both apps, finds every `--ml-*` reference, and replaces it with the correct product prefix. +1. **Fix prefix leaks:** Replace all `--ml-*` references with the correct prefix +2. **Wire generated tokens:** Insert canonical generated CSS (same as Agent 1 does for other repos) ## Prefix Mapping @@ -13,108 +43,192 @@ This task audits both apps, finds every `--ml-*` reference, and replaces it with | 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 +## Per-Repo Procedure (do NomGap first, then NoteLett) + +### Step 0: Backup ```bash -cd -grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | head -100 +cd /Users/sd9235/code/mygh/ +cp web/src/app/globals.css web/src/app/globals.css.backup ``` -### 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:** +### Step 1: Audit — count all --ml- references (DRY RUN) ```bash -# Dry run first -grep -rn 'var(--ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' +echo "=== globals.css definitions ===" +grep -c '\-\-ml-' web/src/app/globals.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' {} + -``` +echo "=== Component/lib usages ===" +grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | wc -l -**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 +echo "=== Full list ===" 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 +Record the total count. After fixing, this count must be exactly **0**. + +**STOP condition:** If the count is already 0, there are no prefix leaks. Skip to the "Wire Generated Tokens" section below. + +### Step 2: Audit — check for `--ml-` in config files too ```bash -grep -c '\-\-ng-' web/src/app/globals.css # NomGap — should be > 0 -grep -c '\-\-ml-' web/src/app/globals.css # Should be 0 +grep -rn '\-\-ml-' web/ --include='*.ts' --include='*.js' --include='*.mjs' --include='*.json' --exclude-dir=node_modules --exclude-dir=.next | grep -v 'src/' ``` -### 8. Build verify +This catches Tailwind config, Next.js config, or other build configs. + +### Step 3: Replace prefix in globals.css DEFINITIONS + +For **NomGap**: replace `--ml-` → `--ng-` in var definitions +For **NoteLett**: replace `--ml-` → `--nl-` in var definitions + +Use the edit tool to make these replacements in `web/src/app/globals.css`. Only replace within `:root` and `[data-theme]` blocks. + +**Critical rule:** Only replace the PREFIX, never the var name. `--ml-accent-primary` → `--ng-accent-primary` (not `--ng-primary`). + +### Step 4: Replace prefix in all USAGES across component/lib files + +For each `.tsx`, `.ts`, `.css` file in `web/src/` that uses `var(--ml-`: + +**NomGap:** `var(--ml-` → `var(--ng-` +**NoteLett:** `var(--ml-` → `var(--nl-` + +Also fix bare references (without `var()`): + +- `'--ml-accent-primary'` → `'--ng-accent-primary'` (in JS string contexts) + +### Step 5: Verify zero --ml- references remain ```bash -cd web && npm run build -- --webpack # or: pnpm run build +count=$(grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | wc -l | tr -d ' ') +echo "Remaining --ml- references: $count" +if [ "$count" -ne "0" ]; then echo "❌ STILL HAS LEAKS — fix them"; else echo "✅ Clean"; fi ``` -### 9. Visual spot-check +**STOP condition:** If count > 0, find and fix the remaining references before proceeding. -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). +### Step 6: Verify definitions match usages -### 10. Commit and push +```bash +# All vars USED in components +grep -rhoP 'var\(--[a-z][-a-z0-9]*' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | sort -u | sed 's/var(//' > /tmp/used-vars.txt + +# All vars DEFINED in globals.css +grep -oP '--[a-z][-a-z0-9]*(?=\s*:)' web/src/app/globals.css | sort -u > /tmp/defined-vars.txt + +# Vars used but not defined (DANGER) +echo "=== Used but not defined ===" +comm -23 /tmp/used-vars.txt /tmp/defined-vars.txt +``` + +**STOP condition:** If any product-prefixed vars are used but not defined, a definition was missed. Fix it before proceeding. + +--- + +## Wire Generated Tokens (same as Agent 1 does for other repos) + +After prefix leaks are fixed, also wire the canonical generated tokens: + +### Step 7: Read the generated product CSS + +```bash +cat /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/.css +``` + +### Step 8: Insert generated tokens at TOP of globals.css + +Add the generated CSS content at the very top, in a marked block: + +```css +/* ============================================================ + Design tokens — auto-generated from @bytelyst/design-tokens + Source: packages/design-tokens/generated/.css + DO NOT EDIT — regenerate with: npx tsx packages/design-tokens/scripts/generate.ts + ============================================================ */ + +/* paste generated content here */ + +/* === END design tokens === */ +``` + +### Step 9: Remove duplicate definitions + +Any `:root` var that now exists in BOTH the generated block AND the app's own block → remove from the app's own block. Keep app-specific vars, focus-visible CSS, animations, component styles. + +--- + +## Build Gate (MANDATORY) + +```bash +cd web && pnpm run build 2>&1 | tail -20 +``` + +**If build fails:** + +1. Check error — usually a missing var +2. Restore backup: `cp web/src/app/globals.css.backup web/src/app/globals.css` +3. Identify the specific issue, fix it, retry + +**STOP condition:** If build fails 3 times, restore backup, commit nothing, leave this TODO at the top of globals.css: + +```css +/* TODO: --ml-* prefix fix failed build — needs manual review */ +``` + +## Final Verification + +```bash +# Zero --ml- leaks +grep -c '\-\-ml-' web/src/app/globals.css # Must be 0 + +# Has correct prefix +grep -c '\-\-ng-' web/src/app/globals.css # NomGap: must be > 0 +# or +grep -c '\-\-nl-' web/src/app/globals.css # NoteLett: must be > 0 + +# Build passes +cd web && pnpm run build +``` + +## Commit and Push ```bash git add -A -git commit -m "fix(design-system): replace --ml-* prefix leaks with correct product prefix" +git commit -m "fix(design-system): replace --ml-* prefix leaks with correct product prefix and wire generated tokens" git push origin main ``` -## Important Rules +## Cleanup -- **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 +```bash +rm web/src/app/globals.css.backup +rm -f /tmp/used-vars.txt /tmp/defined-vars.txt +``` + +## Rollback Recipe + +```bash +git revert HEAD --no-edit && git push origin main +``` + +--- ## Order -1. **NomGap** (`learning_ai_fastgap`) first — likely has more leaks due to being an older app +1. **NomGap** (`learning_ai_fastgap`) first — older app, likely more leaks 2. **NoteLett** (`learning_ai_notes`) second -## Dependency +Complete NomGap fully (fix + wire + build + commit + push) before starting NoteLett. -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. +--- + +## Rules + +- **ONLY touch files in `web/src/`** — no backend, no mobile, no shared/ +- **Only replace the prefix** — never rename the var stem (`accent-primary` stays `accent-primary`) +- **Both definitions AND usages must be fixed** — if you fix one side, the other breaks +- **Keep ALL non-token CSS** — animations, keyframes, focus-visible, Tailwind directives, component styles +- **Backup before every edit** — restore if build fails +- Commit message: `fix(design-system): replace --ml-* prefix leaks with correct product prefix and wire generated tokens` diff --git a/docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md b/docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md index 7116f1e6..4e8f5c2a 100644 --- a/docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md +++ b/docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md @@ -1,54 +1,87 @@ # Agent Task: Wire ToastProvider into App Layouts (Task 3.5) +> **Parallel execution:** SAFE to run alongside ALL other agents. +> **Files touched:** ONLY `providers.tsx` or `layout.tsx` (root layout) + `package.json` for dep. +> **No conflicts:** Agents 1/2 touch `globals.css`, Agent 4 touches component files. This agent only touches layout/provider wiring. + +--- + +## Pre-Flight Checklist + +```bash +# 1. Ensure git is clean in every repo you'll touch +for repo in learning_ai_flowmonk learning_ai_jarvis_jr learning_ai_notes learning_ai_fastgap learning_ai_local_memory_gpt learning_ai_local_llms; do + echo "=== $repo ===" && cd /Users/sd9235/code/mygh/$repo && git status --short +done + +# 2. Pull latest (other agents may have pushed) +for repo in learning_ai_flowmonk learning_ai_jarvis_jr learning_ai_notes learning_ai_fastgap learning_ai_local_memory_gpt learning_ai_local_llms; do + cd /Users/sd9235/code/mygh/$repo && git pull --ff-only origin main 2>&1 | tail -1 +done + +# 3. Verify @bytelyst/ui package exists and has ToastProvider +grep -l 'ToastProvider' /Users/sd9235/code/mygh/learning_ai_common_plat/packages/ui/src/components/Toast.tsx +``` + +**STOP condition:** If any repo has uncommitted changes, stash or commit them first. + +--- + ## 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 +The `@bytelyst/ui` package exports `ToastProvider`, `toast()`, `useToast()`, and `dismissToast()`. This task wires `ToastProvider` into apps that don't have any toast system. ```typescript -// From @bytelyst/ui -export { ToastProvider, toast, useToast, dismissToast } from './components/Toast.js'; +// Usage in any component after wiring: +import { toast } from '@bytelyst/ui'; +toast({ type: 'success', title: 'Saved!', description: 'Changes saved.' }); ``` -- `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 +## Step 0: Audit EVERY Repo First (DRY RUN — no edits) -Run this audit first for each repo to understand the current state: +**Before touching ANY file**, audit all repos to confirm which have/lack toast: ```bash -cd -grep -rn 'toast\|Toast' web/src/ --include='*.tsx' --include='*.ts' | grep -v node_modules | grep -v '.test.' | head -30 +for repo in learning_ai_clock learning_ai_fastgap learning_ai_jarvis_jr learning_ai_trails learning_ai_flowmonk learning_ai_notes learning_ai_local_memory_gpt learning_ai_local_llms; do + echo "=== $repo ===" + if [ "$repo" = "learning_ai_local_llms" ]; then dir="dashboard"; else dir="web"; fi + cd /Users/sd9235/code/mygh/$repo + count=$(grep -rn 'Toast\|toast(' $dir/src/ --include='*.tsx' --include='*.ts' 2>/dev/null | grep -v node_modules | grep -v '.test.' | wc -l | tr -d ' ') + echo " Toast references: $count" + if [ "$count" -gt "3" ]; then echo " → SKIP (has custom toast)"; else echo " → ADD ToastProvider"; fi +done ``` -### Expected Findings +### Expected Results (verify before proceeding!) -| 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 | +| Repo | Expected | Action | +| ------------------------------ | ---------------------- | ------------------------ | +| `learning_ai_clock` | Has custom `Toast.tsx` | **SKIP** — keep existing | +| `learning_ai_trails` | Has custom `Toast.tsx` | **SKIP** — keep existing | +| `learning_ai_fastgap` | No toast | **ADD** | +| `learning_ai_jarvis_jr` | No toast | **ADD** | +| `learning_ai_flowmonk` | No toast | **ADD** | +| `learning_ai_notes` | No toast | **ADD** | +| `learning_ai_local_memory_gpt` | No toast | **ADD** | +| `learning_ai_local_llms` | No toast | **ADD** | -> **IMPORTANT:** Verify the audit above before making changes. If an app already has a working toast, do NOT replace it. +**STOP condition:** If a repo you expected to have no toast actually has one (count > 3), **SKIP it**. Do NOT replace custom toasts. -## Steps for Each Repo That Needs ToastProvider +--- -### 1. Add `@bytelyst/ui` dependency +## Per-Repo Procedure (for repos that need ToastProvider) -Check if the repo already has `@bytelyst/ui` in `package.json`. If not, add it: +### Step 1: Check if `@bytelyst/ui` is already a dependency + +```bash +grep '@bytelyst/ui' web/package.json 2>/dev/null || echo "NOT FOUND" +``` + +If NOT FOUND, add it to `web/package.json` (or `dashboard/package.json` for local-llms): ```json -// In web/package.json (or dashboard/package.json for local-llms) { "dependencies": { "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui" @@ -56,78 +89,162 @@ Check if the repo already has `@bytelyst/ui` in `package.json`. If not, add it: } ``` -Then run `pnpm install` (or `npm install`). +Then 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} - - - ); -} +```bash +cd web && pnpm install ``` -**Pattern B: In providers.tsx (if it exists)** +### Step 2: Find the right place to add ToastProvider + +**Critical:** `ToastProvider` is a client component (uses `useState`/`useEffect`). You **MUST NOT** add `'use client'` to the root `layout.tsx`. Instead: + +**Check for existing providers wrapper:** + +```bash +ls web/src/app/providers.tsx 2>/dev/null && echo "HAS providers.tsx" || echo "NO providers.tsx" +``` + +**Decision tree:** + +``` +Has providers.tsx? + YES → Add ToastProvider INSIDE providers.tsx (it's already 'use client') + NO → Create a new providers.tsx with 'use client' + ToastProvider, + then import it in layout.tsx +``` + +### Step 3A: If `providers.tsx` EXISTS — add ToastProvider there + +Read the existing file: + +```bash +cat web/src/app/providers.tsx +``` + +Wrap the outermost children with ``: ```tsx +// Add this import at the top import { ToastProvider } from '@bytelyst/ui'; +// Wrap children — ToastProvider should be the OUTERMOST wrapper export function Providers({ children }: { children: React.ReactNode }) { return ( - {/* ...existing providers... */} + {/* ...all existing providers stay here... */} {children} ); } ``` -### 4. Verify build +### Step 3B: If NO `providers.tsx` — create one + wire into layout.tsx -```bash -cd web && pnpm run build # or: npm run build -- --webpack +**Create** `web/src/app/providers.tsx`: + +```tsx +'use client'; + +import { ToastProvider } from '@bytelyst/ui'; + +export function Providers({ children }: { children: React.ReactNode }) { + return {children}; +} ``` -### 5. Commit and push +**Then edit** `web/src/app/layout.tsx` to wrap `{children}` with ``: + +Read the current layout first: ```bash -git add -A +cat web/src/app/layout.tsx +``` + +Add the import and wrap: + +```tsx +import { Providers } from './providers'; + +// Inside the tag, wrap children: + + {children} +; +``` + +**Critical:** Do NOT remove any existing content from `layout.tsx`. Only add the `Providers` import and wrapper. + +### Step 4: Build Gate (MANDATORY) + +```bash +cd web && pnpm run build 2>&1 | tail -20 +``` + +**Common errors and fixes:** + +| Error | Fix | +| ------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `Cannot find module '@bytelyst/ui'` | Run `pnpm install` — the dep wasn't installed | +| `'use client' must be at the top` | Ensure `'use client'` is the very first line in providers.tsx | +| `Server component cannot import client component` | You accidentally imported ToastProvider directly in layout.tsx — use providers.tsx wrapper instead | + +**If build fails:** + +1. Read the error carefully +2. If it's a provider ordering issue, adjust the wrapper nesting +3. If it's unrelated to your change, check `git diff` to ensure you only changed what you intended + +**STOP condition:** If build fails 3 times, revert changes: + +```bash +git checkout -- web/src/app/layout.tsx web/src/app/providers.tsx web/package.json +``` + +### Step 5: Verify ToastProvider is actually rendering + +Quick sanity check — the providers file should export something that wraps children: + +```bash +grep -c 'ToastProvider' web/src/app/providers.tsx # Must be >= 1 +``` + +### Step 6: Commit and push + +```bash +git add web/src/app/providers.tsx web/src/app/layout.tsx web/package.json pnpm-lock.yaml 2>/dev/null 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 +## Rollback Recipe + +```bash +git revert HEAD --no-edit && git push origin main +``` + +--- + +## Order (easiest first) + +1. `learning_ai_flowmonk` — simple layout, no providers.tsx +2. `learning_ai_jarvis_jr` — simple layout +3. `learning_ai_notes` — has KeyboardShortcuts in app layout +4. `learning_ai_fastgap` — has providers.tsx (check) +5. `learning_ai_local_memory_gpt` — has providers.tsx (check) +6. `learning_ai_local_llms` — `dashboard/` path, adjust accordingly + +Complete each repo fully (install → wire → build → commit → push) before moving to the next. + +--- + +## Rules + +- **NEVER replace custom toast implementations** — if a repo already has toast UI, SKIP it entirely +- **NEVER add `'use client'` to layout.tsx** — use a providers.tsx wrapper +- **NEVER remove existing providers** — only ADD ToastProvider as an outer wrapper +- **ONLY touch:** `providers.tsx`, `layout.tsx` (import line only), `package.json` (dep only) +- **Backup before edits** — `git stash` or copy files +- **Build must pass** before committing - 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 index 4f0f51f8..f7ac624e 100644 --- a/docs/design-system-agents/AGENT_4_ARIA_LABELS_ICON_BUTTONS.md +++ b/docs/design-system-agents/AGENT_4_ARIA_LABELS_ICON_BUTTONS.md @@ -1,85 +1,150 @@ # Agent Task: Add ARIA Labels to Icon-Only Buttons (Task 4.2) -## Context +> **Parallel execution:** SAFE to run alongside ALL other agents. +> **Files touched:** ONLY `.tsx` component files — adds `aria-label` attributes to existing JSX elements. +> **No conflicts:** Agents 1/2 touch `globals.css`, Agent 3 touches `providers.tsx`/`layout.tsx`. This agent only adds attributes to component JSX — never touches CSS, layout, or provider files. -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. +--- + +## Pre-Flight Checklist + +```bash +# 1. Ensure git is clean in every repo +for repo in learning_ai_flowmonk learning_ai_trails learning_ai_jarvis_jr learning_ai_notes learning_ai_local_memory_gpt learning_ai_fastgap learning_ai_clock learning_ai_local_llms learning_ai_common_plat learning_voice_ai_agent; do + echo "=== $repo ===" && cd /Users/sd9235/code/mygh/$repo && git status --short +done + +# 2. Pull latest (other agents may have pushed) +for repo in learning_ai_flowmonk learning_ai_trails learning_ai_jarvis_jr learning_ai_notes learning_ai_local_memory_gpt learning_ai_fastgap learning_ai_clock learning_ai_local_llms learning_ai_common_plat learning_voice_ai_agent; do + cd /Users/sd9235/code/mygh/$repo && git pull --ff-only origin main 2>&1 | tail -1 +done +``` + +**STOP condition:** If any repo has uncommitted changes, stash or commit them first. + +--- ## 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: +A button is "icon-only" if it renders **no visible text** — only an SVG icon or a Lucide component: ```tsx // BROKEN — no accessible name -// FIXED +// FIXED — add aria-label ``` Also check for: - `` | +| **Icon-only, has aria-label** | SKIP (already fixed) | `` | +| **Icon + text** | SKIP (already accessible) | `` | +| **Not a button** | SKIP | `
` (not interactive) | -### 3. Handle conditional icon buttons +**Critical:** Read the JSX carefully. Don't add aria-label to buttons that already have visible text children, even if text is in a ``. -Some buttons change icon based on state: +### Step 2: Choose good labels + +Use this reference table. **Always prefer context-specific labels:** + +| Icon | Good Label | Bad Label | +| ----------------------------------------- | ------------------------------------------------------- | -------------------- | +| `` | `"Close"` / `"Close dialog"` / `"Dismiss notification"` | `"X"` | +| `` | `"Create new zone"` / `"Add task"` (context!) | `"Plus"` | +| `` | `"Delete task"` / `"Remove agent"` | `"Trash"` | +| `` / `` | `"Edit flow"` / `"Rename"` | `"Pencil"` | +| `` | `"Open settings"` | `"Gear"` | +| `` / `` | `"Toggle sidebar"` / `"Open menu"` | `"Menu icon"` | +| `` / `` | `"Go back"` / `"Next"` / `"Collapse sidebar"` | `"Arrow"` | +| `` | `"Search"` | `"Magnifying glass"` | +| `` | `"Copy to clipboard"` | `"Copy"` | +| `` / `` | `"Switch to light theme"` / `"Switch to dark theme"` | `"Sun"` | +| `` / `` | `"Pin conversation"` / `"Unpin"` | `"Pin"` | +| `` | `"Refresh"` / `"Retry"` | `"Refresh icon"` | +| `` / `` | `"More options"` | `"Dots"` | +| `` | `"Export data"` / `"Download"` | `"Arrow down"` | +| `` / `` | `"Show password"` / `"Hide password"` | `"Eye"` | +| `` | `"Send message"` | `"Send"` | + +### Step 3: Apply fixes — one file at a time + +For each file with icon-only buttons, use the edit tool to add `aria-label` to each element. + +**Pattern — simple icon button:** + +```tsx +// BEFORE + + +// AFTER — add aria-label attribute + +``` + +**Pattern — conditional icons:** ```tsx // BEFORE @@ -87,13 +152,13 @@ Some buttons change icon based on state: {expanded ? : } -// AFTER +// AFTER — dynamic aria-label ``` -### 4. Handle icon links (anchors styled as buttons) +**Pattern — icon Link:** ```tsx // BEFORE @@ -103,22 +168,28 @@ Some buttons change icon based on state: ``` -### 5. Verify no icon-only buttons remain unlabeled +### Step 4: Verify — recount unlabeled icon buttons ```bash -# This heuristic finds buttons without aria-label that might be icon-only -grep -rn '[A-Za-z]' +echo "=== Remaining unlabeled buttons ===" +grep -rn '[A-Za-z]' ``` -Manual review is needed — the grep above will have false positives (buttons with text children). +This will have false positives (buttons with text in child components), but the count should be MUCH lower than Step 0. Manually verify each remaining hit. -### 6. Build verify +**STOP condition:** If you find a button you're unsure about (can't tell if it has visible text), SKIP it. Better to miss one than add a redundant label. + +### Step 5: Build Gate (MANDATORY) ```bash -cd web && pnpm run build # or: npm run build -- --webpack +cd web && pnpm run build 2>&1 | tail -20 ``` -### 7. Commit and push +Adding `aria-label` should NEVER break a build, but verify anyway. + +**If build fails:** Your edit likely had a syntax error (missing quote, unclosed attribute). Check `git diff` and fix. + +### Step 6: Commit and push ```bash git add -A @@ -126,28 +197,49 @@ git commit -m "feat(a11y): add aria-label to icon-only buttons across web app" git push origin main ``` -## Important Rules +### Step 7: Pull latest before next repo -- **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 +Other agents may have pushed while you worked. Always pull before starting the next repo: + +```bash +cd /Users/sd9235/code/mygh/ && git pull --ff-only origin main +``` + +--- + +## Rollback Recipe + +```bash +git revert HEAD --no-edit && git push origin main +``` + +--- + +## Order (simplest first) + +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) +6. `learning_ai_fastgap` — ~15-20 (body viz controls) +7. `learning_ai_clock` — ~20+ (timer controls, pomodoro) +8. `learning_ai_local_llms` — ~10-15 (dashboard/ path) +9. `learning_ai_common_plat` — admin-web + tracker-web (~20 each) +10. `learning_voice_ai_agent` — user-dashboard-web (~15) + +Complete each repo fully (audit → fix → build → commit → push) before starting the next. + +--- + +## Rules + +- **ONLY add `aria-label` attributes** — no other changes to JSX, no CSS, no logic +- **NEVER add aria-label to buttons with visible text** — that creates confusing double-announcement +- **NEVER change visual appearance** — no className changes, no style changes +- **Use context-specific labels** — `"Delete task"` not `"Delete"` when the context is clear from the component +- **Skip when unsure** — better to miss one than introduce a redundant or wrong label +- **The `@bytelyst/ui` components already have aria-labels** — don't duplicate on `Modal`, `ConfirmDialog`, `Toast` +- **Pull before each repo** — other agents are running in parallel +- **Build must pass** before committing - 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)