fix(web): export UnoCSS icon safelist

- add package-owned MDI icon safelist to the design preset

- expose typed ./uno safelist exports for consumers

- document the consumer contract and refresh generated skill references

Author: xiaoland

.changeset/design-web-uno-safelist.md

@@ -0,0 +1,5 @@
+---
+"@partner-up-dev/design-web": patch
+---
+
+Export PartnerUp design UnoCSS safelist constants and include the package-owned built-in icon safelist in the default design preset.

docs/20-product-tdd/release-surface.md

@@ -30,6 +30,13 @@ Public component values and component-specific TypeScript helper types are
 imported from the package root. The web package does not expose
 `src/components/*` or `./components/*` as downstream consumer API.
 
+The `./uno` export exposes the default PartnerUp UnoCSS preset plus named
+package-owned safelist constants. The default preset includes the package-owned
+icon safelist so downstream apps that use `partnerUpDesignPreset()` generate
+CSS for built-in component `i-mdi-*` icons even when the icon class only appears
+inside the published design package. Consumers that do not use the preset may
+merge the exported safelist manually.
+
 ## UniApp Package
 
 Release identity:

docs/30-unit-tdd/web/composition-principles.md

@@ -62,6 +62,9 @@ Use these principles when building application UI with
 - Use public props, slots, events, and exported types from component references.
 - Do not depend on `src/components/*`, generated registry internals, or story
   implementation details.
+- When using UnoCSS, use the package `./uno` preset or safelist export for
+  package-owned built-in icons instead of duplicating design package internal
+  `i-mdi-*` class names in app code.
 <!-- agent-skill:end -->
 
 ## Maintainer Notes

docs/30-unit-tdd/web/type-support.md

@@ -18,6 +18,8 @@ component-related TypeScript types in downstream Vue apps.
   `import { PuButton } from '@partner-up-dev/design-web'`.
 - Import shared and component-specific TypeScript types from the package root:
   `import type { PuButtonFeedback, PuAction } from '@partner-up-dev/design-web'`.
+- Import the UnoCSS preset and safelist constants from
+  `@partner-up-dev/design-web/uno`.
 - Do not import from `@partner-up-dev/design-web/components/*`,
   `@partner-up-dev/design-web/src/*`, generated registry internals, or raw
   implementation files.
@@ -38,6 +40,16 @@ component-related TypeScript types in downstream Vue apps.
   the package.
 - Treat styles and Sass as styling entries only; do not use them to reach
   component implementation files.
+
+## UnoCSS
+
+- Use `partnerUpDesignPreset()` from `@partner-up-dev/design-web/uno` when the
+  consuming app uses UnoCSS.
+- The preset includes the package-owned safelist for built-in component
+  `i-mdi-*` icons; consumers that cannot use the preset may merge
+  `partnerUpDesignSafelist` manually.
+- Keep consumer-provided icon classes, such as `PuInput` prefix or suffix icon
+  values, in the consuming app's own UnoCSS scan scope or safelist.
 <!-- agent-skill:end -->
 
 ## Maintainer Notes

packages/web/README.md

@@ -26,5 +26,21 @@ or `@partner-up-dev/design-web/src/*`; those paths are not consumer API.
 ## UnoCSS
 
 ```ts
+import { defineConfig, presetIcons } from 'unocss'
 import partnerUpDesignPreset from '@partner-up-dev/design-web/uno'
+
+export default defineConfig({
+  presets: [
+    partnerUpDesignPreset(),
+    presetIcons(),
+  ],
+})
+```
+
+`partnerUpDesignPreset()` includes the package-owned icon safelist used by
+default component UI. Consumers that compose a custom UnoCSS config without the
+preset can merge `partnerUpDesignSafelist` manually.
+
+```ts
+import { partnerUpDesignSafelist } from '@partner-up-dev/design-web/uno'
 ```

packages/web/package.json

@@ -34,6 +34,7 @@
     },
     "./utils/*": "./src/utils/*",
     "./uno": {
+      "types": "./dist/styles/unocss-preset.d.ts",
       "import": "./src/styles/unocss-preset.ts"
     },
     "./types": {

packages/web/skills/design-web/references/composition-principles.md

@@ -53,3 +53,6 @@ Use these principles when building application UI with
 - Use public props, slots, events, and exported types from component references.
 - Do not depend on `src/components/*`, generated registry internals, or story
   implementation details.
+- When using UnoCSS, use the package `./uno` preset or safelist export for
+  package-owned built-in icons instead of duplicating design package internal
+  `i-mdi-*` class names in app code.

packages/web/skills/design-web/references/type-support.md

@@ -10,6 +10,8 @@ component-related TypeScript types in downstream Vue apps.
   `import { PuButton } from '@partner-up-dev/design-web'`.
 - Import shared and component-specific TypeScript types from the package root:
   `import type { PuButtonFeedback, PuAction } from '@partner-up-dev/design-web'`.
+- Import the UnoCSS preset and safelist constants from
+  `@partner-up-dev/design-web/uno`.
 - Do not import from `@partner-up-dev/design-web/components/*`,
   `@partner-up-dev/design-web/src/*`, generated registry internals, or raw
   implementation files.
@@ -30,3 +32,13 @@ component-related TypeScript types in downstream Vue apps.
   the package.
 - Treat styles and Sass as styling entries only; do not use them to reach
   component implementation files.
+
+## UnoCSS
+
+- Use `partnerUpDesignPreset()` from `@partner-up-dev/design-web/uno` when the
+  consuming app uses UnoCSS.
+- The preset includes the package-owned safelist for built-in component
+  `i-mdi-*` icons; consumers that cannot use the preset may merge
+  `partnerUpDesignSafelist` manually.
+- Keep consumer-provided icon classes, such as `PuInput` prefix or suffix icon
+  values, in the consuming app's own UnoCSS scan scope or safelist.

packages/web/src/styles/unocss-preset.ts

@@ -119,8 +119,31 @@ const marginPropertyMap: Record<string, string[]> = {
   lb: ["margin-left", "margin-bottom"],
 };
 
+export const partnerUpDesignSafelist = [
+  "i-mdi-alert-circle-outline",
+  "i-mdi-alert-outline",
+  "i-mdi-arrow-left",
+  "i-mdi-check-bold",
+  "i-mdi-check-circle-outline",
+  "i-mdi-chevron-down",
+  "i-mdi-chevron-right",
+  "i-mdi-close",
+  "i-mdi-close-circle",
+  "i-mdi-eye",
+  "i-mdi-eye-off",
+  "i-mdi-file-multiple-outline",
+  "i-mdi-file-outline",
+  "i-mdi-information-outline",
+  "i-mdi-link-variant",
+  "i-mdi-loading",
+  "i-mdi-tray-arrow-up",
+] as const;
+
+export const partnerUpDesignIconSafelist = partnerUpDesignSafelist;
+
 export default definePreset(() => ({
   name: "partner-up-design",
+  safelist: [...partnerUpDesignSafelist],
   theme: {
     colors,
     spacing,

tasks/histoire-mdi-icons-diagnosis/README.md

@@ -137,3 +137,39 @@ http://localhost:6006/__sandbox.html?storyId=src-stories-display-pudescriptionli
 +-- i-mdi-chevron-right and i-mdi-content-copy had non-none mask-image
 +-- screenshot confirmed both icons visible
 ```
+
+## Consumer Package Safelist Follow-up
+
+Date: 2026-06-19
+
+Observed mismatch:
+
+```text
+Histoire:
+- PuPageHeader default back icon span measured 18x18
+- computed mask-image was non-none
+- stylesheet contained .i-mdi-arrow-left
+
+Consumer app /pr/34:
+- PuPageHeader back button existed
+- default back icon span measured 0x0
+- computed mask-image was none
+- stylesheet contained no .i-mdi-arrow-left rule
+```
+
+Root cause:
+
+The published design package uses package-owned `i-mdi-*` classes inside
+component defaults. Downstream UnoCSS can generate icon CSS only for classes it
+matches through its scan graph or safelist. A consumer can have `presetIcons()`
+configured and still miss an icon class that appears only inside the installed
+design package runtime output.
+
+Fix direction:
+
+- Export package-owned icon safelist constants from `@partner-up-dev/design-web/uno`.
+- Include that safelist in the default PartnerUp design UnoCSS preset so
+  consumers that already call `partnerUpDesignPreset()` get built-in component
+  icon CSS automatically.
+- Keep consumer-provided icon class props outside the package safelist; those
+  remain the consuming app's scan or safelist responsibility.