wize-dev-kit 0.16.0 → 0.16.1

package/src/method-skills/3-solutioning/wize-design-system/workflow.md

@@ -1,36 +1,198 @@
 ---
+
 code: wize-design-system
+description: "Use quando o UX design estiver avançando e precisar estabelecer a baseline do design system (tokens, componentes, grids)."
 name: Design System
 phase: 3-solutioning
 owner: wize-agent-ux-designer   # Mantis (WDS Freya — Phase 7)
 absorbs: "WDS Freya — Phase 7 (Design System)"
-status: stub
+status: ready
 ---
 
 # Design System
 
-**Goal.** Establish design tokens and a baseline component library that Shuri implements consistently across the product.
+**Goal.** Establish design tokens and a baseline component library Shuri implements consistently. Mantis defines what; Tony picks the runtime; Shuri builds. Hawkeye verifies a11y and consistency at gate.
+
+Mantis drives. Output lands in `.wize/solutioning/design-system/`.
 
 ## Inputs
-- `.wize/planning/ux/ux-design/`
+
+- `.wize/planning/ux/ux-design/` (every component the specs use)
+- `.wize/planning/nfr-principles.md` (a11y and perf budgets)
+- Overlay playbooks (active):
+  - `web-overlay/playbooks/wcag-aa.md`, `responsive-breakpoints.md`, `semantic-html.md`
+  - `app-overlay/playbooks/apple-hig.md`, `material-design-3.md`, `touch-targets-and-gestures.md`
 
 ## Outputs
-- `.wize/solutioning/design-system/tokens.json`
-- `.wize/solutioning/design-system/components/{Component}.md`
-- `.wize/solutioning/design-system/README.md`
-
-## Tokens covered
-- color (semantic + raw scale)
-- typography (family, sizes, weights, line-heights)
-- spacing scale
-- radii
-- motion (durations, easings)
-- shadows / elevation
-- z-index layers
-
-## Component baseline
-Buttons, inputs, selects, modals, dialogs, tabs, cards, notifications. Enough for the first epic; expand as stories require.
-
-## Overlays
-- **Web overlay** active → responsive token variants, REM-based typography.
-- **App overlay** active → platform-token sets (iOS / Android), touch-friendly spacing scale.
+
+- `.wize/solutioning/design-system/tokens.json` — single source of truth.
+- `.wize/solutioning/design-system/components/{Component}.md` — one per component.
+- `.wize/solutioning/design-system/README.md` — index + theming guide.
+
+## Tokens (the only acceptable way to ship styles)
+
+Mantis defines the tokens; Tony picks the runtime (Tailwind, CSS modules, Vanilla Extract, Compose theme, SwiftUI tokens). The names below are framework-agnostic.
+
+### Color (semantic + raw scale)
+
+| Semantic | Light | Dark | Contrast pair |
+|---|---|---|---|
+| `surface.base` | #FFFFFF | #0B0F14 | text.primary |
+| `surface.raised` | #F5F7FA | #121821 | text.primary |
+| `text.primary` | #0B0F14 | #E5E7EB | surface.base |
+| `text.secondary` | #4B5563 | #9CA3AF | surface.base |
+| `accent.brand` | #6F49FF | #8B6FFF | text.onAccent |
+| `text.onAccent` | #FFFFFF | #FFFFFF | accent.brand |
+| `success` | #058E5C | #34D399 | text.onSuccess |
+| `warning` | #C9621E | #F59E0B | text.onWarning |
+| `error` | #B42318 | #FCA5A5 | text.onError |
+| `border.default` | #E5E7EB | #2A313A | — |
+| `border.focus` | accent.brand | accent.brand | — |
+
+Validate every pair against WCAG AA (≥ 4.5:1 normal, ≥ 3:1 large). Run before you commit.
+
+### Typography
+
+| Token | Family | Size | Weight | Line | Letter |
+|---|---|---|---|---|---|
+| `display.l` | Inter Display | clamp(2.5rem, 5vw, 3.5rem) | 700 | 1.05 | -0.02em |
+| `display.m` | Inter Display | clamp(2rem, 4vw, 2.5rem) | 700 | 1.1 | -0.01em |
+| `heading.l` | Inter | clamp(1.5rem, 3vw, 2rem) | 600 | 1.2 | -0.01em |
+| `heading.m` | Inter | 1.25rem | 600 | 1.3 | 0 |
+| `heading.s` | Inter | 1rem | 600 | 1.4 | 0 |
+| `body.l` | Inter | 1.125rem | 400 | 1.6 | 0 |
+| `body.m` | Inter | 1rem | 400 | 1.55 | 0 |
+| `body.s` | Inter | 0.875rem | 400 | 1.5 | 0 |
+| `caption` | Inter | 0.75rem | 500 | 1.4 | 0.01em |
+
+Use rem for body; clamp() for fluid headings (see `responsive-breakpoints.md`).
+
+### Spacing scale (4px base, geometric)
+
+`0` 0 · `1` 4 · `2` 8 · `3` 12 · `4` 16 · `5` 24 · `6` 32 · `7` 48 · `8` 64 · `9` 96 · `10` 128
+
+### Radius
+
+`none` 0 · `sm` 4 · `md` 8 · `lg` 12 · `xl` 16 · `pill` 999.
+
+### Elevation
+
+| Token | Light | Dark (tonal) |
+|---|---|---|
+| `e1` | 0 1px 2px rgba(0,0,0,.06) | surface.raised |
+| `e2` | 0 2px 4px rgba(0,0,0,.08) | surface.raised + 4% |
+| `e3` | 0 4px 12px rgba(0,0,0,.10) | surface.raised + 8% |
+| `e4` | 0 12px 24px rgba(0,0,0,.12) | surface.raised + 12% |
+
+App overlay: prefer tonal elevation per Material 3.
+
+### Motion
+
+| Token | Duration | Easing |
+|---|---|---|
+| `motion.micro` | 100ms | `ease-out` |
+| `motion.transition` | 200ms | `cubic-bezier(0.2, 0, 0, 1)` |
+| `motion.page` | 300ms | `cubic-bezier(0.4, 0, 0.2, 1)` |
+| `motion.spring.subtle` | (spring) | mass 1, stiff 350, damp 30 |
+
+Honor `prefers-reduced-motion`. Replace transforms with fades.
+
+## Components — the baseline set
+
+Each component has its own `.md` doc with: purpose, anatomy, states (default/hover/focus/active/disabled/loading), variants, accessibility, do/don't, snippets.
+
+| Component | Mandatory states | Notes |
+|---|---|---|
+| Button | default, hover, focus, active, disabled, loading | variants: primary, secondary, tertiary, destructive, ghost |
+| Input | default, focus, error, disabled, success | always has visible label |
+| Select | default, open, focus, disabled | native first; custom only when needed |
+| Textarea | as Input | auto-grow optional |
+| Checkbox | unchecked, checked, indeterminate, focus, disabled | native input + custom skin |
+| Radio | unchecked, checked, focus, disabled | grouped under fieldset |
+| Toggle/Switch | off, on, focus, disabled | `role="switch" aria-checked` |
+| Card | default, raised, interactive | elevation tokens |
+| Modal / Dialog | open, closing | focus trap + ESC + restore |
+| Sheet (app) | half / full | drag handle |
+| Tabs | active, inactive, focus | keyboard arrows |
+| Accordion | collapsed, expanded, focus | `<details>` when possible |
+| Toast / Snackbar | info, success, warning, error | `role="status"` or `alert` |
+| Tooltip | hidden, visible | `aria-describedby`, touch alt |
+| Menu | closed, open, focus | keyboard navigation |
+| Dropdown | (synonym of Menu / Combobox) | follow ARIA combobox |
+| Badge | default, success, warning, error | contrast ≥ 4.5:1 |
+| Avatar | image, initials, placeholder | 1:1 ratio, alt text |
+| Skeleton | static, shimmer | respect reduced-motion |
+| Empty state | default | message + primary action |
+| Loading | spinner / progress | accessible announcement |
+
+## Component template (one per component)
+
+```markdown
+---
+component: Button
+status: ready
+owner: Mantis
+linked_screens: [signup-empty, team-list-empty, …]
+---
+
+# Button
+
+## Purpose
+Trigger an action. Never use for navigation between routes.
+
+## Anatomy
+[icon?] [label] [icon?] · padding by size · radius `md`
+
+## Variants
+- `primary` — main action; one per screen region.
+- `secondary` — alternative action.
+- `tertiary` — text-only.
+- `destructive` — irreversible action.
+- `ghost` — minimal chrome, e.g., toolbar.
+
+## Sizes
+- `sm` (height 32, label `body.s`)
+- `md` (height 40, label `body.m`)
+- `lg` (height 48, label `body.m`)
+
+## States
+
+| State | Treatment |
+|---|---|
+| default | accent.brand bg, text.onAccent label |
+| hover | accent.brand 10% darker |
+| focus | 2px outline `border.focus`, offset 2px |
+| active | accent.brand 15% darker |
+| disabled | opacity 0.4, `aria-disabled="true"`, cursor not-allowed |
+| loading | spinner replaces icon; label unchanged; click ignored |
+
+## Accessibility
+- Native `<button>`.
+- `aria-label` when icon-only.
+- Visible focus ring always (don't override).
+- 24×24 px hit area minimum (web), 44pt (iOS), 48dp (Android).
+- Min contrast on label ≥ 4.5:1.
+
+## Don't
+- Use `<div onclick>`.
+- Remove the focus ring without replacement.
+- Use destructive for "Continue".
+- Stack > 2 primary buttons on a screen.
+```
+
+## Theming + overlays
+
+- **Web overlay:** tokens emit as CSS custom properties; dark mode toggled via `[data-theme="dark"]` on `<html>`.
+- **App overlay (iOS):** tokens as SwiftUI environment values; dark mode auto.
+- **App overlay (Android):** tokens as Compose `MaterialTheme` extensions; honor `dynamicColorScheme` when allowed.
+
+## Anti-patterns Mantis rejects
+
+- **Hex in components.** Everything via tokens.
+- **One-off components shipped without doc.** Add to the system or refuse to merge.
+- **Component matrix without states.** A button without disabled+loading isn't a button.
+- **Component that fails axe.** Failed at definition; don't ship.
+
+## Hand-off
+
+> Tokens + 20 components at `.wize/solutioning/design-system/`. Tony picks the runtime (Tailwind / Vanilla Extract / SwiftUI tokens / Compose theme); Shuri implements. Hawkeye references this in `tea-design.md`: a11y + visual regression hooks point at these tokens.

package/src/method-skills/3-solutioning/wize-nfr-principles/workflow.md

@@ -1,33 +1,161 @@
 ---
+
 code: wize-nfr-principles
+description: "Use quando o PRD estiver validado e precisar definir os princípios de NFR (perf, segurança, confiabilidade, acessibilidade, custo) que guiarão a arquitetura."
 name: NFR Principles
-phase: 2-to-3-boundary
+phase: 3-solutioning
 owner: wize-agent-solution-strategist   # Nick Fury
-status: stub
+status: ready
 ---
 
 # NFR Principles
 
-**Goal.** Define non-functional non-negotiables Tony must design against and Hawkeye must verify.
+**Goal.** Define non-functional non-negotiables Tony must design against and Hawkeye must verify. Hill defers to this when sizing scope. Mantis respects the a11y/perf bars in UX specs. Shuri implements with these targets in hand.
+
+Fury drives. Output lands in `.wize/planning/nfr-principles.md`.
+
+## Inputs
+
+- `.wize/planning/prd.md`
+- `.wize/planning/tech-vision.md`
+- `.wize/planning/brief.md` (compliance constraints, audience implications)
+- Overlay perf playbooks if active:
+  - `web-overlay/playbooks/web-perf-budgets.md`
+  - `app-overlay/playbooks/mobile-perf-budgets.md`
+  - `web-overlay/playbooks/wcag-aa.md`
+  - `app-overlay/playbooks/apple-hig.md`, `material-design-3.md`
+
+## Outputs
 
-## Output
 - `.wize/planning/nfr-principles.md`
 
-## Categories
-- **Performance** — targets (LCP, p95, throughput).
-- **Security** — auth model, data classes, threat surface posture.
-- **Reliability** — uptime, error budget, retry/idempotency policy.
-- **Maintainability** — coding standards, tech-debt allowance.
-- **Accessibility** — WCAG / platform guidelines minimums.
-- **Cost** — monthly envelope and degradation strategy.
+## Categories (always cover these six)
+
+For each, write **non-negotiable** + **stretch** + **deferred** (with trigger). Use the playbooks as starting points; **tighten** if PRD demands, never loosen below playbook recommendations.
+
+### 1. Performance
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | LCP ≤ 2.5s mobile, INP ≤ 200ms, CLS ≤ 0.1 (web) — cold start ≤ 1.5s mid-range (app) |
+| Stretch | LCP ≤ 1.8s, INP ≤ 100ms |
+| Deferred | Server-side LCP for edge regions — revisit when audience > 30% non-NA |
+
+### 2. Security
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | OWASP Top 10 covered; auth via {{vendor}}; tokens never logged; secrets via {{provider}}; RLS on every table with user_id |
+| Stretch | SOC2 type-I controls in place by {{date}} |
+| Deferred | SOC2 type-II — revisit at $1M ARR |
+
+### 3. Reliability
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | 99.9% uptime in primary region; error budget 0.1%/month; retries idempotent with deduplication key |
+| Stretch | 99.95% uptime |
+| Deferred | Multi-region active/active — revisit per tech-vision deferred |
+
+### 4. Maintainability
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | Lint + format on commit; > 80% test coverage on logic modules; ADRs for every architectural decision; deps audited monthly |
+| Stretch | < 5% files over 300 LOC; cyclomatic complexity < 15 per function |
+| Deferred | Auto-doc generation — revisit when API consumers > 3 |
+
+### 5. Accessibility
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | WCAG 2.2 AA on every shipped page; keyboard-complete; axe in CI |
+| Stretch | AAA on critical flows (signup, billing) |
+| Deferred | Full screen-reader manual audit every release — revisit at next compliance review |
+
+### 6. Cost
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | Total infra ≤ ${{X}}/month under {{load}}; degradation strategy documented for 10× spike |
+| Stretch | Cost-per-active-user ≤ ${{Y}} |
+| Deferred | Per-feature cost attribution — revisit when finance asks |
+
+## Steps
+
+### 1. Read the playbooks first
+
+If web/app overlays are active, the perf and a11y playbooks already hold real targets calibrated to mid-range device + 3G fast. Use them as starting point.
+
+### 2. Tighten by audience
+
+Mid-range mobile is the playbook baseline. If your PRD audience is *more* constrained (emerging markets, kiosk hardware, healthcare older devices), tighten. Don't loosen.
+
+### 3. Map every non-negotiable to a verifier
+
+Every non-negotiable must answer the question: *Who and how do we verify this on every release?*
+
+- LCP → `web-perf-budgets.md` lighthouse-ci config.
+- WCAG → axe in CI + Hawkeye review.
+- Uptime → SLO defined in `.wize/solutioning/observability.md` (Tony).
+- Error budget → tracked in {{tool}}.
+
+A non-negotiable with no verifier is a wish.
+
+### 4. Tell the story (one paragraph)
+
+Open the doc with a paragraph: *why these numbers, and what trade-offs they imply.* Future readers re-litigate non-negotiables every six months; the story saves that hour.
+
+### 5. Hand off
+
+Mark `status: aligned`. Tony reads before architecture; Hawkeye reads before risk profile.
+
+## Output template
 
-## Template
 ```markdown
-# NFR Principles
+---
+status: aligned
+owner: Nick Fury
+created: YYYY-MM-DD
+---
+
+# NFR Principles — {{project_name}}
+
+## Why these numbers
+
+{{One paragraph: target audience, country mix, device class, compliance frame. Why we picked these targets specifically.}}
+
+## Performance
+| Tier | Targets | Verifier |
+|---|---|---|
+| Non-negotiable | LCP ≤ 2.5s mobile (CWV), INP ≤ 200ms, CLS ≤ 0.1 | lighthouse-ci + web-vitals beacon |
+| Stretch | LCP ≤ 1.8s | same |
+| Deferred | Multi-region LCP — trigger: EU DAU > 5k | — |
 
-| Category | Non-negotiable | Stretch | Deferred |
-|---|---|---|---|
-| Performance | … | … | … |
-| Security | … | … | … |
+## Security
+…
+
+## Reliability
+…
+
+## Maintainability
+…
+
+## Accessibility
+…
+
+## Cost
 …
 ```
+
+## Anti-patterns Fury rejects
+
+- **Targets without numbers.** "Fast." Wrong. "p95 server response ≤ 200ms."
+- **Stretch targets that are actually goals.** If you must hit it, it's non-negotiable.
+- **No verifier.** Every non-negotiable answers *who verifies, with what tool, on what cadence*.
+- **Loosening below the playbook.** Tightening is fine. Loosening is a smell — escalate.
+- **Cost left blank.** Cost is always an NFR.
+
+## Hand-off
+
+> NFRs at `.wize/planning/nfr-principles.md`. Tony, architecture must respect items 1.A and 4.A from day one (perf and ADR discipline). Hawkeye, your gate policy can stay advisory but NFR gate per epic is mandatory. Hill, scope must keep the budget headroom for item 6.A.

package/src/method-skills/3-solutioning/wize-project-context/workflow.md

@@ -0,0 +1,120 @@
+---
+
+code: wize-project-context
+description: "Use quando precisar estabelecer ou atualizar o contexto do projeto (stack, convenções, restrições) para orientar a solução."
+name: Project Context
+phase: 3-solutioning
+owner: wize-agent-architect   # Tony Stark
+status: ready
+---
+
+# Project Context
+
+**Goal.** Consolidate the 5 foundational artifacts (brief, PRD, UX, architecture, risk profile) into a single `.wize/knowledge/project-context.md` so other agents (Shuri, Hawkeye, Mantis, Wizer) can read the project in one shot instead of stitching it from 5 files.
+
+Tony drives. Peggy polishes prose. Wizer is on call for cross-cutting drift.
+
+## When to run
+
+- After Phase 3 closeout (architecture + ADRs + risk profile all exist).
+- After any major change to brief / PRD / architecture (rerun).
+- Before sprint planning if context feels stale.
+
+## When NOT to run
+
+- During greenfield with no artifacts yet (run only after brief + PRD exist).
+- As a CI step (manual; expensive to run on every commit).
+
+## Inputs
+
+- `.wize/planning/brief.md` — Vision, Audience.
+- `.wize/planning/prd.md` — Goals, scope.
+- `.wize/planning/ux/ux-design/index.md` — UX stack, key screens.
+- `.wize/solutioning/architecture.md` — Tech stack, components.
+- `.wize/solutioning/adrs/*.md` — Key decisions.
+- `.wize/implementation/tea/risk-profile.md` — Active risks.
+
+## Output
+
+- `.wize/knowledge/project-context.md` (5 sections, YAML frontmatter, `last_updated` date).
+
+## Steps
+
+### 1. Vision and Audience
+
+Copy from `brief.md` (or `prd.md` if brief is missing). One paragraph each. Mark the source file in a comment.
+
+### 2. Tech stack
+
+From `architecture.md`, list: runtime, framework, database, key libraries, build tool. One bullet per item. Skip items that are "TBD".
+
+### 3. Key ADRs
+
+List the 5 most recent ADRs from `.wize/solutioning/adrs/`. For each: title, decision, why. Older ADRs are out of scope; refer to `adrs/index.md` for the full list.
+
+### 4. Active risks
+
+Copy from `risk-profile.md` the top 5 risks (highest prob × impact). One bullet per risk with the mitigation. Defer the rest.
+
+### 5. Active sprint
+
+Read `.wize/implementation/sprint-status.yaml` and include: sprint number, capacity, in-progress stories. Skip if no active sprint.
+
+### 6. Hand off
+
+Output is a markdown file. Wizer uses this file to seed `/wize`, `/wize-help`, `/wize-dev-story`, and `/wize-onboarding` reads.
+
+## Output template
+
+```markdown
+---
+generated: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+sources:
+  - .wize/planning/brief.md
+  - .wize/planning/prd.md
+  - .wize/planning/ux/ux-design/index.md
+  - .wize/solutioning/architecture.md
+  - .wize/solutioning/adrs/
+  - .wize/implementation/tea/risk-profile.md
+---
+
+# Project Context — {project_name}
+
+## Vision
+{paragraph from brief.md}
+
+## Audience
+{paragraph from brief.md or prd.md}
+
+## Tech stack
+- Runtime: {value}
+- Framework: {value}
+- Database: {value}
+- Key libraries: {value}
+- Build: {value}
+
+## Key ADRs
+1. **{title}** — {decision}. Why: {why}.
+2. ...
+
+## Active risks
+1. **{R-id}** — {description}. Mitigation: {mitigation}.
+2. ...
+
+## Active sprint
+- Sprint: {N}
+- Capacity: {days}
+- In-progress: {stories}
+```
+
+## Anti-patterns Tony rejects
+
+- Reading all 6 sources in full and dumping them. Summarize in 5 sections.
+- Editing the project-context.md by hand. (Always re-run the workflow to keep `last_updated` honest.)
+- Skipping the frontmatter. Other agents parse it.
+- Including items marked "TBD". Surface them in the `Open questions` section instead.
+
+## Hand-off
+
+> "Project context updated at `.wize/knowledge/project-context.md`. {N} sources, 5 sections, {date}. Next: `/wize-onboarding` (Wizer) reads this for first contact."