@signalflare-ai/ui 0.5.0

package/skills/component-selection/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: component-selection
+description: Choose and implement the right @signalflare-ai/ui components and imports for React codebases. Use when adding UI, selecting between SignalFlare components, wiring props or variants, or looking for canonical component usage.
+license: MIT
+metadata:
+  package: "@signalflare-ai/ui"
+  sources: "ai/component-registry.json, ai/component-registry.md, packages/registry/AGENTS.md"
+---
+
+Use this skill when a task involves adding or updating UI with `@signalflare-ai/ui`.
+
+## What to Use
+
+- Prefer `@signalflare-ai/ui` components before building custom UI from scratch.
+- Check the installed component metadata first in `@signalflare-ai/ui/ai/component-registry.json` or `@signalflare-ai/ui/registry/component-registry.json`.
+- Prefer explicit subpath imports when they improve clarity, for example `@signalflare-ai/ui/components/button`.
+- Use the main package entry when the project already imports from `@signalflare-ai/ui` directly.
+
+## Selection Rules
+
+- Use library components from `src/components/` for app UI.
+- Use `sf add <block>` only for installable blocks; blocks are not normal package exports.
+- Do not import from `src/blocks/` or deep source paths inside the package.
+- Treat `ai/component-registry.json` as the source of truth for component names, categories, props, variants, and examples.
+
+## Implementation Rules
+
+- Follow the existing component API exactly; do not invent props that are not in the registry or type definitions.
+- Prefer composition with existing compound components over reimplementing interactions.
+- Keep imports package-safe; do not use cross-package relative imports.
+- Preserve ESM import style.
+
+## Good Patterns
+
+```tsx
+import { Button } from "@signalflare-ai/ui";
+import { Dialog } from "@signalflare-ai/ui/components/dialog";
+```
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger asChild>
+    <Button>Open settings</Button>
+  </Dialog.Trigger>
+  <Dialog.Content>
+    <Dialog.Header>
+      <Dialog.Title>Settings</Dialog.Title>
+    </Dialog.Header>
+  </Dialog.Content>
+</Dialog.Root>
+```
+
+## Avoid
+
+- Do not import internal source files like `@signalflare-ai/ui/src/...`.
+- Do not treat blocks as package exports.
+- Do not guess variant names; read the registry or package types first.
+- Do not replace SignalFlare components with raw HTML when an existing component already covers the need.
+
+## Helpful References
+
+- `@signalflare-ai/ui/ai/component-registry.json`
+- `@signalflare-ai/ui/ai/component-registry.md`
+- `@signalflare-ai/ui/ai/USAGE.md`

package/skills/installing-blocks/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: installing-blocks
+description: Install and use SignalFlare blocks with the sf CLI. Use when the task mentions sf add, page sections, installable blocks, scaffolding higher-level UI, or copying block source into an app.
+license: MIT
+metadata:
+  package: "@signalflare-ai/ui"
+  sources: "packages/registry/src/command-line/cli.ts, packages/registry/src/command-line/commands/add.ts, packages/registry/AGENTS.md"
+---
+
+Use this skill when working with installable SignalFlare blocks.
+
+## What Blocks Are
+
+- Blocks are higher-level installable source files.
+- Blocks are copied into the consumer project with `sf add <block>`.
+- Blocks are not library exports from `@signalflare-ai/ui`.
+
+## Standard Workflow
+
+1. Run `sf init` to create `sf.json` if the project is not initialized yet.
+2. Run `sf blocks` to see available blocks.
+3. Run `sf add <block-name>` to install one.
+4. Import the generated local file from the app codebase.
+
+## Example
+
+```bash
+sf init
+sf blocks
+sf add PageHeader
+```
+
+## After Installation
+
+- Import the block from the local path created in the project, not from `@signalflare-ai/ui`.
+- Keep `@signalflare-ai/ui` installed because blocks depend on package components.
+
+## Avoid
+
+- Do not import blocks from package internals.
+- Do not assume a block is available as `import { PageHeader } from "@signalflare-ai/ui"`.
+- Do not skip `sf init` in a fresh project.
+
+## When Choosing Between Components and Blocks
+
+- Use components for reusable primitives and app-specific composition.
+- Use blocks when you want prebuilt, editable source copied into the project.

package/skills/theming-and-tokens/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: theming-and-tokens
+description: Apply SignalFlare styling correctly with semantic tokens, cn() composition, and automatic light or dark theming. Use when styling components, changing colors, or modifying Tailwind classes in projects using @signalflare-ai/ui.
+license: MIT
+metadata:
+  package: "@signalflare-ai/ui"
+  sources: "packages/registry/AGENTS.md, AGENTS.md"
+---
+
+Use this skill whenever styling or theme work touches SignalFlare UI.
+
+## Required Styling Rules
+
+- Use semantic tokens only, such as `bg-sf-base`, `text-sf-default`, `border-sf-line`, and `ring-sf-ring`.
+- Compose classes with `cn(...)`.
+- Let dark mode happen automatically through tokens and CSS custom properties.
+
+## Never Do This
+
+- Do not use raw Tailwind color classes like `bg-blue-500`, `text-gray-900`, or similar palette utilities.
+- Do not use `dark:` variants for SignalFlare theming.
+- Do not build class strings dynamically in ways Tailwind cannot statically detect.
+
+## Allowed Exceptions
+
+- `bg-white`
+- `bg-black`
+- `text-white`
+- `text-black`
+- `transparent`
+
+## Surface Hierarchy
+
+- Base surface: `bg-sf-base`
+- Raised surface: `bg-sf-elevated`
+- Recessed surface: `bg-sf-recessed`
+
+## Theme Context
+
+- Parent containers can set `data-mode="light"` or `data-mode="dark"`.
+- FedRAMP theme uses `data-theme="fedramp"` on a parent element.
+
+## Good Pattern
+
+```tsx
+className={cn(
+  "bg-sf-base text-sf-default border border-sf-line",
+  isActive && "ring-2 ring-sf-ring",
+  className,
+)}
+```
+
+## Avoid Pattern
+
+```tsx
+className={`bg-blue-500 text-white ${isDark ? "dark:bg-black" : ""}`}
+```
+
+## If You Need Token Names
+
+- Start from existing components in `@signalflare-ai/ui`.
+- Reuse the nearest semantic token instead of inventing new raw colors.