# Droost Theme

> A base theme with design tokens, Tailwind CSS v4, daisyUI and reusable Drupal components.

**An agent-first base theme: restyle a whole site by editing data, with no
build pipeline in the way.**

Droost Theme is built so an AI coding agent, or a person, can change how a
site looks by editing tokens and classes rather than a build. It is the
theme layer of Droost and the default theme of the
[Droost CMS](https://droost.org/docs/droost-cms.md) recipe.

- **Tailwind CSS v4.** In development, every utility class works the moment
  it is written: no build step, no safelist, no purge.
- **daisyUI components.** `btn btn-primary`, `card`, `hero`, `navbar`,
  `stats`, `alert` and the rest, in any template.
- **Design tokens as editable CSS.** `css/tokens.css` holds the theme's
  colours, radii and surfaces (`--color-primary`, `--color-base-100`,
  `--radius-box`). Rebranding the whole site is an edit to that one file.
- **21 Canvas-ready components.** Single Directory Components (hero, card,
  button, section, grid, stats, steps, tabs, timeline, carousel and more)
  with prop schemas strict enough for Drupal Canvas and UI Patterns'
  component formatters.

## The three styling layers

Edit the highest layer that solves the problem:

1. **Tokens** (`css/tokens.css`): palette, radii, surfaces. The right layer
   for "make it feel like our brand".
2. **Component classes:** daisyUI's vocabulary in templates.
3. **Utility classes:** any Tailwind utility, in Twig or component markup.

## Rebranding that survives composer update

An edit to `css/tokens.css` in `themes/contrib` lasts until the next
`composer update`. The durable way is a subtheme: the same tokens, the same
daisyUI vocabulary and still no build step, with the file you edit in your
own repository. The README walks through the three short files a subtheme
needs, including the one that is easy to miss (regions are not inherited,
so restate them).

## Production CSS, no Node needed

The `css_mode` setting chooses how Tailwind and daisyUI arrive:

- **`compiled`** (the default, for production): `css/droost_theme.css` is
  built and committed, so installing the theme never needs Node. No
  JavaScript at runtime, no flash of unstyled content, nothing for a
  Content Security Policy to allow.
- **`jit`** (for development): the Tailwind browser runtime and daisyUI, so
  an agent can use any utility class in any template at once.

## Install

```bash
composer require 'drupal/droost_theme:^1.0'
drush theme:install droost_theme
drush config:set system.theme default droost_theme
```

Block placements (branding, main menu, messages, local tasks, title) ship
as optional configuration. The Droost CMS recipe installs this theme and
makes it the default for you.

## Custom CSS in production

The base theme's compiled stylesheet includes its own component classes.
A subtheme that adds utility classes must compile those classes into its
own stylesheet and attach it through a library. JIT development can hide
missing production CSS, so verify the site in `compiled` mode before deploying.
Plain CSS in a custom library, as used by this documentation site, needs no
Tailwind compilation.

## Requirements

- Drupal 10.3 or later, 11 or 12; PHP 8.3 or later.
- No Node to install. Node is needed only to rebuild the compiled CSS
  yourself.

The project: [Droost Theme on drupal.org](https://www.drupal.org/project/droost_theme).