arkaos 3.76.0 → 3.78.0

package/VERSION

@@ -1 +1 @@
-3.76.0
+3.78.0

package/arka/skills/flow/SKILL.md

@@ -81,6 +81,20 @@ spec why divergence is justified. Manual audit:
 Dispatch specialists via the `Agent` tool. The squad lead from Phase 3
 names them. Specialists run in parallel when work is independent.
 
+**Design-system check on UI work (PR6 v3.77.0, SHOULD `design-system-locked`).**
+Before dispatching frontend/landing specialists, run the per-project
+linter to surface UI/UX drift:
+
+```
+python -m core.governance.design_system_lint_cli <project_path>
+```
+
+If the project has a `design-system.yaml`, violations come back with
+file:line + the suggestion text declared in the YAML. The frontend
+specialist should fix existing violations OR document why the new work
+diverges. Projects without a `design-system.yaml` skip the check.
+Template: `docs/examples/design-system-example.yaml`.
+
 **Experience injection (PR3 v3.74.0).** When a specialist is dispatched,
 Synapse layer `L2.6 AgentExperiences`
 (`core/synapse/agent_experiences_layer.py`) detects the

package/config/constitution.yaml

@@ -217,6 +217,11 @@ enforcement_levels:
         rule: "Bottom-line first output. Lead with answer, then why, then how. Confidence tags on assessments."
         enforcement: "See config/standards/communication.md for full standard"
 
+      # ─── Rule added in PR6 Squad Intelligence Upgrade (2026-05-28) ───────
+      - id: design-system-locked
+        rule: "Each project SHOULD declare a `design-system.yaml` at its root listing tokens (colors, spacing, fonts), allowed_components, file_globs to scan, and forbidden_patterns with suggestions. The per-project linter (core.governance.design_system_lint) detects UI/UX drift — hex literals outside the palette, inline style attributes, raw HTML where a Nuxt UI component exists, etc. Adoption is opt-in per project (no YAML at project root → no violations). v3.77.0 is advisory-only; pre-commit hook integration lands in v3.77.x once the rule sets stabilise across the operator's projects."
+        enforcement: "Run via `python -m core.governance.design_system_lint_cli <project_path>` (text or JSON output, optional --exit-on-violations). Example template at `docs/examples/design-system-example.yaml`."
+
       # ─── Rule added in PR5 Squad Intelligence Upgrade (2026-05-28) ───────
       - id: dna-fidelity-warn
         rule: "Agent outputs are compared against the `signature_markers` block in each agent's YAML at the end of every turn. Forbidden patterns (avoid_patterns) and missing opening phrases (opening_phrases) generate FidelityViolation records in ~/.arkaos/telemetry/dna-fidelity.jsonl. v3.76.0 is soft-warn — violations are recorded for telemetry and operator review, not blocked. Hard-block mode lands later once the marker set is calibrated against real production usage."

package/core/governance/design_system_lint.py

@@ -0,0 +1,197 @@
+"""Design System Linter — PR6 Squad Intelligence Upgrade v3.77.0.
+
+Scans a project for forbidden patterns declared in its design-system.yaml.
+Opt-in per project: no YAML at root means no violations. Advisory-only in
+v3.77.0; pre-commit hook integration lands in v3.77.x.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field  # noqa: F401 (asdict kept for callers)
+from pathlib import Path
+from typing import Iterator
+
+import yaml
+
+
+# ─── Dataclasses ──────────────────────────────────────────────────────────────
+
+@dataclass
+class DesignSystem:
+    """Loaded design-system.yaml for a project."""
+
+    version: int = 1
+    project: str = ""
+    tokens: dict = field(default_factory=dict)
+    allowed_components: list[str] = field(default_factory=list)
+    file_globs: list[str] = field(default_factory=list)
+    forbidden_patterns: list[dict] = field(default_factory=list)
+
+
+@dataclass
+class DesignViolation:
+    file: str         # relative to project_path, forward slashes
+    line: int         # 1-indexed
+    pattern: str      # the regex string from forbidden_patterns
+    suggestion: str   # suggestion text from forbidden_patterns
+    matched_text: str  # the actual matched substring (cap 200 chars)
+
+
+# ─── Internal helpers ─────────────────────────────────────────────────────────
+
+def _default_file_globs() -> list[str]:
+    return ["**/*.vue", "**/*.tsx", "**/*.jsx"]
+
+
+def _escape_glob_literal(s: str) -> str:
+    """Escape a literal glob segment (no ** inside)."""
+    return re.escape(s).replace(r"\*", "[^/]*").replace(r"\?", "[^/]")
+
+
+def _glob_to_regex(glob_pattern: str) -> re.Pattern[str]:
+    """Translate a glob pattern (with ** support) to a compiled regex.
+
+    Gitignore convention: ``**/`` = zero-or-more ``dir/`` prefixes (including
+    zero), so ``**/*.vue`` matches both ``App.vue`` and ``src/App.vue``.
+    Bare ``*`` = any non-slash run; ``?`` = one non-slash char.
+    """
+    # Split on ** tokens, keeping them as delimiters.
+    tokens = re.split(r"(\*\*)", glob_pattern)
+    result = ""
+    for i, tok in enumerate(tokens):
+        if tok != "**":
+            result += _escape_glob_literal(tok)
+            continue
+        nxt = tokens[i + 1] if i + 1 < len(tokens) else ""
+        if nxt.startswith("/"):
+            # **/ → consume the slash, emit zero-or-more dir/ groups.
+            tokens[i + 1] = nxt[1:]
+            result += "(?:[^/]+/)*"
+        else:
+            # trailing ** or ** not followed by / → match any remaining path.
+            result += ".*"
+    return re.compile(f"^{result}$")
+
+
+def _glob_match(pattern: str, rel_path: str) -> bool:
+    """Return True when rel_path (forward slashes) matches the glob pattern."""
+    try:
+        return bool(_glob_to_regex(pattern).match(rel_path))
+    except re.error:
+        return False
+
+
+def _iter_matching_files(
+    project_path: Path, file_globs: list[str]
+) -> Iterator[Path]:
+    """Yield all files under project_path matching any glob in file_globs."""
+    seen: set[Path] = set()
+    for glob in file_globs:
+        for path in project_path.rglob("*"):
+            if not path.is_file():
+                continue
+            rel = path.relative_to(project_path).as_posix()
+            if _glob_match(glob, rel) and path not in seen:
+                seen.add(path)
+                yield path
+
+
+def _is_excluded(rel_path: str, exclude_paths: list[str]) -> bool:
+    """Return True if rel_path matches any exclude_paths glob or is design-system.yaml."""
+    if rel_path == "design-system.yaml":
+        return True
+    return any(_glob_match(exc, rel_path) for exc in exclude_paths)
+
+
+def _scan_file_for_pattern(
+    file_path: Path,
+    project_path: Path,
+    compiled_re: re.Pattern[str],
+    pattern: str,
+    suggestion: str,
+) -> Iterator[DesignViolation]:
+    """Read one file and yield a DesignViolation for every regex match."""
+    rel = file_path.relative_to(project_path).as_posix()
+    try:
+        text = file_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        for match in compiled_re.finditer(line):
+            yield DesignViolation(
+                file=rel,
+                line=lineno,
+                pattern=pattern,
+                suggestion=suggestion,
+                matched_text=match.group(0)[:200],
+            )
+
+
+# ─── Public API ───────────────────────────────────────────────────────────────
+
+def load_design_system(project_path: Path) -> DesignSystem | None:
+    """Load design-system.yaml from project_path root.
+
+    Returns None when the file is absent or malformed.
+    """
+    yaml_path = project_path / "design-system.yaml"
+    if not yaml_path.is_file():
+        return None
+    try:
+        raw = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    return DesignSystem(
+        version=int(raw.get("version") or 1),
+        project=str(raw.get("project") or ""),
+        tokens=dict(raw.get("tokens") or {}),
+        allowed_components=list(raw.get("allowed_components") or []),
+        file_globs=list(raw.get("file_globs") or []),
+        forbidden_patterns=list(raw.get("forbidden_patterns") or []),
+    )
+
+
+def lint_project(project_path: Path) -> list[DesignViolation]:
+    """Scan project_path for design-system violations.
+
+    Returns an empty list when the project path does not exist, has no
+    design-system.yaml, or the YAML is malformed.
+    """
+    if not project_path.is_dir():
+        return []
+    ds = load_design_system(project_path)
+    if ds is None:
+        return []
+    globs = ds.file_globs if ds.file_globs else _default_file_globs()
+    violations: list[DesignViolation] = []
+    for fp_dict in ds.forbidden_patterns:
+        if not isinstance(fp_dict, dict):
+            continue
+        _collect_pattern_violations(project_path, globs, fp_dict, violations)
+    return violations
+
+
+def _collect_pattern_violations(
+    project_path: Path,
+    file_globs: list[str],
+    fp_dict: dict,
+    violations: list[DesignViolation],
+) -> None:
+    """Compile one forbidden pattern and append matching violations in-place."""
+    raw_pattern = fp_dict.get("pattern", "")
+    suggestion = fp_dict.get("suggestion", "")
+    exclude_paths: list[str] = list(fp_dict.get("exclude_paths") or [])
+    try:
+        compiled = re.compile(raw_pattern)
+    except re.error:
+        return
+    for file_path in _iter_matching_files(project_path, file_globs):
+        rel = file_path.relative_to(project_path).as_posix()
+        if _is_excluded(rel, exclude_paths):
+            continue
+        violations.extend(
+            _scan_file_for_pattern(file_path, project_path, compiled, raw_pattern, suggestion)
+        )

package/core/governance/design_system_lint_cli.py

@@ -0,0 +1,92 @@
+"""CLI for the Design System Linter (PR6 Squad Intelligence Upgrade v3.77.0).
+
+Usage:
+    python -m core.governance.design_system_lint_cli <project_path> [--format text|json] [--exit-on-violations]
+
+Examples:
+    python -m core.governance.design_system_lint_cli /path/to/project
+    python -m core.governance.design_system_lint_cli /path/to/project --format json --exit-on-violations
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+from core.governance.design_system_lint import (
+    DesignViolation,
+    lint_project,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.governance.design_system_lint_cli",
+        description="Scan a project for design-system violations.",
+    )
+    parser.add_argument("project_path", help="Path to the project root containing design-system.yaml.")
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text).",
+    )
+    parser.add_argument(
+        "--exit-on-violations",
+        action="store_true",
+        help="Exit with code 1 when violations are found.",
+    )
+    return parser
+
+
+def _print_text(violations: list[DesignViolation]) -> None:
+    """Group violations by file, sorted by file then line, and pretty-print."""
+    print(f"{len(violations)} design-system violation(s) found:")
+    by_file: dict[str, list[DesignViolation]] = defaultdict(list)
+    for v in violations:
+        by_file[v.file].append(v)
+    for file in sorted(by_file):
+        for v in sorted(by_file[file], key=lambda x: x.line):
+            truncated = v.matched_text[:60] + ("..." if len(v.matched_text) > 60 else "")
+            print(f"  {v.file}:{v.line}  {truncated}")
+            print(f"    → {v.suggestion}")
+
+
+def _print_json(violations: list[DesignViolation]) -> None:
+    """Emit one JSON line per violation followed by a summary line (jsonl)."""
+    for v in violations:
+        print(json.dumps({
+            "file": v.file,
+            "line": v.line,
+            "pattern": v.pattern,
+            "suggestion": v.suggestion,
+            "matched_text": v.matched_text,
+        }))
+    print(json.dumps({"summary": True, "count": len(violations)}))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+    violations = lint_project(Path(args.project_path))
+
+    if not violations:
+        if args.format == "json":
+            print(json.dumps({"violations": [], "count": 0}))
+        else:
+            print("No design-system violations.")
+        return 0
+
+    if args.format == "json":
+        _print_json(violations)
+    else:
+        _print_text(violations)
+
+    return 1 if args.exit_on_violations else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/departments/brand/agents/brand-director.yaml

@@ -36,6 +36,8 @@ mental_models:
     - "StoryBrand SB7 (Miller)"
     - "Positioning (Ries/Trout)"
     - "Design Thinking (IDEO)"
+    - "KB-first (Obsidian canonical source)"
+    - "UI/UX validation gate (squad direction before implementation)"
 
 authority:
   orchestrate: true

package/departments/brand/agents/creative-director.md

@@ -62,6 +62,10 @@ You are Valentina, the Creative Director at WizardingCode. 15 years bridging bra
 
 **ALWAYS read** `departments/brand/references/brand-creation-guide.md` before starting any brand project. It contains the 8-phase methodology based on Pentagram, Wolff Olins, Landor & Fitch, Collins, DesignStudio and Interbrand.
 
+**For UI/UX work, ALSO read** `departments/brand/references/uiux-knowledge-and-tools.md`. You are the validation gate for the UI/UX squad: Sofia D. (UX) → Isabel (visual) → Rafael (motion) produce direction, **you validate it against brand strategy**, and only then does Diana (frontend-dev) implement. Nothing reaches implementation without your validated direction.
+
+**KB-first (NON-NEGOTIABLE):** the Obsidian KB is the canonical primary source for the whole squad. Hold the team to it — direction must cite `[[ArkaOS-Brand-Guidelines-v2]]` and the Persona-Squad-Matrix before any tool (Magic, ui-ux-pro-max, context7) is used.
+
 ## The 8-Phase Brand Process
 
 You orchestrate ALL 8 phases. The brand starts from the BASE (strategy), not the top (visuals).

package/departments/brand/agents/motion-designer.md

@@ -60,7 +60,11 @@ You are Rafael, the Motion Designer at WizardingCode. You bring brands to life t
 
 **Read** `departments/brand/references/brand-creation-guide.md` Phase 5.5 (Motion & Animation) and Phase 6 (Applications). You own motion execution in Phase 5-6.
 
-**Critical rule:** Motion must match the brand's archetype and personality. A Ruler brand (Rolex) moves slowly and deliberately. A Jester brand (Old Spice) moves fast and unexpectedly. Your motion principles come from the strategy, not from trends.
+**For UI/product motion, ALSO read** `departments/brand/references/uiux-knowledge-and-tools.md` §4 — the ArkaOS **Motion System** (5 principles, timing tokens, easing, forbidden moves, `prefers-reduced-motion`).
+
+**KB-first (NON-NEGOTIABLE):** the Obsidian KB is the canonical primary source. Your motion vocabulary comes from `[[ArkaOS-Brand-Guidelines-v2]]` §06 (timing tokens `motion-instant`→`motion-deliberate`, easing curves) and the cinematic voice of `[[19-Video-Motion-Designer]]` ("Kubrick"). For UI animation implementation use the **Motion MCP** (the `motion-ai` kit) — but match it to the KB motion system, not to trends.
+
+**Critical rule:** Motion must match the brand's archetype and personality. A Ruler brand (Rolex) moves slowly and deliberately. A Jester brand (Old Spice) moves fast and unexpectedly. Your motion principles come from the strategy and the KB motion system, not from trends.
 
 ## How You Work
 

package/departments/brand/agents/ux-designer.yaml

@@ -27,6 +27,15 @@ behavioral_dna:
   mbti:
     type: INFJ
 
+mental_models:
+  primary:
+    - "Nielsen 10 Heuristics"
+    - "Laws of UX (Yablonski)"
+    - "Double Diamond"
+  secondary:
+    - "KB-first (Obsidian canonical source)"
+    - "Two-Part Conversion Formula (offer × process)"
+
 authority:
   delegates_to: []
   escalates_to: brand-director-valentina
@@ -48,6 +57,8 @@ expertise:
     - Atomic Design
     - WCAG 2.1 AA
     - Garrett's 5 Planes
+    - Two-Part Conversion Formula
+    - Microinteractions (trigger-rules-feedback-loops)
   depth: expert
   years_equivalent: 8
 

package/departments/brand/agents/visual-designer.md

@@ -60,6 +60,10 @@ You are Isabel, the Visual Designer at WizardingCode. You turn creative briefs i
 
 **ALWAYS read** `departments/brand/references/brand-creation-guide.md` Phase 5 (Visual Identity) before starting visual work. You own Phase 5 execution and co-own Phase 6 (Applications).
 
+**For product UI/UX work, ALSO read** `departments/brand/references/uiux-knowledge-and-tools.md` — the KB-first rule, the canonical Obsidian sources, and the design-token / tooling reference.
+
+**KB-first (NON-NEGOTIABLE):** the Obsidian KB is the canonical primary source. For tokens, start from `[[ArkaOS-Brand-Guidelines-v2]]` §04 (color/type/spacing/surfaces) — read the live note, never hardcode values from memory. Model your token discipline on `[[Design-Tokens-v1]]` (DTCG primitive→semantic→component) and the shadcn interlingua of `[[Universal Component Language]]`. Supplement with Magic / context7 only after the KB.
+
 **Critical rule:** Never start visual work without the strategic foundation from Phases 1-4. Every visual decision must trace back to strategy. If it can't, it's decoration, not branding.
 
 ## How You Work

package/departments/brand/agents/visual-designer.yaml

@@ -27,6 +27,15 @@ behavioral_dna:
   mbti:
     type: ISFP
 
+mental_models:
+  primary:
+    - "Dieter Rams — less but better"
+    - "Design Tokens (DTCG primitive→semantic→component)"
+    - "Atomic Design (visual layer)"
+  secondary:
+    - "KB-first (Obsidian canonical source)"
+    - "Universal Component Language (shadcn interlingua)"
+
 authority:
   delegates_to: []
   escalates_to: brand-director-valentina
@@ -46,6 +55,8 @@ expertise:
     - Color Theory
     - Typography Hierarchy
     - Brand Identity Process (Wheeler)
+    - ArkaOS Design Tokens
+    - WCAG AA contrast
   depth: expert
   years_equivalent: 8
 

package/departments/brand/references/uiux-knowledge-and-tools.md

@@ -0,0 +1,136 @@
+# UI/UX Knowledge & Tools — Squad Reference
+
+> Shared reference for the frontend UI/UX squad: **Diana** (frontend-dev),
+> **Sofia D.** (ux-designer), **Isabel** (visual-designer), **Rafael**
+> (motion-designer) and **Valentina** (creative-director).
+>
+> Read this BEFORE any UI/UX work. It defines the non-negotiable KB-first
+> rule, the canonical knowledge sources, the concrete design tokens, the
+> motion system, the new tooling, and the squad validation order.
+
+---
+
+## 1. KB-First (NON-NEGOTIABLE)
+
+**The Obsidian knowledge base is the canonical, primary source for every
+agent and every team.** New tools (Magic, Motion, ui-ux-pro-max, context7,
+nuxt-ui) are **supplements** — they never replace the vault.
+
+Order of operations on ANY UI/UX task:
+
+1. **Search the Obsidian KB first** (`mcp__obsidian__search_notes` /
+   `read_note`). Start from the canonical sources in §2.
+2. **Cite what you found** with `[[wikilinks]]`, or explicitly declare a
+   KB gap if nothing relevant exists.
+3. **Only then** supplement with the tools in §5 for theory the vault
+   lacks (see §7).
+4. When external research produces something material, **write it back to
+   the KB** so the vault gets richer over time.
+
+This mirrors the Synapse L2.5 pre-injection and the `kb-first` constitution
+rule. Operator directive (2026-05-30): *"a prioridade é sempre a base de
+conhecimento que temos no Obsidian — para qualquer agent ou equipa."*
+
+---
+
+## 2. Canonical KB Sources
+
+| Source (Obsidian) | What it gives you |
+|---|---|
+| `[[ArkaOS-Brand-Guidelines-v2]]` | **Primary.** Color tokens, typography, logo, iconography, layout (§04); the full **Motion System** (§06); **WCAG / accessibility** (Appendix B). Concrete, ready-to-code values. |
+| `[[Area 02 - Design]]` | Framework index: Nielsen, Laws of UX (Yablonski), Krug, Garrett's 5 Planes, Cooper, Norman, Double Diamond, Design Sprint. Names the bodies of theory (see §7 for depth gaps). |
+| `[[ArkaOS-Persona-Squad-Matrix]]` | Persona × framework × squad mapping (NN/g for Francisca; Two-Part Conversion Formula; archetypes for Valentina). |
+| `[[Universal Component Language]]` | Alani Nicolas: 39 design systems → shadcn interlingua; token-extraction pipeline (OKLCH normalization → WCAG audit → Atomic Design). |
+| `[[Design-Tokens-v1]]` (Hringr) | DTCG token architecture: primitive → semantic → component. Reference model for token discipline. |
+| `[[19-Video-Motion-Designer]]` ("Kubrick") | Cinematic motion/video persona — base voice for Rafael's video work. |
+
+---
+
+## 3. Design Tokens — Quick Reference
+
+From `[[ArkaOS-Brand-Guidelines-v2]]` §04 (verify against the note before use):
+
+- **Composition ratio 60 / 25 / 15** — canvas / content / signal (accent
+  green 10–15% max).
+- **Spacing** base 4px scale: `space-1`=4px … `space-24`=96px.
+- **Type**: never body < 16px; line-height 1.5–1.6× body, 1.1–1.2× display;
+  max line length ~75 chars; max 2 families + mono for code.
+- **Surface hierarchy**: 5 layers (0→4), 1px edge border mandatory.
+- **Radius** scale 4px → full; **grid** 12-column, max content 1280px.
+- **Icons**: stroke 1.5px, 24×24 grid, optical alignment.
+
+> Always read the live note for the exact HEX/token names — do not
+> hardcode values from memory.
+
+---
+
+## 4. Motion System
+
+From `[[ArkaOS-Brand-Guidelines-v2]]` §06. **5 principles** (inject verbatim):
+
+1. **Purposeful** — every animation answers "what does it communicate?"; if nothing, remove it.
+2. **Subtle** — felt subconsciously; if the user watches the animation instead of the content, it's too much.
+3. **Precise** — intentional easing, exact timing.
+4. **Fast** — CLI-first product; default to the fastest option.
+5. **Consistent** — same action → same animation everywhere.
+
+**Timing tokens**: `motion-instant` 100ms · `motion-fast` 150ms (default) ·
+`motion-normal` 300ms · `motion-slow` 500ms · `motion-deliberate` 800ms.
+**Easing**: `--ease-out` cubic-bezier(0.25,0,0,1); `--ease-spring`
+cubic-bezier(0.16,1,0.3,1).
+
+**Forbidden**: rotation/spin, bounce/elastic on the logo, 3D/perspective,
+particles, morphing, color-cycling.
+
+**Accessibility**: always honour `prefers-reduced-motion`.
+
+---
+
+## 5. Tools (supplement only — after KB)
+
+| Tool | Type | Use for | Notes |
+|---|---|---|---|
+| **Magic** (`@21st-dev/magic`) | MCP (user scope) | Generate production UI components from natural language, framework-aware (Nuxt UI, Tailwind, shadcn) | Preferred path for frontend UI/UX — mandatory when configured. Wired into nuxt/vue/react/nextjs/full-stack MCP profiles. Needs `MAGIC_API_KEY` (falls back gracefully when absent). |
+| **Motion** (`motion-ai` kit) | MCP + skills | Animation/motion implementation (Motion library) | Auto-installed on install/update. Pair with the §4 motion system. |
+| **ui-ux-pro-max** | Claude plugin | UI/UX methodology + patterns, conjugated with whatever framework is in use | Marketplace `nextlevelbuilder/ui-ux-pro-max-skill`. Use to fill the §7 theory gaps. |
+| **nuxt-ui** / **context7** | MCP | Up-to-date framework + component docs | Use for current API/usage instead of memory. |
+| **playwright** | MCP | Verify the UI in a real browser before claiming done | Constitution: test before claim. |
+
+Framework-agnostic rule: detect the project's framework first (Nuxt UI,
+Tailwind, shadcn, …) and conjugate Magic + ui-ux-pro-max to THAT framework.
+
+---
+
+## 6. Squad Validation Order (NON-NEGOTIABLE)
+
+**Diana (frontend-dev) implements UI ONLY after the UI/UX design agents
+have analysed and their output is validated.** No interface freelancing.
+
+```
+1. Sofia D. (ux-designer)      → UX analysis: flows, IA, heuristics, accessibility
+2. Isabel (visual-designer)    → visual direction: tokens, hierarchy, components
+3. Rafael (motion-designer)    → motion/interaction direction (where relevant)
+4. Valentina (creative-director) → validates direction against brand strategy
+   ───────────────────────────────────────────────────────────────────────
+5. Diana (frontend-dev)        → implements the VALIDATED design with Magic +
+                                  the project framework, then QA + Quality Gate
+```
+
+Operator directive (2026-05-30): *"o frontend developer só faz alguma coisa
+com validação e sempre depois da análise dos outros agentes de UI/UX."*
+
+---
+
+## 7. Theory Gaps (KB-thin → supplement, then write back)
+
+The KB is rich in **applied** knowledge (tokens, motion, WCAG application)
+but thin on **theory**. For these, consult ui-ux-pro-max + context7, then
+write material findings back to `[[Area 02 - Design]]`:
+
+- Nielsen's 10 heuristics in detail
+- Laws of UX (each law)
+- Dieter Rams' 10 principles
+- Atomic Design (full atoms→pages)
+- Microinteractions (trigger→rules→feedback→loops/modes)
+- Color theory & typography science (OKLCH, harmony, modular scale)
+- Gestalt & visual hierarchy (F/Z scanning, proximity, contrast)

package/departments/dev/agents/frontend-dev.md

@@ -54,15 +54,43 @@ You are Diana, the Senior Frontend Developer at WizardingCode. 8 years building
 - **With higher-tier (Marco, Paulo, Gabriel):** Advocates for UX within architectural constraints. Adapts creatively.
 - **With same/lower-tier:** Collaborative. Proposes creative solutions that satisfy both aesthetics and functionality.
 
+## Core Reference — UI/UX Knowledge, Tools & Validation Gate
+
+**ALWAYS read** `departments/brand/references/uiux-knowledge-and-tools.md`
+before any UI work. It defines the KB-first rule, the canonical Obsidian
+sources, the design tokens, the motion system, and the tooling.
+
+**KB-first (NON-NEGOTIABLE):** the Obsidian KB is the canonical primary
+source. Search it first (`[[ArkaOS-Brand-Guidelines-v2]]` for tokens/motion/
+WCAG), cite, then supplement with Magic / Motion / ui-ux-pro-max / context7.
+
+**Validation Gate (NON-NEGOTIABLE):** you implement UI **only after** the
+UI/UX design agents have analysed AND their direction is validated. No
+interface freelancing. The order is:
+
+```
+Sofia D. (UX analysis) → Isabel (visual) → Rafael (motion)
+  → Valentina (validates vs brand strategy) → THEN Diana implements
+```
+
+If you are handed a UI task without that validated design input, stop and
+request it from the UI/UX squad before writing code.
+
+**Magic MCP:** for new components, generate framework-aware scaffolds with
+the Magic MCP (21st.dev), conjugated to the project's framework (Nuxt UI /
+Tailwind / shadcn), then refine to the validated design and the KB tokens.
+
 ## How You Work
 
 1. ALWAYS verify you are on a feature branch before writing code. If on main/master/dev, create a feature branch first.
-2. Read project context (CLAUDE.md / PROJECT.md)
-3. Read Gabriel's architecture design (component hierarchy, state management plan)
-4. Find 2-3 similar existing components and match their patterns exactly
-5. Implement: Composable/Hook → Component → Page → Route
-6. Handle ALL states: loading, error, empty, success
-7. Test components with Vitest + Vue Test Utils or React Testing Library
+2. **Confirm the validated UI/UX design exists** (Sofia D. + Isabel + Rafael, approved by Valentina). No validated design → request it, do not freelance.
+3. Read project context (CLAUDE.md / PROJECT.md)
+4. Read the architecture design (component hierarchy, state management plan)
+5. Search the Obsidian KB for the relevant tokens/patterns; cite them
+6. Find 2-3 similar existing components and match their patterns exactly
+7. Implement with Magic MCP + the project framework: Composable/Hook → Component → Page → Route
+8. Handle ALL states: loading, error, empty, success
+9. Test components with Vitest + Vue Test Utils or React Testing Library; verify in-browser with Playwright
 
 ## Vue 3 / Nuxt 3 Patterns
 
@@ -202,11 +230,13 @@ Every component must have:
 
 ## Before Writing ANY Code
 
-1. Read Gabriel's component hierarchy and state management plan
-2. Read the project's CLAUDE.md/PROJECT.md
-3. Find 2-3 similar existing components and match their patterns
-4. Use Context7 MCP if unsure about framework API
-5. Never guess — always verify
+1. Confirm the validated UI/UX design (Sofia D. + Isabel + Rafael, approved by Valentina). No validated design → request it, do not freelance.
+2. Read Gabriel's component hierarchy and state management plan
+3. Read the project's CLAUDE.md/PROJECT.md
+4. Search the Obsidian KB first for tokens/patterns; cite them
+5. Find 2-3 similar existing components and match their patterns
+6. Use the Magic MCP for scaffolds and Context7/nuxt-ui MCP if unsure about framework API
+7. Never guess — always verify
 
 ## Memory
 

package/departments/dev/agents/frontend-dev.yaml

@@ -36,6 +36,8 @@ mental_models:
     - "Laws of UX (Yablonski)"
     - "WCAG Accessibility"
     - "Component-Driven Development"
+    - "Design-system-as-context (Universal Component Language)"
+    - "KB-first (Obsidian canonical source)"
 
 authority:
   push_code: true
@@ -52,12 +54,16 @@ expertise:
     - Design system implementation
     - Accessibility (WCAG 2.1 AA)
     - Core Web Vitals
+    - Magic MCP (21st.dev) component generation
+    - Motion (animation implementation)
   frameworks:
     - Atomic Design
     - Component-Driven Development
     - Laws of UX
     - Nielsen Heuristics
     - CWV Optimization
+    - ArkaOS Motion System
+    - Design Tokens (DTCG)
   depth: expert
   years_equivalent: 9
 

package/installer/claude-plugins.js

@@ -16,10 +16,18 @@ import { execSync, spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+// Third-party marketplaces that must be registered (via
+// `claude plugin marketplace add <repo>`) before their plugins can be
+// installed. Each entry is a GitHub `owner/repo` shorthand.
+export const DEFAULT_CLAUDE_MARKETPLACES = [
+  "nextlevelbuilder/ui-ux-pro-max-skill",
+];
+
 // Each entry is "name@marketplace" matching the `claude plugin install`
 // CLI argument format.
 export const DEFAULT_CLAUDE_PLUGINS = [
   "frontend-design@claude-plugins-official",
+  "ui-ux-pro-max@ui-ux-pro-max-skill",
 ];
 
 const _INSTALLED_REGISTRY = join(
@@ -29,19 +37,40 @@ const _INSTALLED_REGISTRY = join(
 export function installDefaultClaudePlugins({
   runtime = "claude-code",
   plugins = DEFAULT_CLAUDE_PLUGINS,
+  marketplaces = DEFAULT_CLAUDE_MARKETPLACES,
   home = homedir(),
 } = {}) {
   if (runtime !== "claude-code") {
-    return { skipped: "runtime-not-claude-code", results: [] };
+    return { skipped: "runtime-not-claude-code", results: [], marketplaces: [] };
   }
   if (!isClaudeCliAvailable()) {
-    return { skipped: "claude-cli-not-found", results: [] };
+    return { skipped: "claude-cli-not-found", results: [], marketplaces: [] };
   }
+  // Marketplaces must be registered before their plugins can resolve.
+  const marketplaceResults = marketplaces.map((m) => addMarketplace(m));
   const alreadyInstalled = readInstalledRegistry(home);
   const results = plugins.map((p) =>
     installOne(p, alreadyInstalled),
   );
-  return { skipped: null, results };
+  return { skipped: null, results, marketplaces: marketplaceResults };
+}
+
+// Register a third-party plugin marketplace. Idempotent and never-throws:
+// a marketplace that is already known is reported as already-present.
+function addMarketplace(marketplace) {
+  const out = spawnSync("claude", ["plugin", "marketplace", "add", marketplace], {
+    timeout: 60_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  });
+  if (out.status === 0) {
+    return { marketplace, action: "added" };
+  }
+  const msg = (out.stderr || out.error?.message || "").toLowerCase();
+  if (msg.includes("already") || msg.includes("exists")) {
+    return { marketplace, action: "already-present" };
+  }
+  return { marketplace, action: "failed", reason: msg.trim().slice(0, 200) };
 }
 
 function isClaudeCliAvailable() {

package/installer/doctor.js

@@ -195,6 +195,21 @@ const checks = [
     },
     fix: () => "Upgrade Claude Code: npm install -g @anthropic-ai/claude-code@latest",
   },
+  {
+    name: "magic-api-key",
+    description: "Magic API key configured (frontend UI/UX — Magic MCP)",
+    severity: "warn",
+    check: () => {
+      if (process.env.MAGIC_API_KEY) return true;
+      const keysPath = join(INSTALL_DIR, "keys.json");
+      if (!existsSync(keysPath)) return false;
+      try {
+        const keys = JSON.parse(readFileSync(keysPath, "utf-8"));
+        return !!keys.MAGIC_API_KEY;
+      } catch { return false; }
+    },
+    fix: () => "Run: npx arkaos keys set MAGIC_API_KEY <your-21st-dev-key>  (or re-run npx arkaos@latest update)",
+  },
 ];
 
 // ─── Windows-only checks ───────────────────────────────────────────────

package/installer/frontend-tooling.js

@@ -0,0 +1,150 @@
+// Frontend UI/UX tooling setup for `npx arkaos install` and
+// `npx arkaos@latest update`.
+//
+// Wires three operator-mandated tools into the install/update flow:
+//   1. Magic MCP (@21st-dev/magic) — user-scope, API-key gated. The key is
+//      prompted interactively when missing and never stored in the repo;
+//      it lives only in ~/.arkaos/keys.json (chmod 600) + Claude user config.
+//   2. Motion AI Kit (npx motion-ai) — auto-run on every install/update.
+//   3. (ui-ux-pro-max plugin + marketplace is handled in claude-plugins.js.)
+//
+// Invariants (.claude/rules/node-installer.md):
+//   - ESM, os.homedir()/path.join only, never hardcoded paths.
+//   - No interactive prompts during headless/CI runs (guarded by isTTY).
+//   - Never throws — every failure is logged and swallowed so the installer
+//     never breaks on optional tooling.
+
+import { existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { execSync, spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const MAGIC_ENV = "MAGIC_API_KEY";
+
+function keysPath(home) {
+  return join(home, ".arkaos", "keys.json");
+}
+
+function loadKeys(home) {
+  const path = keysPath(home);
+  if (!existsSync(path)) return {};
+  try { return JSON.parse(readFileSync(path, "utf-8")); } catch { return {}; }
+}
+
+function saveKey(home, name, value) {
+  const path = keysPath(home);
+  const keys = loadKeys(home);
+  keys[name] = value;
+  writeFileSync(path, JSON.stringify(keys, null, 2));
+  try { chmodSync(path, 0o600); } catch {}
+}
+
+// Resolve the Magic API key from (in order) keys.json, then the environment.
+function resolveMagicKey(home) {
+  const keys = loadKeys(home);
+  return keys[MAGIC_ENV] || process.env[MAGIC_ENV] || "";
+}
+
+// Prompt once for the key. Resolves to "" in headless contexts so the
+// installer never blocks on a closed stdin (node-installer rule).
+function promptMagicKey() {
+  if (!process.stdin.isTTY) return Promise.resolve("");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const q = "  21st.dev Magic API key (frontend UI/UX, leave empty to skip): ";
+  return new Promise((resolve) => {
+    rl.question(q, (answer) => { rl.close(); resolve((answer || "").trim()); });
+  });
+}
+
+// Ensure MAGIC_API_KEY exists, prompting interactively when missing.
+// Returns the resolved key (possibly "").
+export async function ensureMagicApiKey({ home = homedir() } = {}) {
+  const existing = resolveMagicKey(home);
+  if (existing) return existing;
+  const entered = await promptMagicKey();
+  if (entered) {
+    saveKey(home, MAGIC_ENV, entered);
+    console.log("         Magic API key saved to ~/.arkaos/keys.json (chmod 600).");
+  }
+  return entered;
+}
+
+function isClaudeCliAvailable() {
+  try {
+    execSync("claude --version", { stdio: "pipe", timeout: 5000 });
+    return true;
+  } catch { return false; }
+}
+
+function isMagicMcpRegistered() {
+  const out = spawnSync("claude", ["mcp", "list"], {
+    timeout: 10_000, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8",
+  });
+  return out.status === 0 && /(^|\s)magic(\s|:)/.test(out.stdout || "");
+}
+
+// Register the Magic MCP at Claude Code user scope. Idempotent and
+// never-throws. Skips on non-Claude runtimes, missing CLI, or missing key.
+export function registerMagicMcp({ runtime = "claude-code", apiKey = "" } = {}) {
+  if (runtime !== "claude-code") return { action: "skipped", reason: "runtime-not-claude-code" };
+  if (!isClaudeCliAvailable()) return { action: "skipped", reason: "claude-cli-not-found" };
+  if (!apiKey) return { action: "skipped", reason: "no-api-key" };
+  if (isMagicMcpRegistered()) return { action: "already-present" };
+  // NOTE (known limitation): the key is passed as a CLI argument because
+  // `claude mcp add` offers no stdin/file alternative. It is briefly
+  // visible to `ps`/proc while the child runs. It is NEVER written to the
+  // repo or to any log (only stderr is captured into `reason`).
+  const out = spawnSync("claude", [
+    "mcp", "add", "magic", "--scope", "user",
+    "--env", `API_KEY=${apiKey}`,
+    "--", "npx", "-y", "@21st-dev/magic@latest",
+  ], { timeout: 60_000, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+  if (out.error || out.status !== 0) {
+    const reason = (out.stderr || out.error?.message || "unknown").trim().slice(0, 200);
+    return { action: "failed", reason };
+  }
+  return { action: "registered" };
+}
+
+function motionMarkerPath(home) {
+  return join(home, ".arkaos", ".motion-kit-installed");
+}
+
+// Run the Motion AI Kit. Auto-runs (no prompt) per operator decision
+// (2026-05-30), but idempotently: a one-time marker in ~/.arkaos/ means
+// re-runs (e.g. every `npx arkaos update`) skip the 180s kit instead of
+// re-downloading it. Claude-runtime only, requires the claude CLI (the
+// kit installs Motion skills into the Claude agent), never-throws.
+export function installMotionKit({ runtime = "claude-code", home = homedir() } = {}) {
+  if (runtime !== "claude-code") return { action: "skipped", reason: "runtime-not-claude-code" };
+  if (!isClaudeCliAvailable()) return { action: "skipped", reason: "claude-cli-not-found" };
+  if (existsSync(motionMarkerPath(home))) return { action: "already-present" };
+  const out = spawnSync("npx", ["-y", "motion-ai"], {
+    timeout: 180_000, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8",
+  });
+  if (out.error || out.status !== 0) {
+    const reason = (out.stderr || out.error?.message || "unknown").trim().slice(0, 200);
+    return { action: "failed", reason };
+  }
+  try { writeFileSync(motionMarkerPath(home), new Date().toISOString()); } catch {}
+  return { action: "installed" };
+}
+
+// Orchestrate the full frontend tooling setup. Single entry point wired
+// into both installer/index.js and installer/update.js.
+export async function setupFrontendTooling({ runtime = "claude-code", home = homedir() } = {}) {
+  const results = {};
+  try {
+    const apiKey = await ensureMagicApiKey({ home });
+    results.magicMcp = registerMagicMcp({ runtime, apiKey });
+  } catch (err) {
+    results.magicMcp = { action: "failed", reason: err.message };
+  }
+  try {
+    results.motionKit = installMotionKit({ runtime, home });
+  } catch (err) {
+    results.motionKit = { action: "failed", reason: err.message };
+  }
+  return results;
+}

package/installer/index.js

@@ -352,6 +352,13 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
     const { installDefaultClaudePlugins } = await import("./claude-plugins.js");
     const pluginResult = installDefaultClaudePlugins({ runtime });
     if (!pluginResult.skipped) {
+      for (const m of pluginResult.marketplaces || []) {
+        if (m.action === "added") {
+          console.log(`         marketplace ${m.marketplace} added.`);
+        } else if (m.action === "failed") {
+          console.log(`         marketplace ${m.marketplace} failed (${m.reason}).`);
+        }
+      }
       for (const r of pluginResult.results) {
         if (r.action === "installed") {
           console.log(`         ${r.plugin} installed.`);
@@ -366,6 +373,27 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
     console.log(`         Warning: could not install default Claude plugins (${err.message})`);
   }
 
+  // Frontend UI/UX tooling — Magic MCP (user scope, API-key gated) + Motion
+  // AI Kit. Key is prompted when missing (interactive only). Never blocks.
+  try {
+    const { setupFrontendTooling } = await import("./frontend-tooling.js");
+    const ft = await setupFrontendTooling({ runtime });
+    if (ft.magicMcp?.action === "registered") {
+      console.log("         Magic MCP registered (user scope).");
+    } else if (ft.magicMcp?.action === "already-present") {
+      console.log("         Magic MCP already registered (skipped).");
+    } else if (ft.magicMcp?.action === "failed") {
+      console.log(`         Magic MCP registration failed (${ft.magicMcp.reason}).`);
+    }
+    if (ft.motionKit?.action === "installed") {
+      console.log("         Motion AI Kit installed.");
+    } else if (ft.motionKit?.action === "failed") {
+      console.log(`         Motion AI Kit install failed (${ft.motionKit.reason}).`);
+    }
+  } catch (err) {
+    console.log(`         Warning: could not set up frontend tooling (${err.message})`);
+  }
+
   const manifest = {
     version: VERSION,
     runtime,

package/installer/keys.js

@@ -8,6 +8,7 @@ const PROVIDERS = {
   OPENAI_API_KEY: { name: "OpenAI", used_for: "Whisper transcription, embeddings, GPT" },
   GOOGLE_API_KEY: { name: "Google", used_for: "Gemini API, Nano Banana, Google Cloud AI" },
   FAL_API_KEY: { name: "fal.ai", used_for: "Image generation, video generation" },
+  MAGIC_API_KEY: { name: "21st.dev Magic", used_for: "Frontend UI/UX component generation (Magic MCP)" },
 };
 
 function loadKeys() {

package/installer/update.js

@@ -439,6 +439,41 @@ export async function update() {
     console.log("         ✓ Repo path updated (skills alias not present)");
   }
 
+  // ── 7b. Frontend UI/UX tooling + Claude plugins ──
+  // Mirrors installer/index.js: marketplaces + plugins (ui-ux-pro-max,
+  // frontend-design) and Magic MCP + Motion AI Kit. The operator wants
+  // these provisioned on update too, not just fresh install. All steps
+  // are idempotent and never throw; interactive key prompt is skipped
+  // in headless runs.
+  const toolingRuntime = manifest.runtime || "claude-code";
+  try {
+    const { installDefaultClaudePlugins } = await import("./claude-plugins.js");
+    const pluginResult = installDefaultClaudePlugins({ runtime: toolingRuntime });
+    if (!pluginResult.skipped) {
+      for (const m of pluginResult.marketplaces || []) {
+        if (m.action === "added") console.log(`         ✓ marketplace ${m.marketplace} added`);
+        else if (m.action === "failed") console.log(`         ⚠ marketplace ${m.marketplace} failed (${m.reason})`);
+      }
+      for (const r of pluginResult.results) {
+        if (r.action === "installed") console.log(`         ✓ ${r.plugin} installed`);
+        else if (r.action === "failed") console.log(`         ⚠ ${r.plugin} failed (${r.reason})`);
+      }
+    }
+  } catch (err) {
+    console.log(`         ⚠ Could not update Claude plugins (${err.message})`);
+  }
+  try {
+    const { setupFrontendTooling } = await import("./frontend-tooling.js");
+    const ft = await setupFrontendTooling({ runtime: toolingRuntime });
+    if (ft.magicMcp?.action === "registered") console.log("         ✓ Magic MCP registered (user scope)");
+    else if (ft.magicMcp?.action === "already-present") console.log("         ✓ Magic MCP already registered");
+    else if (ft.magicMcp?.action === "failed") console.log(`         ⚠ Magic MCP failed (${ft.magicMcp.reason})`);
+    if (ft.motionKit?.action === "installed") console.log("         ✓ Motion AI Kit installed");
+    else if (ft.motionKit?.action === "failed") console.log(`         ⚠ Motion AI Kit failed (${ft.motionKit.reason})`);
+  } catch (err) {
+    console.log(`         ⚠ Could not set up frontend tooling (${err.message})`);
+  }
+
   // ── 8. Update manifest ──
   console.log("  [8/8] Finalizing...");
   manifest.version = VERSION;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.76.0",
+  "version": "3.78.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "3.76.0"
+version = "3.78.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}