docs: plan terminal sessions, developer setup and agent design system

docs/archipelago-agent-design-system-spec.md

@@ -0,0 +1,268 @@
+# Archipelago design system for agent-built apps
+
+Status: planning draft, 2026-10-09. Companion to the
+[terminal and developer environment plan](terminal-developer-environment-spec.md).
+No tokens, components, templates or installed skills are changed by this draft.
+
+An agent asked to build an Archipelago app should produce an app that belongs in
+Archipelago by construction. Give it a maintained component kit, runnable
+starters, documented screen patterns and visual references. A skill telling it
+to “use glassmorphism and orange” is insufficient.
+
+The same foundation should drive Terminal, setup screens, first-party apps and
+newly generated apps. Existing third-party applications keep their own product UI;
+their Archipelago entry, launch and integration surfaces follow this contract.
+
+## Evidence and design authority
+
+At repository baseline `2cb1bae5`, the dashboard's design is distributed across
+`neode-ui/src/style.css`, `neode-ui/tailwind.config.js`, Vue components, and the
+short standards section of `docs/developer-guide.md`. AIUI maintains a separate
+token/style definition in `aiui/packages/app/src/styles/main.css`.
+
+| Existing rule | Source observation | Contract to preserve or resolve |
+| --- | --- | --- |
+| Dark controls | Dashboard sets `color-scheme: dark` and explicit select colors | Dark baseline, including native controls |
+| Glass cards | `.glass-card`: black at 0.65 alpha, white border at 0.18, 16px radius | Preserve the established surface, not a generic frosted card |
+| Blur | Default card blur 18px; dashboard contexts deliberately suppress backdrop blur to avoid rendering corruption | Context-aware surface variants; never reintroduce blanket blur |
+| Buttons | `.glass-button`: 44px minimum, 12px radius; established focus/hover/pressed variants | Reusable buttons with full interaction states |
+| Accent | Dashboard focus/action uses `#fb923c`; AIUI accent is `#F7931A` | Named semantic tokens with explicit mapping; do not silently choose one for everything |
+| Typography | Dashboard body uses Avenir Next/system fallback, headings have bundled Montserrat; AIUI uses Inter/system fallback | Approved roles, metrics, fallback behavior and licensed assets |
+| Spacing | Tailwind extends a 4px grid | Shared spacing scale and layout examples |
+| Search | Existing search is 40px on desktop, 52px below the 920px breakpoint; right clear control retains focus | Shared search component and documented responsive behavior |
+| Card actions | Existing CSS places full-width actions at the bottom on desktop and mobile | Preserve this layout in generated card screens |
+| Modal layout | `BaseModal.vue`: pinned title/footer with independently scrolling content | Shared dialog shell with tested focus and Back behavior |
+| Mobile layout | Dynamic viewport, safe-area and audio-player offsets already exist | One documented inset contract; prevent double padding in embedded apps |
+| Success | Shared `PaymentSuccessPane.vue` and `IdentitySuccessPane.vue` express branded completion | Reuse the relevant pattern only when its completion condition is actually met |
+| Embedded canvas | AIUI embedded mode is transparent; standalone has its own background | Host owns wallpaper; apps choose explicit embedded/standalone mode |
+
+These observations seed a visual audit; they do not make every legacy style a
+rule. Capture representative current screens in the running supported UI before
+extracting components. Approve Home, Apps, app detail, Settings, forms/dialogs,
+list/detail screens, Terminal and mobile examples as reference baselines.
+
+The source of truth becomes versioned tokens plus components and pattern docs.
+Screenshots illustrate that contract and detect drift; they do not replace it.
+Existing dashboard and AIUI differences need explicit migration decisions.
+Preserve the current look first and make intentional design improvements visible
+in review rather than introducing them incidentally through an app template.
+
+## Deliverable shape
+
+Proposed layout, to be finalized against repository packaging conventions:
+
+```text
+packages/archipelago-design/
+  tokens/                 semantic definitions and generated CSS/JSON
+  styles/                 scoped foundations and non-Vue component classes
+  assets/                 approved fonts, icons and licenses
+packages/archipelago-ui/
+  components/             Vue components with documented states
+  patterns/               app shells and composed screen patterns
+docs/design-system/
+  index.md                decision guide and version compatibility
+  foundations.md          typography, color, surfaces, spacing, motion
+  components.md           usage, states, accessibility, stable imports
+  patterns.md             complete screen composition and behavior
+  examples/               reference captures and their matching source
+examples/archipelago-app/
+  ...                     working starter with manifest and tests
+skills/archipelago-design/
+  SKILL.md                concise trigger, routing and workflow
+  references/             versioned design index and evaluation rubric
+```
+
+Build an offline component gallery with the UI kit. Every example links to its
+source, token usage and applicable app pattern. A developer can run the gallery
+without a node session or provider API key. It must show loading, empty, error,
+success, disabled, focused, hovered and pressed states, not only the ideal screen.
+
+Publish packages only as part of an explicitly authorized later implementation
+workflow. Until then these names and paths describe proposed deliverables.
+
+## Token contract
+
+Use framework-neutral CSS custom properties generated from a single definition.
+Vue components and any Tailwind adapters consume the same values. Prefix tokens
+with `--archy-`; do not expose arbitrary dashboard-global selectors to apps.
+
+| Token family | Required coverage |
+| --- | --- |
+| Color | Canvas, card, inset, overlay, border, text primary/secondary/muted, interactive accent, focus, selected, success, warning, danger and info |
+| Typography | Body, heading and monospace families; type scale, weights, line heights and numeric alignment |
+| Space and size | 4px-based scale, page gutters, content widths, control heights, touch targets and icon sizes |
+| Shape | Card, dialog, input, button and pill radii |
+| Elevation | Card/overlay shadows, border strengths, blur-permitted and no-blur surfaces |
+| Motion | Durations/easing, permitted hover/press transitions and reduced-motion equivalents |
+| Layering | Header, navigation, menu, popover, modal and toast layers with ownership rules |
+| Viewport | Host-provided safe areas, keyboard viewport, navigation/audio offsets and embedded mode |
+| Terminal | Canvas, foreground, cursor, selection and a readable 16-color ANSI palette |
+
+Make brand orange and interactive/focus orange distinct roles if preserving both
+existing values. Status colors must communicate meaning alongside text/icons.
+Name action variants by purpose: the existing orange “warning” class also serves
+primary actions, so exporting that name unchanged would teach the wrong semantics.
+
+Typography must have predictable dimensions on Debian, Android and desktop
+browsers. Use only redistributable local font assets. Referencing Avenir or Courier
+New in a fallback stack does not license bundling those fonts. Freeze a tested
+body/heading/mono choice and line-height matrix in the visual review; do not let
+each generated app choose its own fonts or fetch a font CDN.
+
+Check contrast on actual composited surfaces and the brightest/darkest supported
+backgrounds. Opacity values or CSS comments alone do not establish accessibility.
+Small text must remain readable, and focus must remain visible where current
+global styles suppress outlines. Low-power/no-backdrop-filter fallbacks retain
+the same hierarchy and usable contrast.
+
+## Components and patterns agents can reuse
+
+Extract reusable behavior from existing code; avoid giving agents a second
+lookalike library with slightly different interactions. Package components
+without dashboard stores, router assumptions, privileged RPC clients or secrets.
+Use adapters for integrations owned by the host.
+
+| Foundation | First required components | Existing reference |
+| --- | --- | --- |
+| Structure | AppShell, PageHeader, Section, Card, InsetPanel, ActionRow | Dashboard CSS, app headers, card action rules |
+| Controls | Button, IconButton, TextField, PasswordField, Select, Toggle, SearchField, SegmentedControl | `ToggleSwitch.vue`, `PasswordRevealInput.vue`, `AppSearchField.vue` |
+| Navigation | Tabs, Breadcrumbs, Back action, contextual menu | Dashboard navigation, `BackButton.vue`, Cloud menus |
+| Feedback | StatusBadge, EmptyState, Skeleton, Progress, InlineError, Toast | `EmptyState.vue`, `SkeletonCard.vue`, `ToastStack.vue`, existing progress patterns |
+| Dialogs | Dialog, ConfirmDialog, credential handoff | `BaseModal.vue`, `AppConfirmModal.vue`, `AppCredentialInterstitial.vue` |
+| Data | ListRow, responsive table/list, detail key/value row, copy action | Existing app lists, `CopyButton.vue` |
+| Terminal | TerminalShell, SessionList, SessionRow, ConnectionStatus, mobile key strip | New consumers of the same foundation |
+
+Each public component documents supported props/events/slots, sizing, keyboard
+behavior, accessibility, states and examples. Shared helpers must respect context:
+the current modal helper captures Escape and arrow keys, which is unsuitable
+for a terminal, editor or other widget that owns those keys. Fix/reuse that
+behavior through explicit contracts rather than blindly wrapping Terminal in it.
+
+Provide composed patterns for:
+
+- A searchable collection with filters, list/grid view, empty state and bottom
+  card actions.
+- A detail screen with back navigation, metadata, status and primary action.
+- Settings grouped by task, with visible validation, save progress and retry.
+- A multi-step setup flow with skip/resume, honest progress and recovery.
+- First launch and credential handoff, including apps with their own login.
+- A destructive confirmation that names its target and data-preservation effect.
+- A session picker and terminal that clearly distinguish Close from End session.
+
+Copywriting is part of the contract: concise task labels, useful error recovery,
+explicit pending versus complete states, no raw internal exception as the sole
+user message, and appropriate units/time formatting. Technical detail is
+available on demand. App-generated progress must reflect actual work.
+
+## App shells and host integration
+
+Supply a preferred Vue/TypeScript starter and a small portable HTML/CSS example.
+Existing React or other framework applications consume the tokens/styles and
+behavior contracts; do not require a framework rewrite to package an app.
+Full additional framework bindings follow actual demand and have their own
+acceptance, rather than presenting CSS classes as equivalent accessible widgets.
+
+New starters include local assets, locked dependencies, scripts, manifest,
+container definition, health check, persistent-data example, tests and a complete
+reference screen. A starter must build and run from its copied location without
+monorepo-only aliases. It cannot require fetching current dashboard CSS at runtime.
+
+The host integration contract defines:
+
+- Explicit standalone versus embedded appearance. Embedded apps use a transparent
+  canvas where appropriate; they do not add a duplicate wallpaper or navigation
+  shell. Standalone mode still has a complete, readable canvas.
+- Versioned, non-secret theme/inset messages if runtime synchronization is needed.
+  Validate sender origin, source window and payload; no wildcard privileged
+  message bridge. An app must remain usable with no host handshake.
+- Exactly one owner for top/bottom safe-area padding and fixed player/navigation
+  clearance. Test the actual Companion WebView, not just a mobile screenshot.
+- Existing launch interfaces and app-gate behavior from the developer docs.
+  Asset URLs work under their supported base path and HTTP/HTTPS entry points.
+- Nostr signer, media controls and credential handoff only through their supported
+  APIs. Visual kit installation does not give an app host management access.
+
+Package tokens/components with the app's pinned kit version. Evolve them with
+documented compatibility and migrations. Runtime theme values may be forwarded
+through the agreed contract; runtime JavaScript/CSS replacement is not the update
+mechanism. A platform update must not silently break every installed app.
+
+## Agent workflow
+
+The app skill always routes new UI work through `archipelago-design`. The system
+skill does the same when a system modification affects a visible screen. A
+backend-only request loads no unnecessary design material.
+
+For relevant tasks the agent:
+
+1. Reads the design index, supported kit version and matching pattern; identifies
+   existing components before creating new ones.
+2. Inspects the reference screen and its source, then selects the closest starter.
+3. Implements the requested behavior using shared components and semantic tokens.
+4. Exercises normal, loading, empty, invalid, failed and successful states.
+5. Renders standalone and embedded previews at the required viewports; inspects
+   captures, keyboard behavior and actual component geometry.
+6. Runs app checks and supplies the working preview, component/token provenance,
+   results and any deliberate design exceptions.
+
+Make that loop easy: `archy app new`, `archy app preview` and `archy app check`
+should supply the starter, preview fixtures and relevant checks. Those are
+proposed tools in the terminal plan, not currently implemented commands.
+Ordinary changes within the requested task proceed through this loop without
+requiring approval for every edit. A new shared design primitive or intentional
+departure is identified in the review, with its use case and visual evidence.
+
+The skill should tell agents how to find and use the design system, not make
+them recreate it from a long list of adjectives. Keep the entrypoint concise;
+conditional references cover forms, layout, terminal interaction, media and
+signer flows. Templates and screenshots belong in reusable assets, not prose
+that the agent has to transcribe.
+
+## Design conformance and definition of done
+
+Combine targeted static checks, interaction tests and visual review. Static
+checks cannot prove a coherent design; screenshots cannot prove an accessible
+or correct interaction.
+
+| Gate | Acceptance |
+| --- | --- |
+| Shared foundation | New UI imports the approved kit/version; bespoke color/font/radius/z-index values need a named exception, with allowances for content such as charts and user imagery |
+| Visual hierarchy | Reference-matched page width/gutters, type roles, card surfaces, action placement and density |
+| Responsive layout | 320, 390, 768 and 1440px widths plus phone landscape; 200% text zoom; no accidental horizontal page overflow |
+| Input | Keyboard-only use, visible focus, sensible tab order, labels, dialog focus containment/restoration and Back behavior; terminal keys remain intact |
+| Touch | 44px usable targets for new mobile controls, reachable persistent actions, no essential hover-only interaction |
+| States | Loading, empty, offline, denied, validation error, retry and success demonstrated with deterministic fixtures |
+| Appearance | Dark native controls, foreground/background contrast, reduced motion, no-blur fallback and locally available fonts |
+| Host modes | Embedded/standalone, HTTP/HTTPS where supported, software keyboard, safe areas, audio-player offsets and Companion |
+| Runtime truth | Success and readiness only follow actual confirmed results; theme/state changes do not erase form or session work |
+| Regression | Shared component changes compared against representative dashboard and app reference captures before release |
+
+Choose per-component visual-diff tolerances after baseline capture; avoid a
+single permissive threshold that conceals layout regressions. Stabilize fonts,
+viewport, fixture data and animations. Review intended baseline changes rather
+than automatically accepting new screenshots when CI fails.
+
+Behavioral skill evaluation should use realistic tasks with no hidden design
+brief: build a bookmarks app, add a settings form, create an app with first-run
+credentials, adapt a non-Vue app, and improve Terminal's session picker. Inspect
+the generated artifacts and previews for component reuse, consistent appearance,
+correct manifest integration and usable failure states. Repeat on a fresh
+environment to ensure success does not rely on this checkout or an agent's
+conversation history.
+
+## Implementation order
+
+1. Audit representative existing screens; resolve accent/typography/blur and
+   embedded-mode decisions; record the approved reference set.
+2. Extract semantic tokens and the first components while preserving current
+   dashboard rendering. Migrate a small representative slice to prove parity.
+3. Build the offline gallery, app shell and working starter. Use Terminal/setup
+   as real consumers so the foundation is exercised immediately.
+4. Package the app/design skills with matching docs and assets; run realistic
+   generation tasks against the starter and gallery.
+5. Add scoped conformance checks to app validation and qualification; migrate
+   additional first-party surfaces incrementally.
+
+App generation cannot be called complete while agents still invent the visual
+foundation. Completion means a new agent, a new workspace and an ordinary app
+request reliably produce a working, recognizably Archipelago result.