Files
skillshare/wiki/frontend.md
T
Willie 3ba95ef49e feat(plugin): add npm packages from pi.dev through Pi (#363)
* chore(design): export dashboard tokens for design tools

Mockup tools read a design system's tokens.json rather than our CSS, so
designs drifted from the dashboard's Clean theme. The script derives the
tokens from components.css, and CI runs its test so a new color
variable without a usage note fails instead of silently going missing.

* feat(plugin): add npm packages from pi.dev through Pi

Pi packages on pi.dev are npm packages, which Plugins could not add:
it only took local or Git sources, so users had to install them with Pi
and import them. `plugin add npm:<package>` now hands them to
`pi install` for Pi targets and records the binding like an import.

Skillshare can't fetch or review an npm package, and Pi runs its install
scripts, so the preview says so, discover refuses npm sources, and only
targets that run pi itself take them. Pi keeps one entry per package
name, so another version replaces it in place and keeps its extension
filters; Skillshare records the new entry so a reinstall restores them,
and refuses a package another Skillshare package already manages, since
removing one would remove both. Pinned versions are skipped on update
because pi update keeps them.

The dashboard accepts npm sources, a pasted `pi install` command or a
pi.dev address, lists only Pi targets, and the Pi Extensions tab links
to adding a package with that target selected. Pi packages show Pi's
mark in the plugin list.

A blocked change now keeps its own reason when the Agent's CLI is also
missing, and the message key always matches the message the CLI prints.

* fix(plugin): keep npm package names and accept pi by path

The default name of an npm package went through the file-path rule, which
cut its last dot segment as an extension: npm:foo.bar was recorded as foo,
and adding npm:foo.bar@1.2.3 later derived foo.bar and was refused as
another package managing the same Pi entry. npm names are now taken from
the package spec.

A Pi account whose CLI is an absolute path to pi was treated as running
another executable, so it could not take npm packages. It now uses the
same path- and platform-aware check as the Pi Extensions tab.

* docs(wiki): add a pull-requests topic for Codex review rounds

Handling Codex's review was only known from practice: confirm each
finding, fix it with a failing test first, reply in its thread, ask for
another review, and follow up until it answers. Writing it down keeps
agents from resolving threads, amending pushed commits, or stopping at
the 👀 that only means the review is still running.

* feat(ui): give the Extras AGENTS.md and Memory tabs one layout

The two tabs shared a page but looked like different products: the header
shifted between them, notes sat in a joined box with an icon toolbar, and
agents showed as an icon strip in a side card. Switching tabs felt jarring.

Memory now follows the AGENTS.md layout: a sticky list column with search,
the note's name with Edit and a More actions menu, the same preview box,
and Use with agents as one row per tool under the note. Long notes open
collapsed like shared files do. The AGENTS.md list gains a search box and
the same sticky column. The Memory tab label stays English in every locale,
like AGENTS.md. Docs and screenshots follow the new layout.

* chore(docs): add a script that serves the Memory screenshot homes

The Memory how-to screenshots came from demo homes that were never
recorded, so reshooting them meant rebuilding the data by hand. The script
rebuilds the fresh and the populated home inside the devcontainer, serves
each behind the Vite dev server, and hands the port back to air afterwards.

* fix(plugin): refuse npm sources Pi can't resolve

validNpmSource accepted specs such as npm:foo/bar, npm:foo@ and names
containing "..", which Pi's own parser rejects. They passed preview, and
Apply recorded a pending binding before pi install failed, leaving an
entry every later sync retried. Validate with the same grammar the Pi
settings reader uses, which also covers a scope without a package name.

* fix(ui): show the default name when adding an npm package to Pi

The name field for an npm source was blank, so it looked like a name was
missing. Leaving it empty records the package name without its version or
scope, as the git flow already shows; the field now shows that name as its
placeholder.
2026-10-04 00:43:43 +08:00

5.8 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
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-fade-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.
  • Use existing TanStack Query keys, client helpers, and stale-time patterns. Invalidate the correct queries after mutations.

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 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. 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.

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.