Split Quanta and icons out of @plone/components into @plone/quanta and @plone/icons

.github/workflows/changelog.yml

@@ -38,6 +38,10 @@ jobs:
               - 'packages/registry/**'
             components:
               - 'packages/components/**'
+            icons:
+              - 'packages/icons/**'
+            quanta:
+              - 'packages/quanta/**'
             cmsui:
               - 'packages/cmsui/**'
             helpers:
@@ -99,6 +103,22 @@ jobs:
         env:
           BASE_BRANCH: ${{ github.base_ref }}
 
+      - name: Icons changelog check
+        if: steps.filter.outputs.icons == 'true'
+        run: |
+          git fetch --no-tags origin main
+          towncrier check --compare-with origin/main --dir packages/icons
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+
+      - name: Quanta changelog check
+        if: steps.filter.outputs.quanta == 'true'
+        run: |
+          git fetch --no-tags origin main
+          towncrier check --compare-with origin/main --dir packages/quanta
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+
       - name: Helpers changelog check
         if: steps.filter.outputs.helpers == 'true'
         run: |

.github/workflows/code-analysis.yml

@@ -30,6 +30,8 @@ jobs:
           pnpm --filter @plone/types run check:ts
           pnpm --filter @plone/client run check:ts
           pnpm --filter @plone/components run check:ts
+          pnpm --filter @plone/icons run check:ts
+          pnpm --filter @plone/quanta run check:ts
           pnpm --filter @plone/registry run check:ts
           pnpm --filter @plone/blocks run check:ts
           pnpm --filter @plone/cmsui run check:ts
@@ -93,6 +95,10 @@ jobs:
         include:
           - name: '@plone/components'
             files: 'src/**/*.{css,scss,less}'
+          - name: '@plone/icons'
+            files: 'src/**/*.{css,scss,less}'
+          - name: '@plone/quanta'
+            files: 'src/**/*.{css,scss,less}'
           - name: '@plone/theming'
             files: 'styles/**/*.{css,scss,less}'
           - name: '@plone/layout'

.github/workflows/unit.yml

@@ -23,7 +23,9 @@ jobs:
           - '@plone/cmsui'
           - '@plone/components'
           - '@plone/helpers'
+          - '@plone/icons'
           - '@plone/layout'
+          - '@plone/quanta'
           - '@plone/react-router'
           - '@plone/registry'
         node-version: [24.x]

AGENTS.md

@@ -23,10 +23,10 @@ Plone Aurora is composed of focused packages that are assembled into `apps/auror
 | -------------------------- | ----------------------------------------------------------------------------------- |
 | App shell                  | `apps/aurora`                                                                        |
 | Public UI (visitor-facing) | `@plone/publicui`, `@plone/layout`, `@plone/blocks`                                 |
-| CMS UI (editor-facing)     | `@plone/cmsui`, `@plone/contents`, `@plone/plate`, `@plone/blocks`, `@plone/layout` |
+| CMS UI (editor-facing)     | `@plone/cmsui`, `@plone/contents`, `@plone/plate`, `@plone/blocks`, `@plone/layout`, `@plone/quanta` |
 | Shared infrastructure      | `@plone/client`, `@plone/registry`, `@plone/react-router`                           |
 | Utilities and types        | `@plone/helpers`, `@plone/types`                                                    |
-| Theming                    | `@plone/theming`, `@plone/agave`, `@plone/components`                               |
+| Theming                    | `@plone/theming`, `@plone/agave`, `@plone/components`, `@plone/quanta`, `@plone/icons` |
 | Tooling                    | `@plone/tooling`, `@plone/scripts`, `tsconfig`                                      |
 
 ### Volto (Plone 6) — reference only
@@ -55,7 +55,7 @@ Run these from the repo root when working across multiple packages or on the ful
 # Install dependencies
 pnpm install
 
-# Build all publishable packages (registry, client, components, react-router, helpers)
+# Build all publishable packages (registry, client, icons, quanta, components, react-router, helpers)
 pnpm build:deps
 
 # Lint the entire repo

Makefile

@@ -142,6 +142,12 @@ docs-test: docs-clean docs-linkcheckbroken docs-vale  ## Clean docs build, then
 packages/registry/dist: $(shell find packages/registry/src -type f)
 	pnpm build:registry
 
+packages/icons/dist: $(shell find packages/icons/src -type f)
+	pnpm build:icons
+
+packages/quanta/dist: $(shell find packages/quanta/src -type f)
+	pnpm build:quanta
+
 packages/components/dist: $(shell find packages/components/src -type f)
 	pnpm build:components
 
@@ -155,7 +161,7 @@ packages/react-router/dist: $(shell find packages/react-router/src -type f)
 	pnpm build:react-router
 
 .PHONY: build-deps
-build-deps: packages/registry/dist packages/components/dist packages/client/dist packages/react-router/dist packages/helpers/dist  ## Build dependencies
+build-deps: packages/registry/dist packages/icons/dist packages/quanta/dist packages/components/dist packages/client/dist packages/react-router/dist packages/helpers/dist  ## Build dependencies
 
 ##### Release
 

apps/aurora/news/+quanta-upgrade.documentation

@@ -0,0 +1 @@
+Documented how to upgrade existing add-ons for the split of `@plone/components` into `@plone/quanta` and `@plone/icons`. @sneridagh

apps/aurora/news/+quanta.internal

@@ -0,0 +1 @@
+Import icons from `@plone/icons`. Depend on `@plone/quanta` and pre-bundle its dependencies. @pnicolli

apps/aurora/package.json

@@ -55,11 +55,13 @@
     "@plone/client": "workspace:*",
     "@plone/cmsui": "workspace:*",
     "@plone/components": "workspace:*",
+    "@plone/icons": "workspace:*",
     "@plone/contents": "workspace:*",
     "@plone/helpers": "workspace:*",
     "@plone/layout": "workspace:*",
     "@plone/plate": "workspace:*",
     "@plone/publicui": "workspace:*",
+    "@plone/quanta": "workspace:*",
     "@plone/react-router": "workspace:*",
     "@plone/registry": "workspace:*",
     "@plone/theming": "workspace:*",

apps/aurora/tsconfig.json

@@ -11,7 +11,7 @@
   "exclude": ["packages/*"],
   "compilerOptions": {
     "lib": ["DOM", "DOM.Iterable", "ES2022"],
-    "types": ["@react-router/node", "vite/client", "@plone/components/icons"],
+    "types": ["@react-router/node", "vite/client", "@plone/icons/svg"],
     "isolatedModules": true,
     "esModuleInterop": true,
     "jsx": "react-jsx",

apps/aurora/vite.config.ts

@@ -2,7 +2,7 @@ import { reactRouter } from '@react-router/dev/vite';
 import path from 'node:path';
 import { defineConfig, PluginOption } from 'vite';
 import { PloneRegistryVitePlugin } from '@plone/registry/vite-plugin';
-import { PloneSVGRVitePlugin } from '@plone/components/vite-plugin-svgr';
+import { PloneSVGRVitePlugin } from '@plone/icons/vite-plugin-svgr';
 import applyAddonViteConfiguration from './.plone/vite.loader.js';
 import babel from 'vite-plugin-babel';
 import tailwindcss from '@tailwindcss/vite';
@@ -62,24 +62,32 @@ export default defineConfig(({ command, mode, isSsrBuild }) => {
         'react-i18next',
         // Injected by babel-plugin-react-compiler, not in any package.json
         'react/compiler-runtime',
-        // @plone/components and @plone/helpers are not registered add-ons, so
-        // their deps can't be declared in vite.extend.js — list them here
-        '@plone/components > @internationalized/date',
-        '@plone/components > @react-aria/utils',
-        '@plone/components > @react-spectrum/utils',
+        // @plone/components, @plone/icons, @plone/quanta and @plone/helpers are
+        // not registered add-ons, so their deps can't be declared in
+        // vite.extend.js — list them here
         '@plone/components > clsx',
         '@plone/components > react-aria',
         '@plone/components > react-aria-components',
         '@plone/components > react-aria-components/DropZone',
-        '@plone/components > react-aria-components/Form',
-        '@plone/components > react-aria-components/Group',
-        '@plone/components > react-aria-components/Modal',
-        '@plone/components > react-aria-components/Table',
-        '@plone/components > react-aria-components/Tooltip',
-        '@plone/components > react-aria-components/composeRenderProps',
-        '@plone/components > react-stately',
-        '@plone/components > tailwind-merge',
-        '@plone/components > tailwind-variants',
+        '@plone/icons > @react-aria/utils',
+        '@plone/icons > @react-spectrum/utils',
+        '@plone/icons > clsx',
+        '@plone/icons > tailwind-variants',
+        '@plone/quanta > @internationalized/date',
+        '@plone/quanta > @react-aria/utils',
+        '@plone/quanta > clsx',
+        '@plone/quanta > react-aria',
+        '@plone/quanta > react-aria-components',
+        '@plone/quanta > react-aria-components/DropZone',
+        '@plone/quanta > react-aria-components/Form',
+        '@plone/quanta > react-aria-components/Group',
+        '@plone/quanta > react-aria-components/Modal',
+        '@plone/quanta > react-aria-components/Table',
+        '@plone/quanta > react-aria-components/Tooltip',
+        '@plone/quanta > react-aria-components/composeRenderProps',
+        '@plone/quanta > react-stately',
+        '@plone/quanta > tailwind-merge',
+        '@plone/quanta > tailwind-variants',
         '@plone/helpers > jotai',
         '@plone/helpers > jotai/utils',
         '@plone/helpers > jotai-optics',

docs/conceptual-guides/modular-arch-packages.md

@@ -60,7 +60,13 @@ The core packages are:
 :   JavaScript API client for Plone backend.
 
 `@plone/components`
-:   Unified React components for Plone.
+:   Basic, white-label React components for Plone.
+
+`@plone/icons`
+:   Icon set, `Icon` component, and SVG tooling for Plone Aurora.
+
+`@plone/quanta`
+:   Quanta design system components, form widgets, and styles for the CMS UI.
 
 `@plone/registry`
 :   Configuration registry.

docs/development/vite-optimize-deps.md

@@ -80,7 +80,8 @@ The script inspects runtime imports in the workspace packages that require expli
 Run it when:
 
 - you add or remove a runtime import in `@plone/components`, `@plone/helpers`,
-  `@plone/cmsui`, `@plone/layout`, or `@plone/plate`
+  `@plone/icons`, `@plone/quanta`, `@plone/cmsui`, `@plone/layout`, or
+  `@plone/plate`
 - you switch an import to a different package subpath such as
   `some-lib/react`
 - you move an import between browser-only and server-only code and may need to
@@ -108,7 +109,7 @@ Recommended workflow:
 
 ## Non-add-on workspace packages and app deps: `vite.config.ts`
 
-Packages that are not registered add-ons — currently `@plone/components` and `@plone/helpers` — cannot use `vite.extend.js` because `PloneRegistryVitePlugin` never loads their files.
+Packages that are not registered add-ons — currently `@plone/components`, `@plone/icons`, `@plone/quanta`, and `@plone/helpers` — cannot use `vite.extend.js` because `PloneRegistryVitePlugin` never loads their files.
 List their dependencies directly in `apps/aurora/vite.config.ts` under `optimizeDeps.include`.
 
 The same rule applies to packages that are direct dependencies of the app itself (listed in `apps/aurora/package.json`).
@@ -122,6 +123,8 @@ optimizeDeps: {
     'some-app-dep',
     // Non-add-on workspace package dep — requires "pkg > dep" syntax
     '@plone/components > react-aria-components',
+    '@plone/icons > tailwind-variants',
+    '@plone/quanta > react-aria-components',
     '@plone/helpers > jotai',
   ]
 }

docs/how-to-guides/customize-login-screen.md

@@ -68,7 +68,7 @@ The most important requirement is to include a submit button, unless you intenti
 
 ```tsx
 import type { ConfigType } from '@plone/registry';
-import { Button, Link } from '@plone/components/quanta';
+import { Button, Link } from '@plone/quanta';
 
 function MyLoginActions() {
   return (

docs/how-to-guides/icons.md

@@ -4,21 +4,31 @@ myst:
     "description": "Use the Plone Aurora icon system to combine Quanta icons with your own SVGs."
     "property=og:description": "Use the Plone Aurora icon system to combine Quanta icons with your own SVGs."
     "property=og:title": "Use the icon system in Plone Aurora"
-    "keywords": "Plone Aurora, @plone/components, icons, Quanta, SVG, SVGR, guide"
+    "keywords": "Plone Aurora, @plone/icons, icons, Quanta, SVG, SVGR, guide"
 ---
 
 # Icon system
 
 This guide shows how to import icons, customize them, and decide when to use the pre-built React wrappers.
 
-Plone Aurora ships with an icon pipeline via `@plone/components`.
+Plone Aurora ships with an icon pipeline via `@plone/icons`.
 This system is SVG-based, so you can mix its Quanta design system icons with any custom SVGs that you add to your project.
 
 ```{tip}
 Every icon you import is just a React component.
 That means it accepts props, can be composed, and follows the same accessibility rules as any other JSX element.
 ```
 
+## Setup
+
+Import the base icon styles once in your app:
+
+```ts
+import '@plone/icons/icons.css';
+```
+
+This gives icons their base rules, such as inheriting the surrounding text color instead of rendering black, `inline-block` display, and no pointer events. Icon sizes come separately, from the `icon-*` Tailwind utilities generated by `@plone/theming`, or from `@plone/components`' basic CSS.
+
 ## Add custom SVG icons
 
 Plone Aurora uses [{abbr}`SVGR (SVG to React)`](https://react-svgr.com/) through a custom Vite plugin to transform SVG files into React components at build time.
@@ -51,7 +61,7 @@ To fix the TypeScript error `Cannot find module './my-icon.svg?react' or its cor
 
 ```{code-block} ts
 :caption: {file}`packages/<add-on-name>/types.d.ts`
-import '@plone/components/icons';
+import '@plone/icons/svg';
 ```
 ````
 
@@ -93,13 +103,13 @@ export interface IconProps extends DOMProps, AriaLabelingProps {
 
 ## Import Quanta SVG icons
 
-`@plone/components` bundles the Quanta icon set as raw SVG files under the `@plone/components/icons` import path.
+`@plone/icons` bundles the Quanta icon set as raw SVG files under the `@plone/icons/svg` import path.
 These icons go through the same {abbr}`SVGR (SVG to React)` transformation as your custom SVGs.
 
 The following code example shows how to import the trash can icon from the Quanta icon set.
 
 ```tsx
-import TrashSVG from '@plone/components/icons/bin.svg?react';
+import TrashSVG from '@plone/icons/svg/bin.svg?react';
 
 const MyComponent = () => (
   <TrashSVG aria-label="Delete" size="lg" color="--color-quanta-wine" />
@@ -109,12 +119,12 @@ const MyComponent = () => (
 ## Use the pre-built icon components
 
 There's a version of the Quanta icons already wrapped as React components and ready to use.
-They have been pre-built and are available under the `@plone/components/Icons` import path.
+They have been pre-built and are available under the `@plone/icons` import path.
 
 The following code example shows how to use these pre-built components.
 
 ```tsx
-import { AddIcon } from '@plone/components/Icons';
+import { AddIcon } from '@plone/icons';
 
 const MyComponent = () => {
   return <AddIcon aria-label="Add" size="lg" color="--color-quanta-sapphire" />;
@@ -124,7 +134,7 @@ const MyComponent = () => {
 ```{note}
 These pre-built components are equivalent to importing the SVGs directly, but they are bundled JavaScript modules.
 - Use them when the SVGR Vite plugin is not available, for example in Storybook, Jest, or non-Vite frameworks, such as Next.js.
-- When developing `@plone/components` itself, prefer these pre-built modules because the package build pipeline has no awareness of your app's Vite configuration.
+- When developing `@plone/icons` itself, prefer these pre-built modules because the package build pipeline has no awareness of your app's Vite configuration.
 ```
 
 ## Define an icon for a content type

docs/reference/conventions.md

@@ -34,7 +34,7 @@ Also, the Public UI cannot rely on any CMSUI-specific styles or components.
 Storybook is a tool for building UI components in isolation with React.
 It helps you develop components by mocking their different states and interacting with them in a sandbox.
 Plone Aurora follows a Storybook-first approach, so new components should be developed in Storybook first before adding them to the app.
-This mainly applies to design system components (`@plone/components`), but you can also use it for other structural components (`@plone/layout`).
+This mainly applies to design system components (`@plone/components`, `@plone/quanta`), but you can also use it for other structural components (`@plone/layout`).
 
 You can see the Storybook for this package at [Plone Aurora Storybook](https://plone-storybook.readthedocs.io/latest/?path=/docs/introduction--docs).
 
@@ -57,28 +57,36 @@ Otherwise, we'd have to patch the resolution process for every build or bundler
 
 ## `@plone/components` package
 
-This package is the design system for Plone 7.
-It contains reusable UI components like buttons, forms, modals, and more components.
+This package contains the basic, white-label set of reusable UI components for Plone 7, such as buttons, forms, modals, and more.
 
 When adding new components, make sure they are generic and reusable across the app.
 This package should not contain any Plone-specific logic or data handling.
 The components here have to be "dumb" and receive plain props to render its output.
 For example, they will never have the logic for fetching data from Plone or handling authentication.
-This package is a first-level Plone modular architecture package, thus it can't depend on any other Plone package except `@plone/types`.
+This package is a first-level Plone modular architecture package, and it can only depend on `@plone/types` and `@plone/icons`.
 Also, document them well and include Storybook stories to show how to use them and their different states.
 
-There are two sets of components here:
-- Tailwind-based components, which you can use directly and are styled with Tailwind CSS classes.
-- Headless components, which provide functionality without styling, so you can style them however you want.
-
-We also include a basic "baseline" CSS for the headless components to give you a common starting point.
+The components here are headless: they provide functionality without opinionated styling, so you can style them however you want.
+We also include a basic "baseline" CSS to give you a common starting point.
 These styles are very simple ("vanilla") and easy to override with your own styles.
 You can also use these in Volto projects by installing the `@plone/components` package.
 
-The Tailwind-based components are meant for public themes that also use Tailwind CSS, like the default Plone Aurora theme (`@plone/agave`).
+Check out the Storybook for this package at [@plone/components Storybook](https://plone-components.readthedocs.io/latest/?path=/docs/introduction--docs).
+
+## `@plone/quanta` package
+
+This package contains the Quanta design system: React components styled with Tailwind CSS, the `SizeWidget`, `AlignWidget`, and `WidthWidget` form widgets, and the Quanta CSS, typography, and fonts.
+
+The Quanta components are meant for themes that also use Tailwind CSS, like the default Plone Aurora theme (`@plone/agave`).
 They're also used in the CMSUI, which is based on Tailwind CSS.
+This package never depends on `@plone/components`; it only depends on `@plone/icons`.
 
-Check out the Storybook for this package at [@plone/components Storybook](https://plone-components.readthedocs.io/latest/?path=/docs/introduction--docs).
+Check out the Storybook for this package at [@plone/quanta Storybook](https://plone-quanta.readthedocs.io/).
+
+## `@plone/icons` package
+
+This package owns the Quanta icon set: the raw SVGs, a React component per icon, the `Icon` wrapper component, the `*.svg?react` type declarations, and the SVGR Vite plugin used to transform SVGs into React components at build time.
+It has no dependency on any other Plone package.
 
 ## `@plone/layout` package
 

docs/tutorials/add-prisma-database.md

@@ -236,7 +236,7 @@ Create a new file named {file}`LikeButton.tsx` in the {file}`slots` folder of yo
 ```{code-block} tsx
 :caption: packages/\<add-on-name>/slots/LikeButton.tsx
 import type { RootLoader } from '@plone/aurora/app/root';
-import { Button } from '@plone/components/quanta';
+import { Button } from '@plone/quanta';
 import { useFetcher, useParams, useRouteLoaderData } from 'react-router';
 
 export default function LikeButton() {