@aria_asi/cli 0.2.40 → 0.2.41

package/skills/aria-cognition/aria-frontend-architect/references/frontend-cookbook.md

@@ -0,0 +1,358 @@
+# Frontend Architect Cookbook — UX Spine, Component Contracts, Performance Patterns
+
+> Loaded by `aria-frontend-architect`. See also: [`../../aria-senior-code-cookbook/references/engineering-cookbook.md`](../../aria-senior-code-cookbook/references/engineering-cookbook.md) (function contracts §7, WCAG §8, CWV §9).
+
+## 1. Core Web Vitals 2025 — performance budgets
+
+**Source:** [Google — Core Web Vitals](https://developers.google.com/search/docs/appearance/core-web-vitals) · [web.dev — Vitals](https://web.dev/articles/vitals)
+
+| Metric | Good | Needs work | Poor | Weight |
+|---|---|---|---|---|
+| **LCP** Largest Contentful Paint | ≤2.5s | 2.5-4.0s | >4.0s | 40% |
+| **INP** Interaction to Next Paint | ≤200ms | 200-500ms | >500ms | 40% |
+| **CLS** Cumulative Layout Shift | ≤0.1 | 0.1-0.25 | >0.25 | 20% |
+
+(INP replaced FID in March 2024.)
+
+### Production budget contract
+Every page surface declares:
+```typescript
+export const performanceBudget = {
+  LCP: { p75_target_ms: 2500, alert_at_ms: 3000 },
+  INP: { p75_target_ms: 200, alert_at_ms: 300 },
+  CLS: { p75_target: 0.1, alert_at: 0.15 },
+  bundle: {
+    initial_js_kb: 200,    // gzipped
+    total_js_kb: 600,
+    css_kb: 50,
+  },
+};
+```
+
+CI fails on budget regression > 10%.
+
+### Optimization priority order (cost-effectiveness)
+1. **Image optimization** (WebP/AVIF, explicit dimensions, fetchpriority) — biggest LCP win, lowest cost
+2. **Eliminate render-blocking resources** — defer non-critical JS, inline critical CSS
+3. **Server-side render the LCP element** — RSC / SSR for the hero
+4. **Preload + preconnect** — `<link rel="preload" fetchpriority="high">` for LCP image; `<link rel="preconnect">` for critical origins
+5. **Code split** — route-level code splitting standard; component-level for heavy widgets
+6. **Web Workers** for INP-killing computation
+7. **CDN** — last because it costs ongoing and the above is free
+
+## 2. RSC / SSR / SPA architecture decision
+
+**Source:** [Developer Way — RSC Performance](https://www.developerway.com/posts/react-server-components-performance) · [iSync Evolution — RSC Practical Guide](https://www.isyncevolution.com/blog/react-server-components)
+
+### The architecture matrix
+
+| Page shape | Best architecture | Why |
+|---|---|---|
+| Marketing / landing (mostly static) | SSG / ISR | Pre-built; CDN; near-zero compute |
+| Product page (dynamic, high LCP value) | RSC + streaming | Server fetches data; HTML streams; perceived perf wins |
+| Dashboard (auth, frequent updates) | RSC + Client Components for interactivity | Server data fetching; client islands for state |
+| Real-time collab (chat, cursors, live updates) | SPA / Client Components | WebSocket / Server-Sent Events; client-managed state |
+| Admin / internal tool | Whatever your team knows | Performance matters less; velocity matters more |
+
+### RSC decision rules
+- **Server Components**: data fetching with credentials; computation; rendering content that doesn't require interaction
+- **Client Components**: anything with `useState`, `useEffect`, browser APIs, event handlers, real-time updates
+- **The boundary**: explicit `"use client"` directive; passes serializable props from server to client
+
+### RSC anti-patterns
+- Wrapping interactive widgets in server components (won't work)
+- Fetching data in client components when server can (loses RSC's data-fetching speed advantage)
+- Treating RSC as "SSR with fewer bugs" — it's structurally different
+
+## 3. State Home Decision (the most common UI bug source)
+
+State has 5 homes. Each piece of state belongs in exactly one. Wrong-home state is the most common source of UI bugs.
+
+| State type | Home | Examples | Library |
+|---|---|---|---|
+| **URL state** | URL search params | filters, sort order, current page, tab | `useSearchParams` (Next), `nuqs`, native |
+| **Server state** | Server, cached client-side | API data, user list, dashboard stats | TanStack Query, SWR, RTK Query |
+| **Form state** | Form library | input values, validation, dirty state | React Hook Form, Formik |
+| **Local UI state** | React component | open/closed, hover, focus, transient | `useState` |
+| **Global app state** | Store | auth user, theme, feature flags | Zustand, Jotai, Redux |
+
+### The diagnostic
+For each piece of state, ask:
+- Does it survive a refresh? → URL or server, not React
+- Does it sync across tabs? → server, not URL or React
+- Does multiple components need it? → store or server, not local
+- Does it mirror server data? → server (with cache), not React state copy
+
+### Anti-pattern: copying server state into useState
+```tsx
+// ❌ The most common stale-data bug
+const [users, setUsers] = useState([]);
+useEffect(() => { fetch('/users').then(r => r.json()).then(setUsers); }, []);
+// Now /users data lives in two places (server + this component); guaranteed to drift
+
+// ✅ Server state in a server-state library
+const { data: users } = useQuery({ queryKey: ['users'], queryFn: () => fetch('/users').then(r => r.json()) });
+// Single source of truth; cache invalidation built-in
+```
+
+## 4. Component Contract — minimum surface, max predictability
+
+```tsx
+// Canonical component contract
+type ButtonProps = {
+  // Required, named explicitly:
+  label: string;
+  onClick: () => void;
+
+  // Variants — closed set, no string-typed:
+  variant?: 'primary' | 'secondary' | 'destructive' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+
+  // States — designed not optional polish:
+  loading?: boolean;
+  disabled?: boolean;
+
+  // Accessibility — explicit:
+  ariaLabel?: string;
+  // Note: NOT extending HTMLButtonAttributes — keep surface minimal
+};
+
+export function Button({ label, onClick, variant = 'primary', size = 'md', loading, disabled, ariaLabel }: ButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled || loading}
+      aria-busy={loading}
+      aria-label={ariaLabel ?? label}
+      data-variant={variant}
+      data-size={size}
+      className={buttonStyles({ variant, size })}
+    >
+      {loading ? <Spinner size={size} /> : label}
+    </button>
+  );
+}
+```
+
+### Component contract rules
+- **Minimum prop surface** — no kitchen-sink components; favor composition
+- **Closed variant sets** — `'primary' | 'secondary'` not `string`
+- **Designed states** — loading / disabled / error are part of the contract, not afterthoughts
+- **Accessibility built-in** — aria attributes default-correct, not user-supplied
+- **`data-*` attributes for testability** — `data-variant`, `data-testid`
+- **No prop drilling beyond 2 levels** — use context or composition
+
+## 5. WCAG 2.2 — accessibility checklist (paste-ready)
+
+**Source:** [W3C — WCAG 2.2](https://www.w3.org/TR/WCAG22/) · See engineering-cookbook §8 for full coverage
+
+```markdown
+## Per-component / per-page WCAG 2.2 AA checklist
+
+- [ ] All functionality keyboard-accessible (test: unplug mouse)
+- [ ] Focus rings visible (NOT `outline: none` without replacement)
+- [ ] Focus not obscured by sticky chrome (WCAG 2.2 NEW: 2.4.11)
+- [ ] Focus appearance strong (≥2px outline + 3:1 contrast — WCAG 2.2 NEW: 2.4.13 if AAA)
+- [ ] Interactive targets ≥24×24 CSS pixels (WCAG 2.2 NEW: 2.5.8)
+- [ ] Drag interactions have non-drag alternative (WCAG 2.2 NEW: 2.5.7)
+- [ ] Auth allows password manager / biometric (WCAG 2.2 NEW: 3.3.8)
+- [ ] Color contrast ≥4.5:1 body, ≥3:1 large
+- [ ] ARIA roles / labels for non-semantic elements
+- [ ] Loading / error / empty states designed
+- [ ] Heading hierarchy correct (no h2 → h4 jumps)
+- [ ] Forms: labels + error messages + required indicators
+- [ ] Animations respect `prefers-reduced-motion`
+- [ ] Page works in portrait + landscape (WCAG: 1.3.4)
+- [ ] axe-core or Lighthouse accessibility ≥90 in CI
+```
+
+## 6. The Empty / Loading / Error / Offline States
+
+Every data-bound surface has 5 designed states:
+
+```tsx
+// Canonical pattern
+function UserList() {
+  const { data, isLoading, error } = useQuery(...);
+
+  // 1. LOADING
+  if (isLoading) return <UserListSkeleton />;
+
+  // 2. ERROR
+  if (error) return <ErrorState
+    title="Couldn't load users"
+    message={error.message}
+    retry={refetch}
+  />;
+
+  // 3. EMPTY
+  if (data.length === 0) return <EmptyState
+    illustration={<UsersEmptyIllustration />}
+    title="No users yet"
+    cta={{ label: 'Invite your first user', onClick: openInvite }}
+  />;
+
+  // 4. SUCCESS (the happy path)
+  return <UserListItems users={data} />;
+
+  // 5. OFFLINE — handled at app level via service worker / online status
+}
+```
+
+### State design rules
+- **Loading**: skeleton, not spinner (skeleton matches the eventual layout; spinner doesn't)
+- **Error**: actionable message + retry; never raw stack trace; avoid generic "Something went wrong"
+- **Empty**: illustration + explanation + CTA (the empty state is a teaching moment; use it)
+- **Success**: the design you spent time on
+- **Offline**: app-level banner + offline-capable surfaces (forms cache draft locally)
+
+## 7. Animation patterns (design + perceived perf)
+
+### Animation principles
+- **Purpose**: every animation has a job (orient, signal, delight). No purposeless motion.
+- **Duration**: 150-300ms for UI feedback; 400-600ms for page transitions; longer = sluggish
+- **Easing**: `ease-out` for entrances (decelerate); `ease-in` for exits (accelerate); `ease-in-out` for in-place changes
+- **Reduced motion**: respect `prefers-reduced-motion: reduce` — disable or significantly shorten
+
+### Animation cookbook
+```css
+/* Skeleton shimmer */
+.skeleton {
+  background: linear-gradient(90deg, #f0f0f0 0%, #e0e0e0 50%, #f0f0f0 100%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+@keyframes shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+
+/* Modal entrance */
+.modal {
+  animation: modal-in 200ms ease-out;
+}
+@keyframes modal-in {
+  from { opacity: 0; transform: scale(0.96); }
+  to { opacity: 1; transform: scale(1); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton, .modal { animation: none; }
+}
+```
+
+### Anti-patterns
+- Animations that block interaction (don't make user wait for the animation)
+- Spinners > 3 seconds (signals broken; replace with skeleton)
+- Animations that move elements being read (jumpy text)
+- Page transitions > 600ms (feels slow on every navigation)
+
+## 8. Form Design (the highest-friction surface)
+
+### Form contract
+```tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+const SignupSchema = z.object({
+  email: z.string().email('Enter a valid email'),
+  password: z.string().min(12, 'Password must be at least 12 characters'),
+  companyName: z.string().min(2),
+});
+
+function SignupForm() {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm({
+    resolver: zodResolver(SignupSchema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} aria-label="Sign up">
+      <Field label="Email" error={errors.email?.message} required>
+        <input type="email" autoComplete="email" {...register('email')} />
+      </Field>
+      <Field label="Password" error={errors.password?.message} required>
+        <input
+          type="password"
+          autoComplete="new-password"
+          aria-describedby="pw-help"
+          {...register('password')}
+        />
+        <p id="pw-help">At least 12 characters</p>
+      </Field>
+      <Field label="Company name" error={errors.companyName?.message}>
+        <input autoComplete="organization" {...register('companyName')} />
+      </Field>
+      <Button type="submit" loading={isSubmitting} label="Create account" />
+    </form>
+  );
+}
+```
+
+### Form rules
+- **Schema-validated** at the boundary (zod / Valibot / Yup)
+- **autoComplete** correct (email, current-password, new-password, organization, etc.)
+- **Field-level errors** under the input (not at top of form)
+- **Submit-button loading state** (disable + spinner)
+- **Optimistic updates** where reversible
+- **Save-draft** for long forms (localStorage; clears on submit)
+- **Keyboard-friendly** (Tab order matches visual order; Enter submits when single-input forms)
+
+## 9. Bundle size discipline
+
+### The budget
+For most B2B SaaS:
+- Initial JS gzipped: ≤200KB
+- Total JS gzipped: ≤600KB
+- CSS gzipped: ≤50KB
+
+For consumer / mobile-heavy products: tighter (initial JS ≤100KB).
+
+### The audit tools
+- `next-bundle-analyzer` / `webpack-bundle-analyzer` — what's IN the bundle
+- `import-cost` (VS Code extension) — see import size as you write
+- Lighthouse CI — fail PR on regression
+- `bundlephobia.com` — before adding a dependency
+
+### Common bundle bloat sources
+- **Moment.js** (use `date-fns` or native `Intl.DateTimeFormat`)
+- **Lodash full import** (use `lodash-es` and tree-shaking, or `import get from 'lodash/get'`)
+- **Whole-package imports** (`import { Button } from '@chakra-ui/react'` may pull entire package)
+- **Bundled icons** (use SVG sprites or per-icon imports)
+- **Polyfills for evergreen-supported features** (browser support has caught up to most)
+
+## 10. Frontend audit checklist (paste-ready)
+
+```markdown
+## UX
+- [ ] 3 dominant user paths named (with evidence: analytics, interviews, hypothesis)
+- [ ] Component contracts have minimum prop surface
+- [ ] Empty / loading / error states designed (not afterthought)
+- [ ] Focus management works on dynamic content (modals, tabs)
+
+## Performance
+- [ ] Lighthouse mobile ≥90 in CI
+- [ ] LCP p75 ≤2.5s on real-user data
+- [ ] INP p75 ≤200ms
+- [ ] CLS p75 ≤0.1
+- [ ] Bundle within budget (gzipped)
+- [ ] Images use WebP/AVIF with explicit dimensions
+- [ ] LCP image preloaded with fetchpriority=high
+
+## Accessibility (WCAG 2.2 AA)
+- [ ] Keyboard accessible
+- [ ] Focus rings visible + not obscured
+- [ ] Color contrast ≥4.5:1 body, ≥3:1 large
+- [ ] Target size ≥24×24 CSS pixels
+- [ ] axe-core ≥90 in CI
+
+## State
+- [ ] Each piece of state in correct home (URL / server / form / local / store)
+- [ ] No server state in useState
+- [ ] Form state in form library with schema validation
+
+## Code organization
+- [ ] One component = one file; co-located test
+- [ ] Component-library boundaries respected (no internal-only imports)
+- [ ] No prop drilling beyond 2 levels (use context or composition)
+```

package/skills/aria-cognition/aria-fullstack-orchestrator/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: aria-fullstack-orchestrator
+description: TRIGGER for any end-to-end feature, user-story, full-stack task that spans frontend + backend + data + deploy. Sequences aria-frontend-architect, aria-backend-architect, aria-harness-deploy, aria-repo-doctrine into a single coherent build plan with a shared API contract, the dominant user path, and a deploy-day predicate. Composes — does not replace — the underlying skills.
+---
+
+# Aria Full-Stack Orchestrator
+
+The cognition skill for end-to-end features. Most owner-impact work spans all three layers (FE + BE + deploy + data). This skill keeps the contract coherent across them.
+
+## Prime Doctrine
+
+A feature shipped to a customer is one artifact, not three. Optimizing each layer independently produces a UI that promises what the API doesn't deliver, or an API that's correct against a UI nobody wants.
+
+- **Contract is the spine.** Define the FE+BE API contract first, in one place. The FE story and the BE handler must derive from the same source.
+- **Dominant path before edge cases.** Build the one path the customer cares about end-to-end, then layer in the others. Building all paths in parallel is the most common cause of half-shipped features.
+- **Deploy day is part of the design.** Feature flags, schema migrations, backwards-compat windows, observability for the new surface — these are part of the build, not a follow-up.
+- **One owner per layer, one orchestrator across layers.** This skill is the orchestrator. It does not write the handler or the component — it sequences the skills that do.
+
+## Trigger Detection
+
+Fire when:
+
+- A user story / epic / PRD spans FE + BE
+- A new feature requires data model + API + UI + deploy
+- A refactor crosses the FE/BE boundary
+- A migration affects user-visible behavior AND server contract
+- An owner asks for a feature in product-language ("let users do X") rather than layer-language ("add an endpoint")
+
+## Required Workflow (contract → dominant-path → deploy-shape)
+
+Every full-stack decision must produce:
+
+1. **Shared contract** — one source-of-truth for the API contract: shapes, errors, idempotency, auth. Owned by `aria-backend-architect`, consumed by `aria-frontend-architect`, generated as types if possible (zod / typebox / proto / openapi).
+2. **Dominant user path** — the one path the feature is for. Named with the user verb (e.g. "user signs up → confirms email → activates first project"). Other paths follow this one, not in parallel.
+3. **FE plan** — `aria-frontend-architect` produces the UX spine, component contracts, perceived-perf strategy, state home for the dominant path.
+4. **BE plan** — `aria-backend-architect` produces the API contract, failure modes, tenant isolation, idempotency, observability for the dominant path.
+5. **Data plan** — schema migration, backfill, cutover, rollback. Backwards-compat window named.
+6. **Deploy plan** — `aria-harness-deploy` produces the deploy pattern, verify block, expected predicate, rollback.
+7. **Day-1 success predicate** — what signal in production tells us "this works"? Numeric or boolean. Examples: "100 sign-ups complete email confirmation in 24h with < 2% error rate."
+
+## Sequencing Rule
+
+This skill produces a single build plan that sequences the underlying skills. The plan has phases:
+
+1. **Phase 0 — Contract lock.** `aria-backend-architect` produces the API contract draft. `aria-frontend-architect` reviews for FE feasibility. Lock the contract before any handler or component code.
+2. **Phase 1 — Dominant-path FE + BE in parallel.** Each skill works against the locked contract. No edge cases yet.
+3. **Phase 2 — Edge cases + failure modes.** Empty / loading / error / offline / permission-denied surfaces, on both layers, against the contract.
+4. **Phase 3 — Deploy preparation.** Migrations, feature flags, observability wiring, runbook. `aria-harness-deploy` produces the deploy plan.
+5. **Phase 4 — Day-1 verification.** Predicate measured, coach-kernel write, decision to keep / rollback / iterate.
+
+## Lens Mapping
+
+Composes the FE-mapped, BE-mapped, and deploy-mapped lenses from the underlying skills. The orchestrator's specific lens job:
+
+- **truth** — does the FE story match the BE contract match the data model? Three-way consistency check.
+- **harm** — at the seams between layers, what's the worst case? (E.g., FE retries a non-idempotent BE call.)
+- **trust** — does the user-visible behavior match what the contract promises across all paths?
+- **power** — does any layer leak its concerns into another (auth in FE, business rules in DB, presentation in API)?
+- **reflection** — would another engineer joining the team understand this feature from the contract alone?
+- **context** — what's the rollout / migration / backwards-compat shape across layers?
+- **impact** — predicted Day-1 success metric
+- **beauty** — does the feature feel like one thing the customer asked for, or three things stitched together?
+
+## User-Facing Layout (per `aria-readable-output`)
+
+```
+## [Feature in one line — e.g. "Ship lead-capture form, end-to-end, with confirm-email + activation tracking"]
+
+### Plan
+- **Contract:** [shape, errors, idempotency-key strategy]
+- **Dominant path:** [user verb sequence]
+- **FE:** [component + state home + perceived-perf in one bullet]
+- **BE:** [endpoint + failure modes + tenant isolation in one bullet]
+- **Data:** [schema migration + backfill + rollback]
+- **Deploy:** [pattern + verify predicate + rollback]
+- **Day-1 success:** [measurable predicate]
+
+**Next:** [Phase 0 first action — lock the contract]
+```
+
+`<gate>` block REQUIRED when this includes a deploy.
+
+## Composition Rule
+
+- Composes the underlying skills — `aria-frontend-architect`, `aria-backend-architect`, `aria-harness-deploy`, `aria-repo-doctrine`, `aria-business-frame` (if owner-outcome relevant)
+- Calls `mizan`, `tadabbur`, `ghazali-8lens`, `predictor`, `noor-recognition` per defaults
+- Calls `aria-research-orchestrator` if external evidence is needed (e.g., competitive UX research)
+
+## Recovery Contract
+
+- If the contract cannot be locked because the BE doesn't know the FE need (or vice versa): that's a discovery gap. Recommend a 30-minute contract sync before any code is written.
+- If the dominant path is unclear: surface the candidate paths, recommend the one with the highest impact / lowest reversibility ratio, ship that as the dominant path.
+- If the data migration is risky: recommend the backwards-compat window as a separate PR before the feature PR.
+- Log full-stack decisions to coach kernel with `risk_class: 'fullstack_action'` and the Day-1 predicate.
+
+## Anti-Patterns
+
+- Writing FE and BE in parallel without a locked contract (the most common cause of integration hell at PR time)
+- Building all paths at once instead of dominant path first (half-shipped features)
+- Treating deploy as "after the build is done" — deploy shape changes the build
+- Schema migrations bundled with feature code (you cannot roll back the feature without rolling back the schema)
+- "Day-1 success will be obvious" — if you can't predicate it, you can't measure it
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.
+
+
+## Self-Executing Recovery Contract
+
+- One re-run with the missing contract / dominant-path / deploy plan
+- If still insufficient, decompose the feature smaller — most "stuck" full-stack work is a sign the feature is too coupled and should ship in smaller increments