{"id":12345,"library":"vanilla-framework","title":"Vanilla Framework","description":"Vanilla Framework is an extensible CSS framework built by Canonical, utilizing Sass for its core architecture. It provides a comprehensive set of pre-designed components, utility classes, and a robust design system for building consistent web interfaces, particularly those aligned with the Ubuntu design language. The current stable version is 4.49.0, with a rapid release cadence typically seeing multiple minor versions released each month, delivering new features, enhancements, and bug fixes. Key differentiators include its strong integration with the Ubuntu ecosystem, its extensibility through Sass themes and variables, and a focus on accessibility and modern web patterns. It offers a solid foundation for projects requiring a polished and consistent user interface without starting from scratch, consumable either by hotlinking pre-compiled CSS or, more commonly, integrated into a project's Sass build pipeline.","status":"active","version":"4.49.0","language":"javascript","source_language":"en","source_url":"https://github.com/canonical/vanilla-framework","tags":["javascript","ubuntu","vanilla","framework","CSS","SASS","SCSS","mixin","module"],"install":[{"cmd":"npm install vanilla-framework","lang":"bash","label":"npm"},{"cmd":"yarn add vanilla-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add vanilla-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for compiling Vanilla Framework's Sass files, which is the primary and recommended method for integrating and customizing the framework within a project.","package":"sass","optional":false}],"imports":[{"note":"This Sass statement imports the framework's main Sass entry point. It requires your Sass compiler to have `node_modules` included in its `load-path` (e.g., `sass --load-path=node_modules src:dist`).","wrong":"@import 'node_modules/vanilla-framework/scss/vanilla-framework';","symbol":"vanilla-framework","correct":"@import 'vanilla-framework';"},{"note":"This Sass mixin is responsible for compiling and outputting the entire framework's CSS. It must be called within a Sass file *after* `@import 'vanilla-framework';` to have access to the mixin definition.","wrong":"@import 'vanilla';","symbol":"vanilla","correct":"@include vanilla;"},{"note":"For JavaScript/TypeScript projects using module bundlers (like Webpack, Rollup, or Vite), this line directly imports the pre-compiled CSS file. Ensure your bundler is configured to handle CSS imports.","wrong":"import 'vanilla-framework/vanilla.css';","symbol":"vanilla.css","correct":"import 'vanilla-framework/dist/vanilla.css';"}],"quickstart":{"code":"yarn add sass vanilla-framework\n\n// In your package.json, add a script like:\n// \"build-css\": \"sass -w --load-path=node_modules src:dist --style=compressed\"\n\n// Create a file: src/style.scss\n// (The build script will compile this to dist/style.css)\n\n// src/style.scss\n// Import the entire Vanilla Framework\n@import 'vanilla-framework';\n\n// Include the main mixin to output all framework styles\n@include vanilla;\n\n// Optionally, override a Sass variable to customize the theme\n$color-brand: #0073e6; // Example: Set a custom brand color\n\n// You can also include specific parts if the entire framework is not needed:\n// @include vf-b-forms; // Only include form styles\n\n// To compile and watch for changes, run:\n// yarn build-css\n","lang":"scss","description":"Sets up a basic Sass build pipeline for Vanilla Framework, demonstrating how to install, import, include, and customize framework styles via Sass variables, compiling to a `dist/style.css` file."},"warnings":[{"fix":"Always review the release notes and documentation before upgrading minor versions. Test your application thoroughly against the new version, especially in areas using components that have received updates.","message":"Minor versions (e.g., v4.4x.0) often introduce new components and patterns (e.g., 'in-page navigation component', 'Tab section pattern'). While not explicitly labeled 'breaking', these updates might involve changes to underlying class names, Sass variables, or required markup structures that could inadvertently break existing layouts or customizations if not carefully reviewed during upgrades.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your project's `sass` dependency meets or exceeds the peer dependency requirement specified in `package.json` (`^1.79.0`). Upgrade `sass` using `npm install sass@latest` or `yarn add sass@latest`.","message":"Using an incompatible version of `sass` (e.g., older than `^1.79.0`) can lead to compilation errors, unexpected output, or `Undefined variable` errors due to syntax changes or removed features in the Sass language itself that Vanilla Framework relies on.","severity":"gotcha","affected_versions":"<1.79.0"},{"fix":"For production applications, it's recommended to install Vanilla Framework via NPM/Yarn and integrate it into your project's build pipeline. This allows for controlled updates and leveraging Sass for customization.","message":"While hotlinking to specific versioned CSS files (e.g., `vanilla_framework_version_x_x_x_min.css`) is possible, it prevents automatic updates. This means you will not receive new features, bug fixes, or critical security patches unless you manually update the version in your HTML, leading to potentially outdated UIs and missed improvements.","severity":"gotcha","affected_versions":"*"},{"fix":"Prioritize customization through Sass variables, mixins, and provided extension points. When overriding, use the official documentation for component structure and only target stable, documented class names or patterns. Create your own Sass partials that import and extend Vanilla's styles.","message":"Directly modifying compiled CSS or relying on internal, undocumented class names/structures for extensive customization is fragile. Such customizations are highly susceptible to breaking with framework updates, as internal implementation details can change without notice.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure that your custom variables or overrides are placed *after* `@import 'vanilla-framework';` and *before* `@include vanilla;` to ensure proper cascading and definition order.","cause":"Attempting to use a custom Sass variable or override a Vanilla Framework variable before the framework's main Sass file has been imported or the variable is defined.","error":"Error: Undefined variable: \"$my-custom-color\"."},{"fix":"First, ensure `vanilla-framework` is installed (`npm install vanilla-framework` or `yarn add vanilla-framework`). Then, configure your Sass build command to include `node_modules` in its `load-path`, e.g., `sass --load-path=node_modules src:dist`.","cause":"The Sass compiler cannot locate the `vanilla-framework` package. This typically happens if `vanilla-framework` is not installed, or if the `node_modules` directory is not included in the Sass `load-path` configuration.","error":"Error: Can't find stylesheet to import. @import \"vanilla-framework\";"},{"fix":"Verify that `@include vanilla;` is used as a mixin call and is placed *after* the `@import 'vanilla-framework';` statement within your main Sass file.","cause":"This error occurs when `@include vanilla;` is used incorrectly, often by attempting to use it as an `@import` statement or placing it in an invalid Sass context (e.g., outside of a style block or before its definition is available).","error":"Error: SassError: Expected a pseudo-class or pseudo-element, but got identifier \"vanilla\"."},{"fix":"Either import the pre-compiled CSS file (`import 'vanilla-framework/dist/vanilla.css';`) if you don't need Sass customization, or configure your module bundler with an appropriate Sass loader (e.g., `sass-loader` for Webpack) to process `.scss` files.","cause":"Attempting to directly `import` a Sass (`.scss`) file (e.g., `import 'vanilla-framework/scss/vanilla-framework.scss';`) into a JavaScript/TypeScript file without a configured Sass loader (like `sass-loader` for Webpack).","error":"ModuleParseError: Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type."}],"ecosystem":"npm"}