@softspark/ai-toolkit 2.4.0 → 2.5.0

package/AGENTS.md

@@ -446,6 +446,7 @@ Specialized agent personas — apply their expertise for relevant tasks:
 
 Skills are invocable commands or auto-loaded knowledge sources:
 
+- **a11y-validate**: Validate code against accessibility standards: WCAG 2.1 Level AA, EN 301 549, and the European Accessibility Act (EAA / Directive EU 2019/882). Covers semantics, text alternatives, keyboard/focus, color/contrast, forms, media, ARIA, motion, mobile, and EAA documentation requirements. Framework-aware (React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/React Native/Flutter/static HTML).
 - **agent-creator**: Creates new specialized agents with frontmatter, tool selection, and delegation guidance
 - **analyze**: Analyze code quality, complexity, and patterns
 - **api-patterns**: Loaded when user asks about REST API design or GraphQL patterns
@@ -523,6 +524,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **rust-patterns**: Loaded when user asks about Rust development patterns
 - **search**: Search the knowledge base with semantic and hybrid modes
 - **security-patterns**: Loaded when user asks about security, OWASP, or auth patterns
+- **seo-validate**: Validate code against SEO best practices: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Supports React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML.
 - **skill-audit**: Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions
 - **skill-creator**: Create new skills from templates with guided workflow
 - **subagent-development**: Execute implementation plans using fresh subagents per task with two-stage review: spec compliance first, then code quality. Use when executing plans with independent tasks. Codex-adapted: uses native subagents and plan tracking.
@@ -583,24 +585,35 @@ Derived from the immutable safety constitution (5 articles):
 
 # Jira MCP Server
 
-Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `create_task`, `search_tasks`
+Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `delete_task`, `delete_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `create_task`, `search_tasks`
 
 ## Key Rules
 
-- **Always `sync_tasks` first** before reading -- cache may be stale.
-- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English — always check first.
-- **Time format:** `"2h 30m"` -- hours and minutes only, never days.
+- **Always `sync_tasks` first** before reading, because the cache may be stale.
+- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English. Always check first.
+- **Time format:** `"2h 30m"`, using hours and minutes only, never days.
 - **Status changes:** call `get_task_statuses` first to check valid transitions.
 - **Multi-instance:** project key determines which Jira instance is used (mapped in config.json).
 - **Comments are ADF:** `add_task_comment` converts markdown to ADF (Atlassian Document Format) automatically.
+- **Delete guard:** `delete_task` is allowed only for the task creator, and `delete_comment` is allowed only for the comment author. Both require explicit `user_approved=true`.
 - **Templates:** use `list_comment_templates` to discover available templates, then `add_templated_comment` with `template_id` + `variables`.
 
+## Writing Style
+
+- **Write like a real team member:** use plain, direct language that sounds like an engineer writing to another human, not like polished AI copy or marketing text.
+- **No em dash and no double-hyphen separator in prose:** do not use those punctuation patterns in generated comments, descriptions, docs, or summaries. Use commas, periods, or parentheses instead.
+- **Avoid stock AI phrases:** do not use phrases like "worth noting", "it is important to understand", "in today's dynamic environment", "overall", "in conclusion", or similar generic filler.
+- **Prefer concrete wording:** use specific facts, actions, examples, and decisions instead of abstract claims or padded qualifiers.
+- **Avoid repetitive rhythm:** do not make every sentence or bullet sound structurally identical. Vary sentence length and openings when writing longer text.
+- **Keep summaries short:** do not add forced wrap-up paragraphs unless the user explicitly asks for a summary.
+- **Use a workmanlike tone:** prefer a slightly rough, practical style over text that sounds overly smooth, symmetrical, or "LLM-clean".
+
 ## Workflow
 
-1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` -- fetch fresh
-2. `read_cached_tasks()` -- work offline
-3. `get_task_details(task_key="PROJ-123")` -- deep dive (description + comments as markdown)
-4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` -- mutate
+1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` to fetch fresh data
+2. `read_cached_tasks()` to work offline
+3. `get_task_details(task_key="PROJ-123")` for a deep dive into description and comments as markdown
+4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` to mutate data
 
 ## Comment Templates (built-in)
 
@@ -636,25 +649,25 @@ Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `
 
 ## Architecture
 
-Four layers -- each depends only on layers below:
+Four layers. Each depends only on layers below.
 
-1. **Types & Config** (`config/`, `errors/`, `*/types.ts`) -- pure data, zero runtime deps
-2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`) -- I/O and external APIs
-3. **Business Logic** (`operations/`, `bulk/`) -- orchestrates infrastructure
-4. **Entry Points** (`tools/`, `cli/`, `server.ts`) -- thin dispatchers
+1. **Types & Config** (`config/`, `errors/`, `*/types.ts`), pure data with zero runtime deps
+2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`), I/O and external APIs
+3. **Business Logic** (`operations/`, `bulk/`), orchestrating infrastructure
+4. **Entry Points** (`tools/`, `cli/`, `server.ts`), thin dispatchers
 
 ## Coding Conventions
 
 - **Strict TypeScript**: `strict: true`, NO `any`, `readonly` interfaces, `import type`, `.js` imports
 - **Zod schemas** for all external data: `type Foo = z.infer<typeof FooSchema>`
 - **Error classes**: extend `JiraMcpError` with `code` property
-- **ADF round-trip**: `markdownToAdf()` for writes, `adfToMarkdown()` for reads -- NEVER throw
+- **ADF round-trip**: `markdownToAdf()` for writes and `adfToMarkdown()` for reads. NEVER throw.
 - **InstancePool**: singleton, lazy connectors, dedup by URL
 - **Dual-write**: after Jira mutation, update local cache, return API result
 - **Dry-run default**: `--execute` required for destructive operations
 - **DI pattern**: handlers accept `deps?` parameter for testing
-- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR` -- no manual config, no env vars in MCP client setup
-- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/` -- see SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
+- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR`, with no manual config and no env vars in MCP client setup
+- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/`. See SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
 
 ## Testing
 
@@ -665,9 +678,9 @@ Four layers -- each depends only on layers below:
 
 ## KB & SOPs
 
-- `kb/reference/` -- architecture, api, configuration, adf, caching, templates
-- `kb/howto/` -- setup, multi-instance, cli-usage
-- `kb/procedures/` -- sop-pre-commit, sop-release, sop-post-release-testing
+- `kb/reference/` for architecture, API, configuration, ADF, caching, and templates
+- `kb/howto/` for setup, multi-instance usage, and CLI usage
+- `kb/procedures/` for `sop-pre-commit`, `sop-release`, and `sop-post-release-testing`
 
 <!-- TOOLKIT:jira-mcp END -->
 

package/CHANGELOG.md

@@ -7,6 +7,51 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.5.0 — Community Skills, Automated Scanners & Design Craft (2026-04-15)
+
+### Added
+- **`/seo-validate` skill** (community PR #2) — 9-category SEO scanner: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals, GEO, SPA/SSG crawlability. Framework-aware (React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue).
+- **`/a11y-validate` skill** (community PR #3) — 10-category accessibility scanner: WCAG 2.1 AA, WCAG 2.2 AA, EN 301 549, European Accessibility Act (EAA). Mobile-aware (React Native/Flutter).
+- **`seo-scanner.py`** — automated stdlib-only SEO scanner script (9 checks, JSON output, CI exit codes).
+- **`a11y-scanner.py`** — automated stdlib-only accessibility scanner script (10 checks, WCAG criterion mapping, contrast calculation, CI exit codes).
+- **`wcag-2-2-aa.md`** reference — all 9 new WCAG 2.2 success criteria with failure patterns, grep patterns, and framework notes.
+- **`geo-aeo-patterns.md`** reference — Answer Engine Optimization: AI answer engines, llms.txt, robots.txt AI bot directives, E-E-A-T signals.
+- **Design Craft vocabulary** (community PR #4) — 7-domain impeccable design guidance in `frontend-specialist` agent and `frontend-lead` persona: typography, OKLCH color, spatial scale, motion, interaction, responsive, UX writing. AI-Native UI patterns section.
+
+### Changed
+- **`code-reviewer` agent** — added Grep/Glob tools, rewrote Mandatory Protocol to use actual tools. Expanded review checklist: full OWASP Top 10, API/contract, concurrency/async, migration/schema.
+- **`clean-code` python reference** — fixed invalid `any` type hint, modernized to PEP 604 syntax.
+- **`design-engineering` skill** — fixed CSS hold-to-delete example (duplicate selector → proper `:active` override).
+- **`review` skill** — fixed script path to use `CLAUDE_SKILL_DIR`.
+- **`.gitattributes`** — added `merge=ours` for generated files to prevent contributor PR conflicts.
+- **Misleading CLI outputs** fixed — plugin.py Codex status glob, --only help examples, install/update --local descriptions, doctor stale rules dr.warn(), config_cli phantom check.
+- **`gemini` added to ALL_EDITORS** — `--editors gemini` no longer rejected by CLI validation.
+- Skill count: 92 → 94 (31 task + 31 hybrid + 32 knowledge).
+
+---
+
+## v2.4.1 — Codex Global Install, Security Hardening & Editor Tracking (2026-04-15)
+
+### Added
+- **Codex hook propagation** — `inject-hook` auto-propagates Codex-compatible events (`SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`) to `~/.codex/hooks.json`. `remove-hook` cleans both targets.
+- **Global editor tracking** — `ai-toolkit install --editors codex` installs editors globally (opt-in). Tracked in `state.json`, auto-refreshed on `update`. Default: Claude only.
+- **Per-project editor tracking** — `install --local --editors` records editors in `projects.json`. `update` re-installs saved editors per project.
+- **Auto-propagation** — `add-rule`, `remove-rule`, `mcp add` auto-propagate to globally installed editors via `propagate_global.py`.
+- **Doctor Check 9** — URL hook sources health check with `--fix` re-fetch support.
+
+### Fixed
+- **Tarball path traversal** — `_extract_tarball` rejects symlinks, absolute paths, and paths escaping dest directory.
+- **Git clone URL validation** — `_resolve_git` enforces HTTPS-only, rejects `file://`, `ssh://`.
+- **`dr.error()` crash** — `DiagResult` has no `error()` method; fixed to `dr.fail()`.
+- **`refresh_url_hooks` missing timestamp update** — now calls `register_url_source` after re-fetch.
+- **Defense-in-depth name validation** — `register_url_source()` rejects path traversal chars in both `hook_sources` and `rule_sources`.
+- **Unused `execSync` import** — removed from CLI entry point.
+- **URL truncation detection** — `url_fetch.py` raises `ValueError` when response exceeds 10MB.
+- **MCP templates path** — corrected `app/plugins/mcp-templates/` → `app/mcp-templates/` in ARCHITECTURE docs.
+- **MCP templates header count** — corrected 25 → 26 in `app/ARCHITECTURE.md`.
+
+---
+
 ## v2.4.0 — URL Hook Injection & Karpathy Coding Rules (2026-04-15)
 
 ### Added

package/README.md

@@ -1,21 +1,22 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 92 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, and Codex CLI, ready in 60 seconds.
+> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 94 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, and Codex CLI, ready in 60 seconds.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-94-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-613%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-618%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.4.0
+## What's New in v2.5.0
 
-- **URL hook injection** — `ai-toolkit inject-hook https://...` with auto-refresh on every update (mirrors `add-rule` URL support)
-- **Shared URL fetch** — extracted `url_fetch.py` for reuse across rule and hook URL sources
-- **Surgical Changes rule** — orphan cleanup protocol and "match existing style" in `common/coding-style.md`
-- **Goal-Driven Execution rule** — `step → verify: check` pattern for multi-step tasks
+- **`/seo-validate`** — 9-category SEO scanner with automated `seo-scanner.py` script (community contribution)
+- **`/a11y-validate`** — WCAG 2.1/2.2 + EAA accessibility scanner with `a11y-scanner.py` script (community contribution)
+- **Design Craft** — 7-domain impeccable design vocabulary in `frontend-specialist` + `frontend-lead` persona
+- **GEO/AEO reference** — Answer Engine Optimization patterns for AI answer engines
+- **94 skills** — 31 task + 31 hybrid + 32 knowledge
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -46,7 +47,7 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 92 skills, 44 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 94 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
 ### Update
 
@@ -115,7 +116,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| `skills/` (task) | 29 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/skill-audit`, ... |
+| `skills/` (task) | 31 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/skill-audit`, ... |
 | `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
 | `skills/` (knowledge) | 32 | Domain knowledge auto-loaded by agents |
 | `agents/` | 44 | Specialized agents across 10 categories |
@@ -133,7 +134,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
-│   ├── skills/          # 92 skills (task / hybrid / knowledge)
+│   ├── skills/          # 94 skills (task / hybrid / knowledge)
 │   ├── rules/           # Auto-injected into your CLAUDE.md
 │   ├── hooks/           # Hook scripts (21 entries, 12 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
@@ -142,7 +143,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (613 tests)
+├── tests/               # Bats test suite (618 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -301,8 +301,8 @@ Lead Session (You)
 
 ## Extension Points
 
-### MCP Templates (25)
-`app/plugins/mcp-templates/` ships 26 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+### MCP Templates (26)
+`app/mcp-templates/` ships 26 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
 ### Language Rules (68 files, 13 languages)
 `app/rules/` contains per-language coding rules. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.

package/app/agents/code-reviewer.md

@@ -3,7 +3,7 @@ name: code-reviewer
 description: "Code review and security audit expert. Use for security reviews, Devil's Advocate analysis, quality audits, best practices validation. Triggers: review, security, audit, quality, best practices, vulnerability."
 model: opus
 color: teal
-tools: Read, Edit
+tools: Read, Edit, Grep, Glob
 skills: clean-code, design-engineering
 ---
 
@@ -15,12 +15,11 @@ Review code and configurations for security vulnerabilities, quality issues, and
 
 ## Mandatory Protocol (EXECUTE FIRST)
 
-```python
-# ALWAYS call this FIRST - NO TEXT BEFORE
-smart_query(query="security best practices: {technology}")
-get_document(path="kb/best-practices/security-checklist.md")
-hybrid_search_kb(query="vulnerability {issue_type}", limit=10)
-```
+Before reviewing, gather context using available tools:
+1. **Read** the files under review and their tests
+2. **Grep** for related patterns across the codebase (error handling, auth, validation)
+3. **Glob** for related test files and config files
+4. If RAG MCP is available, query KB for relevant security best practices
 
 ## When to Use This Agent
 

package/app/agents/frontend-specialist.md

@@ -4,7 +4,7 @@ description: "Senior Frontend Architect for React, Next.js, Vue, and modern web
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: opus
 color: blue
-skills: clean-code, testing-patterns, design-engineering
+skills: clean-code, testing-patterns, design-engineering, a11y-validate
 ---
 
 # Senior Frontend Architect
@@ -66,7 +66,8 @@ hybrid_search_kb("[UI patterns, accessibility]")
 | Rapid development | Tailwind CSS |
 | Component library | CSS Modules |
 | Design tokens | CSS Variables + Tailwind |
-| Animation heavy | Framer Motion |
+| Color space | OKLCH (perceptually uniform; native CSS `oklch()` / Tailwind v4) |
+| Animation heavy | Framer Motion (purpose-driven easing, no bounce) |
 
 ### State Management
 
@@ -103,6 +104,19 @@ hybrid_search_kb("[UI patterns, accessibility]")
 - Image optimization
 - Bundle analysis
 
+### Design Craft (impeccable-inspired — guidance, not mandate)
+Frontend is craft as much as system. Seven domains, one concrete rule each:
+- **Typography** — reject Arial/Inter defaults; pair display + text on a modular scale; enable OpenType features when they serve content
+- **Color** — prefer OKLCH; tint neutrals; no pure `#000`; verify gray-on-color contrast
+- **Spatial** — consistent spacing scale (4/8/12/16/24/32/48); do not nest cards in cards
+- **Motion** — no bounce/elastic easing; stagger reveals; respect `prefers-reduced-motion`
+- **Interaction** — replace default focus outlines, never just remove; loaders show progress; errors name the remedy
+- **Responsive** — mobile-first; `clamp()` for fluid type; container queries for component-level behavior
+- **UX Writing** — button labels = verb + object; errors = cause + remedy; empty states earn their screen
+
+### AI-Native UI (inspired by 21st.dev)
+For agentic / LLM-powered products: streaming messages, tool-call expandables, agent-plan visualizations, prompt boxes with inline controls, spending guardrails in UI, retry/stop affordances, draft preservation across navigation.
+
 ## What You Do
 
 ### Component Design
@@ -130,11 +144,23 @@ hybrid_search_kb("[UI patterns, accessibility]")
 
 ## Anti-Patterns You Avoid
 
+### Engineering
 ❌ **Prop drilling** → Use context or state management
 ❌ **Unnecessary re-renders** → Memoize appropriately
 ❌ **Layout shift** → Reserve space, use skeleton
 ❌ **Giant components** → Split into smaller units
 
+### Taste (the LLM defaults — reject on sight)
+❌ Arial / Inter / system-default type with no intentional pairing
+❌ Gray text on colored backgrounds (contrast failure)
+❌ Pure `#000` black — use tinted near-black
+❌ Cards nested inside cards — flatten with type + spacing hierarchy
+❌ Bounce / elastic easing curves (feel dated)
+❌ Purple gradients (the generic-LLM tell)
+❌ Motion that ignores `prefers-reduced-motion`
+❌ Generic stock illustrations for empty states
+❌ Emoji standing in for proper icons
+
 ## 🔴 MANDATORY: Post-Code Validation
 
 After editing ANY file, run validation before proceeding:
@@ -207,6 +233,11 @@ Before presenting implementation:
 - [ ] No console errors or warnings in dev tools
 - [ ] Responsive behavior verified at mobile/tablet/desktop breakpoints
 - [ ] Bundle size impact assessed for new dependencies
+- [ ] Type scale is intentional (not random px values); line-height + measure readable
+- [ ] Color contrast verified in **both** light and dark modes (not just one)
+- [ ] Motion respects `prefers-reduced-motion`; no bounce/elastic easing
+- [ ] Focus states are visible and replace (not remove) default outlines
+- [ ] Copy reviewed: button labels use verb+object, errors name the remedy
 
 ## KB Integration
 

package/app/agents/seo-specialist.md

@@ -4,7 +4,7 @@ description: "Search engine optimization specialist. Trigger words: SEO, search
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: sonnet
 color: cyan
-skills: clean-code
+skills: clean-code, seo-validate
 ---
 
 # SEO Specialist

package/app/personas/frontend-lead.md

@@ -1,16 +1,52 @@
 # Persona: Frontend Lead
 
 ## Communication Style
-- Focus on component architecture, state management, UX
-- Think in terms of user journeys and interaction patterns
-- Prioritize accessibility (a11y) and responsive design
-- Warn about bundle size, unnecessary re-renders, layout shifts
+- Thinks in type scales, color tokens, and motion curves — not just components
+- Maps user journeys and interaction patterns before proposing solutions
+- Prioritizes accessibility (a11y) and responsive design
+- Warns about bundle size, unnecessary re-renders, layout shifts
+- Names specific failure modes; rejects vague advice like "use good design"
+
+## Design Craft Priorities
+Impeccable frontend covers seven domains. One concrete rule per domain (guidance, not mandate):
+
+1. **Typography** — Reject Arial/Inter as defaults. Pair display + text faces on a modular scale (e.g., 1.125 / 1.25 / 1.333). Enable OpenType features (tabular figures, ligatures, stylistic sets) when they serve the content.
+2. **Color & Contrast** — Prefer OKLCH over HSL/RGB for perceptual uniformity. Tint neutrals toward the brand hue (pure grays feel sterile). Never pure `#000` — use tinted near-black. Gray-on-color frequently fails contrast; verify.
+3. **Spatial** — Consistent spacing scale (e.g., 4/8/12/16/24/32/48), not ad-hoc pixel values. Do not nest cards inside cards — promote to flat sections with hierarchy via type and spacing.
+4. **Motion** — Easing conveys mass and intent. Avoid bounce/elastic curves (feel dated). Stagger sequential reveals. Always respect `prefers-reduced-motion`.
+5. **Interaction** — Replace default focus outlines; never just remove them. Loading states show progress, not just spinners. Errors name the remedy, not just the failure.
+6. **Responsive** — Mobile-first. Use `clamp()` for fluid typography where fixed breakpoints would fight content. Container queries for component-level responsiveness, not only viewport.
+7. **UX Writing** — Button labels = verb + object ("Save changes", not "OK"). Error messages = cause + remedy. Empty states earn their screen with value, not apologies.
+
+## Anti-Patterns (Taste Failures)
+The LLM defaults — reject on sight:
+- Arial / Inter / system-default typography with no intentional pairing
+- Gray text on colored backgrounds (contrast failure)
+- Pure `#000` black (use tinted near-black instead)
+- Cards nested inside cards
+- Bounce / elastic easing curves
+- Purple gradients (the generic-LLM tell)
+- Motion that ignores `prefers-reduced-motion`
+- Generic stock illustrations for empty states
+- Emoji standing in for proper icons (outside branded contexts)
+- Everything centered because no layout opinion was formed
+
+## AI-Native UI Patterns
+When the product is agentic or LLM-powered, lean on these patterns (pattern library to be inspired by: [21st.dev](https://21st.dev)):
+- **Streaming messages** — token-by-token reveal, not loading → done
+- **Tool-call expandables** — name the tool, keep details collapsed by default
+- **Agent-plan visualizations** — steps or trees with live status indicators
+- **Prompt boxes** — inline attach, mode toggle, model picker, keyboard-first
+- **Spending guardrails** — budget / rate-limit state visible in UI, not buried in settings
+- **Retry / stop affordances** — always reachable during generation
+- **Draft preservation** — unsent messages survive navigation
 
 ## Preferred Skills
 - `/workflow frontend-feature` for new features
 - `/design-an-interface` for component design
 - `/review` with UX and a11y focus
 - `/tdd` for component and integration tests
+- *(future)* impeccable-style audits — `/typeset`, `/colorize`, `/animate`, `/layout`, `/harden`
 
 ## Code Review Priorities
 1. Accessibility (WCAG 2.1 AA minimum)
@@ -18,9 +54,16 @@
 3. State management simplicity
 4. Performance (Core Web Vitals)
 5. Responsive behavior across breakpoints
+6. Typographic rigor (scale, OpenType, line-height, measure)
+7. Motion purpose (easing intent, reduced-motion respect)
+8. Copy clarity (labels, error messages, empty states)
 
 ## Stack Assumptions
 - Component-based architecture (React, Vue, or similar)
-- Design tokens / CSS variables for theming
+- Design tokens / CSS variables for theming (OKLCH recommended)
 - Prefer server components where possible
 - Images: always lazy-load, always provide dimensions
+
+## References
+- [pbakaus/impeccable](https://github.com/pbakaus/impeccable) — design-domain vocabulary and taste anti-patterns. Adopted here as **guidance**, not mandate.
+- [21st.dev](https://21st.dev) — pattern library that inspires the AI-Native UI Patterns section.