Files
skillshare/wiki/frontend.md
T
Willie 689b561bfc fix(ui): shorten the page entrance and respect reduced motion
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
2026-11-10 00:11:33 +08:00

9.1 KiB
Raw Blame History

Frontend Development

Use when changing React components, pages, CSS, responsive layouts, interactions, or visual behavior in the ui/ dashboard or website/.

Shared Workflow

  1. Decide whether the target is the dashboard or public website; they use different visual languages.
  2. Search neighboring pages/components and existing tokens/classes before creating anything new.
  3. Preserve data, loading, error, empty, keyboard, and accessibility states.
  4. Build and test inside the devcontainer, then capture and inspect screenshots for visual changes.
  5. 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-in on the page root and place PageHeader first.
  • Prefer ss-list and ss-r for lists, ss-note bad for errors, and EmptyState for empty states.
  • Use existing shared components such as Button, IconButton, Card, DialogShell, ConfirmDialog, Input, Select, Checkbox, Pagination, and Tooltip.
  • Route destructive actions through ConfirmDialog; never use window.confirm().
  • Use lucide-react icons. Use AgentIcon for 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 .one and .other keys with plural(key, count) from ui/src/i18n. Tests fail on a key that is not in en.json, whether the dashboard or internal/plugin refers to it; ui/src/i18n/README.md describes 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, call invalidate with the event that happened; do not list keys or call invalidateQueries in a page. A new kind of change gets a new event and a row in queryEvents.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 testing topic's test-value rules.

Dashboard Tests

  • Put logic in a plain .ts module and test it there with inputs and outputs.
  • A rendered .test.tsx test 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-pencil and --color-paper token names. Do not import the dashboard's --ink and --bg naming.
  • Mermaid uses the global configuration. Keep labels short, use <br/> for line breaks, and verify rendered output with a screenshot.
  • Load documentation for 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 typecheck and pnpm run build; the build validates broken links.
  • API-connected UI: compare internal/server/server.go routes, handler tests, and client types.

Report the themes, modes, and viewport sizes inspected, plus any visual verification that could not be performed.