@umacloud/knowledge 1.0.1

package/development/11-ui-excellence/ui-engineering-excellence.md

@@ -0,0 +1,435 @@
+---
+id: ui-engineering-excellence
+title: UI Engineering Excellence - Comprehensive Guide
+domain: development
+category: 11-ui-excellence
+difficulty: intermediate
+tags: [aesthetic, architecture, component, development, direction, engineering, excellence, standard]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# UI Engineering Excellence - Comprehensive Guide
+
+> Consolidated reference for UI development lifecycle: aesthetic system, component standards, layout, motion, accessibility, theming, copywriting, scene recipes, anti-patterns, and release readiness.
+
+---
+
+## 1. Aesthetic System & Visual Direction
+
+### 1.1 Visual Identity Definition
+
+Every product must define a primary visual tone before any UI work begins. Choose exactly one from the following directions:
+
+| Direction | Characteristics | Typical Use |
+|-----------|----------------|-------------|
+| Professional & Steady | Muted palette, generous whitespace, conservative type scale | Enterprise SaaS, B2B platforms |
+| Tech & Futuristic | High-contrast accents, geometric shapes, mono-width fonts | Developer tools, data platforms |
+| Warm & Energetic | Rounded corners, vibrant secondary colors, friendly illustration | Consumer apps, community platforms |
+| Premium & Refined | Minimal decoration, ample margins, serif or refined sans-serif | Luxury e-commerce, fintech portals |
+
+Rules:
+- Products within the same business line must not adopt conflicting directions.
+- Every new page must pass a style-consistency review before launch.
+- Visual direction must be documented in the project UIUX artifact and referenced by all designers and engineers.
+
+### 1.2 Visual Hierarchy Rules
+
+Three tiers of information weight govern every screen:
+
+- **Tier 1 (Primary)**: Maximum contrast and strongest typographic weight. Reserved for the single most important element per viewport (e.g., primary CTA, key metric).
+- **Tier 2 (Secondary)**: Supports relationships and context without competing with Tier 1. Uses medium contrast and standard weight.
+- **Tier 3 (Tertiary)**: Auxiliary content presented with low contrast and compact layout. Must never obstruct the task path.
+
+Enforcement: during design review, every element must be tagged with its tier. A page with more than one Tier 1 element per viewport fails review.
+
+### 1.3 Color System
+
+Adopt a three-layer color model:
+
+1. **Brand Colors**: Primary and secondary brand hues. Derived from the visual direction.
+2. **Semantic Colors**: `success`, `warning`, `error`, `info`. Mapped consistently across all components.
+3. **Neutral Colors**: Grays used for backgrounds, borders, text, and dividers. At least 7 steps from lightest to darkest.
+
+Hard rules:
+- No more than 2 action colors (primary + secondary CTA) per page.
+- Warning and error colors must have a unified semantic mapping; never reuse `error-red` for decorative purposes.
+- Contrast ratios must satisfy WCAG 2.2 AA minimum (4.5:1 for normal text, 3:1 for large text).
+
+### 1.4 Typography System
+
+Define at least three type-size tiers:
+
+| Tier | Usage | Example Sizes (Desktop / Mobile) |
+|------|-------|----------------------------------|
+| Heading | Page title, section header | 28-32px / 22-26px |
+| Body | Paragraphs, descriptions, table cells | 14-16px / 14-15px |
+| Caption | Labels, timestamps, help text | 12-13px / 11-12px |
+
+Rules:
+- Line-height prioritizes readability: minimum 1.4 for body text, 1.2 for headings.
+- Long-text regions must control character density: 60-80 characters per line on desktop, 35-50 on mobile.
+- Never sacrifice legibility for "compact" layouts.
+
+### 1.5 Texture & Depth System
+
+- Use shadow, border, blur, and opacity in proportion to element layer depth.
+- Avoid stacking decorative effects that create visual noise.
+- Every decorative element must serve information grouping or visual guidance -- never purely ornamental.
+
+---
+
+## 2. Theme & Token Architecture
+
+### 2.1 Token Layering Model
+
+```
+Foundation Tokens       Semantic Tokens         Component Tokens
+-------------------     -------------------     -------------------
+color-gray-100          color-bg-primary        button-bg-default
+color-blue-500          color-text-success      input-border-error
+spacing-4               spacing-section         card-padding
+radius-sm               radius-interactive      modal-radius
+shadow-sm               shadow-elevated         dropdown-shadow
+font-size-14            font-size-body          table-cell-font-size
+```
+
+Three layers:
+1. **Foundation Tokens**: Raw values -- colors, sizes, radii, shadows, spacing.
+2. **Semantic Tokens**: Mapped to meaning -- `primary`, `success`, `warning`, `error`, `info`, `bg-surface`, `text-muted`.
+3. **Component Tokens**: Scoped to specific components -- `button-bg-disabled`, `input-border-focus`, `card-shadow-hover`.
+
+### 2.2 Theme Strategy
+
+Required theme support:
+- **Light Mode**: Default. Full semantic token set.
+- **Dark Mode**: Inverted neutrals with adjusted semantic colors for contrast. Never a simple CSS `invert()`.
+- **High Contrast Mode**: Meets WCAG AAA (7:1 ratio). Removes subtle decorations.
+
+Rules:
+- Theme switching must be flicker-free (no FOUC).
+- Multi-brand scenarios use brand-extension tokens that overlay the semantic layer without breaking it.
+- Theme variables must be switchable at both build time (CSS custom properties) and runtime (JS context / CSS class toggle).
+
+### 2.3 Engineering Constraints
+
+- Hardcoding brand colors or state colors in component styles is forbidden.
+- Component styles must reference only semantic tokens or component tokens.
+- Token files must be the single source of truth; no duplicate definitions allowed.
+
+---
+
+## 3. Component Excellence Standard
+
+### 3.1 Component Layering
+
+| Layer | Examples | Scope |
+|-------|----------|-------|
+| Atom | Button, Input, Badge, Icon, Avatar | Reusable across all contexts |
+| Molecule | SearchBar, FormGroup, FilterBar, Card | Combine 2-5 atoms for a single purpose |
+| Organism | OrderPanel, UserProfile, WorkbenchModule | Business-specific, composes molecules |
+
+### 3.2 State Completeness Matrix
+
+Every interactive component must implement all applicable states:
+
+| State | Required | Notes |
+|-------|----------|-------|
+| Default | Yes | Idle, no interaction |
+| Hover | Yes | Mouse over (desktop) |
+| Focus | Yes | Keyboard / assistive technology focus ring visible |
+| Active / Pressed | Yes | During click / tap |
+| Disabled | Yes | Non-interactive, visually muted |
+| Loading | Conditional | For async actions |
+| Error | Conditional | For validation or network failure |
+| Empty | Conditional | For containers with no data |
+| Success | Conditional | Post-action confirmation |
+| Recovery | High-risk only | Retry / fallback state after failure |
+
+Enforcement: component PR reviews must include a state coverage checklist.
+
+### 3.3 Interaction Contract
+
+Each component must define:
+- **Input Props**: Types, defaults, required vs optional.
+- **Events / Callbacks**: Emitted events and payload shapes.
+- **Boundary Behavior**: What happens at min/max values, empty input, overflow text.
+- **Error Feedback**: Inline messages, tooltip, or toast for invalid states.
+- **Keyboard Path**: Tab order, Enter/Space activation, Escape dismissal.
+- **Focus Visibility**: Visible focus indicator meeting WCAG requirements.
+
+### 3.4 Maintainability Rules
+
+- Styles must use tokens; hardcoded color / spacing values fail lint.
+- Component documentation must include usage scenarios and forbidden scenarios.
+- Breaking changes must be declared in a changelog with migration instructions.
+- Shared components must have visual regression snapshot tests.
+
+---
+
+## 4. Layout & Visual Hierarchy
+
+### 4.1 Layout Strategy by Context
+
+**Information-Dense Backends (Admin / Dashboard)**
+- 12-column grid with modular zones (sidebar, header, content, detail panel).
+- Consistent gutter and margin tokens.
+- Collapsible sidebar for focus mode.
+
+**Content Display Pages (Marketing / Docs)**
+- Reading-rhythm layout: comfortable whitespace, limited columns.
+- Max content width: 720-800px for readability.
+- Section anchors for long-form navigation.
+
+**Mobile Interfaces**
+- Single-column flow by default.
+- Thumb-reachable zones for primary actions (bottom 40% of screen).
+- Sticky headers and floating action buttons for critical actions.
+
+### 4.2 Visual Hierarchy Enforcement
+
+- Primary action must appear in a stable, predictable location across all pages.
+- Secondary actions must be visually de-emphasized (outlined or text-only buttons).
+- Auxiliary information uses low contrast and compact arrangement.
+- Never move the position of high-frequency buttons between releases.
+
+### 4.3 Scene-Specific Layout Rules
+
+**Dashboard**
+- Zone 1: Key metric cards (top, high contrast).
+- Zone 2: Trend charts (middle, moderate emphasis).
+- Zone 3: Anomaly / alert feed (bottom or side, attention color on trigger).
+
+**Form Page**
+- Step-based progression for > 5 fields.
+- Group related fields with labeled sections.
+- Separate risk-related inputs with warning context.
+
+**Detail Page**
+- Summary section first (key fields at a glance).
+- Long content split into anchor-navigable sections.
+- Related actions in a sticky footer or sidebar.
+
+---
+
+## 5. Motion & Micro-Interaction
+
+### 5.1 Motion Purpose
+
+Motion serves three goals:
+1. **Feedback**: Confirm that the system received input (button press, form submit).
+2. **Orientation**: Reduce cognitive jump between states (page transition, panel open).
+3. **Guidance**: Draw attention to new elements or important changes (onboarding, notification).
+
+Motion must never be purely decorative.
+
+### 5.2 Motion Tiers
+
+| Tier | Use Case | Duration | Example |
+|------|----------|----------|---------|
+| Brand Motion | App entry, splash, key transitions | 300-500ms | Logo reveal, hero animation |
+| Functional Motion | Button feedback, state toggle, loading | 120-200ms | Ripple, spinner, toggle slide |
+| Guidance Motion | Onboarding tooltip, highlight pulse | 200-300ms | Pulse ring, slide-in tooltip |
+
+### 5.3 Parameter Baseline
+
+- Fast feedback (press, toggle): 120ms.
+- Standard transition (panel open, tab switch): 200ms.
+- Complex transition (page change, modal): 300ms.
+- Easing: use `ease-out` for entrances, `ease-in` for exits, `ease-in-out` for continuous motion.
+
+### 5.4 Hard Rules
+
+- Prefer opacity and transform (translate) over layout-triggering properties (width, height, margin).
+- Never use high-frequency flashing as a notification mechanism.
+- Must support `prefers-reduced-motion` media query -- disable or minimize all non-essential motion.
+- Motion must not block interaction; animations must be non-blocking or cancellable.
+
+---
+
+## 6. Accessibility (WCAG Compliance)
+
+### 6.1 Baseline
+
+- Minimum compliance: **WCAG 2.2 Level AA**.
+- All core user flows must be completable via keyboard alone.
+- All interactive elements must be reachable via screen reader.
+
+### 6.2 Mandatory Rules
+
+| Area | Requirement |
+|------|-------------|
+| Color Contrast | Text: 4.5:1 normal, 3:1 large. UI components: 3:1 against adjacent colors. |
+| Labels | Every input must have a programmatic label (`<label>`, `aria-label`, or `aria-labelledby`). |
+| Error Messages | Must identify the field and provide a corrective suggestion. |
+| Modals / Dialogs | Must trap focus and release on close (Escape key required). |
+| Icon Buttons | Must have `aria-label` or visually hidden text alternative. |
+| Images | Decorative: `alt=""`. Informational: descriptive alt text. |
+| Dynamic Content | Use `aria-live` for updates that need screen reader announcement. |
+| Skip Links | Provide "Skip to main content" for keyboard users. |
+
+### 6.3 Testing Protocol
+
+1. **Automated Scan**: Run axe-core or Lighthouse Accessibility on every page. Target score >= 95.
+2. **Keyboard Walkthrough**: Tab through all interactive elements; verify visible focus, logical order, and full operability.
+3. **Screen Reader Spot Check**: Test critical flows with VoiceOver (macOS), NVDA (Windows), or TalkBack (Android). Verify semantic correctness.
+4. **Color Blindness Simulation**: Check with protanopia, deuteranopia, and tritanopia filters.
+
+### 6.4 Gate Policy
+
+- Blocking accessibility issues must not ship.
+- Exceptions require a written waiver with remediation deadline (maximum 30 days).
+- Waiver must be approved by accessibility owner and tracked in the issue system.
+
+---
+
+## 7. Content & Copywriting
+
+### 7.1 Principles
+
+- **Task-oriented**: Every string should help the user complete their current task. Avoid abstract slogans.
+- **Actionable errors**: Error messages must include the cause and a suggested next step.
+- **Verb-first buttons**: "Save changes", "Create project", "Send invitation" -- not "OK", "Submit", "Confirm".
+
+### 7.2 Length Rules
+
+| Element | Guideline |
+|---------|-----------|
+| Button label | 1-3 words, verb-first |
+| Heading | Short and specific; no filler words |
+| Body text | Provides context for the heading; break into paragraphs if > 3 sentences |
+| Key notice / alert | Maximum 2 lines; longer content should use expandable sections |
+| Tooltip | 1 sentence maximum |
+
+### 7.3 Scenario-Specific Copy
+
+- **Empty State**: Explain why it is empty and provide an actionable next step ("No projects yet. Create your first project.").
+- **Risk Notice**: State the impact and the rollback path ("This will delete all data in this workspace. This action cannot be undone.").
+- **Success Feedback**: Confirm the result and suggest the next action ("Invoice sent successfully. View sent invoices.").
+- **Loading State**: If > 2 seconds, display a contextual message ("Loading transaction history...").
+
+---
+
+## 8. Scene Recipes
+
+### 8.1 Growth Landing Page
+
+| Aspect | Specification |
+|--------|--------------|
+| Goal | Build value perception and drive conversion within 5 seconds. |
+| Structure | Hero with value proposition -> Social proof / logos -> Feature comparison -> Pricing -> CTA |
+| Style | High-contrast primary visual, clear copy hierarchy, minimal distraction. |
+| Key Metrics | Bounce rate, scroll depth, CTA click-through rate, conversion rate. |
+| Anti-Pattern | Auto-playing video, excessive animation, hiding pricing. |
+
+### 8.2 Enterprise Admin Backend
+
+| Aspect | Specification |
+|--------|--------------|
+| Goal | Enable high-density information consumption while maintaining control. |
+| Structure | Workspace summary -> Filter / search -> Primary data table -> Detail drawer / modal |
+| Style | Stable neutral palette, clear status colors, consistent iconography. |
+| Key Metrics | Task completion time, error rate, filter usage, support ticket volume. |
+| Anti-Pattern | Overloaded sidebar, inconsistent table actions, missing bulk operations. |
+
+### 8.3 Mobile Transaction Flow
+
+| Aspect | Specification |
+|--------|--------------|
+| Goal | Minimize errors and maximize completion rate on small screens. |
+| Structure | Step-based flow -> Risk notice at critical steps -> Confirmation receipt |
+| Style | Large touch targets (min 44x44px), short copy, strong feedback on action. |
+| Key Metrics | Completion rate, error recovery rate, average time to complete. |
+| Anti-Pattern | Tiny tap targets, hidden confirmation, no undo / back capability. |
+
+### 8.4 AI Interaction Interface
+
+| Aspect | Specification |
+|--------|--------------|
+| Goal | Help users understand model capability boundaries and trust output. |
+| Structure | Input zone -> Result zone -> Evidence / source zone -> Suggested next steps |
+| Style | Low decoration, high readability, prominent trust indicators (source citations, confidence). |
+| Key Metrics | Adoption rate, hallucination escape rate, user correction rate. |
+| Anti-Pattern | Hiding uncertainty, no source attribution, streaming without progress indication. |
+
+---
+
+## 9. Anti-Pattern Catalog
+
+### 9.1 Common UI Anti-Patterns
+
+| ID | Anti-Pattern | Symptom | Remedy |
+|----|-------------|---------|--------|
+| AP-01 | Visual polish without task improvement | Completion rate stagnant despite redesign | Measure task success rate before and after; prioritize flow optimization. |
+| AP-02 | Flashy animation over performance | High LCP / INP, motion sickness complaints | Enforce performance budget; require `prefers-reduced-motion` support. |
+| AP-03 | Page-by-page custom design | Style inconsistency, high maintenance cost | Establish shared component library with token enforcement. |
+| AP-04 | Dark mode by CSS inversion | Contrast failures, semantic color corruption | Build proper dark theme token set with manual tuning. |
+| AP-05 | Unstable button placement | User confusion, increased mis-clicks | Lock primary action position per page type; enforce in layout review. |
+| AP-06 | Excessive modal / dialog usage | Task flow interruption, modal fatigue | Use inline expansion, drawer, or toast for non-critical interactions. |
+| AP-07 | Emoji as primary iconography | Inconsistent rendering across platforms | Use a single icon library; reserve emoji for user-generated content. |
+| AP-08 | Purple gradient hero as default | Generic "AI template" appearance | Define product-specific visual direction; ban default gradient templates. |
+
+### 9.2 Detection Signals
+
+- Completion rate drops or bounce rate rises after a UI change.
+- Design review comments repeatedly focus on style inconsistency.
+- Same component behaves differently on different pages.
+- Accessibility audit scores regress between releases.
+
+### 9.3 Structural Remedies
+
+1. Always design the task path first, then layer visual refinement.
+2. Establish a single source of truth for components and tokens.
+3. Gate design decisions with accessibility and performance checks.
+4. Require anti-pattern review as part of every UI PR.
+
+---
+
+## 10. UI Release Checklist
+
+Before any UI change ships to production, verify every item:
+
+### Visual & Style
+- [ ] Visual style matches the product's defined direction.
+- [ ] Key pages pass component-consistency check (no rogue variants).
+- [ ] Color and text contrast meet WCAG 2.2 AA requirements.
+
+### Interaction & Accessibility
+- [ ] Core flows pass keyboard-only walkthrough.
+- [ ] Core flows pass screen reader basic verification.
+- [ ] Focus indicators are visible and follow logical order.
+- [ ] All interactive elements have accessible names.
+
+### Motion & Performance
+- [ ] Animations support `prefers-reduced-motion`.
+- [ ] Performance metrics within budget (LCP, INP, CLS).
+- [ ] No layout shift caused by lazy-loaded content or fonts.
+
+### Content & States
+- [ ] All component states implemented (empty, error, loading, success).
+- [ ] Copy follows task-oriented copywriting rules.
+- [ ] Error messages include cause and next step.
+
+### Regression & Rollback
+- [ ] Visual regression tests pass (diff threshold <= 0.3%).
+- [ ] Rollback style sheet or feature flag is prepared.
+- [ ] Emergency degradation plan documented.
+
+### Sign-Off
+- [ ] Design owner has approved the final build.
+- [ ] Accessibility owner has signed off (or waiver filed).
+- [ ] QA has verified on target browsers and devices.
+
+---
+
+## Agent Checklist
+
+- [ ] Confirm product visual direction is defined before starting UI work.
+- [ ] Verify token architecture (foundation -> semantic -> component) is in place.
+- [ ] Check component state completeness matrix for every new or modified component.
+- [ ] Validate layout follows the correct strategy for its context (admin / content / mobile).
+- [ ] Ensure motion parameters follow the baseline and support reduced-motion.
+- [ ] Run accessibility automated scan and keyboard walkthrough.
+- [ ] Apply copywriting rules to all user-facing strings.
+- [ ] Cross-reference scene recipe for the target page type.
+- [ ] Check against anti-pattern catalog; flag any matches.
+- [ ] Complete the full UI release checklist before merge.