Promote Portfolio Component

Promote a Portfolio Component

Move a proven portfolio interaction into Sona UI without flattening its craft, importing portfolio-specific coupling, or silently redesigning it. Treat the portfolio as the experimental/editorial layer and Sona UI as the reusable distribution layer.

Required input

Require a path to the source component, demo, or Craft. Resolve the real files with rg --files before forming a plan. Ask only for information that cannot be discovered from the supplied path and its local imports.

Do not assume that a visually finished experiment is library-ready. Do not modify or remove the portfolio source during promotion unless the user explicitly asks for that separate change.

Non-negotiable approval gate

Run this workflow in two distinct phases.

1. Complete Phase 1 as a read-only audit.
2. Present the promotion brief and identify every material decision.
3. Stop and wait for explicit approval.
4. Begin Phase 2 only after the user approves the brief or names a revised direction.

Treat layout, hierarchy, interaction, motion, semantics, visual language, component boundaries, and public API as material decisions. Ask before changing them. Small implementation details that preserve the approved result do not require another confirmation.

Phase 1: Audit and propose

Trace the complete source boundary

Read the supplied file and recursively inspect its local imports. Locate:

• the reusable component and the portfolio-only demo or page shell;
• props, defaults, callbacks, refs, state ownership, and controlled/uncontrolled behavior;
• CSS modules, global styles, tokens, fonts, icons, images, and other assets;
• hooks, utilities, providers, aliases, framework APIs, and runtime packages;
• animation runtime providers and feature-loading boundaries, including whether motion/react-m components depend on an application-level LazyMotion provider;
• responsive, light/dark, keyboard, focus, reduced-motion, and cleanup behavior;
• analytics, content, route, or application-specific coupling that must not enter the library.

Inspect actual files rather than relying on the visible entry file alone. Never read, list, or modify personal/journal/.

Apply the craft review

Read and use the repository-local apple-design and design-motion-principles skills. Review the component through the Emil, Jakub, and Jhey lenses, with attention to:

• immediate pointer-down and keyboard feedback;
• interruptible motion and spatial continuity;
• direct manipulation, velocity handoff, and cancellation where applicable;
• reduced motion, reduced transparency, contrast, focus, and touch behavior;
• restrained typography and visual effects;
• lifecycle cleanup, performance, and resize resilience.

Preserve expressive behavior that demonstrates craft. Propose removing or neutralizing portfolio-specific styling only when it prevents reuse, and make that an explicit approval item.

Define the distributable contract

Separate three layers:

1. Library component — reusable behavior, stable API, styles, and required utilities.
2. Sona demo — realistic content and composition that demonstrate the component without becoming part of its API.
3. Portfolio shell — editorial copy, Craft layout, page navigation, analytics, and product-specific data that remain in the portfolio.

Prefer a focused API with useful composition points over a snapshot of demo-specific markup. Preserve existing props and behavior when they already form a sound public contract. Do not invent variant-only props, domain metaphors, or configuration merely to reproduce one demo.

Classify the result as one of:

• Ready — the reusable boundary and adaptations are clear.
• Ready with decisions — promotion is viable after the user chooses listed API, layout, or interaction decisions.
• Not ready — essential accessibility, behavior, dependency, or ownership problems should be resolved in the portfolio first.
• Portfolio-only — the value depends on its editorial context and would weaken as a general library component.

Present the promotion brief

Report a concise brief containing:

• source entry and files that belong to the component boundary;
• readiness classification and evidence;
• proposed Sona component name, slug, category, and one-sentence purpose;
• proposed public API, defaults, callbacks, ref behavior, and accessibility semantics;
• dependencies and assets to carry, replace, or leave behind;
• behavior and visual details that will remain unchanged;
• proposed adaptations and why each is necessary;
• unresolved material decisions as clearly named options;
• planned Sona files and focused validation commands.

End Phase 1 by explicitly asking the user to approve or revise this brief. Do not create prototypes or production files yet.