UX Principles
These principles apply to the dashboard, docs, examples, and onboarding flows. They are written for enterprise and developer users who need to understand what Punk is doing before they allow it to affect production traffic.
Default To The Safe Path
The first recommended action should be observe-only integration. Users should see live traces, route explanations, cost, latency, and policy verdicts before they are asked to promote artifacts, enable canaries, install many connectors, or tune advanced settings.
Show The Current Decision
Every workflow should answer the operator's immediate question:
| Context | Primary question |
|---|---|
| First run | Did traffic reach Punk, and what happened? |
| First week | What repeated work, cost, risk, and evidence did we observe? |
| Shadow | Does the candidate match live behavior without side effects? |
| Canary | Is the optimized route serving the intended slice safely? |
| Expansion | What can be added without weakening audit or rollback? |
Avoid putting a full feature catalog in the first screen for a new tenant. Link to advanced areas after the current decision is clear.
Use Progressive Disclosure
Expose controls in operational order:
- Observe traffic.
- Review the first-week report.
- Classify side effects.
- Inspect replay and shadow evidence.
- Approve a narrow canary.
- Expand coverage.
Advanced features should stay available, but not compete with the next required decision. Examples: connector catalog details, artifact internals, model substitution settings, semantic-cache modes, custom policies, cross-tenant learning, and high-impact write controls.
Keep Language Operational
Use concrete words: observe, route, trace, policy, side effect, replay, shadow, canary, approval, rollback, expand.
Avoid claims that imply autonomous production change without evidence. The accurate claim is that Punk uses trace-grounded optimization with replay and shadow verification.
Make Evidence Reviewable
A user should be able to inspect:
- Which traffic matched.
- Which route served.
- Which alternatives were rejected.
- Which policy decision applied.
- Which replay and shadow checks passed or failed.
- Which side effects were suppressed, approved, or executed.
- What fallback would happen.
- Who approved promotion.
When an optimization is not ready, the UI and docs should say why in operational terms: insufficient samples, unstable output schema, missing identity, unclassified tool, failed replay, failed shadow, policy block, or missing approval.
Do Not Remove Expert Controls
Simplification means sequencing, not deletion. Keep expert controls for operators and developers, but introduce them from the relevant evidence page or task flow. A new user should not need to understand every route, connector, artifact state, and policy knob before seeing their first run.