Design systems - Lovable Documentation
Documentation Index Fetch the complete documentation index at: /llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Lovable design systems are available on all paid plans and work natively with design systems that are implemented as React components. Wrapping an existing npm package as a design system (see npm wrapper (Path B) ) is available on Enterprise plans only.
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 release a new version, connected projects see an Update available prompt in the project 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: Components : your React component library Schema and guidelines : a machine-readable schema (tokens, component catalog, constraints) plus rendered documentation Lovable reads on every generation 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 release 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 releases, meaning that Lovable does not regenerate it from the schema.
You can edit system.md through the Instructions tab in the project settings or by asking Lovable in the project chat directly. The other files are regenerated on every release. 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 release a new version of your design system, every connected project sees an Update available prompt in the project 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 project 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 project 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 project chat prompt. Lovable design systems work natively with React component libraries. A design system is created as its own dedicated project from the Create a design system flow.
An unreleased design system cannot be used as the basis for a new project. Create an initial release first. A project can be connected to at most one design system at a time. To switch, remove the current one first: open the Design system section in Project settings → General , then choose ⋯ → Remove on the connected one. Removing a design system severs the managed link: the project stops receiving updates and the agent no longer enforces its rules.
The copied files stay under src/design-system/ as ordinary, editable code, so nothing using them breaks; they are now yours to maintain. If your design system or related documentation is hosted within your VPC, reach out to your account team for guidance. Design systems are supported for React. Other frameworks such as Vue, Angular, or Svelte are not supported today, so your mileage may vary. Reach out to your CSM or FDE if you need them.
New projects created from a design system currently scaffold on a TanStack template, even when the design system is a Vite/React one, and the styling framework is not always wired into the build automatically. A consumer that uses Vite can pull in Tailwind 3, which conflicts with Tailwind 4. When this happens, Lovable’s setup verification usually corrects the wiring on the first generation; if styles still look wrong, ask Lovable in the connected project to wire up the design s
The rest of this page is on the live site.