Troubleshooting

What to check when a release, an install, or a generated component does not behave. Each entry starts from the symptom, because that is what you have when it happens.

#Installing the package

#npm install cannot find the package

A released package lives in your organisation's registry, not on the public npm registry, so npm has to be told where to look for your scope. That is one line in .npmrc, and the Release dialog shows the exact one for your organisation:

@your-org:registry=https://registry.milda.app

If the line is there and the install still fails, check that it is in the .npmrc npm actually reads - a project-level file overrides your user-level one, and CI usually has neither until you put it there.

#The install URL points at localhost

That was a real bug, fixed: the publish target and the public origin were the same setting, so a registry published to internally advertised its internal address. If you see it, you are on an old release - re-run the release and the instructions will be regenerated.

#401 or 403 from the registry

Your token is missing, expired, or scoped to a different organisation. Tokens are per user and per scope; a token that installs one organisation's packages will not install another's. Ask an owner to re-issue rather than reusing a colleague's.

#Releasing

#The release fails while building

A release typechecks what it emits, so a failure here is usually the design system rather than the pipeline: a component whose contract references a prop that no longer exists, an icon that lost its asset, a token reference to a deleted token. The error names the component. Open it in the editor and the same problem will be visible in the inspector.

#402 Payment Required

You reached a feature gated to a paid edition - Figma export and private registry destinations are the usual two. See Editions for what is in which tier.

#The version did not go up the way I expected

Milda derives the version from the contract diff, not from a number you type: a removed prop or a narrowed type is a major, a new optional prop is a minor, and a change that no consumer can observe is a patch. If a release came out major and you did not expect it, the diff view lists exactly which contract change caused it.

#Docs sites

#The published docs URL 404s

• Publishing is a separate action from releasing - a release alone does not publish.
• The site lives at your-org.milda.page. A project slug changes the path, not the host.
• Slug changes are blocked after the first publish on purpose, so an existing link cannot rot underneath its readers.

#Generated components

#A component looks different from the canvas

The canvas and the generator are two renderers of the same document, and they are tested against each other over every archetype - so a difference is a bug worth reporting rather than something to design around. Include the archetype and what differs.

#A component has no styling at all

The generated CSS resolves design tokens through custom properties, which come from theme.css. If that file is not imported once at the root of your app, every component renders unstyled - the components themselves look correct in isolation, which is what makes this one confusing.

import '@your-org/ds/theme.css'

#An empty project generates unstyled components

That is the intended meaning of "Empty project": it seeds zero tokens, so the archetype defaults reference tokens that do not resolve yet, and the declarations are omitted rather than guessed. Define foundations, or start from a base system instead.