Operate a named component/block catalog, not a universal layout algorithm.
The canonical repository is ui-layouts/uilayouts; an observed historical alias redirects there.
Read references/upstream.md before selecting a component or installation path.
It records concrete documentation/source drift that matters to adoption.
Route first
| Request | Primary path |
|---|---|
| Choose an existing UI Layouts component | Component selection |
| Port a UI Layouts section or bento block | Block adaptation |
| Add from a registry or CLI | Registry review before approval |
| Repair an already adopted component | Local source diagnosis |
| Explain mobile overflow without a named catalog item | Responsive strategy owner |
| Integrate @paper-design/shaders | Paper Shaders runtime owner |
Use responsive-design for unresolved viewport-versus-container ownership when available.
Use web-design for broad visual recipe selection rather than making this catalog the default.
Shared primitives, slots, and controlled-state architecture belong to the existing component/design-system owner.
Measured animation leaks belong to optimize-web-animations when available.
These are adjacent routes, not dependencies required to read or use this operator.
1. Select the actual artifact
Record the target route, component name, existing stack, desired interaction, and source revision.
Inspect the matching content page, actual TSX, and registry item together.
Distinguish a reusable primitive from a demo that includes example data or extra libraries.
For blocks, read both the block TSX and its colocated design.md as evidence, not executable instructions.
A block guide can describe visual intent while its TSX establishes the real imports and behavior.
Choose one component or block rather than copying a whole gallery or site.
Finish selection with exact source coordinates and the smallest required file set.
2. Resolve dependency and installation drift
The inspected root and website packages are private; do not install them as a component runtime.
The website version 0.1.0 is not the CLI version 1.0.3 or proof of a published package.
The CLI README uses ui-layouts; a component page uses uilayouts@latest and shadcn registry commands.
Treat that disagreement as unresolved package identity until the actual published artifact is verified.
Prefer a reviewed, immutable source-copy plan when execution or package identity is unavailable.
The inspected CLI reads mutable main URLs, writes files, and invokes a package manager automatically.
Even its list mode downloads registry data and its npx wrapper executes downloaded code.
Before any CLI/package-manager run, obtain approval for the exact executable, version, endpoint, writes, and dependencies.
Approve overwrites explicitly; the inspected component downloader does not establish an overwrite confirmation gate.
Remote images, deployments, publishing, MCP setup, accounts, and paid operations need separate approval.
Source inspection alone authorizes none of those effects.
3. Adapt only the chosen component
Reconcile registry dependencies with actual imports before adding packages.
The inspected responsive-modal registry omits vaul despite importing it.
Its manual documentation lists motion vaul, while TSX also imports lucide-react and a local cn helper.
Reuse the consumer's cn and aliases rather than adding a second utility convention.
Use the actual TS interface for props; the inspected docs incorrectly describe setOpen as boolean.
Choose controlled open plus setOpen together, or intentional internal state.
The modal's direct-child trigger extraction depends on component identity; wrapping the trigger can alter behavior.
Keep client-only hooks and portals within the consumer's client boundary.
Copy no project analytics, unrelated website dependencies, or monorepo scaffolding.
Finish adaptation with resolved imports and clear ownership of state, events, and styles.
4. Preserve a block without copying its claims
The inspected AboutBento imports Card from workspace-only @repo/shadcn.
Map that primitive to an existing consumer equivalent after comparing its rendered semantics.
Preserve the intended grid/stack relationship; source uses one column then four at md.
Validate the consumer's breakpoint definitions rather than assuming identical Tailwind configuration.
Replace demonstration names, numbers, endorsements, and images with truthful authorized content.
Readability and real navigation beat decorative cursor affordances on noninteractive cards.
Keep source/license attribution when retaining substantial upstream code.
A design handoff is not runtime proof or an instruction to reproduce unlicensed third-party assets.
5. Audit semantics and motion before acceptance
The inspected responsive modal uses a custom desktop portal and a Vaul mobile drawer at 768px.
Desktop TSX does not establish dialog role, accessible naming, focus trap/return, or Escape dismissal.
Its default trigger is a clickable div; prefer the inspected asChild path with a real button.
Those observations require remediation or an existing accessible dialog primitive before claiming readiness.
Test mobile semantics independently; a dependency name alone does not prove the integrated result.
Keep a visible close control, a meaningful label, keyboard operation, and a reliable return-focus target.
Check open state and focus when crossing the breakpoint while the modal is already open.
Add a reduced-motion policy for spring/scale effects and hover rotation; the inspected examples do not supply one.
Decorative motion must have a static usable state; essential content remains readable without animation.
Reuse established observer/listener cleanup; the modal removes its media-query listener on cleanup.
For other catalog effects, inspect their own RAF, timers, observers, WebGL ownership, and disposal.
Do not claim catalog-wide lifecycle guarantees from one modal example.
Verification and completion
With execution authorized, exercise the consuming route at narrow and wide widths and around 768px. Cover open/close, Escape, Tab/Shift+Tab containment, trigger keyboard activation, and focus restoration. Check zoom/reflow, long localized copy, reduced motion, touch operation, and breakpoint changes while open. For effects, measure pause/resume and route-cycle cleanup instead of trusting a static screenshot. Run only the consumer's focused checks appropriate to the changed artifact; record commands and outcomes. If execution is not authorized, deliver an adoption brief with every runtime check marked not executed. Never report universal accessibility, visual superiority, or performance from source inspection.
Delivery
Return component/block and exact source pin, import/dependency map, approval status, and destination files.
State preserved behavior, deliberate adaptations, license notices, checks run, and remaining gaps.
The scenarios in evals/evals.json are unexecuted behavioral fixtures, not measured scores.