遷移至 Master CSS

Migrate existing projects to Master CSS with incremental setup, styling-system audits, and review workflow.

Migrating a real product to Master CSS is rarely a one-to-one syntax rewrite. Treat the work as a product styling change: inspect the existing styling systems, add Master CSS beside them, convert one reviewable slice at a time, and remove old dependencies only after the migrated UI is validated.

If you use a local AI coding agent, start with AI Coding with Master CSS for setup, context, prompts, and review habits. This page keeps the migration-specific checklist and prompt focused on converting an existing project.

Frameworks

Migration guides for source styling systems with enough differences to need their own migration path.

Migration strategy

CSS migration depends on project context. A static checklist cannot reliably know which files contain product styles, which classes come from a third-party package, which values are design tokens, or which custom CSS is clearer than a generated utility class.

Start with an audit, then migrate incrementally. The first milestone is not deleting the previous styling system; it is getting Master CSS installed, generating CSS for new or converted markup, and keeping the existing UI stable while conversion is in progress.

Before you start

• Start from a clean git working tree, or commit your current work first.
• Identify the existing styling systems, such as global CSS, CSS Modules, Tailwind CSS, CSS-in-JS, Sass, framework style blocks, or component-library CSS.
• Decide which rendering mode fits the project: static rendering, runtime rendering, or progressive rendering.
• Find the CSS file your app already loads. This is usually where @import '@master/css'; should enter the project.
• Keep the old styling system in place until the migrated screens build, run, and visually match the previous UI.

Migration prompt

Paste this into your local coding agent from the project root. For general AI workflow guidance, use AI Coding with Master CSS.

You are migrating this project to Master CSS.Use the official Master CSS documentation as the source of truth:Documentation: https://rc.css.master.coDo not invent Master CSS classes, APIs, directives, or package names.First inspect the repository and identify:- the framework, build tool, package manager, and current styling systems- the app CSS entry point and component/template files that contain styles- any design tokens, theme variables, CSS modules, utility classes, styled components, preprocessors, or third-party stylesheets- the available formatter, lint, type-check, test, and build commandsThen migrate incrementally:1. Install and configure the appropriate Master CSS package or integration.2. Import `@master/css` from the project CSS entry.3. Choose the rendering mode that matches this project: static rendering, runtime rendering, or progressive rendering.4. Convert repeated visual styles into Master CSS classes in markup where that improves clarity.5. Move shared design values into `@theme` tokens.6. Use `@components` and `@compose` for reusable component classes only when markup classes would become hard to maintain.7. Keep vendor CSS, generated CSS, complex animation CSS, and hard-to-read one-off CSS in regular CSS unless converting it improves maintainability.8. Remove the old styling dependency only after the migrated screens build and match the previous UI.Work in small migration batches. After each focused batch, show me the changed files, explain the conversion decisions, and run the project’s formatter, type check, tests, and build if available. Call out anything that needs manual review, especially visual differences, removed CSS, changed tokens, old styling dependencies, or unsupported syntax.

Review the result

Review the migration as code and as UI.

• Inspect the diff before accepting each batch.
• Run the formatter, type check, tests, and production build available in the project.
• Compare important screens in the browser, including responsive states and dark mode if the app supports them.
• Keep regular CSS for vendor styles, generated output, hard-to-read one-off declarations, complex animations, and anything external code controls.
• Remove old styling dependencies only after the converted paths no longer rely on them.

Useful references

• Installation for adding Master CSS to a project.
• Rendering modes for choosing static, runtime, or progressive rendering.
• Style declarations for class syntax.
• Customizing your theme for @theme, tokens, modes, and custom variants.
• Reusing styles for deciding between utilities, theme tokens, and component classes.
• Code linting for validating Master CSS classes in source code.
• Language Service for editor highlighting and completion.