daisyui 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41fa98f82c0377c4615fa5e4a1091ae8383688a951acb726122866cefa273665
-  data.tar.gz: 651713886837f46040942fc397089d1194dc35787ab1ba18308db97f12d94a06
+  metadata.gz: b1bf5647c845ed4fbdf7d538e4934c7171b23039cbc9029d8c68330b82f0acd2
+  data.tar.gz: 9282c494a1db396b4153fda3c9696040e8c95ac7d495d0bbcf9a0be983a49fb1
 SHA512:
-  metadata.gz: be24df2be52d01adbda5f9e257650d788352a0dfd286bee5c734dfce66aee0377dd0ad601269363ffd734d908cd0c2cde612062017dc59fde61086f4f53e716c
-  data.tar.gz: 2320af028c2539b849de1feb7c1d2690cc6ca0e75da24bd7d838415171c4d922f59b26f5833e1cc1a1e035c330ce532eaae75e21107bd89119f24653f7ab3eb4
+  metadata.gz: f2fa7469a01b18c4bb28110ab4da1238ce8c846fef910e3edc488d283ed641e8cee5fb3b2fb69ca528f643283a1339114db14354a0f3d0d306b67f996923e4d8
+  data.tar.gz: 282f9add88cc7e82eabd013b81bb4e1470c8809f6687ada460470ef97a472d228182154f644c56a7df000f4714dd8d51eca4bbc5692f5ddbbdba7607e84617f4

data/CHANGELOG.md

@@ -1,4 +1,103 @@
-## [2.1.0]
+## [Unreleased]
+
+### Documentation for the variants API
+
+- Docs site: "Variants, states and slots" (when to use `variant`, `flag`,
+  `compound`, `state`/`on` and `slot`, the match values, render order and its
+  three pitfalls, introspection) and "Tailwind sources for your components"
+  (`--app`, the rake task, committing the file, the `stale?` spec, stylelint).
+- MCP server: `get_component` includes the component's `variants.schema`, and a
+  new `variants_guide` tool returns a short guide to the DSL with the pitfalls.
+- README: the variants section links the guide and lists the pitfalls.
+
+### Variants, states and slots
+
+A `variants` block declares what a component that owns its design needs
+beyond `register_modifiers`, as data the gem owns (#67). See the README's
+"Variants, states and slots".
+
+```ruby
+class Widget < DaisyUI::Button
+  variants do
+    base "font-medium"
+    default :size, :md
+    compound style: :outline, color: nil, class: "[--btn-bg:var(--color-base-100)]"
+    state :hover, "hover"
+    state :open, "[.dropdown:is(:focus-within,[open],:has(:popover-open))>&]"
+    on %i[hover open], style: %i[ghost link], class: "[--btn-bg:transparent]"
+  end
+end
+```
+
+- `variant` and `flag` are `register_modifiers` (groups, ClassMerge,
+  inheritance unchanged); `base` appends to the inherited base; `default`
+  applies when the caller names no member of a group.
+- `compound(**match, class:, set:)` adds classes when modifiers hold together
+  or one holds and another is absent (`color: nil`, `shape: [nil, :row]`,
+  `color: true`, flags `true`/`false`); `set:` selects members for the
+  caller's empty groups, in declaration order.
+- `state :name, "variant"` names a Tailwind variant once; `on(states, …)`
+  writes a declaration once and renders it under each state.
+- `slot :name, "classes"`, per-slot Hash values, and `slot_classes` /
+  `slot_options` for components with parts.
+- Defaults and `set:` members are resolved, not left to ClassMerge: a default
+  never renders beside the member the caller gave, with class merging off too.
+- A typo (a group, member, flag, state or slot the component does not have)
+  raises `ArgumentError` where it is declared.
+- `Component.variants.schema` returns plain, frozen data: variants, flags,
+  defaults, compounds, `on` rules, states and slots.
+- An unknown modifier's error now lists the component's groups:
+  `… has no modifier :huge. Variants: size: xs, sm, …`.
+- Registries are frozen by `DaisyUI.finalize!` like the others.
+
+### Tailwind sources for an app's own components
+
+State-prefixed classes appear nowhere literally in an app's source, so
+`bin/rails "daisyui:tailwind[app/assets/stylesheets/generated/daisyui_app.css]"`
+(or `daisyui-tailwind --app --require FILE`) writes `@source inline(…)` for
+every `DaisyUI::Base` subclass the app defines: its classes, compounds, slots
+and each `on` class per state. Sorted, versionless output meant to be
+committed; `DaisyUI::Tailwind.stale?(path)` fails a spec when a declaration
+changed and the file was not regenerated. From Ruby:
+`DaisyUI::Tailwind.sources(app: true)`.
+
+## [2.1.1] - 2026-10-17
+
+### Tailwind sources for only the components an app uses
+
+`bundle exec daisyui-tailwind app -o app/assets/stylesheets/generated/daisyui.css`
+writes the Tailwind sources for the DaisyUI components an app's Ruby and
+templates reference, plus the components those render (Dropdown renders
+Button and Menu): one `@source inline("…")` per component, for the Tailwind
+entry to `@import`. See the README's "Tailwind sources".
+
+- Smaller: pointing `@source` at the whole gem hands Tailwind every class of
+  every component and ClassMerge's catalogue of Tailwind utilities. On an app
+  using 33 of the 77 components the gem's share of the CSS went from 210 KB to
+  126 KB (32 → 19 KB gzipped).
+- More complete: Tailwind v4 drops Ruby comments when it scans a `.rb` file
+  and cannot see a Symbol component class (`self.component_class = :navbar`),
+  so a whole-gem scan generated no `.navbar`, `.card` or `.drawer` rule, nor
+  the rules daisyUI nests under them (`indicator-item`, `stack-top`), unless
+  the app spelled the class out itself. The generated sources carry them.
+- No path in the output, so it is the same on every machine; `--output`
+  rewrites the file only when its content changes, so a CSS watcher does not
+  loop on it.
+- `--format json` gives a build script the components, their classes and
+  their absolute files. From Ruby, `DaisyUI::Tailwind.sources(scan: ["app"])`
+  returns the CSS (`format: :json` for the JSON), and
+  `DaisyUI::Tailwind.used_components(scan: ["app"])` the component names.
+- `--responsive sm,md,lg` adds breakpoint variants of each component class and
+  modifier, for apps that render `responsive:` modifiers (off by default: it
+  multiplies the CSS). `--prefix` matches `DaisyUI.configuration.prefix`,
+  which `DaisyUI::Tailwind.sources` uses by default.
+- The manifest behind it, `data/daisyui/tailwind_manifest.json`, lists every
+  component's class, daisyUI name, file, the components it renders and its
+  classes. It is built from the components (`rake tailwind:manifest`) and a
+  spec fails when it is stale. It lives in the gem's data dir, not `lib/`:
+  an app that keeps scanning the gem's `lib/` builds the same CSS as before.
+
+## [2.1.0] - 2026-10-15
 
 ### DaisyUI finalizes itself at boot: class merging in any Ractor (#58)
 
@@ -35,7 +134,7 @@ then works in any Ractor; each Ractor builds its own merger and LRU.
 - Rendering components inside a Ractor waits on Phlex
   ([yippee-fun/phlex#1055](https://github.com/yippee-fun/phlex/pull/1055)).
 
-## [2.0.2] and earlier
+## [2.0.2] - 2026-10-11
 
 ### Unknown modifiers are reported (#54)
 
@@ -69,6 +168,30 @@ end
   (`DaisyUI::Chat#bubble has no modifier :primray`).
 - Keyword booleans are not validated: unknown keywords stay HTML attributes.
 
+### Changed
+
+- The gem ships minified Stimulus controllers with linked sourcemaps, and the
+  importmap pins them without preloading, so with the lazy registration the
+  README shows (`lazyLoadControllersFrom`) a page that never uses one never
+  fetches it. `daisy_dropdown_controller` 6.1 KB → 2.8 KB (2.4 → 1.3 KB gzipped),
+  `daisy_tooltip_controller` 8.8 KB → 5.2 KB (2.4 → 1.8 KB gzipped). The
+  `daisy_ui/controllers/*` specifiers and the bundler import paths are unchanged.
+
+### Fixed
+
+- Modifiers added with `config.modifiers.add(component: X)` now apply to
+  subclasses of `X` too; the closest class wins.
+
+## [2.0.1] - 2026-10-09
+
+### Fixed
+
+- Button renders the `disabled` attribute on `button`/`input` elements when given
+  `:disabled` or `disabled: true`, so a disabled submit button no longer submits
+  its form from the keyboard (#52).
+
+## [2.0.0] - 2026-09-30
+
 ### Upgrading to 2.0
 
 Components now merge their classes: when two classes conflict, the later one
@@ -110,6 +233,35 @@ wins. `Button(:sm, class: "btn-lg")` renders `btn btn-lg` (1.x rendered
   app components subclassing `DaisyUI::Base` can do the same.
   `config.modifiers.add` takes `group:` to join one.
 
+### Changed
+
+- Maintainers cut releases with `bin/release` (`list`, `--dry-run`, `patch`/`minor`/`major`/`X.Y.Z`), which checks the lockfiles for gems that do not accept the new version yet and then drives `rake release`.
+
+## [1.3.1] - 2026-08-31
+
+### Fixed
+
+- Popover tooltips no longer clip arrows that extend beyond the tooltip card.
+
+## [1.3.0] - 2026-08-30
+
+### Added
+
+- `Tooltip` `:popover` modifier for collision-aware tooltips. It renders real
+  tooltip content in the browser top layer, opens on hover or focus, flips and
+  shifts within the visual viewport, follows scroll/resize while open, and
+  exposes `role="tooltip"`/`aria-describedby` semantics. The bundled
+  `daisy-tooltip` Stimulus controller is auto-pinned for importmap-rails apps
+  and supports a custom controller identifier via `stimulus:`.
+
+## [1.2.1] - 2026-07-03
+
+- No changes to the gem; this release shipped documentation-site and deploy changes only.
+
+## [1.2.0] - 2026-06-26
+
+### Added
+
 - Aura component (DaisyUI 5.6) with style variants (dual, rainbow, holo, gold, silver, glow) and sizes
 - Megamenu component (DaisyUI 5.6) with wide, full, vertical modifiers, sizes, and active_indicator sub-component
 - OTP component (DaisyUI 5.6) for one-time password inputs with configurable digit count, joined modifier, sizes, and color variants
@@ -127,34 +279,27 @@ wins. `Button(:sm, class: "btn-lg")` renders `btn btn-lg` (1.x rendered
   positioning fallback (Safari < 26, Firefox < 147) and optional roving
   keyboard navigation. The default `:popover` dropdown remains zero-JS, and the
   gem stays a plain Phlex library when Rails is absent.
-- `Tooltip` `:popover` modifier for collision-aware tooltips. It renders real
-  tooltip content in the browser top layer, opens on hover or focus, flips and
-  shifts within the visual viewport, follows scroll/resize while open, and
-  exposes `role="tooltip"`/`aria-describedby` semantics. The bundled
-  `daisy-tooltip` Stimulus controller is auto-pinned for importmap-rails apps
-  and supports a custom controller identifier via `stimulus:`.
 
 ### Changed
 
-- The gem ships minified Stimulus controllers with linked sourcemaps, and the
-  importmap pins them without preloading, so with the lazy registration the
-  README shows (`lazyLoadControllersFrom`) a page that never uses one never
-  fetches it. `daisy_dropdown_controller` 6.1 KB → 2.8 KB (2.4 → 1.3 KB gzipped),
-  `daisy_tooltip_controller` 8.8 KB → 5.2 KB (2.4 → 1.8 KB gzipped). The
-  `daisy_ui/controllers/*` specifiers and the bundler import paths are unchanged.
-- Maintainers cut releases with `bin/release` (`list`, `--dry-run`, `patch`/`minor`/`major`/`X.Y.Z`), which checks the lockfiles for gems that do not accept the new version yet and then drives `rake release`.
-
 - Range component: added range-vertical modifier for vertical orientation (DaisyUI 5.6)
 - Tooltip component: added alignment modifiers (tooltip-start, tooltip-center, tooltip-end) and tooltip-content sub-component (DaisyUI 5.6)
 
-### Fixed
+## [1.1.1] - 2026-04-05
 
-- Modifiers added with `config.modifiers.add(component: X)` now apply to
-  subclasses of `X` too; the closest class wins.
-- Popover tooltips no longer clip arrows that extend beyond the tooltip card.
-- Button renders the `disabled` attribute on `button`/`input` elements when given
-  `:disabled` or `disabled: true`, so a disabled submit button no longer submits
-  its form from the keyboard (#52).
+### Changed
+
+- The gem packages only `exe/`, `lib/`, `CHANGELOG.md`, `LICENSE.txt` and
+  `README.md`, listed with `git ls-files` (#14).
+
+## [1.1.0] - 2026-04-05
+
+### Changed
+
+- Components aligned with DaisyUI 5 (#13): new `Hover3d` and `TextRotate`
+  components; `Link` sets the `link` class; `MenuItem` uses
+  `menu-disabled`/`menu-active`/`menu-focus`; Button's `no_animation` and
+  `glass`, Mask's `parallelogram` shapes and Menu's color modifiers are removed.
 
 ## [0.1.0] - 2024-08-02
 

data/README.md

@@ -92,33 +92,166 @@ Consider not including DaisyUI in ApplicationComponent if:
 
 In this scenario, including both DaisyUI and your own component library in `ApplicationComponent` will lead to naming conflicts.
 
-3. Update your `tailwind.config.js` file to include DaisyUI component styles:
+3. Tell Tailwind which classes the gem renders: see [Tailwind sources](#tailwind-sources).
 
-```js
-const execSync = require("child_process").execSync;
-const outputDaisyUI = execSync("bundle show daisyui", { encoding: "utf-8" });
-const daisyUIPath = outputDaisyUI.trim() + "/**/*.rb";
-module.exports = {
-  content: [
-    // ... other paths
-    daisyUIPath,
-  ],
-};
+## Tailwind sources
+
+The gem renders daisyUI class names from Ruby, so Tailwind has to be told
+which ones to generate CSS for. Give it the classes of just the components your
+app uses: `daisyui-tailwind` finds the components your Ruby and templates
+reference, adds the components those render (Dropdown renders Button and Menu,
+Menu renders MenuItem), and writes one `@source inline(...)` per component for
+your Tailwind entry to import.
+
+```sh
+bundle exec daisyui-tailwind app -o app/assets/stylesheets/generated/daisyui.css
 ```
 
-4. Update your tailwind.config.js file to detect TailwindCSS classes in Ruby files.
+```css
+/* app/assets/stylesheets/application.tailwind.css */
+@import "tailwindcss";
+@plugin "daisyui";
+
+@source "../../views";                  /* your own classes, as before */
+@import "./generated/daisyui.css";      /* the DaisyUI components you use */
+```
+
+Run it before Tailwind in your CSS build (it rewrites the file only when its
+content changes, so a watcher does not loop on it). The output names no path,
+so it is the same on every machine: commit it, or generate it on every build.
+
+**From a Node build script**, spawn the command, or read JSON:
 
 ```js
-module.exports = {
-  content: [
-    // ... other paths
-    //
-    // Note the "rb" extension at the end
-    "./app/views/**/*.{erb,haml,html,slim,rb}",
-  ],
-};
+// build-css.js (bun)
+Bun.spawnSync(["bundle", "exec", "daisyui-tailwind", "app", "-o", "app/assets/stylesheets/generated/daisyui.css"])
+
+// or per bundle, as JSON: { components, classes, files, shared, daisyui }
+const out = Bun.spawnSync(["bundle", "exec", "daisyui-tailwind", "app/views/admin", "--format", "json"])
+const { components, classes, files } = JSON.parse(out.stdout.toString())
+```
+
+**From Ruby** (a rake task, a build script):
+
+```ruby
+DaisyUI::Tailwind.used_components(scan: ["app"])         # => ["Button", "Menu", "MenuItem", ...]
+DaisyUI::Tailwind.sources(scan: ["app"])                  # => the CSS partial
+DaisyUI::Tailwind.sources(components: %w[Navbar], format: :json)
+```
+
+| Option | |
+|---|---|
+| `PATH...` | Directories (every `.rb`, `.erb`, `.haml`, `.slim` below) or files to scan. A path that does not exist is an error. |
+| `-c, --component Button,Navbar` | Components to include whether or not a path references them (repeatable). |
+| `-f, --format css\|json` | `css` (default) is the partial to import; `json` is for build scripts. |
+| `-o, --output FILE` | Write to FILE instead of stdout, only when its content changes. |
+| `--responsive sm,md,lg` | Add those breakpoint variants of each component class and modifier, for apps that render `responsive:` modifiers. Off by default: they multiply each component's CSS (sm,md,lg made the sample below 3.7 times larger). |
+| `--prefix d-` | Prefix the classes the way an app that sets `DaisyUI.configuration.prefix` renders them. `DaisyUI::Tailwind.sources` uses the configured prefix by default. |
+
+What counts as a use: a kit call with or without parentheses (`Button(:primary)`,
+`Badge :primary do`, `Button variant do`, `Hero do`), an instance (`Card.new`)
+or the constant (`DaisyUI::Navbar`, `class AppNavbar < DaisyUI::Navbar`).
+Comments do not count (`#` lines in Ruby, `<%# %>` in ERB, `-#` in HAML, `/` in
+Slim), nor does a name starting a sentence in a string ("Join thousands of…").
+Matching is textual and errs on the side of including a component: a false hit
+costs a little CSS, a miss would leave a component unstyled. A gem that renders DaisyUI components for you (phlex-forms wraps
+Input, Select, Range...) is scanned like your app:
+`daisyui-tailwind app "$(bundle info phlex-forms --path)/lib"`; the classes it
+writes in its own Ruby still need its own `@source`. Classes your code builds
+by interpolation (`"badge-#{color}"`) are invisible to Tailwind either way:
+spell them out.
+
+**The size win.** Measured on [cosmos](https://github.com/zoolutions/cosmos)
+(33 of the gem's 77 components), the CSS the gem's classes add to a bundle
+(Tailwind 4.3.2, daisyUI 5.6.13, minified):
+
+| Sources | CSS | gzip |
+|---|---|---|
+| `@source` the gem's whole `lib/` | 210.1 KB | 31.9 KB |
+| `daisyui-tailwind` | 125.7 KB | 19.1 KB |
+| `daisyui-tailwind --responsive sm,md,lg` | 466.5 KB | 64.3 KB |
+
+It is also more complete. Tailwind v4 drops Ruby comments when it scans a `.rb`
+file and cannot see a Symbol component class (`self.component_class = :navbar`),
+so the whole-gem scan generated no `.navbar`, `.card`, `.drawer`... rule (the app
+only got them by spelling the class itself) and none of the sub-rules daisyUI
+nests under them (`indicator-item`, `stack-top`). The manifest carries both.
+
+**Scanning the whole gem still works** as it did:
+
+```css
+/* bundle info daisyui --path, resolved by your build script */
+@source "/path/to/gems/daisyui-x.y.z/lib";
+```
+
+### The manifest
+
+The command reads `data/daisyui/tailwind_manifest.json` in the gem, built from
+the components themselves and checked in (`bundle exec rake tailwind:manifest`
+in this repo). It sits outside `lib/`, so an `@source` on the gem's `lib/` or
+its `**/*.rb` never sees it. A build script in another
+language can read it directly from `$(bundle info daisyui --path)`:
+
+```json
+{
+  "schema": 1,
+  "shared": { "files": ["lib/daisy_ui/base.rb"], "classes": ["bg-primary", "skeleton", "..."] },
+  "components": {
+    "Dropdown": {
+      "class": "DaisyUI::Dropdown",
+      "name": "dropdown",
+      "files": ["lib/daisy_ui/dropdown.rb"],
+      "depends_on": ["Button", "Menu"],
+      "modifiers": ["dropdown-end", "dropdown-top", "..."],
+      "classes": ["dropdown", "dropdown-content", "dropdown-end", "..."]
+    }
+  }
+}
+```
+
+- `name`: the daisyUI component class (`null` where it depends on the modifiers, as for Label).
+- `files`: relative to the gem root, for a literal `@source` instead of `inline()`.
+- `depends_on`: the components it renders; resolve them transitively.
+- `modifiers`: the classes `responsive:` can prefix (with `name`).
+- `classes`: everything it can render: `name`, the modifiers and the class words in its Ruby. Words that are not classes cost nothing.
+- `shared`: base.rb's classes, which every component can render (`:skeleton`, the colour modifiers). Include them with any component.
+
+### Your own components (`--app`)
+
+A component you declare with [`variants`](#variants-states-and-slots) renders
+classes that appear nowhere literally in your source: an `on %i[hover open]`
+rule writes `hover:…` and `[.dropdown…>&]:…` at render time. Tailwind only
+compiles what it finds written out, so hand it your components' classes too:
+
+```sh
+bin/rails "daisyui:tailwind[app/assets/stylesheets/generated/daisyui_app.css]"
+# without Rails: load your components, then walk them
+bundle exec daisyui-tailwind --app --require ./config/components.rb -o app/assets/stylesheets/generated/daisyui_app.css
+```
+
+```css
+@import "./generated/daisyui.css";      /* the gem's components you use */
+@import "./generated/daisyui_app.css";  /* your own: variants, compounds, states, slots */
 ```
 
+With the app loaded (the rake task eager-loads Rails), it walks every
+`DaisyUI::Base` subclass defined outside the gem and writes one
+`@source inline(…)` per component, sorted by name: its component class,
+modifiers, `base`, compound and slot classes, and each `on` class once per
+state. `--responsive` and `--prefix` work as above; `--format json` too. From
+Ruby: `DaisyUI::Tailwind.sources(app: true)`, or `app: [Widget, Picker]` for
+some. The header carries no version and nothing depends on the machine, so the
+file only changes when a declaration does: **commit it**, and let a spec fail
+when it is stale, the way this gem checks its own manifest:
+
+```ruby
+# spec/daisyui_tailwind_spec.rb
+it("has fresh Tailwind sources") { expect(DaisyUI::Tailwind.stale?("app/assets/stylesheets/generated/daisyui_app.css")).to be(false) }
+```
+
+`stale?` eager-loads a Rails app before it compares. The CSS build then never
+boots the app; it only imports the file.
+
 ## Class merging
 
 Components merge their classes so the last conflicting class wins, for Tailwind
@@ -209,6 +342,116 @@ end
 Keyword arguments are not validated: `Toggle(primray: true)` renders a
 `primray` attribute, because unknown keywords are HTML attributes.
 
+## Variants, states and slots
+
+The full guide, with when to use which declaration, is on the docs site:
+[Variants, states and slots](https://daisyui.phlex.fun/docs/variants). Four things
+to know before you write one:
+
+- A `default` renders after the caller's modifiers, so it beats one that sets the same property. Put such a value in `base`.
+- A `compound` or `on` rule also renders after the caller's modifiers. Leave the member it would override out of the match (`layout: [nil, :row]`).
+- `on` writes `"<state>:<class>"`, the state outermost. A rule that needs a child selector first (`[&_li]:hover:...`) stays literal in `base`.
+- `on` classes appear nowhere literally: generate [Tailwind sources](#your-own-components---app) for your components or Tailwind never compiles them.
+
+`register_modifiers` maps a symbol to classes. A component that owns its design
+also needs classes for two modifiers together, the same declarations under a
+browser state, and classes for its parts. Declare them in a `variants` block:
+
+```ruby
+class Widget < DaisyUI::Button
+  OPEN = "[.dropdown:is(:focus-within,[open],:has(:popover-open))>&]"
+
+  variants do
+    base "font-medium"                                        # after the inherited base (btn)
+    variant :size, sm: "btn-sm [--fontsize:var(--text-sm)]"  # overrides one inherited member
+    default :size, :md                                        # when the caller names no size
+
+    compound style: :outline, color: nil, class: "[--btn-bg:var(--color-base-100)]"
+    compound style: %i[ghost link], class: "[--btn-border:transparent]"
+
+    state :hover, "hover"
+    state :open, OPEN
+    on %i[hover open], style: %i[ghost link], class: "[--btn-bg:color-mix(in_oklab,var(--color-base-content)_8%,transparent)]"
+  end
+end
+
+Widget()            # btn font-medium btn-md
+Widget(:ghost, :sm) # btn font-medium btn-ghost btn-sm [--fontsize:…] [--btn-border:transparent]
+                    #   hover:[--btn-bg:…] [.dropdown…>&]:[--btn-bg:…]
+```
+
+| Declaration | |
+|---|---|
+| `variant :group, member: "classes", …` | Alternatives: the grouped `register_modifiers(group: { … })`. Members merge as one ClassMerge group. |
+| `flag :name, "classes"` | An on/off modifier: an ungrouped `register_modifiers` entry. `flag :name` alone is a `register_flags` flag, no class, for compounds to match. |
+| `base "classes"` | Classes every instance gets, appended to the inherited base. |
+| `default :group, :member` | The member used when the caller names none of the group. Never rendered beside a member the caller gives. |
+| `compound(**match, class:, set: {})` | `class:` when every key of `match` holds. `set: { group: :member }` selects members for the caller's empty groups; later compounds see them. Applied in order, after defaults. |
+| `state :name, "variant"` | Names a Tailwind variant once: `"hover"`, `"focus-visible"`, `"[.dropdown[open]>&]"`. |
+| `on(states, **match, class:)` | Like `compound`, with each class written once per state: `on %i[hover open], class: "a"` renders `hover:a [.dropdown…>&]:a`. |
+| `slot :name, "classes"` | A part of the component (see below). |
+
+A `match` value says when a group or flag holds:
+
+| Value | Holds when |
+|---|---|
+| `:member` | that member is selected: given, defaulted or set by an earlier compound |
+| `[:a, :b]` | any of them is; a `nil` in the list means "or none": `shape: [nil, :row]` |
+| `nil` / `false` | no member of the group is |
+| `true` | any member of the group is: `color: true` |
+| `true` / `false` | for a flag: it is on / off |
+
+Classes render in this order, merged by ClassMerge: the component class, `base`,
+the given modifiers, the defaulted and set members, compounds, `on` rules,
+`responsive:`, then `class:`. Every declared class goes through
+`DaisyUI.configuration.prefix` like a modifier (`hover:d-…` with `prefix = "d-"`).
+A typo fails where it is declared, at boot: a `compound`, `on`, `default` or
+`set:` naming a group, member, flag, state or slot the component does not have
+raises `ArgumentError`. `class` and `set` are reserved keys: a group called that could never be matched, and nothing stops you naming one.
+
+**Slots.** A component with parts declares each one; a variant, compound or `on`
+value can be a Hash keyed by slot (`root` is the component itself):
+
+```ruby
+class Picker < DaisyUI::Dropdown
+  variants do
+    slot :trigger
+    slot :menu, "mt-2"
+    variant :reach, wide: { root: "picker-wide", menu: "w-96" }
+    state :open, "[.dropdown:is(:focus-within,[open],:has(:popover-open))>&]"
+    on :open, class: { menu: "shadow-lg" }
+  end
+
+  def trigger(*mods, **options, &) = render DaisyUI::Button.new(*mods, **slot_options(:trigger, options), &)
+  def list(*mods, **options, &) = render DaisyUI::Menu.new(*mods, class: slot_classes(:menu, options), **options, &)
+end
+```
+
+`slot_classes(:menu, options)` returns the slot's classes, those of every
+selected member, compound and `on` rule for it, then `options.delete(:class)`,
+merged. `slot_options(:trigger, options)` returns `options` with that `class:`.
+
+**Introspection.** `Widget.variants.schema` is plain, frozen data for a docs
+page, a component gallery or a design-tool parity check:
+
+```ruby
+{
+  base: "btn font-medium",
+  variants: { style: %i[ghost link outline dash soft], size: %i[lg md xs xl sm], … }, # a re-declared member moves last
+  flags: %i[active disabled wide block],
+  defaults: { size: :md },
+  compounds: [{ match: { style: :outline, color: nil }, class: "[--btn-bg:…]", set: {} }, …],
+  on: [{ states: %i[hover open], match: { style: %i[ghost link] }, class: "[--btn-bg:…]" }],
+  states: { hover: "hover", open: "[.dropdown…>&]" },
+  slots: { root: "btn font-medium" }
+}
+```
+
+A component that only calls `register_modifiers` has a schema too (variants and
+flags). An unknown modifier's error names the groups:
+`Widget has no modifier :huge. Variants: style: ghost, link, outline, dash, soft; size: lg, md, xs, xl, sm; …`.
+The state-prefixed classes need [Tailwind sources of their own](#your-own-components---app).
+
 ## Threads, fibers and Ractors
 
 Components and `DaisyUI::ClassMerge` are safe to share between threads (Puma)
@@ -457,6 +700,9 @@ Add to your Claude Code MCP settings (`~/.claude.json` or project `.claude.json`
 - **list_components** - List all available DaisyUI components
 - **get_component** - Get detailed info about a specific component (modifiers, usage examples)
 - **search_components** - Search components by name or modifier
+- **variants_guide** - How to declare a component with `variants`: which declaration to use, the match values, render order and the pitfalls
+
+`get_component` also returns the component's variants schema (groups, flags, defaults, compounds, `on` rules, states and slots).
 
 # Usage