<p align="center">
  <img src="https://gitlab.opencode.de/open-code/document-writing-tools/markdown-webbook/-/raw/v2/docs/assets/easyweb-logo.svg" alt="easyWebsite" width="380" />
</p>

<p align="center">
  A Kern UX based Next.js theme for creating documentation sites from Markdown.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@document-writing-tools/kernux-theme"><img src="https://img.shields.io/npm/v/@document-writing-tools/kernux-theme?style=for-the-badge" alt="npm version" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License" /></a>
</p>

<p align="center">
  <a href="https://easywebsite.opencode.de/">Documentation</a> ·
  <a href="https://www.npmjs.com/package/@document-writing-tools/kernux-theme">npm</a> ·
  <a href="https://gitlab.opencode.de/open-code/document-writing-tools/markdown-webbook">GitLab</a>
</p>

---


A Next.js documentation theme built on the [Kern UX](https://www.kern-ux.de/) design system, with a single, simple interface for customization.

---

## Usage

Import a theme CSS file as the **first import** in your global CSS file.

```css
/* src/styles/globals.css */
@import "@document-writing-tools/kernux-theme/src/styles.css";

/* Optional: scan MDX content for Tailwind classes */
@source "../**/*.{md,mdx}";

/* Optional: customize styles */
:root {
  --primary: #0057b8;
  --radius: 4px;
}
```

### Available themes

| Source import | Description |
|---|---|
| `src/opencode.css`  | openCode — rounded corners, Open Sans + Space Grotesk |
| `src/bund.css` | Bund — sharp corners, Bundes Sans |
| `src/opendesk.css` | openDesk — extends openCode with purple accent palette |
| `src/styles.css` | kernux — Fira Sans, no specialized theme overrides |

Use the **source imports** (`src/…`) when your project runs its own PostCSS / Tailwind pipeline.

---

## Configuration

Override CSS variables **after** the theme import. Only set the variables you want to change — everything else falls back to the theme's defaults.

```css
@import "@document-writing-tools/kernux-theme/src/opencode.css";

:root {
    /* ── Colors ─────────────────────────────────── */
    --primary:            #1544ff;   /* buttons, links, active states */
    --primary-foreground: #ffffff;   /* text on primary color */
    --background:         #ffffff;   /* page background */
    --foreground:         #131f30;   /* default text color */
    --muted:              #f8faff;   /* subtle backgrounds (sidebar, cards) */
    --muted-foreground:   #4d5b79;   /* secondary text */
    --border:             #d9dbdf;   /* borders and dividers */
    --accent:             #00E6CC;   /* highlight color */
    --accent-foreground:  #004039;   /* text on accent */
    --destructive:        #f34458;   /* errors, danger states */
    --success:            #64a183;
    --warning:            #eb702e;
    --info:               #618ce6;

    /* ── Optional surfaces ───────────────────────── */
    --input:              #ffffff;   /* input background (defaults to --background) */
    --sidebar-background: #e9edff;   /* defaults to --muted */
    --footer-background:  #f0f1f3;   /* defaults to --muted */
    --footer-foreground:  #131f30;   /* defaults to --foreground */

    /* ── Shape ───────────────────────────────────── */
    --radius:             16px;      /* largest border-radius; smaller steps scale down from this */

    /* ── Spacing ─────────────────────────────────── */
    --spacing-base:       4px;       /* base unit; all spacing tokens are multiples of this */

    /* ── Typography ──────────────────────────────── */
    --font-family:        "Open Sans", sans-serif;
    --font-size-ratio:    1.13;      /* modular type scale ratio */
    --font-weight-heading: 700;
}

/* Dark mode */
[data-kern-theme="dark"] {
    --primary:            #88a0ff;
    --primary-foreground: #001154;
    --background:         #001154;
    --foreground:         #f0f1f3;
    --muted:              #0a1d75;
    --muted-foreground:   #b6bcc8;
    --border:             #364668;
    --input:              #ffffff;
}
```

### Tailwind utilities

All user-facing variables are available as Tailwind utilities:

```html
<div class="bg-primary text-primary-foreground rounded-lg p-md">...</div>
<div class="bg-muted text-muted-foreground border-border">...</div>
<div class="bg-info text-info bg-info-background">...</div>
```

Border-radius scale (all derived from `--radius`):

| Class | Maps to | Example at `--radius: 16px` |
|---|---|---|
| `rounded` | default | 4px |
| `rounded-sm` | small | 8px |
| `rounded-md` | medium | 12px |
| `rounded-lg` | large | 16px (`--radius`) |
| `rounded-full` | — | 100% |

Spacing scale (all derived from `--spacing-base`):

| Class | Multiplier | Example at `--spacing-base: 4px` |
|---|---|---|
| `p-xxs` | ×1 | 4px |
| `p-xs` | ×2 | 8px |
| `p-sm` | ×3 | 12px |
| `p-md` | ×4 | 16px |
| `p-lg` | ×6 | 24px |
| `p-xl` | ×8 | 32px |

---

## How it works — the bridge system

The theme uses a two-layer architecture. You never need to touch the bridge layer.

```mermaid
flowchart TD
    subgraph USER["Your CSS file"]
        U1["--primary: #1544ff
        --background: #fff
        --radius: 16px
        --spacing-base: 4px
        --font-family: 'Open Sans'
        ..."]
    end

    subgraph BRIDGE["theme-bridge.css (internal — do not edit)"]
        direction TB
        BD["Defaults
        ──────────────────
        --primary: #1A3DA5
        --background: #ffffff
        --radius: var(--kern-8)
        --spacing-base: var(--kern-4)
        --font-family: Fira Sans
        ..."]

        BM["Mappings
        ──────────────────────────────────────────
        --kern-color-action-default:     var(--primary)
        --kern-color-layout-background:  var(--background)
        --kern-metric-border-radius-lg:  var(--radius)
        --kern-metric-space-default:     calc(--spacing-base × 4)
        --kern-typography-font-family:   var(--font-family)
        ..."]
    end

    subgraph OUT["Consumers"]
        K["Kern UX components
        ─────────────────
        .kern-btn
        .kern-alert
        .kern-card
        ...
        use --kern-* variables"]

        T["Tailwind utilities
        ─────────────────
        bg-primary
        text-foreground
        rounded-lg
        p-md
        ...
        use --primary, --background etc."]
    end

    USER -->|"cascade: your values override defaults"| BRIDGE
    BD -->|"used when you don't override"| BM
    BM --> K
    BM --> T
```

**Key rules:**
- Only set variables from the **user-facing interface** (top layer)
- Never reference `--kern-*` variables directly in your CSS — they are internal
- The bridge is the **only** file that maps user vars → kern vars

---

## License

This project is licensed under the MIT License.

Originally derived from [nextra-theme-docs](https://github.com/shuding/nextra/tree/main/packages/nextra-theme-docs) by [Shu Ding](https://github.com/shuding) — MIT licensed, Copyright (c) 2020.

