---
name: component-authoring
description: Write reusable HTML components in daisyUI semantics — self-contained, theme-aware, documented.
---

# Component Authoring

Library-grade components: copy-paste HTML that survives any theme

Author components worthy of a library: each one is a self-contained HTML block that renders correctly inside any daisyUI theme and teaches the reader something.

## Anatomy of a library component

1. **Name** — concrete, not cute ("Editorial Hero", not "Hero Deluxe").
2. **Subtitle** — what it is in one line.
3. **Code** — complete HTML, no external dependencies beyond Tailwind/daisyUI.
4. **Preview** — the same markup rendered live.
5. **Notes** — usage, rules, variations.

## Code rules

- Use daisyUI semantic classes (`btn`, `card`, `badge`) + Tailwind utilities. Never raw hex colors when a semantic token exists — `bg-primary` survives re-theming, `bg-[#e8704f]` doesn't.
- Opacity modifiers over semantic tokens (`text-base-content/60`) give you the dim-scale for free.
- One `<style>` attribute allowed per component for font-family hooks; everything else stays class-based.
- No JavaScript unless interaction demands it; prefer `<details>`, popovers, and CSS-only patterns.
- Placeholder images: `https://picsum.photos/seed/<seed>/<w>/<h>` — seeded so previews stay stable.
- Accessible by construction: real `<button>`/`<a>`, visible labels, alt text that describes content.

## Preview rules

The preview renders inside the live site's theme — which is exactly the point: if your component looks wrong in the preview frame, it will look wrong in users' themes. Keep previews compact (constrain widths, trim list lengths) but never alter the structure between `code` and `preview_html`.

## Notes rules

- **Usage**: when to reach for this component.
- **Rules**: 4–6 hard rules, each one sentence, imperative voice.
- **Variations**: 2–3 named variants with the single change that creates them.

## Anti-patterns

- Components tuned to one theme's colors ("looks broken in light mode").
- Fixed pixel widths instead of max-widths and grids.
- Icon fonts or CDN scripts — inline SVG or glyphs only.
- Dummy text like "Lorem ipsum" — write real microcopy; it doubles as usage documentation.