Building with AI

Set up your assistant once, then describe what you want to build. AWC UI ships component manuals with the package, so your assistant can use the API for your installed version.

1. Set up your project

Run these commands in your app’s directory. Skip the install if Core is already in your project.

npm install @awc-ui/core
npx --no-install awc-ui ai-setup

The setup command adds documentation links to the instruction files used by Codex, Claude Code, Cursor, and GitHub Copilot. It preserves your own instructions and uses your project’s framework when it can detect it.

That is enough to get started. MCP and skills are optional.

2. Ask for what you need

Describe the result and any constraints that matter. You do not need to choose component names or repeat the library’s rules.

Build something new

Build a customer dashboard with AWC UI. Use React, a searchable
customer table, and a form for adding customers. Support mobile.

Change an existing app

Fix the table toolbar jumping when rows are selected.
Use the existing AWC UI components and keep our current theme.

Review without making changes

Review this form's AWC UI integration and keyboard behavior.
Report issues before changing code.

Your assistant should read the relevant component manuals, preserve existing project decisions, and check the requested behavior. For a new app, it asks only about missing decisions that affect the work. A focused fix does not restart app setup, and a review stays read-only unless you request changes.

3. Keep setup current

Run npx --no-install awc-ui ai-setup again after upgrading Core. It refreshes only the generated documentation links.

Preview changes, check setup, and see which files are updated

npx --no-install awc-ui ai-setup --dry-run
npx --no-install awc-ui ai-setup --check

--dry-run previews changes. --check writes nothing and exits with code 1 when setup is missing or stale, so it can also run in CI.

The command maintains a marked AWC UI block in AGENTS.md, CLAUDE.md, .cursor/rules/awc-ui.mdc, and .github/copilot-instructions.md. Content outside that block is preserved.

The links point to main-llm.md for task guidance and src/components/<tag>/readme.md for individual component contracts, inside your installed @awc-ui/core package.

Optional: MCP and skills

Add skills for reusable build and review workflows, or MCP to let your assistant search component documentation through tools. Use either or both; they read the same Core manuals as the basic setup.

Add skills

Copy skills/awc-ui-build/ and skills/awc-ui-review/ from the Core checkout into your app’s .agents/skills/ directory. If your assistant uses another skill directory, copy the complete folders there instead. Preserve any customized copies already in that location.

Then ask your assistant to build or review an interface. In clients that support explicit skill invocation, you can also use:

Use $awc-ui-build to add a settings form. Keep our framework and theme.

Use $awc-ui-review to check this form. Report issues without changing code.

The skills read your installed Core manuals. They preserve project decisions, keep fixes focused, and use MCP only when available with matching documentation.

Install skills through the CLI

With Core installed, run this in your app:

npx --no-install awc-ui ai-setup --skills

This sets up the documentation links and installs both skills in .agents/skills/. Run it again after upgrading Core. Add --dry-run to preview changes or --check to verify setup without writing.

Identical skills are kept. Customized or conflicting copies are reported without being overwritten. The command does not configure MCP or global agent settings.

Connect MCP

MCP gives your assistant tools to find components and read their APIs. Use Node 22.13+ on the 22.x line, or Node 24+. Install Core using the project setup above, then connect your assistant.

Codex

With the Codex CLI installed, run this once to make the server available across your Codex projects:

codex mcp add awc-ui -- npx -y @awc-ui/mcp

Restart Codex, then use /mcp to check the connection. The desktop app and CLI share MCP configuration. See the Codex MCP setup guide for settings and project-specific configuration.

Claude Code

With the Claude Code CLI installed, run this in your app’s directory:

claude mcp add --transport stdio --scope project awc-ui -- npx -y @awc-ui/mcp

This creates or updates .mcp.json in the project root. Start a new Claude Code session, approve the server when prompted, and use /mcp to check the connection. Use --scope user instead of --scope project to make it available across all your projects. See the Claude Code MCP setup guide.

Configure another MCP client

Add this local stdio server in your assistant’s MCP settings. The surrounding configuration format depends on your client.

{
  "mcpServers": {
    "awc-ui": {
      "command": "npx",
      "args": ["-y", "@awc-ui/mcp"]
    }
  }
}

Your assistant starts the server for you; no separate terminal process is needed. The unversioned package name uses npm’s latest release. The first package download needs internet access; the installed server serves its bundled documentation offline, without an API key.

Then ask:

Use the AWC UI MCP tools to find a searchable table component.
Check its API against our installed Core version, then implement it.

The server reports its bundled coreVersion; your assistant should compare it with your app’s installed Core version before using a documented feature. If the versions differ, use the manuals included with your installed Core package. Project edits use your assistant’s existing tools.

Run from a Core checkout instead

To try documentation for the current source, use the repository’s pnpm version:

pnpm install
pnpm build:mcp

Replace the npm configuration with:

{
  "mcpServers": {
    "awc-ui": {
      "command": "node",
      "args": ["/absolute/path/to/core/packages/mcp/bin/awc-ui-mcp.mjs"]
    }
  }
}

Replace the path with your checkout location. A source build may describe unreleased changes; use the npm package for documentation of a released Core version.

MCP tool and resource reference

Tool	Purpose
search_components	Find components by name or use case. An empty query lists components; limit, offset, and nextOffset support pagination.
get_component	Read an exact tag’s manual, structured api, or both.
list_guides	List available framework, build, theme, and accessibility guides.
get_guide	Read a guide by its listed ID.

The same content is available through awc://catalog, awc://components/{tag}/manual, awc://components/{tag}/api, and awc://guides/{id} resources. The awc-ui-build and awc-ui-review MCP prompts accept a task and an optional framework; they do not install skill folders.

Component manuals are canonical Markdown. Guide snapshots retain MDX source; repository-relative links refer to source locations, not files on the client. The server has no project-file, shell, URL-fetch, or application-data tools.

For component APIs, browse the component reference. For a manual project setup, follow the installation guide.