@loomhq/lens 12.17.1 → 12.18.0

package/README.md

@@ -74,25 +74,28 @@ pnpm --filter @loomhq/lens dev
 After running the last `pnpm --filter` in your terminal, a `localhost` address should appear. Follow it to your local lens development website.
 
 ## Contributing
+
 If you are looking to use an ADS (Atlassian Design System) component, [check out this section for implementation guidance](#add-an-icon-to-the-icon-set).
 
 If you add any new Lens components, please surface any urgent pull requests in [#loom-design-system-lens](https://atlassian.enterprise.slack.com/archives/CJ52CKB27).
 
 ### Adding a New Icon to Lens
+
 1. Within the `loom` repository, navigate to `projects/libraries/lens/src/components/icon/available-icons`
 2. Create a new file in the `available-icons` folder, and give it a literal name (e.g., bug icon → bug.tsx)
-    - > **If the icon you are trying to add already exists in ADS**, use the same name as what can be found in the [ADS icon explorer](https://atlassian.design/components/icon/icon-explorer)
+   - > **If the icon you are trying to add already exists in ADS**, use the same name as what can be found in the [ADS icon explorer](https://atlassian.design/components/icon/icon-explorer)
 3. After creating your new icon, go to `index.ts` (found at `/lens/src/components/icon/available-icons/index.ts`) and add an export statement for your new icon in there.
 4. When you're finished adding your icon into lens library, and run `pnpm build` → this command will automatically register your new icon to Lens and must be ran before you can view or test your new icon locally
 5. [Follow these steps to run Lens locally.](#running-lens-locally)
 6. Once you have finalized your changes and your code is ready for PR, you need to run `pnpm changeset` from the root directory
 7. After running `changeset`, you should be prompted with "what changeset do you need" within your terminal
 8. Select the files that you have changed, and press enter to proceed until you see a `patch bump` prompt. Make sure to select a severity that accurately reflects the scope of your changes.
-    - For example, a change that merely adds a new component or icon would be considered minor, but a change that adds a new component **and** removes support for another component/the previous version of that variant would be considered a **major** change.
+   - For example, a change that merely adds a new component or icon would be considered minor, but a change that adds a new component **and** removes support for another component/the previous version of that variant would be considered a **major** change.
 
 > **Note:** If there's no `changeset` file included in your PR, your changes won't be available to use in the rest of the repo until a changeset is merged. Think of it like merging without deploying.
 
 ### Adding a New Illustration to Lens
+
 Follow [this guide](https://hello.atlassian.net/wiki/spaces/~712020ed7894b2bdcb46ecacd40aff80a4be0e/pages/6562186947/Adding+a+new+ADS+Illustration+to+Lens) to add a new illustration to Lens. After running the prompt in the guide, verify the following:
 
 1. **File location and export** — Your illustration lives in `projects/libraries/lens/src/illustrations/` and is exported from the `index.tsx` file in that folder.
@@ -101,7 +104,7 @@ Follow [this guide](https://hello.atlassian.net/wiki/spaces/~712020ed7894b2bdcb4
 
 3. **Color definitions** — Illustration colors are defined in `projects/libraries/lens/src/colors.ts`. The theme-specific colors should have been added to the appropriate dark and light mode entries, and only static colors added to `illustrationColors`.
 
-*Note: For illustrations that aren't from ADS, reach out in [#loom-design-system-lens](https://atlassian.enterprise.slack.com/archives/CJ52CKB27) first.*
+_Note: For illustrations that aren't from ADS, reach out in [#loom-design-system-lens](https://atlassian.enterprise.slack.com/archives/CJ52CKB27) first._
 
 ### Use conventional commits
 
@@ -131,6 +134,39 @@ Add your new SVG to `misc/eslint/common.js` and `projects/libraries/lens/src/com
 
 To see if your icon is in a certain version, refer to [@atlaskit/icon changelog](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/src/master/platform/packages/design-system/icon/CHANGELOG.md) or the [@atlaskit/icon-lab changelog](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/src/master/platform/packages/design-system/icon-lab/CHANGELOG.md).
 
+## Forcing a Theme on a Specific Element
+
+To force a specific theme on an element and its children regardless of the page-level color mode, use `data-lens-theme`:
+
+```tsx
+{/* Always dark */}
+<div data-lens-theme="dark" />
+
+{/* Always light */}
+<div data-lens-theme="light" />
+```
+
+If any Lens tokens in the subtree reference ADS tokens (`--ds-*`) under the hood — which most do (see `colors.ts`) — three additional attributes are required so that `--ds-*` tokens are also correctly scoped:
+
+```tsx
+{/* Always dark, with ADS tokens */}
+<div data-lens-theme="dark" data-subtree-theme data-color-mode="dark" data-theme="light:dark dark:dark" />
+
+{/* Always light, with ADS tokens */}
+<div data-lens-theme="light" data-subtree-theme data-color-mode="light" data-theme="light:light dark:light" />
+```
+
+- **`data-subtree-theme`** — required by ADS (`@atlaskit/tokens`) to re-scope `--ds-*` tokens on the element
+- **`data-color-mode`** — causes `--lns-theme{Dark|Light}-color-*` vars to be re-evaluated in a scope where `--ds-*` tokens already have the correct value, rather than inheriting the page-level value from `:root`
+- **`data-theme`** — tells ADS which theme to apply per page color mode; format is `<pageColorMode>:<themeId>`, e.g. `"light:dark dark:dark"` means always use dark regardless of page mode
+
+Also ensure `setGlobalTheme` is called with `colorMode: 'auto'` once at app startup so both ADS stylesheets are loaded. If only one is loaded, `--ds-*` tokens will be undefined on forced-theme subtrees:
+
+```ts
+// Call once before React renders, e.g. in renderLoomPage.ts
+setGlobalTheme({ colorMode: 'auto', light: 'light', dark: 'dark' });
+```
+
 ## Documentation
 
 https://lens.loom.dev