`: prose and editor read the same rules, so a page looks the same in both β the demo's βEdit Β· Readβ switch proves it to the pixel. The full recipe with slash menu, bubble toolbar and a Notion-style οΌ / β Ώ block handle with drag & drop is [`docs-editor.js`](docs-editor.js) β about 300 lines of plain JavaScript that only put NotionKit classes on their DOM. See it running in the [docs](https://notionkit.jungherz.com/docs.html#editor) and the [demo](https://notionkit.jungherz.com/app.html).
---
## 𧩠Web Components / Shadow DOM
### The problem
A shadow root that adopts the *whole* stylesheet also adopts the `:root` / `[data-theme]` token blocks. Inside that root the selectors match the element's own theme wrapper, every token is re-declared locally β and a matching rule always beats an inherited value. A consumer's own `:root { --nk-accent: β¦ }` never arrives.
### The solution: `notionkit-styles.js`
The build splits the stylesheet at the two token blocks and ships both halves as constructable stylesheets:
```js
import { componentsSheet, tokensCss } from '@jungherz-de/notionkit/notionkit-styles.js';
// Tokens once, on the document, inside a layer β a brand stylesheet wins regardless of load order.
const tokens = new CSSStyleSheet();
tokens.replaceSync(`@layer notionkit-defaults { ${tokensCss} }`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, tokens];
class NkCallout extends HTMLElement {
constructor() {
super();
const root = this.attachShadow({ mode: 'open' });
root.adoptedStyleSheets = [componentsSheet]; // components only
root.innerHTML = `
`;
}
}
customElements.define('nk-callout', NkCallout);
```
### Exports
| Export | Content |
|---|---|
| `css` / `nkSheet` | The whole stylesheet |
| `tokensCss` / `tokensSheet` | Only the `:root` and `[data-theme="dark"]` blocks |
| `componentsCss` / `componentsSheet` | Everything else |
### `::slotted()` twins
Content passed in from outside stays in the light DOM, so `.nk-callout .c-icon` cannot reach it. Every such rule has a twin next to it β `.nk-callout ::slotted(.c-icon)` β 92 in total, including a `[slot="β¦"]` twin for every part NotionKit Elements exposes as a named slot. Two limits: `::slotted()` matches only the assigned node (pass icons directly, never wrapped), and for slotted content the outer document's rules win.
A working proof of concept ships as [`elements-poc.html`](elements-poc.html) / [`nk-callout.js`](nk-callout.js): it measures live that class and element render identically, re-theme together and take the page's branding.
---
## π Project Structure
```
notionkit/
βββ notionkit.css # Source of truth: token block + component block
βββ notionkit.min.css # Generated by npm run build (gitignored)
βββ notionkit.min.css.map # Its source map, published with it (gitignored)
βββ notionkit-styles.js # Generated: constructable stylesheet + split exports (gitignored)
βββ build-styles-js.mjs # Build + split verification
βββ theme-override.css # Theme template: 3 palettes, high-contrast block
βββ SKILL.md # AI/LLM reference, generated from the same sources as the docs
βββ index.html # Landing page (de/index.html)
βββ app.html # Demo app with live editor (de/app.html)
βββ showcase.html # Every component, isolated (de/showcase.html)
βββ docs.html # Documentation (de/docs.html)
βββ docs-editor.js # TipTap recipe used by docs and demo
βββ covers/ # Cover pictures of the demo's start view
βββ elements-poc.html # Web-components proof of concept
βββ nk-callout.js # β¦ its two elements
βββ tools/ # Page/SKILL generators, catalog, contrast helper
βββ test/ # Playwright regression tests for the stylesheet
βββ .github/workflows/ # verify-build Β· release Β· pages
```
### Local development
```bash
npm install
npm run build # minify, split, pages, SKILL.md
npm run check:coverage # every class documented?
npm test # regression tests (once: npx playwright install chromium)
npx http-server -p 8080 -c-1
```
Serve the folder rather than opening files directly: the elements proof of concept imports an ES module, which browsers block on `file://`. The `-c-1` flag disables caching β without it the demo iframes on the landing page may show a stale `app.html` for an hour.
---
## π Documentation
- **[Landing page](https://notionkit.jungherz.com)** β the library as a full-surface app preview, desktop and mobile side by side
- **[Documentation](https://notionkit.jungherz.com/docs.html)** β every component with live preview, markup, classes, mobile behaviour; tokens, states, contrast, editor and web-component integration
- **[Showcase](https://notionkit.jungherz.com/showcase.html)** β every component isolated, both themes
- **[Demo](https://notionkit.jungherz.com/app.html)** β a realistic workspace app with a live TipTap editor
- German versions under [`/de/`](https://notionkit.jungherz.com/de/)
---
## 𧩠The NotionKit Family
NotionKit is the CSS foundation of a three-layer family. The layers share one design language and one naming stem: `.nk-callout` becomes `
`, a modifier class becomes an attribute, a state class becomes a boolean attribute.
### NotionKit Elements β the app layer
If you want to use NotionKit through **drop-in web components** instead of writing the class markup yourself, take a look at **NotionKit Elements**: 88 vanilla-JS custom elements (``, ``, ``, ``, ``, ``, `` β¦) with Shadow DOM, native form participation and pixel parity with the class markup β built on the constructable stylesheet shipped here. The [proof of concept](elements-poc.html) in this repository is its seed.
Useful links:
- GitHub: https://github.com/JUNGHERZ/NotionKit-Elements
- Live demo: https://notionkit-elements.jungherz.com/
- Docs: https://notionkit-elements.jungherz.com/docs.html
- npm: [`@jungherz-de/notionkit-elements`](https://www.npmjs.com/package/@jungherz-de/notionkit-elements)
### NotionKit Web β the website layer
If you want to build a **complete website** rather than assemble components yourself, **NotionKit Web** is the intended path: the official Astro template β docs from Markdown with page tree, bilingual blog with RSS, marketing sections, dark mode without a flash, no external requests, a Playwright smoke suite β on the NotionKit foundation.
Useful links:
- GitHub: https://github.com/JUNGHERZ/NotionKit-Web
- Website: https://notionkit-web.jungherz.com/
- Docs: https://notionkit-web.jungherz.com/docs.html
---
## π€ AI / LLM Reference (`SKILL.md`)
[`SKILL.md`](SKILL.md) is a structured reference for coding agents and AI assistants, generated from the same catalog as the documentation so it cannot drift:
- copy-paste markup for every component with nesting rules and classes
- complete token tables for both themes, read straight from the stylesheet
- the state-class contract
- **eight complete app skeletons** β workspace app, database app, settings modal, AI chat page, form/onboarding page, landing/docs page, home page, sign-in page β each with a "When to use this skeleton?" block
- editor recipes, rules and common mistakes, the web-component contract, the CSS-to-Elements mapping
Point your assistant at it: *"Use NotionKit classes as documented in SKILL.md."* It has been validated blind β an agent given nothing but the file produced a working app whose 61 classes all existed.
---
## π Browser Compatibility
| Browser | Version |
|---|---|
| Chrome / Edge | 111+ |
| Safari | 16.4+ |
| Firefox | 113+ |
The floor is set by `color-mix()` and constructable stylesheets. `:where()`, `inset`, `min()`, `accent-color` and `color-scheme` are older. Emoji are rendered by the operating system's emoji font; NotionKit ships no icon set and no web font β nothing to license.
---
## π States & Modifiers β Cheat Sheet
| Class / attribute | Applies to | Effect |
|---|---|---|
| `hidden` (attribute) | every nk- element and slotted node | Hidden, always β even where a component sets its own `display` |
| `.active` | `nk-tree-item`, `nk-db-tab`, `nk-tab`, `nk-settings-pane`, `nk-segmented button`, `nk-board` | Where the user is |
| `.open` | `nk-modal-backdrop`, `nk-cmdk-backdrop`, `nk-sheet-backdrop`, `nk-dialog-backdrop`, `nk-peek-backdrop`, `nk-pop.floating`, `nk-tooltip`, `nk-sidebar` (phones), `nk-toggle-arrow` | Overlay visible, peek in, menu or tooltip shown, drawer in / arrow rotated |
| `.floating` `.sheet` | `nk-pop` | Fades in with `.open`; a bottom sheet below 860px |
| `.collapsed` | `nk-tree-children`, `nk-sidebar`, `nk-sidebar-toggle` | Subtree folded; sidebar slid out on the desktop, its β° shown |
| `.peek-inset` | `nk-app` | The page moves aside for the open side peek |
| `.selected` | `nk-cmdk-item`, `nk-model-card`, `nk-slash-item`, `nk-calendar .cal-day` | Transient highlight or chosen option β on a calendar the chosen day |
| `.start` `.end` `.in-range` | `nk-calendar .cal-day` | A range: its ends in the accent, the days between tinted |
| `.today` `.off` `.out` | `nk-calendar .cal-day`, `nk-calendar-view .cv-day` | Today in red; a day not worked or of another month greyed |
| `.weeks` | `nk-calendar`, `nk-calendar-view` | ISO calendar weeks in front of the days |
| `.show` | `nk-toast` | Toast slides in |
| `aria-checked="true"` | `nk-switch` (button form) | Switch on |
| `.full` `.small` | `nk-page` | Page options: full width, small text |
| `.primary` `.secondary` `.danger` `.danger-solid` `.small` | `nk-btn` | Button variants |
| `.gray` `.brown` `.orange` `.yellow` `.green` `.blue` `.purple` `.pink` `.red` | `nk-tag`, `nk-avatar` | Notion's nine colours; a tag without one is gray, an avatar the gradient |
| `.small` `.large` `.xlarge` `.square` | `nk-avatar` | 20 / 32 / 56px instead of 24px; workspace-icon corners |
| `.info` `.success` `.warning` `.danger` | `nk-banner` | Banner tones |
NotionKit ships states, not behaviour: toggle these yourself. The demo pages contain reference implementations in plain JavaScript.
---
## π€ Contributing
Issues and pull requests are welcome.
### Guidelines
- Keep the two-block structure: no `--nk-*` declaration outside the token blocks (the build fails otherwise).
- No hex literals in component rules β derive from a token with `color-mix()`.
- Every rule that styles slottable content gets a `::slotted()` twin.
- Add new components to `tools/catalog.mjs`; docs, showcase and `SKILL.md` are generated from it, and `npm run check:coverage` insists every class is documented.
- Code and comments in English; the pages exist in English and German.
### Releasing
A plain push to `main` updates the website (Verify Build + Deploy Pages) and touches nothing on npm. A release is a tag:
```bash
# 1. write the CHANGELOG entry ## [1.1.0] β YYYY-MM-DD (the release workflow refuses to publish without it)
# 2. bump β this also updates the version header in notionkit.css, commits and tags
npm version minor # or patch / major
# 3. push branch and tag
git push && git push --tags
```
The tag triggers `release.yml`: it checks that tag, `package.json` and `CHANGELOG.md` agree, builds, creates the GitHub release with the artefacts and publishes to npm through trusted publishing (OIDC, provenance, no token).
---
## π License
[MIT](LICENSE) Β© 2026 [Jungherz GmbH](https://www.jungherz.com)
---
## π Changelog
See [CHANGELOG.md](CHANGELOG.md).
---
## π’ Credits
Built by [Jungherz GmbH](https://www.jungherz.com). NotionKit is not affiliated with or endorsed by Notion Labs, Inc.; it is an independent design system in a familiar idiom.
