@relipa/ai-flow-kit 0.1.1-beta.0 → 0.1.1

package/custom/mcp-presets/README.md

@@ -119,6 +119,39 @@ See: [Figma workflow guide](../../docs/common/workflows/figma.md)
 
 ---
 
+### Playwright (`playwright.json`)
+
+Drive a real browser to explore selectors, verify flows, and capture evidence. Powers the `automation-testing` skill (Phase 3 — Explore).
+
+**When to use:** Generating E2E UI tests. The skill uses MCP to read the live DOM (real selectors, not guessed) and screenshot each step, then emits durable `.spec.ts` files for CI.
+
+**Setup:**
+```bash
+aiflow init --adapter playwright
+```
+
+**Requirements:**
+- The web app under test must be running and reachable at `baseUrl`
+- No API token needed
+- First run downloads browsers via `npx playwright install` (one-time)
+
+**Tools provided by `@playwright/mcp`:**
+- `browser_navigate(url)` — open a page
+- `browser_snapshot()` — accessibility tree (source of real selectors)
+- `browser_click` / `browser_type` / `browser_fill` — interact with elements
+- `browser_take_screenshot(path)` — capture evidence
+
+**Usage:**
+```
+/automation-testing baseUrl: http://localhost:3000 explore: true
+```
+
+> **Hybrid principle:** MCP is for *exploration + evidence* only. It does not replace test files — the skill always emits committable `.spec.ts` so CI can re-run.
+
+See: [automation-testing design](../../requirements/autotest/AutomationTestWorkflow.md)
+
+---
+
 ### Google Sheets (`google-sheets.json`)
 
 Connect to Google Sheets for loading task context.

package/custom/mcp-presets/playwright.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}

package/custom/rules/test-patterns.md

@@ -0,0 +1,105 @@
+# E2E Test Patterns (Playwright)
+
+Reusable patterns the `automation-testing` skill applies when generating Page Objects and specs. Selector priority is always: **`getByRole` → `getByLabel` → `getByTestId`** → (CSS/XPath only as last resort).
+
+---
+
+## 1. Login / Authentication
+
+**Test cases to cover:**
+- Valid credentials → redirect to landing page
+- Wrong password → error message visible
+- Empty required field → validation message
+- (optional) Locked/disabled account → blocked
+
+```typescript
+test('TC01 - Login success', async ({ page }) => {
+  const login = new LoginPage(page);
+  await login.navigate('/login');
+  await login.login('user@example.com', 'Password123');
+  await expect(page).toHaveURL(/\/dashboard/);
+});
+```
+
+---
+
+## 2. CRUD (Create / Read / Update / Delete)
+
+**Cover:** create → appears in list → edit → reflects change → delete → removed. Always assert on the list/detail after each mutation, not just the success toast.
+
+```typescript
+test('Create item appears in list', async ({ page }) => {
+  const list = new ItemListPage(page);
+  await list.navigate('/items');
+  await list.openCreate();
+  await list.fillForm({ name: 'Sample' });
+  await list.submit();
+  await expect(list.rowByName('Sample')).toBeVisible();
+});
+```
+
+> **Test data:** prefer a unique suffix (e.g. timestamp passed in via fixture) so reruns don't collide. Clean up created data in `afterEach` when possible.
+
+---
+
+## 3. Form validation
+
+- Submit empty → each required field shows its message
+- Invalid format (email, phone) → format message
+- Boundary (min/max length) → length message
+- Valid input → no error, submit succeeds
+
+```typescript
+test('Email format validation', async ({ page }) => {
+  const form = new SignupPage(page);
+  await form.navigate('/signup');
+  await form.emailInput.fill('not-an-email');
+  await form.submit();
+  await expect(page.getByText(/invalid email/i)).toBeVisible();
+});
+```
+
+---
+
+## 4. Modal / Dialog
+
+- Open trigger → modal visible
+- Confirm → action runs + modal closes
+- Cancel / backdrop / Esc → modal closes, no action
+
+```typescript
+await page.getByRole('button', { name: 'Delete' }).click();
+const dialog = page.getByRole('dialog');
+await expect(dialog).toBeVisible();
+await dialog.getByRole('button', { name: 'Confirm' }).click();
+await expect(dialog).toBeHidden();
+```
+
+---
+
+## 5. Pagination / Table
+
+- Default page loads expected count
+- Next/Prev changes rows
+- Page size change updates count
+- Sort by column reorders rows
+
+```typescript
+await expect(page.getByRole('row')).toHaveCount(11); // header + 10 rows
+await page.getByRole('button', { name: 'Next' }).click();
+await expect(page.getByText('Page 2')).toBeVisible();
+```
+
+---
+
+## 6. General assertions & waits
+
+- Prefer **web-first assertions** (`await expect(locator).toBeVisible()`) — they auto-retry. Never `waitForTimeout` to "wait for UI".
+- Assert on **user-visible outcome** (URL, text, element state), not internal state.
+- For async data, assert the loaded element, not a spinner disappearing.
+
+---
+
+## 7. Evidence (MCP explore phase)
+
+When exploring via Playwright MCP, capture a screenshot per significant step into `<evidenceDir>/[ticket-id]/TC<NN>-step<N>.png`. Name files so the reviewer can map evidence → test case at a glance.

package/custom/skills/automation-testing/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: automation-testing
+description: Generate runnable Playwright E2E tests for a web UI from requirement/business-logic docs or a tester's free-form draft. Uses Playwright MCP to explore real selectors and capture evidence on a live browser, then emits durable .spec.ts files plus an HTML report. Tester does not need to know TypeScript.
+keywords: automation, testing, playwright, e2e, mcp, testcase, browser, evidence, report, qa, tester
+---
+
+# Automation Testing (Hybrid MCP)
+
+Generate **runnable** Playwright E2E tests for a web UI. Works in a **multi-repo workspace** (a parent folder containing backend + frontend repos).
+
+## Core principle — HYBRID
+
+> Playwright MCP does **not** replace test files. It **improves** them.
+> Use the live browser to *learn* the app's real selectors and capture evidence, but the deliverable is always committable `.spec.ts` so CI can re-run.
+
+## When to use
+
+- Tester/Dev wants E2E UI tests but doesn't write TypeScript
+- A requirement (`requirement.md`) or business-logic doc exists and test cases should be derived from it
+- A finished feature needs regression coverage with evidence
+
+## How to invoke
+
+```
+/automation-testing baseUrl: <url> [explore: true|false] [autoRun: true|false] [headed: true|false] [ticketId: <id>]
+---
+(optional) tester's free-form test case draft
+```
+
+**Example:**
+```
+/automation-testing baseUrl: http://localhost:3000 explore: true autoRun: true
+---
+1. Vào /login, nhập đúng email/password → vào dashboard
+2. Nhập sai password → hiện thông báo lỗi
+3. Để trống email → hiện validation lỗi
+```
+
+## Params
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `baseUrl` | string | — | URL of the running web app **(required)** |
+| `explore` | boolean | `true` | Use Playwright MCP to explore real selectors + capture evidence before generating |
+| `autoRun` | boolean | `true` | Run `npx playwright test` after generating |
+| `headed` | boolean | `false` | Show browser window during `autoRun` (CI should keep `false`) |
+| `ticketId` | string | — | Ticket id; if omitted, read from `.aiflow/context/current.json` |
+
+---
+
+## Phase 1 — Collect
+
+1. **Resolve workspace.** Read `.aiflow/repos.json`.
+   - If it does NOT exist: copy the template at `.claude/skills/automation-testing/templates/repos.json`, ask the user to confirm the paths (`backend`, `frontend`, `e2e`, `planDir`, `evidenceDir`), then write `.aiflow/repos.json`. **Do not guess** the folder layout.
+2. **Resolve ticket.** Use `ticketId` param, else read `.aiflow/context/current.json`. If none, use a descriptive slug for `[ticket-id]`.
+3. **Read inputs** (any that exist):
+   - `<planDir>/[ticket-id]/requirement.md` (Gate 1)
+   - `<planDir>/[ticket-id]/plan.md` (Gate 2)
+   - business-logic doc (path provided by user or pasted)
+   - tester's draft (text after `---`)
+   - `custom/rules/test-patterns.md`
+4. **Require `baseUrl`.** If missing, ask before continuing.
+5. If NO testcase draft is provided, that's fine — derive test cases from the requirement + business-logic docs (this is the primary value).
+
+---
+
+## Phase 2 — Analyze (GATE 1)
+
+Produce a structured test case list:
+
+```
+## Test Cases — [Feature Name]
+
+| ID   | Test case                      | Steps                                          | Expected Result                  |
+|------|--------------------------------|------------------------------------------------|----------------------------------|
+| TC01 | Đăng nhập thành công           | 1. /login 2. Nhập email+pass hợp lệ 3. Submit  | Redirect /dashboard              |
+| TC02 | Sai mật khẩu                   | 1. /login 2. Sai password 3. Submit            | Hiện error message               |
+| TC03 | Validation email trống         | 1. /login 2. Submit ngay                       | "Email là bắt buộc"              |
+```
+
+> ⚠️ **GATE — STOP HERE.** Show the list and ask:
+> "Danh sách test cases trên có đúng không? Thêm/sửa/xóa gì không? Xác nhận để tôi khám phá app và sinh code."
+>
+> **Wait for confirmation before Phase 3.** Do not explore or generate code until confirmed.
+
+---
+
+## Phase 3 — Explore (Playwright MCP, live browser)
+
+Only if `explore: true` AND the Playwright MCP server is available AND the app is reachable.
+
+For each test case, drive the real app:
+1. `browser_navigate(baseUrl + path)` — open the page
+2. `browser_snapshot()` — read the accessibility tree; **extract real selectors** (prefer `getByRole` → `getByLabel` → `getByTestId`)
+3. Walk the flow (type, click) to confirm it behaves as the test case expects
+4. `browser_take_screenshot()` → save to `<evidenceDir>/[ticket-id]/TC<NN>-step<N>.png`
+5. Record the verified selectors for Phase 4
+
+**Output of this phase:** a selector map (element → verified locator) + evidence screenshots.
+
+> Do NOT commit the MCP session. The committable artifact is produced in Phase 4.
+
+### Fallback
+If `explore: false`, MCP unavailable, or the app is unreachable:
+- Generate from inference (v1 behavior)
+- **Warn clearly** that selectors are unverified and a developer must check them
+- Skip evidence capture
+
+---
+
+## Phase 4 — Generate (durable scripts)
+
+Write files under the `e2e` path from `repos.json`:
+
+```
+<e2e>/
+├── pages/
+│   ├── BasePage.ts          ← only if missing (template below)
+│   └── [Feature]Page.ts     ← Page Object; selectors from Phase 3
+├── specs/[ticket-id]/[feature].spec.ts
+├── fixtures/test.ts         ← only if missing
+└── playwright.config.ts     ← only if missing (template below)
+```
+
+**Rules:**
+- `BasePage.ts` / `playwright.config.ts` / `fixtures/test.ts` — create only if absent. Templates at `.claude/skills/automation-testing/templates/`.
+- **Page Object** — declare locators using verified selectors from Phase 3 (`getByRole` > `getByLabel` > `getByTestId`; avoid CSS/XPath unless unavoidable). One async method per action.
+- **Spec** — one `test()` per case; group with `test.describe`; test ids MUST match Phase 2 (TC01, TC02…); explicit `expect` assertions.
+- Apply patterns from `custom/rules/test-patterns.md` where relevant.
+
+---
+
+## Phase 5 — Run & Report
+
+### If `autoRun: true`
+1. Determine the target repo for E2E (per §Git below) and `cd` there.
+2. Run `npx playwright test <e2e>/specs/[ticket-id]/` (add `--headed` if `headed: true`).
+3. On completion: `npx playwright show-report` (or report the HTML path).
+4. Summarize: pass/fail count, failed-test screenshots, plus the Phase 3 exploration evidence folder.
+
+### If `autoRun: false`
+Print manual instructions:
+```
+✅ Scripts generated.
+  npx playwright test                              # all
+  npx playwright test <e2e>/specs/[ticket-id]/     # this ticket
+  npx playwright test --headed                     # show browser
+  npx playwright show-report                        # HTML report
+```
+
+---
+
+## Git & Gate 5 (multi-repo)
+
+The parent workspace is usually NOT a git repo. Commit to the **repo that owns the code under test**:
+
+| Artifact | Commit target |
+|----------|---------------|
+| E2E tests for UI | the **frontend** repo (`<frontend>/e2e/`) — unless a dedicated `e2e` repo exists |
+| requirement.md / plan.md | `<planDir>` at parent level (shared; not committed into a sub-repo) |
+
+> When creating a PR (aiflow Gate 5 / `requesting-code-review`), `cd` into the correct sub-repo first — `git`/PR commands must run inside that repo, not the parent cwd.
+
+---
+
+## Two mandatory gates
+1. After Phase 2 — confirm the test case list before exploring/generating.
+2. After Phase 5 — hand off (evidence + report) and ask the developer to review before commit/PR.

package/custom/skills/automation-testing/templates/BasePage.ts

@@ -0,0 +1,30 @@
+import { Page, expect } from '@playwright/test';
+
+/**
+ * BasePage — shared helpers for all Page Objects.
+ * Generated by the aiflow `automation-testing` skill. Create once; extend per feature.
+ */
+export abstract class BasePage {
+  constructor(protected readonly page: Page) {}
+
+  /** Navigate to a path relative to playwright.config `baseURL`. */
+  async navigate(path = '/'): Promise<void> {
+    await this.page.goto(path);
+    await this.waitForLoad();
+  }
+
+  /** Wait until network is idle (page settled). */
+  async waitForLoad(): Promise<void> {
+    await this.page.waitForLoadState('networkidle');
+  }
+
+  /** Capture a full-page screenshot as evidence. */
+  async screenshot(name: string): Promise<void> {
+    await this.page.screenshot({ path: `evidence/${name}.png`, fullPage: true });
+  }
+
+  /** Assert the current URL matches (string or RegExp). */
+  async expectUrl(url: string | RegExp): Promise<void> {
+    await expect(this.page).toHaveURL(url);
+  }
+}

package/custom/skills/automation-testing/templates/playwright.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Playwright config generated by the aiflow `automation-testing` skill.
+ * Create once per target repo; edit to fit your environment.
+ */
+export default defineConfig({
+  testDir: './specs',
+  fullyParallel: false,
+  retries: process.env.CI ? 1 : 0,
+  reporter: [['html', { open: 'never' }], ['list']],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+});

package/custom/skills/automation-testing/templates/repos.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "Workspace map for the automation-testing skill. Copied to .aiflow/repos.json. Paths are relative to the parent workspace folder (aiflow cwd). Adjust to match your layout.",
+  "backend": "./backend",
+  "frontend": "./frontend",
+  "e2e": "./frontend/e2e",
+  "planDir": "./plan",
+  "evidenceDir": "./frontend/e2e/evidence"
+}

package/custom/skills/figma-to-component/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: figma-to-component
-description: Read designs from Figma and generate React/Next.js/Vue components following project conventions. Supports specific frame URLs and entire pages.
-keywords: figma, design, component, ui, generate, react, nextjs, vue, frontend
+description: Read designs from Figma and generate React/Next.js App Router/Vue/Angular components following project conventions. Supports specific frame URLs and entire pages.
+keywords: figma, design, component, ui, generate, react, nextjs, nextjs-app-router, vue, angular, frontend
 ---
 
 # Figma to Component
@@ -14,6 +14,19 @@ keywords: figma, design, component, ui, generate, react, nextjs, vue, frontend
 
 ---
 
+## Step 0: Verify Figma MCP is available
+
+Before doing anything, confirm the Figma MCP server is connected in this session:
+
+- The tool `mcp__figma__get_figma_data` (and `mcp__figma__download_figma_images`) must be available.
+- If it is **not** available, STOP and tell the developer:
+  > Figma MCP not connected. Run `aiflow init -a figma` (REST API token) or
+  > `aiflow init -a figma-desktop` (Figma Desktop), then restart the session.
+
+Do not guess design values from the URL — without the MCP server the skill cannot read the design.
+
+---
+
 ## Process
 
 ### Step 1: Identify input
@@ -30,20 +43,24 @@ Extract `fileKey` and `nodeId` from the URL.
 Use Figma MCP tools to fetch design information:
 
 ```
-1. Get node info: figma_get_file_nodes(fileKey, nodeIds=[nodeId])
-2. Get styles: figma_get_file_styles(fileKey)
-3. Get components: figma_get_file_components(fileKey) if needed
-4. Export image if visual reference needed: figma_get_image(fileKey, nodeId)
+1. Get node info, styles, and components in one call:
+   get_figma_data(fileKey, nodeId, depth=2)
+
+2. Export image if visual reference needed:
+   download_figma_images(fileKey, nodes=[{ nodeId, fileName }], localPath)
 ```
 
+Note: `get_figma_data` returns layout, fills, strokes, typography, and component
+definitions in a single response. No separate style or component fetch is needed.
+
 Analyze the output to extract:
 - **Layout**: flexbox direction, gap, padding, alignment
 - **Sizing**: width/height (fixed vs fill vs hug)
-- **Colors**: fills, strokes → map to Tailwind colors if available
-- **Typography**: font-size, font-weight, line-height, letter-spacing → map to Tailwind text classes
-- **Spacing**: padding, margin, gap → map to Tailwind spacing scale
-- **Border**: radius, width, color → map to Tailwind border classes
-- **Shadow**: box-shadow → map to Tailwind shadow classes
+- **Colors**: fills, strokes → map to project CSS tokens / Tailwind colors if available
+- **Typography**: font-size, font-weight, line-height, letter-spacing
+- **Spacing**: padding, margin, gap
+- **Border**: radius, width, color
+- **Shadow**: box-shadow
 - **States**: hover, focus, disabled, active (if variants present)
 - **Responsive**: breakpoints if multiple frames present
 
@@ -73,19 +90,12 @@ download_figma_images({
 - `localPath` defaults to `public/assets/figma/` (relative to the project root)
 - `fileName` follows the pattern: `<layer name in lowercase, spaces replaced with ->-<nodeId>.png`
   - Example: layer "Banner Top" with nodeId "123-456" → `banner-top-123-456.png`
-- If MCP does not support `download_figma_images`, use `get_images` to get the URL, then notify DEV to download manually and place in `public/assets/figma/`
+- If MCP does not support `download_figma_images`, get the image URL via `get_figma_data`, then notify DEV to download manually and place in `public/assets/figma/`
 
 **Record the result:**
 
 After export, save the mapping for use in Step 4:
 
-```
-imageMap = {
-  "<nodeId>": "public/assets/figma/<fileName>.png"
-}
-```
-
-Example:
 ```
 imageMap = {
   "123-456": "public/assets/figma/banner-top-123-456.png",
@@ -93,53 +103,50 @@ imageMap = {
 }
 ```
 
-### Step 3: Map Figma tokens → Tailwind / CSS
+### Step 3: Detect CSS tooling, then map Figma tokens
 
-**Color mapping:**
-```
-Figma hex #3B82F6 → Tailwind blue-500
-Figma hex #EF4444 → Tailwind red-500
-Figma rgba(0,0,0,0.5) → Tailwind black/50
-No Tailwind match → use arbitrary value [#hexcode]
-```
+**Detect the project's styling approach first** (do not assume Tailwind):
 
-**Spacing mapping (8px grid):**
-```
-4px  → p-1 / gap-1
-8px  → p-2 / gap-2
-12px → p-3 / gap-3
-16px → p-4 / gap-4
-24px → p-6 / gap-6
-32px → p-8 / gap-8
-No match → arbitrary value [20px]
-```
+1. `tailwind.config.*` present → **Tailwind** — map to utility classes; extend `tailwind.config` with design tokens when a value has no built-in match
+2. `*.module.css` / `*.module.scss` files present → **CSS Modules** — emit a co-located `.module.css` and reference `styles.x`
+3. `styled-components` / `@emotion` in `package.json` → **CSS-in-JS** — emit styled components
+4. None of the above → **vanilla CSS** — emit a co-located `.css` file with CSS custom properties
+
+**Design tokens:** prefer mapping Figma Styles/Variables to existing project tokens
+(Tailwind theme keys or CSS custom properties) instead of hardcoding hex/px values.
+Only fall back to an arbitrary value when no token matches.
+
+**Tailwind reference mappings** (when Tailwind is the detected tooling):
 
-**Typography mapping:**
 ```
-text-xs: 12px
-text-sm: 14px
-text-base: 16px
-text-lg: 18px
-text-xl: 20px
-text-2xl: 24px
-text-3xl: 30px
-font-normal: 400
-font-medium: 500
-font-semibold: 600
-font-bold: 700
+Color:   #3B82F6 → blue-500 · #EF4444 → red-500 · rgba(0,0,0,0.5) → black/50
+         no match → arbitrary value [#hexcode]
+Spacing: 4→p-1/gap-1 · 8→p-2 · 12→p-3 · 16→p-4 · 24→p-6 · 32→p-8 (8px grid)
+         no match → arbitrary value [20px]
+Type:    12→text-xs · 14→text-sm · 16→text-base · 18→text-lg · 20→text-xl · 24→text-2xl · 30→text-3xl
+         400→font-normal · 500→font-medium · 600→font-semibold · 700→font-bold
 ```
 
 ### Step 4: Generate component
 
-**Framework detection** — check the project's CLAUDE.md to determine the framework:
-- `reactjs` / `nextjs` → generate `.tsx` with React conventions
-- `vue-nuxt` → generate `.vue` with Vue 3 Composition API
+**Framework detection** — check in this order:
+
+1. Read project's `CLAUDE.md` for framework identifier:
+   - `nextjs-app-router` → Next.js App Router (Server/Client Components)
+   - `reactjs` / `nextjs` → React / Next.js Pages Router `.tsx`
+   - `vue-nuxt` → Vue 3 `.vue` with Composition API
+   - `angular` → Angular `@Component` class
+2. Scan project files if CLAUDE.md is ambiguous:
+   - `app/` directory present → `nextjs-app-router`
+   - `angular.json` present → `angular`
+   - `nuxt.config.*` present → `vue-nuxt`
+3. Fallback → `nextjs` (React Pages Router)
 
 **Image node rendering rule:**
 
 Before rendering each node, check `imageMap` from Step 2.5:
 - If `nodeId` is in `imageMap` → render using `<img>` (React/Vue) or `<Image>` (Next.js), do NOT use CSS `background-image`
-- If not in `imageMap` → render normally using div + Tailwind classes
+- If not in `imageMap` → render normally using div + styling classes
 
 React/Next.js template for image node:
 ```tsx
@@ -197,6 +204,57 @@ export const [ComponentName] = ({ className }: [ComponentName]Props) => {
 };
 ```
 
+#### Next.js App Router component template:
+
+Default to **Server Component**. Add `'use client'` only when the design has
+interactive states (hover effects, click handlers, form inputs, modals).
+
+```tsx
+// Server Component — no interactivity (default)
+interface [ComponentName]Props {
+  className?: string;
+}
+
+export default async function [ComponentName]({ className }: [ComponentName]Props) {
+  return (
+    <div className={cn(
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      className
+    )}>
+      {/* Child nodes */}
+    </div>
+  );
+}
+```
+
+```tsx
+// Client Component — has onClick / useState / useEffect
+'use client'
+
+import { useState } from 'react'
+
+interface [ComponentName]Props {
+  className?: string;
+}
+
+export function [ComponentName]({ className }: [ComponentName]Props) {
+  return (
+    <div className={cn(
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      className
+    )}>
+      {/* Child nodes */}
+    </div>
+  );
+}
+```
+
+File path: `app/components/[ComponentName].tsx` or `components/[ComponentName].tsx`
+
 #### Vue 3 component template:
 
 ```vue
@@ -221,6 +279,40 @@ const props = withDefaults(defineProps<Props>(), {});
 </template>
 ```
 
+#### Angular component template:
+
+Use Tailwind classes if `tailwind.config.*` exists in the project root.
+Otherwise use `styles` array with CSS-in-component.
+
+```typescript
+import { Component, Input } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-[component-name]',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div [class]="hostClasses">
+      <!-- Child nodes -->
+    </div>
+  `,
+  styles: []
+})
+export class [ComponentName]Component {
+  @Input() className = '';
+
+  get hostClasses(): string {
+    return [
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      this.className
+    ].filter(Boolean).join(' ');
+  }
+}
+```
+
 ### Step 5: Handle interactive states
 
 If Figma has variants (Default, Hover, Disabled, Active):
@@ -245,14 +337,14 @@ const variantClasses = {
 After generation, verify:
 
 - [ ] Layout matches Figma (flex direction, alignment, gap)
-- [ ] Colors mapping correct (or use arbitrary values if no Tailwind match)
+- [ ] Colors mapping correct (project tokens, or arbitrary values if no match)
 - [ ] Typography correct (size, weight, line-height)
 - [ ] Spacing correct (padding, margin, gap)
 - [ ] Component has `className` prop for external overrides
-- [ ] Use `cn()` helper for conditional/mergeable classes
+- [ ] Conditional/mergeable classes use the project's helper (`cn()` for Tailwind)
 - [ ] Responsive if Figma has mobile frames
 - [ ] Props typed with TypeScript interface
-- [ ] Image nodes use `<img>` tag (do not use CSS `background-image`)
+- [ ] Image nodes use `<img>` / `<Image>` (do not use CSS `background-image`)
 - [ ] Image files exist in `public/assets/figma/` before submitting code
 
 ---
@@ -273,9 +365,9 @@ Always output in order:
 
 ## Rules
 
-- **Do not hardcode** hex colors directly into className if a Tailwind equivalent exists
-- **Always use** `cn()` (clsx + twMerge) to merge classes
-- **No new CSS imports** — use Tailwind utilities only
+- **Detect styling tooling first** — do not assume Tailwind; honour CSS Modules / styled-components / vanilla CSS when detected
+- **Prefer design tokens** — map Figma Styles/Variables to project tokens; only hardcode a value when no token matches
+- **Always use** the project's class-merge helper (`cn()` = clsx + twMerge for Tailwind)
 - **Responsive** — if Figma only has 1 breakpoint, default to mobile-first design
 - **Accessibility** — add `aria-label`, `role`, `alt` for interactive and image elements
 - **Image** — detect image fills in Figma node data, export via `download_figma_images` MCP, save to `public/assets/figma/`. Use `<Image>` (Next.js) or `<img>` (React/Vue) with `src` pointing to the exported file. Do NOT use CSS `background-image` for image nodes.
@@ -283,6 +375,19 @@ Always output in order:
 
 ---
 
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `mcp__figma__get_figma_data` not available | Figma MCP server not connected | Run `aiflow init -a figma` or `-a figma-desktop`, restart session |
+| `403 Forbidden` / token rejected | PAT invalid or wrong header | Re-issue a `figd_...` token; `init` sends `X-Figma-Token` (not `Bearer`) |
+| Tool call hangs / times out | Large node tree (`depth` too high) | Lower `depth` (e.g. `depth=1`), target a specific `nodeId` not the whole file |
+| `404` on node | Wrong `fileKey`/`nodeId` | Re-copy the frame URL; node-id uses `-` in URL but `:` in API |
+| Empty fills / no styles | Node is a component instance | Fetch the main component, or increase `depth` |
+| `download_figma_images` unsupported | Older MCP preset | Get image URL via `get_figma_data`, download manually to `public/assets/figma/` |
+
+---
+
 ## Trigger Example Commands
 
 ```

package/docs/common/CHANGELOG.md

@@ -7,6 +7,22 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.1.1] - 2026-06-08
+
+### Added
+
+- **Ubuntu / Linux clipboard support in `ak prompt`** — `ak prompt` now copies to the clipboard on native Linux. It auto-detects the display server (Wayland → `wl-copy`, X11 → `xclip` → `xsel`) and the package manager (`apt-get` / `dnf` / `pacman` / `zypper`). When no clipboard tool is installed it prints a clear warning (`⚠ Clipboard tool not found (need: xclip)`), shows the exact install command, and offers to install it via `sudo` then retries the copy. If the user declines or no package manager is found, it falls back to printing the full prompt for manual copy. Previously the command silently failed on Ubuntu when neither `xclip` nor `xsel` was present.
+- **`figma-to-component`: image detection & export** — The skill now scans the Figma node tree for image nodes (`fills[].type === "IMAGE"`, `VECTOR`/`BOOLEAN_OPERATION`, complex non-CSS groups), exports them via `download_figma_images` into `public/assets/figma/`, and records an `imageMap`. Generated components render those nodes with `<Image>` (Next.js) / `<img>` (React/Vue) instead of CSS `background-image`.
+- **`figma-to-component`: MCP availability pre-check (Step 0)** — The skill now verifies `mcp__figma__get_figma_data` / `mcp__figma__download_figma_images` are connected before running, and stops with setup instructions (`aiflow init -a figma` / `-a figma-desktop`) instead of guessing design values from the URL.
+- **`figma-to-component`: CSS tooling detection + design tokens** — Detection now branches on the project's styling approach (Tailwind / CSS Modules / styled-components / vanilla CSS) instead of hardcoding Tailwind, and prefers mapping Figma Styles/Variables to existing project tokens (Tailwind theme keys or CSS custom properties), falling back to arbitrary values only when no token matches.
+- **`figma-to-component`: troubleshooting table** — Added a troubleshooting section covering MCP-not-connected, `403`/token rejected, request timeout (lower `depth`), `404` node-id, empty fills, and unsupported `download_figma_images`.
+
+### Fixed
+
+- **Critical: `figma-to-component` source/installed divergence** — The source skill (`custom/skills/figma-to-component/SKILL.md`) still referenced the non-existent tool names `figma_get_file_nodes` / `figma_get_file_styles` / `figma_get_image` and only had 2-tier framework detection, while the installed `.claude/` copy had been fixed in 0.0.9. The next `aiflow init` / `sync-skills` would have overwritten the working copy with the broken source — re-introducing the 0.0.9 bug. Both copies are now synced to a single canonical version: correct tool names (`get_figma_data` / `download_figma_images`), 4-tier framework detection (App Router / React / Vue / Angular), and the image-export step.
+
+---
+
 ## [0.1.0] - 2026-05-28
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.1.1-beta.0",
+  "version": "0.1.1",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {
@@ -65,4 +65,4 @@
       "<rootDir>/tests/**/*.test.js"
     ]
   }
-}
+}