Getting Started

Before you start

• Node.js 22.22+ or 24.15+, the versions Angular 22 supports.
• An Angular 22 project. Still on Angular 19? Use the compat/angular-19 branch.

Tailwind CSS 4 and the Angular CDK

Add Tailwind with its Angular guide. Then install the Angular CDK, which Ply's dialogs, menus, and tooltips build on:

npm install @angular/cdk

Keep Tailwind in its own src/tailwind.css, since Tailwind 4 doesn't run through Sass. @source paths are relative to this file, so ./ scans everything in src/:

@import "tailwindcss";
@source "./**/*.{html,ts}";

List it in angular.json, before your global stylesheet:

"styles": ["src/tailwind.css", "src/styles.scss"]

Install

1. 1

   Run init

   Bash

   npx ply-ui-cli init

   It asks for your components folder, global stylesheet, and Tailwind file. --yes accepts the defaults. Then it writes:

   • ply-ui.json: where components go, src/app/components by default.
   • ply-ui.css: Ply's global styles and brand tokens, imported at the top of your global stylesheet.
   • icons.svg and icons-filled.svg: icon sprites, in your assets folder.
   • ply-ui-lock.json: a record of installed files, so update can tell your edits from upstream changes.
   • Editor rules for AI assistants, if you don't have them yet.

   It doesn't install npm packages or change src/tailwind.css.

2. 2

   Add a component

   Bash

   npx ply-ui-cli add button

   The source lands in src/app/components/button/. It's your code now, so edit it like any other file. If the component needs an npm package you don't have, add prints the install command.

   Run add without a name to pick from the catalog. In scripts and CI, pass names and --yes.

3. 3

   Use it

   Import it from the local folder, for example in src/app/app.ts:

   TypeScript

   import { Component } from '@angular/core';
   import { BaseButtonDirective } from './components/button/ply-button.directive';
   
   @Component({
     selector: 'app-root',
     imports: [BaseButtonDirective],
     template: `<button ply-button color="primary">Save changes</button>`,
   })
   export class App {}

4. 4

   Check your setup

   Bash

   npx ply-ui-cli doctor

   If a component looks unstyled or icons are missing, doctor checks ply-ui.json, the Angular CDK, Tailwind and its @source paths, the ply-ui.css import, and the icon sprites, then tells you what to fix. It doesn't change any files.

AI tools

Ply ships an MCP server for agents that can install components, and editor rules for assistants that only write code.

MCP server

ply-ui-mcp lets your agent search the catalog and run the CLI for you. Pick your tool:

{
  "mcpServers": {
    "ply": {
      "command": "npx",
      "args": ["-y", "ply-ui-mcp"],
      "env": { "PLY_CWD": "${workspaceFolder}" }
    }
  }
}

Run npx ply-ui-cli init --yes first, so the agent has somewhere to write. Free components need no key. For Pro, set PLY_LICENSE_KEY where the server runs. Using DeepSeek or another model? Add the server to the editor or CLI you run it in. All tools and options are on the npm page.

Agent registration

The catalog, CLI, and hosted MCP connector are public. Ply does not issue agent identities or access tokens. auth.md is the discovery file agents fetch. It points at llms.txt and the MCP URL, and it records that registration is not enabled.

Editor rules

These files teach assistants to write Ply the way the docs do. init adds the Cursor rule, snippets, and design skill to your project. Get them here if you skipped init or use Windsurf.

• Cursor rule

  .cursor/rules/ply-ui.mdc

  Copy Download

• Windsurf rule

  .windsurf/rules/ply-ui.md

  Same content as the Cursor rule. init doesn't write it.

  Copy Download

• Snippets for VS Code and Cursor

  .vscode/ply-ui.code-snippets

  Copy Download

• UI design skill

  .cursor/skills/ply-ui-design/
  .agents/skills/ply-ui-design/

  View

Snippets expand usage markup such as ply-card and ply-dialog. They don't install anything, so run add first. npx ply-ui-cli init --refresh-editor-kit replaces a rule, snippet pack, or design skill that is already in the project. What the design skill changes on a card is in Why Ply installs a UI design skill when you run init.

Ply Pro

Ply Pro adds 90 items: page layouts, the app shell, blog, ecommerce, and media blocks, and advanced widgets such as the data table, rich text editor, file upload, and command palette. One license covers every Pro item, with lifetime updates.

1. 1

   Set your license key

   Your key arrives by email after purchase. Set it as an environment variable wherever you run the CLI:

   Bash

   export PLY_LICENSE_KEY=your-license-key

   On Windows, use setx PLY_LICENSE_KEY your-license-key. In CI, store it as a secret.

2. 2

   Add Pro items

   Use the same CLI. Pro items also show up in the add picker.

   Bash

   npx ply-ui-cli add layout-dashboard data-table

Keep components updated

Components are your code, so they never change on their own. See what changed upstream, then pull it in:

npx ply-ui-cli diff
npx ply-ui-cli update

• Files you haven't edited update in place.
• Files only you changed keep your edits. --overwrite-local resets them to upstream.
• When you and upstream both changed a file, update asks whether to merge, keep yours, or take upstream. --merge runs a 3-way merge, --force takes upstream, and with --yes your version stays.

Name components to update only those, as in npx ply-ui-cli update dialog. npx ply-ui-cli changelog dialog lists one component's changes, and the changelog has everything. Free and Pro items update the same way.

Next steps

• Cookbooks Build real screens: a settings form, a dialog form, an invoice table, and an AI chat.
• Configuration Brand color, translated strings, right-to-left layouts, icon paths, and test harnesses.
• Theme Studio Preview a palette, radius, and font on real components, then copy the CSS.
• Components Each page opens on a live preview, with the code, the add command, and a prompt for your agent.

Angular 22 recipes

• Signal forms: form() and [formField] on inputs, selects, and toggles.
• httpResource: a server-paged data table (Pro), an async combobox, and virtual scroll, without RxJS plumbing.
• @defer: load heavy components later, with ply-skeleton as the placeholder.
• View transitions: animate tabs, dialogs, and route changes.