# Default Theme

## Tooling Overview

- Build tool: **Vite**
- CSS pipeline: **Tailwind CSS v4 via `@tailwindcss/vite` with DaisyUI**
- JavaScript: **jQuery-based theme interactions**
- Image optimization: **sharp** during build publish
- CSS entry: `src/css/style.css`
- Main JS entry: `src/js/script.js`
- Standalone classic JS entry: `src/js/conditionals.js`
- Child theme JS scaffold: `src/js/script.js` stub and copied `src/js/conditionals.js`
- Build output:
  - `dist/styles/*` for Vite-managed hashed CSS
  - `dist/fonts/*` for Vite-managed and source-managed fonts
  - `dist/images/*` for Vite-managed and source-managed images with stable simple file names
  - `dist/javascripts/*` for classic JavaScript runtime files (`scripts-*.js`, `conditionals.js`)
- Auto-publish target (default): `../../public/themes/<theme-name-from-theme.json>`

## Essential Files

- `package.json`
  Declares Node requirement, dependencies, and build scripts.
- `vite.config.mjs`
  Registers the Tailwind Vite plugin, builds the CSS entry, turns the classic theme JavaScript into a browser-safe concatenated bundle, copies standalone classic scripts, copies source-managed images/fonts into `dist/`, optimizes images with `sharp`, removes image records from the Vite manifest, and publishes built assets into `public/themes/<theme-name>`.
- `src/css/style.css`
  Tailwind v4 entrypoint. Registers Tailwind, CSS-native `@source` scanning, DaisyUI, the shared brand-value registry, token mappings, and global base element defaults.
- `src/css/components/theme-shared.css`
  Shared theme primitives and compatibility wrappers, including `.site-card`, `.content-rich`, `.btn*`, `.panel*`, `.alert*`, and shared form helper classes.
- `src/css/utility-registry.css`
  Curated `@source inline(...)` utility registry for dynamic CMS/page-builder content that cannot be discovered statically.
- `src/js/script.js`
  Main bundled theme interaction entry. It is bundled with jQuery into `dist/javascripts/scripts-*.js` and loaded through `Theme::vite('src/js/script.js')`.
- `src/js/conditionals.js`
  Standalone classic script emitted as `dist/javascripts/conditionals.js` and loaded through `Theme::script('conditionals.js')`.
- `src/images/`
  Source-managed theme images.
- `src/fonts/`
  Source-managed theme fonts.
- `views/`
  Blade templates scanned for Tailwind class discovery.
- `dist/`
  Generated build output, recreated on each build.
- `theme.json`
  Theme metadata used by the Ignite theme system.
- `Theme::vite()`
  Laravel-facing helper that resolves source entry paths through the published Vite manifest.

## Styling Architecture

- `src/css/style.css` is the source of truth for theme registration and global defaults.
- Raw brand values should only be changed in the `:root` block in `src/css/style.css`.
- Tailwind and DaisyUI both read from that same brand registry, so colors and fonts only need to be updated once.
- `src/css/components/theme-shared.css` is for reusable cross-page primitives and legacy compatibility wrappers.
- Put page- or feature-specific styling in the other files under `src/css/components/`.

## Override Rule

- Avoid `!important` in parent theme styles.
- Prefer normal cascade and selector specificity so child themes can override cleanly.
- Use `!important` only for deliberate exceptions that cannot be expressed another way.

## How To Change The Theme

1. Update shared brand values or global theme registration in `src/css/style.css`.
2. Update shared reusable primitives or compatibility wrappers in `src/css/components/theme-shared.css`.
3. Update page- or feature-specific styling in the relevant file under `src/css/components/`.
4. Update interactions in `src/js/script.js` or add standalone entries under `src/js/`.
5. If you add Tailwind classes to new Blade or JS locations, update the `@source` directives in `src/css/style.css`.

## DaisyUI

- DaisyUI is the primary semantic component layer for this theme.
- Common component classes include:
  - `btn`, `btn-primary`, `btn-secondary`
  - `card`, `card-body`
  - `alert`
  - `badge`
  - `stat`
- DaisyUI does not replace Tailwind layout utilities. Layout, spacing, grid, flex, and responsive behavior still come from Tailwind utilities.
- Tailwind utilities and DaisyUI semantic components both map back to the same `:root` brand registry in `src/css/style.css`.

## Utility Registry

- `src/css/utility-registry.css` uses Tailwind v4 `@source inline(...)`.
- It exists for utilities needed by:
  - CMS-authored content
  - page-builder content
  - other late-authored dynamic content not statically discoverable from Blade or JS
- Keep this file curated. Do not turn it into “all of Tailwind.”

Examples:

- Safe dynamic semantic content: `<div class="btn btn-primary">Dynamic button</div>`
- Dynamic utility content requires registry coverage: `<div class="grid gap-6 lg:grid-cols-3">Dynamic grid</div>`

## Tailwind Scanning

Tailwind scans source files directly from `src/css/style.css` via:

- `@source "../../views/**/*.blade.php";`
- `@source "../js/**/*.js";`

If you add Tailwind classes to new Blade or JS locations, update those `@source` directives.

## Parent Theme JavaScript Inheritance

Non-default themes can inherit JS entry files from `vendor/ignite/themes/<parent-name>/src/js/`.

Behavior:

- If the child theme defines the same relative JS file, the child file replaces the parent file completely.
- If the child theme omits that file, the build falls back to the parent version.
- If the child theme keeps the local `src/js/script.js` stub and imports the parent script, the parent source is inlined during the build and the published output still stays a classic script.
- `src/js/conditionals.js` is published as a standalone classic file and is loaded with `Theme::script('conditionals.js')`.
- Child scaffolding copies the parent `src/js/conditionals.js` file directly so standalone output stays classic JS without ESM import stubs.

How the bundle works:

- `src/js/script.js` is combined with jQuery into the classic `scripts-*.js` asset that the layout loads with a normal `<script>` tag.
- Any child `src/js/script.js` stub can import the parent script for reuse, and `vite.config.mjs` inlines that import before publish so the browser still receives classic JavaScript.
- `src/js/conditionals.js` stays separate, is copied directly to `dist/javascripts/conditionals.js`, and is loaded directly where forms need it with `Theme::script('conditionals.js')`.

Example:

```js
import '../../../vendor/ignite/themes/default/src/js/script.js';

// child-specific additions here
```

## Theme Image Aliases

Theme CSS should reference shared image paths through the `@theme-images` alias instead of hard-coded `../../images/...` paths.

- Parent CSS can keep using shared source files.
- Child themes map `@theme-images` to their own `src/images` folder in `vite.config.mjs`.
- This lets parent CSS stay reusable while each child theme supplies its own images.
- In the current build, `@theme-images` resolves to the child theme's local `src/images` folder only.
- If a child theme wants a parent asset as fallback, create a local wrapper file that imports the parent asset path explicitly.

Example:

```css
.page-banner-bg {
    background-image: url('@theme-images/banner.jpg');
}
```

## Child-First CSS Inclusion

Plain CSS does not have a standard include-path search order like Sass.
This theme keeps the inheritance model simple:

Recommended pattern:

- Keep `src/css/style.css` as the entrypoint.
- Import shared styles with plain relative paths inside the parent stylesheet.
- Let child themes inherit the parent stylesheet directly.
- Add a child stylesheet only when you intentionally want to override or extend the parent output.

Example import pattern:

```css
@import '../../../../vendor/ignite/themes/default/src/css/style.css';
@import './components/site.css';
@import './components/page.css';
```

Notes:

- Relative CSS imports like `@import "./components/page.css";` do not search alternate folders.
- This approach keeps the parent theme buildable by the child theme without wrapper files.

## Assets Pipeline

- Put source-managed images in `src/images`.
- Put source-managed fonts in `src/fonts`.

During build:

- Vite emits hashed theme CSS into `dist/styles`
- The main classic theme script bundle is generated into `dist/javascripts/scripts-*.js`
- Standalone scripts (for `Theme::script()`) are published into `dist/javascripts`
- Vite-emitted and source-managed images are written into `dist/images` using simple stable file names
- Image files are intentionally removed from `manifest.json`; resolve them by direct filename/path rather than `Theme::vite()`
- PNG/JPEG files in `dist/images` are optimized with `sharp`
- Vite-emitted and source-managed fonts are written into `dist/fonts`

Do not hand-manage `dist/` files because build output is regenerated.

## Build

From `themes/default`:

Install dependencies:

```bash
pnpm install
```

If install fails with `ERR_PNPM_IGNORED_BUILDS`, approve build scripts once:

```bash
pnpm approve-builds --all
pnpm install
```

Development build:

```bash
pnpm run build
```

Watch build:

```bash
pnpm run watch
```

Production build:

```bash
pnpm run production
```

Aliases in `package.json`:

- `pnpm run build` = `pnpm run development`
- `pnpm run prod` = `pnpm run production`
- `pnpm run watch-poll` currently runs the same watch build as `pnpm run watch`
- there is no Vite dev server / HMR command in this theme package

## Publishing

Built assets are published automatically after each build into:

- `../../public/themes/<theme-name-from-theme.json>`

Advanced override:

- `THEME_PUBLISH_DIR` can override the publish destination for one-off local or CI builds.

If you still need the Laravel publish command from the project root:

```bash
php artisan ignite:theme:publish default
```

## Activate Theme

Set the active theme in `.env`:

```env
APP_THEME_ACTIVE=default
```

## Legacy Compatibility

The theme still supports legacy semantic classes used across Blade templates, including:

- `.btn*`
- `.panel*`
- `.alert*`
- shared form helper classes

These are compatibility wrappers backed by the tokenized DaisyUI-first theme system. Prefer DaisyUI semantics for new work and only extend the compatibility surface deliberately.
