[Claude Design adoption] PR-A: designs hub + multi-type create wizard

[hqhq1025]

Summary

Implements PR-A from docs/research/28-claude-design-ux-adoption.md — adopts Claude Design's hub navigation and typed project creation flow.

• Designs hub (HubView) with four sibling tabs: Recent / Your designs / Examples / Design systems. Recent and Your designs are wired to a local project list; Examples and Design systems render placeholders that PR-B and PR-C will populate.
• Create modal with four type tabs (Prototype / Slide deck / From template / Other). Each tab shows only its own fields; the CTA stays disabled until the project name is non-empty (and a template is picked, for the From-template tab).
• Project schema lives in packages/shared (Project, ProjectDraft, PROJECT_SCHEMA_VERSION = 1). Persisted to localStorage for now; PR-C will move it to SQLite without a public API change.
• App shell: default view is now hub; the workspace gains a small "All designs" breadcrumb so users can return; ESC walks settings → workspace → hub.
• i18n: full coverage for both en and zh-CN under hub.* and create.*.
• Tokens: every value comes from packages/ui tokens — no hard-coded colors / spacing / typography.

What was deferred (and why)

• Wireframe vs high-fidelity cards — owned by PR-F per the doc; the Prototype form leaves a labeled slot with helper copy.
• Examples gallery contents — owned by PR-B.
• Design systems CRUD + SQLite tables — owned by PR-C; main process untouched here per the file-ownership constraint.
• Auto-suggest project name button — listed as optional in the doc; deferred to keep the PR lean.
• TopBar / global search / status footer — owned by PR-D; left untouched.

PRINCIPLES §5b

• Compatibility: green — no IPC / main / on-disk schema changes; existing 144-test suite passes unchanged.
• Upgradeability: green — Project carries schemaVersion: 1; localStorage payloads validated on read.
• No bloat: green — zero new dependencies; reuses lucide-react + zustand + tokens.
• Elegance: green — single store action per intent; per-type forms < 40 LOC; pure buildDraft helper makes the form testable without DOM.

Test plan

• pnpm typecheck clean
• pnpm lint clean (only pre-existing complexity warnings remain)
• pnpm test — 144 / 144 pass, including new CreateProjectModal.test.ts (6 cases)
• Manual: launch app, land on hub, click "+ New design", create one of each type, confirm it appears in Recent + Your designs and the workspace opens with the correct breadcrumb
• Manual: switch language to zh-CN and re-walk the create flow

Notes for reviewers

• Branch base is main; wt/projects-management was not yet pushed to origin when this branch was cut, so the Project schema is owned here per the doc's fallback clause.
• Modal uses role="dialog" on a <div> (rather than native <dialog>) so that the existing --color-overlay token + click-to-dismiss backdrop continue to behave consistently across themes; suppressed locally with a biome-ignore and a justification.

[github-actions]

Findings

• [Blocker] Silent fallback on project storage read/write errors violates repo constraint and hides data issues from users — catches return [] or no-op without surfacing context in apps/desktop/src/renderer/src/store.ts:147, apps/desktop/src/renderer/src/store.ts:156
  Suggested fix:

  function readStoredProjects(): Project[] {
    if (typeof window === 'undefined') return [];
    const raw = window.localStorage.getItem(PROJECTS_STORAGE_KEY);
    if (!raw) return [];
    const parsed = JSON.parse(raw) as unknown;
    if (!Array.isArray(parsed)) {
      throw new Error('Invalid projects storage payload: expected array');
    }
    return parsed.flatMap((item) => {
      const result = Project.safeParse(item);
      if (!result.success) {
        throw new Error(`Invalid project record in storage: ${result.error.message}`);
      }
      return [result.data];
    });
  }
  
  function persistProjects(projects: Project[]): void {
    if (typeof window === 'undefined') return;
    window.localStorage.setItem(PROJECTS_STORAGE_KEY, JSON.stringify(projects));
  }

• [Blocker] New UI introduces hardcoded sizing values instead of tokenized values, conflicting with the project’s UI-token hard constraint — apps/desktop/src/renderer/src/views/create/SlideDeckForm.tsx:27 (also appears in other added UI lines)
  Suggested fix:

  <input
    type="checkbox"
    checked={speakerNotes}
    onChange={(e) => setSpeakerNotes(e.target.checked)}
    className="mt-[var(--space-1)] w-[var(--size-control-sm)] h-[var(--size-control-sm)] accent-[var(--color-accent)]"
  />

• [Major] Persisted project records are only filtered by schemaVersion and not schema-validated, so malformed local data can pass through and later break hub rendering/sorting — apps/desktop/src/renderer/src/store.ts:141
  Suggested fix:

  return parsed.flatMap((item) => {
    const r = Project.safeParse(item);
    return r.success ? [r.data] : [];
  });

• [Major] Opening an existing project does not reset/load project-scoped workspace state, so users can see stale prompt/preview/messages from a different project (cross-project state leakage) — apps/desktop/src/renderer/src/store.ts:699
  Suggested fix:

  openProject(id) {
    const project = get().projects.find((p) => p.id === id);
    if (!project) return;
    set({
      currentProjectId: id,
      view: 'workspace',
      messages: [],
      previewHtml: null,
      prompt: '',
      generationStage: 'idle',
      isGenerating: false,
      activeGenerationId: null,
    });
  },

Summary

• Review mode: initial
• 4 issues found in the latest diff: 2 blocker, 2 major.
• docs/VISION.md and docs/PRINCIPLES.md were referenced but are unavailable in this checkout (Not found in repo/docs), so constraint checks were based on CLAUDE.md and changed files only.
• Additional residual risk: test coverage in this PR validates buildDraft logic only; there is no coverage for project storage error paths, storage validation, or project switching state isolation.

Testing

• Not run (automation)

open-codesign Bot

[github-actions]

[Blocker] This catch { return [] } is a silent fallback for corrupted/unreadable persisted project data, which conflicts with the repo constraint to surface errors with context.

Suggested fix:

} catch (error) {
  throw new Error(`Failed to read persisted projects: ${String(error)}`);
}

[github-actions]

[Blocker] Hardcoded w-4 h-4 introduces non-tokenized UI sizing in newly added UI code.

Suggested fix:

className="mt-[var(--space-1)] w-[var(--size-control-sm)] h-[var(--size-control-sm)] accent-[var(--color-accent)]"

[github-actions]

[Major] Filtering by schemaVersion alone is not enough to guarantee shape correctness; malformed records can still enter state and fail later during render/sort.

Suggested fix:

return parsed.flatMap((item) => {
  const r = Project.safeParse(item);
  return r.success ? [r.data] : [];
});

[github-actions]

[Major] openProject only switches currentProjectId/view, leaving prior workspace data active; this can show stale content from a different project.

Suggested fix:

set({
  currentProjectId: id,
  view: workspace,
  messages: [],
  previewHtml: null,
  prompt: ,
  generationStage: idle,
  isGenerating: false,
  activeGenerationId: null,
});

[github-actions]

Findings

• [Blocker] Hardcoded control sizing in new UI violates the token-only UI constraint and can drift from centralized theming/scaling, evidence apps/desktop/src/renderer/src/views/create/SlideDeckForm.tsx:27.
  Suggested fix:

  className="mt-[var(--space-1)] w-[var(--size-control-sm)] h-[var(--size-control-sm)] accent-[var(--color-accent)]"

Summary

• Review mode: follow-up after new commits
• 1 issue found in the latest head diff.
• docs/VISION.md and docs/PRINCIPLES.md: Not found in repo/docs.
• Residual risk/testing gap: coverage still does not exercise readStoredProjects() invalid JSON/non-array payload handling or the deferred startup toast path.

Testing

• Not run (automation)

open-codesign Bot

[github-actions]

[Blocker] Hardcoded w-4 h-4 bypasses design tokens and violates the repo UI-token constraint for newly added UI values.

Suggested fix:

className="mt-[var(--space-1)] w-[var(--size-control-sm)] h-[var(--size-control-sm)] accent-[var(--color-accent)]"

[github-actions]

Findings

• [Major] New project creation does not clear prior workspace input context — this can carry previous project attachments/reference URL/selected element into a newly created project, causing unintended prompt context and potential data leakage across projects, evidence apps/desktop/src/renderer/src/store.ts:718 and contrast with the reset done in apps/desktop/src/renderer/src/store.ts:740.
  Suggested fix:

  set({
    projects: next,
    currentProjectId: project.id,
    view: 'workspace',
    createProjectModalOpen: false,
    messages: [],
    previewHtml: null,
    inputFiles: [],
    referenceUrl: '',
    selectedElement: null,
    lastPromptInput: null,
    generationStage: 'idle' as GenerationStage,
    isGenerating: false,
    activeGenerationId: null,
    errorMessage: null,
    lastError: null,
  });

Summary

• Review mode: follow-up after new commits
• 1 issue found in the latest head diff.
• docs/VISION.md and docs/PRINCIPLES.md: Not found in repo/docs.

Testing

• Not run (automation)

open-codesign Bot

[github-actions]

[Major] createProject() resets only part of workspace state; previous inputFiles, referenceUrl, and selectedElement can leak into the new project context. Mirror the full reset already used in openProject() to ensure project isolation.

Suggested fix:

set({
  projects: next,
  currentProjectId: project.id,
  view: 'workspace',
  createProjectModalOpen: false,
  messages: [],
  previewHtml: null,
  inputFiles: [],
  referenceUrl: '',
  selectedElement: null,
  lastPromptInput: null,
  generationStage: 'idle' as GenerationStage,
  isGenerating: false,
  activeGenerationId: null,
  errorMessage: null,
  lastError: null,
});

[github-actions]

Findings

• [Major] createProject does not reset project-scoped workspace inputs — a newly created project can inherit inputFiles, referenceUrl, selectedElement, and generation/error flags from the previously open project, which risks cross-project context leakage and incorrect prompt context, evidence apps/desktop/src/renderer/src/store.ts:718 (partial reset) vs apps/desktop/src/renderer/src/store.ts:740 (full reset used by openProject).
  Suggested fix:

  set({
    projects: next,
    currentProjectId: project.id,
    view: 'workspace',
    createProjectModalOpen: false,
    messages: [],
    previewHtml: null,
    inputFiles: [],
    referenceUrl: '',
    selectedElement: null,
    lastPromptInput: null,
    generationStage: 'idle' as GenerationStage,
    isGenerating: false,
    activeGenerationId: null,
    errorMessage: null,
    lastError: null,
  });

Summary

• Review mode: follow-up after new commits
• 1 issue found in the latest PR diff.
• docs/VISION.md: Not found in repo/docs.
• docs/PRINCIPLES.md: Not found in repo/docs.

Testing

• Not run (automation)

open-codesign Bot

[github-actions]

[Major] createProject() currently performs only a partial state reset. This lets previous project context (inputFiles, referenceUrl, selectedElement, generation/error flags) leak into the newly created project. Mirror the full reset already used in openProject() to preserve project isolation.

Suggested fix:

set({
  projects: next,
  currentProjectId: project.id,
  view: workspace,
  createProjectModalOpen: false,
  messages: [],
  previewHtml: null,
  inputFiles: [],
  referenceUrl: ,
  selectedElement: null,
  lastPromptInput: null,
  generationStage: idle as GenerationStage,
  isGenerating: false,
  activeGenerationId: null,
  errorMessage: null,
  lastError: null,
});

[github-actions]

Findings

• [Blocker] Hardcoded UI values added in renderer components violate the token-only UI constraint (CI-enforced), which can fail policy checks and reintroduce inconsistent sizing contracts, evidence apps/desktop/src/renderer/src/views/create/CreateProjectModal.tsx:86, apps/desktop/src/renderer/src/views/hub/ProjectGrid.tsx:22, apps/desktop/src/renderer/src/App.tsx:138, apps/desktop/src/renderer/src/views/create/fields.tsx:25.
  Suggested fix:

  // 1) Define semantic size tokens in packages/ui (example names)
  :root {
    --layout-sidebar-width: var(--size-panel-sidebar);
    --size-modal-create-max: var(--size-modal-lg);
    --size-card-min: var(--size-card-min);
    --focus-ring-width: var(--size-focus-ring);
  }
  
  // 2) Consume tokens instead of literal px/ch values
  <div className="max-w-[var(--size-modal-create-max)] ..." />
  <div className="... grid grid-cols-[var(--layout-sidebar-width)_1fr]" />
  <ul className="... grid-cols-[repeat(auto-fill,minmax(var(--size-card-min),1fr))]" />
  className="... focus:shadow-[0_0_0_var(--focus-ring-width)_var(--color-focus-ring)]"

Summary

• Review mode: follow-up after new commits
• 1 issue found in the latest PR diff.
• docs/VISION.md: Not found in repo/docs.
• docs/PRINCIPLES.md: Not found in repo/docs.
• Direct provider SDK imports in changed files: Not found.
• New dependencies/license/install-size impact from this diff: Not found.

Testing

• Not run (automation). Added unit tests cover draft-building and project state reset/persist-error paths, but no UI integration coverage for hub/create modal keyboard and accessibility flows.

open-codesign Bot

[github-actions]

[Blocker] This introduces a literal 560px size in renderer UI, which violates the repo's CI-enforced token-only UI rule (packages/ui tokens only, no hardcoded UI values).

Suggested fix:

// add semantic size token in packages/ui, then consume it here
<div className="... max-w-[var(--size-modal-create-max)] ...">

[github-actions]

Findings

• No new high-confidence issues found in added/modified lines of the latest diff.

Summary

• Review mode: follow-up after new commits
• No blocking/major/minor/nit issues identified in this pass.
• docs/VISION.md: Not found in repo/docs.
• docs/PRINCIPLES.md: Not found in repo/docs.
• Residual risk: no UI integration coverage for hub/create modal keyboard flows (focus behavior and ESC handling) in this PR.

Testing

• Not run (automation).

open-codesign Bot