/ui-development

name: ui-development
description: Build UI pages and extensions for Falcon Foundry apps using React or Vue with the Shoelace design system and Foundry-JS. TRIGGER when user asks to "create a UI page", "build a UI extension", "add a Shoelace component", "call an API from the UI", runs `foundry ui pages create` or `foundry ui run`, or needs help with Vite config, Foundry-JS, or Falcon console theming. DO NOT TRIGGER for backend functions, workflow YAML, or collection schemas.
version: 1.7.1
updated: 2026-11-10
tags: [foundry, ui, react, vue, shoelace]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: frontend

Foundry UI Development

> Build UI with Shoelace components using the `falcon-shoelace` theme (not vanilla Shoelace or raw HTML), and load both the dark and light theme stylesheets so it matches the Falcon console. Use `foundry ui run` for live development, and apply the iframe security patterns to every extension.

> **Part of a suite.** If `development-workflow` has not already run, and this is a new app or its first capability, load the `development-workflow` skill first — it owns the CLI prerequisite check, scaffolding order, and manifest coordination.

Falcon Foundry UI pages and extensions use React or Vue with the Shoelace design system (Falcon-themed) and Foundry-JS for platform integration.

Pages vs Extensions

If the user doesn't specify page or extension, **ask which they prefer** before scaffolding. Present this table to help them decide:

| | UI Pages | UI Extensions | |---|---|---| | **What** | Standalone applications | Console-embedded components | | **Where** | Full-page view in Falcon console | Sidebar widget in detection/host/incident pages | | **Sockets** | N/A | One per extension (see socket table below) | | **Use when** | Complex interactions, multiple views, dashboards | Contextual enrichment, quick-glance data | | **Framework** | Vue, React, or Vanilla JS | Vue, React, or Vanilla JS |

CLI Scaffolding

# Create a React page
foundry ui pages create --name "my-page" --description "Page description" --from-template React --homepage --no-prompt

# Create a Vanilla JS page (no npm install or build step needed)
foundry ui pages create --name "my-page" --description "Page description" --from-template "Vanilla JS" --homepage --no-prompt

# Add navigation entry (separate step — --no-prompt skips this during page creation)
foundry ui navigation add --name "My Page" --path / --ref pages.my-page

# Create an extension targeting a console socket
# REQUIRED: --sockets must be specified — omitting it launches an interactive picker that hangs with Error: EOF
# REQUIRED: Use ONLY values from the Extension Socket Locations table below — do NOT guess socket IDs
foundry ui extensions create --name "my-ext" --description "Description" --from-template React --sockets "activity.detections.details" --no-prompt

# Create a Vanilla JS extension (no npm install or build step needed)
foundry ui extensions create --name "my-ext" --description "Description" --from-template "Vanilla JS" --sockets "activity.detections.details" --no-prompt

**Vanilla JS** needs no `npm install` or `npm run build`. The importmap loads foundry-js from CDN. Use it for simple extensions that display data or make API calls without complex state management. Deploy works with just the raw `src/` files.

> **`--homepage` / `homepage:` is not a navigation link.** It sets the app's root page only and doesn't add a side-menu entry. Only `ui.navigation.links` (via `foundry ui navigation add`) creates a menu item, so an app can be reachable at root yet absent from the menu. Add a nav link for every page you want listed.

The blueprint output is deterministic — see [references/blueprint-templates.md](references/blueprint-templates.md) for exact file contents, Shoelace import patterns, and API integration calling examples.

**Editing a React blueprint:** put the UI in `src/routes/home.jsx`, which gets `falcon` from `useContext(FalconApiContext)` (imported from `../contexts/falcon-api-context`). The other scaffolded files (`app.jsx`, `index.html`, the context, `package.json`, `vite.config.js`, `styles.css`, `routes/about.jsx`, the `components/`) work as generated, so you don't need to read them first. Import Shoelace React wrappers from `@shoelace-style/shoelace/dist/react` (for example, `import { SlButton, SlSpinner } from "@shoelace-style/shoelace/dist/react";`).

> **🚫 DO NOT MODIFY `path` or `entrypoint` in manifest.yml** > > The CLI sets `path` and `entrypoint` correctly during scaffolding. **Never edit these values.** The correct CLI-generated format uses full paths from the app root: > ```yaml > # Page — this is CORRECT, do not shorten > path: ui/pages/my-page/src/dist > entrypoint: ui/pages/my-page/src/dist/index.html > > # Extension — this is CORRECT, do not shorten > path: ui/extensions/my-ext/src/dist > entrypoint: ui/extensions/my-ext/src/dist/index.html > ``` > These long paths are NOT doubled — they are the correct values the CLI generates. Shortening `entrypoint` to `src/dist/index.html` breaks the app. If a deploy error mentions entrypoint or file path, you likely changed `vite.config.js` — revert your changes. The scaffolded config is correct.

Vite Build Configuration

> **🚫 DO NOT MODIFY `vite.config.js`** > > The React blueprint's `vite.config.js` is **turnkey** — it works correctly as scaffolded. Do not change ANY values in it. Specifically: > - **Do not change `base: './'`** — not to `''`, not to `'/'`, not to anything else. `'./'` is correct. > - **Do not change `root: 'src'`** — the manifest expects builds at `src/dist/`. > - **Do not remove `noAttr()`** — required for Foundry's sandboxed iframe. > > The blueprint, manifest, and CLI are coordinated. Changing any config value breaks this coordination and causes deploy failures. Just edit your React/JS component code and deploy.

Shoelace Design System

Install the Falcon-themed S