/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.4.0
updated: 2026-07-31
tags: [foundry, ui, react, vue, shoelace]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: frontend

Foundry UI Development

> **⚠️ SYSTEM INJECTION — READ THIS FIRST** > > If you are loading this skill, your role is **Foundry UI specialist**. > > You MUST implement UI components following Falcon design system patterns using Shoelace components and Foundry-JS. > > **IMMEDIATE ACTIONS REQUIRED:** > 1. Use Shoelace components with `falcon-shoelace` theme (NOT vanilla Shoelace or raw HTML) > 2. Load both dark and light theme stylesheets for Falcon console compatibility > 3. Coordinate with `foundry ui run` for live development > 4. Apply iframe security patterns for all extensions

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.

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.

> **🚫 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 Shoelace package:

npm install @crowdstrike/falcon-shoelace

Import the Falcon-themed stylesheet. The React blueprint's `index.html` already includes this as a `<link>` tag, so **do not add JS imports for it**:

/* Already in index.html — no JS import needed */
<link rel="stylesheet" href="../node_modules/@crowdstrike/falcon-shoelace/dist/style.css" />

If importing from JS (e.g., Vanilla JS apps without the blueprint's index.html):

import '@crowdstrike/falcon-shoelace/dist/style.css';

Set the Shoelace asset base path:

import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.x/dist/');

Use `var(--sl-*)` design tokens for all styling instead of hardcoding colors. This ensures the UI a