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

Archipelago design system for agent-built apps

Status: planning draft, 2026-10-09. Companion to the terminal and developer environment plan. 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:

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.