zabi-components 8.0.0 → 8.1.0

package/docs/lucide-icons.md

@@ -1,26 +1,49 @@
 # Lucide icons used by zabi-components
 
-The package depends on `@lucide/svelte`. If your app **aliases** `@lucide/svelte` to a hand-authored barrel, re-export every icon the library imports, or drop the alias and use the real package (or per-icon paths only).
+The package depends on `@lucide/svelte`. Every component imports each icon it uses from that icon's own file:
 
-## Packaged components (from the `zabi-components` build)
+```ts
+import ChevronDown from "@lucide/svelte/icons/chevron-down";
+```
 
-| Source | Import style | Icons |
-|--------|--------------|--------|
-| `CodeBlock` | Per-icon path | `check`, `copy` |
-| `ThemeToggle` | Barrel | `Sun`, `Moon` |
-| `ListItem` | Barrel | `ArrowRight` |
-| `Badge` | Barrel | `Check`, `AlertTriangle`, `X`, `Info` |
-| `ImageUpload` | Barrel | `Image` |
-| `Input` | Barrel | `CheckCircle`, `AlertTriangle`, `AlertCircle` |
-| `Select` | Barrel | `ChevronDown`, `CheckCircle`, `AlertTriangle`, `AlertCircle` |
-| `SidebarPanel` | Barrel | `Search`, `X` |
-| `SidebarAccountPanel` | Barrel | `LogOut`, `Moon`, `Sun`, `User` |
-| `SidebarNavigation` | Barrel | `Command`, `Search` |
+No component imports from the package's barrel (`import { ChevronDown } from "@lucide/svelte"`). The barrel re-exports every icon, about 1,700 Svelte files, and a bundler has to read and compile all of them to find the one that is used: a SvelteKit app with a single `<Button>` from this library transformed 3,800 modules for its client build when the library used the barrel, and 366 now. `npm run check` fails on a barrel import anywhere under `src` (the components, the stories, the docs site and the catalog's code samples), in `docs`, `.storybook` and the README, because the examples are what gets copied; `npm run build:lib` fails on one in `dist` (`scripts/lucide-barrel.js`). The one exception is `src/types/IconPropsCheck.svelte`, the type test that proves an icon from the barrel is still accepted by every icon prop.
 
-Showcase and demo routes under this repo import additional icons (e.g. `CircleQuestionMark`, `Heart`); those are **not** required for consumers who only install the library.
+## In your app
+
+Import icons the same way, one file each. It is the barrel import that is slow, not the number of icons you use.
+
+```svelte
+<script lang="ts">
+    import { List } from "zabi-components";
+    import House from "@lucide/svelte/icons/house";
+    import Settings from "@lucide/svelte/icons/settings";
+
+    const items = [
+        { id: "1", label: "Home", icon: House },
+        { id: "2", label: "Settings", icon: Settings },
+    ];
+</script>
+```
+
+A barrel-imported icon still works wherever a prop takes an icon: the two are the same component with the same type (`src/types/IconPropsCheck.svelte` holds that in `npm run check`). It only costs you the build time described above.
+
+## Icons re-exported from the package root
+
+For convenience the root entry re-exports a few icons: `Sun`, `Moon`, `Monitor`, `Grip`, `GripVertical`, `ChevronUp`, `ChevronDown`, `ChevronRight`, `Zap`, `Briefcase`, `Clipboard` and `Settings`. Each comes from its own file, so `import { Button } from "zabi-components"` does not reach the barrel.
+
+## If your app aliases `@lucide/svelte`
+
+An alias for `@lucide/svelte` itself no longer covers what the library imports: the components ask for `@lucide/svelte/icons/<name>`. If you replace Lucide with a hand-authored set, alias those paths, for each of these files:
+
+`arrow-left`, `arrow-right`, `briefcase`, `check`, `chevron-down`, `chevron-left`, `chevron-right`, `chevron-up`, `circle-alert`, `circle-check-big`, `clipboard`, `command`, `copy`, `external-link`, `grip`, `grip-vertical`, `image`, `image-off`, `info`, `log-out`, `menu`, `monitor`, `moon`, `octagon-alert`, `play`, `plus`, `search`, `settings`, `star`, `sun`, `trash-2`, `triangle-alert`, `user`, `x`, `zap`.
+
+Showcase and demo routes under this repo import additional icons, some of them from the barrel; those are not part of the package.
 
 ## Typings for `@lucide/svelte/icons/*`
 
-`@lucide/svelte` 0.544.x ships per-icon `.svelte.d.ts` files with a duplicate `type X = ReturnType<typeof X>` line that makes some TypeScript language services treat them as non-modules. This affects editor tooling only, not runtime or builds with `skipLibCheck`.
+`@lucide/svelte` 0.544.x ships per-icon `.svelte.d.ts` files with a duplicate `type X = ReturnType<typeof X>` line that makes some TypeScript language services treat them as non-modules, so an editor may report that an icon has no default export. It affects editor tooling only, not runtime and not a build.
+
+The package runs no install scripts in your project, and since 8.1.0 it lists none either: the dev-only `prepare` script is gone, so installing from a tarball no longer makes npm print an `install-scripts` notice.
 
-Since 8.0.0 the package **does not run any install scripts** in your project. If your editor reports missing icon exports such as `Check` or `Copy`, prefer importing per-icon paths (`@lucide/svelte/icons/check`), enable `skipLibCheck`, or upgrade `@lucide/svelte`. Contributors to this repo get the patch automatically via the dev-only `prepare` script.
+- In your app: if your editor complains, enable `skipLibCheck` or upgrade `@lucide/svelte`.
+- In this repo: `npm run check` (svelte-check) and `npm run build:lib` pass on a fresh install without any patch. If your editor still shows the error, run `npm run fix:lucide-types` once after installing; it strips the duplicate line from the files in `node_modules` and changes nothing else.

package/docs/theme-imports.md

@@ -12,8 +12,74 @@ For most Tailwind v4 apps, use:
 @import "zabi-components/theme-dark-only";
 ```
 
+Without Tailwind, import the compiled stylesheet on its own:
+
+```css
+@import "zabi-components/css";
+```
+
 Use short package exports by default. Legacy deep `dist` imports remain supported for compatibility.
 
+## What the theme files contain
+
+`theme` and `theme-only` hold three things:
+
+1. An `@source` directive for the package's own components. Tailwind CSS v4 does not scan `node_modules`, and this is what makes it generate the classes the components use. You do not need an `@source` line of your own.
+2. The `@theme` block with every token.
+3. The hand-written component rules that Tailwind cannot generate from the tokens: `.focus-ring`, `.text-action-primary`, the action hover, active and disabled states, the semantic colour classes and the `z-*` scale.
+
+`theme-dark` and `theme-dark-only` hold the dark overrides, under three selectors:
+
+```css
+.dark, [data-theme="dark"] { … }
+@media (prefers-color-scheme: dark) { [data-theme="auto"] { … } }
+```
+
+Put `class="dark"` or `data-theme="dark"` on `<html>` for dark, `data-theme="auto"` to follow the system, and `data-theme="light"` (or nothing) for light. Following the system is opt-in. See [THEMING.md](../THEMING.md#light-dark-and-auto).
+
+The dark files only remap roles. The raw palettes (`--zabi-brand-*`, `--zabi-accent-*`, `--zabi-base-*` and the rest) are declared once, in the light theme, so that an app's override of them on `:root` applies in both modes. Before 8.1.0 the dark files restated those ramps; they no longer do, so a dark file must be imported together with a light one (`theme`, `theme-only`, or `colors`, which has both).
+
+## Rebranding
+
+Generate one file from your brand colour and import it after the theme files:
+
+```bash
+npx zabi-theme --brand "#C17B00" --neutral "#78716c" --out src/lib/brand.generated.css
+```
+
+```css
+/* src/lib/theme.css */
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only";
+@import "./brand.generated.css"; /* --zabi-brand-*, --zabi-accent-*, --zabi-base-* */
+
+:root {
+  --font-family-heading: "Your Display Font", var(--font-family-sans);
+}
+```
+
+One file covers light and dark. Which tokens an app may set, the generator's
+options and what does not follow an override are in the theming guide,
+[THEMING.md](../THEMING.md). The same function is exported as `createTheme()`
+from `zabi-components/create-theme`.
+
+The universal scrollbar rules are in the compiled `css` bundle only. Importing a theme does not restyle the scrollbars in your app; add `.scrollbar-semantic` where you want them.
+
+## Tailwind together with the compiled stylesheet
+
+`zabi-components/css` is a finished Tailwind build. It carries its own copy of every utility the components use, `w-full`, `px-6` and `mt-10` among them, in the same `utilities` layer your Tailwind build writes to. Two builds cannot be sorted into one order, so the import order decides which copy wins:
+
+- **Tailwind first, `css` second.** The package's plain utilities land after your variants. `w-full md:w-1/2` stays full width, and `px-6 md:px-8` keeps the narrow padding, wherever the package ships the plain class too.
+- **`css` first, Tailwind second.** Your plain utilities land after the package's variants. `Modal` declares `items-end md:items-center` and `p-0 md:p-4`; if your app uses `items-end` or `p-0` anywhere, the dialog stays at the bottom edge, without padding, on wide screens. A component's own `p-6 pt-0` loses its `pt-0` the same way.
+
+Neither order is right. With Tailwind in the app, import `theme-only` and `theme-dark-only` instead, as above: Tailwind then generates each utility once, in its own order, and both cases resolve. If you started on 8.0.0, where `css` was the only import that worked, switch when you upgrade.
+
+The hand-written colour classes (`bg-card`, `text-headline`, `border-border` and the rest) are outside every layer, in `css` and in the theme files alike, so they win over any utility on the same element: `bg-card md:bg-red-500` keeps the card colour. Change the colour by replacing the class, not by adding a variant next to it.
+
+## Version 8.0.0 and earlier
+
+In 8.0.0 and 7.0.2 the theme files were published without semicolons, without the `@source` directive and without the component rules, so they left components unstyled. Upgrade, or import `zabi-components/css`, which worked in those versions too.
+
 ## Package export paths
 
 Use these subpaths with your bundler or `npm`/`pnpm` resolution:
@@ -22,10 +88,11 @@ Use these subpaths with your bundler or `npm`/`pnpm` resolution:
 |--------|-------------|----------|
 | `zabi-components/theme` | `zabi-components-theme.css` | Tailwind **not** already in the project; ships `@import "tailwindcss"` + `@theme`. |
 | `zabi-components/theme-only` | `zabi-components-theme-only.css` | Tailwind **already** configured; merge only the `@theme` block. |
-| `zabi-components/theme-dark` | `zabi-components-theme-dark.css` | Same as `theme` but for **dark**; includes Tailwind import + `.dark { … }`. |
-| `zabi-components/theme-dark-only` | `zabi-components-theme-dark-only.css` | Tailwind present; **only** `.dark { … }` overrides (import after light theme). |
-| `zabi-components/colors` | `zabi-components-colors.css` | **No Tailwind**: `:root` + `.dark` CSS variables only. |
+| `zabi-components/theme-dark` | `zabi-components-theme-dark.css` | Tailwind import + the dark overrides (`.dark`, `[data-theme]`); import after `theme`. |
+| `zabi-components/theme-dark-only` | `zabi-components-theme-dark-only.css` | Tailwind present; **only** the dark overrides (import after light theme). |
+| `zabi-components/colors` | `zabi-components-colors.css` | **No Tailwind**: `:root` + dark (`.dark`, `[data-theme]`) CSS variables only. |
 | `zabi-components/css` | `zabi-components.css` | Full compiled CSS (utilities, components styles, dark). |
+| `zabi-components/create-theme` | `create-theme/index.js` | Not CSS: the `createTheme()` function behind the `zabi-theme` command. |
 
 ### Legacy export paths (supported, deprecated in docs)
 
@@ -43,7 +110,7 @@ These are still exported for backward compatibility but are not the recommended
 ## Decision matrix
 
 1. **Vanilla CSS or no Tailwind** → `colors` (or full `css` if you need utility classes from the bundle).
-2. **Tailwind v4 app, extend design tokens** → `theme-only` (+ `theme-dark-only` if you use `class="dark"` / dark mode).
+2. **Tailwind v4 app, extend design tokens** → `theme-only` (+ `theme-dark-only` if you use `class="dark"` / `data-theme` / dark mode).
 3. **Minimal setup, one import for light** → `theme`.
 4. **Dark as a second file** → `theme` + `theme-dark`, or `theme-only` + `theme-dark-only`.
 
@@ -85,16 +152,17 @@ These are still exported for backward compatibility but are not the recommended
 @import "zabi-components/colors";
 ```
 
-Toggle `.dark` at the root element to activate dark tokens:
+Toggle `.dark` at the root element to activate dark tokens, or use `data-theme`:
 
 ```html
 <html class="dark">
+<html data-theme="auto">
 ```
 
 ## Maintainer checklist (token changes)
 
-1. Edit **`src/app.css`** only (`@theme` for light tokens, `.dark` for overrides).
-2. If you change **physical base ramp** hexes, keep the **mirrored** `--zabi-base-*` block inside `.dark` in sync with `@theme` (required for standalone dark imports).
+1. Edit **`src/app.css`** only (`@theme` for light tokens, the single `.dark` rule for overrides).
+2. Physical ramps (`--zabi-*`) are declared in `@theme` only. `.dark` must not restate them or hold a hex literal; `validate-theme.js` fails the build if it does.
 3. Run **`npm run build:css`** (or **`npm run build:lib`** before publish).
 4. Confirm **`node scripts/verify-build.js`** passes in CI or locally after builds.
 
@@ -102,11 +170,13 @@ Toggle `.dark` at the root element to activate dark tokens:
 
 | File | Contents |
 |------|----------|
-| `zabi-components.css` | PostCSS/Tailwind output: utilities + theme + `.dark`. |
+| `zabi-components.css` | PostCSS/Tailwind output: utilities + theme + dark. |
 | `zabi-components-theme.css` | `@import tailwind` + `@theme`. |
 | `zabi-components-theme-only.css` | `@theme` only. |
-| `zabi-components-theme-dark.css` | `@import tailwind` + `.dark`. |
-| `zabi-components-theme-dark-only.css` | `.dark` only. |
-| `zabi-components-colors.css` | `:root` + `.dark` as plain custom properties. |
+| `zabi-components-theme-dark.css` | `@import tailwind` + dark. |
+| `zabi-components-theme-dark-only.css` | dark only. |
+| `zabi-components-colors.css` | `:root` + dark as plain custom properties. |
+
+"dark" is the `.dark` rule of `src/app.css`, published as `.dark, [data-theme="dark"]` and again as `[data-theme="auto"]` inside `@media (prefers-color-scheme: dark)`, plus `color-scheme` for the three `data-theme` values.
 
 Build logic lives in **`scripts/build-css.js`** (see file header for behavior).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zabi-components",
-  "version": "8.0.0",
-  "description": "Svelte 5 UI components with TypeScript and Tailwind CSS v4. Accessible, easy to theme, works with SSR.",
+  "version": "8.1.0",
+  "description": "Svelte 5 UI component library: accessible components with TypeScript types, Tailwind CSS v4 design tokens, light and dark themes, and SSR support for SvelteKit.",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -39,6 +39,10 @@
       "types": "./dist/routes/lib/variant-utils.d.ts",
       "import": "./dist/routes/lib/variant-utils.js"
     },
+    "./create-theme": {
+      "types": "./dist/create-theme/index.d.ts",
+      "import": "./dist/create-theme/index.js"
+    },
     "./dist/zabi-components.css": "./dist/zabi-components.css",
     "./dist/zabi-components-colors.css": "./dist/zabi-components-colors.css",
     "./dist/zabi-components-theme.css": "./dist/zabi-components-theme.css",
@@ -53,9 +57,16 @@
     "./css": "./dist/zabi-components.css",
     "./package.json": "./package.json"
   },
+  "bin": {
+    "zabi-theme": "./dist/create-theme/cli.js"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "THEME.md",
     "THEMING.md",
     "docs/theme-imports.md",
@@ -64,13 +75,24 @@
   "keywords": [
     "svelte",
     "svelte5",
+    "svelte-5",
     "sveltekit",
+    "svelte-components",
     "components",
+    "component-library",
     "ui",
+    "ui-components",
+    "design-system",
+    "design-tokens",
     "typescript",
     "tailwind",
+    "tailwindcss",
     "runes",
-    "ssr"
+    "ssr",
+    "accessibility",
+    "a11y",
+    "dark-mode",
+    "theming"
   ],
   "author": "Zabi Components Team",
   "license": "MIT",
@@ -84,7 +106,8 @@
     "build:components": "svelte-package -o dist --input src/components",
     "build:lib-files": "mkdir -p dist/routes/lib dist/types && cp src/components/types/variants.ts dist/types/ && cp src/components/types/page.types.ts dist/types/ && tsc src/routes/lib/variant-utils.ts --declaration --module esnext --target es2020 --moduleResolution bundler --skipLibCheck --rootDir src --outDir .lib-tmp && cp .lib-tmp/routes/lib/variant-utils.js .lib-tmp/routes/lib/variant-utils.d.ts dist/routes/lib/ && rm -rf .lib-tmp",
     "build:fix-imports": "node scripts/fix-package-imports.js",
-    "build:lib": "npm run build:css && npm run build:components && npm run build:lib-files && npm run build:fix-imports && npm run build:types && npm run build:css && node scripts/verify-build.js",
+    "build:lib": "npm run build:css && npm run build:components && npm run build:lib-files && npm run build:fix-imports && npm run build:types && npm run build:css && npm run build:create-theme && node scripts/verify-build.js",
+    "build:create-theme": "node scripts/build-create-theme.js",
     "sync:tokens": "node scripts/sync-theme-tokens.js && node scripts/generate-ramps.js && node scripts/generate-surfaces.js",
     "build:css": "npm run sync:tokens && node scripts/build-css.js && node scripts/validate-theme.js && npm run check:design",
     "check:tokens": "node scripts/check-token-violations.js",
@@ -93,19 +116,23 @@
     "check": "svelte-check --tsconfig ./tsconfig.json && node scripts/check-component-imports.js && node scripts/check-layout-width.js && npm run check:design",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
+    "build:storybook-site": "rm -rf static/storybook && storybook build -o storybook-static --quiet && cp -R storybook-static static/storybook",
+    "build:site": "npm run build:storybook-site && vite build",
+    "vercel-build": "npm run build:site",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
     "test:e2e:smoke": "playwright test --grep @smoke",
     "test:playwright": "npm run test:e2e",
-    "test:themes": "node --test tests/theme-output.test.js",
-    "prepare": "node scripts/fix-lucide-svelte-icon-dts.js",
+    "test:themes": "node --test --test-concurrency=1 tests/theme-output.test.js tests/create-theme.test.js",
+    "fix:lucide-types": "node scripts/fix-lucide-svelte-icon-dts.js",
     "prepublishOnly": "npm run build:lib",
     "publish:npm": "npm publish --access public --registry https://registry.npmjs.org/",
     "check:ramps": "node scripts/check-ramp-lightness.js",
     "check:contrast": "node scripts/check-contrast.js",
     "check:geometry": "node scripts/check-control-geometry.js",
-    "check:design": "npm run check:ramps && npm run check:contrast && npm run check:geometry && npm run check:tokens"
+    "check:states": "node scripts/check-state-variants.js",
+    "check:design": "npm run check:ramps && npm run check:contrast && npm run check:geometry && npm run check:tokens && npm run check:states"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",
@@ -122,7 +149,6 @@
     "@tsconfig/svelte": "^5.0.5",
     "@types/node": "^24.5.2",
     "autoprefixer": "^10.4.17",
-    "culori": "^4.0.2",
     "jsdom": "^29.0.2",
     "postcss": "^8.4.35",
     "storybook": "^10.2.19",
@@ -135,6 +161,7 @@
   },
   "dependencies": {
     "@lucide/svelte": "^0.544.0",
+    "culori": "^4.0.2",
     "tailwind-merge": "^3.7.0"
   },
   "peerDependencies": {