[Claude Design adoption] PR-B: examples gallery

[hqhq1025]

Summary

Implements PR-B of the Claude Design adoption plan (docs/research/28-claude-design-ux-adoption.md §3): a first-class Examples gallery with eight curated starting points. Independent of PR-A — ships the data + view component now and can be wired into the hub when PR-A merges.

• 8 examples in packages/templates/src/examples/: cosmic animation, organic loaders, marketing landing page, customer case study, revenue dashboard, pitch slide, welcome email, mobile habit tracker. Each has id, category, prompt, and a stylised inline SVG thumbnail (~1 KB each, no separate asset files, no bundler loaders).
• Self-contained ExamplesTab.tsx + ExampleCard.tsx under apps/desktop/src/renderer/src/views/hub/. Single onUsePrompt prop hands the chosen example back to the host — no store reads, no IPC. Includes a category filter row and an empty state.
• Full i18n for every example title + description in packages/templates/src/examples/locales/{en,zh-CN}.ts, plus examples.tab / useThisPrompt / categories.* keys in packages/i18n for both locales.
• Vitest coverage for the loader: id uniqueness, prompt + thumbnail validity, en/zh coverage parity, locale fallback, getExample lookup.

Not wired into App.tsx yet — the doc explicitly notes PR-B can ship before PR-A and be wired up after the hub structure lands.

Examples included

id	category	description
cosmic-animation	animation	Animated hero with orbiting rings, glowing sun, sparse stars
organic-loaders	ui	Six hand-drawn CSS/SVG loading indicators
landing-page	marketing	Editorial landing for a productivity tool
case-study	document	Print-ready single-page case study with metrics + quote
dashboard	dashboard	Dark SaaS revenue dashboard, MRR/pipeline/forecast
pitch-slide	presentation	A single 16:9 "Why now" slide
email	email	Table-based 600px transactional welcome email
mobile-app	mobile	Phone-framed habit tracker home screen

(All eight from the suggested list landed; none skipped.)

Constraints

• pre-push hook ran clean (typecheck + lint + tests, no --no-verify).
• Token-driven UI — every color/spacing/radius/typography reads from packages/ui CSS variables.
• No new runtime dependencies. Thumbnails are inline SVG strings rendered via <img src="data:image/svg+xml;utf8,…"> to satisfy Biome's noDangerouslySetInnerHTML.
• Examples loader registers locales the same way as getDemos — adding a third locale = one entry + one file.

Checklist (PRINCIPLES §5b)

• Compatibility: ✅ no schema or IPC changes
• Upgradeability: ✅ category list is open; locale registry mirrors existing getDemos pattern
• No bloat: ✅ zero new deps; eight thumbnails total ≈ 8 KB inline
• Elegance: ✅ self-contained tab — single prop API

Test plan

• pnpm typecheck — all 10 workspaces pass
• pnpm lint — only pre-existing complexity warnings remain
• pnpm test — 138 tests pass; new examples.test.ts adds 7 cases
• Manual: mount <ExamplesTab onUsePrompt={…} /> once PR-A's HubView lands and confirm prompt fills the composer + locale switching updates titles/descriptions live

[github-actions]

Findings

• [Major] Silent locale fallback hides data/configuration errors and conflicts with the "no silent fallbacks" project constraint, because unknown locales are downgraded to English with only console.warn (packages/templates/src/examples/index.ts:120).
  Suggested fix:

  function getRegistry(locale: string | undefined): Record<string, ExampleContent> {
    const target = normalizeLocale(locale);
    const reg = REGISTRY[target];
    if (!reg) {
      throw new Error(
        `[templates/examples] unsupported locale "${target}". Supported: ${availableLocales.join(', ')}`,
      );
    }
    return reg;
  }

• [Major] Missing localized content silently degrades to empty/placeholder values, which can mask data integrity regressions (packages/templates/src/examples/index.ts:132).
  Suggested fix:

  export function getExamples(locale?: string): LocalizedExample[] {
    const reg = getRegistry(locale);
    return EXAMPLES.map((ex) => {
      const content = reg[ex.id];
      if (!content) {
        throw new Error(`[templates/examples] missing localized content for id "${ex.id}"`);
      }
      return { ...ex, ...content };
    });
  }

• [Minor] Hardcoded font size bypasses UI token usage requirements (apps/desktop/src/renderer/src/views/hub/ExampleCard.tsx:48).
  Suggested fix:

  <span
    className="
      shrink-0 rounded-full border border-[var(--color-border)]
      px-[var(--space-2)] py-[var(--space-0_5)]
      text-[var(--font-size-caption)] uppercase tracking-wide
      text-[var(--color-text-muted)]
    "
  >

• [Minor] Coverage gap: this PR adds new interactive UI (ExamplesTab filter + onUsePrompt path) but only template-data tests were added; no component test guards the new behavior (apps/desktop/src/renderer/src/views/hub/ExamplesTab.tsx:36).
  Suggested fix:

  it('filters by category and forwards selected example', async () => {
    const onUsePrompt = vi.fn();
    render(<ExamplesTab onUsePrompt={onUsePrompt} />);
  
    await user.click(screen.getByRole('tab', { name: /UI/i }));
    await user.click(screen.getByRole('button', { name: /Use this prompt/i }));
  
    expect(onUsePrompt).toHaveBeenCalledTimes(1);
    expect(onUsePrompt.mock.calls[0][0].category).toBe('ui');
  });

Summary

• Review mode: initial
• 4 issues found (2 Major, 2 Minor).
• docs/VISION.md and docs/PRINCIPLES.md: Not found in repo/docs in this checkout, so policy checks were based on CLAUDE.md and the changed files.

Testing

• Not run (automation)

[github-actions]

[Major] Silent fallback via console.warn + English default hides runtime/config errors and conflicts with the repo's no-silent-fallback rule.

Suggested fix:

if (!reg) {
  throw new Error(
    `[templates/examples] unsupported locale "${target}". Supported: ${availableLocales.join(', ')}`,
  );
}

[github-actions]

[Major] reg[ex.id] ?? enExamples[ex.id] + placeholder return can silently mask missing localization entries. Fail fast with context instead.

Suggested fix:

const content = reg[ex.id];
if (!content) {
  throw new Error(`[templates/examples] missing localized content for id "${ex.id}"`);
}
return { ...ex, ...content };

[github-actions]

[Minor] Hardcoded text-[10px] bypasses design token usage.

Suggested fix:

text-[var(--font-size-caption)]

[github-actions]

[Minor] New interactive behavior is untested (filtering + onUsePrompt wiring). Consider adding a renderer component test for this entrypoint.

Suggested fix:

it('filters by category and forwards selected example', async () => {
  const onUsePrompt = vi.fn();
  render(<ExamplesTab onUsePrompt={onUsePrompt} />);
  await user.click(screen.getByRole('tab', { name: /UI/i }));
  await user.click(screen.getByRole('button', { name: /Use this prompt/i }));
  expect(onUsePrompt).toHaveBeenCalledTimes(1);
});

[github-actions]

Findings

• [Blocker] Hardcoded pixel font size violates token-only UI constraint — text-[10px] bypasses packages/ui typography tokens and breaks the CI-enforced rule that UI values must come from tokens, evidence apps/desktop/src/renderer/src/views/hub/ExampleCard.tsx:48.
  Suggested fix:

  <span
    className="
      shrink-0 rounded-full border border-[var(--color-border)]
      px-[var(--space-2)] py-[var(--space-0_5)]
      text-[var(--font-size-body-xs)] uppercase tracking-wide
      text-[var(--color-text-muted)]
    "
  >

• [Major] Silent fallback hides localization data errors — when an example id is missing in locale content, the code returns { title: ex.id, description: '' } instead of surfacing an error; this violates the "no silent fallbacks" constraint and can ship broken cards without visibility, evidence packages/templates/src/examples/index.ts:132 and packages/templates/src/examples/index.ts:136.
  Suggested fix:

  const content = reg[ex.id] ?? enExamples[ex.id];
  if (!content) {
    throw new Error(
      `[templates/examples] missing localized content for example id "${ex.id}" (locale: "${normalizeLocale(locale)}")`,
    );
  }
  return { ...ex, ...content };

Summary

• Review mode: initial
• 2 issues found in added/modified lines: 1 blocker (token constraint breach), 1 major (silent fallback for missing locale content).
• Constraint checks: direct provider SDK imports not found in diff; new runtime dependencies/license/install-size impact not found in diff; DCO sign-off present.
• Residual risk: renderer behavior/accessibility for the new tab/card components is not covered by UI tests in this PR.

Testing

• Not run (automation)
• Suggested tests: add a renderer Vitest test for ExamplesTab filter behavior and onUsePrompt callback wiring; add a failure-path test asserting getExamples throws on missing locale content for an EXAMPLES id.

open-codesign Bot

[github-actions]

text-[10px] hardcodes typography in app UI. This violates the token-only UI rule; use a --font-size-* token instead (for example text-[var(--font-size-body-xs)]).

[github-actions]

This is a silent fallback for missing locale content ({ title: ex.id, description: }). Please throw with context here so data errors are surfaced instead of rendering degraded UI silently.

[github-actions]

Findings

• [Blocker] Silent fallback on missing locale content violates the no-silent-fallback constraint — getExamples currently returns { title: ex.id, description: '' } when locale content is missing, which can ship degraded UI without surfacing an error, evidence packages/templates/src/examples/index.ts:133 and packages/templates/src/examples/index.ts:136.
  Suggested fix:

  const content = reg[ex.id] ?? enExamples[ex.id];
  if (!content) {
    throw new Error(
      `[templates/examples] missing localized content for example id "${ex.id}" (locale: "${normalizeLocale(locale)}")`,
    );
  }
  return { ...ex, ...content };

Summary

• Review mode: follow-up after new commits
• 1 blocker found in added/modified lines.
• Prior font-token issue is no longer present in this head.
• docs/VISION.md and docs/PRINCIPLES.md: Not found in repo/docs.

Testing

• Not run (automation)
• Suggested tests: add a failure-path test asserting getExamples throws when an EXAMPLES id has no locale content.

open-codesign Bot

[github-actions]

This still silently degrades on missing locale content by returning { title: ex.id, description: '' }. To satisfy the no-silent-fallback rule, throw with context here instead.

const content = reg[ex.id] ?? enExamples[ex.id];
if (!content) {
  throw new Error(
    `[templates/examples] missing localized content for example id "${ex.id}" (locale: "${normalizeLocale(locale)}")`,
  );
}
return { ...ex, ...content };

[github-actions]

Findings

• No high-confidence issues found in added/modified lines.

Summary

• Review mode: follow-up after new commits
• No blocker/major/minor/nit issues identified in the current diff.
• Prior silent-fallback blocker appears addressed in packages/templates/src/examples/index.ts:133.
• docs/VISION.md and docs/PRINCIPLES.md: Not found in repo/docs.

Testing

• Not run (automation)
• Residual risk/testing gaps: no renderer-level tests in this PR for ExamplesTab filter interactions and ExampleCard onUsePrompt callback wiring.

open-codesign Bot