daisy-cotton-ext

Extended components and page blocks for django-cotton and daisyUI.

Built on django-cotton and daisyUI. daisy-cotton holds one Cotton component for each daisyUI component. This package holds what is built on top of those, and it comes in two kinds:

• Extended components: single components that go further than their daisyUI counterpart, such as a card with more structure than card gives you.
• Page blocks: whole regions of a public-facing page, such as a hero, ready to drop in.

The blocks came first, and they are what is built so far.

Component libraries in this space cover the application: navigation, forms, tables, dialogs. They stop at the pages that sit in front of it — the landing page, the pricing page, the sign-up pitch. Those get assembled by hand out of raw utility classes, in every project, every time.

Blocks are configured through attributes and take their colours from whatever daisyUI theme the project already runs, so a page built from them re-themes with the rest of the site.

Contents

• Status
• Scope & philosophy
• Requirements
• Install
• Blocks
• Contributing
• Changelog
• License

Status

Version 0.0.1. Two families are built, heroes and backgrounds, and nothing here is stable. Block names, attributes and the set of classes the stylesheet emits all change between minor versions, and the CHANGELOG is how a project finds out.

Scope & philosophy

What this is. A presentation-only library of extended components and page blocks. Templates, a stylesheet, and the small amount of JavaScript some blocks need. Blocks are configured through attributes and themed by whatever daisyUI theme the project runs, so a page built from them never pins a literal colour into the markup.

What this deliberately is not.

• Not an application. No models, no views, no forms, no URLs, no migrations. A block's content comes from the template author, never from a queryset.
• Not a CSS framework. No daisyUI plugin, no theme layer, no preflight. Those come from the project.
• Not the base components. A component that maps one-to-one onto a daisyUI component belongs in daisy-cotton. What lives here adds to one or combines several.
• Not application chrome. Navigation, forms, tables and CRUD pages take their content from the application, and they are somebody else's job.
• Not a fixed catalogue. The set of blocks grows as new ones are designed. There is no taxonomy to fill in.
• Not page templates. Blocks only. You pick the ones you want and assemble the page yourself. There is no one-tag landing page.

Tie-breaks. When two of these pull against each other: theme-driven beats hard-coded, a block that composes existing daisyUI markup beats one that invents its own, and leaving a job to the project beats doing it here.

The directions the package works toward are in GOALS.md, and the order they are being built in is in the roadmap.

Requirements

• Python 3.12+
• Django 5.2, 6.0 or 6.1
• django-cotton 2.6+
• daisyUI 5, loaded by the project

daisyUI is a hard requirement and this package does not ship it. Any project already running daisyUI satisfies it, whether through its own Tailwind build or through a package that provides one, such as django-mvp.

Install

pip install daisy-cotton-ext

Add it to INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "django_cotton",
    "daisy_cotton_ext",
]

Then load its stylesheet alongside the one carrying daisyUI:

<link rel="stylesheet" href="{% static 'css/your-daisyui-build.css' %}">
<link rel="stylesheet" href="{% static 'css/daisy-cotton-ext.css' %}">

The two stylesheets do different jobs. Yours carries daisyUI, its themes and Tailwind's preflight. This one carries the plain Tailwind utilities the blocks need and which your build has no way to know about, because it scans your source and these templates live in site-packages. Some rules will appear in both, which costs bytes and nothing else.

Blocks are then available as Cotton tags:

<c-hero.centred title="Ship it on Friday">
  ...
</c-hero.centred>

Blocks

Heroes

Three arrangements and one inline helper. A different arrangement is a different tag rather than an option on one component, so moving a page from one to another is a one-word change.

The three arrangements take the same attributes:

And the same slots. Anything you pass that is not listed above is forwarded to the section element, so id, data- attributes and the rest reach the markup untouched.

Backgrounds

A background is not part of a layout, so it is not part of a block. Each one is its own block that goes in another block's background slot, which means any background composes with any layout.

Six more move. Each one holds still for a reader whose system asks for reduced motion.

An attribute that sets an amount takes a number, and any number works:

The number is written to the layer's style attribute, as a custom property or as opacity. A page served under a content security policy that forbids inline styles ignores it and gets the defaults.

The movement is CSS only. Parallax relies on scroll-driven animation, so in a browser without it the wrapped background stays where it is. It also needs every element between itself and the page to clip with overflow: clip and never overflow: hidden, which the hero blocks do.

Two things to know about them. A background belongs in a background slot and nowhere else, because it positions itself against that slot's wrapper rather than filling its parent in normal flow. And a dark background needs invert on the block, since a background cannot reach up to recolour its sibling. Each block's page says whether it wants one.

<c-hero.centred title="Ship the page, not the CSS"
                lead="Blocks for the pages in front of your app."
                invert>
  <c-slot name="background">
    <c-background.image src="{% static 'img/desk.jpg' %}" dim="0.85" />
  </c-slot>
  <c-slot name="actions">
    <a class="btn btn-primary btn-lg" href="{% url 'signup' %}">Get started</a>
  </c-slot>
</c-hero.centred>

Every attribute, its accepted values and its default are listed on each block's own page in the example project, built from the annotations in the block's template. Run it with python manage.py runserver from a checkout.

Contributing

Development setup, building the stylesheet and the rules changes are held to are in CONTRIBUTING.md.

Changelog

Every release is recorded in CHANGELOG.md.

License

MIT