Skip to main content
Book a call and our team will help set this up. We are working towards making this self-serve!
Connecting a published component library brings your existing React components into Magic Patterns. After everything is connected, the AI will:
  • Use your actual component code in generated designs
  • Respect your component APIs, props, and variants
  • Generate code with correct import paths
  • Stay consistent with your design system
Everything on this page is guidance, not a checklist. We work with you during onboarding and adapt to how your team already ships components. For example, we have connected teams using the public NPM registry, private NPM, and GitHub Packages (an npm-compatible registry with a read-only token and .npmrc scoped to your organization). Prefer working from a repository instead? See linking GitHub.

​
What we need

To import your components, we need two things:
  1. Component code: either via an NPM package plus access token, or a zip or tar bundle you send manually. This lets us render the components in the Magic Patterns editor and ensures visual parity.
  2. Component documentation: either via Storybook or a custom MCP. This serves as context for the AI to understand your components and when to use each one.
NPM, GitHub Packages, and other private registries are different ways to host and version the same package artifact; a zip, tar, or npm pack tarball you send manually fills the same role.

​
Package structure

We recommend keeping Storybook files next to your component sources so documentation stays close to the code and is easier for the AI to relate to usage. 
my-design-system/
├── package.json
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.stories.tsx    # Storybook file
│   │   │   └── index.ts
│   │   ├── Card/
│   │   │   ├── Card.tsx
│   │   │   ├── Card.stories.tsx
│   │   │   └── index.ts
│   │   └── index.ts                  # Re-exports all components
│   └── index.ts                      # Main entry point
└── dist/                             # Compiled output

React Components

Your code must be written in React.

​
Ways to share

If your package is on a private registry (NPM, GitHub Packages, or another npm-compatible host), share a read-only access token.
# Generate a read-only token
npm token create --read-only
Share this token securely with your Magic Patterns contact.

​
Documentation best practices

Good documentation helps the AI understand not only what your components do, but when to use them.
Listing props alone is not enough. The AI needs context about when to pick one component or variant over another.

​
Usage guidance

For each component, cover:
  • Purpose: what problem the component solves
  • When to use: which scenarios should lead to this component
  • When not to use: anti-patterns or wrong fits
  • Variants: when each variant is appropriate
/**
 * Button component for user actions.
 *
 * @usage
 * - Use `primary` variant for the main call-to-action on a page
 * - Use `secondary` variant for less important actions
 * - Use `destructive` variant only for delete/remove actions
 * - Use `ghost` variant for tertiary actions or in toolbars
 *
 * @when-not-to-use
 * - Do not use Button for navigation; use Link instead
 * - Do not use multiple primary buttons in the same section
 */
export const Button = ({ variant, size, children, ...props }) => {
  // ...
}

​
Working with multiple packages

Many design systems split across packages that depend on each other. Magic Patterns supports that layout.

Monorepo

Multiple packages in one repository (for example Yarn workspaces, Turborepo, or Nx)

Multi-Repo

Separate repositories for packages that depend on each other
If packages depend on each other, we account for that when syncing: 
@mycompany/tokens        # Design tokens (colors, spacing, etc.)
@mycompany/primitives    # Low-level components (Box, Text, etc.)
@mycompany/components    # High-level components (Card, Modal, etc.)
The AI can:
  • Import from the correct package
  • Use shared tokens in a consistent way
  • Respect your component layering
For multiple packages, plan to share:
  1. Package list: every package that belongs to the design system
  2. Dependency graph: how those packages relate
  3. Access tokens: credentials for each private package when needed
In a monorepo, one access token often covers every package in the workspace.
Generated code can then follow your structure: 
import { colors, spacing } from '@mycompany/tokens'
import { Box, Text } from '@mycompany/primitives'
import { Card, Button } from '@mycompany/components'

export const PricingCard = () => {
  return (
    <Card>
      <Box padding={spacing.lg}>
        <Text color={colors.primary}>Premium Plan</Text>
        <Button variant="primary">Get Started</Button>
      </Box>
    </Card>
  )
}

​
Next steps

Schedule a call

Book time to plan connecting your real component library with your team.