Run 3 Organism Port — Byproducts

Date: 2026-03-19

Discoveries

1. ArdaButton vs Button Export Name

The atoms/button index exports ArdaButton, not Button. The worktree source files all used { Button } from @/components/ui/button (the shadcn primitive). When rewriting to @/components/canary/atoms/button, the import becomes { ArdaButton as Button }.

Run 4+ will encounter this same pattern whenever new molecules are ported that use Button from the worktree. The fix is consistent: alias ArdaButton as Button to preserve local naming.

Alternative: Consider exporting Button as an alias alongside ArdaButton from the atoms index.ts. This would eliminate the aliasing boilerplate across all consumers and make the migration more transparent. Recommend for a Run 7 or 8 clean-up pass.

2. window.matchMedia Not Mocked in Vitest Setup

The vitest.setup.ts was missing a window.matchMedia mock. Added in this run. This was blocking all 37 sidebar-related tests across 7 test files. The fix is backward-compatible and does not affect existing passing tests.

Root cause: The Radix UI SidebarProvider uses the useIsMobile hook from shadcn, which calls window.matchMedia. Any component that wraps with SidebarProvider (including ArdaSidebar and all its molecule children when tested in isolation through the sidebar context) will fail without this mock.

3. JSX String Attributes Do Not Process \u Escapes

In JSX, string attribute values like placeholder="Search items\u2026" pass the literal 18-character string to the underlying DOM element when processed by Vite/SWC. JavaScript Unicode escapes are not processed in JSX string attribute syntax (unlike JSX text content which processes HTML entities, and unlike JavaScript string literals in {...} expressions).

The test files use JavaScript string literals 'Search items\u2026' which DO process Unicode escapes. This mismatch caused 4 out of 6 item-grid tests to fail.

Fix applied: Use JSX expressions {"Search items\u2026"} for attribute values that need Unicode escapes. Going forward, all ported files should prefer literal Unicode characters or JSX expressions over \u escapes in JSX string attributes.

4. Grid-action Molecule Was Undocumented Dependency

The grid-action molecule was a silent dependency of item-details-header.tsx and item-details-card-preview.stories.tsx. Its directory existed as a stub but its files were not in the Run 3 task list. This was discovered during TypeScript verification.

For future runs: when a molecule directory exists as a stub, verify its consumers before declaring the run complete.

5. Sheet Primitive Needed for Item-grid Stories

The item-grid.stories.tsx Composition story uses Sheet, SheetContent, SheetHeader, SheetTitle, SheetDescription from @/components/ui/sheet. This was not listed in the plan’s import mapping for the item-grid organism. The primitive @/components/canary/primitives/sheet was used as the target. Verify this primitive file exists and exports all required components before Run 6 (item-grid integration).

6. Storybook MDX Table Syntax

The item-grid.mdx originally used a Markdown table. Replaced with an HTML <table> element following project MDX conventions (Markdown tables render as raw text in Storybook MDX). This pattern should be documented as a standard gotcha reminder in the project memory.

TODOs for Later Runs

• Run 7 cleanup: Consider exporting Button as an alias from atoms/button/index.ts to eliminate repeated ArdaButton as Button aliasing.
• Run 4+: When porting additional molecules that import Button, apply the ArdaButton as Button aliasing pattern consistently.
• Run 6: Verify @/components/canary/primitives/sheet exports SheetContent, SheetHeader, SheetTitle, SheetDescription before the item-grid integration stories run in the full-app context.