component-library-integration

Component Library Integration

Design Intelligence Preflight

Before choosing or bridging a component library, run project memory, code search, and internal supervibe:design-intelligence lookup for stack-specific UI guidance. Do not install or switch libraries from lookup alone; use existing stack facts and user approval.

When to invoke

• AFTER brandbook skill produces manifest.json with status: approved.
• BEFORE prototype-handoff runs, IF the target stack uses a component library.
• WHEN user asks "use shadcn / use MUI / can we adopt " — propose this skill.

Expert Operating Standard

Follow docs/references/skill-expert-operating-standard.md: start from source of truth, preserve retrieval evidence, apply scope safety, use real producers with runtime receipts for durable delegated outputs, verify before completion claims, and keep confidence below gate when evidence is partial.

Step 0 — Read source of truth

• .supervibe/artifacts/prototypes/_design-system/manifest.json (status must be approved)
• .supervibe/artifacts/prototypes/_design-system/tokens.css
• .supervibe/artifacts/prototypes/_design-system/motion.css
• .supervibe/artifacts/prototypes/_design-system/components/*.md (each baseline component spec)

Decision tree

Ask user one question at a time.

Step 1/4: What is the target stack for production?

• React → continue Step 2
• Vue → recommend HeadlessUI (Vue) or Radix-Vue or custom; Step 2
• Svelte → recommend Melt UI / Bits UI or custom; Step 2
• Angular → recommend Angular Material or custom; Step 2
• Vanilla / multi-framework → custom only; Step 2

Step 2/4: What is the design priority axis?

• Speed-to-market + opinionated visual: MUI | Mantine
• Maximum control + tokens-first: shadcn/ui | Radix UI primitives
• Headless logic only, full visual control: HeadlessUI | Radix UI primitives
• Already chose a library externally (project has it installed): adapt it

Step 3/4: Confirm library:

Step 4/4: Bridge depth — 3 tiers:

• A) Token-only bridge: re-theme library to consume our tokens. Library API stays default.
• B) Token + component-spec alignment: also map each baseline component (button/input/card/...) to the library's primitive.
• C) Full custom layer: build our components on the library's headless primitives, our spec drives API.

Procedure

1. Branch on chosen library:

   • MUI → copy templates/component-adapters/mui-token-bridge.ts.tpl to .supervibe/artifacts/prototypes/_design-system/library-bridge/mui/theme.ts. Fill palette/typography/spacing/shape/transitions from tokens.css.
   • shadcn/ui → copy templates/component-adapters/shadcn-token-bridge.css.tpl to .supervibe/artifacts/prototypes/_design-system/library-bridge/shadcn/globals.css. Map shadcn CSS vars (--background, --foreground, --primary, etc.) to our tokens.
   • Radix / HeadlessUI / Melt UI / Bits UI → copy templates/component-adapters/headless-ui-mapping.md.tpl to .supervibe/artifacts/prototypes/_design-system/library-bridge/<lib>/mapping.md. List which primitive backs each baseline component.
   • Mantine → similar to MUI; create theme.ts from Mantine's MantineThemeOverride shape filled with tokens.
   • Custom → no bridge needed; baseline component specs are the contract.

2. Write a .supervibe/artifacts/prototypes/_design-system/library-bridge/<library>/README.md describing:

   • Why this library (link back to brandbook decision)
   • Bridge depth (A/B/C)
   • How to import in production stack
   • Migration path if library is later swapped

3. Update .supervibe/artifacts/prototypes/_design-system/manifest.json with componentLibrary: { name: "...", bridgeDepth: "...", bridgePath: "..." }.

4. Print feedback prompt (required):

   Approve - save the bridge and continue handoff
   Revise - what should change in the mapping?
   Alternative - build a bridge for another library
   Deep review - ask code-reviewer to review the generated theme
   Stop - keep bridge as draft
   

Output contract

• .supervibe/artifacts/prototypes/_design-system/library-bridge/<library>/ — bridge files
• .supervibe/artifacts/prototypes/_design-system/library-bridge/<library>/README.md — rationale
• Updated manifest.json

Confidence: <N>.<dd>/10
Override: <true|false>
Rubric: framework

Anti-patterns

• library-without-bridge — picking shadcn/MUI/Mantine and shipping with their default theme; project tokens become decoration.
• silent-library-choice — installing MUI/shadcn before asking the user about priority axis.
• bridge-drift — bridge files diverge from tokens.css; bridge must regenerate when tokens change. Add a TODO in README for regeneration trigger.
• asking-multiple-questions-at-once
• advancing-without-feedback-prompt

Verification

• cat .supervibe/artifacts/prototypes/_design-system/library-bridge/<library>/README.md shows: library name, bridge depth, link back to brandbook decision.
• manifest.json componentLibrary.bridgePath resolves to existing file.
• Token references in bridge file (grep for token names from tokens.css) — count must be > 0; bridge that doesn't reference any token is broken.

Guard rails

• Do not mutate files, provider state, network resources, or external tools unless this skill's procedure and the user approval path allow it.
• Do not skip prerequisites, confidence gates, policy gates, or explicit approval gates.
• Do not claim completion without concrete verification evidence.
• Preserve user-owned content and unrelated worktree changes.

Related

• supervibe:brandbook — produces tokens this skill consumes
• supervibe:prototype-handoff — consumes bridge as part of handoff bundle
• agents/_design/creative-director.md — invokes this skill when component-library decision branch fires
• agents/_design/design-system-architect.md — verifies the bridge references approved project tokens and blocks library-default leakage