Every page faded in over 200ms while sliding up 8px. Moving between pages in the sidebar is the most frequent action in the dashboard, so the slide made each click feel slow and shifted the content the user was comparing. Pages now use animate-page-in, a 120ms opacity-only fade, which softens the swap without delaying it or moving anything. The shared fade, dropdown and dialog entrances also ignored prefers-reduced-motion and kept sliding or scaling. Under reduced motion they now keep only their fade; a dialog changing step still swaps without animation, as before. The frontend wiki and the UI style skill told contributors to put animate-fade-in on page roots; they now name animate-page-in and keep animate-fade-in for in-page reveals. Release-As: 0.30.2
9.1 KiB
Frontend Development
Use when changing React components, pages, CSS, responsive layouts, interactions, or visual behavior in the ui/ dashboard or website/.
Shared Workflow
- Decide whether the target is the dashboard or public website; they use different visual languages.
- Search neighboring pages/components and existing tokens/classes before creating anything new.
- Preserve data, loading, error, empty, keyboard, and accessibility states.
- Build and test inside the devcontainer, then capture and inspect screenshots for visual changes.
- Check Clean/Playful × light/dark for the dashboard, and light/dark plus affected breakpoints for the website.
Dashboard Sources of Truth
| Concern | Source |
|---|---|
Tokens and ss-* classes |
ui/src/components.css |
| Tailwind token mapping | ui/src/index.css |
| Theme selection | ui/src/context/ThemeContext.tsx |
| Shared components | ui/src/components/ |
| Query keys | ui/src/lib/queryKeys.ts |
| Which queries a mutation makes stale | named events in ui/src/lib/queryEvents.ts, called as invalidate(queryClient, '<event>') |
| Queries shared across pages (overview, MCP, skills, targets, diff) | ui/src/hooks/useSharedQueries.ts |
| API client | ui/src/api/client.ts |
?kind= query strings |
kindQuery() in ui/src/api/http.ts |
| Translation strings | ui/src/i18n/ |
The dashboard supports Clean and Playful styles plus light, dark, and system modes. New UI must use CSS variables, token utilities, and existing ss-* classes. Never hardcode colors, radii, shadows, or fonts. Scope Playful-only pastels to the Playful theme.
python3 scripts/design/tokens.py exports the Clean tokens from components.css in Design System tokens.json format, for mockup tools that read a design system instead of the CSS. A new Clean color variable needs a usage note in that script, or the export (and its test) fails.
Dashboard Composition
- Use
ss-wrap animate-page-inon the page root and placePageHeaderfirst. - Prefer
ss-listandss-rfor lists,ss-note badfor errors, andEmptyStatefor empty states. - Use existing shared components such as
Button,IconButton,Card,DialogShell,ConfirmDialog,Input,Select,Checkbox,Pagination, andTooltip. - Route destructive actions through
ConfirmDialog; never usewindow.confirm(). - Use
lucide-reacticons. UseAgentIconfor real agents/tools rather than emoji or generic icons. - Icon-only controls require accessible names, and interactive targets must be at least 24 px.
- Route user-visible strings through
useT(). Preserve existing English technical labels for status, mode, and kind values. Choose between a counted sentence's.oneand.otherkeys withplural(key, count)fromui/src/i18n. Tests fail on a key that is not inen.json, whether the dashboard orinternal/pluginrefers to it;ui/src/i18n/README.mddescribes them and their escape hatch. - Use existing TanStack Query keys, client helpers, and stale-time patterns. Write no key literal outside
queryKeys.ts. After a mutation, callinvalidatewith the event that happened; do not list keys or callinvalidateQueriesin a page. A new kind of change gets a new event and a row inqueryEvents.test.ts.
Below 768 px, the dashboard shell replaces the fixed sidebar with a navigation button and a DialogShell menu, and reduces page padding. The menu shares the desktop navigation and closes before link or keyboard navigation attempts (including blocked unsaved edits), on Escape or backdrop click, or when switching to desktop width. Update rows put their actions and status below the resource name on mobile; row actions stay visible on touch devices. Skills and Agents tabs scroll horizontally when needed. The language picker stays within the viewport and scrolls in short windows; the mobile tour omits the hidden sidebar shortcut step.
Do not run an unconfigured Prettier in ui/ because it creates broad unrelated diffs. When Tailwind utilities conflict with the ss-* component layer, inspect the cascade before adding more complex selectors.
The skill/agent editor uses yaml to read and write frontmatter, including escaped strings, block scalars and nested flow metadata. Description prose uses folded block style when needed; repeated edits preserve its value and nested metadata. Unedited frontmatter stays verbatim. The legacy parser remains a fallback for non-YAML headers. Nested object fields are shown as read-only JSON instead of editable [object Object] text.
The config editor's Beautify and Save actions organize top-level YAML sections: sources and default settings, targets, skills, agents, extras, MCP, plugins, hooks, other settings, ignore, and audit. Sections have blank lines between them; nested mappings and lists retain their order, and unknown keys remain in their original relative order at the end. Comments and anchors are preserved; the yaml-language-server schema directive stays at the top of the document, including when repairing a previously misplaced directive. If reordering would change an alias reference, the original section order is retained.
Git Sync shows both local and remote commit counts when histories diverge and offers Pull and merge before pushing. With uncommitted changes and known remote updates, Commit and pull saves local changes before merging. A pull_conflict response opens a whole-file version comparison: users must choose local or remote for every conflict before applying; Keep all local and Keep all remote set every file at once. Cancel leaves the repository unchanged. The API retries the merge and validates the reviewed local/remote revision hashes; stale choices require a fresh review. Metadata conflicts still merge automatically. Binary files and files over 16 KiB have no text preview. After merging and syncing, users push separately. Sync both ways chains commit (when dirty), pull, and push in one action, like push --pull, after a confirmation listing each step with the current counts (dry run previews without asking); a conflict stops it at the review before pushing. It pulls with alwaysSync so targets sync even when nothing new arrives, and on remote_empty it pushes first, then pulls to sync. First-pull merge_failed handling and its confirmed force replacement remain separate from this workflow. See ai_docs/tests/git_ui_conflicts_runbook.md for verification and an isolated preview fixture.
Localization Verification
- Check rendered non-English UI, not just locale-key parity. Skillshare-owned API reasons, notes, warnings and guidance are UI copy too; do not display their English messages directly merely because they originate in Go.
- Trace each changed message from its producer to every visible consumer, including file rows, Details, tooltips and dialogs. Reuse existing translation mappings; preserve paths, names, identifiers, native terms and unknown external diagnostics.
- Inspect representative populated states in the requested locale, including read-only/managed rows. A translated heading or a successful build does not establish that backend guidance is translated.
- Copy/translation-only changes normally need existing locale/placeholder checks and rendered verification, not new tests repeating dictionary values or mocked translations. Add coverage only for a concrete behavioral failure that existing checks cannot detect; follow the
testingtopic's test-value rules.
Dashboard Tests
- Put logic in a plain
.tsmodule and test it there with inputs and outputs. - A rendered
.test.tsxtest must protect user data: the payload a write or delete sends, a confirmation before deleting or overwriting, a draft kept after an error or unsaved-edit prompt, or a stale/conflicting version refused. Security checks (sanitizing, secrets as env references) count too. - Do not write rendered tests for layout, icons, collapse/expand, remembered widths or filters, hover, display order, text being shown, toasts, focus or navigation. Check those with screenshots while working on them.
Website Boundary
This topic also loads website/AGENTS.md for website-specific commands, structure, and deployment rules. Additional boundaries:
- Documentation chrome uses the clean treatment. The hand-drawn string-board treatment belongs only to the homepage and feature map.
- The website keeps its existing
--color-penciland--color-papertoken names. Do not import the dashboard's--inkand--bgnaming. - Mermaid uses the global configuration. Keep labels short, use
<br/>for line breaks, and verify rendered output with a screenshot. - Load
documentationfor content changes. Verify public behavior against Go source before writing it.
Verification
Run all package commands inside the devcontainer. Select checks according to scope:
- Dashboard: targeted Vitest,
pnpm run lint,pnpm run build, and visual screenshots. - Website:
pnpm run typecheckandpnpm run build; the build validates broken links. - API-connected UI: compare
internal/server/server.goroutes, handler tests, and client types.
Report the themes, modes, and viewport sizes inspected, plus any visual verification that could not be performed.