Assistive UX
Use this skill for Berd product intelligence moments that teach,
suggest, or adapt settings based on user behavior.
Before changing code, read docs/assistive-ux.md. Treat that doc as the source
of product intent and architecture.
Core Rule
Keep assistive state separate from user settings:
User settings answer: what should the product do?
Assistive UX answers: what has the app shown, observed, accepted, retired, or applied?
Do not store guidance lifecycle state inside a feature setting. Do not use
assistive state as the source of truth for product behavior.
Types
discover: teaches that a control, setting, or capability exists. It should
not change settings.suggest: notices a repeated behavior and asks before changing a setting.autoApply: changes a reversible local setting only after strong evidence,
then explains the change and offers undo.
Use autoApply conservatively. Never auto-apply changes involving secrets,
credentials, permissions, destructive actions, provider setup, billing-like
behavior, or hard-to-reverse choices.
Implementation Workflow
- Define or update the rule in
src/shared/assistive-ux/registry.ts.
- Keep lifecycle reads and writes in
src/shared/assistive-ux/runtime.ts and
src/shared/assistive-ux/state.ts.
- Render the moment from the relevant feature surface.
- Retire the moment when the user accepts it, dismisses it, sees it enough
times, or manually changes the related setting.
- If the moment changes a setting, call the setting's public setter and provide
an undo path when the change is automatic.
- Keep stored signals coarse. Do not store chat text, file paths, provider
secrets, credentials, or message contents.
UX Checklist
Before shipping, confirm:
- The moment appears close to the behavior it helps with.
- The copy explains the next action without selling the feature.
- The primary workflow still has visual priority.
- The moment has a clear retirement path.
- Repeated exposure is capped.
- Manual setting changes stop or reset related guidance.
- The behavior works in light and dark themes.
Testing
Add focused tests for:
- fresh eligibility
- shown-count updates
- max-show expiration
- acceptance or dismissal retirement
- related setting-change retirement
- invalid localStorage fallback
- any feature surface that renders or applies the moment
For broad behavior, add Playwright coverage only when the flow benefits from
real app navigation or persistence across reloads.
1---2name: assistive-ux3description: Use when adding, reviewing, designing, testing, or managing Assistive UX moments in Berd, including discover, suggest, and autoApply guidance, adaptive settings, behavior signals, retirement rules, or changes under src/shared/assistive-ux.4---56# Assistive UX78Use this skill for Berd product intelligence moments that teach,9suggest, or adapt settings based on user behavior.1011Before changing code, read `docs/assistive-ux.md`. Treat that doc as the source12of product intent and architecture.1314## Core Rule1516Keep assistive state separate from user settings:1718```text19User settings answer: what should the product do?20Assistive UX answers: what has the app shown, observed, accepted, retired, or applied?21```2223Do not store guidance lifecycle state inside a feature setting. Do not use24assistive state as the source of truth for product behavior.2526## Types2728- `discover`: teaches that a control, setting, or capability exists. It should29 not change settings.30- `suggest`: notices a repeated behavior and asks before changing a setting.31- `autoApply`: changes a reversible local setting only after strong evidence,32 then explains the change and offers undo.3334Use `autoApply` conservatively. Never auto-apply changes involving secrets,35credentials, permissions, destructive actions, provider setup, billing-like36behavior, or hard-to-reverse choices.3738## Implementation Workflow39401. Define or update the rule in `src/shared/assistive-ux/registry.ts`.412. Keep lifecycle reads and writes in `src/shared/assistive-ux/runtime.ts` and42 `src/shared/assistive-ux/state.ts`.433. Render the moment from the relevant feature surface.444. Retire the moment when the user accepts it, dismisses it, sees it enough45 times, or manually changes the related setting.465. If the moment changes a setting, call the setting's public setter and provide47 an undo path when the change is automatic.486. Keep stored signals coarse. Do not store chat text, file paths, provider49 secrets, credentials, or message contents.5051## UX Checklist5253Before shipping, confirm:5455- The moment appears close to the behavior it helps with.56- The copy explains the next action without selling the feature.57- The primary workflow still has visual priority.58- The moment has a clear retirement path.59- Repeated exposure is capped.60- Manual setting changes stop or reset related guidance.61- The behavior works in light and dark themes.6263## Testing6465Add focused tests for:6667- fresh eligibility68- shown-count updates69- max-show expiration70- acceptance or dismissal retirement71- related setting-change retirement72- invalid localStorage fallback73- any feature surface that renders or applies the moment7475For broad behavior, add Playwright coverage only when the flow benefits from76real app navigation or persistence across reloads.
block