bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(design-system): rewrite agent prompts with parallel-safety, pre-flight checks, build gates, rollback recipes

Browse Source
This commit is contained in:
saravanakumardb1 2026-03-27 17:43:03 -07:00
parent 0c04f2da46
commit 9a42a30d99
4 changed files with 721 additions and 291 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

223
docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md
View File

@ -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/<product>.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/<product>.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/<product>.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/<product>.css';
/* ============================================================
Design tokens — auto-generated from @bytelyst/design-tokens
Source: packages/design-tokens/generated/<product>.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/<product>.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/<product>.css === */
...
/* === END @bytelyst/design-tokens/<product>.css === */
```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
```
- 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)
## 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`

260
docs/design-system-agents/AGENT_2_FIX_ML_PREFIX_LEAKS.md
View File

@ -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 <repo>
grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | head -100
cd /Users/sd9235/code/mygh/<repo>
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/<product>.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/<product>.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`

273
docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md
View File

@ -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 <repo>
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 (
<html lang="en">
<body>
<ToastProvider>{children}</ToastProvider>
</body>
</html>
);
}
```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 `<ToastProvider>`:
```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 (
<ToastProvider>
{/* ...existing providers... */}
{/* ...all existing providers stay here... */}
{children}
</ToastProvider>
);
}
```
### 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 <ToastProvider>{children}</ToastProvider>;
}
```
### 5. Commit and push
**Then edit** `web/src/app/layout.tsx` to wrap `{children}` with `<Providers>`:
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 <body> tag, wrap children:
<body>
<Providers>{children}</Providers>
</body>;
```
**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`

246
docs/design-system-agents/AGENT_4_ARIA_LABELS_ICON_BUTTONS.md
View File

@ -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
<button onClick={handleClose}><X className="h-4 w-4" /></button>
// FIXED
// FIXED — add aria-label
<button onClick={handleClose} aria-label="Close"><X className="h-4 w-4" /></button>
```
Also check for:
- `<button>` with only an `<svg>` child
- `<button>` with only a Lucide icon (`<Plus />`, `<Trash2 />`, `<Settings />`, `<ChevronLeft />`, etc.)
- `<button>` with only a Lucide icon (`<Plus />`, `<Trash2 />`, `<Settings />`, etc.)
- `<Link>` styled as a button with only an icon
- Icon-only elements inside `<DialogClose>`, `<AlertDialogCancel>`, etc. from Radix UI
- Icon-only elements inside `<DialogClose>`, `<AlertDialogCancel>`, etc.
## Repos to Audit
**NOT icon-only (do NOT add aria-label):**
| Repo | Web Dir | CSS Prefix |
| ------------------------------ | ----------------------------------------------------------- | ---------- |
| `learning_ai_clock` | `web/src/` | `--cm-*` |
| `learning_ai_fastgap` | `web/src/` | `--ng-*` |
| `learning_ai_jarvis_jr` | `web/src/` | `--jj-*` |
| `learning_ai_trails` | `web/src/` | `--at-*` |
| `learning_ai_flowmonk` | `web/src/` | `--fm-*` |
| `learning_ai_notes` | `web/src/` | `--nl-*` |
| `learning_ai_local_memory_gpt` | `web/src/` | `--lmg-*` |
| `learning_ai_local_llms` | `dashboard/src/` | `--llm-*` |
| `learning_ai_common_plat` | `dashboards/admin-web/src/` + `dashboards/tracker-web/src/` | N/A |
| `learning_voice_ai_agent` | `user-dashboard-web/src/` | N/A |
- Buttons with visible text: `<button><Plus /> Add Item</button>` — already accessible
- Buttons that already have `aria-label`
- Pure decorative icons not wrapped in an interactive element
## Steps for Each Repo
---
### 1. Find all icon-only buttons
## Repos to Process
Run this search to find candidate buttons:
| Repo | Web Dir | Estimated buttons |
| ------------------------------ | ----------------------------------------------------------- | ----------------- |
| `learning_ai_flowmonk` | `web/src/` | ~5-10 |
| `learning_ai_trails` | `web/src/` | ~10-15 |
| `learning_ai_jarvis_jr` | `web/src/` | ~10-15 |
| `learning_ai_notes` | `web/src/` | ~10-15 |
| `learning_ai_local_memory_gpt` | `web/src/` | ~15-20 |
| `learning_ai_fastgap` | `web/src/` | ~15-20 |
| `learning_ai_clock` | `web/src/` | ~20+ |
| `learning_ai_local_llms` | `dashboard/src/` | ~10-15 |
| `learning_ai_common_plat` | `dashboards/admin-web/src/` + `dashboards/tracker-web/src/` | ~20 each |
| `learning_voice_ai_agent` | `user-dashboard-web/src/` | ~15 |
---
## Per-Repo Procedure
### Step 0: Audit — find ALL candidates (DRY RUN — no edits yet)
Run all three searches and save the combined output:
```bash
cd <repo>
# Find buttons with Lucide icon imports nearby
grep -rn '<button' web/src/ --include='*.tsx' -A2 | grep -B1 'className="h-[0-9]'
cd /Users/sd9235/code/mygh/<repo>
WEBDIR="web/src" # or "dashboard/src" for local-llms, "user-dashboard-web/src" for voice-agent
# Find buttons that have an icon component and no text children
grep -rn '<button[^>]*>' web/src/ --include='*.tsx' | grep -v 'aria-label'
echo "=== Buttons without aria-label ==="
grep -rn '<button' $WEBDIR/ --include='*.tsx' | grep -v 'aria-label'
# Find Sidebar/header icon buttons specifically
grep -rn 'onClick.*<' web/src/components/ --include='*.tsx' -A1 | grep -E '(Plus|Minus|X|Trash|Edit|Settings|Menu|ChevronLeft|ChevronRight|Search|Filter|Download|Upload|Copy|Check|MoreVertical|MoreHorizontal|RefreshCw|Eye|EyeOff|Sun|Moon|Bell|ArrowLeft|ArrowRight|Grip|Pin|Unpin) '
echo ""
echo "=== Icon imports (to know which icons are used) ==="
grep -rn "from 'lucide-react'" $WEBDIR/ --include='*.tsx' | head -20
echo ""
echo "=== Buttons with only icon children (high-confidence candidates) ==="
grep -rn '<button' $WEBDIR/ --include='*.tsx' -A3 | grep -B1 'className="h-[0-9]\|className="w-[0-9]' | grep '<button'
```
### 2. For each icon-only button, add aria-label
### Step 1: Read each candidate file and classify
Choose descriptive, action-oriented labels:
For each button found, read the actual file and determine:
| Classification | Action | Example |
| ----------------------------- | ------------------------- | ------------------------------------------- |
| **Icon-only, no aria-label** | ADD aria-label | `<button><X /></button>` |
| **Icon-only, has aria-label** | SKIP (already fixed) | `<button aria-label="Close"><X /></button>` |
| **Icon + text** | SKIP (already accessible) | `<button><Plus /> Add</button>` |
| **Not a button** | SKIP | `<div><X /></div>` (not interactive) |
**Critical:** Read the JSX carefully. Don't add aria-label to buttons that already have visible text children, even if text is in a `<span>`.
### Step 2: Choose good labels
Use this reference table. **Always prefer context-specific labels:**
| Icon | Good Label | Bad Label |
| -------------------------- | ---------------------------------------------------- | -------------------- |
| `<X />` | `"Close"` or `"Close dialog"` or `"Dismiss"` | `"X"` |
| `<Plus />` | `"Add timer"` or `"Create new"` | `"Plus"` |
| `<Trash2 />` | `"Delete item"` or `"Remove"` | `"Trash"` |
| `<Edit />` or `<Pencil />` | `"Edit"` or `"Edit note"` | `"Pencil"` |
| `<Settings />` | `"Settings"` or `"Open settings"` | `"Gear"` |
| `<Menu />` | `"Open menu"` or `"Toggle sidebar"` | `"Menu icon"` |
| `<ChevronLeft />` | `"Go back"` or `"Previous"` | `"Left arrow"` |
| ----------------------------------------- | ------------------------------------------------------- | -------------------- |
| `<X />` | `"Close"` / `"Close dialog"` / `"Dismiss notification"` | `"X"` |
| `<Plus />` | `"Create new zone"` / `"Add task"` (context!) | `"Plus"` |
| `<Trash2 />` | `"Delete task"` / `"Remove agent"` | `"Trash"` |
| `<Edit />` / `<Pencil />` | `"Edit flow"` / `"Rename"` | `"Pencil"` |
| `<Settings />` | `"Open settings"` | `"Gear"` |
| `<Menu />` / `<PanelLeft />` | `"Toggle sidebar"` / `"Open menu"` | `"Menu icon"` |
| `<ChevronLeft />` / `<ChevronRight />` | `"Go back"` / `"Next"` / `"Collapse sidebar"` | `"Arrow"` |
| `<Search />` | `"Search"` | `"Magnifying glass"` |
| `<Copy />` | `"Copy to clipboard"` | `"Copy"` |
| `<Sun />` / `<Moon />` | `"Switch to light theme"` / `"Switch to dark theme"` | `"Sun"` |
| `<Pin />` | `"Pin conversation"` | `"Pin"` |
| `<RefreshCw />` | `"Refresh"` | `"Refresh icon"` |
| `<MoreVertical />` | `"More options"` | `"Dots"` |
| `<Download />` | `"Download"` or `"Export"` | `"Arrow down"` |
| `<Pin />` / `<Unpin />` | `"Pin conversation"` / `"Unpin"` | `"Pin"` |
| `<RefreshCw />` | `"Refresh"` / `"Retry"` | `"Refresh icon"` |
| `<MoreVertical />` / `<MoreHorizontal />` | `"More options"` | `"Dots"` |
| `<Download />` | `"Export data"` / `"Download"` | `"Arrow down"` |
| `<Eye />` / `<EyeOff />` | `"Show password"` / `"Hide password"` | `"Eye"` |
| `<Send />` | `"Send message"` | `"Send"` |
### 3. Handle conditional icon buttons
### Step 3: Apply fixes — one file at a time
Some buttons change icon based on state:
For each file with icon-only buttons, use the edit tool to add `aria-label` to each element.
**Pattern — simple icon button:**
```tsx
// BEFORE
<button onClick={handleClose}>
<X className="h-4 w-4" />
</button>
// AFTER — add aria-label attribute
<button onClick={handleClose} aria-label="Close">
<X className="h-4 w-4" />
</button>
```
**Pattern — conditional icons:**
```tsx
// BEFORE
@ -87,13 +152,13 @@ Some buttons change icon based on state:
{expanded ? <ChevronUp /> : <ChevronDown />}
</button>
// AFTER
// AFTER — dynamic aria-label
<button onClick={toggle} aria-label={expanded ? "Collapse" : "Expand"}>
{expanded ? <ChevronUp /> : <ChevronDown />}
</button>
```
### 4. Handle icon links (anchors styled as buttons)
**Pattern — icon Link:**
```tsx
// BEFORE
@ -103,22 +168,28 @@ Some buttons change icon based on state:
<Link href="/settings" aria-label="Settings"><Settings className="h-5 w-5" /></Link>
```
### 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 '<button' web/src/ --include='*.tsx' | grep -v 'aria-label' | grep -v '>[A-Za-z]'
echo "=== Remaining unlabeled buttons ==="
grep -rn '<button' $WEBDIR/ --include='*.tsx' | grep -v 'aria-label' | grep -v '>[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., `<Plus /> 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/<next-repo> && 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)