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

docs(design-system): add 4 agent prompts for deferred remediation tasks

Browse Source
This commit is contained in:
saravanakumardb1 2026-03-27 17:32:59 -07:00
parent 7f257df0f5
commit 0c04f2da46
4 changed files with 511 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
docs/design-system-agents/AGENT_1_WIRE_GENERATED_TOKENS.md Normal file
View File

@ -0,0 +1,105 @@
# Agent Task: Wire Web Apps to Import Generated CSS Tokens (Task 1.3)
## Context
The `@bytelyst/design-tokens` package now generates per-product CSS files in `packages/design-tokens/generated/`. Each file contains product-specific CSS custom properties with the correct prefix (e.g., `--cm-*` for ChronoMind, `--ng-*` for NomGap).
Currently, each web app hand-maintains its own CSS custom properties in `globals.css`. This task replaces those handwritten vars with imports of the canonical generated files, ensuring a single source of truth.
## Generated Token Files
Location: `learning_ai_common_plat/packages/design-tokens/generated/`
| Product | File | Prefix | Web App Repo |
| ----------- | ----------------- | --------- | ----------------------------------- |
| ChronoMind | `chronomind.css` | `--cm-*` | `learning_ai_clock/web/` |
| NomGap | `nomgap.css` | `--ng-*` | `learning_ai_fastgap/web/` |
| JarvisJr | `jarvisjr.css` | `--jj-*` | `learning_ai_jarvis_jr/web/` |
| ActionTrail | `actiontrail.css` | `--at-*` | `learning_ai_trails/web/` |
| FlowMonk | `flowmonk.css` | `--fm-*` | `learning_ai_flowmonk/web/` |
| NoteLett | `notelett.css` | `--nl-*` | `learning_ai_notes/web/` |
| LocalMemGPT | `localmemgpt.css` | `--lmg-*` | `learning_ai_local_memory_gpt/web/` |
| LocalLLMLab | `localllmlab.css` | `--llm-*` | `learning_ai_local_llms/dashboard/` |
## Steps for Each Repo
### 1. Read the generated CSS file for the product
```bash
cat ../learning_ai_common_plat/packages/design-tokens/generated/<product>.css
```
### 2. Read the app's current `globals.css`
- Standard repos: `web/src/app/globals.css`
- LocalLLMLab: `dashboard/src/app/globals.css`
### 3. Identify which `:root` variables in `globals.css` are token-equivalent
Compare the handwritten vars against the generated file. Token-equivalent vars are those that define colors, spacing, radius, typography, elevation, or motion values in `:root` or `[data-theme]` blocks.
### 4. Add an import of the generated CSS
At the TOP of `globals.css` (before any other CSS), add:
```css
/* Design tokens — auto-generated from @bytelyst/design-tokens */
@import '../../../../learning_ai_common_plat/packages/design-tokens/generated/<product>.css';
```
> **NOTE:** The import path depends on the repo layout. For repos using `file:` refs in package.json, you may need to use `@bytelyst/design-tokens/generated/<product>.css` instead. Check how the repo resolves `@bytelyst/*` packages (look at `package.json` for `file:` or registry refs).
### 5. Remove duplicated vars from `globals.css`
Delete any `:root` or `[data-theme]` variable definitions that now exist in the imported generated file. **Keep** any app-specific vars that are NOT in the generated file (e.g., layout-specific vars, component-specific vars).
### 6. Verify the app still works
```bash
cd web && npm run build -- --webpack # or: cd web && pnpm run build
```
If build fails, check for:
- Missing vars that were removed but not in the generated file
- Import path resolution issues
- Vars used in Tailwind config that need updating
### 7. Visual spot-check
Start the dev server and verify colors/spacing haven't changed on the dashboard page.
### 8. Commit and push
```bash
git add web/src/app/globals.css
git commit -m "feat(design-system): wire generated CSS tokens from @bytelyst/design-tokens"
git push origin main
```
## Important Rules
- **Do NOT modify the generated CSS files** — they are auto-generated
- **Do NOT change any component code** — only `globals.css` changes
- **Keep app-specific CSS** that isn't token-related (animations, layout, component styles)
- **Keep the focus-visible CSS** block that was recently added
- If the import doesn't work due to path resolution, fall back to **copying** the generated CSS content into `globals.css` inside a clearly marked block:
```css
/* === BEGIN @bytelyst/design-tokens/<product>.css === */
...
/* === END @bytelyst/design-tokens/<product>.css === */
```
- Commit message format: `feat(design-system): wire generated CSS tokens from @bytelyst/design-tokens`
## Repos to Process (in order)
1. `learning_ai_flowmonk` (simplest — fewer custom vars)
2. `learning_ai_trails` (simple)
3. `learning_ai_jarvis_jr` (simple)
4. `learning_ai_notes` (simple)
5. `learning_ai_local_memory_gpt` (simple)
6. `learning_ai_clock` (more custom vars)
7. `learning_ai_fastgap` (complex — has body viz vars)
8. `learning_ai_local_llms` (dashboard/ path differs)
Do each repo one at a time, verify build, commit, push, then move to the next.

120
docs/design-system-agents/AGENT_2_FIX_ML_PREFIX_LEAKS.md Normal file
View File

@ -0,0 +1,120 @@
# Agent Task: Fix --ml-\* Prefix Leaks in NomGap and NoteLett (Task 1.4)
## Context
The shared design token generator (`packages/design-tokens/scripts/generate.ts`) historically used a hardcoded `--ml-*` prefix (MindLyst) for the shared semantic CSS output (`tokens.css`). Two product web apps — **NomGap** (`learning_ai_fastgap`) and **NoteLett** (`learning_ai_notes`) — copied this file or referenced it, inheriting `--ml-*` prefixed vars instead of their correct product prefixes (`--ng-*` and `--nl-*` respectively).
This task audits both apps, finds every `--ml-*` reference, and replaces it with the correct product prefix.
## Prefix Mapping
| App | Repo | Correct Prefix | Wrong Prefix |
| -------- | --------------------- | -------------- | ------------ |
| NomGap | `learning_ai_fastgap` | `--ng-*` | `--ml-*` |
| NoteLett | `learning_ai_notes` | `--nl-*` | `--ml-*` |
## Steps for Each Repo
### 1. Find all `--ml-` references in the web directory
```bash
cd <repo>
grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | head -100
```
### 2. Categorize the findings
For each `--ml-*` reference, determine:
- **Token var usage** (e.g., `var(--ml-accent-primary)`) → Replace with product prefix (e.g., `var(--ng-accent-primary)`)
- **Token var definition** in `globals.css` (e.g., `--ml-accent-primary: #5A8CFF;`) → Replace prefix in the definition
- **False positives** — strings that happen to contain `--ml-` but aren't CSS vars (unlikely, but check)
### 3. Replace in globals.css
In `web/src/app/globals.css`, replace all `--ml-` prefixed variable **definitions** with the correct prefix:
**NomGap:** `--ml-` → `--ng-`
**NoteLett:** `--ml-` → `--nl-`
### 4. Replace in all component/lib files
Search and replace all `var(--ml-` references in `.tsx`, `.ts`, and `.css` files:
**NomGap:**
```bash
# Dry run first
grep -rn 'var(--ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css'
# Then replace
find web/src -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.css' \) -exec sed -i '' 's/var(--ml-/var(--ng-/g' {} +
```
**NoteLett:**
```bash
find web/src -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.css' \) -exec sed -i '' 's/var(--ml-/var(--nl-/g' {} +
```
### 5. Also fix any `--ml-` in style objects or template literals
Some components use inline styles with template literals:
```tsx
// WRONG
style={{ color: 'var(--ml-text-primary)' }}
// NomGap CORRECT
style={{ color: 'var(--ng-text-primary)' }}
```
### 6. Verify no --ml- references remain
```bash
grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css'
# Should return 0 results
```
### 7. Verify globals.css `:root` block defines vars with correct prefix
```bash
grep -c '\-\-ng-' web/src/app/globals.css # NomGap — should be > 0
grep -c '\-\-ml-' web/src/app/globals.css # Should be 0
```
### 8. Build verify
```bash
cd web && npm run build -- --webpack # or: pnpm run build
```
### 9. Visual spot-check
Start dev server, open dashboard. Colors/fonts/spacing should look identical to before the change. If anything breaks, a CSS var was renamed in usage but not in the `:root` definition (or vice versa).
### 10. Commit and push
```bash
git add -A
git commit -m "fix(design-system): replace --ml-* prefix leaks with correct product prefix"
git push origin main
```
## Important Rules
- **ONLY change `--ml-` to the correct product prefix** — do NOT rename any other vars
- **Do NOT change var names** — only the prefix. `--ml-accent-primary` → `--ng-accent-primary`, not `--ng-primary`
- **Check Tailwind config** — if the app uses Tailwind with `var(--ml-*)` in `tailwind.config.ts`, fix those too
- **Check Next.js config** — `next.config.ts` sometimes has theme colors
- The `globals.css` definitions AND all usages must match — if you fix one, fix both
- If a file references `--ml-surface-card` but that var doesn't exist in the generated product CSS, it may be a shared semantic token. Keep it and add a TODO comment
## Order
1. **NomGap** (`learning_ai_fastgap`) first — likely has more leaks due to being an older app
2. **NoteLett** (`learning_ai_notes`) second
## Dependency
This task should run AFTER Agent 1 (Task 1.3) has wired the generated token imports. If Agent 1 hasn't completed yet, you can still fix the prefix leaks — the generated CSS already uses the correct prefixes, so the work is complementary.

133
docs/design-system-agents/AGENT_3_TOAST_PROVIDER_WIRING.md Normal file
View File

@ -0,0 +1,133 @@
# Agent Task: Wire ToastProvider into App Layouts (Task 3.5)
## Context
The `@bytelyst/ui` package (at `learning_ai_common_plat/packages/ui/`) now exports a `ToastProvider` component and a `toast()` function. Some product web apps already have their own toast implementations. This task wires `ToastProvider` into every app that's missing one, and documents which apps already have a custom implementation (leave those alone).
## What Was Built
```typescript
// From @bytelyst/ui
export { ToastProvider, toast, useToast, dismissToast } from './components/Toast.js';
```
- `ToastProvider` — wraps `{children}`, renders a fixed toast container at bottom-right
- `toast({ type, title, description?, duration? })` — global function, no hook needed
- `useToast()` — returns `{ toast, dismiss }` for component-scoped usage
- Types: `success`, `error`, `warning`, `info`
- Auto-dismiss after 5s by default
## Audit: Current Toast Status Per App
Run this audit first for each repo to understand the current state:
```bash
cd <repo>
grep -rn 'toast\|Toast' web/src/ --include='*.tsx' --include='*.ts' | grep -v node_modules | grep -v '.test.' | head -30
```
### Expected Findings
| Repo | Status | Action |
| ------------------------------ | -------------------------------------------------------- | ------------------------ |
| `learning_ai_clock` | Has custom `Toast.tsx` component | **Skip** — keep existing |
| `learning_ai_fastgap` | No toast system | **Add** ToastProvider |
| `learning_ai_jarvis_jr` | No toast system | **Add** ToastProvider |
| `learning_ai_trails` | Has custom `Toast.tsx` in `web/src/components/Toast.tsx` | **Skip** — keep existing |
| `learning_ai_flowmonk` | No toast system | **Add** ToastProvider |
| `learning_ai_notes` | No toast system | **Add** ToastProvider |
| `learning_ai_local_memory_gpt` | No toast system | **Add** ToastProvider |
| `learning_ai_local_llms` | No toast system | **Add** ToastProvider |
> **IMPORTANT:** Verify the audit above before making changes. If an app already has a working toast, do NOT replace it.
## Steps for Each Repo That Needs ToastProvider
### 1. Add `@bytelyst/ui` dependency
Check if the repo already has `@bytelyst/ui` in `package.json`. If not, add it:
```json
// In web/package.json (or dashboard/package.json for local-llms)
{
"dependencies": {
"@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui"
}
}
```
Then run `pnpm install` (or `npm install`).
### 2. Find the root layout file
The ToastProvider must wrap the entire app. Find the correct layout:
- **If the app has `web/src/app/layout.tsx`** — this is the root layout
- **If the app has `web/src/app/providers.tsx`** — add it there (preferred, keeps layout clean)
- **LocalLLMLab:** `dashboard/src/app/layout.tsx`
### 3. Add ToastProvider to the layout
**Pattern A: Direct in layout.tsx (if no providers.tsx exists)**
```tsx
import { ToastProvider } from '@bytelyst/ui';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<ToastProvider>{children}</ToastProvider>
</body>
</html>
);
}
```
**Pattern B: In providers.tsx (if it exists)**
```tsx
import { ToastProvider } from '@bytelyst/ui';
export function Providers({ children }: { children: React.ReactNode }) {
return (
<ToastProvider>
{/* ...existing providers... */}
{children}
</ToastProvider>
);
}
```
### 4. Verify build
```bash
cd web && pnpm run build # or: npm run build -- --webpack
```
### 5. Commit and push
```bash
git add -A
git commit -m "feat(design-system): wire ToastProvider from @bytelyst/ui into root layout"
git push origin main
```
## Important Rules
- **Do NOT replace existing custom toast implementations** — ChronoMind and ActionTrail have their own. Leave them.
- **ToastProvider must be a client component** — it uses `useState`/`useEffect`. The layout.tsx is typically a server component. Either:
- Wrap `ToastProvider` in a `'use client'` providers file, OR
- Import it in an existing client-side providers wrapper
- **Do NOT add `'use client'` to layout.tsx** — that would break server components. Use a separate providers wrapper.
- If the repo doesn't resolve `@bytelyst/ui` (TS errors), ensure `pnpm install` was run after adding the dep
- Commit message: `feat(design-system): wire ToastProvider from @bytelyst/ui into root layout`
## Order
1. `learning_ai_flowmonk` (simplest layout)
2. `learning_ai_jarvis_jr`
3. `learning_ai_notes`
4. `learning_ai_fastgap`
5. `learning_ai_local_memory_gpt`
6. `learning_ai_local_llms`

153
docs/design-system-agents/AGENT_4_ARIA_LABELS_ICON_BUTTONS.md Normal file
View File

@ -0,0 +1,153 @@
# Agent Task: Add ARIA Labels to Icon-Only Buttons (Task 4.2)
## Context
Across all ByteLyst product web apps, there are buttons that contain only an icon (no visible text). Screen readers cannot describe these buttons to users, causing WCAG 2.1 AA failures. This task audits every web app, finds icon-only buttons, and adds `aria-label` attributes.
## What Counts as an Icon-Only Button
A button is "icon-only" if it renders **no visible text** — only an SVG icon or a Lucide/icon component:
```tsx
// BROKEN — no accessible name
<button onClick={handleClose}><X className="h-4 w-4" /></button>
// FIXED
<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.)
- `<Link>` styled as a button with only an icon
- Icon-only elements inside `<DialogClose>`, `<AlertDialogCancel>`, etc. from Radix UI
## Repos to Audit
| 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 |
## Steps for Each Repo
### 1. Find all icon-only buttons
Run this search to find candidate buttons:
```bash
cd <repo>
# Find buttons with Lucide icon imports nearby
grep -rn '<button' web/src/ --include='*.tsx' -A2 | grep -B1 'className="h-[0-9]'
# Find buttons that have an icon component and no text children
grep -rn '<button[^>]*>' web/src/ --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) '
```
### 2. For each icon-only button, add aria-label
Choose descriptive, action-oriented 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"` |
| `<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"` |
### 3. Handle conditional icon buttons
Some buttons change icon based on state:
```tsx
// BEFORE
<button onClick={toggle}>
{expanded ? <ChevronUp /> : <ChevronDown />}
</button>
// AFTER
<button onClick={toggle} aria-label={expanded ? "Collapse" : "Expand"}>
{expanded ? <ChevronUp /> : <ChevronDown />}
</button>
```
### 4. Handle icon links (anchors styled as buttons)
```tsx
// BEFORE
<Link href="/settings"><Settings className="h-5 w-5" /></Link>
// AFTER
<Link href="/settings" aria-label="Settings"><Settings className="h-5 w-5" /></Link>
```
### 5. Verify no icon-only buttons remain unlabeled
```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]'
```
Manual review is needed — the grep above will have false positives (buttons with text children).
### 6. Build verify
```bash
cd web && pnpm run build # or: npm run build -- --webpack
```
### 7. Commit and push
```bash
git add -A
git commit -m "feat(a11y): add aria-label to icon-only buttons across web app"
git push origin main
```
## Important Rules
- **Do NOT change any visual appearance** — only add `aria-label` attributes
- **Do NOT add aria-label to buttons that already have visible text** — that creates redundancy
- **Use context-specific labels** — `"Delete timer"` is better than `"Delete"` when context is clear
- **Do NOT add aria-label to decorative icons** — icons next to text (e.g., `<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
- 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)