@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/DESIGN.md

@@ -1,929 +0,0 @@
-# Design.md — React Word Editor
-
-## 1. Purpose
-
-This document defines the visual design, interaction style, layout system, and front-end styling principles for the React-based Word-compatible editor component.
-
-Use this together with:
-
-* `README.md` for product scope
-* `docs/plans/master-plan.md` for architecture
-* `docs/roadmap.md` for delivery sequencing
-* `docs/reference/word-review-editor-frontend-architecture.md` for frontend implementation architecture
-
-The component is intended for **legal review workflows**, not general-purpose document creation and not a Microsoft Word clone.
-
-The design must feel:
-
-* clean
-* calm
-* modern
-* highly legible
-* lightweight
-* trustworthy
-* precise
-* review-oriented
-
-The desired experience is closer to:
-
-* TipTap
-* Notion document surfaces
-* Figma-side-panel clarity
-* modern code-review tools
-
-It must **not** feel like:
-
-* Microsoft Word ribbon UI
-* enterprise bloatware
-* dense legacy office software
-* a generic WYSIWYG rich text box
-
----
-
-## 2. Product design goals
-
-The UI must optimize for the realities of legal review:
-
-* long reading sessions
-* frequent review of insertions/deletions
-* comment navigation
-* structured documents with lists and tables
-* low cognitive overhead
-* confidence that the document remains Word-compatible
-
-The design should help users answer these questions instantly:
-
-* What mode am I in?
-* What changed?
-* Where are the comments?
-* What is selected?
-* Is the document safe/saved?
-* What action can I take next?
-
----
-
-## 3. Core design principles
-
-### 3.1 Calm over chrome
-
-The editor should minimize permanent controls and decorative noise.
-
-Use:
-
-* contextual actions
-* restrained separators
-* whitespace for hierarchy
-* compact but comfortable controls
-
-Avoid:
-
-* large toolbars
-* ribbon metaphors
-* heavy outlines everywhere
-* constant multi-color emphasis
-
-### 3.2 Content first
-
-The document surface is the primary product.
-
-The design must make the content area feel:
-
-* spacious
-* readable
-* central
-* stable
-
-Everything else is secondary UI.
-
-### 3.3 Review clarity without aggression
-
-Comments and redlines must be obvious but not visually exhausting.
-
-Use:
-
-* measured annotation color
-* subtle tint backgrounds
-* slim indicators
-* progressive disclosure
-
-Avoid:
-
-* neon diff colors
-* thick borders around every change
-* overwhelming always-on markup density
-
-### 3.4 Precision and trust
-
-The UI should feel deterministic.
-
-Users in legal workflows must feel that:
-
-* the editor is controlled
-* actions are explicit
-* review state is reliable
-* save/export behavior is dependable
-
-### 3.5 Progressive complexity
-
-The default state should be simple.
-
-Only show advanced controls when needed:
-
-* floating formatting tools on selection
-* review controls when review mode is active
-* contextual table tools when table is focused
-* comment tools when a commentable range is selected
-
----
-
-## 4. Overall layout
-
-## 4.1 Primary regions
-
-The component layout consists of:
-
-1. **Top toolbar**
-2. **Document surface area**
-3. **Optional right sidebar** for comments/review
-4. **Optional bottom status bar**
-5. **Floating inline toolbar**
-6. **Contextual popovers/dialogs**
-
-## 4.2 Layout priorities
-
-The document surface must receive the most visual emphasis.
-
-Default width strategy:
-
-* full component width container
-* document centered within available space
-* sidebars dock outside the reading column
-
-Recommended desktop layout:
-
-* toolbar at top
-* centered page/document surface
-* right sidebar for comments and review
-* status bar minimal and low-emphasis
-
-## 4.3 Reading column
-
-The document should sit in a reading column that feels like a paper-informed canvas, but not literal fake paper unless page mode is enabled.
-
-Two supported visual modes:
-
-### Canvas mode (default)
-
-* clean centered surface
-* subtle panel background
-* minimal page framing
-* better for continuous reading and review
-
-### Page mode (optional)
-
-* page-like boundaries
-* light shadow
-* more Word-like print awareness
-* still restrained
-
-Default for legal review should be **Canvas mode**.
-
----
-
-## 5. Toolbar design
-
-## 5.1 Toolbar goals
-
-The toolbar should feel compact, stable, and lightweight.
-
-It is not a ribbon.
-
-It should expose only the highest-value actions persistently.
-
-## 5.2 Toolbar sections
-
-Persistent controls should include:
-
-* undo / redo
-* paragraph style selector
-* bold / italic / underline
-* bullet list / numbered list
-* insert comment
-* track changes toggle
-* markup mode selector
-* save / export
-
-Optional overflow controls:
-
-* image insertion
-* hyperlink insertion
-* table insertion
-* accept/reject controls
-* more formatting
-
-## 5.3 Visual styling
-
-Toolbar should:
-
-* have a low-contrast surface
-* use subtle segmentation
-* avoid heavy button borders
-* use compact icon buttons with clear hover/focus states
-* keep action density moderate
-
-Recommended dimensions:
-
-* toolbar height: 44–52px
-* icon button size: 30–34px
-* horizontal padding: 12–16px
-
----
-
-## 6. Document surface design
-
-## 6.1 Surface role
-
-The editor surface is the emotional center of the component.
-
-It must feel:
-
-* stable
-* elegant
-* highly readable
-* slightly elevated from the app background
-
-## 6.2 Surface styling
-
-Recommended defaults:
-
-* soft neutral app background behind the document
-* white or near-white document panel
-* subtle radius
-* soft shadow only if page framing is used
-* generous interior padding
-
-Suggested desktop spacing:
-
-* outer shell padding: 16–24px
-* document panel max width: 780–920px depending on mode
-* document interior padding: 40–64px
-
-## 6.3 Typography on surface
-
-Prioritize readability over visual novelty.
-
-Defaults should feel appropriate for legal text:
-
-* neutral serif or highly readable system serif for document body, or a sober sans if product direction insists on sans
-* excellent line height
-* moderate paragraph spacing
-* clearly differentiated headings
-
-Recommended body defaults:
-
-* font size: 15–16px
-* line height: 1.55–1.7
-* body text color: deep neutral, not pure black
-
-Headings should feel structured, not editorially dramatic.
-
----
-
-## 7. Sidebar design
-
-## 7.1 Sidebar role
-
-The sidebar is the review companion, not the main stage.
-
-It should contain:
-
-* comments
-* review navigation
-* change summary
-* selected annotation detail
-
-## 7.2 Sidebar behavior
-
-Default:
-
-* docked on the right on desktop
-* collapsible
-* width stable enough for comfortable reading
-
-Recommended width:
-
-* 320–380px
-
-## 7.3 Sidebar styling
-
-* slightly tinted neutral surface
-* subtle divider from document area
-* cards or grouped threads with soft contrast
-* clear active/selected comment state
-* low-noise metadata styling
-
-Comment cards should feel closer to modern discussion UIs than email clients.
-
----
-
-## 8. Review and annotation design
-
-## 8.1 Markup modes
-
-The UI must support at least:
-
-* clean
-* simple markup
-* full markup
-
-### Clean
-
-* review marks hidden from main visual emphasis
-* document reads as final text
-* comments may be discoverable via indicators
-
-### Simple markup
-
-* slim margin or inline indicators
-* low-noise review visibility
-* best default for legal review reading
-
-### Full markup
-
-* insertions/deletions visibly styled inline
-* comments strongly visible
-* intended for detailed review work
-
-## 8.2 Insertions
-
-Insertions should be visible but elegant.
-
-Recommended styling:
-
-* subtle tinted background or underline accent
-* stronger on selection/focus
-* avoid loud green fill blocks
-
-## 8.3 Deletions
-
-Deletions should be readable without dominating the paragraph.
-
-Recommended styling:
-
-* muted red/pink tone
-* strikethrough
-* optional soft background tint in full markup mode
-
-## 8.4 Comment anchors
-
-Commented text should use:
-
-* subtle highlight wash
-* comment-specific accent indicator
-* stronger highlight on hover/focus
-
-Avoid always-on thick borders.
-
-## 8.5 Margin indicators
-
-Where used, indicators should be:
-
-* slim
-* aligned cleanly
-* color-coded but muted
-* clickable
-
----
-
-## 9. Selection and interaction styling
-
-## 9.1 Text selection
-
-Selection should feel native but polished.
-
-Use:
-
-* lightly tinted brand-aware selection color
-* strong enough contrast to confirm range
-* avoid over-saturated browser-default feeling if custom selection is possible safely
-
-## 9.2 Current block focus
-
-A focused paragraph/table/cell can use:
-
-* very subtle background emphasis
-* contextual handles/tools only when useful
-
-## 9.3 Hover philosophy
-
-Hover states should exist but remain understated.
-
-Use:
-
-* small contrast change
-* no dramatic color shifts
-* no jumpy motion
-
-## 9.4 Active state philosophy
-
-The active state must be clearer than hover.
-
-For toolbar controls:
-
-* soft filled background
-* readable icon contrast
-* no thick inset outlines unless focus-visible
-
----
-
-## 10. Floating toolbar and contextual tools
-
-## 10.1 Floating toolbar
-
-Appears on text selection.
-
-Must feel:
-
-* fast
-* lightweight
-* unobtrusive
-
-Include only high-frequency inline actions:
-
-* bold
-* italic
-* underline
-* comment
-* link
-* maybe clear formatting
-
-Visual style:
-
-* compact rounded popover
-* subtle shadow
-* high legibility
-* low decoration
-
-## 10.2 Contextual tools
-
-Show only when contextually relevant:
-
-* table controls when inside table
-* image controls when image selected
-* comment actions when comment active
-* revision actions when change selected
-
----
-
-## 11. Color system
-
-## 11.1 Overall palette strategy
-
-Use a restrained neutral-first palette with disciplined accents.
-
-The UI should primarily rely on:
-
-* whites / near-whites
-* light neutral backgrounds
-* cool or warm gray hierarchy
-* one product accent color
-* reserved review colors
-
-## 11.2 Semantic color groups
-
-### Neutral
-
-Used for:
-
-* shell backgrounds
-* toolbar surfaces
-* dividers
-* typography hierarchy
-* sidebars
-
-### Accent
-
-Used for:
-
-* primary actions
-* focused selected states
-* links
-* active controls
-
-### Comment color
-
-Used for:
-
-* comment anchor indicators
-* comment sidebar highlights
-* active thread emphasis
-
-### Revision colors
-
-Used for:
-
-* insertion
-* deletion
-* review navigation indicators
-
-### Feedback colors
-
-Used for:
-
-* success
-* warning
-* error
-* info
-
-## 11.3 Recommended token ranges
-
-### Neutrals
-
-* background-app
-* background-panel
-* background-surface
-* background-muted
-* border-subtle
-* border-default
-* text-primary
-* text-secondary
-* text-muted
-
-### Accent
-
-* accent-50
-* accent-100
-* accent-500
-* accent-600
-* accent-700
-
-### Review
-
-* comment-100 / 500 / 700
-* insertion-100 / 500 / 700
-* deletion-100 / 500 / 700
-
-Review colors must be muted enough for long sessions.
-
----
-
-## 12. Typography system
-
-## 12.1 Typography goals
-
-Typography should communicate:
-
-* trust
-* hierarchy
-* readability
-* low fatigue
-
-## 12.2 UI typography
-
-UI chrome should use a modern neutral sans.
-
-Recommended scale:
-
-* label-xs
-* label-sm
-* body-sm
-* body-md
-* heading-sm
-* heading-md
-
-Use medium weight sparingly.
-
-## 12.3 Document typography
-
-Document typography should prioritize long-form reading.
-
-Recommended options:
-
-* sober serif for body text
-* or neutral sans if product brand requires it, but keep it highly readable
-
-Headings should follow predictable scale steps.
-
-Avoid dramatic display styles.
-
----
-
-## 13. Spacing and sizing system
-
-Use a consistent spacing scale.
-
-Recommended base unit:
-
-* 4px
-
-Primary spacing tokens:
-
-* 4
-* 8
-* 12
-* 16
-* 20
-* 24
-* 32
-* 40
-* 48
-* 64
-
-Usage guidance:
-
-* controls: 8–12 internal padding
-* toolbar gutters: 12–16
-* panels: 16–24
-* document interior: 40+
-
-The design should feel spacious but not luxurious to the point of wasting space.
-
----
-
-## 14. Shape, borders, and elevation
-
-## 14.1 Radius
-
-Use rounded corners consistently.
-
-Recommended radius tokens:
-
-* small: 6px
-* medium: 10px
-* large: 14px
-* popover/panel: 14–18px
-
-## 14.2 Borders
-
-Prefer subtle borders over heavy outlines.
-
-Use:
-
-* hairline or light 1px neutral borders
-* stronger borders only for active states when needed
-
-## 14.3 Elevation
-
-Use shadow sparingly.
-
-Recommended:
-
-* almost none on baseline surfaces
-* gentle shadow on floating toolbar/popovers/dialogs
-* optional light page shadow in page mode
-
----
-
-## 15. Motion and transitions
-
-Motion should be minimal and utilitarian.
-
-Use only for:
-
-* panel open/close
-* hover/focus refinement
-* popover appearance
-* sidebar transitions
-
-Rules:
-
-* short durations
-* low travel distance
-* no playful bounce
-* no large zoom effects
-
-Prefer 120–180ms for small UI transitions.
-
-Support reduced motion mode.
-
----
-
-## 16. Component-level styling guidance
-
-## 16.1 Buttons
-
-Primary button:
-
-* filled or softly tinted
-* used sparingly for save/export or primary confirmation
-
-Secondary button:
-
-* low-contrast outlined or tinted
-
-Ghost button:
-
-* preferred for toolbar and sidebar actions
-
-Danger button:
-
-* only for destructive flows, visually restrained but clear
-
-## 16.2 Inputs and dropdowns
-
-Must feel simple and modern.
-
-Use:
-
-* medium radius
-* subtle borders
-* strong focus ring
-* compact heights
-
-Avoid enterprise-form heaviness.
-
-## 16.3 Comment cards
-
-Each comment thread should use:
-
-* soft card or grouped panel style
-* clear author/meta hierarchy
-* compact spacing
-* distinct selected state
-
-## 16.4 Status bar
-
-If present, keep it extremely minimal.
-
-Useful items:
-
-* save state
-* track changes state
-* warnings count
-* word compatibility status badge if desired
-
----
-
-## 17. Modes and state-specific appearance
-
-## 17.1 Read-only mode
-
-Read-only mode should:
-
-* remove editing affordances
-* preserve review visibility
-* keep navigation controls available
-* reduce toolbar actions intelligently
-
-## 17.2 Track changes enabled
-
-When track changes is on:
-
-* show a clear but restrained state indicator
-* make review actions discoverable
-* avoid bathing the entire interface in warning color
-
-## 17.3 Comment-focused state
-
-When a comment is selected:
-
-* highlight anchor range more strongly
-* scroll related sidebar thread into focus
-* visually connect thread and anchor subtly
-
-## 17.4 Warning / preserved-content state
-
-For unsupported-preserved content:
-
-* show an explicit but calm warning banner or inline badge
-* do not disrupt reading more than necessary
-* clearly distinguish from fatal errors
-
----
-
-## 18. Accessibility and inclusive design
-
-The visual system must support:
-
-* strong focus-visible states
-* non-color-only distinction for insertions/deletions/comments
-* keyboard navigability
-* clear contrast ratios
-* optional high contrast mode
-* reduced motion
-
-Revision styling must never rely only on color:
-
-* insertions may use underline or indicator shape
-* deletions may use strikethrough plus tone
-* comments may use both tint and marker
-
----
-
-## 19. Responsive behavior
-
-## 19.1 Desktop first
-
-The primary experience is desktop-first.
-
-## 19.2 Narrow layouts
-
-On narrower widths:
-
-* toolbar may collapse into grouped controls
-* sidebar may become overlay/drawer
-* document padding may reduce modestly
-* floating controls remain usable
-
-The document should remain readable before preserving full control density.
-
----
-
-## 20. Styling architecture
-
-Recommended styling approach:
-
-* design tokens first
-* component-scoped styles
-* theme object for overrides
-* clear semantic tokens rather than raw color use
-
-The component should support:
-
-* default theme
-* host overrides through typed theme tokens
-* style isolation to avoid host CSS collisions
-
-Avoid hard-coding visual values directly in individual components where tokens should exist.
-
-### Implementation reference
-
-The canonical frontend implementation architecture, component inventory, theme contract, and
-editing model are defined in `docs/reference/word-review-editor-frontend-architecture.md`.
-That document governs how the design principles in this file are realized in code.
-
----
-
-## 21. Default theme token recommendation
-
-Example token groups:
-
-* `font.ui`
-* `font.document`
-* `font.mono`
-* `size.text.xs/sm/md/lg/xl`
-* `space.1..10`
-* `radius.sm/md/lg/xl`
-* `color.bg.app`
-* `color.bg.panel`
-* `color.bg.surface`
-* `color.border.subtle`
-* `color.border.default`
-* `color.text.primary`
-* `color.text.secondary`
-* `color.text.muted`
-* `color.accent.default`
-* `color.accent.hover`
-* `color.comment.bg`
-* `color.comment.border`
-* `color.comment.text`
-* `color.revision.insert.bg`
-* `color.revision.insert.text`
-* `color.revision.delete.bg`
-* `color.revision.delete.text`
-* `color.warning.bg`
-* `color.warning.text`
-* `color.error.bg`
-* `color.error.text`
-* `shadow.sm/md`
-* `focus.ring`
-
----
-
-## 22. Look-and-feel summary
-
-The component should feel like:
-
-* a premium legal review workspace
-* a focused document environment
-* a modern structured editor
-* calm but capable software
-
-It should not feel like:
-
-* a retro office suite
-* a CMS rich text field
-* a flashy collaboration toy
-* an over-designed consumer writing app
-
-The visual personality should be:
-
-* serious
-* refined
-* efficient
-* low-noise
-* trustworthy
-
----
-
-## 23. Final design rule
-
-When in doubt:
-
-1. privilege readability
-2. reduce noise
-3. keep controls contextual
-4. keep review states clear
-5. preserve trust and precision
-
-The user should always feel that the editor is **quietly powerful and legally reliable**.