# AI Usage Guide

This guide is written for AI agents using Semmet Angular while implementing designs from Figma, screenshots, or product specs.

## Product Rule

Semmet Angular generates accessible Angular application code. It does not generate a visual design system.

Generated files are meant to be edited. The consuming application owns visual design and final layout.

Use Semmet to turn Figma structure into Angular delivery faster: identify the UI/accessibility patterns, generate the matching Semmet components or directives, compose the page in the app, and then apply the Figma visual properties in local HTML/CSS without breaking the accessibility contract.

`ng add semmet-angular` never configures Playwright. Only run the e2e schematic when the user explicitly asks for e2e setup:

```bash
ng add semmet-angular
ng generate semmet-angular:e2e
```

## Official Figma-to-Semmet Prompt

Use this prompt after pasting a Figma selection, screenshot description, or exported design summary into an AI coding agent:

```text
You are implementing this Figma selection in an Angular app that uses Semmet Angular.

First, analyze the selection and list every UI pattern you can identify: form fields, buttons, icon buttons, checkboxes, radios, switches, selects, comboboxes, textareas, cards, lists, tables, tabs, accordions, dialogs, menus, navbars, breadcrumbs, alerts, toasts, progress indicators, skeleton states, carousels, and page landmarks.

Then map each pattern to the smallest useful Semmet schematic. Prefer generated Semmet components or headless directives over raw custom HTML when Semmet has a matching accessibility pattern.

Return:
1. A component inventory table with: Figma element, interaction, Semmet schematic, generated name, and notes.
2. The exact `ng generate semmet-angular:<schematic> <name>` commands.
3. Whether Playwright e2e setup is needed now. Do not add e2e unless the project already has Playwright or I explicitly ask for it.
4. The Angular composition plan: which page/component imports each generated component and how the generated pieces are wired together.
5. The Figma styling plan: spacing, typography, colors, radius, shadow, responsive layout, and component variants/sizes to apply in local CSS.
6. The accessibility checklist: labels, `aria-labelledby`, `aria-describedby`, invalid/error state, focus order, Escape handling, arrow-key behavior, native controls, landmarks, live regions, masked sensitive data, and clear financial amounts/statuses.
7. The verification commands to run: build/typecheck, unit tests, optional e2e, and optional `ng generate semmet-angular:ci`, `docker`, or `deploy`.

When editing generated files, preserve the accessibility contract: native controls, ARIA relationships, accessible names/descriptions, focus management, keyboard behavior, and generated tests. You may freely change layout wrappers, projected content, CSS, classes, variants, sizes, and visual details to match Figma.
```

## Official Implementation Runbook

Follow this order during implementation:

1. Extract structure from Figma: controls, repeated items, layout regions, overlay behavior, loading/error/empty states, and responsive differences.
2. Identify accessibility patterns before choosing components.
3. Generate the smallest useful Semmet pieces. Prefer isolated components/directives for precise product UI; use `block` only for generic section scaffolds.
4. Compose the page using project-owned Angular code. Import generated standalone components/directives directly where needed.
5. Replace sample content, data arrays, labels, hints, errors, and option lists with product data.
6. Apply Figma visuals in local CSS or project design tokens. Keep Semmet CSS minimal and functional.
7. Preserve semantic HTML, IDs, labels, ARIA wiring, focus behavior, keyboard behavior, and native form controls.
8. Run tests and build. Add e2e setup only when requested or already configured.
9. Add delivery scaffolding explicitly with `ci`, `docker`, or `deploy` only when the project needs those files.

## Prefer Isolated Components

When translating a Figma prototype, prefer isolated components and directives.

Use Semmet for:

- ARIA roles and relationships;
- accessible names and descriptions;
- keyboard and focus behavior;
- native form/control semantics;
- generated unit tests;
- optional e2e specs when requested.

Write application-specific layout yourself:

- page sections;
- grids;
- spacing rhythm;
- typography;
- color;
- radius;
- shadows;
- responsive composition;
- final Figma matching.

## Use Starter Blocks Carefully

Blocks are starter scaffolds, not final UI contracts.

Use a block only when the Figma structure closely matches a common section pattern such as hero, pricing, footer, table section, tabs section, or card section.

If the Figma design diverges, do not fight the block. Replace its markup or generate isolated components instead.

Generated block files include this reminder:

```html
<!-- Semmet Angular: starter scaffold. Edit or replace this markup freely; it is generated application code, not a Semmet runtime API. -->
```

## Do Not Preserve Semmet Markup Blindly

Generated HTML is a starting point. Preserve the accessibility contract, not the exact structure.

Safe changes:

- changing wrappers and layout elements;
- adding icons, badges, avatars, counters, and custom content;
- replacing block section markup;
- changing CSS completely;
- adding project-specific classes;
- using open visual variants such as `variant="light"` or `size="compact"` — see "Naming Visual Variants" for the naming convention to follow.

Be careful with:

- removing required accessible labels;
- breaking `aria-labelledby` / `aria-describedby` relationships;
- removing focus management from interactive patterns;
- changing keyboard behavior for ARIA patterns;
- replacing native controls with non-native elements without restoring semantics.

## Naming Visual Variants

Do not replace a Semmet component with raw HTML just to match a Figma visual. Try, in order: an existing `variant`/`size` value, a new named variant, a project-local class, project CSS, or composition (projected content/templates) — dropping to raw HTML forfeits the ARIA wiring and keyboard behavior the component already gives you for free.

Components expose `variant` and `size` as open strings (e.g. `input<string>('primary')` on `button`/`badge`), not closed unions. This is deliberate: Semmet ships no visual design system, so it cannot predict the variant names a given Figma prototype will need.

Because the names are free, an AI agent must still pick *some* convention, or every project reinvents its own vocabulary and later sessions can't guess it. Use this pattern:

```
<context>-<role>
```

- `context` — where in the page/design this variant lives (`hero`, `pricing`, `campaign`, `checkout`).
- `role` — what it signals, not what it looks like (`highlight`, `cta`, `label`, `muted`), so the name survives a future restyle even if the color/shape changes.

```html
<app-ui-button variant="hero-cta" size="hero" />
<app-ui-card variant="pricing-highlight" />
<app-ui-badge variant="campaign-label" />
```

Avoid:

- Raw Figma layer/frame names (`variant="Frame 42"`) — meaningless outside the design file.
- Bare visual adjectives with no context (`variant="yellow"`, `variant="big"`) — breaks the moment the palette changes.
- Reusing `primary`/`secondary` for everything — fine for truly generic actions, but collapses distinct design intents into one name once a page has more than one kind of emphasis.

The CSS for each named variant belongs in the consuming app (attribute selector `[variant='hero-cta']` or a project class), never in the lib — Semmet stays the accessible structure, the app owns what each name looks like.

## E2E Specs

Component e2e specs are opt-in:

```bash
ng generate semmet-angular:button cta-button --e2e
```

Do not generate e2e specs unless the app has Playwright configured or the user explicitly asks for e2e setup.

## Figma Pattern Mapping

Use this table when mapping a Figma prototype to Semmet commands.

| Figma pattern | Prefer | Notes |
|---|---|---|
| CTA, button, icon button, submit action | `button`, `close-button` | Use open `variant` / `size` strings named per "Naming Visual Variants" (`<context>-<role>`). |
| Button group, segmented actions, formatting controls | `button-group`, `toolbar` | Use `toolbar` when arrow-key roving focus across tools matters — headless directives (`[toolbar]`, `toolbarItem`), app owns the buttons. |
| Testimonial, product card, feature card | `card` | Use free projected content; do not force title/description/action taxonomy. |
| Feature checklist, selectable list, sidebar section list | `list-group` | Headless directives let the app own every list item layout. |
| Search bar with icon/action | `input-group` | Use prefix/suffix templates for icons, counters, badges, or buttons. |
| Text field, select, textarea, checkbox, radio, switch | `input`, `select`, `textarea`, `checkbox`, `radio-group`, `switch` | Generate the smallest native control that matches the Figma interaction. |
| One-time password, 2FA code, login confirmation code | `otp-input` | Single native input with `autocomplete="one-time-code"`, numeric input mode, label, hint, and error wiring. |
| Transaction PIN, secure code, transaction password | `secure-code-input` | Native password input with visibility toggle, `aria-controls`, `aria-pressed`, hint/error wiring, and optional numeric sanitation. |
| Monetary input, transfer amount, payment amount | `currency-input` | Native input with label, currency description, hint/error wiring, and decimal input mode. Keep formatting/parsing rules project-owned. |
| Source account, destination account, account picker | `account-selector` | Native radio selection with account metadata, disabled account state, selected account output, and clear balance/status text. |
| Account balance card, account dashboard tile | `account-summary` | Semantic account summary with balance visibility toggle. Keep balance data and permission rules project-owned. |
| Bank statement, recent activity, transaction history | `transaction-list` | Native table with caption, scoped headers, dates, status, signed amounts, and empty state. |
| Statement filters, date/status/type filters | `transaction-filter` | Native filter form with date-range validation, live status, and apply/reset outputs. |
| Saved recipients, beneficiaries, favorite accounts | `beneficiary-list` | Semantic list of native selection buttons with selected state and empty state. |
| New/edit beneficiary, favorecido registration | `beneficiary-form` | Native recipient form with CPF/CNPJ/document, bank, branch, account, account type, field errors, reset, and submit output. |
| Saved card summary, debit/credit card tile | `payment-card` | Masked card summary with accessible description and native action button. Do not collect raw card data with this component. |
| Card security toggles, block card, online/international/contactless controls | `card-controls` | Native checkbox switches with masked card context, per-control descriptions, live status, and change output. |
| Bank transfer, PIX/wire/ACH starter form | `transfer-form` | Native form controls, fieldset/legend, validation messages, live status, and submit output. Replace validation and submission with project banking rules. |
| Pix payment, Pix key, Pix copy-and-paste flow | `pix-payment` | Native method radios, Pix key/copy-and-paste input, amount, description, validation messages, and submit output. |
| Boleto, payment slip, digitable line, bill payment | `payment-slip` | Native barcode/digitable-line, amount, due date, validation messages, accessible summary, and submit output. |
| Scheduled payment, recurring transfer, future payment | `scheduled-payment` | Native date and recurrence controls with validation, recurrence summary, submit, and cancel outputs. |
| Limit management, Pix/card/withdrawal limits | `limit-manager` | Native numeric inputs and `<meter>` summaries for current/requested/max limits with live submit status. Approval rules stay project-owned. |
| Approval queue, corporate authorization, pending transactions | `authorization-queue` | Native table with scoped headers, checkbox row selection, bulk approve/reject actions, and live status. |
| Loan simulator, credit simulation, installment preview | `loan-simulator` | Native numeric controls and accessible `<output>` summary. Real CET, fees, eligibility, and regulatory calculations stay project-owned. |
| Compliance notice, LGPD/Open Finance/risk acknowledgement | `compliance-alert` | Alert semantics with optional consent checkbox, disabled confirm until acknowledgement, and acknowledge/cancel outputs. |
| Transfer/payment review step, confirmation before submit | `confirmation-summary` | Semantic review summary with details, total amount, and native confirm/cancel actions. Keep authorization rules project-owned. |
| Receipt, comprovante, transaction detail page | `transaction-detail` | Semantic receipt with reference, date/time, amount, parties, copy action, download action, and live copy status. |
| Autocomplete/searchable option picker | `combobox` | Pass extracted options through `[items]`; restyle the popup in app CSS. |
| App menu button / overflow actions | `menu-button` | Headless directives (`[menuButton]`, `menuButtonTrigger`, `menuButtonMenu`, `menuButtonItem`); app owns trigger/menu markup, keyboard and outside-click behavior stay wired. |
| Tabs / tabbed content | `tabs` | Headless directives (`[tabs]`, `tabsList`, `tabsTab`, `tabsPanel`); app owns the tab strip and panel markup, content stays in plain DOM (no `ng-template`). |
| Data table | `table` | Generic `<table>` wrapper with content projection — project your own `caption`/`thead`/`tbody` with the real column count and row shape, no fixed 2-column assumption. |
| Breadcrumb trail | `breadcrumb` | Headless directives (`[breadcrumb]`, `breadcrumbItem`); app owns the `nav`/`ol`/`li` structure and marks the current item with `[current]`. |
| Navbar / top navigation | `navbar` | Headless directives (`[navbar]`, `navbarItem`, `navbarToggle`, `navbarMenu`); app owns brand, links and the responsive markup — no fixed one-row shape. |
| Disclosure FAQ | `accordion` or `block section-faq` | Headless directives (`[accordion]`, `accordionHeader`, `accordionPanel`); app owns headings and panel content. Use `accordion` for precise Figma layouts; use block only for a generic FAQ section. |
| Pricing section | `card` or `block section-pricing` | Prefer `card` when the Figma cards are visually specific. |
| Footer columns | `block footer-navigation` or custom HTML | Use the block only if the Figma footer is structurally generic. |
| Page shell / landmarks | `landmarks` | Useful when the prototype has explicit header/nav/main/aside/footer regions. |
| Carousel / media rail | `carousel` | Project each slide so Figma-specific media/content stays in app markup. |
| Tree / nested navigation | `tree-view` | Headless directives (`[treeView]`, `treeViewItem`, `treeViewGroup`); app owns the nested `ul`/`li` structure, any depth. |

## Figma Workflow

Recommended flow:

1. Extract structure and interaction requirements from Figma.
2. Identify accessibility patterns.
3. Generate the smallest useful Semmet components.
4. Compose the page manually in the app.
5. Edit generated HTML/CSS to match Figma.
6. Run Angular typecheck/build.
7. Run `ng generate semmet-angular:e2e` only when the project is ready for Playwright.