Design QA + Redesign Prep
Reproducible workflow for evaluating AI-generated design drafts against Clapilot design-system guardrails before implementation.
This page defines the reusable workflow and checklist for reviewing AI-generated design drafts before implementation. It is for anyone preparing a redesign or new screen: run drafts through the checklist, then implement with existing Clapilot components. The worked example at the end is historical and kept only as a reference for how to apply the process.
This process keeps new screens visually consistent with Clapilot while still allowing fast AI-assisted exploration.
Research result
Recommendation: use Claude Design or a comparable design-generation tool only as an optional prep step.
Claude Design is useful for fast flow exploration, alternate layouts, stakeholder-visible mockups, and design-to-code handoff bundles. As of its April 17, 2026 launch and the help documentation reviewed in May 2026, it was a research-preview product for Pro, Max, Team, and Enterprise plans, with Enterprise access off by default. It supports conversational design generation, codebase/design-file context, inline comments, export formats, and handoff to coding tools.
For Clapilot, that is valuable but not sufficient. Final implementation must still follow the local component system, token usage, information density, and agent/tool wiring rules in this repository. Do not treat an exported prototype as source of truth.
Decision:
- Worth it partially for early redesign prep, especially for complex module workflows.
- Not worth it as an implementation dependency until generated output consistently maps to existing Clapilot components.
- No lock-in: the same checklist and prompt can be used with Claude Design, Figma, screenshots, or a plain Markdown design review.
Sources:
Required workflow
-
Feature idea to UX flow
- Define the user goal, primary entity, main action, and expected agent involvement.
- Name the target page or module and the current implementation files.
- List the key states: loading, empty, populated, error, success, and permission-limited.
-
AI design exploration
- Ask for 2-3 alternatives only after the core workflow is clear.
- Provide screenshots or links to existing Clapilot screens when possible.
- Include this page, UI Style Guide, and the affected module docs as guardrail context.
- Keep generated artifacts as references: screenshot, PDF, HTML export, or Markdown wireframe.
-
Design-system QA
- Review the draft against the checklist below.
- Record pass/fail notes before implementation starts.
- Reject drafts that require a new visual system unless the feature explicitly calls for one.
-
Implementation with Clapilot components
- Use existing
src/components/ui/*, shared app patterns, tokens, and module conventions. - Preserve expected agent wiring for user-facing workflows.
- Keep API and tool contracts documented when behavior changes.
- Use existing
-
PR evidence
- Include before/after screenshots or a screenshot of the final implemented state.
- Link the design artifact or paste the Markdown wireframe when no external design file is used.
- Mention which checklist items were intentionally traded off.
Design-system checklist
Use this as a review checklist or paste it into an AI design tool.
You are preparing a Clapilot product screen, not a standalone marketing concept.
Product context:
- Clapilot is an AI-native office automation workspace for documents, email, tasks, calendar, modules, and agent-assisted operations.
- The UI should feel dense, operational, calm, and repeatable.
- Final implementation must use existing Clapilot components, tokens, and module patterns.
Global guardrails:
- Do not create a new visual identity, color system, icon style, spacing scale, or card language.
- Prefer compact, information-rich layouts over large editorial sections.
- Avoid excessive whitespace, oversized hero text, decorative gradients, and custom illustrations.
- Use existing navigation, tabs, tables, filters, dialogs, empty states, toasts, and button hierarchy.
- Keep controls predictable: primary action, secondary actions, icon actions, overflow menus.
- Use app tokens for primary, muted, border, background, foreground, success, warning, and destructive states.
- Do not hardcode bright accent colors unless they represent a semantic state.
- Use subtle internal separators only where density requires them.
- Preserve accessible contrast, keyboard focus, loading states, and responsive behavior.
Clapilot surface rules:
- Page-level and module shells should follow the elevated surface pattern from /docs/style.
- Avoid nested cards inside cards.
- Keep rows compact and scannable.
- Use dense tables only for comparison or audit workflows; use review rows for queues.
- Empty states should state what is missing and offer the next useful action.
- Success states should be short toasts or inline confirmations, not separate celebration screens.
Agent and workflow rules:
- If the user can reasonably ask the agent about the feature, define the needed context, tools, or explicit non-support rationale.
- Do not design UI-only workflows when the feature requires chat/live agent reachability.
- Show how pending background agent work, completion, failure, and retry are represented.
Required output:
- Provide 2-3 target screens or states.
- For each screen, list the main entity, primary action, secondary actions, empty/error/loading states, and component mapping.
- Include a short implementation note that names existing Clapilot components/patterns to reuse.
Standard screen patterns
Inbox / Review Queue
Use for tasks that require triage, review, approval, correction, or delegation.
- Header: concise title, entity scope selector, search/filter, primary import/create action.
- Summary: 3-4 compact KPI cards only when they change the next action.
- Body: grouped review rows or a table, depending on density.
- Row content: entity name, source, date, status, confidence/reason, primary action, overflow menu.
- Detail: side panel or full detail screen for rich context; avoid expanding large details inside every row.
- Empty state: explain the source and provide the setup/import action.
- Agent state: show background analysis progress and retry path.
Dashboard / KPI Cards
Use for at-a-glance operational status, not for every landing screen.
- Keep cards compact and comparable.
- Use real operational labels and counts, not decorative summaries.
- Pair KPIs with the next actionable list or queue.
- Avoid one-note color palettes and warning-colored cards unless the data is actually warning-level.
Detail View / Sidepanel
Use when a selected item needs context, history, metadata, comments, or a focused edit/review flow.
- Left/main area: primary content or selected entity details.
- Right/side area: metadata, linked objects, automation status, and actions.
- Keep destructive actions secondary or inside overflow unless they are the explicit task.
- On mobile, prefer a full detail screen over a cramped side panel.
Settings
Use for durable configuration, defaults, connections, and permission-dependent setup.
- Group by job-to-be-done, not by database table.
- Keep dangerous or advanced options visually separate.
- Show saved state and validation inline.
- Avoid mixing daily workflow actions into settings unless the action is setup-only.
Empty States
Use an empty state when the page has no useful rows yet.
- Title: concrete missing object or condition.
- Body: one sentence about where data comes from.
- Action: one primary next step and at most one secondary link.
- Do not use large decorative art for standard app empties.
Success / Toast States
Use success states to confirm work without blocking the next action.
- Toast for simple success.
- Inline banner for persistent async outcomes.
- Detail log or activity row when auditability matters.
- Do not navigate away from the workflow just to show success.
V1 testcase: Finance Inbox Refactor v2
Historical example (May 2026). This prep artifact is kept as a worked example of the process above; it does not describe the current
tax-managerUI. See the module doc for the shipped state.
Target module: tax-manager / Finanzen.
Reference docs:
Screen 1: Zu prüfen / Inbox
+--------------------------------------------------------------------------------+
| Finanzen [Mandant] [2026] [Alle Gruppen] [Importieren] |
+--------------------------------------------------------------------------------+
| Offen zur Prüfung 12 | Belege fehlen 5 | Privat/Auslage 3 | Bereit 18 |
+--------------------------------------------------------------------------------+
| Braucht Prüfung Sort |
| [ ] Telekom Rechnung 129,90 EUR 08.05.2026 Kategorie unklar |
| Quelle: Dokumente Import Status: Review Grund: niedrige Sicherheit |
| [Bestätigen] [Korrigieren] [Mehr] |
| |
| [ ] Stripe Auszahlung 840,00 EUR 07.05.2026 Beleg fehlt |
| Quelle: Bank Status: Review Grund: matching_required |
| [Beleg zuordnen] [Ignorieren] [Mehr] |
+--------------------------------------------------------------------------------+
| Background: Finance Inbox Assistent analysiert 2 neue Vorgänge... |
+--------------------------------------------------------------------------------+
Component mapping:
- Module shell uses the standard elevated surface pattern.
- Filters reuse existing select/input/button primitives.
- KPI cards stay compact and operational.
- Review rows are compact blocks, not large cards with marketing copy.
- Agent progress is an inline status strip, not a modal.
Screen 2: Detailview
+------------------------------------------------------+-------------------------+
| Telekom Rechnung | Prüfung |
| Betrag: 129,90 EUR Datum: 08.05.2026 | Status: Review |
| Anbieter: Telekom Deutschland | Grund: Kategorie unklar |
| Kategorie Vorschlag: Telekommunikation | Sicherheit: Mittel |
| | Aktionen |
| Belegvorschau / Dokumentlink | [Bestätigen] |
| Historie und extrahierte Felder | [Korrigieren] |
| | [Privat markieren] |
| Notizen | [Ignorieren] |
+------------------------------------------------------+-------------------------+
Component mapping:
- Desktop may use a side panel for review metadata and actions.
- Mobile opens this as a dedicated full screen.
- Primary action remains visible without repeating the whole row.
- Document preview and extracted fields stay readable before confirmation.
Screen 3: Übersicht / Archiv kompakt
+--------------------------------------------------------------------------------+
| Archiv [Suche] [Typ] [Kategorie] [Status] |
+--------------------------------------------------------------------------------+
| Datum Anbieter Typ Betrag Kategorie Status |
| 08.05.2026 Telekom Deutschland Beleg 129,90 EUR Telekommun. Erledigt |
| 07.05.2026 Stripe Vorgang 840,00 EUR Einnahmen Erledigt |
| 06.05.2026 DB Fernverkehr Beleg 67,40 EUR Reisen Privat |
+--------------------------------------------------------------------------------+
Component mapping:
- Use a table because archive scanning is comparison-heavy.
- Keep filters in one compact row.
- Do not duplicate Inbox review actions here; expose archive detail and audit metadata.
PR checklist
Before opening a PR for a design-affecting feature:
- Attach or link the design prep artifact.
- Include a before/after or final screenshot.
- Confirm the implementation uses existing Clapilot components/tokens.
- Confirm empty, loading, error, and success states are covered.
- Confirm mobile behavior for list/detail screens.
- Confirm agent/context/tool documentation was updated or explicitly not required.