# Theming

> For AI: how a widget built from the canonical template gets its colors, typography and radii, and what it may and may not style. The rules below are enforced by the template's Stylelint configuration and its `tests/boundaries/styleBoundaries.test.ts`.

---

## The site carries the theme, the widget does not

The Modyo site loads Dynamic UI's CSS, the theme and the fonts **once for the whole page**. The widget ships only its own styles: `src/app/main.tsx` imports `@/styles/base.scss` and nothing else, and the build puts those styles in `dist/main.css`.

If a widget bundled Dynamic's CSS or its own theme, every widget on the page would download it again, redeclare `:root` with Dynamic's defaults (overriding the site's brand, depending on load order) and could mix two versions of the library.

So the brand lives in the **site's theme**, not in the widget. To brand a widget, adjust the site's theme.

---

## What the widget does not define

In `src/` the template does not allow:

- hex or named colors. In TSX style objects (`style={{}}`), color properties (`color`, `background`, `borderColor`, `fill`, …) only take `var(--…)`, also inside shorthands (`border`, `outline`, `boxShadow`: `'1px solid var(--bs-border-color)'`);
- `font`, `font-family`, `border-radius` or the per-corner radii, also in `style={{}}`;
- SCSS variables (`$x`) and `@import`;
- Dynamic UI's CSS, compiled (`dynamic-ui.css`) or from its sources (`@dynamic-framework/ui-react/src/style/…`). The only Dynamic partial allowed is `abstracts/+import` (functions and mixins such as `media-breakpoint-up`; it emits no CSS, and its SCSS variables are not used either);
- `[data-bs-theme]` selectors, with or without a value.

`npm run stylelint` checks `.css` and `.scss`; the boundary test also checks `.ts` and `.tsx`, including `style={{}}`. Each error names the file, the line and what to use instead.

---

## What the widget does

### Use Dynamic's tokens and utilities

Colors, typography and spacing come from Dynamic's custom properties (`var(--bs-*)`) and utility classes (`fs-*`, `fw-*`, `rounded-*`, `text-*`, `bg-*`, spacing). In components, use the `color` prop (`<DButton color="secondary" />`, `<DIcon color="primary" />`).

### Prefix its own classes

The widget's own classes follow `.widget-name__block--variant`, where `widget-name` is renamed to the widget's name in `index.html`, `src/styles/base.scss` and the `selector-class-pattern` rule of `.stylelintrc`. Stylelint rejects any other class selector in the widget's styles; for the rest, use Dynamic's utilities.

From the template's README:

```scss
@use "@dynamic-framework/ui-react/src/style/abstracts/+import" as df;

.widget-name__summary {
  color: var(--bs-body-color);
  background-color: rgba(var(--bs-primary-rgb), .1);

  @include df.media-breakpoint-up(md) {
    padding: var(--bs-ref-spacer-4);
  }
}
```

### Theme zones: `data-bs-theme` in JSX

Dynamic UI has no global dark scheme switched by `prefers-color-scheme`. A part of the page uses another scheme through a **zone**: an element carrying `data-bs-theme`. The widget sets the attribute in JSX and never styles `[data-bs-theme]` itself:

```tsx
<div className="widget-name__summary rounded-2 fs-5" data-bs-theme="dark">
```

What a zone changes is defined by the site's theme.

### Declare a published theme

`widget.manifest.json` has a `theme` field: `null`, or `package@version` when the widget is designed for a theme published as a package. The template ships `"theme": null`.

---

## Typography

The font family is set in `--bs-font-sans-serif`; Dynamic UI derives `--bs-body-font-family` from it, and tooltips and popovers read `--bs-font-sans-serif`. A theme sets `--bs-font-sans-serif`, not only `--bs-body-font-family`. The widget does not set either: it uses the site's.

---

## Seeing the site's theme locally

`npm run dev` serves `index.html`, which links Dynamic UI's CSS from the CDN with an absolute URL, so components look right. Without the site's theme you see Dynamic's default tokens. To see the brand, add a `<link>` to the site's theme stylesheet **after** Dynamic's, also with an absolute URL (taken from the `<head>` of the published site):

```html
<link rel="stylesheet" href="https://cdn.dynamicframework.dev/assets/<version>/ui-react/css/dynamic-ui.min.css">
<link rel="stylesheet" href="https://my-company.modyo.cloud/stylesheets/site-theme.css">
```

Modyo never renders `index.html`: nothing in it reaches the published widget. The Dynamic UI link keeps the version the template pins; `tests/boundaries/dynamicCssLink.test.ts` checks that the URL is absolute and matches the installed version.

---

## Building a site theme

Site themes are generated and checked with the tools that Dynamic UI publishes in its package: `npx dynamic-theme-expand theme.json -o theme.css` and `npx dynamic-theme-validate theme.css --strict`.

---

## Common mistakes

| Wrong | Right |
|-------|-------|
| A `theme.scss` in the widget with `:root { --bs-primary-rgb: … }` | The brand goes in the site's theme |
| `@import "…"` | `@use` for the widget's own partials; Dynamic's CSS and the theme come from the site |
| `$brand: #336699` | `var(--bs-*)` |
| `font-family: …`, `border-radius: 8px` (with any value, `var(--bs-*)` included) | Inherit the site's font family; `rounded-*` for radii; `fs-*`, `fw-*`, or `font-size: var(--bs-body-font-size)` for size and weight |
| `.summary { … }` | `.widget-name__summary { … }` |
| `[data-bs-theme="dark"] .summary { … }` | `data-bs-theme="dark"` on the element in JSX |
| `@media (prefers-color-scheme: dark)` | A zone marked by `data-bs-theme` |
| Importing `dynamic-ui.css` in `main.tsx` | The site loads it |
