ui-ux-master 1.1.0

package/references/ui-ux-complete-checklist.md

@@ -0,0 +1,214 @@
+# UI/UX Complete Checklist
+
+Use this checklist for every UI/UX design, audit, redesign, or implementation review.
+
+## 1. Product Fit
+
+- [ ] Product category is clear.
+- [ ] Primary user is identified.
+- [ ] User job-to-be-done is explicit.
+- [ ] Business goal is explicit.
+- [ ] Success metric is defined.
+- [ ] Constraints are listed: platform, brand, tech, timeline, compliance, localization.
+- [ ] Assumptions are separated from facts.
+- [ ] Risks and open questions are documented.
+
+## 2. Information Architecture
+
+- [ ] Navigation matches user mental model.
+- [ ] Top-level sections are mutually exclusive and collectively useful.
+- [ ] Labels use user vocabulary, not internal implementation names.
+- [ ] Important tasks are reachable in the shortest path.
+- [ ] Secondary and rare tasks are discoverable but not dominant.
+- [ ] Search, filter, sort, and grouping are specified where needed.
+- [ ] Role/permission visibility is defined.
+- [ ] Breadcrumbs or location indicators exist for deep structures.
+
+## 3. User Flows
+
+- [ ] Entry points are defined.
+- [ ] Happy path is short and clear.
+- [ ] Back/cancel behavior is defined.
+- [ ] Error recovery is defined.
+- [ ] Empty states have next actions.
+- [ ] Success confirmation is defined.
+- [ ] Destructive actions have undo or confirmation.
+- [ ] System feedback exists after every important action.
+- [ ] Flow supports first-time and returning users.
+
+## 4. Layout and Hierarchy
+
+- [ ] Each screen has one primary goal.
+- [ ] Main CTA is visually dominant.
+- [ ] Secondary actions do not compete with primary action.
+- [ ] Content is grouped by task or meaning.
+- [ ] Spacing supports scanability.
+- [ ] Headings create a logical page outline.
+- [ ] Dense areas have progressive disclosure.
+- [ ] Important information appears before advanced options.
+- [ ] Visual weight matches importance.
+
+## 5. Visual Design
+
+- [ ] Design style matches product trust level and brand personality.
+- [ ] Color roles are semantic and consistent.
+- [ ] Typography scale supports hierarchy.
+- [ ] Spacing scale is consistent.
+- [ ] Radius, borders, elevation, and shadows are consistent.
+- [ ] Icon style is consistent.
+- [ ] Imagery/illustration style is defined if used.
+- [ ] Motion style is purposeful and not excessive.
+- [ ] UI density matches user context.
+
+## 6. Components
+
+- [ ] Buttons have variants, sizes, states, and usage rules.
+- [ ] Form controls have labels, helper text, validation, disabled states.
+- [ ] Navigation components have current, hover, focus, and collapsed states.
+- [ ] Modals/drawers/popovers define open/close, focus trap, escape behavior.
+- [ ] Tables define sorting, filtering, pagination, empty, loading, and bulk actions.
+- [ ] Cards define clickable area and metadata hierarchy.
+- [ ] Alerts/toasts define severity and dismissal behavior.
+- [ ] Tooltips do not contain critical information.
+- [ ] Component reuse is preferred over one-off styling.
+
+## 7. State Coverage
+
+- [ ] Default state.
+- [ ] Loading state.
+- [ ] Skeleton state if needed.
+- [ ] Empty state.
+- [ ] Error state.
+- [ ] Partial data state.
+- [ ] Offline/network issue state if applicable.
+- [ ] Permission denied state.
+- [ ] Disabled state.
+- [ ] Hover/focus/active states.
+- [ ] Selected/current state.
+- [ ] Success state.
+- [ ] Undo/recovery state.
+
+## 8. Forms
+
+- [ ] Only necessary fields are requested.
+- [ ] Every field has a visible label.
+- [ ] Required/optional status is clear.
+- [ ] Helper text explains ambiguous fields.
+- [ ] Validation timing is user-friendly.
+- [ ] Error messages explain the fix.
+- [ ] User input is preserved after errors.
+- [ ] Inputs use correct type/autocomplete.
+- [ ] Long forms are grouped or stepped.
+- [ ] Submit/loading/disabled behavior is defined.
+
+## 9. Content and Microcopy
+
+- [ ] H1 explains the page purpose.
+- [ ] CTA labels are verb-led and specific.
+- [ ] Empty state copy explains what happened and what to do next.
+- [ ] Error copy avoids blame and includes recovery.
+- [ ] Confirmation copy states the result.
+- [ ] Destructive action copy explains impact.
+- [ ] Tone is consistent.
+- [ ] Text is concise without becoming vague.
+- [ ] Jargon is avoided unless the audience expects it.
+
+## 10. Accessibility
+
+- [ ] WCAG 2.2 AA is the baseline.
+- [ ] Semantic HTML/roles are correct.
+- [ ] Heading order is logical.
+- [ ] Keyboard navigation works.
+- [ ] Focus order matches visual/task order.
+- [ ] Focus indicators are visible.
+- [ ] Contrast meets AA.
+- [ ] Color is not the only status indicator.
+- [ ] Images/icons have appropriate alt text or are decorative.
+- [ ] Form errors are programmatically associated.
+- [ ] Motion respects reduced motion.
+- [ ] Touch targets are at least 44x44 px where possible.
+
+## 11. Responsive Design
+
+- [ ] Mobile layout is not an afterthought.
+- [ ] Navigation has a mobile pattern.
+- [ ] Tables/cards have small-screen behavior.
+- [ ] Sticky elements do not block content.
+- [ ] Modals/drawers fit small screens.
+- [ ] Text wraps safely.
+- [ ] Images preserve useful crops.
+- [ ] Layout works at 320px width.
+- [ ] Layout works at tablet, desktop, and wide sizes.
+
+## 12. Trust, Safety, and Ethics
+
+- [ ] Costs, risks, permissions, and data usage are transparent.
+- [ ] Dark patterns are avoided.
+- [ ] Consent is explicit where needed.
+- [ ] Destructive actions are recoverable or confirmed.
+- [ ] Sensitive data requests explain why.
+- [ ] AI-generated or uncertain content is labeled when relevant.
+- [ ] User control is preserved.
+
+## 13. Performance Perception
+
+- [ ] Critical content loads first.
+- [ ] Loading states reduce uncertainty.
+- [ ] Layout shift is minimized.
+- [ ] Feedback appears immediately after user action.
+- [ ] Heavy visuals do not harm usability.
+- [ ] Expensive interactions have optimistic UI or clear progress.
+
+## 14. Handoff
+
+- [ ] Screen list is complete.
+- [ ] Components and states are specified.
+- [ ] Design tokens are listed.
+- [ ] Responsive behavior is defined.
+- [ ] Accessibility requirements are explicit.
+- [ ] Data requirements are defined.
+- [ ] Analytics events are listed.
+- [ ] QA checklist is included.
+- [ ] Out-of-scope items are documented.
+
+## Advanced One-Stop Coverage Additions
+
+### Research Evidence
+
+- [ ] Evidence sources are documented: analytics, support, interviews, usability tests, screenshots, or stakeholder assumptions.
+- [ ] Research confidence is labeled high, medium, or low.
+- [ ] Assumptions are not presented as user facts.
+- [ ] Research method fits the uncertainty: interview, survey, usability test, card sort, tree test, accessibility test, or heuristic review.
+
+### Platform-Native Conventions
+
+- [ ] Web, iOS, Android/Material, desktop, email, kiosk, TV, or wearable conventions are followed as relevant.
+- [ ] Touch, mouse, keyboard, remote, and assistive-tech input models are considered.
+- [ ] Back, Escape, safe areas, system font scaling, zoom, and reduced-motion behaviors are defined where relevant.
+
+### Internationalization and Content Resilience
+
+- [ ] Text can expand without breaking layout.
+- [ ] RTL/bidirectional layout is considered where relevant.
+- [ ] Date, time, number, currency, address, phone, name, and plural formats are locale-aware where relevant.
+- [ ] Translation keys, variables, fallback copy, and legal copy ownership are documented.
+
+### Measurement and Quality Gates
+
+- [ ] Task success metric is explicit.
+- [ ] Accessibility, responsive, platform, performance, and content gates are defined.
+- [ ] Analytics events support the key user decisions and outcomes.
+- [ ] Usability validation method is specified when risk is medium or high.
+
+### Ethics, Privacy, and Inclusion
+
+- [ ] No dark patterns: hidden costs, forced continuity, confirmshaming, obstruction, sneaking, or manipulative urgency.
+- [ ] Consent is clear, granular, and not preselected for optional tracking.
+- [ ] Sensitive data and permissions are requested only when needed and explained plainly.
+- [ ] High-risk flows include recovery, appeal, export/delete, or human handoff where appropriate.
+
+### Data Visualization and Dashboards
+
+- [ ] Charts have titles, units, timeframes, clear scales, and accessible color choices.
+- [ ] Tables support keyboard use, sorting, filtering, density, empty/no-results states, and exports where relevant.
+- [ ] Data freshness, partial data, stale data, and uncertainty are communicated.

package/references/ui-ux-curriculum-and-standards.md

@@ -0,0 +1,40 @@
+# UI/UX Curriculum and Standards Map
+
+Use this reference to ensure `ui-ux-master` covers basic-to-advanced UI/UX knowledge and aligns with recognized education paths and standards.
+
+## Beginner Foundations
+
+- UX vs UI, usability, accessibility, human-centered design.
+- Product goal, user goal, jobs-to-be-done.
+- Basic research: interviews, surveys, competitive analysis.
+- Basic IA: sitemap, navigation, labels.
+- Wireframes, flows, states, responsive basics.
+- Visual basics: typography, color, spacing, hierarchy.
+
+Aligned sources: Google UX Design Professional Certificate, Interaction Design Foundation topic library, NN/g definition of UX, Digital.gov usability guidance.
+
+## Intermediate Practice
+
+- Research planning, synthesis, personas/JTBD, journey maps.
+- Usability testing, heuristic evaluation, accessibility audit.
+- Design systems, components, tokens, governance.
+- Platform conventions for web, iOS, Android, desktop.
+- Content design, forms, ecommerce, dashboard/data visualization.
+- Measurement: task success, SEQ, SUS, funnel metrics, HEART.
+
+Aligned sources: NN/g UX Certification curriculum areas, GOV.UK Service Manual, Material Design, Apple HIG, Microsoft Fluent, W3C WCAG/WAI.
+
+## Advanced Practice
+
+- Service design and omnichannel journeys.
+- Experimentation and product strategy.
+- Advanced accessibility and assistive technology testing.
+- Ethical design, privacy, dark-pattern avoidance, AI transparency.
+- Design system operations, versioning, contribution, deprecation.
+- High-risk domain design for health, finance, children, identity, safety.
+
+Aligned sources: ISO 9241-210, ISO 9241-11, HFI certification topics, W3C privacy principles, FTC dark patterns report, NIST AI Risk Management Framework.
+
+## Agent Rule
+
+When asked for a learning path, audit, or design plan, classify the work as beginner, intermediate, or advanced and include next-step learning or validation recommendations.

package/references/ui-ux-frontend-implementation-rules.md

@@ -0,0 +1,378 @@
+# UI/UX Frontend Implementation Rules
+
+Use these rules every time an agent creates, edits, reviews, or ships frontend using `ui-ux-master`. This file is the implementation guardrail so frontend work does not miss UX, UI, accessibility, responsiveness, states, branding, or handoff requirements.
+
+## Non-Negotiable Rule
+
+No frontend is complete until it handles:
+
+- User goal and business goal.
+- Primary flow and secondary flow.
+- Layout, hierarchy, and responsive structure.
+- Brand/style direction and design tokens.
+- Components and all interactive states.
+- Loading, empty, error, success, disabled, and permission states.
+- Accessibility and keyboard behavior.
+- Content/microcopy.
+- Data requirements and validation.
+- QA verification.
+
+If any item is missing, the implementation is incomplete.
+
+## Required Implementation Order
+
+### 1. Inspect Before Building
+
+Before writing UI code:
+
+- Check for an application UI/UX memory file first: `.ui-ux-memory.md`, `docs/ui-ux-memory.md`, `docs/design/ui-ux-memory.md`, or `design/ui-ux-memory.md`.
+- If memory exists, read it and follow it as the source of truth for brand and UI consistency.
+- If no memory exists, inspect existing branding and create `.ui-ux-memory.md` using `templates/ui-ux-memory.md` before or alongside the first durable UI change.
+- Check the project stack and dependencies.
+- Check existing component library or design system.
+- Check routing, layout, state management, and styling conventions.
+- Check existing colors, typography, spacing, and components.
+- Check similar pages/components before creating new ones.
+
+Do not assume Tailwind, Bootstrap, shadcn, Radix, MUI, Framer Motion, icons, fonts, or chart libraries exist. Verify first.
+
+### 2. Define the UX Contract
+
+If this is a fresh project with no existing memory or branding, ask minimal high-value questions first: what is being built, who it is for, primary success action, desired personality, colors/fonts/references to use or avoid, and platform/type. If the user does not answer, proceed with explicit assumptions and save them in `.ui-ux-memory.md`.
+
+Before coding a screen, write or infer:
+
+- Screen purpose.
+- Primary user.
+- Primary task.
+- Primary CTA.
+- Secondary actions.
+- Entry point.
+- Success outcome.
+- Failure/recovery path.
+- Required data.
+- Permissions/roles if applicable.
+
+### 3. Choose the Design Method
+
+Use `references/top-100-brand-website-analysis.md` and choose one primary method plus up to two supporting methods:
+
+- Product Cinema.
+- Utility Command Center.
+- Editorial Brand World.
+- Enterprise Trust Hub.
+- Card-Based Discovery.
+- Conversion Simplicity.
+- Ecosystem Bundling.
+- Premium Restraint.
+- Playful Familiarity.
+- Technical Authority.
+
+Never copy a brand exactly. Extract methods, not trademarks.
+
+### 4. Create or Reuse Tokens
+
+Use tokens instead of scattered hardcoded values.
+
+Required token groups:
+
+- Color: background, surface, text, border, primary, secondary, success, warning, danger, info, focus.
+- Typography: display, h1, h2, h3, body, body-sm, label, caption, code.
+- Spacing: 0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80.
+- Radius: none, sm, md, lg, xl, full.
+- Elevation: none, sm, md, lg, overlay.
+- Motion: fast, base, slow, easing.
+- Breakpoints: mobile, tablet, desktop, wide.
+
+Use existing project tokens if present. Extend them only when needed.
+
+### 5. Build Layout First
+
+Every page must define:
+
+- Header/navigation.
+- Main content region.
+- Sidebar/panel if needed.
+- Primary action region.
+- Secondary/supporting content.
+- Footer or persistent actions if needed.
+- Responsive behavior for each region.
+
+Layout rules:
+
+- One clear primary action per screen.
+- Most important content appears first in reading and tab order.
+- Use spacing to group related content.
+- Use consistent max-widths and grid rhythm.
+- Avoid horizontal scrolling except intentional data tables.
+- Do not hide critical actions below unclear menus.
+
+### 6. Build Components with Complete States
+
+Every interactive component must include:
+
+- Default.
+- Hover.
+- Focus-visible.
+- Active/pressed.
+- Selected/current.
+- Disabled.
+- Loading.
+- Error.
+- Success if applicable.
+
+Every screen must include:
+
+- Loading state.
+- Empty state.
+- Error state.
+- Success/confirmation state.
+- Permission denied state if roles/auth exist.
+- Offline/network failure state if network dependent.
+- Partial data state if data can be incomplete.
+
+### 7. Accessibility Is Part of the Build
+
+Minimum: WCAG 2.2 AA.
+
+Required:
+
+- Use semantic HTML first.
+- Buttons are buttons; navigation links are links.
+- Every input has a visible label.
+- Error text is associated with the field.
+- Keyboard can reach and operate every control.
+- Focus order matches visual/task order.
+- Focus-visible styles are obvious.
+- Text contrast meets AA.
+- UI control contrast meets AA where applicable.
+- Do not rely on color alone.
+- Icon-only controls have accessible names.
+- Modals/drawers trap focus and restore focus on close.
+- Menus/popovers support keyboard and Escape.
+- Motion respects reduced-motion preferences.
+- Images have useful alt text or are marked decorative.
+- Touch targets are ideally 44x44 px.
+
+### 8. Responsive Rules
+
+Design mobile, tablet, desktop, and wide behavior.
+
+Check:
+
+- 320px minimum width.
+- 375px mobile.
+- 768px tablet.
+- 1024px desktop.
+- 1440px wide.
+
+Required decisions:
+
+- What stacks?
+- What becomes a drawer?
+- What becomes cards instead of tables?
+- What remains sticky?
+- What content is hidden, collapsed, or prioritized?
+- How does the keyboard affect mobile forms?
+
+Do not simply shrink desktop UI.
+
+### 9. Forms and Validation Rules
+
+Forms must include:
+
+- Visible labels.
+- Required/optional clarity.
+- Helper text where useful.
+- Correct input types and autocomplete.
+- Inline validation after user interaction.
+- Clear error messages that explain how to fix the issue.
+- Submit loading state.
+- Disabled state with reason when not obvious.
+- Data preservation after errors.
+- Success confirmation.
+
+Avoid:
+
+- Placeholder-only labels.
+- Validation before the user interacts.
+- Generic messages like `Invalid input`.
+- Clearing user input on failure.
+
+### 10. Content and Microcopy Rules
+
+Every screen needs:
+
+- Clear H1 matching the user's task.
+- CTA labels that describe the next action.
+- Helpful empty state with next action.
+- Recovery-focused error copy.
+- Success copy that confirms what happened.
+- Destructive action copy that explains consequences.
+
+Copy must be specific, concise, human, and action-oriented.
+
+### 11. Branding and Visual Quality Rules
+
+Use selected brand method to define:
+
+- Personality.
+- Color strategy.
+- Typography feel.
+- Layout rhythm.
+- Imagery/icon style.
+- Motion style.
+- Density.
+
+Quality rules:
+
+- Use one dominant visual idea per screen.
+- Limit accents; reserve strong color for action or meaning.
+- Use consistent spacing and alignment.
+- Match visual density to product type.
+- Avoid random gradients, shadows, glassmorphism, and animations unless they support the chosen method.
+- Do not use top-brand inspiration to copy protected assets or exact identity.
+
+### 12. Data and API UX Rules
+
+For every data-driven screen, define:
+
+- Loading behavior.
+- Empty response behavior.
+- Error response behavior.
+- Partial data behavior.
+- Pagination/infinite scroll behavior.
+- Refresh behavior.
+- Optimistic update or confirmation behavior.
+- Permission/authorization behavior.
+- Validation errors from backend.
+
+Never show raw backend errors to users. Translate them into helpful recovery copy.
+
+### 13. Navigation and IA Rules
+
+Navigation must:
+
+- Match user vocabulary.
+- Show current location.
+- Keep common tasks close.
+- Separate primary, secondary, and utility navigation.
+- Support keyboard and mobile.
+- Avoid hiding frequent tasks in overflow menus.
+
+For large products, route by user intent: role, task, industry, product category, or lifecycle stage.
+
+### 14. Performance Perception Rules
+
+Frontend should feel fast even when data is slow.
+
+Required:
+
+- Show immediate feedback after actions.
+- Use skeletons for structured content loads over 500ms.
+- Avoid layout shift.
+- Lazy-load non-critical media.
+- Keep hero media optimized.
+- Avoid blocking UI with unnecessary modals.
+- Use optimistic UI only when rollback is safe.
+
+### 15. Security, Trust, and Ethics Rules
+
+Include trust cues when users face risk:
+
+- Price/cost clarity.
+- Privacy/data usage explanation.
+- Permission explanation.
+- Secure payment/account cues.
+- Confirmation before destructive actions.
+- Undo when possible.
+- Clear distinction between human and AI-generated content if relevant.
+
+Avoid dark patterns:
+
+- Hidden costs.
+- Forced continuity.
+- Confirm-shaming.
+- Fake scarcity.
+- Obstructive cancellation.
+- Misleading defaults.
+
+### 16. Frontend QA Checklist
+
+Before marking implementation complete, verify:
+
+- [ ] Primary flow works end-to-end.
+- [ ] Secondary flow works.
+- [ ] Loading state appears.
+- [ ] Empty state appears.
+- [ ] Error state appears and has recovery copy.
+- [ ] Success state appears.
+- [ ] Disabled state is understandable.
+- [ ] Keyboard-only usage works.
+- [ ] Focus states are visible.
+- [ ] Screen reader names are meaningful for icon controls.
+- [ ] Forms have labels and associated errors.
+- [ ] Color contrast meets WCAG AA.
+- [ ] Layout works at 320, 375, 768, 1024, and 1440 px.
+- [ ] No critical action is hover-only.
+- [ ] Mobile nav works.
+- [ ] Tables/lists are usable on mobile.
+- [ ] Motion respects reduced-motion.
+- [ ] Copy is specific and human.
+- [ ] Component styling is consistent with tokens.
+- [ ] No console errors.
+- [ ] No broken images or missing assets.
+- [ ] No copied protected logos/assets unless owned by the user.
+
+### 17. Implementation Handoff Checklist
+
+When handing off or summarizing frontend work, include:
+
+- Files changed.
+- Components created/modified.
+- Tokens added/used.
+- UX method selected.
+- States implemented.
+- Accessibility measures.
+- Responsive behavior.
+- Known limitations.
+- Test/QA commands run.
+- Screenshots or visual verification if available.
+
+## Agent Stop Condition
+
+Do not stop at "implemented the UI" if verification has not happened. Run available checks, inspect the result, and fix issues found. If browser or visual tools are available, visually verify the page. If tests/lint/build exist, run them. If no automated checks exist, perform the manual QA checklist and report what was verified.
+
+## Advanced Deployment Checks
+
+### Platform-Specific Implementation
+
+- Follow the target platform conventions from `references/platform-guidelines.md`.
+- Do not force desktop web patterns into mobile/native contexts.
+- Implement Back, Escape, focus restoration, safe-area, zoom, and reduced-motion behavior where applicable.
+
+### Internationalization Implementation
+
+- Avoid hardcoded concatenated strings that cannot be translated.
+- Allow text expansion and wrapping.
+- Use locale-aware date, number, currency, phone, address, and name formatting where relevant.
+- Test RTL or bidirectional layout when target locales require it.
+
+### Privacy and Consent UI
+
+- Do not preselect optional consent.
+- Make destructive, paid, public, or data-sharing actions explicit.
+- Provide clear recovery or cancellation paths where appropriate.
+
+### Advanced Accessibility Widgets
+
+- For dialogs, tabs, menus, comboboxes, data grids, toasts, drag/drop, and live updates, follow `references/accessibility-advanced-patterns.md`.
+- Specify keyboard model, focus behavior, accessible name/state, and announcements.
+
+### Measurable Frontend Quality Gates
+
+- Build/lint/test command passes when available.
+- Main task can be completed at 320px, 768px, 1024px, and 1440px.
+- Keyboard-only path completes the main task.
+- Console has no new runtime errors in the changed flow.
+- Loading, empty, error, success, disabled, permission, and offline/partial states are handled when applicable.