Skip to main content
Lovable design systems are available on Enterprise plans and work natively with design systems that are implemented as React components.
Design systems let you define your component library, styling guidelines, and installation instructions once, and reuse them across every project in your workspace. When a design system is connected to a project, components, rules, and updates flow from the design system project into every project connected to it. In Lovable, a design system is created as a dedicated project. This project serves as the source of truth for your design system and can be connected to other projects in your workspace.

​
What you get

  • Centralized source of truth for UI components, tokens, and styles
  • Your library’s React components delivered directly into every connected project, ready for use
  • One-click updates: when you publish a new version, connected projects see an Update available prompt in the chat
  • Automatic setup verification after every connect or update — Lovable checks the wiring (build config, CSS imports, theme providers, dependencies) and fixes anything missing
  • Adherence enforcement during ongoing work: Lovable catches raw colors, custom or customized components, and other deviations from your design system

​
How design systems work

A design system in Lovable defines how components, styles, and setup instructions are applied across projects. Design systems are Lovable projects and can be opened and edited like any other project.

​
What a design system consists of

A design system in Lovable combines three core parts:
  1. Components: your React component library
  2. Schema and guidelines: a machine-readable schema (tokens, component catalog, constraints) plus rendered documentation Lovable reads on every generation
  3. Installation: setup instructions and required configuration
If you already have these in place, you can create a design system project in Lovable and reference your existing materials. If your documentation is scattered or incomplete, you can create and improve the design system directly inside Lovable.

​
The design system project and the .lovable folder

The design system project owns a special .lovable folder. When you publish your design system, Lovable generates the following:
  • design-system.json: the standardized, machine-readable schema, including tokens, component catalog (variants, props, examples), and stack constraints. This is the source of truth.
  • rules/components.md: component catalog, rendered from the schema.
  • rules/design-tokens.md: token reference, rendered from the schema.
  • rules/library-guidelines.md: stack requirements and usage rules, rendered from the schema.
  • system.md: high-level installation instructions and design philosophy. This file is preserved across publishes, meaning that Lovable does not regenerate it from the schema.
You can edit system.md through the Knowledge tab in the project settings or by chatting with Lovable directly. The other files are regenerated on every publish.

​
How design systems are applied to projects

When a project is connected to a design system, Lovable performs a file-copy attach:
  • The design system’s React components are copied into the connected project at src/design-system/<design-system-slug>/. Lovable imports components from there.
  • The design system’s .lovable knowledge files (schema, rendered rules, and system.md) are copied to .lovable/rules/libraries/<design-system-slug>/. Lovable reads them on every generation.
  • Required runtime dependencies are merged into the connected project’s package.json.
  • A [[libraries]] entry in lovable.toml records which design system is connected and at what version.
The components are then ordinary local, readable, and usable React resources in the connected project. Avoid editing them: local edits are replaced the next time you accept an update from the design system. If you need permanent changes, propose them in the relevant design system project.

​
Updates

When you publish a new version of your design system, every connected project sees an Update available prompt in the chat. Accept the update and Lovable reruns the file-copy attach against the new version: old design system files are removed, new ones are copied in, dependencies are remerged, and setup verification reruns. The connected project’s own code is untouched.

​
Setup verification

After a design system is attached to a project (either at project creation or in an existing project), the agent runs a silent verification pass to confirm that the design system is wired up correctly. This pass checks that:
  • Your build pipeline picks up the design system’s source folder, and does not fail.
  • The design system’s styling entry is imported wherever your project loads styles.
  • Any wrapper components or providers the design system requires are in place at the appropriate scope.
  • All required dependencies are declared in package.json.
If everything is correctly wired up, the verification leaves no trace in the chat. If anything is missing, Lovable corrects it in a follow-up generation and reruns the check, until everything is in place or a short checklist of what couldn’t be fixed surfaces in the chat.
Setup verification turns are billed at zero credits and do not count toward your workspace usage.

​
Adherence checks

While you’re working in a connected project, every generation is scanned for violations of the design system:
  • Raw color literals where a design system token should be used
  • One-off values that bypass the design system’s tokens or scale
  • Inline styles that override the design system’s defaults
  • Local component implementations for things that should come from the design system
When violations are found, Lovable automatically retries to correct them before finishing the generation.

​
Key notes and limitations

  • The .lovable folder is owned by the design system project and cannot be edited from connected projects.
  • Connected projects record the version of the design system they were last attached at. Updates apply when accepted from the chat prompt.
  • Lovable design systems work natively with React component libraries.
  • Any project can be turned into a design system from the project settings. When a project is marked as a design system, it becomes available for other projects in the workspace to connect to.
  • An unpublished design system cannot be used as the basis for a new project. Publish it first.
  • A project can be connected to at most one design system at a time. Detaching a connected design system isn’t supported yet. Ensure to pick the right one before connecting.
  • If your design system or related documentation is hosted within your VPC, reach out to your account team for guidance.

​
Create a design system

1

Prepare access (private packages only)

If your component library or packages are private, go to Workspace settings → Build secrets and add the required build secrets (for example, npm tokens).
2

Create a design system project

From the + dropdown of the lovable.dev prompt box, select Design and select Use a design system.In the modal, select Create design system.This creates a new design system project. Lovable assigns a name to your project, which you can change from the project settings.Give your design system a meaningful name. This name is used when connecting the design system to projects later.
3

Configure the design system by chatting with Lovable

You can set up your design system in two main ways.Option A: Auto-fetch an existing React libraryIf your design system is implemented as React components, share the repository or documentation URL in the chat.
  • If public, Lovable fetches it automatically
  • If private, Lovable fetches it using the secrets you configured
Once imported, Lovable extracts a schema from your component source on publish — variants, props, and examples are captured automatically. For additional usage context the schema can’t infer (design philosophy, narrative usage rules, installation quirks), edit system.md via the Knowledge tab in project settings or by chatting with Lovable directly.
When fetching an existing library, ignore the guided questions and proceed to enter the URL.
Option B: Build your design system with structured instructionsIf your documentation is scattered or incomplete, guide Lovable explicitly to build your design system. This approach lets you:
  • Import PDFs, Markdown files, screenshots, and other assets
  • Define components, patterns, tokens, and styling guidelines
  • Write installation and setup instructions
  • Update everything dynamically across connected projects
Suggested prompt structure
[High-level goal]

[Install instructions]

[Other context for setting up the system, for example tech stack and constraints]

[Component library request]

[Links to documentation, sites, PDFs, MCPs for more context. Lovable can crawl websites so
feel free to include wide context here.]
After the first run, Lovable will generate a working design system project, for example: https://design-system-demo.lovable.app/
4

Release the design system

Select Release version in the design system project. Lovable generates the schema, renders the documentation, bumps the version, and commits everything to the design system project’s repository. The design system is now selectable when creating new projects or attaching to existing ones.Re-release whenever you want to push updates to connected projects.

​
Connect a design system to projects

Attach a design system with care. It is not possible to detach a design system from a project.
In each project’s settings, you can see which design system is connected and which ones are available to connect.

​
Connect a design system to new projects

From the + dropdown of the lovable.dev prompt box, go to Design and select Use a design system, select the design system you want to use, then enter your prompt. Lovable generates your new project using the selected design system.
Only released design systems are available for selection. If the design system you want to use is marked as Draft, open the design system project and release it first.

​
Connect a design system to existing projects

To connect a design system to an existing project, follow the steps below:
  1. Go to Project settings → Design systems.
  2. Under Available, select a design system and click Add.
  3. Click Save.
Lovable copies the design system’s components and knowledge files into your project, merges dependencies, and runs setup verification automatically.

​
Refine your design system

Design systems are meant to evolve. After the initial setup, iterate on the contents of the .lovable folder and your component source.
  1. Check the structure
    Open the .lovable folder to see how Lovable generated your schema and documentation. These files are what gets applied to all connected projects on the next update.
  2. Fix inconsistencies
    If components do not render correctly, ask Lovable to fix them and update the schema at the same time. Republish to push the fix to connected projects.
  3. Add detail
    Request additional component documentation, token definitions, or usage patterns as needed. Each publish bumps the version and notifies connected projects of an available update.

​
.lovable folder structure

Lovable generates this automatically when you publish. In the design system project: 
.lovable/
├── design-system.json          # canonical schema (tokens, components, constraints)
├── system.md                   # high-level installation instructions, hand-authored
└── rules/
    ├── components.md           # rendered from design-system.json
    ├── design-tokens.md        # rendered from design-system.json
    └── library-guidelines.md   # rendered from design-system.json
In a connected project, the design system’s .lovable files are copied to a namespaced subfolder: 
.lovable/
└── rules/
    └── libraries/
        └── <design-system-slug>/
            ├── design-system.json
            ├── system.md
            ├── components.md
            ├── design-tokens.md
            └── library-guidelines.md
The corresponding component source lives at src/design-system/<design-system-slug>/ in the connected project, imported as @/design-system/<design-system-slug>/....

​
Fetch external design system documentation with MCP servers

MCP servers can be used to fetch design system documentation that is stored separately from your npm packages. See Integrate with your tools using chat connectors (MCP servers) for more information.

​
Troubleshooting

If your design system uses React 19 but the project defaults to React 18, or vice versa, tell Lovable explicitly. For example:
My design system requires React 19. Please update the project dependencies accordingly.
If your design system uses a different styling solution than the project’s defaults, ask Lovable to remove the conflicting dependencies. For example:
Please uninstall the project's default styling dependencies. My design system uses
[your styling solution] instead.
Setup verification usually catches this and fixes the wiring automatically. If something still looks off, open the chat in the connected project and ask Lovable to verify the design system is wired up correctly. It will rerun the check and propose fixes.
The adherence scanner catches most violations automatically. If it misses something, point it out in the chat. For example, “use the Button from the design system here, not a custom one.” Lovable will replace the local implementation with the design system component.

​
FAQ

Yes, a design system is a regular Lovable project that is marked as a design system. It can be opened and edited like any other project, and other projects can connect to it.If the design system wraps an external npm package, the package itself isn’t editable from Lovable, only the wrapper layer in the design system project is. Changes to the underlying components have to be made in the upstream npm package and republished there.
No. A project can be connected to at most one design system at a time. Detaching a connected design system isn’t supported yet, so review the available design systems before connecting.
Yes, any project can be marked as a design system from project settings. Set Project type to Design system. Once marked, it becomes available for other projects in the workspace to connect to.
Go to Project settings → Design systems. The tab shows the connected design system (if any) and lets you browse available ones to connect.
Yes. Every publish bumps the version. Connected projects record the version they were last attached at, and an Update available prompt appears in the chat whenever a newer version is published.
An unpublished design system exists as a project but has not been published yet, so it has no schema or rendered documentation. You cannot use an unpublished design system as the basis for a new project. Publish it first. Once published, the design system gets a version number and becomes selectable in the design system picker.
Not yet. Detaching a connected design system from project settings isn’t supported in this release. Pick the design system you want before connecting.
The design system’s source and documentation are managed by the design system project. The files in src/design-system/<design-system-slug>/ and .lovable/rules/libraries/<design-system-slug>/ are present in a connected project’s git, so you can read and import them, but local edits will be replaced the next time you accept an update. For permanent changes, propose them in the design system project.
No. Design systems are an in-Lovable feature. Components and documentation flow directly between your Lovable projects. If you also want to publish your design system to a public npm or a private registry for use outside Lovable, that’s a separate flow.
Lovable design systems support React-based component libraries out of the box. The design system declares its required stack and dependencies through its schema, and Lovable adapts the setup automatically. Your library determines what gets wired up, not a fixed list of supported frameworks. If your design system is built with other frameworks such as Vue, Angular, or Svelte, reach out to your CSM or FDE.
When you attach a design system, Lovable runs an automatic setup verification pass to check that the design system is wired up correctly (configuration, CSS imports, theme providers, dependencies, and import paths). If the agent finds gaps, it applies fixes and reruns verification. Successful verifications are silent and do not appear in the chat. Verification turns are billed at zero credits.
No, design systems do not replace templates. Templates and design systems serve different purposes and are often used together. Templates are best for initial project scaffolding, while design systems provide ongoing UI and design guidance across projects.