Sona UI Agent Skill

---
name: sona-ui
description: Discover and integrate Sona UI registry components. Use when selecting, installing, composing, reviewing, or troubleshooting a Sona UI component in a consumer project.
metadata:
  version: "1.2.0"
---

# Sona UI Agent Skill

## Core invariant

Treat the Sona UI shadcn registry as the installation authority. When a component exists in the registry, install its source-owned item instead of reconstructing it.

Registry namespace:

```text
@sona-ui
```

Registry URL:

```text
https://sonaui.com/r/{name}.json
```

Current-resource manifest:

```text
https://sonaui.com/agent/manifest.json
```

## Reference routing

Before selecting a component, read:

- `references/component-selection.md`

Before installation or troubleshooting, read:

- `references/consumer-validation.md`

Before composing or reviewing motion and visual behavior, read:

- `references/design-principles.md`

When skill discovery or the optional shadcn MCP setup needs troubleshooting, read:

- `references/provider-setup.md`

## Workflow

1. Inspect the consumer project's framework, React version, styling entry, aliases, and existing component conventions. This phase is complete when each value is known and the presence or absence of `components.json` is recorded.
2. Fetch the current-resource manifest before selecting or installing a component. When reachable, use its catalog URL rather than an installed or copied catalog URL. If it is unavailable, record that the skill is using a local snapshot that may be older than production.
3. Read `references/component-selection.md`, translate the request into an interaction intent, and search the catalog named by the manifest. This phase is complete when one candidate—or the decision to use no Sona component—is justified from its `useWhen`, `avoidWhen`, accessibility, motion, and dependency fields, and its exact `detail`, `docs`, and `registryItem` resources are recorded.
4. When the user supplies an exact component name that is absent from the catalog, fetch `https://sonaui.com/r/{name}.json` directly before deciding it is unavailable. If reachable, treat that registry item as authoritative and record its file targets, dependencies, registry dependencies, documentation URL when present, and accessibility and motion behavior. Do not infer that the item is unavailable from the catalog omission alone.
5. When installation is requested, read `references/consumer-validation.md` and complete every preflight check. Installation is unblocked only when every dependency resolves, every target is known, and every collision has an explicit decision.
6. Install the smallest useful set with the consumer project's existing package runner:

   ```bash
   bunx shadcn@latest add @sona-ui/<component>
   ```

   Use `pnpx`, `npx`, or `yarn dlx` when that matches the consumer project.

7. Confirm the generated paths and imports match the inspected consumer conventions before composing the component into the requested experience.
8. Read `references/design-principles.md` when the component is interactive or visually integrated, then apply every validation tier required by `references/consumer-validation.md`. The work is complete only when each applicable check has a recorded result and static, interaction, and visual verification are reported separately.

## Publishing a new Sona component

Every published `registry:ui` item must also have a matching entry in `src/registry/agent-metadata.ts`. Add accurate `useWhen`, `avoidWhen`, capabilities, accessibility, motion, reduced-motion, and related-component guidance, then regenerate and validate both publishing surfaces:

```bash
bun run build:registry
bun run build:agent-resources
bun run check:registry
bun run check:agent-resources
```

Do not treat an item as published until both registry and agent-resource checks pass. The public component navigation is independent from registry and agent publication; an intentionally hidden documentation link still needs the full metadata contract.

## Scope discipline

Inspect before editing. Ask the user before making a material layout decision that was not requested. Do not rewrite a consumer's styling system to match Sona UI.

# Component Selection

Use intent, constraints, and interaction shape to select a Sona UI item.

Start with the user's job:

- Local view switching → tabs.
- Focused confirmation or short task → dialog.
- Progressive disclosure → accordion or dropdown.
- Compact action revealing 2 to 4 related choices in place → Expanding Action. Avoid it for navigation, long menus, or destructive actions.
- Responsive action group with clear action priority → Smart Overflow. Avoid it when every item must remain visible for scanning or comparison.
- Deliberate destructive action → hold-to-delete.
- Atmospheric visual depth → shader or spotlight effect.
- Short decorative typography → text motion resource.

Compare every plausible item's `useWhen`, `avoidWhen`, accessibility, motion, and dependency fields before installation. Selection is complete when one candidate—or the decision to use no Sona component—is justified against all five fields. If the request needs a general navigation system, choose a navigation pattern rather than forcing local tabs into that role.

# Consumer Validation

The registry install boundary is the source of truth.

Check `components.json`, aliases, Tailwind CSS entry points, React/framework versions, and existing `components/ui` conventions before installing.

## Preflight

Before installation:

1. Confirm the `@sona-ui` registry alias exists.
2. View the selected namespaced item through the shadcn CLI.
3. Inspect file targets, package dependencies, and registry dependencies.
4. Confirm remote dependencies resolve without authentication.
5. Detect target collisions and get explicit approval before overwriting a public primitive.

Preflight passes only when all five checks pass. Use the exact catalog `detail`, `docs`, and `registryItem` values, then use the detail resource's exact `docs.rawUrl`.

## Validation tiers

Required for every installation:

- Confirm registry dependencies and foundation files resolve.
- Confirm generated paths and imports follow the consumer aliases.
- Run the consumer's typecheck or build command.

Required for interactive components:

- Exercise the primary keyboard interaction.
- Check focus behavior and disabled states.
- Check `prefers-reduced-motion` behavior.

Required when visually integrated:

- Check narrow and wide layouts.
- Check light and dark themes when supported.
- Complete a browser visual review.

Record a pass, failure, or explicit not-run status for every applicable check. Report static validation separately from interaction and rendered visual verification.

## Failure classification

If an item references a protected, preview-only, or unreachable dependency URL, report a Sona registry metadata failure. Do not rewrite consumer aliases, copy source manually, or install dependency files separately as a workaround: shadcn still traverses declared registry dependencies.

Classify installation failures as consumer configuration, registry metadata, generated payload, agent resource, MCP/client, or deployment before changing source. Repair consumer configuration in the consumer project; repair generated payload or registry metadata at the Sona source.

# Sona UI Design Principles

- Interaction should feel clear before it feels expressive.
- Motion communicates feedback, continuity, orientation, or hierarchy.
- Reduced motion removes nonessential choreography while preserving the state change.
- Hover is progressive enhancement, never the only interaction path.
- Prefer semantic tokens and component-local variables.
- Keep decorative effects separate from meaningful content.
- Preserve semantic HTML, keyboard access, visible focus, accessible names, dialog labeling, and contrast against the complete visual surface.
- Preserve the consumer's existing layout decisions unless the user asks for a redesign.

The review is complete when every applicable principle has been checked and any exception is explained.

# Provider Setup

The skill installs at `.agents/skills/sona-ui/`. Skill discovery from that shared project directory depends on the agent client and its current configuration; confirm the client lists `sona-ui` before relying on automatic invocation.

The registry and the skill work without a custom Sona MCP server. The official shadcn MCP server is optional and provides registry discovery through the agent client.

## Codex

Add the shadcn server to the user's Codex configuration:

```toml
[mcp_servers.shadcn]
command = "npx"
args = ["shadcn@latest", "mcp"]
```

## Claude Code

Add `.mcp.json` to the consumer project:

```json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}
```

## Cursor

Add `.cursor/mcp.json` to the consumer project using the same `mcpServers.shadcn` configuration shown for Claude Code.

Setup is complete when the client lists the `sona-ui` skill and, when MCP is enabled, exposes the shadcn registry tools. Treat documented configuration as fixture-ready until a live discovery and installation session has been recorded for that client.