Zard

zard/ui

An Angular component library. Components are installed as source code into the user's project by the CLI — there is no runtime package to import from, and no component to npm install.

IMPORTANT: Run every CLI command with the project's own package runner: npx zard-cli, pnpm dlx zard-cli, yarn zard-cli, or bunx zard-cli — pick the one matching packageManager in components.json. The examples below use npx zard-cli; substitute the right runner.

Current Project Context

Read components.json at the project root before doing anything else. It is written by zard-cli init and is the whole configuration — there is no zard-cli info command to call.

{
  "$schema": "https://zardui.com/schema.json",
  "style": "css",
  "icons": "lucide",
  "rtl": false,
  "projectType": "angular",
  "appConfigFile": "src/app/app.config.ts",
  "packageManager": "npm",
  "tailwind": { "css": "src/styles.css", "baseColor": "neutral" },
  "baseUrl": "src/app",
  "aliases": {
    "components": "@/shared/components",
    "utils": "@/shared/utils",
    "core": "@/shared/core",
    "services": "@/shared/services",
    "blocks": "@/shared/blocks"
  }
}

No components.json means the project has not been initialised — run init rather than writing component files by hand.

A components.json that exists but whose installed component source uses a renamed selector or an old file layout (core/css/tailwind.css instead of core/css/zard.css, a bare ::-webkit-scrollbar block in the global CSS, a button-group "divider" instead of "separator", a toast folder instead of sonner) belongs to a project predating the current registry. That is a job for the migration skill, which names every renamed selector precisely — not for guessing which shape is current.

For anything the file does not answer — what exists, what a component's API is, what it depends on — read the registry or use the MCP server. Never reconstruct a component API from memory.

Key Fields

• aliases.components → the import prefix for every component. Use the actual value; never hardcode @/shared/components. The prefix can be anything (@app/..., ~/...) — it is mapped in tsconfig.json, or tsconfig.base.json in an Nx workspace.
• aliases.blocks → the import prefix a block (add dashboard-01, add login-01) is written under. Absent from a components.json written before blocks were installable — a re-run of init adds it.
• baseUrl → the source root the aliases resolve against. Components are written under it.
• projectType → angular, angular-library, nx, nx-library, or analog. Decides which tsconfig holds the aliases, where Tailwind is configured, and whether an app.config.ts exists at all. See cli.md.
• appConfigFile → where provideZard() is registered. Empty in a library — there the consuming app registers it.
• tailwind.css → the global CSS file holding the theme tokens. Always edit this file; never create a second one.
• tailwind.baseColor → the theme preset: neutral, stone, zinc, gray, or slate.
• icons → the icon family the components are written with (lucide today). Decides the @ng-icons/* package and the symbol names. See rules/icons.md.
• rtl → declares layout direction intent. It does not change what gets installed.
• packageManager → use it for every dependency install (pnpm add date-fns, not npm install date-fns) and to pick the CLI runner.
• registryUrl → optional. Present when the project installs from a registry other than https://zardui.com/r. See registry.md.

Principles

1. Install before importing. A component only exists once zard-cli add has written it. Check the components directory first; do not import what is not there.
2. Compose what exists. A settings page is Card + Field + Input + Button. A dashboard is Sidebar + Card + Chart + Table. Reach for custom markup only when nothing covers it.
3. Variants before classes. zType="outline", zSize="sm" — not a class that re-styles the component into the same thing.
4. Semantic tokens only. bg-primary, text-muted-foreground. Never bg-blue-500, never a dark: colour override.
5. The library's own conventions apply to the code you write. Standalone, OnPush, input(), z-prefixed inputs. See rules/angular.md.

Critical Rules

Always enforced. Each links to a file with Incorrect/Correct pairs.

Angular API → rules/angular.md

• Standalone with imports, ChangeDetectionStrategy.OnPush, ViewEncapsulation.None. No NgModules, no Default change detection.
• Signal inputs: input(), model(), output(). No @Input() / @Output() decorators in new code.
• Selectors are z-<name> and/or [z-<name>]. Some components are element-only, some are attributes on a native tag (input[z-input], button[z-button]). Use the one the component declares.
• Composite components import their Zard<Name>Imports array, not the individual classes one by one.
• Never edit generated output. apps/web/src/generated/** and public/r/*.json are build artefacts.

Styling → rules/styling.md

• Semantic tokens, never raw colours. bg-primary not bg-blue-600.
• class is for layout, not for restyling. It is merged last and wins — which is exactly why it should not be used to override the component's own colours.
• mergeClasses(), not string concatenation. It is twMerge(clsx(...)); plain interpolation loses the conflict resolution.
• No space-x-* / space-y-*. Use flex with gap-*.
• size-* when width and height match. size-4, not w-4 h-4.
• No dark: colour overrides. The tokens already switch.
• Tailwind v4 only. There is no tailwind.config.js; the theme lives in CSS.
• scroll-fade needs an overflow container; shimmer is text-only. Both are pure-CSS utilities from the core item.

Composition → rules/composition.md

• Use the full composition. z-card wants z-card-header / z-card-title / z-card-content / z-card-footer, not everything dumped into content.
• Items belong to their group. z-select-item inside z-select-group.
• Dialogs, sheets, alert dialogs and drawers have two forms. Compose z-dialog / z-sheet / z-alert-dialog / z-drawer in the template with [(zVisible)] and the header/title/description/footer children, or open the same panel from code through ZardDialogService / ZardSheetService / ZardAlertDialogService / ZardDrawerService. Never toggle them with a hand-written open flag or @if.
• Toasts go through ZardSonnerService — show, success, error, promise.
• Use the component instead of styled markup. z-separator not <hr>, z-skeleton not an animate-pulse div, z-badge not a styled span, z-empty not a hand-built empty state.

Forms → rules/forms.md

• All three Angular form APIs are supported: Signal Forms, Reactive Forms, Template-driven. Follow whichever the project already uses.
• Form layout is z-field-group + z-field, never a div with space-y-*.
• Validation state is data-invalid on the field and aria-invalid on the control.
• Errors render in z-field-error, not a loose paragraph.

Typeset → rules/typeset.md

• Rendered markdown gets a typeset container, never a class per tag. zard-cli add typeset installs the stylesheet.
• Six variables govern it, three of which are the rhythm: --typeset-size, --typeset-leading, --typeset-flow.
• not-typeset on any component embedded in prose. It brings its own sizing.
• typeset-scroll around a wide table, instead of a hand-rolled overflow wrapper.
• Utilities beat it with no !important — every element selector sits inside :where().