Michael Chihlas
0f90c0e199
- Sidebar: kill the drifting railGroups + sections dual definition. Single source of truth (workItems / libraryItems / footerItems) rendered in both pinned and rail modes; pin/unpin is a width and label affordance, not an IA switch. Hairline divider replaces section labels. Guides moves to the footer alongside Account. Renames: Home -> Dashboard, History -> Sessions, Insights -> Analytics. - CURRENT-STATE.md: log PR #158 (session impeccable pass + tasklane keyboard flow) under "Recently shipped". - PRODUCT.md: design-context source of truth (users, brand, aesthetic); sibling to DESIGN-SYSTEM.md. - skills-lock.json: lock /impeccable + /documentation-writer skill versions so other sessions reproduce the same tooling state. - Drop stale .impeccable.md. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
69 lines
4.5 KiB
Markdown
69 lines
4.5 KiB
Markdown
# Design Context — ResolutionFlow
|
|
|
|
> Persistent design guidance for all AI sessions. Source of truth for design intent and principles.
|
|
> For component specs, tokens, and implementation details, see [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md).
|
|
|
|
## Users
|
|
|
|
**MSP engineers** — IT professionals at Managed Service Providers who troubleshoot infrastructure and support issues for multiple client companies. They work under ticket pressure, juggling PSA tools (ConnectWise, Autotask, HaloPSA) and need to resolve issues fast while producing clean documentation.
|
|
|
|
**Context of use:** Mid-ticket, often stressed, switching between tools. They need the interface to get out of their way and help them think clearly. Documentation is a pain point — it should feel automatic, not like extra work.
|
|
|
|
**Job to be done:** Describe an issue, get guided through resolution, and walk away with professional ticket notes — without manual writeup.
|
|
|
|
## Brand Personality
|
|
|
|
**Three words:** Professional, Modern, SaaS
|
|
|
|
**Voice:** Direct, competent, no fluff. Built by MSP engineers, for MSP engineers. The product speaks like a senior colleague — helpful without being patronizing, technical without being dense.
|
|
|
|
**Emotional goals:** Confidence, competence, clarity, focus. The interface should make engineers feel like they have a reliable system backing them up. Every interaction should reinforce trust and reduce cognitive load.
|
|
|
|
## Aesthetic Direction
|
|
|
|
**Visual tone:** Flat, high-contrast dark theme. Premium and clean — Sentry/PostHog DNA. Minimal decoration, maximum signal. Information density without clutter.
|
|
|
|
**References:**
|
|
- **Notion** — clarity of layout, whitespace discipline, typography hierarchy
|
|
- **Stripe** — polish, professional confidence, attention to micro-detail
|
|
- **Figma** — functional density done right, tool-like precision, dark mode execution
|
|
|
|
**Anti-references:**
|
|
- **Microsoft Teams** — cluttered, inconsistent spacing, overwhelming chrome, unclear hierarchy
|
|
- **Kaseya VSA 9** — dated UI patterns, poor information density, legacy enterprise feel
|
|
|
|
**Theme:** Dark mode primary (charcoal palette). Light mode planned but not yet implemented.
|
|
|
|
**Accent:** Electric blue (#60a5fa dark / #2563eb light) — conveys trust, precision, and reliability fitting a troubleshooting tool MSP engineers depend on during outages. Used sparingly (max 5% of UI). Warning uses amber (#fbbf24), info uses cyan (#67e8f9).
|
|
|
|
**Hard rules:** No glassmorphism, no gradient surfaces, no ambient orbs, no backdrop blur, no decorative shadows at rest. Elevation = lighter surface + border, not shadow.
|
|
|
|
## Accessibility
|
|
|
|
**Target:** WCAG 2.2 AA as baseline, with two enhanced commitments:
|
|
- **Enhanced focus appearance** — all interactive elements must have visible, high-contrast focus indicators (not just inputs). Keyboard navigation must be obvious and consistent.
|
|
- **7:1 contrast ratio for data visualization** — chart colors, graph elements, and any data-bearing color must meet AAA contrast against their background. Standard text follows AA (4.5:1 body, 3:1 large).
|
|
|
|
**Already implemented:**
|
|
- `prefers-reduced-motion` fully handled (animations collapse to 0.01ms)
|
|
- Mobile responsive (app shell collapses below 768px)
|
|
- Bottom-sheet modals on mobile
|
|
- Styled scrollbars (6px, subtle)
|
|
|
|
**Considerations for future work:**
|
|
- Color blindness: avoid relying on red/green distinction alone for status — always pair with icons or text labels
|
|
- Screen reader: ensure all interactive elements have accessible names
|
|
- Keyboard: all flows must be completable without a mouse
|
|
|
|
## Design Principles
|
|
|
|
1. **Clarity over decoration.** Every pixel should communicate. If an element doesn't help the user understand or act, remove it. No ornamental gradients, glows, or effects.
|
|
|
|
2. **Density without clutter.** MSP engineers work with lots of data. Show what matters, hide what doesn't. Use typography hierarchy and spacing — not chrome — to create structure.
|
|
|
|
3. **Confidence through consistency.** Same patterns, same tokens, same behavior everywhere. Predictability builds trust. Reference [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) for every component decision.
|
|
|
|
4. **Speed is a feature.** The interface should feel instant. Minimize clicks to action. Auto-generate what can be auto-generated. The copilot-first UX means the primary interaction is typing, not navigating.
|
|
|
|
5. **Accessible by default.** WCAG 2.2 compliance isn't a checklist item — it's a design constraint. Enhanced focus, high-contrast data viz, and motion sensitivity are built in, not bolted on.
|