Source Document
The canonical guideline lives in the gems-project repository. This portal page is a PM-readable summary.
docs/Tatekan/TATEKANOS_UI_UX_Canonical_Guideline.mdCanonical UI/UX Guideline (18 sections, 574 lines)
Open in GitHub
Scope and Precedence
- Applies to: Toriteki, Mitsumori, TATEKAN Control, dMemo, TATEKAN Time, and all future apps.
- Hierarchy: Family canonical > Product supplements > Screen-level decisions.
- Product supplements may narrow or extend family rules but must not contradict them.
- Legacy Toriteki UX doc is reclassified as a product supplement, not the family baseline.
Before Building
Three Required Artifacts
- Visual Thesis -- what the screen looks like (layout, color, spacing)
- Content Plan -- what text appears (labels, errors, empty states)
- Interaction Thesis -- how the screen behaves (transitions, loading, keyboard)
Design Defaults
App/Admin Screens
- Few colors, one accent per product, minimal chrome
- No dashboard-card mosaics, no ornamental icons
- Task-first density: dense is OK, but must be scannable
- One clear primary action per screen
Safety
Safe-by-Default Actions
- Destructive actions are visually separated and require confirmation
- Consequence text is mandatory before delete/cancel/reject
- Progressive complexity: advanced controls hidden by default
Maturity
Respect Existing Workflows
- Redesign should reduce friction, not force novelty
- Existing product UI language is preserved on mature screens
- Family-wide cleanup is allowed when explicitly approved by PM
Completion Gates
No UI change ships without passing all three gates.
- Gate 1:
code_checked -- valid HTML, i18n-wrapped text, shared components reused, no inline styles
- Gate 2:
ui_verified_desktop -- verified at 1366x768; visual hierarchy clear; primary action above fold; skeleton loading states
- Gate 3:
ui_verified_mobile -- verified at 390x844; touch targets 44px min; single-column forms; card fallback for tables
What To Avoid
- Prohibited everywhere: dashboard-card mosaics, ornamental icons, placeholder-only labels, color-only state indicators, modal dialogs for success, hover-only interactions, infinite scroll on data tables
- Prohibited in business workflows: scarcity cues, decoy pricing, variable reward, gamification (points/badges/streaks), dark patterns
- Narrow exceptions for true marketing surfaces require explicit PM approval
Key Sections in Full Document
- 1. Purpose
- 2. Scope and Precedence
- 3. Core Principles (6 sub-principles)
- 4. Screen Types (app/admin, public intake, marketing)
- 5. Visual System (color, typography, spacing, hierarchy, design tokens)
- 6. Information Architecture (navigation, page structure, progressive disclosure, empty states)
- 7. Forms and Data Entry (labels, validation, save/cancel, destructive actions)
- 8. Table and List Ergonomics (headers, filtering, row actions, mobile fallback, pagination)
- 9. Interaction Rules (Doherty threshold, skeleton screens, feedback, keyboard, click targets)
- 10. Status and Workflow Visibility (state awareness, step indicators, status badges)
- 11. Copy Rules (i18n, tone, terminology consistency)
- 12. Accessibility and Responsiveness (WCAG 2.1 AA, breakpoints, mobile/desktop rules)
- 13. AI-Assisted UI Design Rules
- 14. Completion Gates
- 15. What To Avoid
- 16. Product-Specific Supplements
- 17. Canonical Adoption Notes
- 18. Summary