Requirement Editor UX

If the Requirement Editor is:

• too loose → it becomes a document tool
• too rigid → juniors hate it
• too complex → they avoid writing

So we need:

Structured, guided, but not bureaucratic.

Let’s design it properly.

Goal of the Requirement Editor

When someone writes a requirement, the UI should:

1. Encourage clarity
2. Prevent vagueness
3. Teach good engineering habits
4. Feel fast and modern

Not academic. Not heavy.

Core Design Principle

A requirement is a structured object — not a paragraph.

So we avoid:

• Large free-text editor
• Floating formatting toolbars
• Document-like UI

Instead we use:

• Field-based structured layout
• Clean visual hierarchy
• Subtle guidance

Layout Structure

Use a 2-column layout

--------------------------------------------
Main Editing Area | Context Panel
--------------------------------------------

Main Editing Area

Structure it into clear blocks.

Header Block (Identity & Metadata)

Horizontal row:

REQ-001      [FUNCTIONAL ▼]   [MUST ▼]   [DRAFT ▼]

UX Notes

• ID is auto-generated but editable
• Dropdowns are compact pills
• Status should be right-aligned
• Use color subtly for priority

Example:

Don’t overdo it.

Requirement Statement (Most Important Field)

Label:

Requirement Statement *

Large textarea.

Placeholder:

The system shall allow users to reset their password via email verification.

Smart Micro-Guidance (Very Powerful)

Under the field:

Small muted hint:

Use “The system shall…” for clarity and testability. Not mandatory — just guidance.

Optional (v0.2+)

Light lint warning:

If user writes:

The system should be fast

Show:

Warning: “Fast” is ambiguous. Consider measurable criteria.

Rationale (Optional but Important)

Collapsible section:

▼ Rationale

Textarea.

Explain:

Why is this requirement necessary?

This trains thinking.

Acceptance Criteria (Structured, Not Paragraph)

This is where you differentiate your app.

Layout

Acceptance Criteria
-------------------------------------
[ + Add Criterion ]

Each criterion as a small card:

Given ...
When ...
Then ...

OR simple mode:

• User receives email within 30 seconds

UX Decision (Important)

Do NOT force Gherkin in v0.1.

Allow simple bullet criteria:

Criterion text field

Later:

• Add toggle for structured Given/When/Then

Why This Matters

This teaches:

• Requirements must be testable
• Clarity > verbosity

Context Panel (Right Side)

Dynamic, lightweight.

When editing a requirement, show:

Section: 3.1 Functional Requirements
Created: Jan 10
Last edited: Jan 12
Acceptance Criteria: 2

Optional:

Checklist:

- Has acceptance criteria
- Priority assigned
- Clear statement

This is subtle discipline.

Save Strategy

Avoid “Save” button spam.

Use:

• Auto-save (debounced)
• Small status indicator:

Saved (checkmark)
Saving...

Never make juniors fear losing content.

Edit Modes

Two possible approaches:

Option A — Always Editable (Recommended v0.1)

Fields are editable immediately.

Cleaner.

Option B — View Mode / Edit Mode

More enterprise-feeling.

Not necessary for MVP.

Flow for Creating a New Requirement

1. Click “Add Requirement”
2. Open in editor immediately
3. Auto-generate ID:

REQ-003

4. Focus cursor on statement field
5. Status = DRAFT by default
6. Priority defaults to SHOULD

Minimize friction.

Visual Hierarchy

Spacing is critical.

Use:

• Clear section dividers
• Strong field labels
• White space
• No heavy borders

Think Linear.app / GitHub Issues — not SharePoint.

Gentle Constraints That Improve Quality

Add soft validation:

• Statement required
• At least 1 acceptance criterion before marking APPROVED

When user changes status to APPROVED:

If no criteria:

You must add at least one acceptance criterion.

This reinforces discipline without being annoying.

Component Architecture (React)

Break it cleanly:

<RequirementEditor>
  <RequirementHeader />
  <RequirementStatement />
  <RequirementRationale />
  <AcceptanceCriteriaList />
  <ContextPanel />
</RequirementEditor>

Keep it modular.

Future-Proofing Hooks (Don’t Build Yet)

Add DB fields now? No.

But design UI to later support:

• Traceability links
• Impact analysis
• Requirement history
• Review comments
• AI linting

Leave vertical space below statement for future extensions.

What To Avoid

• Rich text formatting toolbar
• Markdown in requirement statement
• Nested comments
• Tabs inside the editor
• Heavy modal flows

Keep it calm.

Why This UX Works for Junior Devs

It:

• Teaches requirement anatomy
• Encourages measurable writing
• Prevents vague feature dumping
• Feels modern
• Doesn’t intimidate

And for you (as architect):

• Maps 1:1 to Prisma model
• Easy API structure
• Clean domain logic
• Scales beautifully